Connecting to distributed ObjectGrid instances programmatically

You can connect to a distributed ObjectGrid with the connection end points for the catalog service domain. You must have the host name and listener port of each catalog server in the catalog service domain to which you want to connect.

Before you begin

To connect to a distributed data grid, you must configure your server-side environment with a catalog service and container servers.
You must have the listener port for each catalog service. For more information, see Planning for network ports.
If the client application is running in WebSphere Application Server augmented with eXtreme Scale, configure the catalog service domain using the WebSphere Application Server administrative console or wsadmin.

About this task

When running in a Java™ EE application, consider using the eXtreme Scale resource adapter. The resource adapter allows the application to look up a ObjectGrid connection in Java Naming Directory Interface (JNDI) using a Java Connector Architecture (JCA) connection factory, which significantly simplifies access to the data grid and allows integration with Java Transaction API (JTA) transactions. For more information, see Scenario: Using JCA to connect transactional applications to eXtreme Scale clients.

The ObjectGridManager.connect() methods connect to a catalog service domain using the supplied connection end points and returns a ClientClusterContext object that is used to retrieve ObjectGrid instances for the domain. The connection end points are a comma-delimited list of host and port combinations for each catalog server in the catalog service domain. See the following format of the catalog service endpoints:

catalogServiceEndpoints ::= <catalogServiceEndpoint> [,<catalogServiceEndpoint>]
catalogServiceEndpoint  ::= <hostName> : <listenerPort>
hostName                ::= The IP address or host name of a catalog service.
listenerPort            ::= The listener port that the catalog service is configured to use.

After you connect to the catalog service domain, use the ObjectGridManagerFactory.getObjectGrid(ClientClusterContext ccc, String objectGridName) method to retrieve a named ObjectGrid client instance. This ObjectGrid instance is a proxy for the named data grid and is cached in the client application. The ObjectGrid instance represents a logical connection to the remote data grid and is thread safe. All underlying physical connections to the data grid are managed automatically and can tolerate failure events.

The connection steps vary depending on whether you are using a stand-alone configuration or WebSphere Application Server.

Procedure

Connect to a stand-alone distributed data grid using explicit catalog service end points.

// Retrieve an ObjectGridManager instance.
ObjectGridManager ogm = ObjectGridManagerFactory.getObjectGridManager();

// Obtain a ClientClusterContext by connecting to a catalog 
// service domain, manually suppling the catalog service endpoints, 
// and optionally specifying the ClientSecurityConfiguration and 
// client ObjectGrid override XML file URL.
String catalogServiceEndpoints = "host1:2809,host2:2809";
ClientClusterContext ccc = ogm.connect(catalogServiceEndpoints, 
		(ClientSecurityConfiguration) null, (URL) null);
				
// Obtain a distributed ObjectGrid using ObjectGridManager and providing
// the ClientClusterContext.
ObjectGrid og = ogm.getObjectGrid(ccc, "Mygrid");

Connect to a catalog service domain from a client application that is hosted in WebSphere Application Server, where the catalog service domain was configured using the administrative console or admin task. The catalog service endpoints can be retrieved from a named domain identifier or for the default domain using the ObjectGridManager.

// Retrieve an ObjectGridManager instance.
ObjectGridManager ogm = ObjectGridManagerFactory.getObjectGridManager();

// Retrieve the domain by its ID (the name given to it in the admin console or wsadmin)
// The CatalogDomainManager also includes methods to retrieve all domains and the default domain.
CatalogDomainInfo di = ogm.getCatalogDomainManager().getDomainInfo("ProductionDomain");
if(di == null) throw new IllegalStateException("Domain not configured");

// Connect to the domain using the catalog service endpoints and the security configuration
// in the CatalogDomainInfo object.  The client override ObjectGrid XML is optional
// and is manually supplied.
ClientClusterContext ccc = ogm.connect(di.getClientCatalogServiceEndpoints(),  
		di.getClientSecurityConfiguration(), (URL) null);

// Obtain a distributed ObjectGrid using ObjectGridManager and by providing
// the ClientClusterContext.
ObjectGrid og = ogm.getObjectGrid(ccc, "MyGrid");

What to do next

If the catalog service domain is hosted in a WebSphere Application Server deployment manager, clients outside of the cell, including Java Platform, Enterprise Edition clients, must connect to the catalog service using the deployment manager host name and the IIOP bootstrap port. When the catalog service runs in WebSphere Application Server cells, and the clients run outside of the cells, look to the eXtreme Scale domain configuration pages in the WebSphere Application Server administrative console for the information that you need to point a client to the catalog service.