Manage JAR Files in GemFire XD

When you install a JAR file, you specify a unique GemFire XD JAR name, which is a SQL92Identifier. GemFire XD installs the JAR file and automatically loads the JAR file classes into its class loader, and the classes become available to all members of the distributed system (including members that join the system at a later time).

GemFire XD provides gfxd commands to install, replace, and remove JAR files as described in these sections:

Installing a JAR File

To install a JAR file to a GemFire XD distributed, use the install-jar command. For example, the following command installs the tours.jar file to the APP schema:
gfxd install-jar -name=APP.toursjar -file=c:\tours.jar 
                 -client-bind-address=locator_address
                 -client-port=locator_port
If the GemFire XD distributed system uses multicast for discovery instead of a locator, specify the multicast properties instead, as in:
gfxd install-jar -name=toursjar -file=c:\tours.jar 
                 -mcast-address=multicast_address
                 -mcast-port=multicast_port

The -name that you provide for the JAR must be a unique identifier. You must include a schema name to qualify the identifier. You can use the identifier with later calls to gfxd replace-jar or gfxd remove-jar.

The -file option specifies the location of the JAR file to install using either a local path or a URL.

After installing the JAR to the distributed system, GemFire XD automatically loads the JAR file classes into its class loader; you do not need to explicitly load classes after installing the JAR. The JAR and its classes are available to all members of the GemFire XD distributed system, including those that later join the cluster.

Note: After you install a JAR file, you cannot modify any of the individual classes or resources within the JAR file. Instead, you must replace the entire JAR file to update a class.

Replacing a JAR File

Use the replace-jar command to replace an installed JAR file with a new JAR. Specify the identifier of an existing JAR installation when using the command, as in:
gfxd replace-jar -name=APP.toursjar -file=c:\tours2.jar 
                 -client-bind-address=locator_address
                 -client-port=locator_port

To replace an existing JAR file, GemFire XD waits to obtain a lock on all datastore members, and then loads the new classes. It also recompiles objects that depend on the JAR file, such as installed listener and procedure implementations. All subsequent invocations of the affected listeners or procedures then use the new implementation.

Note: When you execute the command to replace a JAR file, it is possible that existing classes in the JAR are currently being used. For example, a data-aware procedure may be executing at the time when you choose to replace the JAR that contains the procedure implementation. In this case, gfxd waits for a period of time (gemfirexd.max-lock-wait) to obtain the locks necessary to replace the JAR file. If the procedure does not complete within this timeout period, you receive the error: ERROR 40XL1: A lock could not be obtained within the time requested. Should this occur, simply retry the gfxd replace-jar command.

Removing an Installed JAR File

Specify the JAR identifier with the remove-jar command to remove an installed JAR file. For example, the following command removes the class files associated with the APP.toursjar JAR installation:
gfxd remove-jar -name=APP.toursjar 
                 -client-bind-address=locator_address
                 -client-port=locator_port