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:
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
Parameters:
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 = "");
virtual void disconnect();
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);
virtual void setOption(long option, DKAny& value);
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);
Exceptions
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);
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);
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);
Exceptions
Error messages
virtual void addObject(dkDataObject* dataobj);
Exceptions
Error messages
virtual void deleteObject(dkDataObject* dataobj);
Exceptions
Error messages
virtual void retrieveObject(dkDataObject* dataobj);
Exceptions
Error messages
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();
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);
Parameters
virtual void unRegisterMapping(const char* mappingName);
virtual DKString* listMappingNames(long& arraySize);
Parameters
virtual dkSchemaMapping* getMapping(const char* mappingName);
Parameters
virtual dkExtension* getExtension(const char* extensionName);
Parameters
virtual void addExtension(const char* extensionName,dkExtension* extensionObj);
Parameters ex
virtual void removeExtension(const char* extensionName);
virtual DKString* listExtensionNames(long& arraySize);
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);
virtual dkCollection* listSearchTemplates();
virtual DKString* listSearchTemplateNames(long& arraySize);
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.