IBM developerWorks: Wikis - WebSphere eXtreme Scale V6.1 User Guide

See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in with your developerWorks ID, you can leave comments and feedback for the development team.

The ObjectGrid entity metadata descriptor file is an XML file that is used to define an entity schema for an ObjectGrid. All of the entity metadata can be explicitly defined in the XML file, or 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 Entity metadata XML schema for details on the formatting of an entity metadata descriptor XML file.

Element description

All elements, and attributes and child elements for each element follow:

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

The element id, 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.

Element: basic:
- Attributes:
  - name (required): Specifies the name of the attribute in the class.
  - alias: Specifies the element alias. The alias value is overriden, if used in conjunction with an annotated entity.
  - fetch: Specifies the fetch type. Valid values are, LAZY | EAGER.

The element Basic, implies that the attribute is a primitive type or wrappers to primitive types, such as,
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[] and Java SE 5 enum ².
It is not necessary to specify any attribute as basic. The basic attributes are automatically configured using reflection.

Element: id-class:
- Attributes:
  - class-name: Specifies the class name, which is an id-class, to be used for this entity.

The id_class element is useful for specifying a compound key class, which helps to find entities with compound keys.

Element: transient:
- Attributes:
  - name: Specifies the name of the attribute, which is ignored.

The transient element, implies that it is ignored and not processed. It also can be overriden if used in conjunction with annotated entities.

Element: version*
- Attributes:
  - name:

Element: cascade-type** Child Elements:
- - cascade-all: Cascades the all operation to associations.
  - cascade-persist: Cascades the persist operation to associations.
  - cascade-remove: Cascades the remove operation to associations.
  - cascade-merge: Currently not used.
  - cascade-refresh: Currently not used.

Element: one-to-one:
- Attributes:
  - name: Specifies the name of the attribute in the class, which has a one-to-one relationship.
  - alias: Specifies a name alias.
  - target-entity: Specifies the association class that it refers to. This value is a fully-qualified class name.
  - fetch: Specifies the fetch type. Valid values are, LAZY | EAGER.
  - mapped-by: Specifies the field that owns the relationship. The mapped-by element is only specified on the inverse (non-owning) side of the association.
  - id:Identifies the association as key
- Child Elements:
  - cascade: cascade-type

Element: one-to-many:
- Attributes:
  - name (required): Specifies the name of the attribute in the class.
  - alias: Specifies a name alias.
  - target-entity: Refers to the association class that it refers to. This value is a fully-qualified class name.
  - fetch: Specifies the fetch type. Valid values are, LAZY | EAGER.

- - mapped-by: Specifies the field that owns the relationship. The mapped-by element is only specified on the inverse (non-owning) side of the association.
- Child Elements:
  - order-by
  - cascade: cascade-type

Element: many-to-one:
- Attributes:
  - name (required): Specifies the name of the attribute in the class.
  - alias: Specifies a name alias.
  - target-entity: Refers to the class that this attribute refers to. This value is a fully-qualified class name.
  - fetch: Specifies the fetch type. Valid values are, LAZY | EAGER.
  - id:Identifies the association as key.
- Child Elements:
  - cascade: cascade-type

Element: many-to-many:
- Attributes:
  - name (required): Specifies the name of the attribute in the class.
  - alias: Specifies a name alias.
  - target-entity: Refers to the class that this attribute refers to. This value is a fully-qualified class name.
  - fetch: Specifies the fetch type. Valid values are, LAZY | EAGER.
  - mapped-by: Specifies the field that owns the relationship. The mapped-by element is only specified on the inverse (non-owning) side of the association.
- Child Elements:
  - order-by
  - cascade: cascade-type

Element: attributes:
- Attributes:
- Child Elements:

Element: Entity:
- Attributes:
  - name (required): Specifies the name of the attribute in the class.
  - class-name: Specifies the fully-qualified class name.
  - access: Specifies the access type. Valid values are, PROPERTY|FIELD.
  - schemaRoot: Specifies that this entity is the schemaRoot and is used as a parent class for partitioned data.
- Child Elements:
  - description: Specifies a description.
  - id-class
  - attributes

Element: entity-mappings:
- Attributes:
- Child Elements:
  - description : Specifies a description.
  - entity

Element: entity-listener:
- Attributes:
  - class-name (required): Specifies the name of the listener class.
- Child Elements:
  - PrePersist
  - PostPersist
  - PreRemove
  - PostRemove
  - PreUpdate
  - PostUpdate
  - PostLoad

