replace-jar

Replaces an installed JAR file with the contents of a new JAR file. The classes in the new JAR file are automatically loaded into the GemFire XD class loader and they replace any classes that were previously installed for the same JAR identifier. GemFire XD also recompiles objects that depend on the JAR file, such as installed listener implementations.

Syntax

To replace an installed JAR file with the contents of a new JAR file, use the syntax:

gfxd replace-jar -file=<path or URL> -name=<identifier>
     [-auth-provider=<name>]
     [-bind-address=<address>]
     [-client-bind-address=<address>]
     [-client-port=<port>]
     [-extra-conn-props=<properties>] 
     [-help] [-locators=<adresses>]
     [-mcast-address=<address>]
     [-mcast-port=<port>]
     [-password[=<password>]]
     [-user=<username>]

This table describes options for the gfxd replace-jar command. Default values are used if you do not specify an option.

Option Description
-file

The local path of the new JAR file, or a URL that links to the JAR file.

This argument is required.

-name The unique identifier of an existing JAR installation to replace. The identifier you provide must specify a schema name delimiter. For example: APP.myjar.

This argument is required.

-auth-provider Sets the authentication provider to use for peer-to-peer connections as well as client-server connections. Valid values are BUILTIN and LDAP. All other members of the GemFire XD distributed system must use the same authentication provider and user definitions. If you omit this option, the connection uses no authentication mechanism. See Configuring Security.
-bind-address The address to which this peer binds for receiving peer-to-peer messages. By default gfxd uses the hostname, or localhost if the hostname points to a local loopback address.
-client-bind-address

The hostname or IP address on which a GemFire XD locator listens for client connections. The default is "localhost."

Use this option with -client-port to attach to a GemFire XD cluster as a thin client and perform the command.

-client-port

The port on which a GemFire XD locator listens for client connections. The default is 1527.

Use this option with -client-bind-address to attach to a GemFire XD cluster as a thin client and perform the command.

-extra-conn-props

A semicolon-separated list of properties to use when connecting to the GemFire XD distributed system.

-help, --help

Display the help message for this gfxd command.

-locators

The list of locators as comma-separated host[port] values, used to discover other members of the distributed system.

Using -locators creates a peer client member to execute the gfxd command.

-mcast-address

The multicast address used to discover other members of the distributed system. This value is used only when the -locators option is not specified. The default multicast address is 239.192.81.1.

Use this option with -mcast-port to attach to a GemFire XD cluster as a peer client and perform the command.

-mcast-port

The multicast port used to communicate with other members of the distributed system. If zero, multicast is not used for member discovery (specify -locators instead). This value is used only if the -locators option is not specified.

Valid values are in the range 0–65535, with a default value of 10334.

Use this option with -mcast-address to attach to a GemFire XD cluster as a peer client and perform the command.

-password

If the servers or locators have been configured to use authentication, this option specifies the password for the user (specified with the -user option) to use for booting the server and joining the distributed system.

The password value is optional. If you omit the password, gfxd prompts you to enter a password from the console.

-user If the servers or locators have been configured to use authentication, this option specifies the user name to use for booting the server and joining the distributed system.

Description

Specify one of these pairs of options with the command to connect to a GemFire XD Distributed system and replace a JAR file installation:
  • Use both -client-bind-address and -client-port to connect to a GemFire XD cluster as a thin client and perform the command.
  • Use both mcast-port and -mcast-address, or use the -locators property to connect to a GemFire XD cluster as a peer client and perform the command.

The -name that you provide for the JAR must be an existing JAR file identifier (created with install-jar). You must include a schema name to qualify the identifier.

The -file option specifies the location of the new JAR file to use for replacing the existing JAR installation. Include either a local path to the file or a URL.

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 for the data-aware procedure to finish. If the procedure does not complete within the timeout period, you receive a the error: ERROR 40XL1: A lock could not be obtained within the time requested. If this occurs, simply retry the gfxd replace-jar command.

See Storing and Loading JAR Files in GemFire XD.

Examples

This command connects to a GemFire XD network server running on localhost:1527, and replaces the JAR installation name APP.toursjar with a new JAR file named tours2.jar:
gfxd replace-jar -name=APP.toursjar -file=c:\tours2.jar
This command connects to a GemFire XD network server running on myserver:1234 to replace the JAR file:
gfxd replace-jar -name=APP.toursjar -file=c:\tours2.jar 
     -client-bind-address=myserver -client-port=1234
This command connects as a peer client to a GemFire XD system running on multicast port 1234, and replaces the JAR file:
gfxd replace-jar -name=APP.toursjar -file=c:\tours2.jar
    -mcast-port=1234 -extra-conn-props=host-data=false