#include <StorageSvc/IStorageSvc.h>

Inheritance diagram for pool::IStorageSvc:

Collaboration diagram for pool::IStorageSvc:

Public Types
enum	: unsigned { ISTORAGESVC_ERROR = DbStatus::Error, INVALID_SESSION_TOKEN = ISTORAGESVC_ERROR+2, INVALID_CONNECTION_TOKEN = ISTORAGESVC_ERROR+4, INVALID_TRANSACTION_TOKEN = ISTORAGESVC_ERROR+6, INVALID_AUTHENTICATION = ISTORAGESVC_ERROR+8, TRANSACTION_FAILED = ISTORAGESVC_ERROR+10, INVALID_OBJECT = ISTORAGESVC_ERROR+12, INVALID_OBJ_TOKEN = ISTORAGESVC_ERROR+14, OBJ_NOT_LOADED = ISTORAGESVC_ERROR+16, CONNECTION_NOT_EXISTING = ISTORAGESVC_ERROR+18, ISTORAGESVC_LAST = ISTORAGESVC_ERROR+20, ISTORAGESVC_INFO = DbStatus::Info, SHAPE_NOT_AVAILIBLE = ISTORAGESVC_INFO+2, IS_PERSISTENT_SHAPE = ISTORAGESVC_INFO+4 }
	DbStatus code definitions. More...

Public Member Functions
virtual DbStatus	queryInterface (const Guid &riid, void **ppvUnkn)=0
	IInterface implementation: Query interfaces of Interface. More...

virtual unsigned int	addRef ()=0
	IInterface implementation: Reference Interface instance More...

virtual unsigned int	release ()=0
	IInterface implementation: Release Interface instance More...

virtual std::string	getContName (FileDescriptor &refDB, Token &pToken)=0
	Get container name for object. More...

virtual DbStatus	allocate (FileDescriptor &refDB, const std::string &refCont, int technology, const void object, ShapeH shapeH, Token &refpTok)=0
	Register object for write. More...

virtual DbStatus	read (const FileDescriptor &refDB, const Token &pToken, ShapeH shapeH, void **object)=0
	Read a persistent object from the medium. More...

virtual DbStatus	update (FileDescriptor &refDB, const void *object, ShapeH shapeH, Token &refToken)=0
	In place update of an existing object. More...

virtual DbStatus	destroy (FileDescriptor &refDB, Token &refToken)=0
	Destroy an existing persistent object. More...

virtual DbStatus	getShape (FileDescriptor &refDB, const Guid &objType, ShapeH &shapeH)=0
	Retrieve persistent shape from Storage manager. More...

virtual DbStatus	createShape (const FileDescriptor &refDB, const std::string &cntName, const Guid &shapeID, ShapeH &shapeH)=0
	Create a persistent shape a given Database container. More...

virtual DbStatus	startSession (int mode, int tech, SessionH &session)=0
	Start a new Database Session. More...

virtual DbStatus	endSession (const SessionH session)=0
	End the Database session. More...

virtual DbStatus	existsConnection (const SessionH sessionH, int mode, const FileDescriptor &refDB)=0
	Check the existence of a logical Database unit. More...

virtual DbStatus	connect (const SessionH sessionH, int mode, FileDescriptor &refDB)=0
	Connect to a logical Database unit. More...

virtual DbStatus	reconnect (FileDescriptor &refDB, int mode)=0
	Reconnect to a logical Database unit with different access mode. More...

virtual DbStatus	disconnect (FileDescriptor &refDB)=0
	Disconnect from a logical Database unit. More...

virtual DbStatus	openMode (FileDescriptor &refDB, int &mode)=0
	Query the access mode of a Database unit. More...

virtual DbStatus	endTransaction (ConnectionH conn, Transaction::Action typ)=0
	End/Finish an existing Transaction sequence. More...

Static Public Member Functions
static const Guid &	interfaceID ()
	Retrieve interface ID. More...

static const char *	category ()
	Retrieve category name. More...

Protected Member Functions
virtual	~IStorageSvc ()
	Destructor (called only by sub-classes) More...

Detailed Description

The IStorageSvc interface is able to handle user request for

