Index

DKDatastoreFed

Purpose:

DKDatastoreFed is a specific version of dkDatastore used to implement the federated datastore. A federated datastore is a virtual datastore which combines several heterogeneous datastores into a consistent and unified conceptual view. This view, or a federated schema, is established using schema mapping of the underlying datastores. The users interact with a federated datastore using the federated schema, without needing to know how the individual datastores participate in this federation.

The federated datastore coordinates query evaluation, data-access, and transaction processing of the participating datastores. Given the federated schema, a multiple-search query can be formulated, executed, and coordinated to produce results in the form of datastore-neutral dynamic data object.

Since DKDatastoreFed is a subclass of dkDatastore, its interface is the same as the interface of other datastores, for example DKDatastoreDL. Therefore, a user would be able to access DKDatastoreFed and other datastores in a consistent and uniform manner. With respect to the notion of federation, each participating datastore preserves the right to maintain its personality, such as its own query language, data-model or schema, function of interactions, and so forth, and at the same time cooperate in federation to provide a federated schema. This design allows the users to preserve the natural view to their favorite datastores and access them in conjunction with other datastores in a federated context.

The execute and evaluate functions of DKDatastoreFed accept query strings expressed in federated query language. The DKFederatedQuery object accepts queries in this syntax.

Class summary:

class DKDatastoreFed : public dkDatastore
{
  public:
   DKDatastoreFed();
   DKDatastoreFed(const char* configuration);
   virtual ~DKDatastoreFed();
 
   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 =
                             DK_CM_FEDERATED_QL_TYPE,
                          const DKNVPair* parms = 0);
   virtual DKAny evaluate(dkQuery* query);
   virtual DKAny evaluate(DKCQExpr* qe);
   virtual dkResultSetCursor* execute(const char* command,
                                      const short commandLangType =
                                         DK_CM_FEDERATED_QL_TYPE,
                                      const DKNVPair* parms = 0);
   virtual dkResultSetCursor* execute(dkQuery* query);
   virtual dkResultSetCursor* execute(DKCQExpr* qe);
   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 dkQuery*  createQuery(const char* command,
                                 const short commandLangType =
                                    DK_CM_FEDERATED_QL_TYPE,
                                 const DKNVPair* parms=0);
   virtual dkQuery*  createQuery(DKCQExpr* qe);
   virtual void addObject(dkDataObject* dataobj);
   virtual void deleteObject(dkDataObject* dataobj);
   virtual void retrieveObject(dkDataObject* dataobj);
   virtual void updateObject(dkDataObject* dataobj);
    virtual void commit ();
   virtual void rollback ();
   virtual DKBoolean isConnected();
   virtual DKHandle* connection();
   virtual DKHandle* handle(const char* type);
   virtual dkCollection* listDataSources();
   virtual DKString* listDataSourceNames(long& arrarySize);
   virtual dkCollection* listEntities();
   virtual DKString* listEntityNames(long& arraySize);
   virtual dkCollection* listEntityAttrs(const char* entityName);
   virtual DKString* listEntityAttrNames(const char* entityName,
                                         long& arraySize);
   virtual dkDatastoreDef* datastoreDef();
   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 dkCollection* listSearchTemplates();
   virtual DKString* listSearchTemplateNames(long& arraySize);
   virtual dkSearchTemplate* getSearchTemplate(const char* templateName);
   void requestConnection (const char* serverName,
                           const char* userId,
                           const char* passwd,
                           const char* connectString);
   dkDatastore* datastoreByServerName (const char* dsType, 
                                       const char* dsName);
   void       excludeServer (const char* serverName,
                             const char* templateName);
   DKString*  listExcludedServers (const char* templateName,
                                   long& arraySize);
   void       clearExcludedServers (const char* templateName);
};

Members:

Constructors and destructor

DKDatastoreFed()
Constructs the datastore and initializes it with the default configuration. Parameters: None Returns: None

DKDatastoreFed(const char* configuration)
Constructs the datastore object and initializes it using the supplied configuration string. Parameters:

configuration

Configuration string used for initialization. The configuration string is a sequence of name/value pairs separated by semi-colons.

DSNAME = <datastore_name>

Supplies the datastore name. Optional.

DBAUTH = <SERVER | CLIENT>

Database authentication information. If SERVER is supplied, the database userid and password will be supplied to the server. If CLIENT is supplied no database userid and password will be supplied to the server. The default is SERVER. Optional

