Program guide > Access data with client applications > Use ObjectGridManager
createObjectGrid methods
This topic describes the seven createObjectGrid methods in the ObjectGridManager interface. Each of these methods creates a local instance of an ObjectGrid.
Local in-memory instance
The following code snippet illustrates how to obtain and configure a local ObjectGrid instance with eXtreme Scale.
// Obtain a local ObjectGrid reference // you can create a new ObjectGrid, or get configured ObjectGrid // defined in ObjectGrid xml file ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager(); ObjectGrid ivObjectGrid = objectGridManager.createObjectGrid("objectgridName"); // Add a TransactionCallback into ObjectGrid HeapTransactionCallback tcb = new HeapTransactionCallback(); ivObjectGrid.setTransactionCallback(tcb); // Define a BackingMap // if the BackingMap is configured in ObjectGrid xml // file, you can just get it. BackingMap ivBackingMap = ivObjectGrid.defineMap("myMap"); // Add a Loader into BackingMap Loader ivLoader = new HeapCacheLoader(); ivBackingMap.setLoader(ivLoader); // initialize ObjectGrid ivObjectGrid.initialize(); // Obtain a session to be used by the current thread. // Session can not be shared by multiple threads Session ivSession = ivObjectGrid.getSession(); // Obtaining ObjectMap from ObjectGrid Session ObjectMap objectMap = ivSession.getMap("myMap");
Default shared configuration
The following code is a simple case of creating an ObjectGrid to share among many users.
import com.ibm.websphere.objectgrid.ObjectGrid; import com.ibm.websphere.objectgrid.ObjectGridException; import com.ibm.websphere.objectgrid.ObjectGridManagerFactory; import com.ibm.websphere.objectgrid.ObjectGridManager; final ObjectGridManager oGridManager= ObjectGridManagerFactory.getObjectGridManager(); ObjectGrid employees = oGridManager.createObjectGrid("Employees",true); employees.initialize(); employees. /*sample continues..*/
The preceding Java™ code snippet creates and caches the Employees ObjectGrid. The Employees ObjectGrid is initialized with the default configuration and is ready for use. The second parameter in the createObjectGrid method is set to true, which instructs the ObjectGridManager to cache the ObjectGrid instance it creates. If this parameter is set to false, the instance is not cached. Every ObjectGrid instance has a name, and the instance can be shared among many clients or users based on that name.
If the objectGrid instance is used in peer-to-peer sharing, the caching must be set to true. For more information on peer-to-peer sharing, see Distributing changes between peer Java Virtual Machines.
XML configuration
WebSphere eXtreme Scale is highly configurable. The previous example demonstrates how to create a simple ObjectGrid without any configuration. This example shows you how to create a pre-configured ObjectdGrid instance that is based on an XML configuration file. You can configure an ObjectGrid instance programmatically or using an XML-based configuration file. You can also configure ObjectGrid using a combination of both approaches. The ObjectGridManager interface allows creation of an ObjectGrid instance based on the XML configuration. The ObjectGridManager interface has several methods that take a URL as an argument. Every XML file that is passed into the ObjectGridManager must be validated against the schema. XML validation can be disabled only when the file is previously validated and no changes have been made to the file since its last validation. Disabling validation saves a small amount of overhead but introduces the possibility of using an invalid XML file. The IBM Java Developer Kit (JDK) 1.4.2 has support for XML validation. When using a JDK that does not have this support, Apache Xerces might be required to validate the XML.
The following Java code snippet demonstrates how to pass in an XML configuration file to create an ObjectGrid.
import java.net.MalformedURLException; import java.net.URL; import com.ibm.websphere.objectgrid.ObjectGrid; import com.ibm.websphere.objectgrid.ObjectGridException; import com.ibm.websphere.objectgrid.ObjectGridManager; import com.ibm.websphere.objectgrid.ObjectGridManagerFactory; boolean validateXML = true; // turn XML validation on boolean cacheInstance = true; // Cache the instance String objectGridName="Employees"; // Name of Object Grid URL allObjectGrids = new URL("file:test/myObjectGrid.xml"); final ObjectGridManager oGridManager= ObjectGridManagerFactory.getObjectGridManager(); ObjectGrid employees = oGridManager.createObjectGrid(objectGridName, allObjectGrids, bvalidateXML, cacheInstance);
The XML file can contain configuration information for several ObjectGrids. The previous code snippet specifically returns ObjectGrid Employees, assuming that the Employees configuration is defined in the file. For the XML syntax, see ObjectGrid configuration. Seven createObjectGrid methods exist, and are documented in the following code block.
/** * A simple factory method to return an instance of an * Object Grid. A unique name is assigned. * The instance of ObjectGrid is not cached. * Users can then use {@link ObjectGrid#setName(String)} to change the * ObjectGrid name. * * @return ObjectGrid an instance of ObjectGrid with a unique name assigned * @throws ObjectGridException any error encountered during the * ObjectGrid creation */ public ObjectGrid createObjectGrid() throws ObjectGridException; /** * A simple factory method to return an instance of an ObjectGrid with the * specified name. The instances of ObjectGrid can be cached. If an ObjectGrid * with the this name has already been cached, an ObjectGridException * will be thrown. * * @param objectGridName the name of the ObjectGrid to be created. * @param cacheInstance true, if the ObjectGrid instance should be cached * @return an ObjectGrid instance * @this name has already been cached or * any error during the ObjectGrid creation. */ public ObjectGrid createObjectGrid(String objectGridName, boolean cacheInstance) throws ObjectGridException; /** * Create an ObjectGrid instance with the specified ObjectGrid name. The * ObjectGrid instance created will be cached. * @param objectGridName the Name of the ObjectGrid instance to be created. * @return an ObjectGrid instance * @throws ObjectGridException if an ObjectGrid with this name has already * been cached, or any error encountered during the ObjectGrid creation */ public ObjectGrid createObjectGrid(String objectGridName) throws ObjectGridException; /** * Create an ObjectGrid instance based on the specified ObjectGrid name and the * XML file. The ObjectGrid instance defined in the XML file with the specified * ObjectGrid name will be created and returned. If such an ObjectGrid * cannot be found in the xml file, an exception will be thrown. * * This ObjecGrid instance can be cached. * * If the URL is null, it will be simply ignored. In this case, this method behaves * the same as {@link #createObjectGrid(String, boolean)}. * * @param objectGridName the Name of the ObjectGrid instance to be returned. It * must not be null. * @param xmlFile a URL to a wellformed xml file based on the ObjectGrid schema. * @param enableXmlValidation if true the XML is validated * @param cacheInstance a boolean value indicating whether the ObjectGrid * instance(s) * defined in the XML will be cached or not. If true, the instance(s) will * be cached. * * @throws ObjectGridException if an ObjectGrid with the same name * has been previously cached, no ObjectGrid name can be found in the xml file, * or any other error during the ObjectGrid creation. * @return an ObjectGrid instance * @see ObjectGrid */ public ObjectGrid createObjectGrid(String objectGridName, final URL xmlFile, final boolean enableXmlValidation, boolean cacheInstance) throws ObjectGridException; /** * Process an XML file and create a List of ObjectGrid objects based * upon the file. * These ObjecGrid instances can be cached. * An ObjectGridException will be thrown when attempting to cache a * newly created ObjectGrid * that has the same name as an ObjectGrid that has already been cached. * * @param xmlFile the file that defines an ObjectGrid or multiple * ObjectGrids * @param enableXmlValidation setting to true will validate the XML * file against the schema * @param cacheInstances set to true to cache all ObjectGrid instances * created based on the file * @return an ObjectGrid instance * @throws ObjectGridException if attempting to create and cache an * ObjectGrid with the same name as * an ObjectGrid that has already been cached, or any other error * occurred during the * ObjectGrid creation */ public List createObjectGrids(final URL xmlFile, final boolean enableXmlValidation, boolean cacheInstances) throws ObjectGridException; /** Create all ObjectGrids that are found in the XML file. The XML file will be * validated against the schema. Each ObjectGrid instance that is created will * be cached. An ObjectGridException will be thrown when attempting to cache a * newly created ObjectGrid that has the same name as an ObjectGrid that has * already been cached. * @param xmlFile The XML file to process. ObjectGrids will be created based * on what is in the file. * @return A List of ObjectGrid instances that have been created. * @throws ObjectGridException if an ObjectGrid with the same name as any of * those found in the XML has already been cached, or * any other error encounterred during ObjectGrid creation. */ public List createObjectGrids(final URL xmlFile) throws ObjectGridException; /** * Process the XML file and create a single ObjectGrid instance with the * objectGridName specified only if an ObjectGrid with that name is found in * the file. If there is no ObjectGrid with this name defined in the XML file, * an ObjectGridException * will be thrown. The ObjectGrid instance created will be cached. * @param objectGridName name of the ObjectGrid to create. This ObjectGrid * should be defined in the XML file. * @param xmlFile the XML file to process * @return A newly created ObjectGrid * @throws ObjectGridException if an ObjectGrid with the same name has been * previously cached, no ObjectGrid name can be found in the xml file, * or any other error during the ObjectGrid creation. */ public ObjectGrid createObjectGrid(String objectGridName, URL xmlFile) throws ObjectGridException;
Client hangs during a getObjectGrid method call
A client might seem to hang when calling the getObjectGrid method on the ObjectGridManager or throw an exception: com.ibm.websphere.projector.MetadataException. The EntityMetadata repository is not available and the timeout threshold is reached. The reason is the client is waiting for the entity metadata on the ObjectGrid server to become available. This error can occur when a container has been started, but the initial number of containers or minimum number of synchronous replicas has not been reached. Examine the deployment policy for the ObjectGrid and verify that the number of active containers is greater than or equal to both the numInitialContainers and minSyncReplicas attributes in the deployment policy descriptor file.
Parent topic:
Interacting with an ObjectGrid using ObjectGridManager
Related concepts
Controlling the life cycle of an ObjectGrid