Index

dkDatastore

Purpose:

A dkDatastore object represents and manages a connection to datastore, transactions, and executes datastore commands. Datastore is a special version of query manager class. It supports evaluate method, so it may be considered as a subclass of query manager.

dkDatastore should be subclassed to provide a specific implementation of the target datastore. For example:

Class summary:

class dkDatastore : public dkQueryManager 
 {
     public:
      dkDatastore(const char* datastore_type, const char* datastore_name = "");
      virtual ~dkDatastore();
      virtual void connect (const char* datastore_name, const char* user_name = "", const char* authentication = "", const char* connect_string = "");
      virtual void disconnect();
      virtual void getOption(long option, DKAny& value);
      virtual void setOption(long option, DKAny& value);
      virtual DKAny evaluate(const char* command, const short commandLangType, const DKNVPair* parms = 0);
      virtual DKAny evaluate( dkQuery* query);
      virtual DKAny evaluate(DKCQExpr* qe);
      virtual DKAny evaluate(dkSearchTemplate* st);
          virtual dkResultSetCursor* execute( const char* command, const short commandLangType, const DKNVPair* parms = 0);
      virtual dkResultSetCursor* execute( dkQuery* query);
      virtual dkResultSetCursor* execute( DKCQExpr* qe);
      virtual dkResultSetCursor* execute( dkSearchTemplate* st);
      virtual void executeWithCallback( const char* command, const short commandLangType, const DKNVPair* parms, dkCallback* callbackObj);
      virtual void executeWithCallback( dkQuery* query, dkCallback* callbackObj);
      virtual void executeWithCallback( DKCQExpr* qe, dkCallback* callbackObj);
       virtual void executeWithCallback( dkSearchTemplate* st,dkCallback* callbackObj);
      virtual dkQuery*  createQuery(const char* command, const short commandLangType, const DKNVPair* parms=0);
      virtual dkQuery*  createQuery(DKCQExpr* qe);
      virtual void addObject(dkDataObject* dataobj);
      virtual void addObject(dkDataObject* dataobj, long option);
      virtual void addObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);
      virtual void addObjects(dkCollection* ddoCollection);
      virtual void addObjects(dkCollection* ddoCollection, long option);
      virtual void addObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);
      virtual void deleteObject(dkDataObject* dataobj);
      virtual void deleteObject(dkDataObject* dataobj, long option);
      virtual void deleteObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);
      virtual void deleteObjects(dkCollection* ddoCollection);
      virtual void deleteObjects(dkCollection* ddoCollection, long option);
      virtual void deleteObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);
      virtual void retrieveObject(dkDataObject* dataobj);
      virtual void retrieveObject(dkDataObject* dataobj, long option);
      virtual void retrieveObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);
      virtual void retrieveObjects(dkCollection* ddoCollection);
      virtual void retrieveObjects(dkCollection* ddoCollection, long option);
      virtual void retrieveObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);
      virtual void updateObject(dkDataObject* dataobj);
      virtual void updateObject(dkDataObject* dataobj, long option);
      virtual void updateObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);
      virtual void updateObjects(dkCollection* ddoCollection);
      virtual void updateObjects(dkCollection* ddoCollection, long option);
      virtual void updateObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);
      virtual void startTransaction();
      virtual void commit ();
      virtual void rollback ();
      virtual DKBoolean isConnected();
      virtual DKString  datastoreName() const;
      virtual DKString  datastoreType() const;
      virtual DKString  userName() const;
      virtual DKHandle* connection();
      virtual DKHandle* handle(const char* type);
      virtual dkCollection* listDataSources();
      virtual DKString* listDataSourceNames(long& arrarySize);
      virtual DKAny listServers();
      virtual DKAny listSchema();
      virtual DKAny listSchemaAttributes(const char* schemaEntry);
      virtual dkCollection* listSearchableEntities();
      virtual dkCollection* listEntities();
      virtual DKString* listEntityNames(long& arraySize);
      virtual dkCollection* listEntityAttrs(const char* entityName)
      virtual DKString* listEntityAttrNames(const char* entityName, long& arraySize);
      virtual DKString* listSearchableEntityNames(long& arraySize);
      virtual dkDatastoreDef* datastoreDef();
      virtual dkCollection* listSearchTemplates();
      virtual DKString* listSearchTemplateNames(long& arraySize);
      virtual DKString registerMapping(DKNVPair* sourceMap);
      virtual void unRegisterMapping(const char* mappingName);
      virtual DKString* listMappingNames(long& arraySize);
      virtual dkSchemaMapping* getMapping(const char* mappingName);
      virtual dkExtension* getExtension(const char* extensionName);
      virtual void addExtension(const char* extensionName, dkExtension* extensionObj);
      virtual void removeExtension(const char* extensionName)
      virtual DKString* listExtensionNames(long& arraySize);
      virtual DKDDO* createDDO(const char* objectType, long Flags);
      virtual void clearCache();
      virtual void clearCache(long option);
      virtual dkServiceMgr* serviceMgr();
      virtual DKString* listAvailableServices(long& arraySize);
};