LDAPORG = <LDAP organization>

Specifies the LDAP organization providing the directory information. This can be used when the list of datasources is in IBM Secure Way. Optional

virtual ~ DKDatastoreFed()
Destructor. Destroys the in-memory representation of the datastore object. Parameters: None Returns: None

Member functions

connect
Establishes a connection to a Federated datastore.

Parameters:

datastore_name
The federated datastore name used for the connection, as represented by its federated mapping server.

user_name
The user name used for connection.

authentication
The password.

connect_string
The connect string used for connection. This is used to provide additinal connection options. Valid connect_string name/value pairs are separated by semi-colons.

SQLUID=<database userid>

Userid for the underlying database. Optional

SQLPWD=<database password>

The user's password for the undelying database. Optional

DBAUTH=<SERVER | CLIENT>

Database authentication information. If SERVER is supplied the database userid and password will be supplied to the server. If CLIENT is supplied, no database userid and password will be supplied to the server. The default is SERVER. Optional

SCHEMA=<database schema>

Database schema name to use. Optional

APPLNAME=<application name>

Specifies the application name you are running. It is used to identify trace and log information. Optional

NPWD=<new password for userid>

Changes the user's password to this new value. Only valid if userid is not a system userid. Optional

LANG=<database language>

Server language. Optional

TRACESERVERLEVEL=<trace level>

The trace level. Optional. The default trace level for the server is0. The trace level is constructed by adding the numbers of the set trace levels. For example, a commone trace level is 15. The number 15 was constructed by adding 1(ICMTRACE_BASIC), 2(ICMTRACE_DETAILED), 4(ICMTRACE_DATA), and 8(ICMTRACE_PERFORMANCE). Following is the list of ICM trace flags:

0 ICMTRACE_OFF

1 ICMTRACE_BASIC

2 ICMTRACE_DETAILED

4 ICMTRACE_DATA

8 ICMTRACE_PERFORMANCE

16 ICMTRACE_PARSEBUILD

256 ICMTRACE_CACHE_TRACE

512 ICMTRACE_CACHE_ALLOC

1024 ICMTRACE_CACHE_MGT

Throws: DKException if a problem is encountered.

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

disconnect
Disconnects from the datastore.
   virtual void disconnect();
 

getOption
Gets the defined datastore option. The following are federated datastore options:

DK_CM_OPT_CACHEIndicate s if caching is enabled for schema information. For example, schema mapping.

DK_CM_TRUECache is true.

DK_CM_FALSECache is false.

virtual void getOption(long option, DKAny& value);

setOption
Sets the given option with a specific value.
   virtual void setOption(long option, DKAny& value);
 

evaluate

The first form evaluates a query and returns the result as a federated collection. The second form takes a query object. The third form takes a compound-query expression as an alternate form of a query string.

The processing of the query involves decomposing, translating, and filtering the federated query into each native query to be sent to the underlying native datastore. The result from each native datastore will be converted, filtered and merged into a federated collection and returned to the user. See "Federated query processing" in the OO and Internet Application Programming Guide for the description of the query processing mechanism.

virtual DKAny evaluate(const char* comand,const short commandLangType = DK_CM_FEDERATED_QL_TYPE,const DKNVPair* parms = 0);
virtual DKAny evaluate(dkQuery* query);
virtual DKAny evaluate(DKCQExpr* qe);
 

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

Exceptions

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

executeWithCallback
Executes a query-with-a-callback function. This is the concrete implementation of executeWithCallBack for federated datastore.

Parameters

callbackObj A dkCallback object.

qe A compound query expression 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);
 

createQuery
Creates a federated-query object using the given parameters. The second form takes a compound-query expression as an alternate form of a query string.

Parameters

command A query string that represents the query criteria.

commandLangType A query language type.

params=() A name/value pairs list.

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

addObject
Adds the data object to the persistent datastore.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectAlreadyExists
  • DKUsageError

Error messages

  • PID invalid
  • Data type not supported

   virtual void addObject(dkDataObject* dataobj);
 

deleteObject
Deletes the data object from the corresponding persistent datastore. The in-memory copy of the data object is not affected.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

Error messages

  • PID invalid
  • Data type not supported
  • Data object mapping inconsistent

virtual void deleteObject(dkDataObject* dataobj);

retrieveObject
Retrieves the data object from the corresponding persistent datastore into memory.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

