org.objectweb.jorm.api
Interface PClassMapping


public interface PClassMapping

The PClassMapping interface defines the behaviour of objects that contain all information required to map a JORM class. It is a PBinder but mainly delegates this behaviour to a nested PBinder that it must reference. It allows the creation or deletion of the persistent structures required to map this class within a particular hosting data store. It also holds references to naming contexts associated to reference fields, as well as to PClassMapping associated to generic class instances of relevant fields.

Author:
P. Dechamboux

Nested Class Summary
static interface PClassMapping.ReferenceConfigurator
           
 
Field Summary
static byte CLEANUP_DONOTHING
          It tells that a cleanup is required for a JORM class with nothing to do on existing data or hosting structures.
static byte CLEANUP_REMOVEALL
          It tells that a cleanup is required for a JORM class with the removal of existing data as well as hosting structures.
static byte CLEANUP_REMOVEDATA
          It tells that a cleanup is required for a JORM class with the removal of only existing data.
static byte CREATE_STRUCTURE_IF_NEEDED
          It permits to specify to create the if it does not already exist.
 
Method Summary
 void addAssociation(PClassMapping targetClass, int[] indexes)
          Adds an association [pclassmapping-> table of indexes] to the association table.
 void classDefined(PMappingStructuresManager pmsm)
          Register the class in the cluster.
 void configureRefFields(PClassMapping.ReferenceConfigurator rc)
          It permits to assign the PNameCoder of all the reference fields of the persitent class.
 PBinding createPBinding()
          It creates a new PBinding.
 boolean exist(PBinding pb, java.lang.Object conn)
          It verifies if the DSI attached to a binding exists within the DS.
 java.util.HashMap getAssociationTable()
          Returns the map storing association between a pclassmapping on which is done a query and a table of int representing the fields numbers to select in the tuple to fill in the field of an instance of the class.
 java.lang.String getClassName()
          It retrieves the name of the class referenced by this PClassMapping.
 PNameCoder getClassPNameCoder()
          It returns the PNameCoder to use for the class.
 PName getDecodedPName(TupleCollection tc, PName pname, boolean intermediaryTuple)
          It returns the PName valid in the "good" binder according to the tuple collection.
 PClassMapping getGenClassMapping()
          It gives access to the PClassMapping associated to the element of a generic class whose type is a generic class.
 PClassMapping getGenClassMapping(java.lang.String fn)
          It gives access to the PClassMapping associated to a field whose type is a generic class.
 int[] getIndexesTable(PClassMapping targetClass)
          Returns the indexes table associated to the pclassmapping targetClass, null if not contained in the map.
 MetaObject getMetaInfo()
          It returns the Class/GenClass object representing the meta-information associated to the JORM class/generic class whose mapping is defined by this PClassMapping.
 PBinder getPBinder()
          It yields the PBinder associated to this PClassMapping.
 PMapper getPMapper()
          It gives access to the mapper that has mapped the associated JORM class as defined by this PClassMapping.
 PNameCoder getPNameCoder()
          It returns the naming context that manages the references contained by the generic class instance whose mapping is defined by this PClassMapping.
 PNameCoder getPNameCoder(java.lang.String fn)
          It returns the naming context that manages the reference associated to a field whose type is a JORM class.
 java.util.Iterator getPNameIterator(java.lang.Object conn)
          Deprecated. use getPNameIterator(Object, boolean, boolean)
 PNameIterator getPNameIterator(java.lang.Object conn, boolean withSubType, boolean prefetching, java.lang.Object txctx)
          It returns an iterator over all pname of persitent objects availlable in this class.
 java.lang.String getProjectName()
          It retrieves the project name.
 PType getPType()
          Retrieves the PType of this mapped JORM class.
 PClassMapping[] getSubPCMs()
          Gets the list of the sub PClassMappings.
 void init(PMappingCallback mapper, MetaObject metaclass)
          It intialises the class mapping.
 void init(PMappingStructuresManager pmsm)
          Register the mapping structures and the dependencies.
 boolean isConform(java.lang.String mappername)
          It specifies if the given kind of PMapper is supported by this PClassMapping.
 boolean match(java.lang.Object obj, boolean intermediaryTuple)
          Returns true if the object obj matches (exactly) this class, else it returns false.
 void read(PBinding pb, java.lang.Object conn, PAccessor pa)
          It reads the data store instance designated by the PName of a binding and transfers each attribute value to the accessor object.
 void read(PBinding pb, java.lang.Object conn, PAccessor pa, java.lang.Object txctx)
          It reads the data store instance designated by the PName of a binding and transfers each attribute value to the accessor object.
 void read(PBinding pb, java.lang.Object conn, PAccessor pa, java.lang.Object txctx, boolean forUpdate)
           
 PName resolve(java.lang.Object conn, PName pname)
          It returns the PName valid in the "good" binder.
 void setPBinder(PBinder pb)
          It assigns the PBinder associated to this PClassMapping.
 void write(PBinding pb, java.lang.Object conn, PAccessor pa)
          It transfers each attribute value taken from the PAccessor object to the data store instance designated by the PName associated with a binding.
 

