You can use EntityManager API 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.
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>
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>
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");
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");
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.
@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.
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.