Error messages

  • PID invalid
  • Data type not supported
  • Data object mapping inconsistent

virtual void retrieveObject(dkDataObject* dataobj);

updateObject
Updates the persistent datastore with the new value of this data object.

Exceptions

  • DKDatastoreAccessError
  • DKDataObjectNotFound
  • DKDataObjectNotUnique
  • DKUsageError

Error messages

  • PID invalid
  • Data type not supported
  • Data object mapping inconsistent

virtual void updateObject(dkDataObject* dataobj);

commit
Currently, this function is not supported.
virtual void commit ();

rollback
Currently, this function is not supported.
virtual void rollback ();

isConnected
Returns TRUE if connected to the datastore.
virtual DKBoolean isConnected();

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

handle
Gets a datastore handle.
virtual DKHandle* handle(const char* type);

listDataSources
Returns a list of valid federated mapping servers to connect to. The return value is a collection of server definition objects describing the server.
virtual dkCollection* listDataSources();
 

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

listEntities
Gets the list of federated entities defined in this datastore.
virtual dkCollection* listEntities();

listEntityNames
Gets the list of federated entity names defined in this datastore.
virtual DKString* listEntityNames(long& arraySize);
 

listEntityAttrs
Gets the list of attributes for a given entity name.
virtual dkCollection* listEntityAttrs(const char* entityName);

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

datastoreDef
Gets the datastore definition. Returns the meta data of this datastore, a DKDatastoreDefFed object.
virtual dkDatastoreDef* datastoreDef();

registerMapping
Returns the name of the mapping definition, usually is the name of the entity being mapped.

Parameters

sourceMap An NVPair with the following possible values (only "SCHEMA" is supported):

"SCHEMA" The reference to the dkSchemaMapping object containing the mapping.

virtual DKString registerMapping(DKNVPair* sourceMap);

unRegisterMapping
Unregisters a mapping definition from this datastore.

Parameters

mappingName
The name of the mapping definition.
virtual void unRegisterMapping(const char* mappingName);

listMappingNames
Gets the list of registered mappings for this datastore.
   
virtual DKString* listMappingNames(long& arraySize);
 

getMapping
Gets the mapping object with the given name.

Parameters

mappingName
The name of the mapping definition.
virtual dkSchemaMapping* getMapping(const char* mappingName);
 

getExtension
Gets the extension object of the given extension name.

Parameters

extensionName
The parameter definition.
virtual dkExtension* getExtension(const char* extensionName);
 

addExtension
Adds a new extension object providing a set of new functions.

Parameters

extensionName
The name of the extension object.

extensionObj
The extension object providing the services.
   
virtual void addExtension(const char* extensionName,dkExtension* extensionObj);
 

removeExtension
Removes an existing extension object.

Parameters ex

tensionName
The name of the extension object.
virtual void removeExtension(const char* extensionName);
 

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

createDDO
Creates a new dynamic data object (DDO) with properties and attributes information set to represent an object of the given type. It is a convenience function that constructs a DDO according to the object type, so that the caller only needs to set the attribute values.

Parameters

objectType The object type of the dynamic data object (DDO) to be created.

Flags Indicators for various options to specify more detailed characteristics of the DDO to be created. For example, it may be a directive to create a document DDO or a folder.

virtual DKDDO* createDDO(const char* objectType, long Flags);

listSearchTemplates
Gets a list search templates from a federated server.
virtual dkCollection* listSearchTemplates();
 

listSearchTemplateNames
Gets a list of search template names from a federated server.
virtual DKString* listSearchTemplateNames(long& arraySize);
 

getSearchTemplate
Gets search template information from a given template name.
virtual dkSearchTemplate* getSearchTemplate(const char*      templateName);
 

Federated query string

The syntax of federated query string is similar to Content Manager parametric query string:

Federated query syntax:

PARAMETRIC_SEARCH=([ENTITY=entity_name,][MAX_RESULTS=maximum_results,][COND=(conditional_expression)]   [; ...]
);
[OPTION=([CONTENT=[YES|NO|ATTRONLY]]
)]
[[AND | OR] TEXT_SEARCH=(COND=(text_search_expression)
);
[OPTION=([SEARCH_INDEX={search_index_name | (index_list) };]
[ASSOCIATED_ENTITY={associated_entity_name)};][MAX_RESULTS=maximum_results;] [TIME_LIMIT=time_limit]
)]
]

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