PObject Class

OCCI provides object navigational calls that enable applications to perform any of the following on objects:

• Creating, accessing, locking, deleting, copying, and flushing objects
• Getting references to the objects

This class enables the type definer to specify when a class is capable of having persistent or transient instances. Instances of classes derived from PObject are either persistent or transient. A class (called "A") that is persistent-capable inherits from the PObject class:

class A : PObject { ... } 

Some of the methods provided, such as lock() and refresh(), are applicable only for persistent instances, not for transient instances.

To create a null PObject, use the syntax:

PObject();

The only methods valid on a null PObject are setNull(), isNull, and operator=().

To create a copy of a PObject, use the syntax:

PObject(const PObject& obj);

Summary of PObject Methods

Table 8-15 PObject Methods  

Method	Summary
flush()	Flushes a modified persistent object to the database server.
getConnection()	Return the connection from which the PObject object was instantiated.
getRef()	Return a reference to a given persistent object.
isLocked()	Test whether the persistent object is locked.
isNull()	Test whether the object is null.
lock()	Lock a persistent object on the database server. The default mode is to wait for the lock if not available.
markDelete()	Mark a persistent object as deleted.
markModified()	Mark a persistent object as modified or dirty.
operator=()	Assign one PObject to another.
operator delete()	Remove the persistent object from the application cache only.
operator new()	Creates a new persistent / transient instance.
pin()	Pins an object.
setNull()	Sets the object value to null.
unmark()	Unmarks an object as dirty.
unpin()	Unpins an object. In the default mode, the pin count of the object is decremented by one.

flush()

This method flushes a modified persistent object to the database server.

Syntax

void flush();

getConnection()

This method returns the connection from which the persistent object was instantiated.

Syntax

const Connection *getConnection() const;

getRef()

This method returns a reference to the persistent object.

Syntax

RefAny getRef() const;

isLocked()

This method test whether the persistent object is locked. If the persistent object is locked, then true is returned; otherwise, false is returned.

Syntax

bool isLocked() const;

isNull()

This method tests whether the persistent object is null. If the persistent object is null, then true is returned; otherwise, false is returned.

Syntax

bool isNull() const;

lock()

This method locks a persistent object on the database server.

Syntax

void lock(PObject::LockOption lock_option);

Parameters

lock_option

Specifies whether the lock operation should wait if the object is already locked by another user. The default value is OCCI_LOCK_WAIT, meaning the operation will wait.

Valid values are:

OCCI_LOCK_WAIT

OCCI_LOCK_NOWAIT

markDelete()

This method marks a persistent object as deleted.

Syntax

void markDelete();

markModified()

This method marks a persistent object as modified or dirty.

Syntax

void mark_Modified();

operator=()

This method assigns the value of a persistent object this PObject object. The nature (transient or persistent) of the object is maintained. Null information is copied from the source instance.

Syntax

PObject& operator=(const PObject& obj);

Parameters

obj

The object to copy from.

operator delete()

This method is used to delete a persistent or transient object. The delete operator on a persistent object removes the object from the application cache only. To delete the object from the database server, invoke the markDelete() method.

Syntax

void operator delete(void *obj,
   size_t size);

operator new()

This method is used to create a new object. A persistent object is created if the connection and table name are provided. Otherwise, a transient object is created.

Syntax

There are variants of syntax:

void *operator new(size_t size);

void *operator new(size_t size,
   const Connection *x,
   const string& tablename,
   const char *type_name);

Parameters

size

x

The connection to the database in which the persistent object is to be created.

tablename

The name of the table in the database server.

type_name

The SQL type name corresponding to this C++ class. The format is <schemaname>.<typename>.

pin()

This method pins the object and increments the pin count by one. As long as the object is pinned, it will not be freed by the cache even if there are no references to this object instance.

Syntax

void pin();

setNull()

This method sets the object value to null.

Syntax

void setNull();

unmark()

This method unmarks a persistent object as modified or deleted.

Syntax

void unmark();

unpin()

This method unpins a persistent object. In the default mode, the pin count of the object is decremented by one. When this method is invoked with OCCI_PINCOUNT_RESET, the pin count of the object is reset.

If the pin count is reset, this method invalidates all the references (Ref) pointing to this object. The cache sets the object eligible to be freed, if necessary, reclaiming memory.

Syntax

void unpin(UnpinOption mode=OCCI_PINCOUNT_DECR);

Parameters

mode

Specifies whether the pin count should be decremented or reset to 0.

Valid values are:

OCCI_PINCOUNT_RESET

OCCI_PINCOUNT_DECR