This topic explains how to deploy application JAR files to VMware Tanzu GemFire cluster members.
You can dynamically deploy your application JAR files to specific members or to all members in your cluster. Tanzu GemFire automatically keeps track of JAR file versions, auto-loads the deployed JAR files to the class loader, and auto-registers any functions that the JAR contains.
To deploy and undeploy application JAR files in VMware Tanzu GemFire, use the gfsh deploy or undeploy command.
Note: When deploying a JAR, the name of the JAR cannot contain any of the following characters: *, !, #, @, ?.
You can deploy a single JAR or multiple JARs (by specifying either the JAR filenames or 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 cluster where you want to deploy the JAR files, you could type at the gfsh prompt:
gfsh> deploy --jars=group1_functions.jar
This command deploys the group1_functions.jar file to all members in the cluster.
To deploy the JAR file to a subset of members, use the --groups argument. For example:
gfsh> deploy --jars=group1_functions.jar --groups=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 Configuring and Running a Cluster for more information about defining member groups and adding 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 cluster:
gfsh> undeploy
To undeploy a specific JAR file:
gfsh> undeploy --jars=group1_functions.jar
To target a specific member group when undeploying all JAR files:
gfsh> undeploy --groups=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 JAR files in your cluster:
gfsh> list deployed
To see a list of all deployed JARs in a specific member group:
gfsh> list deployed --groups=MemberGroup1
Sample output:
Member | Deployed JAR | JAR Location
--------- | -------------------- | -------------------------------------------------
datanode1 | group1_functions.jar | /usr/local/gemfire/deploy/group1_functions.v1.jar
datanode2 | group1_functions.jar | /usr/local/gemfire/deploy/group1_functions.v1.jar
For more information about gfsh usage, see gfsh.
About Deploying JAR Files and the Cluster Configuration Service
By default, the cluster configuration service distributes deployed JAR files to all locators in the cluster. When you start a new server using gfsh, the locator supplies configuration files and deployed jar files to the member and writes them to the server’s directory.
See Overview of the Cluster Configuration Service.
Tanzu GemFire deploys JAR files using a classloader isolation model. JAR files are loaded into their own classloaders which are isolated from the rest of the system and from each other. Deployments are able to access classes from other deployed JAR files and from the system, but will look inside their own classloaders first before looking externally.
Note: Classloader isolation is the default setting and is recommended for all new implementations. Chained classloading was the GemFire version 9 default, and is provided in support of legacy applications. Classloader isolation can be disabled using the flag --disable-classloader-isolation=true when starting members through Gfsh using the start command.
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.
Deployment Location for JAR Files
JAR files are placed into a staging directory on the system and are not copied to the server’s working directory. Since JAR files are not located in the working directory, they will not be automatically redeployed from disk when the server restarts. JAR files will be redeployed by cluster configuration if it has been enabled.
Versioning of JAR Files
When you deploy a new JAR file, the member receiving the deployment checks whether the JAR file is a duplicate, meaning a JAR file with the same name and matching byte-for-byte contents is already deployed. If the JAR file is determined to be a duplicate, the deployment succeeds, but no changes occur as a result. If the JAR file is not a duplicate, the old JAR file is removed, its classes are unloaded, and the new JAR file is deployed.
Automatic Class Path Loading
Once a JAR file is deployed, its classes and resources are loaded into a classloader which will be accessible via the ClassPathLoader.
Undeploying a JAR file automatically unloads the classes and functions that were loaded during deployment. You do NOT need to restart your members to unload those classes.
JAR files are not automatically loaded from disk when the member starts. However, JAR files are automatically deployed by cluster configuration if it is enabled.
