com.ibm.websphere.sdo.mediator.ejb

Class MediatorFactory

java.lang.Object

com.ibm.websphere.sdo.mediator.ejb.MediatorFactory

public class MediatorFactory
extends java.lang.Object

The factory class used for creating an instance of Mediator. An EJB Mediator is an extension of the J2EE EJB programming model that allows an ejb query to return a DataGraph and to perform updates based on graph's change log.

The EJB Mediator takes as an argument an array of EJB query statements. Each query defines an DataObject type. The SELECT clause lists the cmp fields or expressions to return into the data object. The dataypes supported are

   java primitive and wrapper types
   String, BigDecimal, BigInteger, byte[]
   java.sql.Date, Time and Timestamp
   java.util.Date, Calendar

The WHERE clause specifies the filtering conditions.

The first query in the array specifies either an EJB abstract schema name or a query parameter that designates a collection of EJBs.

The FROM clause of the other queries specifies an ejb relationship which is used to navigate to the related schema and to create DataObject references. The relationship may be single or many valued. The query statements must form a hierarchy of schema types and a schema can be referenced in one and only one query FROM clause.

Each FROM clause can only specify one element. Joins are not allowed.

In order to the DataObject to be updateable, the query must retrieve all the primary fields of the EJB and if the EJB is defined with one or more optimistic predicate fields, at least one of these fields must be retrieved. It is the caller's responsibility to ensure that the optimistic predicate field is incremented or updated appropriately. DataObject attributes derived from a query expression such as e.salary+e.bonus as total_pay or e.dept.name as deptName or a method call are not updateable.

Aggregate expressions (e.g. SUM, AVG, COUNT ) can be used in subselects.

The following compound ejb query is valid

                select d.deptno from Dept as d
                select e.empid from in(d.emps) as e
 

The following query is invalid

                select d.deptno from Dept as d
                select p.projno from in(e.projects) as p
                select e.empid from in(d.emps) as e
 

because the correlation id "e" in the second query has not been defined.

Collection valued input argument allowed in FROM clause. If ?1 refers to a collection of Dept EJBs then the following query is valid

                select d.deptno from (Dept)?1 as d
 

This example shows multiple paths in the type hierarchy.

        String[] query = 
      {
       "select d.deptno, d.name from Dept as d where d.deptno between ?1 and ?2 ",
       "select e.empid,e.name,e.salary+e.bonus as totalPay from in(d.emps)as  e", 
       "select p.projid from in(d.projects) as p   ", 
       "select t.taskid, t.cost from in(p.tasks)as t where t.cost > ?3" 
      }; 

        Object[] parms = new Object{ new Integer(40), new Integer(50), new Double(60.0) };
        Object[] realParms = new Object{ new Integer(70), new Integer(80), new Double(90.0) };
 
        Mediator m = MediatorFactory.getInstance().createMediator( query, parms);
        DataObject root = m.getGraph(realParms);
        // update the DataGraph and then ...
        m.applyChanges(root);

The parms passed on the create call are used during query execution, unless getGraph call supplies another set of input parameters. In that case parameters passed in getGraph call are used. However the type of the input parameters passed during the getGraph call need to be the same as the ones passed during the create mediator call.

The mediator can return dynamic DataObjects or an EClass argument can be specified for a user defined DataObject schema. The user defined DataObject schema must have class names corresponding to EJB abstract schema names or a map argument can be used to specify the mapping between EJB ASN names and unqualified EClass names.

The mediator supports three patterns of DataObject containment.

The ROOT_CONTAINS_ALL pattern is a pattern in which a dummy graph root object contains all other EJB related DataObjects. EJB relationships map to noncontainment references between DataObjects.

For user defined graph schema a pattern of NO_DUMMY_ROOT requires that the first EJB query return a single result and all DataObject other than the graph root are contained by the EJB relationship specifed the query FROM clause.

ROOT_CONTAIN_SOME pattern is a hybrid pattern in which a dummy graph root object exists and each DataObject is contained either by the dummy root or the EJB relationship specified in the query.

