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