The entity metadata descriptor file is an XML file that
is used to define an entity schema for WebSphere® eXtreme Scale. Define all of the
entity metadata in the XML file, or define the entity metadata as
annotations on the entity Java™ class
file. The primary use is for entities that cannot use Java annotations.
Use XML configuration to create entity metadata that is
based on the XML file. When used in conjunction with annotation, some
of the attributes that are defined in the XML configuration override
the corresponding annotations. If you can override an element, the
override is explicitly in the following sections. See emd.xsd file for an example of the entity metadata
descriptor XML file.
id element
The id element implies that the
attribute is a key. At a minimum, at least one id element must be
specified. You can specify multiple id keys for use as a compound
key.
Attributes- name
- Specifies the name of the attribute. The attribute must exist
in the Java file.
- alias
- Specifies the element alias. The alias value is overridden if
used in conjunction with an annotated entity.
basic element
The basic element implies that
the attribute is a primitive type or wrappers to primitive types:
- java.lang.String
- java.math.BigInteger
- java.math.BigDecimal
- java.util.Date
- java.util.Calendar
- java.sql.Date
- java.sql.Time
- java.sql.Timestamp
- byte[]
- Byte[]
- char[]
- Character[]
- Java Platform,
Standard Edition Version 5
enum
It is not necessary to specify any attribute as basic. The basic
element attributes are automatically configured using reflection.
id-class element
The id_class element specifies
a compound key class, which helps to find entities with compound keys.
Attributes- class-name
- Specifies the class name, which is an id-class, to use with the
id-class element.
transient
The transient element implies that
it is ignored and not processed. It also can be overridden if used
in conjunction with annotated entities.
Attributes- name
- Specifies the name of the attribute, which is ignored.
version
The transient element implies that
it is ignored and not processed. It also can be overridden if used
in conjunction with annotated entities.
Attributes- name
- Specifies the name of the attribute, which is ignored.
property element
Use the property element to
add properties to plug-ins. The name of the property must correspond
to a set method on the class referenced by the containing bean.
- Number of occurrences: Zero to many
- Child element: None
Attributes- name
- Specifies the name of the property. The value that is assigned
to this attribute must correspond to a set method on the class that
is provided as the className attribute on the containing bean. For
example, if you set the className attribute of the bean to com.ibm.MyPlugin,
and the name of the property that is provided is size,
the com.ibm.MyPlugin class must have a setSize
method. (Required)
- type
- Specifies the type of the property. The type is passed to the
set method that is identified by the name attribute. The valid values
are the Java primitives, the
java.lang counterparts, and java.lang.String. The name and type attributes
must correspond to a method signature on the className attribute of
the bean. For example, if you set the name as size and
the type as int, a setSize(int) method must
exist on the class that is specified as the className attribute for
the bean. (Required)
- value
- Specifies the value of the property. This value is converted to
the type that is specified by the type attribute, and is then used
as a parameter in the call to the set method that is identified by
the name and type attributes. The value of this attribute is not validated
in any way. (Required)
- description
- Describes the property. (Optional)
<bean
(1) name="name"
(2) type="java.lang.String" | "boolean" | "java.lang.Boolean" | "int" |
"java.lang.Integer" | "double" | "java.lang.Double" | "byte" |
"java.lang.Byte" | "short" | "java.lang.Short" | "long" |
"java.lang.Long" | "float" | "java.lang.Float" | "char" |
"java.lang.Character"
(3) value="value"
(4) description="description"
/>
In the following example, the
companyGridProperty.xml file
is used to demonstrate how to add a property element to a bean. In
this example, a property with the name maxSize and type int is added
to an evictor. The com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor
Evictor has a method signature that matches the setMaxSize(int) method.
An integer value of 499 is passed to the setMaxSize(int) method on
the com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor class.
<?xml version="1.0" encoding="UTF-8"?>
<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="CompanyGrid">
<backingMap name="Customer"
pluginCollectionRef="customerPlugins"/>
</objectGrid>
</objectGrids>
<backingMapPluginCollections>
<backingMapPluginCollection id="customerPlugins">
<bean id="Evictor"
className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor>
<property name="maxSize" type="int" value="449"
description="The maximum size of the LRU Evictor"/>
</bean>
</backingMapPluginCollection>
</backingMapPluginCollections>
</objectGridConfig>
The following code sample
demonstrates the programmatic approach to achieving the same configuration
as the
companyGridProperty.xml file in the preceding
example.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
BackingMap customerMap = companyGrid.defineMap("Customer");
LRUEvictor lruEvictor = new com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor();
// if the XML file is used instead,
// the property that was added would cause the following call to occur
lruEvictor.setMaxSize(449);
customerMap.setEvictor(lruEvictor);
backingMapPluginsCollections element
The backingMapPluginsCollections
element is a container for all the backingMapPluginCollection elements.
In the
companyGridProperty.xml file in the preceding
section, the backingMapPluginCollections element contains one backingMapPluginCollection
element with the ID
customerPlugins.
- Number of occurrences: Zero to one
- Child element: backingMapPluginCollection element
backingMapPluginCollection element
The backingMapPluginCollection
element defines the BackingMap plug-ins, and is identified by the
id attribute.
Specify the pluginCollectionRef attribute to reference the plug-ins.
When configuring several BackingMaps plug-ins similarly, each BackingMap
can reference the same backingMapPluginCollection element.
- Number of occurrences: Zero to many
- Child element: bean element
Attributes- id
- Identifies the backingMapPluginCollection, and is referenced by
the pluginCollectionRef attribute of the backingMap element. Each
ID must be unique. If the value of a pluginCollectionRef attribute
does not match the ID of one backingMapPluginCollection element, XML
validation fails. Any number of backingMap elements can reference
a single backingMapPluginCollection element. (Required)
<backingMapPluginCollection
(1) id="id"
/>
In the following example, the
companyGridCollection.xml file
is used to demonstrate how to use the backingMapPluginCollection element.
In this file, the Customer BackingMap uses the customerPlugins backingMapPluginCollection
to configure the Customer BackingMap with an LRUEvictor. The Item
and OrderLine BackingMaps reference the collection2 backingMapPluginCollection.
These BackingMaps each have an LFUEvictor set.
<?xml version="1.0" encoding="UTF-8"?>
<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="CompanyGrid">
<backingMap name="Customer"
pluginCollectionRef="customerPlugins"/>
<backingMap name="Item" pluginCollectionRef="collection2"/>
<backingMap name="OrderLine"
pluginCollectionRef="collection2"/>
<backingMap name="Order"/>
</objectGrid>
</objectGrids>
<backingMapPluginCollections>
<backingMapPluginCollection id="customerPlugins">
<bean id="Evictor"
className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor/>
</backingMapPluginCollection>
<backingMapPluginCollection id="collection2">
<bean id="Evictor"
className="com.ibm.websphere.objectgrid.plugins.builtins.LFUEvictor/>
<bean id="OptimisticCallback"
className="com.ibm.websphere.samples.objectgrid.EmployeeOptimisticCallBackImpl"/>
</backingMapPluginCollection>
</backingMapPluginCollections>
</objectGridConfig>
The following code sample
demonstrates the programmatic approach to achieving the same configuration
as the
companyGridCollection.xml file in the
preceding example.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
BackingMap customerMap = companyGrid .defineMap("Customer");
LRUEvictor customerEvictor = new LRUEvictor();
customerMap.setEvictor(customerEvictor);
BackingMap itemMap = companyGrid.defineMap("Item");
LFUEvictor itemEvictor = new LFUEvictor();
itemMap.setEvictor(itemEvictor);
BackingMap orderLineMap = companyGrid.defineMap("OrderLine");
LFUEvictor orderLineEvictor = new LFUEvictor();
orderLineMap.setEvictor(orderLineEvictor);
BackingMap orderMap = companyGrid.defineMap("Order");
querySchema element
The querySchema element
defines relationships between BackingMaps and identifies the type
of object in each map. This information is used by ObjectQuery to
translate query language strings into map access calls.
For more information, see Configuring an ObjectQuery schema.- Number of occurrences: Zero to one
- Child element: mapSchemas element, relationships element
mapSchemas element
Each querySchema element
has one mapSchemas element that contains one or more mapSchema elements.
- Number of occurrences: One
- Child element: mapSchema element
mapSchema element
A mapSchema element defines
the type of object that is stored in a BackingMap and instructions
on how to access the data.
- Number of occurrences: One or more
- Child element: None
Attributes- mapName
- Specifies the name of the BackingMap to add to the schema. (Required)
- valueClass
- Specifies the type of object that is stored in the value portion
of the BackingMap. (Required)
- primaryKeyField
- Specifies the name of the primary key attribute in the valueClass
attribute. The primary key must also be stored in the key portion
of the BackingMap. (Optional)
- accessType
- Identifies how the query engine introspects and accesses the persistent
data in the valueClass object instances. If you set the value to FIELD,
the class fields are introspected and added to the schema. If the
value is PROPERTY, the attributes that are
associated with get and is methods are used. The default value is PROPERTY.
(Optional)
<mapSchema
(1) mapName="backingMapName"
(2) valueClass="com.mycompany.OrderBean"
(3) primaryKeyField="orderId"
(4) accessType="PROPERTY" | "FIELD"
/>
In the following example, the
companyGridQuerySchemaAttr.xml file
is used to demonstrate a sample mapSchema configuration.
<?xml version="1.0" encoding="UTF-8"?>
<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="CompanyGrid">
<backingMap name="Order"/>
<backingMap name="Customer"/>
<querySchema>
<mapSchemas>
<mapSchema mapName="Order"
valueClass="com.mycompany.OrderBean"
primaryKeyField="orderNumber"
accessType="FIELD"/>
<mapSchema mapName="Customer"
valueClass="com.mycompany.CustomerBean"
primaryKeyField="id"
accessType="FIELD"/>
</mapSchemas>
</querySchema>
</objectGrid>
</objectGrids>
</objectGridConfig>
The following code sample
demonstrates the programmatic approach to achieving the same configuration
as the
companyGridQuerySchemaAttr.xml file in
the preceding example.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
companyGrid.defineMap("Order");
companyGrid.defineMap("Customer");
// Define the schema
QueryConfig queryCfg = new QueryConfig();
queryCfg.addQueryMapping(new QueryMapping(
"Order", OrderBean.class.getName(), "orderNumber", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryMapping(new QueryMapping(
"Customer", CustomerBean.class.getName(), "id", QueryMapping.FIELD_ACCESS));
companyGrid.setQueryConfig(queryCfg);
relationships element
Each querySchema element
has zero or one relationships element that contains one or more relationship
elements.
- Number of occurrences: Zero or one
- Child element: relationship element
relationship element
A relationship element
defines the relationship between two BackingMaps and the attributes
in the valueClass attribute that bind the relationship.
- Number of occurrences: One or more
- Child element: None
Attributes- source
- Specifies the name of the valueClass of the source side of a relationship.
(Required)
- target
- Specifies the name of the valueClass of the target side of a relationship.
(Required)
- relationField
- Specifies the name of the attribute in the source valueClass that
refers to the target. (Required)
- invRelationField
- Specifies the name of the attribute in the target valueClass that
refers to the source. If this attribute is not specified, the relationship
is one directional. (Optional)
<mapSchema
(1) source="com.mycompany.OrderBean"
(2) target="com.mycompany.CustomerBean"
(3) relationField="customer"
(4) invRelationField="orders"
/>
In the following example, the
companyGridQuerySchemaWithRelationshipAttr.xml file
is used to demonstrate a sample mapSchema configuration that includes
a bi-directional relationship.
<?xml version="1.0" encoding="UTF-8"?>
<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="CompanyGrid">
<backingMap name="Order"/>
<backingMap name="Customer"/>
<querySchema>
<mapSchemas>
<mapSchema mapName="Order"
valueClass="com.mycompany.OrderBean"
primaryKeyField="orderNumber"
accessType="FIELD"/>
<mapSchema mapName="Customer"
valueClass="com.mycompany.CustomerBean"
primaryKeyField="id"
accessType="FIELD"/>
</mapSchemas>
<relationships>
<relationship
source="com.mycompany.OrderBean"
target="com.mycompany.CustomerBean"
relationField="customer"/>
invRelationField="orders"/>
</relationships>
</querySchema>
</objectGrid>
</objectGrids>
</objectGridConfig>
The following code sample
demonstrates the programmatic approach to achieving the same configuration
as the
companyGridQuerySchemaWithRelationshipAttr.xml file
in the preceding example.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
companyGrid.defineMap("Order");
companyGrid.defineMap("Customer");
// Define the schema
QueryConfig queryCfg = new QueryConfig();
queryCfg.addQueryMapping(new QueryMapping(
"Order", OrderBean.class.getName(), "orderNumber", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryMapping(new QueryMapping(
"Customer", CustomerBean.class.getName(), "id", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryRelationship(new QueryRelationship(
OrderBean.class.getName(), CustomerBean.class.getName(), "customer", "orders"));
companyGrid.setQueryConfig(queryCfg);
timeBasedDBUpdate element
A timeBasedDBUpdate
element defines a configuration for a time-based database updater.
A timeBasedDBUpdate element contains information on how often to retrieve
newly inserted and updated records from the database using Java Persistence API (JPA), and
how to update the data in the corresponding ObjectGrid maps.
- Number of occurrences: Zero or one
- Child element: None
Attributes- entityClass
- Specifies the entity class name used to interact with the JPA
provider. The entity class name is used to retrieve JPA entities using
entity queries. (Required)
- persistenceUnitName
- Specifies the JPA persistence unit name for creating a JPA entity
manager factory. The default value is the name of the first persistence
unit defined in the persistence.xml file. (Optional)
- mode
- Specifies the time-based database update mode. By default, the
time-based database update mode is set to INVALIDATE_ONLY. An INVALIDATE_ONLY
type indicates to invalidate the entries in the ObjectGrid map if
the corresponding records in the database have changed. An UPDATE_ONLY
type indicates to update the existing entries in the ObjectGrid map
with the latest values from the database. However, all the newly inserted
records to the database are ignored. An INSERT_UPDATE type indicates
to update the existing entries in the ObjectGrid map with the latest
values from the database. Also, all the newly inserted records to
the database are inserted into the ObjectGrid map. (Optional)
- timestampField
- Specifies the name of the time stamp field. A time stamp field
value is used to identify the time or sequence when a database back-end
record was last updated. (Optional)
- jpaPropertyFactory
- Identifies the JPAPropertyFactory implementation class name or
spring bean. The com.ibm.websphere.objectgrid.jpa.JPAPropertyFactory
interface is used to plug in persistence property map to override
the default JPA properties. Use spring framework beans if additional
attributes need to be set on the JPAPropertyFactory instance. See Integrating with Spring framework for more information. (Optional)
<timeBasedDBUpdate
(1) persistenceUnitName="SamplePU"
(2) mode="INVALIDATE_ONLY" | "UPDATE_ONLY" | "INSERT_UPDATE"
(3) timestampField="TIMESTAMP"
(4) entityClass="entity class"
(5) jpaPropertyFactory="JPA property factory class" | "{spring}bean name"
/>
streamQuerySet element
The streamQuerySet element
is the top-level element for defining a stream query set.
- Number of occurrences: Zero to many
- Child element: stream element, view element
stream element
The stream element represents
a stream to the stream query engine. Each attribute of the stream
element corresponds to a method on the StreamMetadata interface.
- Number of occurrences: One to many
- Child element: basic element
Attributes- name
- Specifies the name of the stream. Validation fails if this attribute
is not specified. (Required)
- valueClass
- Specifies the class type of the value that is stored in the stream
ObjectMap. The class type is used to convert the object to the stream
events and to generate an SQL statement if the statement is not provided.
(Required)
- sql
- Specifies the SQL statement of the stream. If this property is
not provided, a stream SQL is generated by reflecting the attributes
or accessor methods on the valueClass attribute or by using the tuple
attribues of the entity metadata. (Optional)
- access
- Specifies the type to access the attributes of the value class.
If you set the value to FIELD, the attributes
are directly retrieved from the fields using Java reflection. Otherwise, accessor methods
are used to read the attributes. The default value is PROPERTY.
(Optional)
<stream
(1) name="streamName"
(2) valueClass="streamMapClassType"
(3) sql="streamSQL create stream stockQuote
keyed by t ( transactionvolume INTEGER, price DECIMAL (9,2),
issue VARCHAR(100) );"
(4) access="PROPERTY" | "FIELD"
/>
view element
The view element represents a
stream query view. Each stream element corresponds to a method on
the ViewMetadata interface.
- Number of occurrences: One to many
- Child element: basic element, id element
Attributes- name
- Specifies the name of the view. Validation fails if this attribute
is not specified. (Required)
- sql
- Specifies the SQL of the stream, which defines the view transformation.
Validation fails if this attribute is not specified. (Required)
- valueClass
- Specifies the class type of the value that is stored in this view
of the ObjectMap. The class type is used to convert view events into
the correct tuple format that is compatible with this class type.
If the class type is not provided, a default format following the
column definitions in the Stream Processing Technology Structured
Query Language (SPTSQL) is used. If an entity metadata is defined
for this view map, this attribute should not be used. The entity metadata
is used instead. (Optional)
- access
- Specifies the type to access the attributes of the value class.
If you set the access type to FIELD, the column
values are directly set to the fields using Java reflection. Otherwise, accessor methods
are used to set the attributes. The default value is PROPERTY.
(Optional)
<view
(1) name="viewName"
(2) valueClass="viewMapValueClass"
(3) sql="viewSQL CREATE VIEW last5MinuteAvgPrice AS
SELECT issue, avg(price) as totalVolume
FROM (SELECT * FROM stockQuote FETCH LATEST 5 MINUTES) group by issue;"/>
(4) access="PROPERTY" | "FIELD"
/>
basic element
The basic element is used to
define a mapping from the attribute name in the value class or entity
metadata to the column that is defined in the SPTSQL.
- Number of occurrences: Zero to many
- Child element: None
Attributes<basic
(1) name="attributeName"
(2) column="columnName"
/>
id element
the id element is used for a key
attribute mapping.
- Number of occurrences: Zero to many
- Child element: None
Attributes<id
(1) name="idName"
(2) column="columnName"
/>
In the following example, the
StreamQueryApp2.xml file
is used to demonstrate how to configure the attributes of a streamQuerySet.
The stream query set _stockQuoteSQS_ has one stream and one view.
Both the stream and view define its name, valueClass, sql, and access
type respectively. The stream also defines a basic element, which
specifies that the volume attribute in the StockQuote class is mapped
to the SQL column transactionvolume that is defined in the SQL statement.
<?xml version="1.0" encoding="UTF-8"?>
<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="og1">
<backingMap name="stockQuote" readOnly="false" copyKey="true"
streamRef="stockQuote"/>
<backingMap name="last5MinuteAvgPrice" readOnly="false" copyKey="false"
viewRef="last5MinuteAvgPrice"/>
<streamQuerySet name="stockQuoteSQS">
<stream
name="stockQuote"
valueClass="com.ibm.ws.objectgrid.streamquery.sample.guide.StockQuote"
sql="create stream stockQuote
keyed by t ( transactionvolume INTEGER, price DECIMAL (9,2),
issue VARCHAR(100) );"
access="FIELD">
<basic name="volume" column="transactionvolume"/>
</stream>
<view
name="last5MinuteAvgPrice"
valueClass="com.ibm.ws.objectgrid.streamquery.sample.guide.AveragePrice"
sql="CREATE VIEW last5MinuteAvgPrice AS SELECT issue, avg(price) as avgPrice
FROM (SELECT * FROM stockQuote FETCH LATEST 5 MINUTES) group by issue;"
access="FIELD"
</view>
</streamQuerySet>
</objectGrid>
</objectGrids>
</objectGridConfig>