Upgrading 3DSwym

Data located in the shared folder and databases should not be deleted.

Within a given release, when upgrading from a previous version (whether it is a GA or update (FP) level) to the current update (FP) level, the same procedure must be run again on both Windows and Linux.

• If migrating from a R2016x MySQL 3DSwym to a R2019x Oracle 3DSwym, all the target databases must be different from the ones used in the previous 3DSwym installation.
• If migrating from a R2016x Oracle 3DSwym to a R2019x Oracle 3DSwym, only the 3DSwym Content database must be different from the ones used in the previous 3DSwym installation.

1. Specify the parameters of the previous database.
2. Specify the previous shared data directory.

Do not create any content before and during migration, this could lead to data inconsistency or data loss.

• copy MySQL JDBC driver JAR into the TomEE+ lib path
• Warning: These steps must be run only once. Do not run it on the next FP. Running it again after creating some data could lead to data inconsistency or data loss
• Modify the file <installPath>/<os>/resources/migration/media_migration.properties by replacing the following key values:

  Key	Description	Example
  src.userid	R2016x 3DSwym MySQL database user name	x3ds
  src.passwd	R2016x 3DSwym MySQL database user password
  src.url	R2016x 3DSwym Media MySQL database JDBC URL	jdbc:mysql://localhost:3306/x3dswym_media
  dst.userid	R2019x 3DSwym Media Oracle database user name (prefilled)	X3DSWYM_MEDIA
  dst.passwd	R2019x 3DSwym Media Oracle database user password
  dst.url	R2019x 3DSwym Media Oracle database JDBC URL (prefilled)	jdbc:oracle:thin:@//localhost:1521/DBMEDIA
  dst.tns_admin	Oracle tnsnames.ora directory (prefilled, optional)

• Run the 3DSwym Media database migration command: <installPath>/<os>/code/command/migrateMediaFromR2016x.(sh|.bat) -cp <path/to/MySQL_JDBC_driver.jar> where <path/to/MySQL_JDBC_driver.jar> is the path to the MySQL JDBC driver JAR file. This will transfer the R2016x 3DSwym Media MySQL database content to the R2019x 3DSwym Media Oracle database. You can follow the migration progression in the console.
• After this step has succeeded, you can remove the plain text passwords from the <installPath>/<os>/resources/migration/media_migration.properties file.

1. Add the following lines:
   • If you migrate from MySQL:

     batch.migration.enable=true
     batch.migration.db.driver=com.mysql.jdbc.Driver
     batch.migration.db.url=jdbc:mysql://<host>:<port>/<schema>?zeroDateTimeBehavior=convertToNull
     batch.migration.db.username=<dbusername>
     batch.migration.db.password=<dbpassword>
     batch.migration.media.file.operation=copy

   • If you migrate from Oracle:

     batch.migration.enable=true
     batch.migration.db.driver=oracle.jdbc.OracleDriver
     batch.migration.db.url=jdbc:oracle:thin:@//<host>:<port>/<service_name>
     #Or if using tnsnames.ora: jdbc:oracle:thin:@<service_name>
     batch.migration.db.username=<dbusername>
     batch.migration.db.password=<dbpassword>
     batch.migration.media.file.operation=copy

2. Replace the following by the values used for the R2016x FP.1621 (or higher) 3DSwym Content Database to be migrated:

   Value	Description
   <host>	database host
   <port>	port of the database
   <schema>	database schema for 3DSwym content
   <service_name>	service name
   <dbusername>	database user name
   <dbuserpassword>	database user password

On Linux, or on Windows when not running TomEE+ as a Windows service:

Examples of command line options to be added in setenv.sh|.bat:

-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=<jmxPort> -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false

where <jmxPort> is an available port.

On Windows, when running TomEE+ as a Windows service:

1. Make a copy of the <installPath>\<os>\code\command\VENApacheTomEE_createService.bat file and modify this copy by adding the following line (where <jmxPort> is an available port):

   set JAVA_OPTIONS_PARAM=%JAVA_OPTIONS_PARAM%;-Dcom.sun.management.jmxremote;-Dcom.sun.management.jmxremote.port=<jmxPort>;-Dcom.sun.management.jmxremote.local.only=false;-Dcom.sun.management.jmxremote.authenticate=false;-Dcom.sun.management.jmxremote.ssl=false

   after:

   rem ++JvmOptions
   set JAVA_OPTIONS_PARAM=-Dfile.encoding=UTF-8
   

2. Run this copy in order to unregister and register again the Windows service with JMX enablement parameters.

• reverse proxy and load balancer
• 3DPassport
• the single TomEE+ instance for 3DSwym Content, Widget Platform and Rich Media Server, with JMX enabled.
• the <sharedDirectory> shared directory (must be read/write accessible to the TomEE process)

<installPath>/<os>/code/command/migrateFromR2016x.(sh|.bat) -jmxPort <jmxPort> -cleanSharedFolder

where <jmxPort> is the TomEE+ JMX port.

This will copy data from the R2016x 3DSwym Content database to the R2019x 3DSwym Content database, and also reorganize the media file structure located under the shared folder. This reorganization duplicates certain files, but it is possible to clean up duplicated files and save disk space by specifying the -cleanSharedFolder parameter.

You can follow the migration progression in the console.

1. Delete the properties file, because it stores the passwords in plain text.
2. Delete the MySQL driver JAR file.

This is particularly important now that 3DSwym Index is installed on top of Exalead CloudView.

• On Windows: Run the command <3DSwymInstallPath>\win_b64\code\command\clearExaleadIndex.bat
• On Linux: Run the command <3DSwymInstallPath>/linux_a64/code/command/clearExaleadIndex.sh

Data located in the shared folder and databases should not be deleted.

This is particularly important now that 3DSwym Index is installed on top of Exalead CloudView.