org.objectweb.jorm.api
Interface PMapper

public interface PMapper

The PMapper interface defines a JORM mapper as an object that mainly maintains the set of JORM classes that it maps on a particular DS. It relies on JCA as a means to access a DS. It enables to access to the meta-information associated to JORM classes at runtime. Before being able to request the load of meta-information at mapping time, the mapper should have been assigned a mapping name, a meta-information manager, as well as a parser.

Author:

P. D?chamboux

Field Summary

static java.lang.String	PBINDINGAPPENDER
static java.lang.String	PCLASSMAPPINGAPPENDER

Method Summary

void	closeConnection(java.lang.Object conn) Closes the given connection which has been allocated previously using getConnection.
java.lang.String	cn2mn(java.lang.String cn) Constructs a "mapped name" starting from a JORM class name.
java.lang.Object	getConnection() Allocates a connection for accessing the underlying DS.
java.lang.Object	getConnection(java.lang.Object ctxt) Allocates a connection for accessing the underlying DS knowing additional context information.
java.lang.Object	getConnectionFactory() Returns the connection factory associated to this mapper.
java.lang.String	getMapperName() The name yielded by this method defines what kind of PMapper is used on a particular DS.
java.lang.String	getMappingName() It retrieves the name of the mapping that is instanciated through this mapper.
Manager	getMetaInfoManager() It retrieves a meta-information Manager that may used by a parser in order to load the meta-information associated to JORM classes mapped within this PMapper.
PTypeSpace	getPTypeSpace() It returns a PTypeSpace that may be used to create PType associated to JORM classes mapped within this PMapper.
PClassMapping	lookup(java.lang.String classname) It looks for the PClassMapping object associated to a JORM class within this PMapper.
void	map(java.lang.Object conn, PClassMapping pcm, byte cleanup) It registers a PClassMapping associated to a particular JORM class within this PMapper.
void	map(java.lang.Object conn, PClassMapping pcm, byte cleanup, boolean loadmeta) It registers a PClassMapping associated to a particular JORM class within this PMapper.
void	map(PClassMapping pcm, byte cleanup) It registers a PClassMapping associated to a particular JORM class within this PMapper.
void	setConnectionFactory(java.lang.Object cf) Assigns a connection factory to this mapper.
void	setMapperName(java.lang.String mappername) It assigns the name of the mapper that is instanciated.
void	setMappingName(java.lang.String mappingname) It assigns the name of the mapping that is instanciated.
void	setMetaInfoManager(Manager m) It assigns a meta-information Manager that may used by a parser in order to load the meta-information associated to JORM classes mapped within this PMapper.
void	setParser(Parser p) It assigns a Parser that may be used to create the meta-information associated to JORM classes mapped within this PMapper.
void	setPTypeSpace(PTypeSpace pts) It assigns a PTypeSpace that may be used to create PType associated to JORM classes mapped within this PMapper.
void	unmap(java.lang.String classname) It unmaps a particular JORM class within this PMapper.

Field Detail

PCLASSMAPPINGAPPENDER

public static final java.lang.String PCLASSMAPPINGAPPENDER

PBINDINGAPPENDER

public static final java.lang.String PBINDINGAPPENDER

Method Detail

closeConnection

public void closeConnection(java.lang.Object conn)
                     throws PException

Closes the given connection which has been allocated previously using getConnection.

Parameters:

conn - The concerned connection.

cn2mn

public java.lang.String cn2mn(java.lang.String cn)

Constructs a "mapped name" starting from a JORM class name. For example, "foo" class name produces ".foo", while "p1.p2.foo" produces "p1.p2..foo".

Parameters:

cn - The JORM class name.

getConnection

public java.lang.Object getConnection()
                               throws PException

Allocates a connection for accessing the underlying DS.

getConnection

public java.lang.Object getConnection(java.lang.Object ctxt)
                               throws PException

Allocates a connection for accessing the underlying DS knowing additional context information.

Parameters:

ctxt - Context information used to allocate the connection.

getMapperName

public java.lang.String getMapperName()

The name yielded by this method defines what kind of PMapper is used on a particular DS.

Returns:

The name defining the PMapper kind.

getMappingName

public java.lang.String getMappingName()

It retrieves the name of the mapping that is instanciated through this mapper.

Returns:

The name of the mapping.

lookup

public PClassMapping lookup(java.lang.String classname)

