To insert, delete, update, and retrieve data from your
data grid, you must write a client application. The getting started
sample includes a Java client application
that you can use to learn about creating your own client application.
The Client.java file in the wxs_install_root/ObjectGrid/gettingstarted/client/src/ directory
is the client program that demonstrates how to connect to a catalog
server, obtain the ObjectGrid instance, and use the ObjectMap API.
The ObjectMap API stores data as key-value pairs
and is ideal for caching objects that have no relationships involved.
The following steps discuss the contents of the Client.java file.
- Connect to the catalog service by obtaining a ClientClusterContext
instance.
To connect to the catalog server, use the connect method
of ObjectGridManager API. The following code snippet demonstrates how to connect
to a catalog server and obtain a ClientClusterContext instance:
ClientClusterContext ccc = ObjectGridManagerFactory.getObjectGridManager().connect(cep, null, null);
The connect method attempts
to connect to each appliance in the list until it makes a successful
connection. Automatic failover is provided if one of the other appliances
does not respond.
If the connections to the catalog servers succeed,
the connect method returns a ClientClusterContext
instance. The ClientClusterContext instance is required to obtain
the ObjectGrid from the ObjectGridManager API.
- Obtain an ObjectGrid instance.
To obtain
ObjectGrid instance, use the getObjectGrid method
of the ObjectGridManager API. The getObjectGrid method
requires both the ClientClusterContext instance and the name of the
data grid instance. The ClientClusterContext instance is obtained
during the connection to catalog server. The name of the data grid instance is the name
of the simple data grid that you created in the user interface. The
following code snippet demonstrates how to obtain the data grid by
calling the getObjectGrid method of the ObjectGridManager API.
ObjectGrid grid = ObjectGridManagerFactory.getObjectGridManager().getObjectGrid(ccc, "my_simple_data_grid");
- Set the necessary security
credentials.
Create a client security configuration
and a credential generator with a user name and password that you
supply to the application. The user name and password that you use
must have permission to access the data grid on the appliance. See
Managing users and groups for more information
about creating an authorized user.
// Creates a ClientSecurityConfiguration object using the specified file
ClientSecurityConfiguration clientSC = ClientSecurityConfigurationFactory.getClientSecurityConfiguration();
clientSC.setSecurityEnabled(true);
// Creates a CredentialGenerator using the passed-in user and password.
CredentialGenerator credGen = new UserPasswordCredentialGenerator(username,password);
clientSC.setCredentialGenerator(credGen);
return clientSC;
- Get a Session instance.
You can get a Session
from the obtained ObjectGrid instance. A Session instance is required
to get the ObjectMap instance, and perform transaction demarcation.
The following code snippet demonstrates how to get a Session instance
by calling the getSession method of the ObjectGrid API.
Session sess = grid.getSession();
- Get an ObjectMap instance.
After getting
a Session, you can get an ObjectMap instance from a Session instance
by calling getMap method of the Session API. The map instance name that you pass to the getMap method
has the same name as the data grid that you created in the user interface. The
following code snippet demonstrates how to obtain ObjectMap by calling
the getMap method of the Session API.
ObjectMap map1 = sess.getMap("my_simple_data_grid");
The previous example uses the default map instance
that is named after the data grid. You can also specify a new map
name, such as in the following examples:
ObjectMap map2 = sess.getMap("my_simple_data_grid.CT.P");
ObjectMap map3 = sess.getMap("my_new_map.NONE");
The
my_simple_data_grid.CT.P map
is a map that uses creation time eviction and pessimistic locking.
The
my_new_map.NONE map does not have any eviction
or locking settings. See
Dynamic map configuration options for more
information.
- Use the ObjectMap methods.
After an ObjectMap
instance is obtained, you can use the ObjectMap API.
Remember that the ObjectMap interface is a transactional map and requires
transaction demarcation by using the begin and commit methods
of the Session API. If there is no explicit transaction
demarcation in the application, the ObjectMap operations run with
auto-commit transactions.
The keys that
you use can be of an existing Java type, such as java.lang.String
or Integer. Values can consist of any serializable object type.
The following code snippet demonstrates how to use the ObjectMap API
with an auto-commit transaction.
map1.insert(key1, value1);
- You can either run a transaction on one
partition at a time, or on multiple partitions. To run a transaction
on a single partition, use a one-phase commit transaction:
sess.setTxCommitProtocol(TxCommitProtocol.ONEPHASE);
sess.begin();
map1.insert(k, v);
sess.commit();
To run a transaction across multiple partitions,
use a two-phase commit transaction: sess.setTxCommitProtocol(TxCommitProtocol.TWOPHASE);
sess.begin();
map1.insert(k, v);
sess.commit();
- Optional: Close the Session. After all of the Session and ObjectMap operations are complete,
close the session with the Session.close() method.
Running this method returns the resources that were being used by
the session.
sess.close();
As a result, subsequent getSession() method
calls return faster, and fewer Session objects are in the heap.