transient objects to become persistent and
persistent objects to be made trasient. What the storage manager however needs to perform this task are object mappings, which translate between the two representations.

The activity of the storage manager includes the Transaction handling and hence the management of

Database sessions: The Database session handles Databases of one given type. This involves specific handling of a given domain represented by a technology type.
Database connections: A connection is equivalent to the triple (OCISession, OCIServer, OCISvcCtx) in ORACLE, a login to a datasource using ODBC, or a single federation for Objectivity. For file based technologies, such as root, MS Access, ODBC/Text etc., this is involves the opening of the file.
Database Transactions: Start and end a Transaction.

Author: Markus Frank

Version: 1.0

Definition at line 56 of file IStorageSvc.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum : unsigned

DbStatus code definitions.

Enumerator
ISTORAGESVC_ERROR	Error tag.
INVALID_SESSION_TOKEN	Invalid Database session token.
INVALID_CONNECTION_TOKEN	Invalid Database connection token.
INVALID_TRANSACTION_TOKEN	Invalid Database Transaction token.
INVALID_AUTHENTICATION	Invalid Database authentication.
TRANSACTION_FAILED	The Transaction failed.
INVALID_OBJECT	Object pointer is invalid.
INVALID_OBJ_TOKEN	Invalid object address.
OBJ_NOT_LOADED	Sorry, the requested object is not loaded.
CONNECTION_NOT_EXISTING	Database does not exist.
ISTORAGESVC_LAST	Terminator.
ISTORAGESVC_INFO	Info tag.
SHAPE_NOT_AVAILIBLE	Requested shape is unfortunately not availible.
IS_PERSISTENT_SHAPE	Requested shape the persistent shape.

Definition at line 313 of file IStorageSvc.h.

          : unsigned {
       ISTORAGESVC_ERROR         = DbStatus::Error,
       INVALID_SESSION_TOKEN     = ISTORAGESVC_ERROR+2,
       INVALID_CONNECTION_TOKEN  = ISTORAGESVC_ERROR+4,
       INVALID_TRANSACTION_TOKEN = ISTORAGESVC_ERROR+6,
       INVALID_AUTHENTICATION    = ISTORAGESVC_ERROR+8,
       TRANSACTION_FAILED        = ISTORAGESVC_ERROR+10,
       INVALID_OBJECT            = ISTORAGESVC_ERROR+12,
       INVALID_OBJ_TOKEN         = ISTORAGESVC_ERROR+14,
       OBJ_NOT_LOADED            = ISTORAGESVC_ERROR+16,
       CONNECTION_NOT_EXISTING   = ISTORAGESVC_ERROR+18,
       ISTORAGESVC_LAST          = ISTORAGESVC_ERROR+20,
       ISTORAGESVC_INFO          = DbStatus::Info,
       SHAPE_NOT_AVAILIBLE       = ISTORAGESVC_INFO+2,
       IS_PERSISTENT_SHAPE       = ISTORAGESVC_INFO+4
     };

Constructor & Destructor Documentation

◆ ~IStorageSvc()

virtual pool::IStorageSvc::~IStorageSvc ( )

inlineprotectedvirtual

Destructor (called only by sub-classes)

Definition at line 59 of file IStorageSvc.h.

59 { }

Member Function Documentation

◆ addRef()

virtual unsigned int pool::IStorageSvc::addRef ( )

pure virtual

IInterface implementation: Reference Interface instance

Implemented in pool::DbStorageSvc.

◆ allocate()

virtual DbStatus pool::IStorageSvc::allocate	(	FileDescriptor &	refDB,
		const std::string &	refCont,
		int	technology,
		const void *	object,
		ShapeH	shapeH,
		Token *&	refpTok
	)

pure virtual

Register object for write.

Parameters

refDB	[IN] Reference to Database descriptor
refCont	[IN] Reference to container name
technology[IN]	Specialised sub-technology
object	[IN] Pointer to persistent data object.
shapeH	[IN] Handle to persistent type information
refpTok	[OUT] Reference to location for storing the pointer of the persistent object token.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ category()

static const char* pool::IStorageSvc::category ( )

inlinestatic

Retrieve category name.

Definition at line 66 of file IStorageSvc.h.