It looks for the PClassMapping object associated to a JORM class within this PMapper.

Returns:

The PClassMapping that maps the corresponding class, or null if none exists

map

public void map(PClassMapping pcm,
                byte cleanup)
         throws PException

It registers a PClassMapping associated to a particular JORM class within this PMapper. It initializes the storage structures if necessary. It previously removes them if the "dsrem" flag is set. If the mapper is ready to manage the meta-information, it is loaded for this JORM class.

Parameters:

pcm - The class mapping to add to this mapper.

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

Throws:

PExceptionIO - It is raised when an I/O problem occurs within the underlying DS.

PExceptionProtocol - It is raised when a problem occurs during initialisation of the class mapping.

PExceptionTyping - It is raised when a typing problem occurs during initialisation of the class mapping.

map

public void map(java.lang.Object conn,
                PClassMapping pcm,
                byte cleanup)
         throws PException

It registers a PClassMapping associated to a particular JORM class within this PMapper. It initializes the storage structures if necessary. It previously removes them if the "dsrem" flag is set. If the mapper is ready to manage the meta-information, it is loaded for this JORM class.

Parameters:

conn - The connection to access to the underlying DS.

pcm - The class mapping to add to this mapper.

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

Throws:

PExceptionIO - It is raised when an I/O problem occurs within the underlying DS.

PExceptionProtocol - It is raised when a problem occurs during initialisation of the class mapping.

PExceptionTyping - It is raised when a typing problem occurs during initialisation of the class mapping.

map

public void map(java.lang.Object conn,
                PClassMapping pcm,
                byte cleanup,
                boolean loadmeta)
         throws PException

It registers a PClassMapping associated to a particular JORM class within this PMapper. It initializes the storage structures if necessary. It previously removes them if the "dsrem" flag is set. It also loads the meta-information related to this class if the "loadmeta" flag is set.

Parameters:

conn - The connection to access to the underlying DS.

pcm - The class mapping to add to this mapper.

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

loadmeta - It specifies that meta-information should be loaded for this class to map.

Throws:

PExceptionIO - It is raised when an I/O problem occurs within the underlying DS.

PExceptionProtocol - It is raised when a problem occurs during initialisation of the class mapping.

PExceptionTyping - It is raised when a typing problem occurs during initialisation of the class mapping.

setConnectionFactory

public void setConnectionFactory(java.lang.Object cf)
                          throws PException

Assigns a connection factory to this mapper.

Throws:

PExceptionProtocol - It is raised if a connection factory has already been assigned.

getConnectionFactory

public java.lang.Object getConnectionFactory()

Returns the connection factory associated to this mapper.

setMapperName

public void setMapperName(java.lang.String mappername)

It assigns the name of the mapper that is instanciated. It is mandatory to assign it at mapper initialization as the load of meta-information depends on it.

Parameters:

mappingname - The name of the maping as defined within the XML JORM definition files.

setMappingName

public void setMappingName(java.lang.String mappingname)

It assigns the name of the mapping that is instanciated. It is mandatory to assign it at mapper initialization as the load of meta-information depends on it.

Parameters:

mappingname - The name of the maping as defined within the XML JORM definition files.

getMetaInfoManager

public Manager getMetaInfoManager()

It retrieves a meta-information Manager that may used by a parser in order to load the meta-information associated to JORM classes mapped within this PMapper.

Returns:

The meta-information Manager assigned.

setMetaInfoManager

public void setMetaInfoManager(Manager m)

It assigns a meta-information Manager that may used by a parser in order to load the meta-information associated to JORM classes mapped within this PMapper.

Parameters:

m - The meta-information Manager to be assigned.

setParser

public void setParser(Parser p)

It assigns a Parser that may be used to create the meta-information associated to JORM classes mapped within this PMapper.

Parameters:

p - The Parser to be assigned.

setPTypeSpace

public void setPTypeSpace(PTypeSpace pts)

It assigns a PTypeSpace that may be used to create PType associated to JORM classes mapped within this PMapper.

Parameters:

pts - The PTypeSpace to be assigned.

getPTypeSpace

public PTypeSpace getPTypeSpace()

It returns a PTypeSpace that may be used to create PType associated to JORM classes mapped within this PMapper.

unmap

public void unmap(java.lang.String classname)
           throws PException

It unmaps a particular JORM class within this PMapper.

Parameters:

classname - The name of the JORM class to be unmapped.