Field Detail

CLEANUP_REMOVEALL

public static final byte CLEANUP_REMOVEALL
It tells that a cleanup is required for a JORM class with the removal of existing data as well as hosting structures.

See Also:
Constant Field Values

CLEANUP_REMOVEDATA

public static final byte CLEANUP_REMOVEDATA
It tells that a cleanup is required for a JORM class with the removal of only existing data.

See Also:
Constant Field Values

CREATE_STRUCTURE_IF_NEEDED

public static final byte CREATE_STRUCTURE_IF_NEEDED
It permits to specify to create the if it does not already exist. If the table exist then nothing is done.

See Also:
Constant Field Values

CLEANUP_DONOTHING

public static final byte CLEANUP_DONOTHING
It tells that a cleanup is required for a JORM class with nothing to do on existing data or hosting structures.

See Also:
Constant Field Values
Method Detail

createPBinding

public PBinding createPBinding()
                        throws PException
It creates a new PBinding.

Returns:
The new PBinding with lifecycle state set to LIFECYCLE_NOTBOUND.
Throws:
PException

init

public void init(PMappingCallback mapper,
                 MetaObject metaclass)
          throws PException
It intialises the class mapping. It especially assigns a mapper as well as a meta-object describing either a class or a generic class. It also defines all type information related to this class mapping.

Parameters:
mapper - The mapper to be assigned to this class mapping.
metaclass - The meta-object describing the associated class. It may be null.
Throws:
PException

init

public void init(PMappingStructuresManager pmsm)
          throws PException
Register the mapping structures and the dependencies.

Parameters:
pmsm - The PMappingStructuresManager in which mapping structures are registered.
Throws:
PException

classDefined

public void classDefined(PMappingStructuresManager pmsm)
                  throws PException
Register the class in the cluster.

Parameters:
pmsm -
Throws:
PException

getClassName

public java.lang.String getClassName()
It retrieves the name of the class referenced by this PClassMapping. should be the same as the one get when calling "getPBinder().getPType().getJormName()" if the PType exists, that is a fully qualified name.

Returns:
The name of this class.

getProjectName

public java.lang.String getProjectName()
It retrieves the project name.


getGenClassMapping

public PClassMapping getGenClassMapping()
                                 throws java.lang.UnsupportedOperationException
It gives access to the PClassMapping associated to the element of a generic class whose type is a generic class.

Returns:
The PClassMapping of the generic class instance.
Throws:
java.lang.UnsupportedOperationException - Raised when the method is not supported by the PClassMapping.

getGenClassMapping

public PClassMapping getGenClassMapping(java.lang.String fn)
                                 throws java.lang.UnsupportedOperationException
It gives access to the PClassMapping associated to a field whose type is a generic class.

Parameters:
fn - The name of the generic class field.
Returns:
The PClassMapping of the generic class instance.
Throws:
java.lang.UnsupportedOperationException - Raised when the method is not supported by the PClassMapping.

getMetaInfo

public MetaObject getMetaInfo()
It returns the Class/GenClass object representing the meta-information associated to the JORM class/generic class whose mapping is defined by this PClassMapping. It may be null if not requested at mapping time.

Returns:
The Class/GenClass meta-object or null.
See Also:
PMapper.map(org.objectweb.jorm.api.PClassMapping)

getPBinder

public PBinder getPBinder()
It yields the PBinder associated to this PClassMapping. As a PBinder itself, this PClassMapping delegates this behaviour to this PBinder.

Returns:
The PBinder associated to this PClassMapping.

getPMapper

