Using the modify_war Script

The script has the following options:

USAGE: modify_war <args>
WHERE <args>:

    -e <jar>
                    Assumes the input file is an .ear file and will add the
                    given jar as a shared, application library. The file will
                    be added in a /lib directory (by default) and any embedded
                    .war files will have a corresponding Class-Path entry added
                    to their MANIFEST.MF file. The option can be given multiple times.

    -h
                    Displays this help message.

    -j <jar>
                    Additional library to add to the input file. Can be given
                    multiple times.

    -J <jvm opt>
                    JVM argument to pass to sub-commands. Typically this might
                    be to define proxy values. For example -J"-Dhttp.proxyHost=my-proxy"

    -l <lib>
                    Library directory where new jars will be placed inside war.
                    Defaults to WEB-INF/lib.

    -m <lib>
                    Library directory where new jars will be placed inside ear.
                    Defaults to /lib.

    -o <file>
                    The output file.

    -p <param=value>
                    Specific parameter for inclusion into the session filter
                    definition as a regular init-param. Can be given multiple times.

    -r
                    Test run which only outputs an updated web.xml file.

    -t <cache-type>
                    Type of cache. Must be one of 'peer-to-peer' or
                    'client-server'. Default is peer-to-peer.

    -v 
                    Verbose output

    -w <war/ear file>
                    The input file - either a WAR or EAR. The following actions
                    will be performed depending on the type of file:
                    WARs will have a <filter> element added to the web.xml and
                    will have the appropriate jars copied to WEB-INF/lib.
                    If the file is an EAR, then the appropriate jars will be
                    copied to lib, within the ear and each embedded war files'
                    manifest will have a Class-Path entry added (if one does
                    not already exist).
                    An appropriate slf4j binding jar must be included for ears
                    or wars using -e or -j respectively. The following jars are
                    provided:
                        slf4j-jdk14
                        slf4j-log4j12
                        gemfire-modules-slf4j-weblogic

    -x
                    Do not create a self-contained war/ear file by copying all
                    necessary jars into the file. When this option is used,
                    additional jars will need to be made available to the
                    container:
                        gemfire.jar
                        gemfire-modules.jar
                        gemfire-modules-session.jar
                        slf4j-api.jar
                        slf4j-jdk14.jar (not for WebLogic)
                        gemfire-modules-slf4j-weblogic.jar (WebLogic only)
                    This option still modifes any web.xml files.
      

Manual Configuration

To modify your war or ear file manually, make the following updates:

If you are deploying an ear file and wish to bundle all dependent jars within the ear then the following steps are also required:

Peer-to-Peer Setup

To run GemFire in a peer-to-peer configuration, use the -t peer-to-peer option to the modify_war script. This adds the following to web.xml:

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
      com.gemstone.gemfire.modules.session.filter.SessionCachingFilter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>peer-to-peer</param-value>
    </init-param>
</filter>

If you do not make any further configuration changes, peers attempt to locate each other using a default multicast channel (as defined by the mcast-port property found in Using a Different Multicast Port). Refer to Peer-to-Peer Configuration Using Locators for information on creating and using locators, which provide both discovery and load balancing services.

GemFire properties can be set with filter params prefixed with gemfire.property. Thus, to use a specific multicast port you would use the following option: -p gemfire.property.mcast-port=12345 -t peer-to-peer. This would create the xml below:

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
      com.gemstone.gemfire.modules.session.filter.SessionCachingFilter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>peer-to-peer</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.mcast-port</param-name>
        <param-value>12345</param-value>
    </init-param>
</filter>

Client/Server Setup

To run GemFire in a client/server configuration, you make the application server operate as a GemFire client. Use the -t client-server option to the modify_war script. This adds the following filter to application server's web.xml file:

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
      com.gemstone.gemfire.modules.session.filter.SessionCachingFilter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>client-server</param-value>
    </init-param>
</filter>

Because the application server operates as a GemFire client in this configuration, you must manually launch a GemFire cache server. You can do this with the following script (which should be installed into the bin subdirectory):

In Unix: 
  prompt$ ./cacheserver.sh start
  
In Windows:
  prompt> cacheserver.bat start 

See Running GemFire Server Processes for more information on using this script.

If you plan to use the deprecated cacheserver script that comes with the standalone GemFire product, you will need to manually add the following items to the GemFire server's classpath. Note that these JARs and file directory are automatically added to the classpath by the supplied cacheserver.sh (or cacheserver.bat) script that comes with the GemFire HTTP Session Management Module for AppServers.

• $GEMFIRE/lib/gemfire-modules-X.X.X.jar
• $GEMFIRE/lib/gemfire-modules-session-X.X.X.jar
• $GEMFIRE/lib/gemfire-modules-session-external-X.X.X.jar
• $GEMFIRE/lib/servlet-api-2.5.jar
• $GEMFIRE/lib/slf4j-api-1.5.8.jar
• $GEMIFRE/lib/slf4j-jdk14-1.5.8.jar
• $GEMFIRE/conf

where X.X.X corresponds to the version of GemFire you are using.

Without making any further configuration changes, the client and server attempt to locate each other on the same system using a default port (40404). Though useful for testing purposes, you would not normally deploy a client/server configuration in this way. Refer to Client/Server Configuration Using Locators for information on creating and using Locators, which provide both discovery and load balancing services.

Starting the Application Server

After you update the configuration, you are now ready to start your application server instance. Refer to your application server documentation for starting the application server. Once the application server is started, GemFire will automatically launch within the application server process.

Verifying that GemFire Started

You can verify that GemFire has successfully started by inspecting the application server log file. For example:

####<Feb 22, 2011 10:34:34 AM PST> <Info> ... <BEA-000000> 
    <Creating distributed system from: 
    {log-file=user/weblogic/domain1/servers/myserver/
     logs/gemfire_modules.2011-02-22.log,
    cache-xml-file=cache.xml}>
####<Feb 22, 2011 10:34:39 AM PST> <Info> ... <BEA-000000> 
    <Created GemFireCache[id = 28354945; isClosing = false; 
    created = Tue Feb 22 10:34:39 PST 2011; server = false; 
    copyOnRead = false; lockLease = 120; lockTimeout = 60]>

Information is also logged within the GemFire log file, which by default is named "gemfire_modules.<date>.log".

Configuring Non-Sticky Session Replication

Some situations require sessions to be 'non-sticky', which means that client requests can be directed to any server in a cluster of application servers instead of the same server each time. To achieve this, you must configure your deployment as described for the following topologies.

Peer-to-Peer

No additional configuration is required.

Client-Server

For client-server topologies, the local client cache must be empty. Ensure that the filter property gemfire.cache.enable_local_cache=false is set. This effectively sets the local client cache to be a PROXY cache.