See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in
with your developerWorks ID, you can leave comments and feedback for the development team.
In the Introduction to the EntityManager API section, EntityManager usage was discussed with a local, standalone ObjectGrid. In this section EntityManager usage is discussed with a distributed and partitioned ObjectGrid. The main difference however, is the remote ObjectGrid is accessed or connected. After the connection is established with remote ObjectGrid, no difference exists in accessing EntityManager from the Session object and using EntityManager API.
Required configuration files
Three XML configuration files are required:
- ObjectGrid descriptor XML file
- Entity descriptor XML file
- Deployment or cluster descriptor XML file
The server must be told which entities and BackingMaps to host during startup. Create an ObjectGrid XML and an entity XML file:
The Entity metadata descriptor file describes to the ObjectGrid all of the entities that are used. At minimum, the entity class and name must be specified. The ObjectGrid automatically reads the entity class and its annotations, if you are running in Java SE 5 environment. Additional XML attributes can be defined if the entity class has no annotations or if any overriding is required. An XML configuration snippet for defining an objectGrid configuration to be used with entities follows. Here the server creates an ObjectGrid with the name bookstore and an associated backing map with the name order. The snippet refers to the entity.xml file which contains the entities, in this case only one (order).
<objectGrids>
<objectGrid name="bookstore" entityMetadataXMLFile="entity.xml">
<backingMap name="Order"/>
</objectGrid>
</objectGrids>
This ObjectGrid.xml file refers to the entity.xml with the entityMetadataXMLFile attribute. The location of this file is relative to the location of the objectGrid.xml file. An example of the entity.xml file follows:
<entity class-name="emtutorial.distributed.step1.Order" name="Order"/>
For information about starting of ObjectGrid server, see Starting ObjectGrid server processes, which uses both the deployment.xml and objectGrid.xml files to start the catalog server.
Connecting to a distributed ObjectGrid server
The following code snippet describes the connect mechanism for a client and server on the same machine.
String catalogEndpoints="localhost:2809";
URL clientOverrideURL= new URL("file:etc/emtutorial/distributed/step1/objectgrid.xml");
ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, clientOverrideURL);
ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");
 |
A client override ObjectGrid descriptor XML should always be passed to connect method when using entities. If a null value is passed to to the clientOverrideURL property and the client has a different directory structure than the server, then the client may fail to locate the objectgrid or entity descriptor XML files. At minimum, the server's objectgrid and entity xml files can be copied to the client. |
From the above code snippet, you have a reference to remote ObjectGrid server. All EntityManager operations, such as persist, update, remove and find can be performed.
Client and server side schemas
The server side schema is what is actually stored in the Maps on a server. The client side schema is a mapping to application objects from the schema on the server. For example, you might have the following server side schema:
@Entity
class ServerPerson
{
@Id String ssn;
String firstName;
String surname;
int age;
int salary;
}
A client might have an object annotated as in the following example:
@Entity(name="ServerPerson")
class ClientPerson
{
@Id @Basic(alias="ssn") String socialSecurityNumber;
String surname;
}
This client would then take a server side entity and project the subset of it into the client object. This projection leads to bandwidth and memory savings on a client because the client has only what it needs instead of everything in the server side entity. Different applications can use their own objects instead of forcing all applications to share a set of classes for data access.
Where does the schema come from?
If the application uses Java SE 5, then it can be added to the objects using annotations. The EntityManager can read the schema from the annotations on those objects. The EntityManager needs to know which Objects to look at. The application tells the ObjectGrid runtime about these objects using the entity.xml file, which is referenced from the objectgrid.xml file. The entity.xml file lists all entities. For each entity, it specifies either a class name or a schema. If a class name is specified, then it tries to read the Java 5 annotations from those classes to determine the schema. If class file is not annotated then the schema is taken from the XML. The XML is used to specify all the attributes, keys and relationships for each entity.
A standalone ObjectGrid usage doesn't need any XML files. The program can obtain an ObjectGrid reference and invoke the ObjectGrid.registerEntities method to specify a list of Java 5 annotated classes or an XML file.
The runtime uses the XML file or a list of annotated classes to find entity names, attribute names and types, key fields and types and relationships between entities. If ObjectGrid is running on a server or in standalone mode, then it automatically makes a Map named after each Entity. These Maps can be customized further using the objectgrid.xml file or APIs set either by the application or injection frameworks such as Spring.
© Copyright IBM Corporation 2007,2009. All Rights Reserved.
