WebSphere eXtreme Scale Programming Guide > Access data in WebSphere eXtreme Scale > EntityManager API introduction

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

These files specify which entities and BackingMaps a server will host.

The entity metadata descriptor file contains a description of the entities that are used. At minimum, 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 you are required to override the class attributes. If you are registering the entities classless , provide all of entity information in the XML file only.

You can use the following XML configuration snippet to define 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. Note that the objectgrid.xml snippet refers to the entity.xml file. In this case, the entity.xml file contains one entity, the Order entity.

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:

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>

This example assumes the Order class would have the orderNumber and desc fields annotated similarly.

An equivalent classless entity.xml would be as follows

classless 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="@Order " name="Order">
       
<description>"Entity named: Order"</description>
       
<attributes>
           
<id name="orderNumber" type="int"/>
           
<basic name="desc" type="java.lang.String"/>
       
</attributes>
    </entity>
</entity-mappings>

For information about starting an eXtreme Scale server, see Start stand-alone WebSphere eXtreme Scale servers, which uses both the deployment.xml and objectgrid.xml files to start the catalog server.

Connect to a distributed eXtreme Scale server

The following code enables the connect mechanism for a client and server on the same computer:

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, note the reference to the remote eXtreme Scale server. After you establish a connection , you can invoke EntityManager API methods such as persist, update, remove and find.

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.

Previously, using entities on an ObjectGrid client required you to make the ObjectGrid XML and entity XML available to the client in one of the following two ways:

1. Pass an overriding ObjectGrid XML to the ObjectGridManager.connect(String catalogServerAddresses, ClientSecurityConfiguration securityProps, URL overRideObjectGridXml) method.

   String catalogEndpoints="myHost: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");
   

2. Pass null for the override file and ensure that the ObjectGrid XML and referenced entity XML are available to the client on the same path as on the server.

   String catalogEndpoints="myHost:2809";
   ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, null);
   ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");
   

The XML files were required regardless of whether or not you wanted to use subset entities on the client side. These files are no longer required to use the entities as defined by the server. Instead, pass null as the overRideObjectGridXml parameter as in option 2 of the previous section. If the XML file is not found on the same path set on the server, the client will use the entity configuration on the server.

However, if you use subset entities on the client, provide an overriding ObjectGrid XML as in option 1.

Client and server side schema

The server-side schema defines the type of data 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 can have an object annotated as in the following example:

@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.

The client-side entity descriptor XML file is required in the following cases: if the server is running with class-based entities while the client side is running classless; or if the server is classless and the client uses class-based entities. A classless client mode allows the client to still run entity queries without having access to the physical classes. Assuming the server has registered the ServerPerson entity above, the client would override the grid with an entity.xml such as follows:

<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="@ServerPerson " name="Order">
       
<description>"Entity named: Order"</description>
       
<attributes>
           
<id name="socialSecurityNumber" type="java.lang.String"/>
           
<basic name="surname" type="java.lang.String"/>
       
</attributes>
    </entity>
</entity-mappings>

This will achieve an equivalent subset entity on the client, without requiring the client to provide the actual annotated class. If the server is classless, and the client is not, the client overrides with an entity descriptor XML file with a reference to the class file.

Referencing the schema

If running in Java SE 5, then the application can be added to the objects by using annotations. The EntityManager can read the schema from the annotations on those objects. The application provides the eXtreme Scale run time with references to these objects using the entity.xml file, which is referenced from the objectgrid.xml file. The entity.xml file lists all the entities, each of which is associated with either a class or a schema. If a proper class name is specified, then the application attempts to read the Java SE 5 annotations from those classes to determine the schema. If you do not annotate the class file or specify a classless identifier as the class name, 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 grid does not need XML files. The program can obtain an ObjectGrid reference and invoke the ObjectGrid.registerEntities method to specify a list of Java SE 5 annotated classes or an XML file.

The run time 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.

Parent topic

EntityManager API introduction

Related reference

API documentation: EntityManager interface

EntityTransaction interface

+

Search Tips   |   Advanced Search