Skip navigation
Toggle Sidebar

Project Documentation

Description

This utility enables clients of old version to automatically work with space of newer version without needing to install the new version's libraries on the client. This facilitates easy upgrade for multi-client environments.

Synchronizing the clients by using the synchronization utility requires restarting the client's VM. This is valid for clients running as standalone applications as well as for client running on application servers.

Installation Instructions

  1. Download the GigaSpaces Client Version Synchronization Utility zip file from the download page.
  2. Extract the zip file in any directory on the client machine.
    The extraction directory will contain the following files:
    gs-sync.jar - the synchronization implementation classes.
    gs-sync.bat - a batch file to invoke the update as a standalone application (WIN).
    gs-sync.sh - a shell command file to invoke the update as a standalone application (UNIX).
    gs-sync.properties - synchronization instructions file.
    readme.txt - contains instructions on how to use the synchronization utility.

Usage Instructions

Specifying Synchronization Instructions

The synchronization utility expects to receive synchronization instructions as input. Those instructions can be passed to the utility in two methods:

  1. Using a properties file
  2. Direct argument

1. Using a properties file

In this method one specifies the synchronization instructions in a properties file and passes the location of this file to the utility as an argument.

Each line in the properties file represent a synchronization instruction that specifies a jar file needed to be updated. Each key specifies the URI where the jar file can be found using HTTP. Each value specifies a list of destination directories where the jar file should be deployed.

An example for the properties file format is as follows:

http://192.168.1.3:9813/JSpaces.jar = D:/dev/test1,D:/dev/test2
http://192.168.1.3:9813/jsk-platform.jar = D:/dev/test1
#the following line in commented
#http://192.168.1.3:9813/jsk-lib.jar = D:/dev/test1,D:/dev/test2
#the following line in commented too
!http://192.168.1.3:9813/ServiceGrid/gs-boot.jar = D:/dev/test1,D:/dev/test2

Lines can be commented by putting # or ! at the beginning of the line.

The code above does the following:

  1. Downloads JSpaces.jar and put it in D:/dev/test1 and in D:/dev/test2.
  2. Downloads jsk-platform.jar and put it in D:/dev/test1.

2. Direct argument

In this method one specifies the synchronization instructions in a single string and passes it to the utility as an argument to the -javaagent VM property.

The string is a list of synchronization instructions separated by a semicolon ';'. Each synchronization instruction specifies a jar file needed to be updated. Each instruction has two parts separated by the equal sign '='. The left side of the equal sign is the URI where the jar file can be found using HTTP. The right side of the equal sign is a list of destination directories where the jar file should be deployed.

An example for the argument format is as follows:

-javaagent:../gs-sync.jar=http://192.168.1.3:9813/JSpaces.jar=D:/dev/test1,D:/dev/test2;http://192.168.1.3:9813/jsk-platform.jar=D:/dev/test1

There is no way to comment sources here.

The code above does the following:

  1. Downloads JSpaces.jar and put it in D:/dev/test1 and in D:/dev/test2.
  2. Downloads jsk-platform.jar and put it in D:/dev/test1.

Running the synchronization utility as a Java agent (JDK 1.5+)

JDK 1.5 introduced the instrumentation API, which gives the ability to run Java agents as soon as the JVM initializes, right before the application's main method is invoked.
It is possible to run the synchronization utility as a Java agent. As a result, each time the VM starts, the Java agent will replace the old JAR files with the new JAR files before the application starts.

To do so one needs to add the following VM argument in the command line that runs the Java process:

-javaagent:<path>/gs-sync.jar=<option>

The parts margined by <> need to be specified.
path - the path to the gs-sync.jar file
option - a string containing the synchronization instructions, or a location to a properties file that contains those instructions.

When running the synchronization utility as a Java agent, the GigaSpaces JAR files that are specified in the application's classpath and being downloaded by the synchronization utility will be added again to the classpath. This is done due to the VM's nature not to recognize replaced JAR files after the VM's initialization.
The added path will be of the same JAR file, only with a small change.
For example:
If the classpath contains ../bin/JSpaces.jar, the following path will be added ../bin/./JSpaces.jar.

Running the synchronization utility as a standalone application

It is possible to run the synchronization utility as a standalone application. Each time a synchronization is required one can run the application on the client's machine and the JAR files will be replaced.

Running the synchronization utility using batch/shell files

Windows

  1. Edit the file gs-sync.bat.
  2. Set the value of SYNC_ARGUMENT to contain one of the following:
    • The location of a properties file that contains the synchronization instructions (the default is gs-sync.properties).
    • A string containing the synchronization instructions.
  3. Run the file gs-sync.bat to perform the synchronization.