66 { return "pool_IStorageSvc"; }

◆ connect()

virtual DbStatus pool::IStorageSvc::connect	(	const SessionH	sessionH,
		int	mode,
		FileDescriptor &	refDB
	)

pure virtual

Connect to a logical Database unit.

A connection is equivalent to the triple (OCISession, OCIServer, OCISvcCtx) in ORACLE, a login to a datasource using ODBC, or a single federation for Objectivity. For file based technologies, such as root, MS Access, ODBC/Text etc., this is involves the opening of the requested file.

Parameters

sessionH	[IN] Session context to be used to open the Database.
mode	[IN] Flag to indicate the accessmode of the session. READ, NEW/CREATE/WRITE, UPDATE, RECREATE.
refDB	[I/O] Descriptor of the Database to be opened. On successful return the Database handle is valid.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ createShape()

virtual DbStatus pool::IStorageSvc::createShape	(	const FileDescriptor &	refDB,
		const std::string &	cntName,
		const Guid &	shapeID,
		ShapeH &	shapeH
	)

pure virtual

Create a persistent shape a given Database container.

This request involves Database actions. On creation of a shape the corresponding Database container is created.

Parameters

refDB	[IN] Reference to Database descriptor
cntName	[IN] Shape/Container name.
shapeID	[IN] Shape identifier.
shapeH	[OUT] Handle to persistent mapping of a given object type.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ destroy()

virtual DbStatus pool::IStorageSvc::destroy	(	FileDescriptor &	refDB,
		Token &	refToken
	)

pure virtual

Destroy an existing persistent object.

Parameters

refDB	[IN] Reference to Database descriptor
refToken	[IN] Reference to token containing the location information of the persistent object.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ disconnect()

virtual DbStatus pool::IStorageSvc::disconnect ( FileDescriptor & refDB )

pure virtual

Disconnect from a logical Database unit.

The request for disconnect requires, that all pending Transactions are already commited. Otherwise data are lost. On disconnection the access to the Database is finalized, closed. The token will be invalidated may not be used at any longer after disconnection.

Parameters

refDB [IN] Descriptor of the Database access. This handle was retrieved when connecting to the logical Database. On successful return the Database handle will be invalidated.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ endSession()

virtual DbStatus pool::IStorageSvc::endSession ( const SessionH session )

pure virtual

End the Database session.

The request to end a Database session requires, that all pending Transactions and connections are closed. Otherwise internally the close will be forced and potentially data on pending Transactions will be lost. The token will be invalidated may not be used at any longer once the session ended.

Parameters

session [IN] Handle to the Database session. This handle was retrieved when starting the session.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ endTransaction()

virtual DbStatus pool::IStorageSvc::endTransaction	(	ConnectionH	conn,
		Transaction::Action	typ
	)

pure virtual

End/Finish an existing Transaction sequence.

At this phase all objects, which were marked for write when the Transaction was started, are either going to be made persistent or scratched. After the Transaction ended, the Transaction context is invalidated and may no longer be used independent wether the Transaction was successful or not.

Parameters

conn	[IN] Database connection
typ	[IN] Enum indicating an action to be performed. Valid arguments are COMMIT and ROLLBACK. ROLLBACK can only be suported if the underlying technology supports the necessary features.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ existsConnection()

virtual DbStatus pool::IStorageSvc::existsConnection	(	const SessionH	sessionH,
		int	mode,
		const FileDescriptor &	refDB
	)

pure virtual

Check the existence of a logical Database unit.

Parameters

sessionH	[IN] Session context to be used to open the Database.
mode	[IN] Flag to indicate the accessmode of the session. READ, NEW/CREATE/WRITE, UPDATE, RECREATE.
refDB	[I/O] Descriptor of the Database to be opened. On successful return the Database handle is valid.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ getContName()

virtual std::string pool::IStorageSvc::getContName	(	FileDescriptor &	refDB,
		Token &	pToken
	)

pure virtual

Get container name for object.

Parameters

refDB	[IN] Reference to Database descriptor
pToken	[IN] Token to the persistent object.

Returns: std::string container name.

Implemented in pool::DbStorageSvc.

◆ getShape()