Members:

Constructors and destructor
The constructor takes a string of datastore name, datastore type, and a server name.
dkDatastore(const char* datastore_type,
const char* datastore_name = "");
virtual ~dkDatastore();

Member functions

connect
Connects to the datastore. Datastore name is the name of the database or library server. connect_string describes some selected options, supported by the specific implementation of the datastore.

Exceptions

  • DKDatastoreError
  • DKDatastoreAccessError
  virtual void connect (const char* datastore_name, const char* user_name = "", const char* authentication = "", const char* connect_string = "");

disconnect
Disconnects from the datastore.

Exceptions

  • DKDatastoreError
  • DKDatastoreAccessError
virtual void disconnect ();

setOption
Sets a datastore option.

Exceptions

  • DKDatastoreError
  • DKUsageError
virtual void setOption (long option, DKAny& value);

getOption
Gets the datastore option.
virtual void getOption (long option, DKAny& value);

evaluate
Evaluates a query and returns the result as a DKAny containing dkQueryableCollection. The second form takes a query object as a parameter.
virtual DKAny evaluate(const char* command, const short commandLangType, const DKNVPair* parms = 0);
virtual DKAny evaluate( dkQuery* query); virtual DKAny evaluate(DKCQExpr* qe);
virtual DKAny evaluate(dkSearchTemplate* st);

evaluate
Evaluates a query and returns the result as a DKAny containing dkQueryableCollection. The second form takes a query object as a parameter.
virtual DKAny evaluate( dkQuery* query);

Note:
DKUsageError exception thrown if method is not implemented.

execute
Executes a command to the datastore and returns a result set cursor. The second form takes a query object.

Exceptions

  • DKDatastoreError
  • DKDatastoreAccessError
  • DKUsageError
virtual dkResultSetCursor* execute( const char* command, const short commandLangType, const DKNVPair* parms = 0); 
virtual dkResultSetCursor* execute( dkQuery* query);
virtual dkResultSetCursor* execute( DKCQExpr* qe);
virtual dkResultSetCursor* execute(dkSearchTemplate* st);

execute
Executes a command to the datastore and returns a result set cursor. The second form takes a query object. Exceptions..

Exceptions

  • DKDatastoreError
  • DKDatastoreAccessError
  • DKUsageError

virtual dkResultSetCursor* execute( dkQuery* query);

Note:
DKUsageError exception thrown if method is not implemented

executeWithCallback
Executes a command to the datastore and pass results to the dkCallback object.
virtual void executeWithCallback( const char* command, const short commandLangType, const DKNVPair* parms, dkCallback* callbackObj);
virtual void executeWithCallback(dkQuery* query, dkCallback* callbackObj);
virtual void executeWithCallback( DKCQExpr* qe, dkCallback* callbackObj);
virtual void executeWithCallback( dkSearchTemplate* st,                          dkCallback* callbackObj);

executeWithCallback
Executes a command to the datastore and pass results to the dkCallback object.
virtual void executeWithCallback( dkQuery* query, dkCallback* callbackObj);

Note:
DKUsageError exception thrown if method is not implemented

createQuery
Creates a query object using the given parameters.

Exceptions

  • DKUsageError
virtual dkQuery* createQuery(const char* command, const short commandLangType, const DKNVPair* parms=0);
virtual dkQuery*  createQuery(DKCQExpr* qe);

Note:
DKUsageError exception thrown if method is not implemented.

addObject
Adds the data object to the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectAlreadyExists
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
virtual void addObject(dkDataObject* dataobj);
virtual void addObject(dkDataObject* dataobj, long option);
virtual void addObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

addObject
Adds the data objects to the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectAlreadyExists
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
virtual void addObjects(dkCollection* ddoCollection);
virtual void addObjects(dkCollection* ddoCollection, long option);
virtual void addObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

deleteObject
Deletes the data object from the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void deleteObject(dkDataObject* dataobj);
virtual void deleteObject(dkDataObject* dataobj, long option);
virtual void deleteObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

deleteObject
Deletes the data object from the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void deleteObjects(dkCollection* ddoCollection);
virtual void deleteObjects(dkCollection* ddoCollection, long option);
virtual void deleteObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

retrieveObject
Retrieve the data object from the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void retrieveObject (dkDataObject* dataObj)

retrieveObject
Retrieve the data object from the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void retrieveObject(dkDataObject* dataobj, long option);
virtual void retrieveObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

retrieveObject
Retrieve the data object from the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void retrieveObjects(dkCollection* ddoCollection);
virtual void retrieveObjects(dkCollection* ddoCollection, long option);
virtual void retrieveObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

updateObject
Updates this data object in the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void updateObject (dkDataObject* dataObj);
virtual void updateObject(dkDataObject* dataobj, long option);
virtual void updateObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

updateObject
Updates this data object in the datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

    Error messages:

    • PID invalid
    • Data type not supported
    • Schema mapping definition error
    • Data object mapping inconsistent