public PMapper getPMapper()
It gives access to the mapper that has mapped the associated JORM class as defined by this PClassMapping.

Returns:
The associated PMapper.

getPNameCoder

public PNameCoder getPNameCoder()
                         throws java.lang.UnsupportedOperationException
It returns the naming context that manages the references contained by the generic class instance whose mapping is defined by this PClassMapping.

Returns:
The naming context that manages references contained by a generic class instance.
Throws:
java.lang.UnsupportedOperationException - It is raised when this PClassMapping does not map a generic class instance, or when the elements of this generic class instance are not references.

getPNameCoder

public PNameCoder getPNameCoder(java.lang.String fn)
                         throws java.lang.UnsupportedOperationException
It returns the naming context that manages the reference associated to a field whose type is a JORM class.

Returns:
The naming context that manages the reference defined by a field.
Throws:
java.lang.UnsupportedOperationException - It is raised when no naming context is associated to the corresponding field.

getClassPNameCoder

public PNameCoder getClassPNameCoder()
It returns the PNameCoder to use for the class. This PNamingContext manages also the sub classes.


getPNameIterator

public PNameIterator getPNameIterator(java.lang.Object conn,
                                      boolean withSubType,
                                      boolean prefetching,
                                      java.lang.Object txctx)
                               throws PException
It returns an iterator over all pname of persitent objects availlable in this class. When you use the returned iterator you must leave the connection opened.

Parameters:
conn - is the connection which permits to access to the support
withSubType - indicates if the subclass instances must be included into the iterator
prefetching - indicates if prefething must be activated during the query on the persistent support.
txctx - The transaction context that can be used in case of prefetching.
Returns:
the iterator over PName objects
Throws:
PExceptionProtocol - A problem occured during the request that is not related to I/O.
PExceptionIO - A problem occured during the request.
PException

getPNameIterator

public java.util.Iterator getPNameIterator(java.lang.Object conn)
                                    throws PException
Deprecated. use getPNameIterator(Object, boolean, boolean)

Throws:
PException

getPType

public PType getPType()
Retrieves the PType of this mapped JORM class.

Returns:
The PTYpe.

getSubPCMs

public PClassMapping[] getSubPCMs()
                           throws PException
Gets the list of the sub PClassMappings.

Returns:
the list of sub pcms or null if the class has no child
Throws:
PException - if the PType is not defined for the PClassMapping

isConform

public boolean isConform(java.lang.String mappername)
It specifies if the given kind of PMapper is supported by this PClassMapping.

Parameters:
mappername - The name defining the PMapper kind.
Returns:
true if this kind of mapper is supported.

setPBinder

public void setPBinder(PBinder pb)
                throws PException
It assigns the PBinder associated to this PClassMapping. As a PBinder itself, this PClassMapping delegates this behaviour to this PBinder.

Parameters:
pb - The PBinder associated to this PClassMapping.
Throws:
PExceptionTyping - It is raised when the structure of the the name that identifies the DSI for the PClassMapping is not supported by this PBinder that should be connected to this PClassMapping.
PException

configureRefFields

public void configureRefFields(PClassMapping.ReferenceConfigurator rc)
                        throws PException,
                               java.lang.UnsupportedOperationException
It permits to assign the PNameCoder of all the reference fields of the persitent class. The implementation of this method must call both method 'getPNameCoder' and 'isCodingOnly' of the specified PNCGetter. for each field which is a reference (to a class or a GenClass).

Parameters:
rc - is the callback object which knows the PNameCoder to use.
Throws:
PExceptionTyping - It is raised when the structure of the the names that reference the DSI stored within the generic class instance is not supported by the naming context returned by the callBack method.
PException
java.lang.UnsupportedOperationException

exist

public boolean exist(PBinding pb,
                     java.lang.Object conn)
              throws PException
It verifies if the DSI attached to a binding exists within the DS.

Parameters:
pb - is the PBinding instance
conn - The connection that can be used to refer to the DS.
Returns:
It returns true if the DSI exists.
Throws:
PExceptionIO - It is raised when a problem occured while accessing to the DS.
PExceptionNaming - It is raised when there is a problem for the associated binder to manage this PName.
PExceptionProtocol - It is raised when it is called with a state different from the following ones: LIFECYCLE_ACTIVEFORIO
PException

read

