Ontology Wrapper
\
OntologyWrapper
traits

\OntologyWrapper\traitsStatus

Status trait

The main purpose of this trait is to add status management to classes, this is done by adding a bitfield {@link $mStatus} data member and a set of methods that handle this bitfield.

This trait defines the common methods for managing the bitfield data member and handles the following flags:

  • {@link kFLAG_STATE_INITED}: This flag indicates that the object is ready to be used and is set by the {@link isInited()} method; if the flag is not set, it means that the object is not functional.
  • {@link kFLAG_STATE_DIRTY}: This flag is set whenever the object's offsets are modified and it can be managed by the {@link isDirty()} method. For persistent objects it is an indication that the object should be updated; if the flag is not set, it means that the object persistent properties are in the same state as when it was loaded from a persistent store.
  • {@link kFLAG_STATE_COMMITTED}: This flag is set whenever the object is either loaded from or stored in a persistent store and can be managed by the {@link isCommitted()} method. It is an indication that the object is persistent; if the flag is not set, it means that the object was not loaded from or stored in a persistent store.
  • {@link kFLAG_STATE_ALIAS}: This flag indicates an encoded state and can be managed by the {@link isAlias()} method, which means that some object offsets have been encoded and need to be decoded before the object is saved in a persistent store or effectively used. This state is often associated to the network transmission of objects: some data types must be converted prior to be sent over the network; if the flag is not set, it means that the object can be saved in a persistent store or serialised for being transmitted on the network.

All the flag accessor methods are protected, since they provide access to the internal workings of the object, if you need to provide status information you should do so by using these methods in a public interface.

Summary

Methods
Properties
Constants
committed()
No public properties found
No constants found
statusReset()
isInited()
isDirty()
isCommitted()
isAlias()
manageBitField()
No protected properties found
N/A
No private methods found
$mStatus
N/A

Properties

$mStatus

$mStatus : int

Status flags.

This data member holds the status flags in a bitfield value

Type

int

Methods

committed()

committed() : boolean

Check if object is committed

This method will return TRUE if the object is committed.

Returns

boolean —

TRUE is committed.

statusReset()

statusReset()

Reset status

This method can be used to reset the status, it will set it to {@link kFLAG_DEFAULT}.

This is generally at the end of the constructor after having modified offsets to set the status to an idle state.

isInited()

isInited(mixed $theState) : boolean

Manage inited status

This method can be used to get or set the object's inited state.

An object becomes inited when it has all the required elements necessary for it to be correctly used or persistently stored. Such a state indicates that at least the minimum required information was initialised in the object.

The counterpart state indicates that the object still lacks the necessary elements to successfully operate the object.

This method operates by setting or clearing the {@link kFLAG_STATE_INITED} flag.

The method features a single parameter:

  • NULL: The method will return the object's inited state.
  • TRUE: The method will set the object's inited state.
  • FALSE: The method will reset the object's inited state.

In all cases the method will return the state after it was eventually modified.

Parameters

mixed $theState

TRUE, FALSE or

                                            <tt>NULL</tt>.

Returns

boolean —

TRUE inited, FALSE idle.

isDirty()

isDirty(mixed $theState) : boolean

Manage dirty status

This method can be used to get or set the object's dirty state.

A dirty object is one that was modified since the last time this state was probed. In general, this state should be set whenever the persistent properties of the object are modified.

In this class we automatically set this state when setting or unsetting offsets.

The method features a single parameter:

  • NULL: The method will return the object's dirty state.
  • TRUE: The method will set the object's dirty state.
  • FALSE: The method will reset the object's dirty state.

In all cases the method will return the state after it was eventually modified.

Parameters

mixed $theState

TRUE, FALSE or

                                            <tt>NULL</tt>.

Returns

boolean —

TRUE dirty, FALSE clean.

isCommitted()

isCommitted(mixed $theState) : boolean

Manage committed status

This method can be used to get or set the object's committed state.

A committed object is one that has either been loaded from a container or committed to a container, this state can be used in conjunction with the {@link kFLAG_STATE_DIRTY} flag to determine whether an object needs to be committed.

The method features a single parameter:

  • NULL: The method will return the object's committed state.
  • TRUE: The method will set the object's committed state.
  • FALSE: The method will reset the object's committed state.

In all cases the method will return the state after it was eventually modified.

Parameters

mixed $theState

TRUE, FALSE or

                                            <tt>NULL</tt>.

Returns

boolean —

TRUE committed, FALSE uncommitted.

isAlias()

isAlias(mixed $theState) : boolean

Manage alias status

This method can be used to get or set the object's alias state.

This flag determines whether the object is an alias or not, alias objects hold a reference to their master object in the {@link kTAG_MASTER} offset.

The method features a single parameter:

  • NULL: The method will return the object's alias state.
  • TRUE: The method will set the object's alias state.
  • FALSE: The method will reset the object's alias state.

In all cases the method will return the state after it was eventually modified.

Parameters

mixed $theState

TRUE, FALSE or

                                            <tt>NULL</tt>.

Returns

boolean —

TRUE is an alias, FALSE not an alias.

manageBitField()

manageBitField(\OntologyWrapper\traits\reference $theField, \OntologyWrapper\traits\bitfield $theMask, mixed $theState) : \OntologyWrapper\traits\bitfield

Manage a bit-field property

This method can be used to manage a bitfield property, it accepts the following parameters:

  • &$theField: Reference to the bit-field property.
  • $theMask: Bit-field mask.
  • $theState: State or operator:
    • NULL: Return the masked bitfield.
    • FALSE: Turn off the masked bits.
    • other: Turn on the masked bits.

In all cases the method will return the status after it was eventually modified.

Parameters

\OntologyWrapper\traits\reference $theField

Bit-field reference.
\OntologyWrapper\traits\bitfield $theMask

Bit-field mask.
mixed $theState

Value or operator.

Returns

\OntologyWrapper\traits\bitfield —

Current masked status.