If the user specified schema contains properties that are not retrieved by the query, the properties will be unset.

All factory and mediator methods must be invoked in the context of either a user transaction or a container transaction.

Field Summary

Fields

Modifier and Type	Field and Description
static int	NO_DUMMY_ROOT There is no dummy root DataObject.
static int	ROOT_CONTAINS_ALL There is a dummy root DataObject that contains all other DataObjects.
static int	ROOT_CONTAINS_SOME There is a dummy root DataObject.

Method Summary

Methods

Modifier and Type	Method and Description
Mediator	createMediator(java.lang.String[] ejbQuery, java.lang.Object[] parms) Creates an ejb mediator using an array EJB query statements.
Mediator	createMediator(java.lang.String[] ejbQuery, java.lang.Object[] parms, org.eclipse.emf.ecore.EClass schema) Creates an ejb mediator from an array of EJB query statements.
Mediator	createMediator(java.lang.String[] ejbQuery, java.lang.Object[] parms, org.eclipse.emf.ecore.EClass schema, java.util.Map asnToSDONameMap, int pattern) Creates an ejb mediator from an array of EJB query statements.
static MediatorFactory	getInstance() Obtain the factory class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROOT_CONTAINS_ALL

public static final int ROOT_CONTAINS_ALL

There is a dummy root DataObject that contains all other DataObjects. The EClass name for the root can be any valid name in case of static DataObjects. However in the dynamic DataObjects the EClass name for the root is "DataGraphRoot".

See Also:

Constant Field Values

ROOT_CONTAINS_SOME

public static final int ROOT_CONTAINS_SOME

There is a dummy root DataObject. An EJB relationship referenced in the query can be defined as an contained reference. If not,then the dummy root MUST be defined to contain the DataObject.

See Also:

Constant Field Values

NO_DUMMY_ROOT

public static final int NO_DUMMY_ROOT

There is no dummy root DataObject. The DataGraph root refers to the DataObject returned by the first query statement. Since a DataGraph can have only one root instance, if the qurey returns zero or more than one record, an exception will be thrown.

See Also:

Constant Field Values

Method Detail

createMediator

public Mediator createMediator(java.lang.String[] ejbQuery,
                      java.lang.Object[] parms)
                        throws QueryException

Creates an ejb mediator using an array EJB query statements. The mediator will return dynamic DataObjects. Caller must be in server environment.

Parameters:

ejbQuery - The array of ejb query statements.

parms - Values for query input arguments.

Returns:

The EJB Mediator.

Throws:

QueryException - Invalid query. Message contains details.

createMediator

public Mediator createMediator(java.lang.String[] ejbQuery,
                      java.lang.Object[] parms,
                      org.eclipse.emf.ecore.EClass schema)
                        throws QueryException

Creates an ejb mediator from an array of EJB query statements. This call is used when using statically generated DataObjects. The EClass names of the DataObjects must match the EJB ASN. Caller must be in server environment.

Parameters:

ejbQuery - The array of EJB query statements.

parms - Values for query input arguments.

schema - Provides the EMF schema class of the root DataObject.

Returns:

The EJB Mediator.

Throws:

QueryException - Invalid query. Message contains details.

createMediator

public Mediator createMediator(java.lang.String[] ejbQuery,
                      java.lang.Object[] parms,
                      org.eclipse.emf.ecore.EClass schema,
                      java.util.Map asnToSDONameMap,
                      int pattern)
                        throws QueryException

Creates an ejb mediator from an array of EJB query statements. This call is used when using static DataObjects. Caller must be in server environment.

Parameters:

ejbQuery - Array of EJB query statements.

parms - Values for query input arguments.

schema - Provides the EMF schema class of the root DataObject.

asnTOSDONameMap - The map between the EJB asn name and the unqualifed EClass class name.

pattern - DataObject containment pattern specifid by ROOT_CONTAINS_SOME, NO_DUMMY_ROOT or ROOT_CONTAINS_ALL.

Throws:

QueryException - Invalid query. Message contains details.

getInstance

public static MediatorFactory getInstance()

Obtain the factory class.

Returns:

The factory class.