EntityManager in a distributed environment

You can use EntityManager with a local ObjectGrid or in a distributed eXtreme Scale environment. The main difference is how you connect to this remote environment. After you establish a connection, there is no difference between using a Session object or using the EntityManager API.

Required configuration files

The following XML configuration files are required:
  • ObjectGrid descriptor XML file
  • Entity descriptor XML file
  • Deployment or grid 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 contains a description of the entities that are used. At minimum, you must specify the entity class and name. If you are running in a Java™ Platform, Standard Edition 5 environment, eXtreme Scale automatically reads the entity class and its annotations. You can define additional XML attributes if the entity class has no annotations or if any overriding is required. You can use the following XML configuration snippet for defining an eXtreme Scale grid with entities. In this snippet, 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. In this case, the entity.xml file contains one entity, the order entity.
Figure 1. objectgrid.xml
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
    <objectGrid name="bookstore" entityMetadataXMLFile="entity.xml">
     <backingMap name="Order"/>
    </objectGrid>
</objectGrids>

</objectGridConfig>
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:
Figure 2. entity.xml
<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="com.ibm.websphere.tutorials.objectgrid.em.distributed.step1.Order" name="Order"/>
</entity-mappings>
For information about starting an eXtreme Scale server, see Starting stand-alone WebSphere® eXtreme Scale servers, which uses both the deployment.xml and objectgrid.xml files to start the catalog server.

Connecting to a distributed eXtreme Scale server

The following code enables the connect mechanism for a client and server on the same computer:
Figure 3. Connection to distributed server
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");
In the preceding code snippet, notice the reference to the remote eXtreme Scale server. After the connection is established, you can invoke EntityManager API operations, such as the persist, update, remove and find methods.
Attention: When you are using entities, pass the client override ObjectGrid descriptor XML file to the connect method. If a null value is passed to the clientOverrideURL property and the client has a different directory structure than the server, then the client might fail to locate the ObjectGrid or entity descriptor XML files. At minimum, the ObjectGrid and entity XML files for the server can be copied to the client.

Client and server side schemas

The server side schema defines the type of data that is 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:
Figure 4. ServerPerson.java
@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:
Figure 5. ClientPerson.java
@Entity(name="ServerPerson")
class ClientPerson
{
  @Id @Basic(alias="ssn") String socialSecurityNumber;
  String surname;
}
This client then takes a server side entity and projects the subset of the entity into the client object. This projection leads to bandwidth and memory savings on a client because the client has only the information it needs instead of all of the information that is 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 the application 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 eXtreme Scale run time about these objects using the entity.xml file, which is referenced from the objectgrid.xml file. The entity.xml file lists all the entities. For each entity, the file specifies either a class name or a schema. If a class name is specified, then it tries to read the Java SE 5 annotations from those classes to determine the schema. If you do not annotate the class file, then the schema is taken from the XML file. The XML file is used to specify all the attributes, keys and relationships for each entity.

A local ObjectGrideXtreme Scale grid does not need any XML files. The program can obtain an eXtreme Scale reference and invoke the ObjectGrid.registerEntities method to specify a list of Java SE 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 eXtreme Scale is running on a server or in stand-alone 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.

Entity metadata descriptor file

See emd.xsd file for more information about the metadata descriptor file.