clientAPI

GemStone^® GemFire Enterprise^™

Client/Server Caching API Example

The clientAPI example demonstrates how to configure your client applications through the GemFire API instead of through the cache.xml. For information on client/server caching, see the GemFire Enterprise Developer's Guide and the online Java documentation under the com.gemstone.gemfire.cache package in subpackages util, client, and server.

The Configuration Files
The gemfire.properties distributed system configuration file is used by the locator and cacheserver processes that you will be running.

The cacheserver also uses the server.xml cache configuration file. The client does not use any configuration files.

The Client/Server Processes
The processes used for this example are:

• The GemFire locator service. The locator runs as a member of the server's distributed system, using the same gemfire.properties file as the server. The locator maintains a dynamic list of the members of its system, and knows which of them are running as servers. The locator provides both peer member discovery for the server system and server discovery for any clients that connect to it.


• The cacheserver process. The server runs with the same distributed system configuration as the locator, and connects to the locator at startup to join the distributed system.


• The client processes. The Client.java application can be run in two modes: publisher and subscriber. All client configuration is done inside the application. The client runs outside of the server distributed system as a standalone application. In its cache configuration, the client defines a server connection pool, which specifies the locator's address as the place to go for server connection information. At startup, whether running as publisher or subscriber, the client connects only to the server process and not to any peer applications. The subscriber creates its region with a CacheListener to report on entry updates. It sends a subscription request to the server for all entry events in the region. It then waits for 10 puts to arrive in its cache. The publisher creates the same region and puts 10 entries into it. The puts are forwarded to the server, who forwards them to the subscriber.

When you run the examples, if you get a startup failure with a message indicating socket creation failure or that the port is already in use, make sure you are not starting a second copy of the same GemFire process, with the same port configuration. If you are not, then the port specification probably conflicts with some other non-GemFire application. Follow the instructions in Changing the ports used in the examples for the process that is failing to start.

You need two terminal sessions: one to run the locator, cacheserver, and client subscriber, and the other to run the client publisher. For both sessions, make sure the environment is set according to the instructions in examples/EnvSetup.html.

1. Change directory to examples/dist/clientAPI. The example instructions assume you are starting from that directory.
   


2. In one session, start the locator:

gemfire start-locator -port=41111

3. When that returns, run the cacheserver in the same session:

cacheserver start cache-xml-file=server.xml

4. When that returns, start the client subscriber in the same session:

java clientAPI.Client subscriber

The subscriber starts, connects to the server, and reports that it is waiting for the publisher to do its puts.


5. Start the client publisher in the other session:

java clientAPI.Client publisher

When the clients finish, both exit automatically.

6. In the first session, stop the locator and cacheserver:

    cacheserver stop 
    gemfire stop-locator -port=41111

• Change the command-line -port specification for gemfire start-locator and gemfire stop-locator.
• Change the locators specification in the gemfire.properties file.
• Add -DlocatorPort=<yourPortNumber> to the java command-line invocation for the subscriber and the publisher, like this:.

     java -DlocatorPort=40100 clientAPI.Client subscriber
     java -DlocatorPort=40100 clientAPI.Client publisher

• When you finish the example, stop the locator and specify the new port number by entering the following command in one of the open sessions:

     gemfire stop-locator -port=40100