public void read(PBinding pb,
                 java.lang.Object conn,
                 PAccessor pa)
          throws PException
It reads the data store instance designated by the PName of a binding and transfers each attribute value to the accessor object.

Parameters:
conn - The connection that can be used to refer to the DS.
pa - The PAccessor used to access memory variables.
Throws:
PExceptionIO - It is raised when a problem occured while accessing to the DS.
PExceptionNaming - It is raised when there is a problem for the associated binder to manage this PName.
PExceptionProtocol - It is raised when it is called with a state different from the following ones: LIFECYCLE_ACTIVEFORIO
PException

read

public void read(PBinding pb,
                 java.lang.Object conn,
                 PAccessor pa,
                 java.lang.Object txctx)
          throws PException
It reads the data store instance designated by the PName of a binding and transfers each attribute value to the accessor object. This read method should be used when prefetching is requested.

Parameters:
conn - The connection that can be used to refer to the DS.
pa - The PAccessor used to access memory variables.
txctx - The transaction context that can be used in case of prefetching.
Throws:
PExceptionIO - It is raised when a problem occured while accessing to the DS.
PExceptionNaming - It is raised when there is a problem for the associated binder to manage this PName.
PExceptionProtocol - It is raised when it is called with a state different from the following ones: LIFECYCLE_ACTIVEFORIO
PException

read

public void read(PBinding pb,
                 java.lang.Object conn,
                 PAccessor pa,
                 java.lang.Object txctx,
                 boolean forUpdate)
          throws PException
Throws:
PException

write

public void write(PBinding pb,
                  java.lang.Object conn,
                  PAccessor pa)
           throws PException
It transfers each attribute value taken from the PAccessor object to the data store instance designated by the PName associated with a binding.

Parameters:
conn - The connection that can be used to refer to the DS.
pa - The PAccessor used to access memory variables.
Throws:
PExceptionIO - It is raised when a problem occured while accessing to the DS.
PExceptionNaming - It is raised when there is a problem for the associated binder to manage this PName.
PExceptionProtocol - It is raised when it is called with a state different from the following ones: LIFECYCLE_ACTIVEFORIO LIFECYCLE_NEWTOWRITE LIFECYCLE_DELTOWRITE
PExceptionTyping - It is raised when a reference to be stored has a type incompatible with the respective field definition.
PException

getAssociationTable

public java.util.HashMap getAssociationTable()
Returns the map storing association between a pclassmapping on which is done a query and a table of int representing the fields numbers to select in the tuple to fill in the field of an instance of the class. Example: Let's say we are instanciating D objects A(pk1, pk2, f1), B(f2), C(f3, f4), D(f5) _________A_______ B C____ D The prefetch query on A will be: Select pk1, pk2, f1, f2, f3, f4, f5 For D, the index table will be [1,2,3,5,6,7] because we need only pk1, pk2, f1, f3, f4, f5 to instanciate D objects The prefetch query on C will be: Select pk1, pk2, f1, f3, f4, f5 For D, the index table will be [1,2,3,4,5,6] because we need all the fields to instanciate D objects Then, the map returned for D will be: [ pclassmapping of A, [1,2,3,5,6,7]] [ pclassmapping of C, [1,2,3,4,5,6]]


addAssociation

public void addAssociation(PClassMapping targetClass,
                           int[] indexes)
Adds an association [pclassmapping-> table of indexes] to the association table. If the map already has an entry corresponding to the pclassmapping, this entry is replaced by the new one.

Parameters:
targetClass - the PClassMapping on which is done the query
indexes - a table of int composed of the indexes of fields required

getIndexesTable

public int[] getIndexesTable(PClassMapping targetClass)
Returns the indexes table associated to the pclassmapping targetClass, null if not contained in the map.


resolve

public PName resolve(java.lang.Object conn,
                     PName pname)
              throws PException
It returns the PName valid in the "good" binder.

Parameters:
conn - The connection that can be used to refer to the DS.
Throws:
PException

match

public boolean match(java.lang.Object obj,
                     boolean intermediaryTuple)
              throws PException
Returns true if the object obj matches (exactly) this class, else it returns false.

Throws:
PException

getDecodedPName

public PName getDecodedPName(TupleCollection tc,
                             PName pname,
                             boolean intermediaryTuple)
                      throws PException
It returns the PName valid in the "good" binder according to the tuple collection.

Throws:
PException