virtual void updateObjects(dkCollection* ddoCollection);
virtual void updateObjects(dkCollection* ddoCollection, long option);
virtual void updateObjects(dkCollection* ddoCollection, const DKNVPair* parms, long arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

startTransaction
Starts a transaction.

Exceptions

  • DKDatastoreAccessError
virtual void startTransaction();

Note:
DKUsageError exception thrown if method is not implemented.

commit
Commits the current transaction.

Exceptions

  • DKDatastoreAccessError
   virtual void commit ();

Note:
DKUsageError exception thrown if method is not implemented.

rollback
Rolls back the current transaction.

Exceptions

  • DKDatastoreAccessError
   virtual void rollback ();

Note:
DKUsageError exception thrown if method is not implemented.

isConnected
Returns TRUE if it is connected to datastore.
   virtual DKBoolean isConnected () const;

datastoreName
Gets datastore name.
   virtual DKString datastoreName() const;

datastoreType
Gets datastore type.
   virtual DKString datastoreType() const;

userName
Gets user name.
   virtual DKString userName() const;

connection
Returns the connection handle of this datastore.
virtual DKHandle* connection() const;

Note:
DKUsageError exception thrown if method is not implemented.

handle
Returns the handle specified by its type for this datastore.
virtual DKHandle* handle(const char* type);

listDataSources
Returns a list of valid servers to connect to. The return value is a collection of dkServerDef objects.
 virtual dkCollection* listDataSources();

listDataSourceNames
Returns a list of valid servers names to connect to.
 virtual DKString* listDataSourceNames(long& arrarySize);

listServers
listServers has been deprecated.
virtual DKAny listServers();

Note:
DKUsageError exception thrown if method is not implemented.

listSchema
listSchema has been deprecated.
virtual DKAny listSchema();

Note:
DKUsageError exception thrown if method is not implemented.

listSchemaAttributes
listSchemaAttributes has been deprecated.
virtual DKAny listSchemaAttributes(const char * schemaEntry);

Note:
DKUsageError exception thrown if method is not implemented.

listEntities
Returns a list of dkEntityDef objects in a collection for the current server.
 virtual dkCollection* listEntities();

listSearchableEntities
Returns a list of searchable dkEntityDef objects in a collection for the current server.
virtual dkCollection* listSearchableEntities();

Note:
Default behavior will call dkDatastore.listEntities()

listSearchTemplates
Returns a list of search template objects in a collection for the current server.
 virtual dkCollection* listSearchTemplates();

Note:
DKUsageError exception thrown if method is not implemented.

listEntityNames
Returns a list of entity names for the current server.
virtual DKString* listEntityNames(long& arraySize);

listSearchableEntityNames
Returns a list of searchable entity names for the current server.
virtual DKString* listSearchableEntityNames(long& arraySize);

Note:
Default behavior will call dkDatastore.listEntityNames()

listSearchTemplateNames
Returns a list of search template names for the current server.
virtual DKString* listSearchTemplateNames(long& arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

listEntityAttrs
Returns a list of dkAttrDef objects in a collection for the given entity.
virtual dkCollection* listEntityAttrs(const char* entityName);

listEntityAttrNames
Returns a list of attribute names for the given entity.
virtual DKString* listEntityAttrNames(const char* entityName, long& arraySize);

datastoreDef
Returns the datastore definition object.
virtual dkDatastoreDef* datastoreDef();

registerMapping
Register mapping to the datastore.
virtual DKString registerMapping(DKNVPair* sourceMap);

unRegisterMapping
Unregister mapping for the datastore.
 virtual void unRegisterMapping(const char* mappingName);

listMappingNames
Return list of registered mapping names for the datastore.
virtual DKString* listMappingNames(long& arraySize);

getMapping
Gets a registered mapping by mapping name.
virtual dkSchemaMapping* getMapping(const char* mappingName);

getExtension
Gets an extension by extension name.
virtual dkExtension* getExtension(const char* extensionName);

addExtension
Adds an extension with extension name.
virtual void addExtension(const char* extensionName, dkExtension* extensionObj);

removeExtension
Removes an extension with extension name.
 virtual void removeExtension(const char* extensionName);

listExtensionNames
Gets list of extension names.
virtual DKString* listExtensionNames(long& arraySize);

createDDO
Create dynamic data object with meta-data set.
 virtual DKDDO* createDDO(const char* objectType, long Flags);

clearCache
Create dynamic data object with meta-data set.
virtual void clearCache();
virtual void clearCache(long option);

Note:
DKUsageError exception thrown if method is not implemented

serviceMgr
Returns the service manager class which manages services.
virtual dkServiceMgr* serviceMgr();

listAvailableServices
List of available services. Return service ids.
virtual DKString* listAvailableServices(long& arraySize);

Note:
DKUsageError exception thrown if method is not implemented.

Exceptions:

(c) Copyright International Business Machines Corporation 1996, 2003. IBM Corp. All rights reserved.