Entity manager in a distributed environment
Required configuration files
- ObjectGrid descriptor XML file
- Entity descriptor XML file
- Deployment or data grid descriptor XML file
These files specify the entities and BackingMaps that a server hosts.
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 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 a data 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 objectgrid.xml file 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>
- For a relative directory: Specify the location relative to the location of the objectgrid.xml file.
- For an absolute path: Specify the location with a URL format, such as file:// or http://.
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 that the Order class would have the orderNumber and
desc fields annotated similarly.An equivalent classless entity.xml file 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>
Connecting 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");
- Pass an overriding ObjectGrid XML configuration to the ObjectGridManager.connect(String
catalogServerEndpoints, 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");
- 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 uses the entity configuration on the server.
However, if you use subset entities on the client, you must 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;
}
@Entity(name="ServerPerson")
class ClientPerson
{
@Id @Basic(alias="ssn") String socialSecurityNumber;
String surname;
}
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 data grid with an entity.xml file 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 file achieves 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 classless, then the client provides an overriding entity descriptor XML file. This entity descriptor XML file contains an override to the class file reference.
Referencing the schema
If your application is 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 data 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.