Entity metadata descriptor XML file

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

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

mapSchemas element

Each querySchema element has one mapSchemas element that contains one or more mapSchema elements.

mapSchema element

A mapSchema element defines the type of object that is stored in a BackingMap and instructions on how to access the data.
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.

relationship element

A relationship element defines the relationship between two BackingMaps and the attributes in the valueClass attribute that bind the relationship.
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.
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.

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.
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.
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.
Attributes
<basic
(1)			name="attributeName"
(2)			column="columnName"
/>

id element

the id element is used for a key attribute mapping.
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>