org.objectweb.jorm.api
Interface PBinding

All Known Subinterfaces:
PBindingCtrl

public interface PBinding

The PBinding interface defines the behaviour of binding objects used in order to control the I/Os between a data store instance and its associated memory instance.

Author:
R. Basset, P. Dechamboux

Field Summary
static byte ACTION_BIND
           
static byte ACTION_EXIST
           
static byte ACTION_EXPORT
           
static byte ACTION_READ
           
static byte ACTION_UNBIND
           
static byte ACTION_UNEXPORT
           
static byte ACTION_WRITE
           
static byte LIFECYCLE_ACTIVEFORIO
          The PBinding can perform read and write to the data store: It has a PName to reach an existing data store instance.
static byte LIFECYCLE_DELTOWRITE
          On the next write call, the PBinding will delete the data store instance associated to its PName, and release its PName: It has a PName to reach the related data store instance.
static byte LIFECYCLE_ERROR
          This is not a real state for a PBinding.
static byte LIFECYCLE_NEWTOWRITE
          The PBinding has a PName to reach the data store, but the corresponding data store instance does not exist yet.
static byte LIFECYCLE_NOTBOUND
          The PBinding does not have any PName to reach a data store instance.
 
Method Summary
 void bind(PName pn)
          It assigns a DSI represented by the PName passed as a parameter to this PBinding.
 boolean exist(java.lang.Object conn)
          It verifies if the DSI attached to this binding exists within the DS.
 PName export(java.lang.Object conn)
          It creates a new PName for this binding, the binding state is normally changed to LIFECYCLE_NEWTOWRITE, and the link to a data store instance if it existed is removed.
 PName export(java.lang.Object conn, java.lang.Object hints)
          It creates a new PName for this binding, the binding state is normally changed to LIFECYCLE_NEWTOWRITE, and the link to a data store instance if it existed is removed.
 PClassMapping getPClassMapping()
          It gives access to the PClassMapping which manages this binding.
 PName getPName()
          It gives access to the PName, which designate a particular DSI, associated to this binding.
 byte getStatus()
          It yields the current status associated with this PBinding.
 void init(PClassMapping pcm)
          It initialises a PBinding.
 void read(java.lang.Object conn, PAccessor pa)
          It reads the data store instance designated by the PName of this binding and transfers each attribute value to the accessor object.
 void read(java.lang.Object conn, PAccessor pa, java.lang.Object txctx)
          It reads the data store instance designated by the PName of this binding and transfers each attribute value to the accessor object.
 void unbind()
          It remove the association between a PName and a PBinding.
 void unexport(java.lang.Object conn)
          It prepares this PBinding to remove the data store instance from the data store.
 void write(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 this binding.
 

Field Detail

ACTION_BIND

public static final byte ACTION_BIND
See Also:
Constant Field Values

ACTION_UNBIND

public static final byte ACTION_UNBIND
See Also:
Constant Field Values

ACTION_EXPORT

public static final byte ACTION_EXPORT
See Also:
Constant Field Values

ACTION_UNEXPORT

public static final byte ACTION_UNEXPORT
See Also:
Constant Field Values

ACTION_EXIST

public static final byte ACTION_EXIST
See Also:
Constant Field Values

ACTION_READ

public static final byte ACTION_READ
See Also:
Constant Field Values

ACTION_WRITE

public static final byte ACTION_WRITE
See Also:
Constant Field Values

LIFECYCLE_ACTIVEFORIO

public static final byte LIFECYCLE_ACTIVEFORIO
The PBinding can perform read and write to the data store: It has a PName to reach an existing data store instance.

See Also:
Constant Field Values

LIFECYCLE_DELTOWRITE

public static final byte LIFECYCLE_DELTOWRITE
On the next write call, the PBinding will delete the data store instance associated to its PName, and release its PName: It has a PName to reach the related data store instance.

See Also:
Constant Field Values

LIFECYCLE_NEWTOWRITE

public static final byte LIFECYCLE_NEWTOWRITE
The PBinding has a PName to reach the data store, but the corresponding data store instance does not exist yet. It is thus ready to create the new data store instance.

See Also:
Constant Field Values

LIFECYCLE_NOTBOUND

public static final byte LIFECYCLE_NOTBOUND
The PBinding does not have any PName to reach a data store instance.

See Also:
Constant Field Values

LIFECYCLE_ERROR

public static final byte LIFECYCLE_ERROR
This is not a real state for a PBinding. It is used when a transition leads to a protocol error.

See Also:
Constant Field Values
Method Detail

bind

public void bind(PName pn)
          throws PException
It assigns a DSI represented by the PName passed as a parameter to this PBinding. This thus changes the link to the data store instance if one has been already assigned. The state changed to LIFECYCLE_ACTIVEFORIO.

Parameters:
pn - The new PName to associate to this binding. This name must belong to the binder associated to this binding.
Throws:
PExceptionNaming - It is raised when there is a problem for the associated binder to manage this PName.
PException

exist

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

Parameters:
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

export

public PName export(java.lang.Object conn)
             throws PException
It creates a new PName for this binding, the binding state is normally changed to LIFECYCLE_NEWTOWRITE, and the link to a data store instance if it existed is removed.

Parameters:
conn - The connection that can be used to refer to the DS.
Returns:
The new PName assigned to this binding.
Throws:
PExceptionIO - It is raised when a problem occured while accessing to the DS.
PExceptionNaming - It is raised when the associated binder does not manage to create a new name.
PExceptionProtocol - It is raised when it is called with a state different from the following ones: LIFECYCLE_ACTIVEFORIO LIFECYCLE_DELTOWRITE LIFECYCLE_NEWTOWRITE
PException

export

public PName export(java.lang.Object conn,
                    java.lang.Object hints)
             throws PException
It creates a new PName for this binding, the binding state is normally changed to LIFECYCLE_NEWTOWRITE, and the link to a data store instance if it existed is removed.

Parameters:
conn - The connection that can be used to refer to the DS.
hints - Any information relevant for name creation.
Returns:
The new PName assigned to this binding.
Throws:
PExceptionIO - It is raised when a problem occured while accessing to the DS.
PExceptionNaming - It is raised when the associated binder does not manage to create a new name.
PExceptionProtocol - It is raised when it is called with a state different from the following ones: LIFECYCLE_ACTIVEFORIO LIFECYCLE_DELTOWRITE LIFECYCLE_NEWTOWRITE
PException

getPClassMapping

public PClassMapping getPClassMapping()
It gives access to the PClassMapping which manages this binding.

Returns:
The PClassMapping which creates this binding.

getPName

public PName getPName()
It gives access to the PName, which designate a particular DSI, associated to this binding. It returns null if the binding has not been given a PName using a bind or export method.

Returns:
The PName associated to this binding.

getStatus

public byte getStatus()
It yields the current status associated with this PBinding.

Returns:
The corresponding status.

init

public void init(PClassMapping pcm)
          throws PException
It initialises a PBinding.

Parameters:
pcm - The PBinding to initialise.
Throws:
PExceptionProtocol - This PBinding cannot be managed by this PClassMapping.
PException

read

public void read(java.lang.Object conn,
                 PAccessor pa)
          throws PException
It reads the data store instance designated by the PName of this 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(java.lang.Object conn,
                 PAccessor pa,
                 java.lang.Object txctx)
          throws PException
It reads the data store instance designated by the PName of this 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

unbind

public void unbind()
            throws PException
It remove the association between a PName and a PBinding. No more PName is associated with this binding (it has no more link with a DSI).

Throws:
PExceptionNaming - It is raised when there is a problem for the associated binder to manage this PName.
PException

unexport

public void unexport(java.lang.Object conn)
              throws PException
It prepares this PBinding to remove the data store instance from the data store. In order to actually remove this DSI, a call to write must follow.

Parameters:
conn - The connection that can be used to refer to the DS.
Throws:
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_DELTOWRITE LIFECYCLE_NEWTOWRITE
PException

write

public void write(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 this 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