Alternate Methods for Managing JAR Files

GemFire XD also provides system procedures that you can use to interactively install and manage JAR files from a client connection. Keep in mind that the procedures have certain limitations compared to using gfxd commands to manage JAR files.

This topic contains the following sections:

See also JAR Installation Procedures for more information about the procedures used to manage installed JAR files.

Restrictions for Managing JAR Files Using System Procedures

To use the SQLJ.INSTALL_JAR or SQLJ.REPLACE_JAR procedure, the JAR file path must be available on the specific GemFire XD data store to which the client is connected. If the client connects directly to a known GemFire XD server, then only that server requires the JAR file to be available at the specified path when the procedure executes. However, if the client connects using a locator then it may be connected to any available server in the distributed system. In this case, the JAR file path should be available to all members of the GemFire XD cluster (for example, from a fileshare location such as z:\) to ensure that the procedure can execute.

Note: If you cannot provide a common JAR location to ensure that SQLJ.INSTALL_JAR or SQLJ.REPLACE_JAR executes, use the gfxd commands described in Manage JAR Files in GemFire XD or manually inject the JAR file into the GemFire XD system as described in Installing a JAR File Directly into SYS.JARS .

Installing a JAR File with SQLJ.INSTALL_JAR

To install a JAR file to GemFire XD, connect to a GemFire XD member and execute the install_jar procedure. For example, the following procedure installs the tours.jar file to the APP schema, from a fileshare location:
call sqlj.install_jar(
    'z:\tours.jar', 'APP.Sample1', 0)
Note: The final integer argument specifies an alias for the JAR file. However, GemFire XD ignores this argument, so it is normally set to 0.

The second argument defines an identifier for the JAR file in the GemFire XD system. You must include a schema name to qualify the identifier. You can use the JAR identifier at a later time with the SQLJ.REPLACE_JAR and SQLJ.REMOVE_JAR procedures.

You can optionally specify a quoted identifier for the GemFire XD JAR name:

call sqlj.install_jar(
    'z:\tours.jar', 'APP."Sample2"', 0)

After installing the JAR, 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.

Installing a JAR File Directly into SYS.JARS

If the JAR file to install is not available to every data store member in the GemFire XD cluster, inject the JAR file directly from the client into the GemFire XD system using Java code.

The SYS.JARS table stores installed JAR files, and you can insert a new JAR into this table as a byte[] value. For example, an application can use code similar to the following to add a JAR to the SYS.JARS table:
byte[] jarBytes = getJarBytes(myjar);
String sql = "insert into SYS.JARS values(?, ?)";
    PreparedStatement ps = conn.prepareStatement(sql);
    ps.setString(1, "app.sample1");
    ps.setBytes(2, jarBytes);
    ps.executeUpdate();
In this example application, the getJarBytes() method would be implemented in the following way:
public static byte[] getJarBytes(String jar) throws Exception {
    FileInputStream fis = new FileInputStream(jar);
    byte[] data = new byte[4096];
    int len;
    ByteArrayOutputStream bos = new ByteArrayOutputStream();
    while ((len = fis.read(data)) != -1) {
      bos.write(data, 0, len);
    }
    return bos.toByteArray();
  }

GemFire XD automatically loads the installed JAR file class into its class loader; you do not need to explicitly load classes after installing the JAR.

Replacing a JAR File with SQLJ.REPLACE_JAR

Execute the SQLJ.REPLACE_JAR procedure on a GemFire XD member to replace a JAR file. For example, the following procedure replaces the JAR contents of the loaded APP.Sample1 JAR installation with the contents of the newtours.jar file.

call sqlj.replace_jar(
    'c:\myjarfiles\newtours.jar', 'APP.Sample1');

When you replace a JAR file, GemFire XD loads the new classes right away without your having to reboot.

Removing an Installed JAR File with SQLJ.REMOVE_JAR

Execute the SQLJ.REMOVE_JAR procedure on a GemFire XD member to remove an installed JAR file. For example, the following command removes the class files associated with the APP.Sample1 JAR installation:
call sqlj.remove_jar(
    'APP.Sample1', 0);
Note: The final integer argument specifies an alias for the JAR file. However, GemFire XD ignores this argument, so it is normally set to 0.