Note: Documentation for Pivotal GemFire 7.0.x is now available at http://gemfire.docs.pivotal.io/7.0.2/index.html. Please refer to the Pivotal site for the latest and most up-to-date documentation on GemFire 7.0.x. The vFabric GemFire 7.0 documentation site will no longer be updated.

Deploying Application JARs to vFabric GemFire Members

You can dynamically deploy your application JAR files to specific members or to all members in your distributed system. GemFire automatically keeps track of JAR file versions; autoloads the deployed JAR files to the CLASSPATH; and auto-registers any functions that the JAR contains.

To deploy and undeploy application JAR files in vFabric GemFire, use the gfsh deploy or undeploy command. You can deploy a single JAR or multiple JARs (by either specifying the JAR filenames or by specifying a directory that contains the JAR files), and you can also target the deployment to a member group or multiple member group. For example, after connecting to the distributed system where you want to deploy the JARs, you could type at the gfsh prompt :
gfsh> deploy --jar=group1_functions.jar
This command deploys the group1_functions.jar file to all members in the distributed system.
To deploy the JAR file to a subset of members, use the --group argument. For example:
gfsh> deploy --jar=group1_functions.jar --group=MemberGroup1
In the example it is assumed that you have already defined the member group that you want to use when starting up your members. See Using Member Groups for more information on how to define member groups and add a member to a group.
To deploy all the JAR files that are located in a specific directory to all members:
gfsh> deploy --dir=libs/group1-libs
You can either provide a JAR file name or a directory of JARs for deployment, but you cannot specify both at once.
To undeploy all previously deployed JAR files throughout the distributed system:
gfsh> undeploy
To undeploy a specific JAR file:
gfsh> undeploy --jar=group1_functions.jar
To target a specific member group when all JAR files:
gfsh> undeploy --group=MemberGroup1
Only JAR files that have been previously deployed on members in the MemberGroup1 group will be undeployed.
To see a list of all deployed JARs in your distributed system:
gfsh> list deployed
To see a list of all deployed JARs in a specific member group:
gfsh> list deployed --group=MemberGroup1
Sample output:
 
Member   |     Deployed JAR     |                JAR Location            
--------- | -------------------- | ---------------------------------------------------
datanode1 | group1_functions.jar | /usr/local/gemfire/deploy/vf.gf#group1_functions.jar#1
datanode2 | group1_functions.jar | /usr/local/gemfire/deploy/vf.gf#group1_functions.jar#1

For more information on gfsh usage, see Using the GemFire SHell (gfsh).

Deployment Location for JAR Files

The system location where JAR files are written on each member is determined by the deploy-working-dir GemFire property configured for that member. For example, you could have the following configured in the gemfire.properties file for your member:
#gemfire.properties
deploy-working-dir=/usr/local/gemfire/deploy
This deployment location can be local or a shared network resource (such as a mount location) used by multiple members in order to reduce disk space usage. If you use a shared directory, you still need to deploy the JAR file on every member that you want to have access to the application, because deployment updates the CLASSPATH and auto-register functions.

Versioning of JAR Files

When you deploy JAR files to a distributed system or member group, the JAR file is modified to indicate version information in its name. Each JAR filename is prefixed with vf.gf# and contains a version number at the end of the filename. For example, if you deploy MyClasses.jar five times, the filename is displayed as vf.gf#MyClasses.jar#5 when you list all deployed jars.

When you deploy a new JAR file, the member receiving the deployment checks whether the JAR file is a duplicate, either because the JAR file has already been deployed on that member or because the JAR file has already been deployed to a shared deployment working directory that other members are also using. If another member has already deployed this JAR file to the shared directory (determined by doing a byte-for-byte compare to the latest version in its directory), the member receiving the latest deployment does not write the file to disk. Instead, the member updates the ClassPathLoader to use the already deployed JAR file. If a newer version of the JAR file is detected on disk and is already in use, the deployment is canceled.

When a member begins using a JAR file, the member obtains a shared lock on the file. If the member receives a newer version by deployment, the member releases the shared lock and tries to delete the existing JAR file in favor of the newer version. If no other member has a shared lock on the existing JAR, the existing, older version JAR is deleted.

Automatic Class Path Loading

When a cache is started, the new cache requests that the latest versions of each JAR file in the current working directory be added to the ClassPathLoader. If a JAR file has already been deployed to the ClassPathLoader, the ClassPathLoader updates its loaded version if a newer version is found; otherwise, there is no change. If detected, older versions of the JAR files are deleted if no other member has a shared lock on them.

Undeploying a JAR file does not automatically unload the classes that were loaded during deployment. You need to restart your members to unload those classes.

When a cache is closed it requests that all currently deployed JAR files be removed from the ClassPathLoader.

If you are using a shared deployment working directory, all members sharing the directory should belong to the same member group. Upon restart, all members that share the same deployment working directory will deploy and autoload their CLASSPATH with any JARs found in the current working directory. This means that some members may load the JARs even though they are not part of the member group that received the original deployment.

Automatic Function Registration

When you deploy a JAR file that contains a function (in other words, contains a class that implements the Function interface), the function is automatically registered through the FunctionService.registerFunction method. If another JAR file is deployed (either with the same JAR filename or another filename) with the same function, the new implementation of the function is registered, overwriting the old one. If a JAR file is undeployed, any functions that were auto-registered at the time of deployment are unregistered. Because deploying a JAR file that has the same name multiple times results in the JAR being un-deployed and re-deployed, functions in the JAR are unregistered and re-registered each time this occurs. If a function with the same ID is registered from multiple differently named JAR files, the function is unregistered if any of those JAR files are re-deployed or un-deployed.

During cache.xml load, the parameters for any declarables are saved. If functions found in a JAR file are also declarable, and have the same class name as the declarables whose parameters were saved after loading cache.xml, then function instances are created using those Parameters and are also registered. Therefore, if the same function is declared multiple times in the cache.xml with different sets of parameters, when the JAR is deployed a function is instantiated for each set of parameters. If any functions are registered using parameters from a cache.xml load, the default, no-argument function is not registered.