virtual DbStatus pool::IStorageSvc::getShape	(	FileDescriptor &	refDB,
		const Guid &	objType,
		ShapeH &	shapeH
	)

pure virtual

Retrieve persistent shape from Storage manager.

The persistent shape is saved at write time to a Database. To match the transient shape of an object to the persistent shape of the data at the time the data were written should allow for schema evolution and object transformation(s).

Parameters

refDB	[IN] Reference to Database descriptor
objType	[IN] Shape identifier.
shapeH	[OUT] Handle to persistent mapping of a given object type.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ interfaceID()

static const Guid& pool::IStorageSvc::interfaceID ( )

static

Retrieve interface ID.

◆ openMode()

virtual DbStatus pool::IStorageSvc::openMode	(	FileDescriptor &	refDB,
		int &	mode
	)

pure virtual

Query the access mode of a Database unit.

In order to reconnect, the database obviously must already be open.

Parameters

refDB	[IN] Descriptor of the Database to be queried.
mode	[OUT] Open mod to the database.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ queryInterface()

virtual DbStatus pool::IStorageSvc::queryInterface	(	const Guid &	riid,
		void **	ppvUnkn
	)

pure virtual

IInterface implementation: Query interfaces of Interface.

Implemented in pool::DbStorageSvc.

◆ read()

virtual DbStatus pool::IStorageSvc::read	(	const FileDescriptor &	refDB,
		const Token &	pToken,
		ShapeH	shapeH,
		void **	object
	)

pure virtual

Read a persistent object from the medium.

Reading an object does not create the object.

Parameters

refDB	[IN] Reference to Database descriptor
pToken	[IN] Reference to persistent token information.
object	[OUT] Pointer to persistent data pointer.
shapeH	[IN] Desired object shape to be read

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ reconnect()

virtual DbStatus pool::IStorageSvc::reconnect	(	FileDescriptor &	refDB,
		int	mode
	)

pure virtual

Reconnect to a logical Database unit with different access mode.

In order to reconnect, the database obviously must already be open.

Parameters

refDB	[IN] Descriptor of the Database to be re-opened.
mode	[IN] Flag to indicate the accessmode of the session. Since a database can only be re-opened if it exists, possible values may only be: READ, UPDATE.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ release()

virtual unsigned int pool::IStorageSvc::release ( )

pure virtual

IInterface implementation: Release Interface instance

Implemented in pool::DbStorageSvc.

◆ startSession()

virtual DbStatus pool::IStorageSvc::startSession	(	int	mode,
		int	tech,
		SessionH &	session
	)

pure virtual

Start a new Database Session.

The Database session handles Databases of one given type. This involves specific handling of a given domain represented by a technology type. All subsequent actions involving Database actions will re-use this technology identifier. The session is a purely logical concept, which typically cannot fail unless the underlying technology requires global initialization calls.

Parameters

mode	[IN] Flag to indicate the accessmode of the session. READ, NEW/CREATE/WRITE, UPDATE, RECREATE
tech	[IN] Flag indicating the technology type of the Database the user wants to connect to.
session	[OUT] Token or handle to the Database session. This handle may later be used to open a new Database connection.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

◆ update()

virtual DbStatus pool::IStorageSvc::update	(	FileDescriptor &	refDB,
		const void *	object,
		ShapeH	shapeH,
		Token &	refToken
	)

pure virtual

In place update of an existing object.

Parameters

refDB	[IN] Reference to Database descriptor
object	[IN] Pointer to persistent data object.
shapeH	[IN] Handle to persistent type information
refToken	[IN] Reference to token containing the location information of the persistent object.

Returns: DbStatus code indicating success or failure.

Implemented in pool::DbStorageSvc.

The documentation for this class was generated from the following file:

IStorageSvc.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ ~IStorageSvc()

Member Function Documentation

◆ addRef()

◆ allocate()

◆ category()

◆ connect()

◆ createShape()

◆ destroy()

◆ disconnect()

◆ endSession()

◆ endTransaction()

◆ existsConnection()

◆ getContName()

◆ getShape()

◆ interfaceID()

◆ openMode()

◆ queryInterface()

◆ read()

◆ reconnect()

◆ release()

◆ startSession()

◆ update()