UNIX

  1. Edit the file gs-sync.sh.
  2. Set the value of SYNC_ARGUMENT to contain one of the following:
    • The location of a properties file that contains the synchronization instructions (the default is gs-sync.properties).
    • A string containing the synchronization instructions.
  3. Run the file gs-sync.sh to perform the synchronization.

Running the synchronization utility from the command line

To run the synchronization utility directly from the command line do the following:

java.exe -jar gs-sync.jar <option>

Set the value of <option> to contain one of the following:

  • The location of a properties file that contains the synchronization instructions.
  • A string containing the synchronization instructions.

Examples

WebSphere 6.1

This example shows how to synchronize the GigaSpaces JAR files in the ReplicatedSessionBean example deployment in WebSphere 6.1.

To set the agent to run when WebSpahere 6.1 starts:

  1. Edit the file: <WS_HOME>\profiles\AppSrv01\config\cells\hostNode01Cell\nodes\hostNode01\servers\server1\server.xml
  2. Put the agent argument in: genericJvmArguments as follows:
genericJvmArguments="-javaagent:D:\CSU\gs-sync.jar=D:\CSU\ws-gs-sync.properties"

ws-gs-sync.properties content:

http://192.168.1.3:9813/JSpaces.jar = D:\WebSphere611\profiles\AppSrv01\installedApps\sw-ltNode02Cell\Replicated Session.ear\lib
http://192.168.1.3:9813/jsk-platform.jar = D:\WebSphere611\profiles\AppSrv01\installedApps\sw-ltNode02Cell\Replicated Session.ear\lib\jini
http://192.168.1.3:9813/jsk-lib.jar = D:\WebSphere611\profiles\AppSrv01\installedApps\sw-ltNode02Cell\Replicated Session.ear\lib\jini
http://192.168.1.3:9813/ServiceGrid/gs-boot.jar = D:\WebSphere611\profiles\AppSrv01\installedApps\sw-ltNode02Cell\Replicated Session.ear\lib\ServiceGrid

WebLogic 10

This example shows how to synchronize the GigaSpaces JAR files in the ReplicatedSessionBean example deployment in WebLogic 10.

To set the agent to run when WebLogic 10 starts:

  1. Edit the file: <WL_HOME>\wlserver_10.0\samples\domains\wl_server\bin\startWebLogic.cmd
  2. Add the agent argument to the command line as follows:
# set the Java agent variable
set GS_AGENT=-javaagent:D:\CSU\gs-sync.jar=D:\CSU\wl-gs-sync.properties
# put the variable in the command line
%JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %GS_AGENT% %JAVA_OPTIONS% .....

wl-gs-sync.properties content:

http://192.168.1.3:9813/JSpaces.jar = D:\bea\wlserver_10.0\samples\domains\wl_server\servers\examplesServer\tmp\_WL_user\ReplicatedSessionBean\s7gk48\lib
http://192.168.1.3:9813/jsk-platform.jar = D:\bea\wlserver_10.0\samples\domains\wl_server\servers\examplesServer\tmp\_WL_user\ReplicatedSessionBean\s7gk48\lib\jini
http://192.168.1.3:9813/jsk-lib.jar = D:\bea\wlserver_10.0\samples\domains\wl_server\servers\examplesServer\tmp\_WL_user\ReplicatedSessionBean\s7gk48\lib\jini
http://192.168.1.3:9813/ServiceGrid/gs-boot.jar = D:\bea\wlserver_10.0\samples\domains\wl_server\servers\examplesServer\tmp\_WL_user\ReplicatedSessionBean\s7gk48\lib\ServiceGrid

Tomcat

This example shows how to synchronize the GigaSpaces JAR files in a common servlet deployment in Tomcat 6.0.14.

To set the agent to run when Tomcat 6.0.14 starts:

  1. Edit the file: <TOMCAT_HOME>\bin\catalina.bat
  2. Add the agent argument to the command line as follows:
# set the Java agent variable
set GS_AGENT=-javaagent:D:\CSU\gs-sync.jar=D:\CSU\tc-gs-sync.properties
# put the variable in the command line
%_EXECJAVA% %GS_AGENT% %JAVA_OPTS% ....

tc-gs-sync.properties content:

http://192.168.1.3:9813/JSpaces.jar = D:/apache-tomcat-6.0.14/webapps/mywar/WEB-INF/lib
http://192.168.1.3:9813/jsk-platform.jar = D:/apache-tomcat-6.0.14/webapps/mywar/WEB-INF/lib/jini
http://192.168.1.3:9813/jsk-lib.jar = D:/apache-tomcat-6.0.14/webapps/mywar/WEB-INF/lib/jini
http://192.168.1.3:9813/ServiceGrid/gs-boot.jar = D:/apache-tomcat-6.0.14/webapps/mywar/WEB-INF/lib/ServiceGrid

Synchronization Logs
Adaptavist Theme Builder Powered by Atlassian Confluence