Element: PrePersist:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PrePersist event.

Element: PostPersist:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PostPersist event.

Element: PreRemove:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PreRemove event.

Element: PostRemove:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PostRemove event.

Element: PreUpdate:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PreUpdate event.

Element: PostUpdate:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PostUpdate event.

Element: PostLoad:
- Attributes:
  - method-name (required): Specifies the lifecycle callback method for the PostLoad event.

Examples

Some XML configuration examples are provided, using Java classes from Basic EntityManager tutorial step 1. The classes are duplicated here and do not contain any annotations.

Order.java

package com.myCompany;
public class Order
{
    String orderNumber;
    Date date;
    String customerName;
    String itemName;
    int quantity;
    double price;
}

For the Order class, a minimal XML configuration follows. Note, all attributes are not included, and by default, all attributes are treated as "basic".

entity.xml - minimum

?xml version="1.0" encoding="UTF-8"?>

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

<description>"Entity Mapping description for class Order"</description>
    <entity class-name="com.myCompany.Order" name="Order" access="FIELD">
	   <description>"This is the Order class"</description>
		<attributes>
			<id name="orderNumber"/>
           	</attributes>
    </entity>

</entity-mappings>

Here all elements are included, but the price is marked as transient. Even though the attribute price is not transient in the Java class, this XML overrides it.

entity.xml

?xml version="1.0" encoding="UTF-8"?>

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

<description>"Entity Mapping description for class Order"</description>
    <entity class-name="com.myCompany.Order" name="Order" access="FIELD">
	   <description>"This is an Order class"</description>
		<attributes>
			<id name="orderNumber"/>
			<basic name="date"/>
                        <basic name="customerName"/>
                        <basic name="itemName"/>
                        <basic name="quantity"/>
                        <transient name="price"/>
           	</attributes>
    </entity>

</entity-mappings>

Further expanding based on Basic EntityManager tutorial step 2. Here the configuration with associations.

Customer.java

public class Customer
{
    String id;
    String firstName;
    String surname;
    String address;
    String phoneNumber;
}

This is very similar to the old Order object in the previous step. The new Order object follows:

Order.java

public class Order
{
    String orderNumber;
    Date date;
    Customer customer;
    String itemName;
    int quantity;
    double price;
}

The corresponding XML configuration file follows:

entity.xml

<?xml version="1.0" encoding="UTF-8"?>

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


	<description>"Entity Mapping description"</description>

	<entity class-name="com.myCompany.Customer" name="Customer" access="FIELD">
		<description>"This is the Customer class"</description>
		<attributes>
			<id name="id" />
			<basic name="firstName" />
			<basic name="surname" />
			<basic name="address" />
			<basic name="phoneNumber" />
		</attributes>
	</entity>
	
	<entity class-name="com.myCompany.Item" name="Item" access="FIELD">
		<description>"Item"</description>
		<attributes>
			<id name="id" />
			<basic name="description" />
			<basic name="quantityOnHand" />
			<basic name="price" />
		</attributes>
	</entity>	

	<entity class-name="com.myCompany.OrderLine" name="OrderLine" access="FIELD">
		<description>"Order Line"</description>
		<attributes>
			<id name="lineNumber" />
			<basic name="quantity" />
			<basic name="price" />
			<many-to-one name="order" id="true" target-entity="com.myCompany.Order">
				<cascade><cascade-persist/></cascade>
			</many-to-one>
			<one-to-one name="item" target-entity="com.myCompany.Item">
				<cascade><cascade-persist/></cascade>
			</one-to-one>
		</attributes>
	</entity>
	
	<entity class-name="com.myCompany.Order" name="Order" access="FIELD">
		<description>"An Order class"</description>
		<attributes>
			<id name="orderNumber" />
			<basic name="date" />
			<one-to-many name="lines" target-entity="com.myCompany.OrderLine" mapped-by="order">
				<order-by>lineNumber ASC</order-by>
				<cascade><cascade-all /></cascade>
			</one-to-many>
			<one-to-one name="customer" target-entity="com.myCompany.Customer">
				<cascade>
					<cascade-persist />
				</cascade>
			</one-to-one>
		</attributes>
	</entity>

	


</entity-mappings>

¹ java.util.Calendar is available in 6.1.0.5 and later
² Java SE 5 enum types are available in 6.1.0.3 and later

Element description

Examples

Wiki Disclaimer and License

© Copyright IBM Corporation 2007,2009. All Rights Reserved.