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. D?chamboux

Inner 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	configureRefFields(PClassMapping.ReferenceConfigurator rc) It permits to assign the PNamingContext of all the reference fields of the persitent class.
PBinding	createPBinding() It creates a new PBinding.
java.lang.String	getClassName() It retrieves the name of the class referenced by this PClassMapping.
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.
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.
java.util.Iterator	getPNameIterator(java.lang.Object conn) It returns an iterator over all pname of persitent objects availlable in this class.
PNamingContext	getPNameManager() It returns the naming context that manages the references contained by the generic class instance whose mapping is defined by this PClassMapping.
PNamingContext	getPNameManager(java.lang.String fn) It returns the naming context that manages the reference associated to a field whose type is a JORM class.
void	init(PMapper mapper, MetaObject metaclass) It intialises the class mapping.
void	initMappingStructures(java.lang.Object conn, byte cleanup) It initializes the persistent structures required to map a JORM class within a particular Data Store.
boolean	isConform(java.lang.String mappername) It specifies if the given kind of PMapper is supported by this PClassMapping.
void	removeMappingStructures(java.lang.Object conn, boolean contentonly) It removes the persistent structures required to map a JORM class within a particular Data Store.
void	setGenClassMapping(PClassMapping pcm) It assigns the GenClassMapping used to manage the reference hold by a field whose type is a JORM class.
void	setGenClassMapping(java.lang.String fn, PClassMapping pcm) It assigns the GenClassMapping used to manage the reference hold by a field whose type is a JORM class.
void	setPBinder(PBinder pb) It assigns the PBinder associated to this PClassMapping.
void	setPNamingContext(PNamingContext pnc, boolean codingonly) It assigns the PNamingContext used to manage the references hold by a generic class instance whose mapping is described by this PClassMapping.
void	setPNamingContext(java.lang.String fn, PNamingContext pnc, boolean codingonly) It assigns the PNamingContext used to manage the reference hold by a field whose type is a JORM class.

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.

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.

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.

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.

Method Detail

createPBinding

public PBinding createPBinding()
                        throws PException

It creates a new PBinding.

Returns:

The new PBinding with lifecycle state set to LIFECYCLE_NOTBOUND.

init

public void init(PMapper 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.

initMappingStructures

public void initMappingStructures(java.lang.Object conn,
                                  byte cleanup)
                           throws PException

It initializes the persistent structures required to map a JORM class within a particular Data Store. This method has no effect when the structures already exist, or when the structure must not be manipulated via JORM (e.g., case of a legacy DS). The deletion of these structures may be requested before initializing them.

Parameters:

conn - The connection that can be used to access the DS.

cleanup - Tells if structures and/or data should be removed at initialization time.

Throws:

PExceptionProtocol - A problem occured during initialisation that is not related to I/O.

PExceptionIO - A problem occured during the initialization of the DS.

removeMappingStructures

public void removeMappingStructures(java.lang.Object conn,
                                    boolean contentonly)
                             throws PException

It removes the persistent structures required to map a JORM class within a particular Data Store. This method has no effect when the structures do not exist, or when the structure must not be manipulated via JORM (e.g., case of a legacy DS).

Parameters:

conn - The connection that can be used to access the DS.

contentonly - It specifies if only the content of the persistent structures should be removed (it only removes data).

Throws:

PExceptionProtocol - A problem occured during the deletion that is not related to I/O.

PExceptionIO - A problem occured during the deletion of the DS.

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.

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.

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.

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.

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, byte)

getPNameManager

public PNamingContext getPNameManager()
                               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.

getPNameManager

public PNamingContext getPNameManager(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.

getPNameIterator

public java.util.Iterator getPNameIterator(java.lang.Object conn)
                                    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

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.

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.

setGenClassMapping

public void setGenClassMapping(PClassMapping pcm)
                        throws java.lang.UnsupportedOperationException

It assigns the GenClassMapping used to manage the reference hold by a field whose type is a JORM class.

setGenClassMapping

public void setGenClassMapping(java.lang.String fn,
                               PClassMapping pcm)
                        throws java.lang.UnsupportedOperationException

It assigns the GenClassMapping used to manage the reference hold by a field whose type is a JORM class.

setPNamingContext

public void setPNamingContext(PNamingContext pnc,
                              boolean codingonly)
                       throws PException,
                              java.lang.UnsupportedOperationException

It assigns the PNamingContext used to manage the references hold by a generic class instance whose mapping is described by this PClassMapping. It should verify that the name structure for this reference is supported by the corresponding naming context.

Parameters:

pnc - The PNamingContext to be associated to this generic class PClassMapping for managing its reference elements.

codingonly - It specifies that when using this naming context for managing a reference, it only executes coding or both coding and export/resolve phase.

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 this naming context.

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.

setPNamingContext

public void setPNamingContext(java.lang.String fn,
                              PNamingContext pnc,
                              boolean codingonly)
                       throws PException,
                              java.lang.UnsupportedOperationException

It assigns the PNamingContext used to manage the reference hold by a field whose type is a JORM class. It should verify that the name structure for this reference is supported by the corresponding naming context.

Parameters:

fn - The name of the involved field.

pnc - The PNamingContext to be associated to this field for managing the reference it may hold.

codingonly - It specifies that when using this naming context for managing a reference, it only executes coding or both coding and export/resolve phase.

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 this naming context.

java.lang.UnsupportedOperationException - It is raised when no naming context is associated to the corresponding field.

configureRefFields

public void configureRefFields(PClassMapping.ReferenceConfigurator rc)
                        throws PException,
                               java.lang.UnsupportedOperationException

It permits to assign the PNamingContext of all the reference fields of the persitent class. The implementation of this method must call both method 'getPNameManager' and 'isCodingOnly' of the specified PNCGetter. for each field which is a reference (to a class or a GenClass).

Parameters:

pncg - is the callback object which knows the PNamingContext 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.