Design and implementation of a client/server framework for federated multi-search and update across heterogeneous datastores

[0002] This application is related to the following co-pending and commonly-assigned patent applications:

[0003] Application Ser. No. 09/400,532, entitled “MANAGING RESULTS OF FEDERATED SEARCHES ACROSS HETEROGENEOUS DATASTORES WITH A FEDERATED RESULT SET CURSOR OBJECT,” filed on same date herewith, by Basuki N. Soertarman et al.;

[0004] Application Ser. No. 09/399,690, entitled “THE ARCHITECTURE AND IMPLEMENTATION OF A DYNAMIC RMI SERVER CONFIGURATION HIERARCHY TO SUPPORT FEDERATED SEARCH AND UPDATE ACROSS HETEROGENEOUS DATASTORES,” filed on same date herewith, by Kehsing J. Chou et al.;

[0005] Application Ser. No. 09/399,682, entitled “ARCHITECTURE TO ENABLE SEARCH GATEWAYS AS PART OF FEDERATED SEARCH,” filed on same date herewith, by Kehsing J. Chou et al.;

[0006] Application Ser. No. 09/399,699, entitled “DELAYED DELIVERY OF QUERY RESULTS OR OTHER DATA FROM A FEDERATED SERVER TO A FEDERATED CLIENT UNTIL SUCH INFORMATION IS NEEDED,” filed on same date herewith, by M. W. Huang et al.;

[0007] Application Ser. No. 09/399,695, entitled “IMPROVED EXTENDED DATA OBJECT ARCHITECTURE FOR HANDLING MULTI-STREAMING AND COMPLEX MULTI-DIMENSIONAL FILES,” filed on same date herewith, by Kehsing J. Chou et al.;

[0008] Application Ser. No. 08/852,062, now U.S. Pat. No. 5,960,438 entitled “CLASS HIERARCHY FOR OBJECT AGGREGATION REPRESENTATION OF RELATIONAL DATABASE ROWS WITH CELLS HAVING NONTRADITIONAL DATATYPES,” filed on May 6, 1997, by Daniel T. Chang et al.;

[0009] Application Ser. No. 08/852,055, now U.S. Pat. No. 5,924,100 entitled “FLEXIBLE OBJECT REPRESENTATION OF RELATIONAL DATABASE CELLS HAVING NONTRADITIONAL DATATYPES,” filed on May 6, 1997, by Daniel T. Chang et al.;

[0010] Application Ser. No. 09/052,678, now U.S. Pat. No. 6,272,488 entitled “MANAGING RESULTS OF FEDERATED SEARCHES ACROSS HETEROGENEOUS DATASTORES WITH A FEDERATED COLLECTION OBJECT,” filed on Apr. 1, 1998, by Daniel T. Chang et al.;

[0011] Application Ser. No. 09/052,680, now U.S. Pat. No. 6,263,342 entitled “FEDERATED SEARCHING OF HETEROGENEOUS DATASTORES USING A FEDERATED DATASTORE OBJECT,” filed on Apr. 1, 1998, by Daniel T. Chang et al.;

[0012] Application Ser. No. 09/052,679, now U.S. Pat. No. 6,233,586 entitled “FEDERATED SEARCHING OF HETEROGENEOUS DATASTORES USING A FEDERATED QUERY OBJECT,” filed on Apr. 1, 1998, by Daniel T. Chang et al.;

[0013] each of which is incorporated by reference herein.

[0014] 1. Field of the Invention

[0015] This invention relates in general to database management systems performed by computers, and in particular, to a design and implementation of a client/server framework for federated multi-search and update across heterogeneous datastores.

[0016] 2. Description of Related Art

[0017] The present invention relates to a system and method for representing and searching multiple heterogeneous datastores and managing the results of such searches. Datastore is a term used to refer to a generic data storage facility, such as a relational data base, flat-file, hierarchical data base, etc. Heterogeneous is a term used to indicate that the datastores need not be similar to each other. For example, each datastore may store different types of data, such as image or text, or each datastore may be based on a different theory of data model, such as Digital Library/VisualInfo or Domino Extended Search (DES).

[0018] For nearly half a century computers have been used by businesses to manage information such as numbers and text, mainly in the form of coded data. However, business data represents only a small part of the world's information. As storage, communication and information processing technologies advance, and as their costs come down, it becomes more feasible to digitize other various types of data, store large volumes of it, and be able to distribute it on demand to users at their place of business or home.

[0019] New digitization technologies have emerged in the last decade to digitize images, audio, and video, giving birth to a new type of digital multimedia information. These multimedia objects are quite different from the business data that computers managed in the past, and often require more advanced information management system infrastructures with new capabilities. Such systems are often called “digital libraries.”

[0020] Bringing new digital technologies can do much more than just replace physical objects with their electronic representation. It enables instant access to information; supports fast, accurate, and powerful search mechanisms; provides, new “experiential” (i.e. virtual reality) user interfaces; and implements new ways of protecting the rights of information owners. These properties make digital library solutions even more attractive and acceptable not only to corporate IS organizations, but to the information owners, publishers and service providers.

[0021] Generally, business data is created by a business process (an airline ticket reservation, a deposit at the bank, and a claim processing at an insurance company are examples). Most of these processes have been automated by computers and produce business data in digital form (text and numbers). Therefore it is usually structured coded data. Multimedia data, on the contrary, cannot be fully pre-structured (its use is not fully predictable) because it is the result of the creation of a human being or the digitization of an object of the real world (x-rays, geophysical mapping, etc.) rather than a computer algorithm.

[0022] The average size of business data in digital form is relatively small. A banking record—including a customers name, address, phone number, account number, balance, etc.—represents at most a few hundred characters, i.e. few hundreds/thousands of bits. The digitization of multimedia information (image, audio, video) produces a large set of bits called an “object” or “blobs” (Binary Large Objects). For example, a digitized image of the parchments from the Vatican Library takes as much as the equivalent of 30 million characters (30 MB) to be stored. The digitization of a movie, even after compression, may take as much as the equivalent of several billions of characters (3-4 GB) to be stored.

[0023] Multimedia information is typically stored as much larger objects, ever increasing in quantity and therefore requiring special storage mechanisms. Classical business computer systems have not been designed to directly store such large objects. Specialized storage technologies may be required for certain types of information, e.g. media streamers for video or music. Because certain multimedia information needs to be preserved “forever” it also requires special storage management functions providing automated back-up and migration to new storage technologies as they become available and as old technologies become obsolete.

[0024] Finally, for performance reasons, the multimedia data is often placed in the proximity of the users with the system supporting multiple distributed object servers. This often requires a logical separation between applications, indices, and data to ensure independence from any changes in the location of the data.

[0025] The indexing of business data is often imbedded into the data itself. When the automated business process stores a person's name in the column “NAME,” it actually indexes that information. Multimedia information objects usually do not contain indexing information. This “meta data” needs to be created in addition by developers or librarians. The indexing information for multimedia information is often kept in “business like” databases separated from the physical object.

[0026] In a Digital Library (DL), the multimedia object can be linked with the associated indexing information, since both are available in digital form. Integration of this legacy catalog information with the digitized object is crucial and is one of the great advantages of DL technology. Different types of objects can be categorized differently as appropriate for each object type. Existing standards like MARC records for libraries, Finding Aids for archiving of special collections, etc. . . can be used when appropriate.

[0027] The indexing information used for catalog searches in physical libraries is mostly what one can read on the covers of the books: authors name, title, publisher, ISBN, . . . enriched by other information created by librarians based on the content of the books (abstracts, subjects, keywords, . . . ). In digital libraries, the entire content of books, images, music, films, etc . . . are available and “new content” technologies are needed; technologies for full text searching, image content searching (searching based on color, texture, shape, etc . . . ), video content searching, and audio content searching. The integrated combination of catalog searches (e.g. SQL) with content searches will provide more powerful search and access functions. These technologies can also be used to partially automate further indexing, classification, and abstracting of objects based on content.

[0028] To harness the massive amounts of information spread throughout these networks, it has become necessary for a user to search numerous storage facilities at the same time without having to consider the particular implementation of each storage facility.

[0029] Object-oriented approaches are generally better suited for such complex data management. The term “object-oriented” refers to a software design method which uses “classes” and “objects” to model abstract or real objects. An “object” is the main building block of object-oriented programming, and is a programming unit which has both data and functionality (i.e., “methods”). A “class” defines the implementation of a particular kind of object, the variables and methods it uses, and the parent class it belongs to.

[0030] Some known programming tools that can be used for developing search and result-management frameworks include IBM VisualAge C++, Microsoft Visual C++, Microsoft Visual J++, and Java.

[0031] There is a need in the art for an improved federated system. In particular, there is a need in the art for an improved client/server framework for federated multi-search and update across heterogeneous datastores.

[0032] To overcome the limitations in the prior art described above, and to overcome other limitations that will become apparent upon reading and understanding the present specification, the present invention discloses a method, apparatus, and article of manufacture for a design and implementation of a client/server framework for federated multi-search and update across heterogeneous datastores.

[0033] According to an embodiment of the invention, a technique for manipulating data in one or more heterogeneous datastores at a computer is provided. An object-oriented model is provided for integrating one or more heterogeneous datastores with a federated datastore. One or more heterogeneous datastores and a federated datastore are generated based on the object-oriented model. The generated datastores are organized into a federated composition.

[0034] Referring now to the drawings in which like reference numbers represent corresponding parts throughout:

[0035] FIG. 1 is a diagram illustrating a computer architecture that could be used in accordance with the present invention;

[0036] FIG. 2 is a diagram illustrating a class hierarchy for Data Object classes;

[0037] FIG. 3 is a diagram illustrating a class hierarchy for Datastore classes;

[0038] FIG. 4 is a diagram illustrating one composition of a federated datastore;

[0039] FIG. 5 is a diagram of an extended Grand Portal architecture;

[0040] FIG. 6 is a diagram illustrating individual datastores and federated compositions; and

[0041] FIG. 7 is a flow diagram illustrating one use of the client/server framework for federated multi-search and update across heterogeneous datastores.

[0042] In the following description of the preferred embodiment, reference is made to the accompanying drawings which form a part hereof, and in which is shown by way of illustration a specific embodiment in which the invention may be practiced. It is to be understood that other embodiments may be utilized and structural and functional changes may be made without departing from the scope of the present invention.

[0043] Federated Architecture

[0044] FIG. 1 is a diagram illustrating a computer architecture that could be used in accordance with the present invention. The present invention is described herein by way of example and is not intended to be limited to the described embodiment. The description of the preferred embodiment is based on, but certainly not limited to, the IBM design of Java Grand Portal Class Library, the Digital Library Java Application Programming Interface (API).

[0045] The Java Grand Portal 120 is comprised of client and server classes. In particular, Java Grand Portal is a set of Java classes which provides access and manipulation of local or remote data stored in Digital Library storage facilities. It uses Java APIs based on OMG-Object Query Services (OQS) and a Dynamic Data Object protocol, which is a part of OMG/Persistence Object Services.

[0046] The Java APIs provide multi-search capabilities such as:

[0047] 1. Searching within a given datastore using one or a combination of supported query types, i.e.

[0048] Parametric query—Queries requiring an exact match on the condition specified in the query predicate and the data values stored in the datastore.

[0049] Text query—Queries on the content of text fields for approximate match with the given text search expression, e.g. the existence (or non-existence) of certain phrases or word-stems.

[0050] Image query—Queries on the content of image fields for approximate match with the given image search expression, e.g. image with certain degree of similarity based on color percentages, layout, or texture.

[0051] 2. Each search type is supported by one or more search-engines.

[0052] 3. Searching on the results of a previous search.

[0053] 4. Searching involving heterogeneous datastores.

[0054] The Digital Library Grand Portal classes provide a convenient API for Java application users; the applications can be located at local or remote sites. Java classes will typically reside on both server and client sides; both sides providing the same interface. The client side of Java classes communicates with the server side to access data in the Digital Library through the network. Communication between client and server sides is done by these classes; it is not necessary to add any additional programs.

[0055] In particular, FIG. 1 is an architectural diagram outlining the structure of the federated search for Digital Library repositories using the federated datastore 100, comprised of a federated datastore client and server. A federated datastore 100 is a virtual datastore which combines several heterogeneous datastores 102 into a consistent and unified conceptual view. This view, or a federated schema, is established via schema mapping 104 of the underlying datastores. The users interact with a federated datastore 100 using the federated schema, without needing to know about the individual datastores 102 which participate in the federated datastore 100.

[0056] One embodiment of the invention provides a federated result set cursor object across heterogeneous datastores. In one embodiment of the invention, one or more classes implement the federated result set cursor object, and one or more methods are provided to manipulate the federated result set cursor object. In one embodiment, the class definitions and methods reside at the federated datastore client and server.

[0057] The federated datastore 100 does not have a corresponding back-end client. Since it is a virtual datastore, the federated datastore 100 relies on the underlying physical back-end client associated with it, such as the DL client (i.e., Digital Library client), OnDemand, VisualInfo, DB2, etc. Digital Library, OnDemand, VisualInfo, and DB2 are all products from International Business Machines Corporation. As mentioned before, this association is established by a schema mapping component 104.

[0058] The communication between the federated datastore 100 client and server can be done by any appropriate protocol. On top of Java Grand Portal client classes, the users can develop application programs using, for example, any existing Java Beans 122 development environment.

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

[0060] Note that each heterogeneous datastore and the federated datastore are created using one datastore definition or superclass. The federated datastore 100 and the heterogeneous datastores 102 are all subclasses of a class called Datastore, therefore, all of these datastores 100 and 102 have the same interface. Therefore, a user would be able to access the federated datastore 100 and the heterogeneous datastores 102 in a consistent and uniform manner.

[0061] Additionally, the objects stored in the federated datastore 100 and the heterogeneous datastores 102 are subclasses of a Data Object class. The Data Object class includes subclasses for dynamic data objects (DDOs) and extended data objects (XDOs). A DDO has attributes, with type, value, and properties. The value of an attribute can be a reference to another DDO or XDO, or a collection of DDOs or XDOs.

[0062] FIG. 2 is a diagram illustrating a class hierarchy for Data Object classes. The objects stored in and manipulated by the datastores and fetch operations belong to data object classes. These objects are returned as the result of a fetch, or created and used in CRUD (add, retrieve, update, delete) operations.

[0063] A DataObjectBase 200 is an abstract base class for all data objects known by datastores. It has a protocol attribute, that indicates to the datastore which interface can be used to operate on this object. A XDOBase 210 is the base class used to represent user-defined-types (UDT) or large objects. In particular, the XDOBase 210 is the base class for some user-defined types 212 and XDOs 214. AXDO 214 represents complexUDTs or large objects (LOB). This object can exist stand-alone or as a part of a DDO 236. Therefore, it has a persistent object identifier and CRUD operations capabilities.

[0064] Blob 216 is a base class for BLOBs as a place holder to share all generic operations pertaining to BLOBs. Clob 218 is a base class for CLOBs (Character Large Objects) as a placeholder to share all generic operations pertaining to CLOBs. DBClob 220 is a base class for DBCLOBs (database character large object) as a placeholder to share all generic operations pertaining to DBCLOBs. BlobDB2222 represents a BLOB specific to DB2, and BlobDL 22 represents a BLOB specific to DL. Similarly, though not shown, there may be subclasses for ClobDB2, ClobDL, etc.

[0065] A DataObject 230 is a base class for PersistentObject 232 and DDOBase 234. A PersistentObject 232 represents a specific object whose code is statically generated and compiled. This type of object will not be covered in this document. A DDOBase 234 is a base class for a dynamic data object 236 (without the CRUD methods). A DDO (Dynamic Data Object) 236 represents generic data objects which are constructed dynamically at runtime. This object fits well with query and browsing activities in Grand Portal where objects are only known and generated at runtime. It supports the CRUD operations (add, retrieve, update, and delete), and, with the help of its associated datastore, a DDO can put itself into and out of the datastore.

[0066] One skilled in the art would recognize that these are only example classes and subclasses and other structures maybe used for objects and other classes or subclasses may be added to or removed from the tree shown in FIG. 2.

[0067] With respect to the notion of “federation”, each participating datastore preserves the right to maintain its “personality”, i.e. its own query language, data-model or schema, method of interaction, etc, and at the same time cooperating in a federation to provide a federated schema. This design allows the users to preserve the natural view to their favorite datastore as well as access them in conjunction with other datastores in a federated context.

[0068] The federated datastore 100 can combine the participating native datastores in two ways:

[0069] With mapping. As described above, mapping of concepts across participating datastores is established to provide a unified conceptual view. Based on this federated schema, federated queries with both join and union expressions can be formulated.

[0070] Without mapping. In this case, the federated datastore 100 only reflects the union of each participating datastore's conceptual view. Although it coordinates query processing and data-access for each underlying datastore, the federated datastore 100 must accept queries in each datastore's native language since the query translation process can not be performed without mapping. In addition, since there is no conceptual mapping between datastores, the FederatedQuery 19 results can only reflect the union of results from each datastore.

[0071] The embodiment of the invention is incorporated into one or more software programs that reside at the federated datastore 100. Generally, the software programs and the instructions derived therefrom, are all tangibly embodied in a computer-readable medium, e.g. one or more of the data storage devices, which may be connected to the federated datastore 100. Moreover, the software programs and the instructions derived therefrom, are all comprised of instructions which, when read and executed by the computer system 100, causes the computer system 100 to perform the steps necessary to implement and/or use the present invention. Under control of an operating system, the software programs and the instructions derived therefrom, may be loaded from the data storage devices into a memory of the federated datatstore 100 for use during actual operations.

[0072] Thus, the present invention may be implemented as a method, apparatus, or article of manufacture using standard programming and/or engineering techniques to produce software, firmware, hardware, or any combination thereof. The term “article of manufacture” (or alternatively, “computer program product”) as used herein is intended to encompass a computer program accessible from any computer-readable device, carrier, or media. Of course, those skilled in the art will recognize many modifications may be made to this configuration without departing from the scope of the present invention.

[0073] Those skilled in the art will recognize that the exemplary environment illustrated in FIG. 1 is not intended to limit the present invention. Indeed, those skilled in the art will recognize that other alternative hardware environments may be used without departing from the scope of the present invention.

[0074] An embodiment of the invention provides a design and implementation of a client/server framework for federated multi-search and update across heterogeneous datastores.

[0075] A consistent framework is provided for developing client/server application programs for multi-search and update on a single or multiple heterogeneous datastores participating in a federation. The datastores can be of the same or different types, and in a mixture of local or client/server configurations. Several different search-engines, such as, text search and image search engines, may be added to enrich the combined multi-search capability of the system.

[0076] In particular, an embodiment of the invention provides an environment and facilities for client/server application development with object-oriented class libraries. Example object-oriented class libraries are described in more detail below. The object-oriented class libraries support a consistent framework for representing a variety of data-storage facilities via the use of datstore objects, including the federation of several heterogeneous datastores. Additional datastore types can be defined and incorporated in the federation.

[0077] The object-oriented class libraries support a consistent framework for data-access across a single or heterogeneous datastore via the implementation of dynamic data objects and extender data objects.

[0078] The object-oriented class libraries support a consistent framework for performing multi-search using a variety of search engines and for performing federated search via the federated datastores.

[0079] The object-oriented class libraries support a consistent framework for handling a variety of multi-media data via the implementation of an extender data object and its extensions.

[0080] The object-oriented class libraries support a consistent framework for client/server implementation of the above.

[0081] The object-oriented class libraries support a consistent framework for defining a dynamic client/server configuration and load balancing.

[0082] Modern day application programs work in a complex environment. The present invention provides support for a number of features. Non-traditional data types, such as text, image, voice, and video are supported, along with capabilities for capturing, storing/archiving, searching, updating, and presenting these data types. The ability to perform a multi-search (i.e., a combination of parametric, text, and image search) with the help of proper search engines is supported. The ability to access and update data from a single or heterogeneous data source in a federated or non-federated environment is supported. The ability to work in a client/server environment with dynamic topology where new servers can be added or removed from the configuration is supported. The ability to support a choice of different implementation languages, such as Java, C++, and Visual Basic, in diverse customer shops and machine platforms is supported. The ability to support applications launched from the World Wide Web is available. The ability to support re-usable component based software development is available.

[0083] FIG. 3 is a diagram illustrating a class hierarchy for Datastore classes. A main datastore class 300 is an abstract base class (i.e., superclass) for all datastores. In particular, some datastore classes that are based on the datastore class 300 and inherit its characteristics are the following: a DL Datastore class 302, a VisualInfo Datastore class 304, a Federated Datastore class 306, and an OnDemand Datastore class 308. It is to be understood that the techniques of the invention may be applied to any data source and is not limited to the mentioned datastores.

[0084] FIG. 4 is a diagram illustrating one composition of a federated datastore. The federated datastore 400 connects to heterogeneous datastores 402,404,406, and 408. As illustrated, a federated datastore 406 may connect to and be nested under federated datastore 400. Additionally, the federated datastore 406 may connect to heterogeneous datastores 410,412, and 414. The depicted architecture is only a sample, and one skilled in the art would recognize that other examples fall within the scope of the invention.

[0085] FIG. 5 is a diagram of an extended Grand Portal architecture. A Grand Portal client for a federated client datastore 500 is connected to a Grand Portal server for a federated server datastore 502. Another federated client/server system 504 may be connected to the federated server 502. A Grand Portal client/server system for an OnDemand (OD) datastore 506 may be part of the federation. Additionally, a Grand Portal client/server system for a Digital LibraryNisualinfo (DL/VI) datastore 508 may be part of the federation. As with any of the datastores discussed herein, a user may access the client or the server directly. Therefore, user applications may reside either at the client or the server.

[0086] FIG. 6 is a diagram illustrating individual datastores and federated compositions. In particular, a datastore can be configured as a stand-alone or as part of a federation. Additionally, a federated datastore can be composed of any number of datastores, including other federated datastores. Stand-alone datastores may be accessed directly by auser. The following are example stand-alone datastores in FIG. 6: a Digital Libt (DL) datastore 600, an OnDemand datastore 602, a Visualnfo/400 datastore 604, a Domino.Doc datastore 606, or a ImagePlus/390 datastore 608. Additionally, there may be multiple federated compositions 610 and 612. A federated composition 612 may include individual datastores 614, 616, and 620, along with another federated datastore 618.

[0087] Part of the novelty and uniqueness of the Grand Portal architecture is that it is rich and robust enough to allow a user to compose a search in the following configurations:

[0088] 1. Search against a single datastore either from a client or a server configuration. Depending on the target datastore features, the architecture may support multi-search involving several different search engines (text and image search) or an update function.

[0089] 2. Non-federated search against several datastores. Non-federated means that there is no mapping used. The user manages the search to each native datastore and processes the results according to a specific application to solve a specific problem. In this case, the datastore could be a gateway.

[0090] 3. Federated search across several datastores, including other federated datastores

[0091] 4. A mixture of 2 and 3.

[0092] 5. Search in a combination of different platforms (e.g., AMx, NT/Win98) using a variety of languages (e.g., Java, C++, Visual Basic)

[0093] FIG. 7 is a flow diagram illustrating one use of the client/server framework for federated multi-search and update across heterogeneous datastores. Initially, in block 700 a federated composition is built by generated datastores from datastore classes. For example, a federated datastore is generated from a federated datastore class that is based on a base datastore class. Similarly, a Digital Library datastore, a QBIC datastore, and a Text datastore may be generated from their corresponding datastore classes, each of which is based on the base datastore class.

[0094] Then, in block 702, data is stored in the datastores using objects based on object classes. For example, the objects may be dynamic data objects or extended data objects. On type of extended data object is a binary large object. Next, searching may be performed across the heterogeneous (native) datastores, block 704. This is done using query objects. For example, the query can be a combined query object (for retrieving a combination of data, such as text, image or parametric), or the query can be a text query, an image query, a parametric query, or a SQL query.

[0095] In order for the federated datastore to communicate with the native datastores, shema mapping objects are used, block 706. Once the mapping is performed and the query is submitted to each native datastore, in block 708, data is returned from each native datastore in the form, for example, of a collection object or a result set cursor object. Then, in block 710, a user or application program may iterate thorugh the returned data using an iterator object.

[0096] 1. Datastore Base Class

[0097] The dkDatastore is the class on which each other datastore class is based. An example class definition for dkDatastore is set forth below.

[0098] The following methods are part of the dkDatastore class:

[0099] public abstract void connect(String datastore_name,

[0100] String user_name,

[0101] String authentication,

[0102] String connect string) throws DKException, Exception

[0103] Connects to a datastore.

[0104] Parameters:

[0105] datastore_name—the datastore name used for connection

[0106] user_name—the user name used for connection

[0107] authentication—the authentication used for connection

[0108] connect_string—the connect string used for connection. This is used to provide additional connection options.

[0109] public abstract void disconnect( ) throws DKException, Exception

[0110] Disconnects to a datastore.

[0111] public abstract ObjectgetOption(int option) throws DKException, Exception

[0112] Gets a datastore option.

[0113] Parameters:

[0114] option—the option identifier

[0115] Returns:

[0116] an option value

[0117] public abstract void setOption(int option,

[0118] Object value) throws DKException, Exception

[0119] Sets a datastore option.

[0120] Parameters:

[0121] option—the option identifier

[0122] value—the option value

[0123] public abstract Object evaluate(String command,

[0124] short commandLangType,

[0125] D NVPair params[ ]) throws DKException, Exception

[0126] Evaluates a query.

[0127] Parameters:

[0128] command—a query string

[0129] commandLang—a query type

[0130] params—additional query option in name/value pair

[0131] Returns:

[0132] a collection of the results

[0133] public abstract Object evaluate(dkQuery query) throws DKException, Exception

[0134] Evaluates a query.

[0135] Parameters:

[0136] qo—a query object

[0137] Returns:

[0138] a collection of the results

[0139] public abstract Object evaluate(DKCQExpr qe) throws DKException, Exception

[0140] Evaluates a query.

[0141] Parameters:

[0142] qe—a common query expression object

[0143] Returns:

[0144] a collection of the results

[0145] public abstract dkResultSetCursor execute(String command,

[0146] short commandLangType,

[0147] DKNVPairparams[ ]) throws DKException, Exception

[0148] Executes the query.

[0149] Parameters:

[0150] command—a query string

[0151] commandLang—a query type

[0152] params—additional query option in name/value pair

[0153] Returns:

[0154] resultSetCursor which represents a datastore cursor.

[0155] public abstract dkResultSetCursor execute(dkQuery query) throws DKException, Exception

[0156] Executes the query.

[0157] Parameters:

[0158] qo—a query object

[0159] Returns:

[0160] resultSetCursor which represents a datastore cursor.

[0161] public abstract dkResultSetCursor execute(DKCQExpr qe) throws DKException, Exception

[0162] Executes the query.

[0163] Parameters:

[0164] qe—a common query expression object

[0165] Returns:

[0166] resultSetCursor which represents a datastore cursor.

[0167] public abstract void executeWithCallback(dkQuery qo,

[0168] dkcallback callbackObj) throws DKException, Exception

[0169] Executes the query with callback function.

[0170] Parameters:

[0171] qo—a query object

[0172] callbackObj—a dkCallback object

[0173] public abstract void executeWithCallback(String command,

[0174] short commandLangType,

[0175] DKNVPairparams[ ],

[0176] dkcallback callbackObj) throws DKException, Exception

[0177] Executes the query with callback function.

[0178] Parameters:

[0179] command—a query string

[0180] commandLang—a query type

[0181] params—additional query option in name/value pair

[0182] callbackObj—a dkCallback object

[0183] public abstract void executeWithCallback(DKCQExpr qe,

[0184] dkcallback callbackObj) throws DKException, Exception

[0185] Executes the query with callback function.

[0186] Parameters:

[0187] qe—a common query expression object

[0188] callbackObj—a dkCallback object

[0189] public abstract dkQuery createQuery(String command,

[0190] short commandLangType,

[0191] KNVPair params[ ]) throws DKException, Exception

[0192] Creates a query object.

[0193] Parameters:

[0194] command—a query string

[0195] commandLang—a query type

[0196] params—additional query option in name/value pair

[0197] Returns:

[0198] a query object

[0199] public abstract dkQuery createQuery(DKCQExpr qe) throws DKException, Exception

[0200] Creates a query object.

[0201] Parameters:

[0202] qe—a common query expression object

[0203] public abstract void addObject(dkDataObject ddo) throws DKException, Exception

[0204] Adds this ddo to this datastore.

[0205] Parameters:

[0206] ddo—the ddo to be added to this datastore

[0207] public abstract void deleteObject(dkDataObject ddo) throws DKException, Exception

[0208] Deletes this ddo from this datastore.

[0209] Parameters:

[0210] ddo—the ddo to be deleted from this datastore

[0211] public abstract void retrieveObject(dkDataObject ddo) throws DKException, Exception

[0212] Retrieves this ddo from this datastore.

[0213] Parameters:

[0214] ddo—the ddo to be retrieved from this datastore

[0215] public abstract void updateObject(dkDataObject ddo) throws DKException, Exception

[0216] Updates this ddo in this datastore.

[0217] Parameters:

[0218] ddo—the ddo to be updated in this datastore

[0219] public abstract void commit( ) throws DKException, Exception

[0220] Commits a datastore transaction.

[0221] public abstract void rollback( ) throws DKException, Exception

[0222] Rolls back a datastore transaction.

[0223] public abstract boolean isConnected( ) throws Exception

[0224] checks to see if the datastore is connected.

[0225] Returns:

[0226] true if connected

[0227] public abstract String datastorename( ) throws Exception

[0228] Gets the name of this datastore object. Usually it represents a datastore source's server name.

[0229] Returns:

[0230] datastore name

[0231] public abstract String datastoretype( ) throws Exception

[0232] Gets the datastore type for this datastore object.

[0233] Returns:

[0234] datastore type

[0235] public abstract DKHandle connection( ) throws Exception

[0236] Gets the connection handle for a datastore.

[0237] Returns:

[0238] connection handle

[0239] public abstract DKHande handle(String type) throws Exception

[0240] Gets a datastore handle.

[0241] Parameters:

[0242] type—type of datastore handle wanted

[0243] Returns:

[0244] a datastore handle

[0245] public abstract String userName( ) throws Exception

[0246] Gets the user name for this datastore object.

[0247] Returns:

[0248] user name

[0249] public abstract dkcollection listDataSources( ) throws DKException, Exception

[0250] List the available datastore sources that can be used to connect with.

[0251] Returns:

[0252] a collection of server defs

[0253] public abstract String[ ] listDataSourceNames( ) throws DKException, Exception

[0254] Lists the available datastore source names that can be used to connect with.

[0255] Returns:

[0256] an array of server names

[0257] public abstract Object listServers( ) throws DKException, Exception

[0258] Lists the available datastore sources that can be used to connect with. Note: listservers( ) is deprecated. Replace by listDataSources.

[0259] Returns:

[0260] a collection of server definitions

[0261] See Also:

[0262] listDataSources

[0263] public abstract Object listSchema( ) throws DKException, Exception

[0264] List the entities that belong to this datastore. Note: listSchema( ) is deprecated. Replace by listEntities.

[0265] Returns:

[0266] an object that contains the schema

[0267] See Also:

[0268] listEntities

[0269] public abstract Object listSchemaAttributes(String schemaEntry) throws DKException, Exception

[0270] List the attributes that belong to a schema Note: listSchemaAttributes( ) is deprecated. Replace by listEntityAttributes.

[0271] Parameters:

[0272] schemaEntry—the name of the schema.

[0273] Returns:

[0274] an object that contains the attributes that belong to this schema

[0275] See Also:

[0276] listEntityAttrs

[0277] public abstract dkcollection listEntities( ) throws DKException, Exception

[0278] Gets a list of entities from persistent datastore.

[0279] Returns:

[0280] a collection of entity defs

[0281] Throws: DKException

[0282] if error occurs

[0283] public abstract dkcollection listSearchableEntities( ) throws DKException, Exception

[0284] public abstract String[ ] listEntityNames( ) throws DKException, Exception

[0285] Gets a list of entity names from persistent datastore

[0286] Returns:

[0287] an array of entity names

[0288] Throws: DKException

[0289] if error occurs

[0290] public abstract String[ ] listSearchableEntityNames( ) throws DKException, Exception

[0291] public abstract dkcollection listEntityAttrs(String entityName) throws DKException, Exception

[0292] Gets a list of attributes for a given entity name.

[0293] Parameters:

[0294] entityName—name of entity to retrieve attributes for

[0295] Returns:

[0296] a dkCollection of dkAttrDef objects

[0297] Throws: DKException

[0298] if the entity name does not exist

[0299] public abstract String[ ] listEntityAttrNames(String entityName) throws DKException, Exception

[0300] Gets a list of attribute names for a given entity name.

[0301] Parameters:

[0302] entityName—name of entity to retrieve attribute names for

[0303] Returns:

[0304] an array of attribute names

[0305] Throws: DKException

[0306] if the entity name does not exist

[0307] public abstract dkDatastoreDef datastoreDef( ) throws DKException; Exception

[0308] Gets datastore definition

[0309] Returns:

[0310] the meta-data (dkDatastoreDef) of this datastore

[0311] public abstract String registerMapping(DKNVPair sourceMap) throws DKException, Exception

[0312] Registers mapping information to this datastore

[0313] Parameters:

[0314] sourceMap—source name and mapping

[0315] Returns:

[0316] the mapping name for the mapping information

[0317] public abstract void unRegisterMapping(String mappingName) throws DKException, Exception

[0318] Unregisters mapping information for this datastore

[0319] Parameters:

[0320] mappingName—name of the mapping information

[0321] public abstract String[ ] listMappingNames( ) throws DKException, Exception

[0322] Gets the list of the register mappings for this datastore

[0323] Returns:

[0324] an array of register mapping objects' names

[0325] public abstract dkSchemaMapping getMapping(String mappingName) throws DKException, Exception

[0326] Gets mapping information for this datastore

[0327] Parameters:

[0328] mappingName—name of the mapping information

[0329] Returns:

[0330] the schema mapping object

[0331] public abstract dkextension getExtension(String extensionName) throws DKException, Exception

[0332] Gets the extension object from a given extenstion name.

[0333] Parameters:

[0334] extensionName—name of the extension object.

[0335] Returns:

[0336] extension object.

[0337] public abstract void addExtension(String extensionname, dkExtension extensionObj) throws DKException, Exception

[0338] Adds a new extension object.

[0339] Parameters:

[0340] extensionname—name of new extension object

[0341] extensionObj—the extension object to be set

[0342] public abstract void removeExtension(String extensionName) throws DKException, Exception

[0343] Removes an existing extension object

[0344] Parameters:

[0345] extensionname—name of extension object to be removed

[0346] public abstract String[ ] listExtensionNames( ) throws DKException, Exception

[0347] Gets the list of extension objects' names

[0348] Returns:

[0349] an array of extension objects' names

[0350] public abstract DKDDO createDDO(String objectType,

[0351] int Flags) throws DKException, Exception

[0352] Creates a new DDO with object type, properties and attributes set for a given backend server.

[0353] Parameters:

[0354] objectType—the object type user wants to create Flags—to indicate various options to specify more detail characteristics of the DDO to create. For example, it may be a directive to create a document DDO, a folder, etc.

[0355] Returns:

[0356] a new DDO of the given object type with all the properties and attributes set, so that the user only need to set the attribute values

[0357] public abstract void changePassword(String userId,

[0358] String oldPwd,

[0359] String newPwd) throws DKException, Exception

[0360] public abstract void destroy( ) throws DKException, Exception

[0361] Destroys datastore and performs datastore cleanup if needed.

[0362] 2. Federated Datastore

[0363] In the preferred embodiment, the federated datastore takes query strings expressed in a federated query language. An example class definition for DatastoreFederated is set forth below.

[0364] The following methods are part of the federated datastore class:

[0365] public DKDatastoreFed( ) throws DKException, Exception

[0366] Constructs default Federated Datastore.

[0367] public DKDatastoreFed(String configuration) throws DKException, Exception

[0368] Constructs default Federated Datastore.

[0369] public void connect(String datastore_name,

[0370] String user_name,

[0371] String authentication,

[0372] String connect_string) throws DKException, Exception

[0373] Establishes a connection to a federated datastore.

[0374] Parameters:

[0375] datastore_name—federated datastore name

[0376] user_name—userid to logon to this federated datastore

[0377] authentication—password for this user_name

[0378] connect_string—additional information string

[0379] Throws: DKException

[0380] if either:

[0381] datastore_name, user_name, or authentication is null or if error occurs in the federated datastore

[0382] Overrides:

[0383] connect in class dkAbstractDatastore

[0384] public void disconnect( ) throws DKException, Exception

[0385] Disconnects from the federated datastore.

[0386] Throws: DKException

[0387] if unable to disconnect from server.

[0388] Overrides:

[0389] disconnect in class dkAbstractDatastore

[0390] public Object getoption(int option) throws DKException

[0391] Gets defined datastore option

[0392] Parameters:

[0393] option—an option id

[0394] Returns:

[0395] the value for the given option

[0396] Throws: DKException

[0397] if option is not set

[0398] Overrides:

[0399] getOption in class dkAbstractDatastore

[0400] public void setOption(int option, Object value) throws DKException

[0401] Sets the given “option” with a specific “value”.

[0402] Parameters:

[0403] option—an option id

[0404] value—the value for the “option”

[0405] Throws: DKException

[0406] if option/value is invalid

[0407] Overrides:

[0408] setOption in class dkAbstractDatastore

[0409] public Object evaluate(String command,

[0410] short commandLangType,

[0411] DKNVPairparams[ ]) throws DKException, Exception

[0412] Evaluates a query and returns the result as a dkQueryableCollection object.

[0413] Parameters:

[0414] command—a query stirring that represent the query criteria

[0415] commandLangType—a query language type, for Federated, it will be DK_FEDERATED_QL_TYPE

[0416] params—a name/value pairs list

[0417] Returns:

[0418] a query result collection

[0419] Throws: DKException

[0420] if “command” argument is null

[0421] Overrides:

[0422] evaluate in class dkAbstractDatastore

[0423] public Object evaluate(dkQuery query) throws DKException, Exception

[0424] Evaluates a query and returns the result as a dkQueryableCollection.

[0425] Parameters:

[0426] query—a given query object

[0427] Returns:

[0428] a query result collection

[0429] Throws: DKException

[0430] if the “query” input is null or not of federated query type.

[0431] Overrides:

[0432] evaluate in class dkAbstractDatastore

[0433] public Object evaluate(DKCQExpr qe) throws DKException, Exception

[0434] Evaluates a query.

[0435] Parameters:

[0436] qe—a common query expression object

[0437] Returns:

[0438] a collection of the results

[0439] Throws: DKException

[0440] if common query expression object is invalid

[0441] Overrides:

[0442] evaluate in class dkAbstractDatastore

[0443] public dkResultSetCursor execute(String command,

[0444] short commandLangType,

[0445] DKNVPairparams[ ]) throws DKException, Exception

[0446] Executes a command query of the federated datastore and returns a result set cursor.

[0447] Parameters:

[0448] command—a query string that represents the query criteria.

[0449] commandLangType—a query language type, for Federated, it will be DK_FEDERATED_—QL_TYPE.

[0450] params[ ]—a name/value pairs list.

[0451] Returns:

[0452] a dkResultSetCursor object.

[0453] Throws: DKException

[0454] if “command” is null or invalid, or “commandLangType” is not Federated Query type.

[0455] Overrides:

[0456] execute in class dkAbstractDatastore

[0457] public dkResultSetCursor execute(dkQuery query) throws DKException, Exception

[0458] Executes a command query of the federated datastore and returns a result set cursor. This method takes a Federated query object as an argument.

[0459] Parameters:

[0460] query—a federated dkQuery object

[0461] Returns:

[0462] a dkResultSetCursor object

[0463] Throws: DKException

[0464] if “query” object is null or query.qlType( ) is not DK_FEDERATED_QL_TYPE

[0465] Overrides:

[0466] execute in class dkAbstractDatastore

[0467] public dkResultSetCursor execute(DKCQExpr cqe) throws DKException, Exception

[0468] Executes a query expression.

[0469] Parameters:

[0470] cqe—a common query expression object

[0471] Returns:

[0472] resultSetCursor which represents a federated datastore cursor.

[0473] Throws: DKException

[0474] if “cqe” object is invalid

[0475] Overrides:

[0476] execute in class dkAbstractDatastore

[0477] public void executeWithCallback(dkQuery query,

[0478] dkcallback callbackObj) throws DKException, Exception

[0479] Executes a query with callback function.

[0480] Parameters:

[0481] query—a query object

[0482] callbackObj—a dkCallback object

[0483] Overrides:

[0484] executeWithCallback in class dkAbstractDatastore

[0485] public void executeWithCallback(String command,

[0486] short commandLangType,

[0487] DKNVPair params[ ],

[0488] dkcallback callbackObj) throws DKException, Exception

[0489] Executes the query with callback function.

[0490] Parameters:

[0491] command—a query string

[0492] commandLang—a query type

[0493] params—additional query option in name/value pair

[0494] callbackObj—a dkCallback object

[0495] Overrides:

[0496] executeWithCallback in class dkAbstractDatastore

[0497] public void executeWithCallback(DKCQExpr cqe,

[0498] dkcallback callbackObj) throws DKException, Exception

[0499] Executes a query expression with callback function.

[0500] Parameters:

[0501] cqe—a common query expression object

[0502] callbackObj—a dkCallback object

[0503] Overrides:

[0504] executeWithCallback in class dkAbstractDatastore

[0505] public dkQuery createQuery(String command,

[0506] short commandLangType,

[0507] DKNVPair params[ ]) throws DKException

[0508] Creates a federated query object.

[0509] Parameters:

[0510] command—a query string that represents the query criteria

[0511] commandLangType—a query language type, it will be one of the

[0512] following:

[0513] DK_CM_TEMPLATE_QL_TYPE

[0514] DK_CM_TEXT_QL_TYPE

[0515] DK_CM_IMAGE_QL_TYPE

[0516] DK_CM_PARAMETRIC_QL_TYPE

[0517] DK_CM_COMBINED_QL_TYPE

[0518] params[ ]—a name/value pairs list

[0519] Returns:

[0520] a federated dkQuery object

[0521] Throws: DKException

[0522] if “command” is null

[0523] Overrides:

[0524] createQuery in class dkAbstractDatastore

[0525] public dkQuery createQuery(DKCQExpr qe) throws DKException

[0526] Creates a query object.

[0527] Parameters:

[0528] cqe—a common query expression object

[0529] Throws: DKException

[0530] if “cqe” object is invalid

[0531] Overrides:

[0532] createQuery in class dkAbstractDatastore

[0533] public dkcollection listDataSources( ) throws DKException

[0534] Lists the available datastore sources that a user can connect to.

[0535] Returns:

[0536] a collection of ServerDef objects describing the servers

[0537] Throws: DKException

[0538] if internal error occurs from server

[0539] Overrides:

[0540] listDataSources in class dkAbstractDatastore

[0541] public String[ ] listDataSource( )throws DKException

[0542] Gets a list of datasource names.

[0543] Returns:

[0544] an array of datasource names

[0545] Throws: DKException

[0546] if error occurs when retrieving datasource names

[0547] Overrides:

[0548] listDataSourceNames in class dkAbstractDatastore

[0549] public void addObject(dkDataObject dataobj) throws DKException, Exception

[0550] Adds a DDO object.

[0551] Parameters:

[0552] ddo—a Federated object to be added.

[0553] Throws: DKException

[0554] if error occurs during add

[0555] Overrides:

[0556] addObject in class dkAbstractDatastore

[0557] public void deleteObject(dkDataObject dataobj) throws DKException, Exception

[0558] Deletes a data object.

[0559] Parameters:

[0560] ddo—a federated DDO object to be deleted

[0561] Throws: DKException

[0562] if error occurs during delete.

[0563] Overrides:

[0564] deleteObject in class dkAbstractDatastore

[0565] public void retrieveObject(dkDataObject dataobj) throws DKException, Exception

[0566] Retrieves a data-object.

[0567] Parameters:

[0568] ddo—document object to be retrieved.

[0569] Throws: DKException

[0570] when retrieve failed.

[0571] Overrides:

[0572] retrieveObject in class dkAbstractDatastore

[0573] public void updateObject(dkDataObject dataobj) throws DKException, Exception

[0574] Updates a data-object.

[0575] Parameters:

[0576] ddo—the data-object to be updated.

[0577] Throws: DKException

[0578] if error occurs in the datastore

[0579] Overrides:

[0580] updateObject in class dkAbstractDatastore

[0581] public void commit( ) throws DKException

[0582] Commits all activities since the last commit.

[0583] Throws: DKException

[0584] is thrown since federated datastore does not support transaction scope for now.

[0585] Overrides:

[0586] commit in class dkAbstractDatastore

[0587] public void rollbacks throws DKException

[0588] Rolls back all activities since the last commit.

[0589] Throws: DKException

[0590] is thrown since Federated does not support transaction scope for now.

[0591] Overrides:

[0592] rollback in class dkAbstractDatastore

[0593] public boolean isconnected( )

[0594] Checks to see if the datastore is connected

[0595] Returns:

[0596] true if connected, false otherwise

[0597] Overrides:

[0598] isConnected in class dkAbstractDatastore

[0599] public DKHandle connections throws Exception Gets the connection handle for the datastore.

[0600] Returns:

[0601] the connection handle

[0602] Overrides:

[0603] connection in class dkAbstractDatastore

[0604] public DKHandle handle(String type) throws Exception

[0605] Gets a datastore handle.

[0606] Parameters:

[0607] type—type of datastore handle wanted

[0608] Returns:

[0609] a datastore handle

[0610] Overrides:

[0611] handle in class dkAbstractDatastore

[0612] public String userName( )

[0613] Gets the user name that user used to logon to the datastore.

[0614] Returns:

[0615] the userid that user used to logon

[0616] Overrides:

[0617] userName in class dkAbstractDatastore

[0618] public String datastoreName( ) throws Exception

[0619] Gets the name of this datastore object. Usually it represents a datastore source's server name.

[0620] Returns:

[0621] datastore name

[0622] Overrides:

[0623] datastoreName in class dkAbstractDatastore

[0624] public String datastoreType( ) throws Exception

[0625] Gets the datastore type for this datastore object.

[0626] Returns:

[0627] datastore type

[0628] Overrides:

[0629] datastoreType in class dkAbstractDatastore

[0630] public dkDatastoreDef datastoreDef( ) throws DKException, Exception

[0631] Gets datastore definition.

[0632] Returns:

[0633] the meta-data (dkDatastoreDef) of this datastore

[0634] Overrides:

[0635] datastoreDef in class dkAbstractDatastore

[0636] public dkcollection listEntities( ) throws DKException, Exception

[0637] Gets a list of federated entities from Federated server.

[0638] Returns:

[0639] a collection of dkEntityDef

[0640] Throws: DKException

[0641] if error occurs

[0642] Overrides:

[0643] listEntities in class dkAbstractDatastore

[0644] public String[ ] listEntityNames( ) throws DKException, Exception

[0645] Gets a list of federated entities names from Federated server.

[0646] Returns:

[0647] an array of names

[0648] Throws: DKException

[0649] if error occurs

[0650] Overrides:

[0651] listEntityNames in class dkAbstractDatastore

[0652] public String[ ] listTextEntityNames( ) throws DKException, Exception

[0653] Gets a list of federated text search entities names from Federated server.

[0654] Returns:

[0655] an array of names

[0656] Throws: DKException

[0657] if error occurs

[0658] public String[ ] listParmEntityNames( ) throws DKException, Exception

[0659] Gets a list of federated parametric search entities names from Federated server.

[0660] Returns:

[0661] an array of names

[0662] Throws: DKException

[0663] if error occurs

[0664] Overrides:

[0665] listEntityAttrs

[0666] public dkcollection listEntityAttrs(String entityName) throws DKException, Exception

[0667] Gets a list of attributes for a given entity name.

[0668] Parameters:

[0669] entityName—name of entity to retrieve attributes for

[0670] Returns:

[0671] a dkCollection of dkAttrDef objects

[0672] Throws: DKException

[0673] if the entity name does not exist

[0674] Overrides:

[0675] listEntityAttrs in class dkAbstractDatastore

[0676] public String[ ] listEntityAttrNames(String entityName) throws DKException, Exception

[0677] Gets a list of attribute names for a given entity name.

[0678] Parameters:

[0679] entityName—name of entity to retrieve attribute names for

[0680] Returns:

[0681] an array of attribute names

[0682] Throws: DKException

[0683] if the entity name does not exist

[0684] Overrides:

[0685] listEntityAttrNames in class dkAbstractDatastore

[0686] public String registerMapping(DKNVPair sourceMap) throws DKException, Exception

[0687] Registers a mapping definition to this datastore. Mapping is done by entities.

[0688] Parameters:

[0689] sourceMap—source name and mapping, a DKNVPair class with the following possible values:

[0690] (“BUFFER”,): buffer_ref is a reference to a string in memory

[0691] (“FILE”,): file_name is the name of the file containing the mapping

[0692] (“URL”,): URL-address location of the mapping

[0693] (“LDAP”,): LDAP file-name

[0694] (“SCHEMA”,): a reference to a dkSchemaMapping object defining the mapping. Currently, only “SCHEMA” option is supported, others may be added later.

[0695] Returns:

[0696] the name of the mapping definition.

[0697] Overrides:

[0698] registerMapping in class dkbstractDatastore

[0699] See Also:

[0700] unRegisterMapping

[0701] public void unRegisterMapping(String mappingName) throws DKException, Exception

[0702] Unregisters mapping information from this datastore.

[0703] Parameters:

[0704] mappingname—name of the mapping information

[0705] Overrides:

[0706] unRegisterMapping in class dkAbstractDatastore

[0707] See Also:

[0708] registerMapping

[0709] public String[ ] listMappingNames( ) throws DKException, Exception

[0710] Gets the list of the registered mappings for this datastore.

[0711] Returns:

[0712] an array of registered mapping objects' names. The array length would be zero if there is no mapping registered.

[0713] Overrides:

[0714] listMappingNames in class dkAbstractDatastore

[0715] See Also:

[0716] registerMapping

[0717] public dkSchemaMapping getMapping(String mappingName) throws DKException, Exception

[0718] Gets mapping information from this datastore.

[0719] Parameters:

[0720] mappingName—name of the mapping information

[0721] Returns:

[0722] the schema mapping object

[0723] Overrides:

[0724] getMapping in class dkAbstractDatastore

[0725] See Also:

[0726] registerMapping

[0727] public synchronized dkextension getExtension(String extensionName) throws DKException, Exception

[0728] Gets the extension object from a given extension name.

[0729] Parameters:

[0730] extensionname—name of the extension object.

[0731] Returns:

[0732] extension object.

[0733] Overrides:

[0734] getextension in class dkAbstractDatastore

[0735] public synchronized void addExtension(String extensionName,

[0736] dkExtension extensionObj) throws DKException, Exception

[0737] Adds a new extension object.

[0738] Parameters:

[0739] extensionName—name of new extension object

[0740] extensionObj—the extension object to be set

[0741] Overrides:

[0742] add Extension in class dkAbstractDatastore

[0743] public synchronized void removeExtension(String extensionName) throws DKException, Exception

[0744] Removes an existing extension object.

[0745] Parameters:

[0746] extensionName—name of extension object to be removed

[0747] Overrides:

[0748] removeExtension in class dkAbstractDatastore

[0749] public synchronized String[ ] listExtensionNames( ) throws DKException, Exception

[0750] Gets the list of extension objects' names.

[0751] Returns:

[0752] an array of extension objects' names

[0753] Overrides:

[0754] listExtensionNames in class dkAbstractDatastore

[0755] public DKDDO createDDO(String objectType,

[0756] int Flags) throws DKException, Exception

[0757] Creates a new DDO with object type, properties and attributes set for a given backend server.

[0758] Parameters:

[0759] objectType—the object type

[0760] Flags—to indicate various options and to specify more detailed characteristics of the DDO to create. For example, it may be a directive to create a document DDO, a folder, etc.

[0761] Returns:

[0762] a new DDO of the given object type with all the properties and attributes set, so that the user only needs to set the attribute values

[0763] Overrides:

[0764] createDDO in class dkAbstractDatastore

[0765] public dkcollection listSearchTemplates( ) throws DKException, Exception

[0766] Gets a list search templates from a federated server.

[0767] Returns:

[0768] a DKSequentialCollection of search templates

[0769] Throws: DKException

[0770] if internal datastore error occurs

[0771] public String[ ] listSearchTemplateNames( ) throws DKException, Exception

[0772] Gets a list search templates' names from a federated server.

[0773] Returns:

[0774] an array of search template names

[0775] Throws: DKException

[0776] if internal datastore error occurs

[0777] public dkSearchTemplate getSearchTemplate(String templateName) throws DKException, Exception

[0778] Gets a search template information from a given template name.

[0779] Returns:

[0780] dkSearchTemplate object.

[0781] Throws: DKException

[0782] if internal datastore error occurs

[0783] public void destroy( ) throws DKException, Exception

[0784] Destroys datastore—datastore cleanup if needed

[0785] Overrides:

[0786] destroy in class dkAbstractDatastore

[0787] public synchronized string addRemoveCursor (dkResultSetCursor iCurt int action)

[0788] throws DKException, Exception

[0789] public dkDatastore datastoreByServerName (String dsType, String dsName)

[0790] throws DKException, Exception

[0791] Gets a reference to the specified datastore. The datastore must be connected, otherwise it will return null even if one is found. First, it will look in the free connection pool. If none found, it will look under the connection pool held by active cursors.

[0792] public void changePassword (String serverName,

[0793] String user Id,

[0794] String oldPwd,

[0795] String newPwd)

[0796] throws DKException, Exception

[0797] Changes the password of a given user Id for a specified server. Administrator only function.

[0798] Parameters:

[0799] userid—the user—id

[0800] oldPwd—the old password

[0801] newPwd—the new password

[0802] public void requestConnection (String serverName,

[0803] String userId,

[0804] Stringpasswd,

[0805] String connectString)

[0806] throws DKException, Exception

[0807] Requests a connection to a particular server with the given userid, password & connectString.

[0808] Parameters:

[0809] userId—the user Id

[0810] passwd—the password

[0811] connectString—the connect string to logon

[0812] public void excludeServer (Sting serverName, String templateName)

[0813] throws DKException, Exception

[0814] Requests the named server to be skipped for the named search template.

[0815] Parameters:

[0816] serverName—a back end server name

[0817] templateName—a search template name

[0818] public boolean isServerExcluded (String serverName, String templateName)

[0819] throws DKException, Exception, java.rmi. RemoteException

[0820] Checks if the given server is in the excluded list for the named search template.

[0821] Parameters:

[0822] serverName—a back end server name

[0823] templateName—a search template name

[0824] Returns:

[0825] true or false

[0826] public String[ ] listExcludedServers(String templateName) throws DKException, Exception

[0827] Lists all the excluded servers for the named search template

[0828] Parameters:

[0829] s—templateName—a search template name

[0830] Returns:

[0831] an array of server names that were excluded during search

[0832] public void clearExcludedServers(String templateName) throws DKException, Exception

[0833] Clears all the excluded servers for the named search template

[0834] Parameters:

[0835] s—templateName—a search template name

[0836] The following is sample syntax of a federated query string. However, it is to be understood that other syntax, including other parameters, may be used for the federated query string without departing from the scope of the invention.

[0837] There are several mechanisms for users to submit federated queries for execution. For example, users can create a federated query string and pass it to a federated query object and then invoke an execute or evaluate method on that object to trigger the query processing. Alternatively, a user can pass the federated query string to the execute or evaluate method in the federated datastore to process the query directly. The query string will be parsed into a federated query canonical form (query expression), which is essentially a datastore neutral representation of the query. In case the input query comes from a graphical user interface (GUI) based application, the query does not need to be parsed and the corresponding canonical form can be directly constructed.

[0838] The query canonical form is the input for the federated query processor module. This module will perform the following tasks:

[0839] Query translation. Translates the query canonical form into several native queries that corresponds to each native datastore associated to this federated datastore. The translation information is obtained from the schema mapping.

[0840] Data conversion. Converts data in the query into a native data type for each of the associated native datastores. This process uses the mapping and conversion mechanisms described in the schema mapping.

[0841] Data filtering. Filters only the relevant data during the construction of native queries.

[0842] Each native query is submitted to the corresponding native datastore for execution. Initially, the results returned are cursors to the data in each datastore.

[0843] The end-result of an initial query is a federated result set cursor object, which is a virtal collection (i.e., at this time, data has not actually been retrieved) of cursors to objects in each of the native datastores.

[0844] The user can retrieve the actual data using a fetch. When a fetch is issued for data, the data is returned by the native datastores to the federated query results processor module, which will do the following:

[0845] Data conversion. Converts data from the native type into a federated type according to the mapping information.

[0846] Data filtering. Filters the results to include only the requested data Result merging. Merges the results from several native datastores into a federated collection.

[0847] The federated result set cursor object provides the facility to separate query results according to the source native datastores. To do such a processing, the user/application may either use the federated cursor to fetch data or a native datastore cursor to fetch data from a particular datastore.

[0848] A FederatedQuery represents and executes queries across heterogeneous datastores. This query can be a combination of a DL parametric query, OnDemand query, and other query types involving supported datastores. To retrieve data from each datastore, the federated datastore delegates the query processing task to each of the native datastores.

[0849] The following methods are part of the federated query class:

[0850] public DKFederatedQuery(dkDatastore creator,

[0851] String queryString)

[0852] Constructs a Federated query.

[0853] Parameters:

[0854] creator—datastore

[0855] queryString—a query string

[0856] public DKFederatedQuery(dkDatastore creator,

[0857] DKCQExpr queryExpr)

[0858] Constructs a Federated query

[0859] Parameters:

[0860] creator—datastore

[0861] queryExpr—a query expression

[0862] public DKFederatedQuery(DKFederatedQueryfromQuery)

[0863] Constructs a Federated query from a Federated query object.

[0864] Parameters:

[0865] fromQuery—Federated query

[0866] public voidprepare(DKNVPair params[ ]) throws DKException, Exception

[0867] Prepares a query.

[0868] Parameters:

[0869] params—additional prepare query option in name/value pair

[0870] public void execute(DKNVPair params[ ]) throws DKException, Exception

[0871] Executes a query.

[0872] Parameters:

[0873] params—additional query option in name/value pair

[0874] public int status( )

[0875] Gets query status.

[0876] Returns:

[0877] query status

[0878] public Object result( ) throws DKException, Exception

[0879] Gets query result.

[0880] Returns:

[0881] query result in a DKResults object

[0882] public dkResultSetCursor resultSetCursor( ) throws DKException, Exception

[0883] Gets query result.

[0884] Returns:

[0885] query result in a dkResultSetCursor object

[0886] public short qlType( )

[0887] Gets query type.

[0888] Returns:

[0889] query type

[0890] public String querystring( )

[0891] Gets query string

[0892] Returns:

[0893] query string

[0894] public dkDatastore getDatastore( )

[0895] Gets the reference to the owner datastore object.

[0896] Returns:

[0897] the dkDatastore object

[0898] public void setDatastore(dkDatastore ds) throws DKException, Exception

[0899] Sets the reference to the owner datastore object.

[0900] Parameters:

[0901] ds—a datastore

[0902] public String getName( )

[0903] Gets query name.

[0904] Returns:

[0905] name of this query

[0906] public void setName(String name)

[0907] Sets query name.

[0908] Parameters:

[0909] name—new name to be set to this query object

[0910] public int numberOfResults( )

[0911] Gets the number of query results.

[0912] Returns:

[0913] number of query results

[0914] 3. Digital Library Datastore

[0915] DKDatastoreDL is a specific version of dkDatastore used to implement the Digital Library/Visual Info datastore. It provides Documents, Parts and Folders storage and retrieval mechanisms, as well as search and other document processing capabilities supported by Digital Library. An example class definition for DKDatastoreDL is set forth below.

[0916] The following methods are part of the DKDatastoreDL class:

[0917] public DKDatastoreDL( ) throws DKException, Exception

[0918] Constructs the datastore and initializes the datastore.

[0919] public DKDatastoreDL(String configuration) throws DKException, Exception

[0920] Constructs the datastore and initializes the datastore.

[0921] public void connect(String datastore_name,

[0922] String user_name,

[0923] String authentication,

[0924] String connect_string) throws DKException, Exception

[0925] Connects to a datastore.

[0926] Parameters:

[0927] datastore_name—the datastore name used for connection

[0928] user_name—the user name used for connection

[0929] authentication—the authentication used for connection

[0930] connect_string—the connect sting used for connection. This is used to

[0931] provide additional connection options.

[0932] Overrides:

[0933] connect in class dkAbstracDatastore

[0934] public void disconnect( ) throws DKException, Exception

[0935] Disconnects from a datastore.

[0936] Overrides:

[0937] disconnect in class dkAbstractDatastore

[0938] public Object getOption(int option) throws DKException, Exception

[0939] Gets a datastore option.

[0940] Parameters:

[0941] option—the option identifier

[0942] Returns:

[0943] an option value

[0944] Overrides:

[0945] getOption in class dkAbstractDatastore

[0946] public void setOption(int option,

[0947] Object value) throws DKException, Exception

[0948] Sets a datastore option.

[0949] Parameters:

[0950] option—the option identifier

[0951] value—the option value

[0952] Overrides:

[0953] setOption in class dkAbstractDatastore

[0954] public Object evaluate(String command,

[0955] short commandLangType,

[0956] DKNVPair params[ ]) throws DKException, Exception

[0957] Evaluates the query.

[0958] Parameters:

[0959] command—a query string

[0960] commandlang—a query type

[0961] params—additional query option in name/value pair

[0962] Returns:

[0963] a collection of the results

[0964] Overrides:

[0965] evaluate in class dkAbstractDatastore

[0966] public Object evaluate(dkquery query) throws DKException, Exception

[0967] Evaluates the query.

[0968] Parameters:

[0969] query—a query object

[0970] Returns:

[0971] a collection of the results

[0972] Overrides:

[0973] evaluate in class dAbstractDatastore

[0974] public Object evaluate(DKCQExpr qe) throws DKException, Exception

[0975] Evaluates the query.

[0976] Parameters:

[0977] qe—a common query expression object

[0978] Returns:

[0979] a collection of the results

[0980] Overrides:

[0981] evaluate in class dkAbstractDatastore

[0982] public dkResultSetCursor execute(String command,

[0983] short commandLangType,

[0984] DKNVPairparams[ ]) throws DKException, Exception

[0985] Executes the query.

[0986] Parameters:

[0987] command—a query sting

[0988] commandlang—a query type

[0989] params—additional query option in name/value pair

[0990] Returns:

[0991] resultSetCursor which represents a datastore cursor.

[0992] Overrides:

[0993] execute in class dkAbstractDatastore

[0994] public dkResultSetCursor execute(dkQuery query) throws DKException, Exception

[0995] Executes the query.

[0996] Parameters:

[0997] query—a query object

[0998] Returns:

[0999] resultSetCursor which represents a datastore cursor.

[1000] Overrides:

[1001] execute in class dkAbstractDatastore

[1002] public dkResultSetCursor execute(DKCQExpr cqe) throws DKException, Exception

[1003] Executes a query expression and returns a result set cursor

[1004] Parameters:

[1005] cqe—a common query expression object

[1006] Returns:

[1007] resultSetCursor which represents a datastore cursor.

[1008] Overrides:

[1009] execute in class dkAbstractDatastore

[1010] public void executeWithCallback(dkQuery query,

[1011] dkcallback callbackObj) throws DKException, Exception

[1012] Executes the query with callback function.

[1013] Parameters:

[1014] qo—a query object

[1015] callbackObj—a dkCallback object

[1016] Overrides:

[1017] executeWithCallback in class dkAbstractDatastore

[1018] public void executeWithCallback(String command,

[1019] short commandLangType,

[1020] DKNVAPair params[ ],

[1021] dkcallback callbackObj) throws DKException, Exception

[1022] Executes the query with callback function.

[1023] Parameters:

[1024] command—a query string

[1025] commandLang—a query type

[1026] params—additional query option in name/value pair

[1027] callbackObj—a dkCallback object

[1028] Overrides:

[1029] executeWithCallback in class dkAbstractDatastore

[1030] public void executeWithCallback(DKCQExpr qe,

[1031] dkcallback callbackObj) throws DKException, Exception

[1032] Executes the query with callback function.

[1033] Parameters:

[1034] qe—a common query expression object

[1035] callbackObj—a dkCallback object

[1036] Overrides:

[1037] executeWithCallback in class dkAbstractDatastore

[1038] public dkQuery createQuery(String command,

[1039] short commandLangType,

[1040] DKNVPair params[ ]) throws DKException, Exception

[1041] Creates a query object.

[1042] Parameters:

[1043] command—a query string

[1044] commandlang—a query type

[1045] params—additional query option in name/value pair

[1046] Returns:

[1047] a query object

[1048] Overrides:

[1049] createQuery in class dkAbstractDatastore

[1050] public dkQuery createQuery(DKCQExpr qe) throws DKException, Exception

[1051] Creates a query object.

[1052] Parameters:

[1053] qe—a common query expression object

[1054] Overrides:

[1055] createQuery in class dkAbstractDatastore

[1056] public void addObject(dkDataObject ado) throws DKException, Exception

[1057] Adds this data-object to the DL datastore.

[1058] Parameters:

[1059] ddo—the data-object to be added to this datastore

[1060] Overrides:

[1061] addObject in class dkAbstractDatastore

[1062] See Also:

[1063] add

[1064] public void deleteObject(dkDataObject ddo) throws DKException, Exception

[1065] Deletes this data-object from this datastore.

[1066] Parameters:

[1067] ddo—the data-object to be deleted from this datastore

[1068] Overrides:

[1069] deleteObject in class dkAbstractDatastore

[1070] See Also:

[1071] del

[1072] public void retrieveObject(dkDataObject ddo) throws DKException, Exception

[1073] Retrieves the data-object from this datastore.

[1074] Parameters:

[1075] ddo—the data-object to be retrieved from this datastore

[1076] Overrides:

[1077] retrieveObject in class dkAbstractDatastore

[1078] See Also:

[1079] retrieve

[1080] public void updateObject(dkDataObject ddo) throws DKException, Exception

[1081] Updates the data-object in this datastore.

[1082] Parameters:

[1083] ddo—the data-object to be updated in this datastore

[1084] Overrides:

[1085] updateObject in class dkAbstractDatastore

[1086] See Also:

[1087] update

[1088] public void moveObject(dkDataObject ddo,

[1089] String entityName) throws DKException, Exception

[1090] Moves the data-object from one index class to another in this datastore.

[1091] Parameters:

[1092] ddo—the data-object to be move in this datastore entityName—new entity name to move this data-object to

[1093] public void startTransaction( ) throws DKException, Exception

[1094] Starts a transaction

[1095] public void commit( ) throws DKException, Exception

[1096] Commits a datastore transaction

[1097] Overrides:

[1098] commit in class dkAbstractDatastore

[1099] public void rollback( ) throws DKException, Exception

[1100] Rolls back a datastore transaction

[1101] Overrides:

[1102] rollback in class dkAbstractDatastore

[1103] public boolean isconnected( ) throws Exception

[1104] Checks to see if the datastore is connected.

[1105] Returns:

[1106] true if connected

[1107] Overrides:

[1108] isConnected in class dkAbstractDatastore

[1109] public String datastoreName( ) throws Exception

[1110] Gets the name of this datastore object. Usually it represents a datastore source's server name.

[1111] Returns:

[1112] datastore name

[1113] Overrides:

[1114] datastoreName in class dkAbstracDatastore

[1115] public String datastoreType( ) throws Exception

[1116] Gets the datastore type for this datastore object

[1117] Returns:

[1118] datastore type

[1119] Overrides:

[1120] datastoreType in class dkAbstractDatastore

[1121] public DKHandle connection( ) throws Exception

[1122] Gets the connection handle for a datastore

[1123] Returns:

[1124] connection handle

[1125] Overrides:

[1126] connection in class dkAbstractDatastore

[1127] public DKHandle handle(String type) throws Exception

[1128] Gets a datastore handle

[1129] Parameters:

[1130] type—type of datastore handle wanted

[1131] Returns:

[1132] a datastore handle

[1133] Overrides:

[1134] handle in class dkAbstractDatastore

[1135] public DKHandle transactionConnection( ) throws DKException, Exception

[1136] Gets the transaction handle for a datastore

[1137] Returns:

[1138] transaction handle

[1139] public String userName( ) throws Exception

[1140] Gets the user name for this datastore object

[1141] Returns:

[1142] user name

[1143] Overrides:

[1144] userName in class dkAbstractDatastore

[1145] public dkCollection listDataSources( ) throws DKException, Exception

[1146] List the available datastore sources that can be used to connect with.

[1147] Returns:

[1148] a collection of server definitions

[1149] Overrides:

[1150] listDataSources in class dkAbstractDatastore

[1151] public String[ ] listDataSourceNames( ) throws DKException, Exception

[1152] Lists the available datastore source names that can be used to connect with.

[1153] Returns:

[1154] an array of server names

[1155] Overrides:

[1156] listDataSourceNames in class dkAbstractDatastore

[1157] public Object listServers( ) throws DKException, Exception

[1158] Lists the available datastore sources that can be used to connect with. Note: listservers( ) is deprecated. Replace by listDataSources.

[1159] Returns:

[1160] a collection of server definitions

[1161] Overrides:

[1162] listServers in class dkAbstractDatastore

[1163] See Also:

[1164] listDataSources

[1165] public Object listschema( ) throws DKUsageError

[1166] Lists the entities that belong to this datastore. Note: listschema( ) is deprecated. Replace by listentities.

[1167] Returns:

[1168] an object that contains the schema

[1169] Overrides:

[1170] listSchema in class dkAbstractDatastore

[1171] See Also:

[1172] listEntities

[1173] public Object listSchemaAttributes(String schemaEntry)throwsDKUsageError,

[1174] DKDatastoreAccessError

[1175] Lists the attributes that belong to a schema Note: listSchemaAttributes( ) is deprecated. Replace by listEntityAttributes.

[1176] Parameters:

[1177] schemaEntry—the name of the schema

[1178] Returns:

[1179] an object that contains the attributes that belong to this schema

[1180] Overrides:

[1181] listSchemaAttributes in class dkAbstractDatastore

[1182] See Also:

[1183] listEntityAttrs

[1184] public dkCollection listEntities( ) throws DKException, Exception

[1185] Gets a list of entities from persistent datastore

[1186] Returns:

[1187] a collection of entity defs

[1188] Throws: DKException

[1189] if error occurs

[1190] Overrides:

[1191] listEntities in class dkAbstractDatastore

[1192] public String[ ] listEntityNames( ) throws DKException, Exception

[1193] Gets a list of entity names from persistent datastore

[1194] Returns:

[1195] an array of entity names

[1196] Throws: DKException

[1197] if error occurs

[1198] Overrides:

[1199] listEntityNames in class dkAbstractDatastore

[1200] public dkcollection listEntityAttrs(String entityName) throws DKException, Exception

[1201] Gets a list of attributes for a given entity name.

[1202] Parameters:

[1203] entityName—name of entity to retrieve attributes for

[1204] Returns:

[1205] a dkCollection of dkAttrDef objects

[1206] Throws: DKException

[1207] if the entity name does not exist

[1208] Overrides:

[1209] listEntityAttrs in class dkAbstractDatastore

[1210] public String[ ] listEntityAttrNames(String entityName) throws DKException, Exception

[1211] Gets a list of attribute names for a given entity name.

[1212] Parameters:

[1213] entityName—name of entity to retrieve attribute names for

[1214] Returns:

[1215] an array of attribute names

[1216] Throws: DKException

[1217] if the entity name does not exist

[1218] Overrides:

[1219] listEntityAttrNames in class dkAbstractDatastore

[1220] public void wake UpService(String searchEngine) throws DKException, Exception

[1221] Wakes up a user exit to process search index request. Note: wakeUpService( ) is deprecated. Replace by invokeSearchEngine.

[1222] Parameters:

[1223] searchengine—search engine name (SM)

[1224] See Also:

[1225] invokeSearchEngine

[1226] public void invokeSearchEngine(String searchEngine,

[1227] String searchIndex) throws DKException, Exception

[1228] Invokes a user exit to process search index request.

[1229] Parameters:

[1230] searchEngine—search engine name (ie SM or QBIC)

[1231] searchIndex—search index (ie TM-TMINDEX or QBICDB-QBICCAT-QBICSRV)

[1232] public dkDatastoreDef datastoreDef( )

[1233] Gets datastore definition

[1234] Returns:

[1235] the meta-data (dkDatastoreDef) of this datastore

[1236] Overrides:

[1237] datastoreDef in class dkAbstractDatastore

[1238] public DKWorkFlowServiceDL createWorkFlowService( ) throws DKException, Exception

[1239] Gets work flow service

[1240] Returns:

[1241] the a work flow service for this datastore

[1242] public String registerMapping(DKNVPair sourceMap) throws DKException, Exception

[1243] Registers a mapping definition to this datastore. Mapping is done by entities.

[1244] Parameters:

[1245] sourceMap—source name and mapping, a DKNVPair class with the following possible values:

[1246] (“BUFFER”,): buffer_ref is a reference to a string in memory

[1247] (“FILE”,): file_name is the name of the file containing the mapping

[1248] (“URL”,): URL-address location of the mapping

[1249] (“LDAP”,): LDAP file-name

[1250] “SCHEMA”,): a reference to a dkSchemaMapping object defining the mapping. Currently, only “SCHEMA” option is supported, others may be added later.

[1251] Returns:

[1252] the name of the mapping definition.

[1253] Overrides:

[1254] registerMapping in class dkAbstractDatastore

[1255] See Also:

[1256] unRegisterMapping

[1257] public void unRegisterMapping(String mappingName) throws DKException, Exception

[1258] Unregisters mapping information from this datastore.

[1259] Parameters:

[1260] mappingName—name of the mapping information

[1261] Overrides:

[1262] unRegisterMapping in class dkAbstractDatastore

[1263] See Also:

[1264] registerMapping

[1265] public String[ ] listMappingNames( ) throws DKException, Exception

[1266] Gets the list of the registered mappings from this datastore.

[1267] Returns:

[1268] an array of registered mapping objects' names

[1269] Overrides:

[1270] listMappingNames in class dkAbstractDatastore

[1271] See Also:

[1272] registerMapping

[1273] public dkSchemaMapping getMapping(String mappingName) throws DKException, Exception

[1274] Gets a mapping information from this datastore.

[1275] Parameters:

[1276] mappingName—name of the mapping information

[1277] Returns:

[1278] the schema mapping object

[1279] Overrides:

[1280] getMapping in class dkAbstractDatastore

[1281] See Also:

[1282] registerMapping

[1283] public synchronized dkExtension getExtension(String extensionName) throws DKException, Exception

[1284] Gets the extension object from a given extenstion name.

[1285] Parameters:

[1286] extensionname—name of the extension object.

[1287] Returns:

[1288] extension object.

[1289] Overrides:

[1290] getextension in class dkAbstractDatastore

[1291] public synchronized void addExtension(String extensionName,

[1292] dkExtension extensionObj) throws DKException, Exception

[1293] Adds a new extension object.

[1294] Parameters:

[1295] extensionname—name of new extension object

[1296] extensionObj—the extension object to be set

[1297] Overrides:

[1298] addextension in class dkAbstractDatastore

[1299] public synchronized void removeExtension(String extensionName) throws DKException, Exception

[1300] Removes an existing extension object

[1301] Parameters:

[1302] extensionName—name of extension object to be removed

[1303] Overrides:

[1304] removeExtension in class dkAbstractDatastore

[1305] public synchronized String[ ] listExtensionNames( ) throws DKException, Exception

[1306] Gets the list of extension objects' names

[1307] Returns:

[1308] an array of extension objects' names

[1309] Overrides:

[1310] listExtensionNames in class dkAbstractDatastore

[1311] public DKDDO createDDO(String objectType,

[1312] int Flags) throws DKException, Exception

[1313] Creates a new DDO with object type, properties and attributes set for a given backend server.

[1314] Parameters:

[1315] objectType—the object type user wants to create

[1316] Flags—to indicate various options to specify more detailed

[1317] characteristics of the DDO to create. For example, it may be a directive to create a document DDO, a folder, etc.

[1318] Returns:

[1319] a new DDO of the given object type with all the properties and

[1320] attributes set, so that the user only need to set the attribute values

[1321] Overrides:

[1322] createDDO in class dkAbstractDatastore

[1323] public void destroy( ) throws DKException, Exception

[1324] Destroys datastore—datastore cleanup if needed

[1325] Overrides:

[1326] destroy in class dkAbstractDatastore

[1327] public boolean isCheckedOut(dkDataObject dobj) throws DKUsageError,

[1328] DKDatastoreAccessError

[1329] Checks whether a document or folder item is checked out from datastore

[1330] Parameters:

[1331] dobj—data object (document or folder item)

[1332] Returns:

[1333] a boolean indicating if it is checked out or not

[1334] public String checkedOutUserid(dkDataObject dobj) throws DKUsageError, DKDatastoreAccessError

[1335] Lists the userid who checked out the document or folder

[1336] Parameters:

[1337] dobj—data object (document or folder item)

[1338] Returns:

[1339] a userid or empty string (i.e., not checked out)

[1340] public void unlockCheckedOut(dkDataObject dobj) throws DKUsageError,

[1341] DKDatastoreAccessError

[1342] Unlocks the checked-out document or folder item

[1343] Parameters:

[1344] dobj—data object (document or folder item)

[1345] public void checkOut(dkDataObject dobj) throws DKUsageError, DKDatastoreAccessError

[1346] Checks out document or folder item from datastore

[1347] Parameters:

[1348] dobj—data object (document or folder item)

[1349] public void checkln(dkDataObject dobj) throws DKUsageError, DKDatastoreAccessError

[1350] Checks in document or folder item from datastore

[1351] Parameters:

[1352] dobj—data object (document or folder item)

[1353] public void changePassword(String userId,

[1354] String oldPwd,

[1355] String newPwd) throws DKException, Exception

[1356] Changes LS user password

[1357] Overrides:

[1358] changepassword in class dkAbstractDatastore

[1359] public synchronized dkXDO retrieveFormOverlay(String objid) throws DKException, Exception

[1360] Retrieves the form overlay object

[1361] Parameters:

[1362] id—the id string to retrieve the object

[1363] Returns:

[1364] the form overlay xdo object

[1365] public void moveObject (dkDataObject ddo, String entityName) throws DKException, Exception

[1366] Moves the data object from one index class to another.

[1367] Parameters:

[1368] ddo—data object to be moved

[1369] entityName—target index class for this data object

[1370] public DKCQExpr translate(DKCQExpr cqe) throws DKException, Exception

[1371] Translates a query expression into a native query expression processable by this datastore.

[1372] Parameters:

[1373] cqe—the input compound query expression

[1374] Returns:

[1375] a translated query expression or null if the expression is invalid

[1376] 4. OBIC Datastore

[1377] DKDatastoreQBIC is a specific version of dkDatastore used to implement the QBIC datastore. An example class definition for DKDatastoreQBIC is set forth below.

[1378] The following methods are part of the DKDatastoreQBIC class:

[1379] public DKDatastoreQBICO throws DKException, Exception

[1380] Constructs the datastore and initializes the datastore.

[1381] public DKDatastoreQBIC(String configuration) throws DKException, Exception

[1382] Constructs the datastore and initializes the datastore.

[1383] public void connect(String datastore_name, String user_name, String authentication, String connect_string) throws DKException, Exception

[1384] Connects to a datastore.

[1385] Parameters:

[1386] datastore_nane—the datastore name used for connection

[1387] user_name—the user name used for connection

[1388] authentication—the authentication used for connection

[1389] connect_string—the connect string used for connection. This is used to

[1390] provide additional connection options.

[1391] Overrides:

[1392] connect in class dkAbstractDatastore

[1393] public void disconnect( ) throws DKException, Exception

[1394] Disconnects to a datastore.

[1395] Overrides:

[1396] disconnect in class dkAbstractDatastore

[1397] public Object getOption(int option) throws DKException, Exception

[1398] Gets a datastore option.

[1399] Parameters:

[1400] option—the option identifier

[1401] Returns:

[1402] an option value

[1403] Overrides:

[1404] getOption in class dkAbstractDatastore

[1405] public void setOption(int option,

[1406] Object value) throws DKException, Exception

[1407] Sets a datastore option.

[1408] Parameters:

[1409] option—the option identifier

[1410] value—the option value

[1411] Overrides:

[1412] setOption in class dkAbstractDatastore

[1413] public Object evaluate(String command,

[1414] short commandLangType,

[1415] DKNVPair params[ ]) throws DKException, Exception

[1416] Evaluates the query.

[1417] Parameters:

[1418] command—a query string

[1419] commandLang—a query type

[1420] params—additional query option in name/value pair

[1421] Returns:

[1422] a collection of the results

[1423] Overrides:

[1424] evaluate in class dkAbstractDatastore

[1425] public Object evaluate(dkQuery query) throws DKException, Exception

[1426] Evaluates the query.

[1427] Parameters:

[1428] query—a query object

[1429] Returns:

[1430] a collection of the results

[1431] Overrides:

[1432] evaluate in class dkAbstractDatastore

[1433] public Object evaluate(DKCQExpr qe) throws DKException, Exception

[1434] Evaluates the query.

[1435] Parameters:

[1436] qe—a common query expression object

[1437] Returns:

[1438] a collection of the results

[1439] Overrides:

[1440] evaluate in class ckAbstractDatastore

[1441] public dkResultSetCursor execute(String command,

[1442] short commandLangType,

[1443] DKNVPairparams[ ]) throws DKException, Exception

[1444] Executes the query.

[1445] Parameters:

[1446] command—a query string

[1447] commandLang—a query type

[1448] params—additional query option in name/value pair

[1449] Returns:

[1450] resultSetCursor which represents a datastore cursor.

[1451] Overrides:

[1452] execute in class dkAbstractDatastore

[1453] public dkResultSetCursor execute(dkQuery query) throws DKException, Exception

[1454] Executes the query.

[1455] Parameters:

[1456] query—a query object

[1457] Returns:

[1458] resultSetCursor which represents a datastore cursor.

[1459] Overrides:

[1460] execute in class dkAbstractDatastore

[1461] public dkResultSetCursor execute(DKCQExpr qe) throws DKException, Exception

[1462] Executes the query.

[1463] Parameters:

[1464] qe—a common query expression object

[1465] Returns:

[1466] resultSetCursor which represents a datastore cursor.

[1467] Overrides:

[1468] execute in class dkAbstractDatastore

[1469] public void executeWithCallback(dkQuery query,

[1470] dkcallback callbackObj) throws DKException, Exception

[1471] Executes the query with callback function.

[1472] Parameters:

[1473] qo—a query object

[1474] callbackObj—a dkCallback object

[1475] Overrides:

[1476] executeWithCallback in class dkAbstractDatastore

[1477] public void executeWithCallback(String command,

[1478] short commandLangType,

[1479] DKNVPair params[ ],

[1480] dkCallback callbackObj) throws DKException, Exception

[1481] Executes the query with callback function.

[1482] Parameters:

[1483] command—a query string

[1484] commandLang—a query type

[1485] params—additional query option in name/value pair

[1486] callbackObj—a dkCallback object

[1487] Overrides:

[1488] executeWithCallback in class dkAbstractDatastore

[1489] public void executeWithCallback(DKCQExpr qe,

[1490] dkcallback callbackObj) throws DKException, Exception

[1491] Executes the query with callback function.

[1492] Parameters:

[1493] qe—a common query expression object

[1494] callbackObj—a dkCallback object

[1495] Overrides:

[1496] executeWithCallback in class dkAbstractDatastore

[1497] public dkQuery createQuery(String command,

[1498] short commandLangType,

[1499] DKNVPairparams[ ]) throws DKException, Exception

[1500] Creates a query object.

[1501] Parameters:

[1502] command—a query string

[1503] commandLang—a query type

[1504] params—additional query option in name/value pair

[1505] Returns:

[1506] a query object

[1507] Overrides:

[1508] createQuery in class dkAbstractDatastore

[1509] public dkQuery createQuery(DKCQExpr qe) throws DKException, Exception

[1510] Creates a query object.

[1511] Parameters:

[1512] qe—a common query expression object

[1513] Overrides:

[1514] createQuery in class dkAbstractDatastore

[1515] public void addObject(dkDataObject ddo) throws DKException, Exception

[1516] Adds this ddo to this datastore.

[1517] Parameters:

[1518] ddo—the ddo to be added to this Datastore

[1519] Overrides:

[1520] addObject in class dkAbstractDatastore

[1521] public void deleteObject(dkDataObject ddo) throws DKException, Exception

[1522] Deletes this ddo from this datastore.

[1523] Parameters:

[1524] ddo—the ddo to be deleted from this Datastore

[1525] Overrides:

[1526] deleteObject in class dkAbstractDatastore

[1527] public void retrieveObject(dkDataObject ddo) throws DKException, Exception

[1528] Retrieves this ddo from this datastore.

[1529] Parameters:

[1530] ddo—the ddo to be retrieved from this Datastore

[1531] Overrides:

[1532] retrieveObject in class dkAbstractDatastore

[1533] public void updateObject(dkDataObject ddo) throws DKException, Exception

[1534] Updates this ddo in this datastore.

[1535] Parameters:

[1536] ddo—the ddo to be updated in this Datastore

[1537] Overrides:

[1538] updateObject in class dkAbstractDatastore

[1539] public void commit( ) throws DKException, Exception

[1540] Commits a datastore transaction

[1541] Overrides:

[1542] commit in class dkAbstractDatastore

[1543] public void rollback( ) throws DKException, Exception

[1544] Rolls back a datastore transaction

[1545] Overrides:

[1546] rollback in class dkAbstractDatastore

[1547] public boolean isconnected( ) throws Exception

[1548] Checks to see if the datastore is connected.

[1549] Returns:

[1550] true if connected

[1551] Overrides:

[1552] is Connected in class dkAbstractDatastore

[1553] public String datastoreName( ) throws Exception

[1554] Gets the name of his datastore object. Usually it represents a datastore source's server name.

[1555] Returns:

[1556] datastorename

[1557] Overrides:

[1558] datastorename in class dkAbstractDatastore

[1559] public String datastoreType() throws Exception

[1560] Gets the datastore type for this datastore object

[1561] Returns:

[1562] datastore type

[1563] Overrides:

[1564] datastoreType in class dkAbstractDatastore

[1565] public DKHandle connection( ) throws Exception

[1566] Gets the connection handle for a Datastore

[1567] Returns:

[1568] connection handle

[1569] Overrides:

[1570] connection in class dkAbstractDatastore

[1571] public DKHandle handle(String type) throws Exception

[1572] Gets a datastore handle

[1573] Parameters:

[1574] type—type of datastore handle wanted

[1575] Returns:

[1576] a datastore handle

[1577] Overrides:

[1578] handle in class dkAbstractDatastore

[1579] public String userName( ) throws Exception

[1580] Gets the user name for this datastore object

[1581] Returns:

[1582] user name

[1583] Overrides:

[1584] userName in class dkAbstracIDatastore

[1585] public dkcollection listDataSources( ) throws DKException, Exception

[1586] Lists the available datastore sources that can be used to connect with.

[1587] Returns:

[1588] a collection of server definitions

[1589] Overrides:

[1590] listDataSources in class dkAbstractDatastore

[1591] public String[ ] listDataSourceNames( ) throws DKException, Exception

[1592] Lists the available datastore source names that can be used to connect with.

[1593] Returns:

[1594] an array of server names

[1595] Overrides:

[1596] listDataSourceNames in class dkAbstractDatastore

[1597] public Object listServers( ) throws DKException, Exception

[1598] Lists the available datastore sources that can be used to connect with. Note: listservers( ) is deprecated. Replace by listDatasources.

[1599] Returns:

[1600] a collection of server definitions

[1601] Overrides:

[1602] listservers in class dkAbstractDatastore

[1603] See Also:

[1604] listDataSources

[1605] public Object listschema( ) throws DKException, Exception

[1606] Lists the entities that belong to this datastore. Note: listschema( ) is deprecated. Replace by listEntities.

[1607] Returns:

[1608] an object that contains the schema

[1609] Overrides:

[1610] listSchema in class dkAbstractDatastore

[1611] See Also:

[1612] listEntities

[1613] public Object listSchemaAttributes(String schemaEntry) throws DKException, Exception

[1614] Lists the attributes that belong to a schema. Note: listSchemaAttributes( ) is deprecated. Replace by listEntityAttributes.

[1615] Parameters:

[1616] schemaentry—the name of the schema.

[1617] Returns:

[1618] an object that contains the attributes that belong to this schema

[1619] Overrides:

[1620] listSchemaAttributes in class dkAbstractDatastore

[1621] See Also:

[1622] listEntityAttrs

[1623] public dkcollection listEntities( ) throws DKException, Exception

[1624] Gets a list of entities from persistent Datastore

[1625] Returns:

[1626] a collection of entity defs

[1627] Throws: DKException

[1628] if error occurs

[1629] Overrides:

[1630] listentities in class dkAbstractDatastore

[1631] public String[ ] listEntityNames( ) throws DKException, Exception

[1632] Gets a list of entity names from persistent Datastore

[1633] Returns:

[1634] an array of entity names

[1635] Throws: DKException

[1636] if error occurs

[1637] Overrides:

[1638] listEntityNames in class dkAbstractDatastore

[1639] public dkcollection listEntityAttrs(String entityName) throws DKException, Exception

[1640] Gets a list of attributes for a given entity name.

[1641] Parameters:

[1642] entityName—name of entity to retrieve attributes for

[1643] Returns:

[1644] a dkCollection of dkAttrDef objects

[1645] Throws: DKException

[1646] if the entity name does not exist

[1647] Overrides:

[1648] listEntityAttrs in class dkAbstractDatastore

[1649] public String[ ] listEntityAttrNames(String entityName) throws DKException, Exception

[1650] Gets a list of attribute names for a given entity name.

[1651] Parameters:

[1652] entityName—name of entity to retrieve attribute names for

[1653] Returns:

[1654] an array of attribute names

[1655] Throws: DKException

[1656] if the entity name does not exist

[1657] Overrides:

[1658] listEntityAttrNames in class dkAbstractDatastore

[1659] public void destroy( ) throws DKException, Exception

[1660] datastore destroy—datastore cleanup if needed

[1661] Overrides:

[1662] destroy in class dkAbstractDatastore

[1663] public void createDatabase(String database_name) throws DKException, Exception

[1664] Create image search database

[1665] Parameters:

[1666] database_name—database name

[1667] public void deleteDatabase(String database_name) throws DKException, Exception

[1668] Deletes image search database

[1669] Parameters:

[1670] database_name—database name

[1671] public void createCatalog(String database_name, String catalog_name) throws DKException, Exception

[1672] Creates image search catalog

[1673] Parameters:

[1674] database_name—database name

[1675] catalog_name—catalog name

[1676] public void deleteCatalog(String database_name,

[1677] String catalog_name) throws DKException, Exception

[1678] Deletes image search catalog

[1679] Parameters:

[1680] database_name—database name

[1681] catalog_name—catalog name

[1682] public void openCatalog(String database_name,

[1683] String catalog_name) throws DKException, Exception

[1684] Opens QBIC catalog for a specified database

[1685] Parameters:

[1686] database_name—database name

[1687] catalog_name—catalog name

[1688] public void closecatalog( ) throws DKException, Exception

[1689] Closes current catalog

[1690] public void addColorFeature( ) throws DKException, Exception

[1691] Adds color feature to the current catalog

[1692] public void addDrawFeature( ) throws DKException, Exception

[1693] Adds draw feature to the current catalog

[1694] public void addColorHistogramFeature( ) throws DKException, Exception

[1695] Adds color histogram feature to the current catalog

[1696] public void addTextureFeature( ) throws DKException, Exception

[1697] Adds texture feature to the current catalog

[1698] public void addFeature(intfeatureSelection,

[1699] boolean bReCatalog) throws DKException, Exception

[1700] Adds feature to the current catalog

[1701] Parameters:

[1702] featureSelection—specific feature

[1703] bReCatalog—when true image search server reanalyze the new feature for existing images.

[1704] public void removeColorFeature( ) throws DKException, Exception

[1705] Removes color feature from the current catalog

[1706] public voidremoveDrawFeature( )throwsDKException, Exception

[1707] Removes draw feature from the current catalog

[1708] public void removeColorHistogramFeature( ) throws DKException, Exception

[1709] Removes color histogram feature from the current catalog

[1710] public void removeTextureFeature( ) throws DKException, Exception

[1711] Removes texture feature from the current catalog

[1712] public voidprocessImages(DKImageRecordQBIC imageList[ ],

[1713] int count) throws DKException, Exception

[1714] Processes a list of images for the current catalog

[1715] Parameters:

[1716] imageList—Image Record list

[1717] count—number of objects in the array

[1718] public synchronized void queueImages(DKImageRecordQBIC imageList[ ], int count) throws DKException, Exception

[1719] Puts a list of images into the image queue for later processing

[1720] Parameters:

[1721] imageList—Image Record list

[1722] count—number of objects in the array

[1723] public voidprocessImageQueue( ) throws DKException, Exception

[1724] Processes the image queue.

[1725] public void reCatalogImages(intfeatureSelectionList) throws DKException, Exception

[1726] Recatalogs the images

[1727] Parameters:

[1728] featureSelectionList—feature list. features are ored together.

[1729] public Object listDatabases( ) throws DKException, Exception

[1730] Lists all databases in the image search server

[1731] Returns:

[1732] a collection of DKIndexQBIC objects

[1733] public Object listCatalogs( ) throws DKException, Exception

[1734] Lists all catalogs in the current database

[1735] Returns:

[1736] a collection of DKIndexQBIC objects

[1737] public Object listCatalogs(String database_name) throws DKException, Exception

[1738] Lists all catalogs in the specified database

[1739] Parameters:

[1740] database_name—database name

[1741] Returns:

[1742] a collection of DKIndexQBIC objects

[1743] public Object listFeatures( ) throws DKException, Exception

[1744] Lists all features in the current catalog

[1745] Returns:

[1746] a collection of DKIndexQBIC objects

[1747] public Object listColorImages( ) throws DKException, Exception

[1748] Lists all images cataloged in the color feature in the current catalog.

[1749] Returns:

[1750] a collection of DKImageInfoQBIC objects

[1751] public Object listHistogramImages( ) throws DKException, Exception

[1752] Lists all images cataloged in the histogram feature in the current catalog.

[1753] Returns:

[1754] a collection of DKImageInfoQBIC objects

[1755] public Object listDrawImages( ) throws DKException, Exception

[1756] Lists all images cataloged in the draw feature in the current catalog.

[1757] Returns:

[1758] a collection of DKImageInfoQBIC objects

[1759] public Object listTextureImages( ) throws DKException, Exception

[1760] Lists all images cataloged in the texture feature in the current catalog.

[1761] Returns:

[1762] a collection of DKImageInfoQBIC objects

[1763] public String databaseName( ) throws DKException, Exception

[1764] Gets the current database name

[1765] Returns:

[1766] the database name

[1767] public String catalogName( ) throws DKException, Exception

[1768] Gets the current catalog name

[1769] Returns:

[1770] the catalog name

[1771] public String getLibServerName( ) throws DKException, Exception

[1772] Gets the library server name

[1773] Returns:

[1774] the library server name

[1775] public dkDatastoreDef datastoreDef( ) throws DKException, Exception

[1776] Gets datastore definition

[1777] Returns:

[1778] the meta-data (dkDatastoreDef) of this Datastore

[1779] Overrides:

[1780] datastoreDef in class dkAbstractDatastore

[1781] public String registerMapping(DKNVPair sourceMap) throws DKException, Exception

[1782] Registers mapping information to this Datastore

[1783] Parameters:

[1784] sourceMap—source name and mapping

[1785] Returns:

[1786] the mapping name for the mapping information

[1787] Overrides:

[1788] registerMapping in class dkAbstractDatastore

[1789] public void unRegisterMapping(String mappingName) throws DKException, Exception

[1790] Unregisters mapping information for this Datastore

[1791] Parameters:

[1792] mappingName—name of the mapping information

[1793] Returns:

[1794] an array of register mapping objects' names

[1795] Overrides:

[1796] unRegisterMapping in class dkAbstractDatastore

[1797] public String[ ] listMappingNames( ) throws DKException, Exception

[1798] Gets the list of the register mappings for this Datastore

[1799] Returns:

[1800] an array of register mapping objects' names

[1801] Overrides:

[1802] listMappingNames in class dkAbstractDatastore

[1803] public dkSchemaMapping getMapping(String mappingName) throws DKException, Exception

[1804] Gets mapping information for this Datastore

[1805] Parameters:

[1806] A mappingName—name of the mapping information

[1807] Returns:

[1808] the schema mapping object

[1809] Overrides:

[1810] getMapping in class dkAbstractDatastore

[1811] public synchronized dkExtension getExtension(String extensionName) throws DKException, Exception

[1812] Gets the extension object from a given extenstion name.

[1813] Parameters:

[1814] extensionName—name of the extension object.

[1815] Returns:

[1816] extension object.

[1817] Overrides:

[1818] getExtension in class dkAbstractDatastore

[1819] public synchronized void addExtension(String extensionName, dkExtension extensionObj) throws DKException, Exception

[1820] Adds a new extension object.

[1821] Parameters:

[1822] extensionname—name of new extension object

[1823] extensionObj—the extension object to be set

[1824] Overrides:

[1825] addExtension in class dkAbstractDatastore

[1826] public synchronized void removeExtension(String extensionName) throws DKException, Exception

[1827] Removes an existing extension object

[1828] Parameters:

[1829] extensionName—name of extension object to be removed

[1830] Overrides:

[1831] removeExtension in class dkAbstractDatastore

[1832] public synchronized String[ ] listExtensionNames( ) throws DKException, Exception

[1833] Gets the list of extension objects' names

[1834] Returns:

[1835] an array of extension objects' names

[1836] Overrides:

[1837] listExtensionNames in class dkAbstracDatastore

[1838] public DKDDO createDDO(String objectType,

[1839] int Flags) throws DKException, Exception

[1840] Creates a new DDO with object type, properties and attributes set for a given backend server.

[1841] Parameters:

[1842] objectType—the object type user wants to create

[1843] Flags—to indicate various options to specific more detail

[1844] characteristics of the DDO to create. For example, it may be a directive

[1845] to create a document DDO, a folder, etc.

[1846] Returns:

[1847] a new DDO of the given object type with all the properties and

[1848] attributes set so that the user only need to set the attribute values

[1849] Overrides:

[1850] createDDO in class dkAbstractDatastore

[1851] 5. Text Search Datastore

[1852] DKDatastoreTS is a specific version of dkDatastore and is used to query and access text search data. An example class definition for DKDatastoreTS is set forth below.

[1853] The following methods are part of the DKDatastoreTS class:

[1854] public DKDatastoreTS( ) throws DKException, Exception

[1855] Constructs the datastore and initializes the datastore.

[1856] public DKDatastoreTS(String configuration) throws DKException, Exception

[1857] Constructs the datastore and initializes the datastore.

[1858] public void connect(String datastore_name,

[1859] String user_name,

[1860] String authentication,

[1861] String connect_string) throws DKException, Exception

[1862] Connects to a datastore.

[1863] Parameters:

[1864] datastore_name—the datastore name used for connection

[1865] user_name—the user name used for connection

[1866] authentication—the authentication used for connection

[1867] connect_string—the connect string used for connection. This is used to

[1868] provide additional connection options.

[1869] Overrides:

[1870] connect in class dkAbstractDatastore

[1871] public void connect(String server_name,

[1872] String port,

[1873] char communication_type) throws DKException, Exception

[1874] Connects to a datastore.

[1875] Parameters:

[1876] server_name—the hostname where the text server is located

[1877] port—the port where the text server is located

[1878] communication_type—the communication type T for TCPIP or P for PIPES

[1879] public void disconnect( ) throws DKException, Exception

[1880] Disconnects to a datastore.

[1881] Overrides:

[1882] disconnect in class dkAbstractDatastore

[1883] public Object getOption(int option) throws DKException, Exception

[1884] Gets a datastore option.

[1885] Parameters:

[1886] option—the option identifier

[1887] Returns:

[1888] an option value

[1889] Overrides:

[1890] getOption in class dkAbstractDatastore

[1891] public void setOption(int option,

[1892] Object value) throws DKException, Exception

[1893] Sets a datastore option.

[1894] Parameters:

[1895] option—the option identifier

[1896] value—the option value

[1897] Overrides:

[1898] setOption in class dkAbstractDatastore

[1899] public Object evaluate(String command,

[1900] short commandLangType,

[1901] DKNVPair params[ ]) throws DKException, Exception

[1902] Evaluates the query.

[1903] Parameters:

[1904] command—a query string

[1905] commandLang—a query type

[1906] params—additional query option in name/value pair

[1907] Returns:

[1908] a collection of the results

[1909] Overrides:

[1910] evaluate in class dkAbstractDatastore

[1911] public Object evaluate (dkQuery query) throws DKException Exception

[1912] Evaluates the query.

[1913] Parameters:

[1914] query—a query object

[1915] Returns:

[1916] a collection of the results

[1917] Overrides:

[1918] evaluate in class dkAbstractDatastore

[1919] public Object evaluate(DKCQExpr qe) throws DKException, Exception

[1920] Evaluates the query.

[1921] Parameters:

[1922] qe—a common query expression object

[1923] Returns:

[1924] a collection of the results

[1925] Overrides:

[1926] evaluate in class dkAbstractDatastore

[1927] public dkResultSetCursor execute(String command,

[1928] short commandLangType,

[1929] DKNVPair params[ ]) throws DKException, Exception

[1930] Executes the query.

[1931] Parameters:

[1932] command—a query string

[1933] commmdLang—a query type

[1934] params—additional query option in name/value pair

[1935] Returns:

[1936] resultSetCursor which represents a datastore cursor.

[1937] Overrides:

[1938] execute in class dkAbstracDatastore

[1939] public dkResultSetCursor execute(dkQuery query) throws DKException, Exception

[1940] Executes the query.

[1941] Parameters:

[1942] query—a query object

[1943] Returns:

[1944] resultSetCursor which represents a datastore cursor.

[1945] Overrides:

[1946] execute in class dkAbstractDatastore

[1947] public dkResultSetCursor execute(DKCQExpr cqe) throws DKException, Exception

[1948] Executes the query.

[1949] Parameters:

[1950] qe—a common query expression object

[1951] Returns:

[1952] resultSetCursor which represents a datastore cursor.

[1953] Overrides:

[1954] execute in class dkAbstractDatastore

[1955] public void executeWithCallback(dkQuery query,

[1956] dkCallback callbackObj) throws DKException, Exception

[1957] Executes the query with callback function.

[1958] Parameters:

[1959] qo—a query object

[1960] callbackObj—a dkCallback object

[1961] Overrides:

[1962] executeWithCallback in class dkAbstractDatastore

[1963] public void executeWithCallback(String command,

[1964] short commandLangType,

[1965] DKVPairparams[ ],

[1966] dkCallback callbackObj) throws DKException, Exception

[1967] Executes the query with callback function.

[1968] Parameters:

[1969] command—a query string

[1970] commandLang—a query type

[1971] params—additional query option in name/value pair

[1972] callbackObj—a dkCallback object

[1973] Overrides:

[1974] executeWithCallback in class dkAbstractDatastore

[1975] public void executeWithCallback(DKCQExpr qe,

[1976] dkCallback callbackObj) throws DKException, Exception

[1977] Executes the query with callback function.

[1978] Parameters:

[1979] qe—a common query expression object

[1980] callbackObj—a dkCallback object

[1981] Overrides:

[1982] executeWithCallback in class dkAbstractDatastore

[1983] public ckQuery createQuery(String command,

[1984] short commandLangType,

[1985] DKNVPair params[ ]) throws DKException, Exception

[1986] Creates a query object.

[1987] Parameters:

[1988] command—a query string

[1989] commandLang—a query type

[1990] params—additional query option in name/value pair

[1991] Returns:

[1992] a query object

[1993] Overrides:

[1994] createQuery in class dkAbstractDatastore

[1995] public dkQuery createQuery(DKCQExpr qe) throws DKException, Exception

[1996] Creates a query object.

[1997] Parameters:

[1998] qe—a common query expression object

[1999] Overrides:

[2000] createQuery in class dkAbstractDatastore

[2001] public void addObject(dkDataObject ddo) throws DKException, Exception

[2002] Adds this ddo to this datastore.

[2003] Parameters:

[2004] ddo—the ddo to be added to this Datastore

[2005] Overrides:

[2006] addObject in class dkAbstractDatastore

[2007] public void deleteObject(dkDataObject ddo) throws DKException, Exception

[2008] Deletes this ddo from this datastore.

[2009] Parameters:

[2010] ddo—the ddo to be deleted from this Datastore

[2011] Overrides:

[2012] deleteObject in class dkAbstractDatastore

[2013] public void retrieveObject(dkDataObject ddo) throws DKException, Exception

[2014] Retrieves this ddo from this datastore.

[2015] Parameters:

[2016] ddo—the ddo to be retrieved from this Datastore

[2017] Overrides:

[2018] retrieveObject in class dkAbstractDatastore

[2019] public void updateObject(dkDataObject ddo) throws DKException, Exception

[2020] Updates this ddo in this datastore.

[2021] Parameters:

[2022] ddo—the ddo to be updated in this Datastore

[2023] Overrides:

[2024] updateObject in class dkAbstractDatastore

[2025] public void commit( ) throws DKException, Exception

[2026] Commits a datastore transaction

[2027] Overrides:

[2028] commit in class dkAbstractDatastore

[2029] public void rollback( ) throws DKException, Exception

[2030] Rolls back a datastore transaction

[2031] Overrides:

[2032] rollback in class dkAbstractDatastore

[2033] public boolean isconnected( ) throws Exception

[2034] Checks to see if the datastore is connected.

[2035] Returns:

[2036] rue if connected

[2037] Overrides:

[2038] isConnected in class dkAbstractDatastore

[2039] public String datastoreName( ) throws Exception

[2040] Gets the name of this datastore object. Usually it represents a datastore source's server name.

[2041] Returns:

[2042] datastore name

[2043] Overrrides:

[2044] datastoreName in class dkAbstractDatastore

[2045] public String datastoreType( ) throws Exception

[2046] Gets the datastore type for this datastore object

[2047] Returns:

[2048] datastore type

[2049] Overrides:

[2050] datastoreType in class dkAbstractDatastore

[2051] public DKHandle connection( ) throws Exception

[2052] Gets the connection handle for a Datastore

[2053] Returns:

[2054] connection handle

[2055] Overrides:

[2056] connection in class dkAbstractDatastore

[2057] public DKHandle handle(String type) throws Exception

[2058] Gets a datastore handle

[2059] Parameters:

[2060] type—type of datastore handle wanted

[2061] Returns:

[2062] a datastore handle

[2063] Overrides:

[2064] handle in class dkAbstractDatastore

[2065] public String userName( ) throws Exception

[2066] Gets the user name for this datastore object

[2067] Returns:

[2068] user name

[2069] Overrides:

[2070] userName in class dkAbstractDatastore

[2071] public dkcollection listDataSources( ) throws DKException, Exception

[2072] Lists the available datastore sources that can be used to connect with.

[2073] Returns:

[2074] a collection of server definitions

[2075] Overrides:

[2076] listDataSources in class dkAbstractDatastore

[2077] public String[ ] listDataSourceNames( ) throws DKException, Exception

[2078] Lists the available datastore source names that can be used to connect with.

[2079] Returns:

[2080] an array of server names

[2081] Overrides:

[2082] listDataSourceNames in class dkAbstractDatastore

[2083] public Object listservers( ) throws DKException, Exception

[2084] List the available datastore sources that can be used to connect with. Note: listServers( ) is deprecated. Replace by listDatasources.

[2085] Returns:

[2086] a collection of server definitions

[2087] Overrides:

[2088] listServers in class dkAbstractDatastore

[2089] See Also:

[2090] listDataSources

[2091] public Object listschema( ) throws DKException, Exception

[2092] Lists the entities that belong to this datastore. Note: listSchema( ) is deprecated. Replace by listEntities.

[2093] Returns:

[2094] an object that contains the schema

[2095] Overrides:

[2096] listSchema in class dkAbstractDatastore

[2097] See Also:

[2098] listEntities

[2099] public Object listSchemaAttributes(String schemaEntry) throws DKException, Exception

[2100] Lists the attributes that belong to a schema. Note: listSchemaAttributes( ) is deprecated. Replace by listEntityAttributes.

[2101] Parameters:

[2102] schemaentry—the name of the schema.

[2103] Returns:

[2104] an object that contains the attributes that belong to this schema

[2105] Overrides:

[2106] listSchemaAttributes in class dkAbstractDatastore

[2107] See Also:

[2108] listEntityAttrs

[2109] public dkCollection listEntities( ) throws DKException, Exception

[2110] Gets a list of entities from persistent Datastore

[2111] Returns:

[2112] a collection of entity defs

[2113] Throws: DKException

[2114] if error occurs

[2115] Overrides:

[2116] listEntities in class dkAbstractDatastore

[2117] public String[ ] listEntityNames( ) throws DKException, Exception

[2118] Gets a list of entity names from persistent Datastore

[2119] Returns:

[2120] an array of entity names

[2121] Throws: DKException

[2122] if error occurs

[2123] Overrides:

[2124] listEntityNames in class dkAbstractDatastore

[2125] public dkCollection listEntityAttrs(String entityName) throws DKException, Exception

[2126] Gets a list of attributes for a given entity name.

[2127] Parameters:

[2128] entityName—name of entity to retrieve attributes for

[2129] Returns:

[2130] a dkCollection of dkAttrDef objects

[2131] Throws: DKException

[2132] if the entity name does not exist

[2133] Overrides:

[2134] listEntityAttrs in class dkAbstractDatastore

[2135] public String[ ] listEntityAttrNames(String entityName) throws DKException, Exception

[2136] Gets a list of attribute names for a given entity name.

[2137] Parameters:

[2138] entityName—name of entity to retrieve attribute names for

[2139] Returns:

[2140] an array of attribute names

[2141] Throws: DKException

[2142] if the entity name does not exist

[2143] Overrides:

[2144] listEntityAttrNames in class dkAbstractDatastore

[2145] public void startUpdateIndex(String indexName) throws DKException, Exception

[2146] Starts the indexing process.

[2147] Parameters:

[2148] indexName—the name of the search index.

[2149] public void clearIndex(String indexName) throws DKException, Exception

[2150] Clears all indexed terms from a search index.

[2151] Parameters:

[2152] indexName—the name of the search index.

[2153] public void createIndex(DKIndexInfoTS newIndex) throws DKException, Exception

[2154] Creates a search index.

[2155] Parameters:

[2156] newIndex—the search index to be created.

[2157] public void deleteIndex(String indexName) throws DKException, Exception

[2158] Deletes a search index.

[2159] Parameters:

[2160] indexName—the name of a search index.

[2161] public DKIndexInfoTS getIndexInformation(String indexName) throws DKException, Exception

[2162] Gets index information about a search index.

[2163] Parameters:

[2164] indexName—the name of a search index.

[2165] Returns:

[2166] a search index object which contains search index information.

[2167] public DKIndexFuncStatusTS getIndexFunctionStatus(String indexName ) throws DKException, Exception

[2168] Gets indexing function status, document and document message queue count for search index.

[2169] Parameters:

[2170] indexName—the name of a search index.

[2171] Returns:

[2172] a search index function status object which contains the indexing

[2173] function status.

[2174] public void setIndexFunctionStatus(String indexName,

[2175] int actionid) throws DKException, Exception

[2176] Set indexing function status for a search index.

[2177] Parameters:

[2178] indexName—the name of a search index.

[2179] actionaId—the indicator applied to a text search function. It can be

[2180] enabled, disabled or reset.

[2181] public dkDatastoreDef datastoreDef( ) throws DKException, Exception

[2182] Get datastore definition

[2183] Returns:

[2184] the meta-data (dkDatastoreDef) of this datastore

[2185] Overrides:

[2186] datastoreDef in class dkAbstractDatastore

[2187] public DKMatchesInfoTS getMatches(dkResultSetCursor cursor,

[2188] String documentId,

[2189] String textIndexName,

[2190] boolean useDictionary) throws DKException, Exception

[2191] Get Match Information given indexName and document id

[2192] Returns:

[2193] A DKMatchesInfoTS object that contains match information public String registerMapping(DKNVpair sourceMap) throws DKException, Exception

[2194] Registers a mapping definition to this datastore. Mapping is done by Entities.

[2195] Parameters:

[2196] sourceMap—source name and mapping, a DKNVPair class with the following possible values:

[2197] (“BUFFER”,): buffer_ref is a reference to a string in memory

[2198] (“FILE”,): file_name is the name of the file containing the mapping

[2199] (“URL”,): URL-address location of the mapping

[2200] (“LDAP”,): LDAP file-name

[2201] (“SCHEMA”,): a reference to a dkSchemaMapping object defining the mapping. Currently, only “SCHEMA” option is supported, others may be added later.

[2202] Returns:

[2203] the name of the mapping definition.

[2204] Overrides:

[2205] registerMapping in class dkAbstractDatastore

[2206] See Also:

[2207] unRegisterMapping

[2208] public void unRegisterMapping(String mappingName) throws DKException, Exception

[2209] Unregisters mapping information for this Datastore

[2210] Parameters:

[2211] mappingName—name of the mapping information

[2212] Returns:

[2213] an array of register mapping objects' names

[2214] Overrides:

[2215] unRegisterMapping in class dkAbstractDatastore

[2216] public String[ ] listMappingNames( ) throws DKException, Exception

[2217] Gets the list of the register mappings for this Datastore

[2218] Returns:

[2219] an array of register mapping objects' names

[2220] Overrides:

[2221] listMappingNames in class dkAbstractDatastore

[2222] public dkSchemaMapping getMapping(String mappingName) throws DKException, Exception

[2223] Gets mapping information for this Datastore

[2224] Parameters:

[2225] mappingName—name of the mapping information

[2226] Returns:

[2227] the schema mapping object

[2228] Overrides:

[2229] getMapping in class dkAbstractDatastore

[2230] See Also:

[2231] registerMapping

[2232] public synchronized dkExtension getExtension(String extensionName) throws DKException,

[2233] Exception

[2234] Gets the extension object from a given extenstion name.

[2235] Parameters:

[2236] extensionName—name of the extension object.

[2237] Returns:

[2238] extension object.

[2239] Overrides:

[2240] getextension in class dkAbstractDatastore

[2241] public synchronized void addExtension(String extensionName,

[2242] dkExtension extensionObj) throws DKException, Exception

[2243] Adds a new extension object.

[2244] Parameters:

[2245] extensionName—name of new extension object

[2246] extensionObj—the extension object to be set

[2247] Overrides:

[2248] addExtension in class dkAbstractDatastore

[2249] public synchronized void removeExtension(String extensionName) throws DKException, Exception

[2250] Removes an existing extension object

[2251] Parameters:

[2252] extensionName—name of extension object to be removed

[2253] Overrides:

[2254] removeExtension in class dkAbstractDatastore

[2255] public synchronized String[ ] listExtensionNames( ) throws DKException, Exception

[2256] Gets the list of extension objects' names

[2257] Returns:

[2258] an array of extension objects' names

[2259] Overrides:

[2260] listExtensionNames in class dkAbstractDatastore

[2261] public DKDDO createDDO(String objectType,

[2262] int Flags) throws DKException, Exception

[2263] Creates a new DDO with object type, properties and attributes set for a given backend server.

[2264] Parameters:

[2265] objectType—the object type user wants to create

[2266] Flags—to indicate various options to specify more detail

[2267] characteristics of the DDO to create. For example, it may be a directive

[2268] to create a document DDO, a folder, etc.

[2269] Returns:

[2270] a new DDO of the given object type with all the properties and

[2271] attributes set, so that the user only need to set the attribute values

[2272] Overrides:

[2273] createDDO in class dkAbstractDatastore

[2274] public void destroy( ) throws DKException, Exception

[2275] datastore destroy—datastore cleanup if needed

[2276] Overrides:

[2277] destroy in class dkAbstractDatastore

[2278] 6. Dynamic Data Objects

[2279] DKDDOBase is the base class to represent a Dynamic Data Object (DDO). An example class definition for DKDDOBase is set forth below.

[2280] The following methods are part of the DKDDOBase class:

[2281] public DKDDOBase( )

[2282] Constructs a DDO Base object.

[2283] public DKDDOBase(short initialSize)

[2284] Constructs a DDO Base object which has enough space for the given initial number of data-items.

[2285] Parameters:

[2286] initialSize—initial number of data items.

[2287] public DKDDOBase(DKDDOBase ddo)

[2288] Constructs a DDO Base object from an existing DDO Base (copy contructor).

[2289] Parameters:

[2290] ddo—a DDO Base object.

[2291] public DKDDOBase(String objectType)

[2292] Constructs a DDO Base object for a given object type.

[2293] Parameters:

[2294] objectType—the object type.

[2295] public DKDDOBase(String objectType,

[2296] short initialSize)

[2297] Constructs a DDO Base object for a given object type, with an initial number of data-items.

[2298] Parameters:

[2299] objectType—the object type.

[2300] initialSize—initial number of data items.

[2301] public DKDDOBase(DKPid pid)

[2302] Constructs a DDO Base object with a given Pid.

[2303] Parameters:

[2304] pid—the Pid object

[2305] public DKDDOBase(DKPid pid,

[2306] short initialSize)

[2307] Constructs a DDO Base object with a given Pid and an initial number of data-items.

[2308] Parameters:

[2309] pid—the Pid object.

[2310] initialSize—initial number of data items.

[2311] public shortprotocol( )

[2312] Returns the protocol type supported by this data-object. In this case, it is DK_DDO, which essentially means that this data-object can be made persistent with the help of an associated datastore object. The DK_DDO protocol consists of get/setData, get/setDataProperty, and other methods in this object, which support the representation of a self describing data-object.

[2313] Returns:

[2314] the protocol.

[2315] Overrides:

[2316] protocol in class dkDataobject

[2317] public String getObjectType( )

[2318] Gets the type of this data-object.

[2319] Returns:

[2320] the object type.

[2321] Overrides:

[2322] getObjectType in class dkDataobject

[2323] public void setObjectType(String toObjectType)

[2324] Sets the type of this data-object and synchronizes it with the object type of its Pid.

[2325] Parameters:

[2326] toObjectType—the object type.

[2327] public boolean updatable( )

[2328] Returns true if this data object is updatable.

[2329] Returns:

[2330] true if updatable.

[2331] public short addData( ) throws DKUsageError

[2332] Adds a new data-item to this databject and returns the new data-item number (data-d).

[2333] Returns:

[2334] the data-item number (data-id).

[2335] public short addData(String data_name) throws DKUsageError

[2336] Adds a new data-item wit the given name to this data-object and returns the new data-item number (data-id).

[2337] Parameters:

[2338] data_name—data-item name.

[2339] Returns:

[2340] data-item number (data-id).

[2341] public short addDataProperty(short data_id ) throws DKUsageError

[2342] Adds a new property to a given data-item and returns the new property number property-id).

[2343] Parameters:

[2344] data_id—data-id .

[2345] Returns:

[2346] data-property number (property-id).

[2347] public short addDataProperty(short data_id,

[2348] String property_name) throws DKusageError

[2349] Adds a new property with the given name to the data-item and returns the new property number (property-id).

[2350] Parameters:

[2351] data_id—data id.

[2352] property_name—property name.

[2353] Returns:

[2354] data property number (property-id).

[2355] public short addDataProperty(short data_id,

[2356] String property_name,

[2357] Object property_value) throws DKUsageError

[2358] Adds a new property with the given name and value to the data-item and returns the new property number (property-id).

[2359] Parameters:

[2360] data_id—the data-id.

[2361] property_name—property name.

[2362] property_value—property value.

[2363] Returns:

[2364] data property number (property-id).

[2365] public short datacount( )

[2366] Gets the number of data-items in this data-object.

[2367] Returns:

[2368] number of data-items.

[2369] public short dataPropertyCount(short data_id) throws DKUsageError

[2370] Gets the number of properties associated with this data-item.

[2371] Parameters:

[2372] data_id—the data-id.

[2373] Returns:

[2374] the number of properties.

[2375] public void setDataProperty(short data_id,

[2376] short property_id,

[2377] Object property_value) throws DKUsageError

[2378] Sets the value of a given property in a data-item.

[2379] Parameters:

[2380] data_id—data-id.

[2381] property_id—property-id.

[2382] property_value—the property value.

[2383] public Object getDataProperty(short data_id,

[2384] short property_id) throws DKUsageError

[2385] Gets the value of a given property in a data-item.

[2386] Parameters:

[2387] data_id—data-id.

[2388] property_id—property-id.

[2389] Returns:

[2390] property value.

[2391] public void setDataPropertyName(short data_id,

[2392] short property_id,

[2393] String property_name) throws DKUsageError

[2394] Sets the name of a given property in a data-item.

[2395] Parameters:

[2396] data_id—data-id.

[2397] property_id—property-id.

[2398] propertyk_name—property name.

[2399] public String getDataPropertyName(short data_id),

[2400] short property_id) throw DKUsageError

[2401] Gets the name of a given data-item.

[2402] Parameters:

[2403] data_id—data-id.

[2404] property_id—property-id.

[2405] Returns:

[2406] property name.

[2407] public void setData(short data_id,

[2408] Object data_value) throws DKUsageError

[2409] Sets the value of a given data-item.

[2410] Parameters:

[2411] data_value—data-id.

[2412] data_value—data value.

[2413] public Object getData(short data_id) throws DKUsageError

[2414] Gets the value of a given data-item.

[2415] Parameters:

[2416] data_id—data-id.

[2417] Returns:

[2418] data value.

[2419] public void setDataName(short data_id,

[2420] String data_name) throw DKUsageError

[2421] Sets the name of a given data-item.

[2422] Parameters:

[2423] data_id—data-id.

[2424] data_name—data name.

[2425] public String gatDataName(short data_id) throws DKUsageError

[2426] Gets the name of a given data-item.

[2427] Parameters:

[2428] data_id—data-item.

[2429] Returns:

[2430] data name.

[2431] public short dataId(String data_name) throws DKUsageError

[2432] Gets the data-id of a given data-item name.

[2433] Parameters:

[2434] data_name—data name.

[2435] Returns:

[2436] the data-id.

[2437] public short dataPropertyId(short data_id,

[2438] String data_property_name) throws DKUsageError

[2439] Gets the property-id of a given property-name in a data-item.

[2440] Parameters:

[2441] data_id—data-id.

[2442] data_property_name—data-property name.

[2443] Returns:

[2444] the property-id.

[2445] public Object getDataByName(String data_name) throws DKUsageError

[2446] Gets the value of a data-item given its name.

[2447] Parameters:

[2448] data_name—data-item name.

[2449] Returns:

[2450] data value.

[2451] public Object getDataPropertyByName(short data_id,

[2452] String data_property_name) throws DKUsageError

[2453] Gets the value of a given property-name of a data-item id.

[2454] Parameters:

[2455] data_id—data-id.

[2456] data_property_name—data-property name.

[2457] Returns:

[2458] property value.

[2459] public Object getDataPropertyByName(String data_name,

[2460] String data_property_name) throws DKUsageError

[2461] Gets the value of a given property-name of a data-item name.

[2462] Parameters:

[2463] data_name—data-item name.

[2464] data_property_name—data-property name.

[2465] Returns:

[2466] property value.

[2467] public void setNull(short data_id) throws DKUsageError

[2468] Sets the value of a data-item to a null value. The data-item must be nullable, and the data-object must be updatable.

[2469] Parameters:

[2470] data_id—data-id.

[2471] public boolean isNull(short data_id) throws DKUsageError

[2472] Returns true if the value of this data-item is null.

[2473] Returns:

[2474] true if data-item value is null.

[2475] public boolean isDataSet(short data_id) throws DKUsageError

[2476] Returns true if this data-item has been set to a value.

[2477] Returns:

[2478] true if data item value is set.

[2479] public boolean isDataPropertySet(short data_id,

[2480] short property_id) throws DKUsageError

[2481] Returns true if a given properly of a data-item is set.

[2482] Returns:

[2483] true if data item property value is set.

[2484] public short addProperty( ) throws DKUsageError

[2485] Adds a new property to this DDO and returns the new property number (property-id).

[2486] Returns:

[2487] the new property number (property id).

[2488] public short addProperty(String property_name) throws DKUsageError

[2489] Adds a new property with a given name to this DDO and returns the new property number (property-id).

[2490] Parameters:

[2491] property_name—property name.

[2492] Returns:

[2493] property number (property-id).

[2494] public short addProperty(String property_name,

[2495] Object property_value) throws DKUsageError

[2496] Adds a new property with a given name and value to this DDO. and returns the new property number (property-id).

[2497] Parameters:

[2498] property_name—property-name.

[2499] property_value—property value.

[2500] Returns:

[2501] the property number (property-id).

[2502] public short propertycount( ) throws DKUsageError

[2503] Gets the number of properties associated with this DDO.

[2504] Returns:

[2505] the number of properties.

[2506] public void setProperty(short property_id,

[2507] Object property_value) throws DKUsageError

[2508] Sets the value of a given property in this DDO.

[2509] Parameters:

[2510] property_id—property-id.

[2511] property_value—property value.

[2512] public Object getProperty(short property_id) throws DKUsageError

[2513] Gets the value of a given property in this DDO.

[2514] Parameters:

[2515] property_id—property-id.

[2516] Returns:

[2517] property value.

[2518] public void setPropertyName(short property_id,

[2519] String property_name) throws DKUsageError

[2520] Sets the name of a given property in this DDO.

[2521] Parameters:

[2522] property_id—property-id.

[2523] property_name—property name.

[2524] public String getPropertyName(short property_id) throws DKUsageError

[2525] Gets the name of a given property in this DDO.

[2526] Parameters:

[2527] property_id—property-id.

[2528] Returns:

[2529] the property name.

[2530] public shortpropertyId(String property_name) throws DKUsageError

[2531] Gets the property-id of a given property-name in this DDO.

[2532] Parameters:

[2533] property_name—property-name.

[2534] Returns:

[2535] the property-id.

[2536] public Object getPropertyByName(String property_name) throws DKUsageError

[2537] Gets the value of a given property-name in this DDO.

[2538] Parameters:

[2539] property_name—property-name.

[2540] Returns:

[2541] the property value.

[2542] public boolean isPropertySet(shortproperty_id) throws DKUsageError

[2543] Returns true if the given property in this DDO has been set to a value.

[2544] Parameters:

[2545] property_id—property-id.

[2546] Returns:

[2547] true if the property is set

[2548] DKDDO is the class to represents a Dynamic Data Object. It is a sub-class of DKDDOBase with additional methods to support persistency, such as add( ), retrieve( ), update( ), and del( ). An example class definition for DKDDO is set forth below.

[2549] The following methods are part of the DKDDO class:

[2550] public DKDDOO( )

[2551] Constructs a DDO object.

[2552] public DKDDO(short initialSize)

[2553] Constructs a DDO object which has enough space for the given initial number of data-items.

[2554] Parameters:

[2555] initialSize—the initial number of data-items.

[2556] public DKDDO(DKDDO ddo)

[2557] Constructs a DDO object by copying another DDO object (copy constructor).

[2558] Parameters:

[2559] ddo—the other existing DDO object.

[2560] public DKDDO(String objectType)

[2561] Constructs a DDO object for a given object type.

[2562] Parameters:

[2563] objectType—an object-type.

[2564] public DKDDO(String objectType,

[2565] short initialSize)

[2566] Constructs a DDO object for a given object type, with an initial number of data-items.

[2567] Parameters:

[2568] objectType—an object-type.

[2569] initialSize—the initial number of data items.

[2570] public DKDDO(dkDatastore ds,

[2571] String objectType)

[2572] Constructs a DDO object

[2573] Parameters:

[2574] ds—a datastore object.

[2575] objectType—an object-type.

[2576] public DKDDO(dkDatastore ds,

[2577] String objectType,

[2578] short initialSize)

[2579] Constructs a DDO object for a given object type, with an initial number of data-items and the datastore associated with it.

[2580] Parameters:

[2581] ds—a datastore object.

[2582] objectType—an object-type.

[2583] initialSize—the initial number of data-items.

[2584] public DKDDO(DKPid pid)

[2585] Constructs a DDO object with a given Pid.

[2586] Parameters:

[2587] pid—a Pid object.

[2588] public DKDDO(DKPid pid,

[2589] short initialSize)

[2590] Constructs a DDO object with a given Pid and an initial number of data-items.

[2591] Parameters:

[2592] pid—a Pid object.

[2593] initialSize—the initial number of data-items.

[2594] public DKDDO(dkDatastore ds,

[2595] DKPid pid)

[2596] Constructs a DDO object with a given Pid and the datastore associated with it.

[2597] Parameters:

[2598] ds—a datastore object.

[2599] pid—a Pid object.

[2600] public DKDDO(dkDatastore ds,

[2601] DKPid pid,

[2602] short initialSize)

[2603] Constructs a DDO object with a given Pid, the datastore associated with it, and an initial number of data-items.

[2604] Parameters:

[2605] ds—a datastore object.

[2606] pid—a Pid object.

[2607] initialSize—the initial number of data-items.

[2608] public void setDatastore(dkDatastore ds)

[2609] Sets this datastore as the one associated with this DDO; that is, the datastore to keep the persistent copy of this DDO.

[2610] Parameters:

[2611] ds—a datastore object.

[2612] public datastore getDatastore( )

[2613] Gets the associated datastore for this DDO.

[2614] Returns:

[2615] the datastore object.

[2616] public shortprotocol( )

[2617] Returns the protocol type supported by this data-object. In this case, it is DK_PDDO, which essentially means that this object knows the datastore which it is associated with. With the help of the datastore, this object can transfer itself in and out of the datastore, thus making itself persistent.

[2618] Returns:

[2619] the protocol

[2620] Overrides:

[2621] protocol in class DKDDOBase

[2622] public void add( ) throws DKException, Exception

[2623] Adds this data-object to the persistent store. An initial entry of persistent copy of this data-object is created, according to the corresponding entity structure defined in the datastore. Onlypersistent data-items (or attributes) are saved.

[2624] public void retrieve( ) throws DKException, Exception

[2625] Retrieve this data-object from the persistent store. The in-memory values of this data-object is replaced with the persistent copy retrieved from the datastore. Only persistent data-items (or attributes) are retrieved.

[2626] public void update( ) throws DKException, Exception

[2627] Updates this object in the persistent store. The persistent copy of this data-object is updated with the current values in-memory. Only persistent data-items (or attributes) are updated.

[2628] public void del( ) throws DKException, Exception

[2629] Deletes this object from the persistent store. The persistent copy of this data-object is deleted from the datastore. The in-memory copy of this object is not affected. After this method is executed, a subsequent call to retrieve( ), update( ), or del( ), will cause an exception because the persistent copy of this data-object no longer exists.

[2630] 7. Extended Data Objects

[2631] The dkXDO class is a common abstract class that can represent a complex LTDT(User Defined Type) or LOB(Large Object). An example class definition for dkXDO is set forth below.

[2632] The following methods are part of the dkXDO class:

[2633] public abstract void setPid(DKPidXDO aPidXDO) throws DKUsageError

[2634] Sets the pid information of this object with the new provided pid

[2635] Parameters:

[2636] aPidXDO—a DKPidXDO object

[2637] Throws: DKUsageError

[2638] if provided pid is null

[2639] public abstract DKPidYDO getPid( )

[2640] Gets a copy of the persistent ID object of this object

[2641] Returns:

[2642] a copy of the persistent ID object of this object

[2643] public abstract DKPidXDO getPidObject( )

[2644] Gets a copy of the persistent ID object of this object

[2645] Returns:

[2646] a copy of the persistent ID object of this object

[2647] public abstract void setPidObject(DKPidYDO aPidXDO) throws DKException

[2648] Sets the pid information of this object with the new provided pid

[2649] Parameters:

[2650] aPidXDO—a DKPidXDO object

[2651] Throws: DKException

[2652] if provided pid is null

[2653] public abstract void add( ) throws DKException, Exception

[2654] Adds the object content from memory to the Datastore

[2655] Throws: DKException,

[2656] Exception If error occurred

[2657] public abstract void retrieves throws DKException, Exception

[2658] Retrieves the object content from the datastore to the memory buffer

[2659] Throws: DKException,

[2660] Exception If error occurred

[2661] public abstract void update( ) throws DKException, Exception

[2662] Updates the object content in datastore with the content in memory

[2663] Throws: DKException,

[2664] Exception If error occurred

[2665] public abstract void del( ) throws DKException Exception

[2666] Deletes the object content from dataaore

[2667] Throws: DKException,

[2668] Exception If error occurred

[2669] public abstract boolean isContentChanged( )

[2670] Checks if the part content changed (in memory).

[2671] Returns:

[2672] true if the object content is changed; false otherwise.

[2673] public abstract boolean isset( )

[2674] Checks if the part content is set (in memory).

[2675] Returns:

[2676] true if the object content is set; false otherwise.

[2677] public abstract void copyData(dkXDO aXDO) throws DKException, Exception

[2678] Replaces the content of this object with the content of the other XDO object

[2679] Parameters:

[2680] adkXDO—the other XDO object

[2681] Throws: DKException,

[2682] Exception If error occurred

[2683] public abstract boolean compareData(dkXDO aXDO) throws DKException, Exception

[2684] Compares the content of this object with the content of the other XDO object

[2685] Parameters:

[2686] adkXDO—the other XDO object

[2687] Throws: DKException,

[2688] Exception If object type is different

[2689] public shortprotocol( )

[2690] Returns the protocol supported by this object.

[2691] Returns:

[2692] the protocol “DK_XDO”

[2693] Overrides:

[2694] protocol in class dkXDOBase

[2695] public dkdatastore datastore( )

[2696] Gets the reference to the owner datastore object. Note: datastore( ) is deprecated. Replace by getdatastore.

[2697] Returns:

[2698] the dk Datastore object

[2699] See Also:

[2700] getDatastore

[2701] public dkDatastore getDatastore( )

[2702] Gets the reference to the owner datastore object

[2703] Returns:

[2704] the dkDatastore object

[2705] public void setDatastore(dkDatastore ds)

[2706] Sets the reference to the owner datastore object

[2707] Parameters:

[2708] ds—a dkDatastore

[2709] public abstract dkDO cloneSkeleton( ) throws DKUsageError, Exception

[2710] Clones this XDO with its persistent-id only, that is, with its data content set to empty.

[2711] public int getAffiliatedType( ) throws DKException, Exception

[2712] Gets the affiliated type of this object. An affiliated type could be ANNOTATION, NOTES, etc. The subclass need to override the behaviour of the default implementation of this method.

[2713] Returns:

[2714] the affiliated type for this object, for example: DK_CM_ANNOTATION, DK_CM_NOTE, etc.

[2715] public void setAffliatedType(int affliatedtype) throws DKException, Exception

[2716] Sets the affiliated type for this object. The subclass need to override the behaviour of the default implementation of this method.

[2717] Parameters:

[2718] affiliatedType—the affiliated type

[2719] See Also:

[2720] getAffiliatedtype

[2721] public String getMimeType( ) throws DKException, Exception

[2722] Gets the MIME type of this object. The subclass need to override the behaviour of the default implementation of this method.

[2723] Returns:

[2724] the MIME type for this object,

[2725] public void setMimeType(String mimeType) throws DKException, Exception

[2726] Sets the MIME type for this object. The subclass need to override the behaviour of the default implementation of this method.

[2727] Parameters:

[2728] mimeType—the MIME type

[2729] See Also:

[2730] getMimetype

[2731] public String getContentType( )

[2732] Gets the content type of this object. A content type could be ASCII, JPG, AVI, GIF, HTML, etc. The subclass need to override the behavior of the default implementation of this method.

[2733] Returns:

[2734] the content type for this object,

[2735] public void setContentType(String contentType) throws DKException, Exception

[2736] Sets the content type for this object. The subclass need to override the behaviour of the default implementation of this method.

[2737] Parameters:

[2738] contentType—the content type

[2739] See Also:

[2740] getContenttype

[2741] public void addExtension(String extensionName,

[2742] dkExtension extensionObj) throws DKException, Exception

[2743] Adds the extension object.

[2744] Parameters:

[2745] extensioName—the extension name

[2746] extensionObj—a source extension object

[2747] Throws: DKException,

[2748] Exception If error occurred

[2749] public void removeExtension(String extensionName) throws DKException

[2750] Removes the extension object.

[2751] Parameters:

[2752] extensionName—the extension name

[2753] Throws: DKException

[2754] If error occurred

[2755] public dkextension getExtension(String extensionName) throws DKException, Exception

[2756] Gets the extension object. Default always throws exception. Subclass must write this method.

[2757] Parameters:

[2758] extensionName—the extension name

[2759] Returns:

[2760] a dkextension object

[2761] Throws: DKException,

[2762] Exception If error occurred

[2763] public abstract byte[ ] getContent( ) throws DKException, Exception

[2764] Gets the content of this object

[2765] Returns:

[2766] the object content as a byte array stream

[2767] Throws: DKException,

[2768] Exception If object type is different

[2769] public abstract void setContent(byte aByteArr[ ]) throws DKException

[2770] Sets the content of this object with a byte array stream argument

[2771] Parameters:

[2772] aByteArr—a byte array

[2773] public abstract void setRank(int aRank)

[2774] public abstract int getRank( )

[2775] 8. Binary Large Objects

[2776] The dkBlob class is a common abstract class for basic BLOBs in each datastore. An example class definition for dkBlob is set forth below.

[2777] The following methods are part of the dkBlob class:

[2778] public abstract void add(String aFullFileName) throws DKException, Exception

[2779] Adds the object content from existing file to the Datastore

[2780] Parameters:

[2781] aFullFileName—a fully qualified path and file name, default is current

[2782] directory

[2783] Throws: DKException,

[2784] Exception If error occurred

[2785] public abstract void retrieve(String aFullFileName) throws DKException, Exception

[2786] Retrieves the object content from the datastore to a file name

[2787] Parameters:

[2788] aFullFileName—a fully qualified path and file name, default is current

[2789] directory

[2790] Throws: DKException,

[2791] Exception If error occurred

[2792] public abstract void update(String aFullFileName) throws DKException, Exception

[2793] Updates the object content in datastore with a file

[2794] Parameters:

[2795] aFullFileName—a fully qualified path and file name, default is current

[2796] directory

[2797] Throws: DKException,

[2798] Exception If error occurred

[2799] public abstract void del(boolean flush) throws DKException, Exception

[2800] Deletes the object content from Datastore

[2801] Parameters:

[2802] flush—if true the memory content will be flush, if false and content

[2803] is not set, the object will be retreived before delete it. The default

[2804] is flush.

[2805] Throws: DKException,

[2806] Exception If error occurred

[2807] public abstract void getContentToClientFile(String afileName,

[2808] int fileOption) throws DKException, Exception

[2809] Copies the lob data of this object to the given file

[2810] Parameters:

[2811] afileName—a fully qualified path with file name, default is current

[2812] directory(if no path)

[2813] fileOption—1 will create or overwrite an existing file; 2 will only

[2814] create file, but will also throw an exception if the file already

[2815] exists; 3 appends to an existing file

[2816] Throws: DKException,

[2817] Exception If error occurred

[2818] public abstract void setContentFromClientFile(String afileName) throws DKException

[2819] Replaces the lob data of this object with the contents of the file afilename

[2820] Parameters:

[2821] afileName—a fully qualified path with file name, default is current

[2822] directory(if no path)

[2823] Throws: DKException

[2824] If error occurred

[2825] public abstract dkBlob concatReplace(dkBlob adkBlob) throws DKException, Exception

[2826] Concatenates this object content with another object content the results of the concatenation replaces the existing contents of this object. Note: concatReplace( ) is deprecated.

[2827] Parameters:

[2828] adkBlob—another dkBlob object

[2829] Returns:

[2830] a dkBlob object

[2831] public abstract dkBlob concatReplace(byte aByteArrg[ ]) throws DKException, Exception

[2832] Concatenates this object content with another stream the results of the concatenation replaces the existing contents of this object. Note: concatReplace( ) is deprecated.

[2833] Parameters:

[2834] aByteArrg—a byte array stream

[2835] Returns:

[2836] a dkBlob object

[2837] public abstract int length( ) throws DKException, Exception

[2838] Gets the length of this object content in memory

[2839] Returns:

[2840] a byte length of this object content in memory

[2841] public abstract int indexOf(String astring,

[2842] int startpos) throws DKException, Exception

[2843] Returns the byte offset of the first occurrence of the search argument within this object, starting the search at offset startPos. If the search argument is not found, return 0. Note: indexOf( ) is deprecated.

[2844] Parameters:

[2845] astring—the search string argument

[2846] startpos—the offset position start to search

[2847] Returns:

[2848] the byte offset of the first occurrence of the search argument; return 0

[2849] if the search argument is not found

[2850] public abstract int indexOf(dkBlob adkglob,

[2851] int startpos) throws DKException, Exception

[2852] Returns the byte offset of the first occurrence of the search argument within this object, starting the search at offset startPos. If the search argument is not found, return 0. Note: indexOf( ) is deprecated.

[2853] Parameters:

[2854] adkBlob—the lobData of this dkBlob is the search argument

[2855] starpos—the offset position start to search

[2856] Returns:

[2857] the byte offset of the first occurrence of the search argument; return 0

[2858] if the search argument is not found

[2859] public abstract String subString(int startpos,

[2860] int alength) throws DKException, Exception

[2861] Returns a string object containing a substring of the lob data of this object. The substring will be taken starting at byte offset startpos, and extracting alength bytes. Note: subString( ) is deprecated.

[2862] Parameters:

[2863] startpos—the byte offset position start to extract

[2864] alength—the length to extract

[2865] Returns:

[2866] a string object

[2867] public abstract dkBlob remove (int startpos,

[2868] int alength) throws DKException, Exception

[2869] Deletes the portion of the lob data of this object starting at startpos for alength bytes. Note: remove( ) is deprecated.

[2870] Parameters:

[2871] startpos—the byte offset position start to delete

[2872] alength—the length to delete

[2873] Returns:

[2874] a dkBlob object

[2875] public abstract dkBlob insert(String astring,

[2876] int startpos) throws DKException, Exception

[2877] Inserts the argument data, following position startpos in the lob data of this object. Note: insert( ) is deprecated.

[2878] Parameters:

[2879] astring—the argument string data

[2880] startpos—the byte offset position start to insert

[2881] Returns:

[2882] a dkBlob object

[2883] public abstract dkBlob insert(dkBlob adkBlob,

[2884] int startpos) throws DKException, Exception

[2885] Inserts the argument data, following position startpos in the lob data of this object. Note: insert( ) is deprecated.

[2886] Parameters:

[2887] adkBlob—the lobData of this dkBlob is the argument data

[2888] startpos—the byte offset position start to insert

[2889] Returns:

[2890] a dkBlob object

[2891] public abstract void open(String afileName) throws DKException, Exception

[2892] Unloads the object content to a file afileName provided by the application and then synchronously invoking a default handler against the file.

[2893] Parameters:

[2894] afileName—a provided file name

[2895] Throws: DKException,

[2896] Exception If error occurred

[2897] public abstract void setInstanceOpenHandler(String ahandler,

[2898] boolean newSynchronousFlag)

[2899] Sets the executable handler program name and whether this handler should be invoked synchronously or asynchronously for this object instant

[2900] Parameters:

[2901] ahandler—the handler program name to view the content

[2902] newSynchronousFlag—true for synchronous process; false otherwise.

[2903] public abstract void setClassOpenHandler(String ahandler,

[2904] boolean newSynchronousFlag)

[2905] Sets the executable handler program name and whether this handler should be invoked synchronously or asynchronously for this object class

[2906] Parameters:

[2907] ahandler—the handler program name to view the content

[2908] newSynchronousFlag—true for synchronous process; false otherwise.

[2909] public abstract String getOpenHandler( )

[2910] Gets the current program name of the handler for this object instance

[2911] Returns:

[2912] the handler program name

[2913] public abstract boolean isOpenSynchronous( )

[2914] Gets the current synchronization property

[2915] Returns:

[2916] TRUE or FALSE for the handler

[2917] DKBlobDL is a specific version of DKBlob for a Digital Library/Visual Info. Note that for DKBlobDL, a blob (XDO) represents a part object of DL. An example class definition for DKBlobDL is set forth below.

[2918] The following methods are part of the DKBlobDL class:

[2919] public DKBlobDL(dkDatastore aDatastore) throws DKUsageError, Exception

[2920] Constructs the blob and defers initialization until implementation methods are called.

[2921] Parameters:

[2922] aDatastore—a DKDatastoreDL representing the associated DL Datastore

[2923] Throws: DKUsageError,

[2924] Exception If invalid datastore type

[2925] public DKBlobDL(dkDatastore aDatastore,

[2926] byte aByteArr[ ]) throws DKException, Exception

[2927] Constructs the blob and set the object's content.

[2928] Parameters:

[2929] aDatastore—a DKDatastoreDL representing the associated DL datastore

[2930] aByteArr—a byte array to be set as this object's content

[2931] Throws: DKException,

[2932] Exception If error occurred

[2933] public DKBlobDL(DKBlobDL aDKBlobDL) throws DKException

[2934] Copy constructor.

[2935] Parameters:

[2936] aDKBlobDL—an instance of DKBlobDL

[2937] Throws: DKException

[2938] If error occurred

[2939] public String getObjectType( )

[2940] Gets the object type.

[2941] Returns:

[2942] the object type “DKBlobDL”

[2943] Overrides:

[2944] getObjectType in class dkXDOBase

[2945] public void deletingvalue( )

[2946] Deletes value, this function performs as setNull in this class. Note: deletingvalue( ) is deprecated.

[2947] Overrides:

[2948] deletingValue in class dkXDOBase

[2949] public boolean isContentChanged( )

[2950] Checks if the part content changed (in memory).

[2951] Returns:

[2952] true if the object content is changed; false otherwise.

[2953] Overrides:

[2954] isContentChanged in class dkXDO

[2955] public boolean isset( )

[2956] Checks if the part content is set (in memory).

[2957] Returns:

[2958] true if the object content is set; false otherwise.

[2959] Overrides:

[2960] isSet in class dkXDO

[2961] public boolean isNull( )

[2962] Checks if the part content is null (in memory).

[2963] Returns:

[2964] true if the object content is null; false otherwise.

[2965] Overrides:

[2966] isNull in class dkXDOBase

[2967] public void setNull( )

[2968] Sets the part content to null (in memory).

[2969] Overrides:

[2970] setNull in class dkXDOBase

[2971] public boolean equals(dkXDOBase adkXDOBase) throws DKException

[2972] Checks if the xdo objects have same type, pid, content and indexed by same search engine. Note: equals( ) is deprecated.

[2973] Parameters:

[2974] adkXDOBase—an instance of dkXDOBase

[2975] Returns:

[2976] true if the objects have same type, pid, content and search index false otherwise.

[2977] Throws: DKException

[2978] If objects are not the same class

[2979] Overrides:

[2980] equals in class dkXDOBase

[2981] public boolean notEqual(dkXDOBase adkXDOBase) throws DKException

[2982] Checks if the xdo objects is not equal. Note: notEqual( ) is deprecated.

[2983] Parameters:

[2984] adkXDOBase—an instance of dkXDOBase

[2985] Returns:

[2986] true if the objects do not have same type, pid, content and search index

[2987] false otherwise.

[2988] Throws: DKException

[2989] If objects are not the same class

[2990] Overrides:

[2991] notEqual in class dkXDOBase

[2992] public DKPidXDO getPid( )

[2993] Gets a copy of the persistent ID object of this DKBlobDL object. Note: getPid( ) is deprecated. Replace by getPidObject( ).

[2994] Returns:

[2995] a copy of the persistent ID object of this DKBlobDL object

[2996] Overrides:

[2997] getPid in class dkXDO

[2998] See Also:

[2999] getPidobject

[3000] public void setPid(DKPidXDO aDKPid) throws DKUsageError

[3001] Sets the pid information of this object with the new provided pid. Note: setPid( ) is deprecated. Replace by setPidObject(DKPidXDO aPidXDO).

[3002] Parameters:

[3003] aDKPid—a DKPidXDO object

[3004] Throws: DKUsageError

[3005] If provided pid is null

[3006] Overrides:

[3007] setPid in class dkXDO

[3008] See Also:

[3009] setPidobject

[3010] public DKPidXDO getPidObject( )

[3011] Gets a copy of the persistent ID object of this object

[3012] Returns:

[3013] a copy of the persistent ID object of this object

[3014] Overrides:

[3015] getPidObject in class dkXDO

[3016] public void setPidObject(DKPidXDO aPidYDO) throws DKException

[3017] Sets the pid information of this object with the new provided pid

[3018] Parameters:

[3019] aPidXDO—a DKPidXDO object

[3020] Throws: DKException

[3021] If provided pid is null

[3022] Overrides:

[3023] setPidObject in class dkXDO

[3024] public void add( ) throws DKException, Exception

[3025] Adds the object content from memory to the Datastore

[3026] Throws: DKException,

[3027] Exception If error occurred

[3028] Overrides:

[3029] add in class dkXDO

[3030] public void add(String aFullFileName) throws DKException, Exception

[3031] Adds the object content from existing file to the Datastore

[3032] Parameters:

[3033] aFullFileName—a fully qualified path and file name, default is current

[3034] directory

[3035] Throws: DKException,

[3036] Exception If error occurred

[3037] Overrides:

[3038] add in class dkBlob

[3039] public void retrieve( ) throws DKException, Exception

[3040] Retrieves the object content from the datastore to the memory buffer

[3041] Throws: DKException,

[3042] Exception If error occurred

[3043] Overrides:

[3044] retrieve in class dkXDO

[3045] public void retrieve(String aFileName) throws DKException, Exception

[3046] Retrieves the object content from the datastore to a file name

[3047] Parameters:

[3048] aFileName—a fully qualified path and file name, default is current

[3049] directory

[3050] Throws: DKException,

[3051] Exception If error occurred

[3052] Overrides:

[3053] retrieve in class dkBlob

[3054] public void update(String aFileName) throws DKException, Exception

[3055] Updates the object content in datastore with a file

[3056] Parameters:

[3057] aFileName—a fully qualified path and file name, default is current

[3058] directory

[3059] Throws: DKException,

[3060] Exception If error occurred

[3061] Overrides:

[3062] update in class dkBlob

[3063] public void update( ) throws DKException, Exception

[3064] Updates the object content in datastore with the content in memory

[3065] Throws: DKException,

[3066] Exception If error occurred

[3067] Overrides:

[3068] update in class dkXDO

[3069] public void del( ) throws DKException, Exception

[3070] Deletes the object content from Datastore

[3071] Throws: DKException,

[3072] Exception If error occurred

[3073] Overrides:

[3074] del in class dkXDO

[3075] public void del(boolean flush) throws DKException, Exception

[3076] Deletes the object content from Datastore

[3077] Parameters:

[3078] flush—if true the memory content will be flush, if false and content

[3079] is not set, the object will be retreived before delete it. The default

[3080] is flush.

[3081] Throws: DKException,

[3082] Exception If error occurred

[3083] Overrides:

[3084] del in class dkBlob

[3085] public void copyData(dXDO adkXDO) throws DKException, Exception

[3086] Replaces the content of this object with the content of the other XDO object

[3087] Parameters:

[3088] adkXDO—the other XDO object

[3089] Throws: DKException,

[3090] Exception If error occurred

[3091] Overrides:

[3092] copyData in class dkXDO

[3093] public boolean compareData(dkXDO adkXDO) throws DKException, Exception

[3094] Compares the content of this object with the content of the other XDO object

[3095] Parameters:

[3096] adkXDO—the other XDO object

[3097] Throws: DKException,

[3098] Exception If object type is different

[3099] Overrides:

[3100] compareData in class dkXDO

[3101] public void setContent(byte aByteArray[ ])

[3102] Sets the content of this object with a byte array stream argument

[3103] Parameters:

[3104] aByteArray—a byte array

[3105] Overrides:

[3106] setContent in class dkXDO

[3107] public byte[ ] getContent( ) throws DKException, Exception

[3108] Gets the content of this object

[3109] Returns:

[3110] the object content as a byte array stream

[3111] Throws: DKException,

[3112] Exception If object type is different

[3113] Overrides:

[3114] getContent in class dkXDO

[3115] public void getContentToClientFile(String afileName,

[3116] int fileOption) throws DKException, Exception

[3117] Copies the lob data of this object to the given file

[3118] Parameters:

[3119] afileName—a fully qualified path with file name, default is current

[3120] directory(if no path)

[3121] fileOption—1 will create or overwrite an existing file; 2 will only create file, but will also throw an exception if the file already exists; 3 appends to an existing file

[3122] Throws: DKException,

[3123] Exception If error occurred

[3124] Overrides:

[3125] getContentToClientFile in class dkBlob

[3126] public void setContentFromClientFile(String afileName) throws DKException

[3127] Replaces the lob data of this object with the contents of the file afilename

[3128] Parameters:

[3129] afileName—a fully qualified path with file name, default is current

[3130] directory(if no path)

[3131] Throws: DKException

[3132] If error occurred

[3133] Overrides:

[3134] setContentFromClientFile in class dkBlob

[3135] public dkBlob concatReplace(dkBlob adkBlob) throws DKException, Exception

[3136] Concatenates this object content with another object content the results of the concatenation replaces the existing contents of this object. Note: concatReplace( ) is deprecated.

[3137] Parameters:

[3138] adkBlob—another dkBlob object

[3139] Returns:

[3140] a dkBlob object

[3141] Overrides:

[3142] concatReplace in class dkBlob

[3143] public dkBlob concatReplace(byte aByteArr[ ]) throws DKException, Exception

[3144] Concatenates this object content with another stream the results of the concatenation replaces the existing contents of this object. Note: concatReplace( ) is deprecated.

[3145] Parameters:

[3146] aByteArr—a byte array stream

[3147] Returns:

[3148] a dlkBlob object

[3149] Overrides:

[3150] concatReplace in class dkBlob

[3151] public int length( ) throws DKException, Exception

[3152] Gets the length of this object content in memory

[3153] Returns:

[3154] a byte length of this object content in memory

[3155] Overrides:

[3156] length in class dkBlob

[3157] public int indexOf(String astring,

[3158] int startpos) throws DKException, Exception

[3159] Returns the byte offset of the first occurrence of the search argument within this object, starting the search at offset startPos. If the search argument is not found, return 0. Note: indexOf( ) is deprecated.

[3160] Parameters:

[3161] astring—the search string argument

[3162] starpos—the offset position start to search

[3163] Returns:

[3164] the byte offset of the first occurrence of the search argument; return 0

[3165] if the search argument is not found

[3166] Overrides:

[3167] indexOf in class dkBlob

[3168] public int indexOf(dkBlob adkBlob,

[3169] int startpos) throws DKException, Exception

[3170] Returns the byte offset of the first occurrence of the search argument within this object, starting the search at offset startPos. If the search argument is not found, return 0. Note: indexOf( ) is deprecated.

[3171] Parameters:

[3172] adkBlob—the lobData of this dkBlob is the search argument

[3173] startpos—the offset position start to search

[3174] Returns:

[3175] the byte offset of the first occurrence of the search argument; return 0

[3176] if the search argument is not found

[3177] Overrides:

[3178] indexOf in class dkBlob

[3179] public String subString(int startpos,

[3180] int alength) throws DKException, Exception

[3181] Returns a string object containing a substring of the lob data of this object. The substring will be taken starting at byte offset startpos, and extracting alength bytes. Note: subString( ) is deprecated.

[3182] Parameters:

[3183] startpos—the byte offset position start to extract

[3184] alength—the length to extract

[3185] Returns:

[3186] a string object

[3187] Overrides:

[3188] subString in class dkBlob

[3189] public dkBlob remove(int startpos,

[3190] int alength) throws DKException, Exception

[3191] Deletes the portion of the lob data of this object starting at startpos for alength bytes. Note: remove( ) is deprecated.

[3192] Parameters:

[3193] startpos—the byte offset position start to delete

[3194] alength—the length to delete

[3195] Returns:

[3196] a dkBlob object

[3197] Overrides:

[3198] remove in class dkBlob

[3199] public dkBlob insert(String astring,

[3200] int startpos) throws DKException, Exception

[3201] Inserts the argument data, following position startpos in the lob data of this object. Note: insert( ) is deprecated.

[3202] Parameters:

[3203] astring—the argument string data

[3204] startpos—the byte offset position start to insert

[3205] Returns:

[3206] a dkBlob object

[3207] Overrides:

[3208] insert in class dkBlob

[3209] public dkBlob insert(dkBlob adkBlob,

[3210] int startpos) throws DKException, Exception

[3211] Inserts the argument data, following position startpos in the lob data of this object. Note: insert( ) is deprecated.

[3212] Parameters:

[3213] adkBlob—the lobData of this dkBlob is the argument data

[3214] startpos—the byte offset position start to insert

[3215] Returns:

[3216] a dkBlob object

[3217] Overrides:

[3218] insert in class dkBlob

[3219] public void open( ) throws DKException, Exception

[3220] Unloads the object content to a client file with a system generated name and then synchronously invoking a default handler against the file.

[3221] Throws: DKException,

[3222] Exception If error occurred

[3223] Overrides:

[3224] open in class dkXDOBase

[3225] public void open(String afileName)throws DKException, Exception

[3226] Unloads the object content to a file afileName provided by the application and then synchronously invoking a default handler against the file.

[3227] Parameters:

[3228] afileName—a provided file name

[3229] Throws: DKException,

[3230] Exception If error occurred

[3231] Overrides:

[3232] open in class dkBlob

[3233] public void setInstanceOpenHandler(String ahandler,

[3234] boolean newSynchronousFlag)

[3235] Sets the executable handler program name and whether this handler should be invoked synchronously or asynchronously for this object instant

[3236] Parameters:

[3237] ahandler—the handler program name to view the content

[3238] newSynchronousFlag—true for synchronous process; false otherwise.

[3239] Overrides:

[3240] set InstanceOpenHandler in class dkBlob

[3241] public void setClassOpenHandler(String ahandler,

[3242] boolean newSynchronousFlag)

[3243] Sets the executable handler program name and whether this handler should be invoked synchronously or asynchronously for this object class

[3244] Parameters:

[3245] ahandler—the handler program name to view the content

[3246] newSynchronousFlag—true for synchronous process; false otherwise.

[3247] Overrides:

[3248] setClassOpenHandler in class dkBlob

[3249] public String getOpenHandler( )

[3250] Gets the current program name of the handler for this object instance

[3251] Returns:

[3252] the handler program name

[3253] Overrides:

[3254] getOpenHandler in class dkBlob

[3255] public boolean isOpengynchronous( )

[3256] Gets the current synchronization property

[3257] Returns:

[3258] TRUE or FALSE for the handler

[3259] Overrides:

[3260] isOpenSynchronous in class dkBlob

[3261] public String getRepType( )

[3262] Gets the DL representation type of the object content

[3263] Returns:

[3264] the DL representation type of the object content

[3265] public void setRepType(String aRType)

[3266] Sets the DL representation type of the object content

[3267] Parameters:

[3268] aRType—the DL representation type of the object content

[3269] public String getItemId( )

[3270] Gets the DL item id of the object content

[3271] Returns:

[3272] the DL item id of the object content

[3273] public void setItemId(String aItemId)

[3274] Sets the DL item id of the object content

[3275] Parameters:

[3276] aRType—the DL item id of the object content

[3277] public int getContentClass( )

[3278] Gets the content class of the object

[3279] Returns:

[3280] the content class of the object

[3281] public void setContentClass(int aCClass)

[3282] Sets the content class of the object

[3283] Parameters:

[3284] aCClass—the content class of the object

[3285] public int getAffiliatedType( ) throws DKException, Exception

[3286] Gets the affiliated type of the object if DK_ANNOTATION, the getExtension(“DKAnnotationDL”) should point to DKAnnotationDL

[3287] Returns:

[3288] the affiliated type of the object

[3289] Overrides:

[3290] getAffiliatedType in class dkXDO

[3291] public void setAffiliatedType(int aAType) throws DKException, Exception

[3292] Sets the affiliated type of the object

[3293] Parameters:

[3294] aAType—the affiliated type of the object

[3295] Overrides:

[3296] setAffiliatedType in class dkXDO

[3297] getAffiliatedData

[3298] public DKAnnotation getAffliatedData( )

[3299] Gets the affiliated data of this object, if the affiliatedType is DK_ANNOTATION, this should get the DKAnnotation object. Note: getAffiliatedData( ) is deprecated. Replace by getExtension(String extensionName).

[3300] Returns:

[3301] a DKAnnotation object contains the annotation data informations

[3302] See Also:

[3303] getExtension

[3304] public void setAffiliatedData(DKAnnotation apAData)

[3305] Sets the affiliated data of this object, if the affiliatedType is DK_ANNOTATION, this should be provided. Note: setAffiliatedData( ) is deprecated. Replace by setExtension(..).

[3306] Parameters:

[3307] apAData—a DKAnnotation object contains the annotation data

[3308] informations

[3309] See Also:

[3310] setExtension

[3311] public String getSearchEngine( ) throws DKException, Exception

[3312] Gets search engine name. Note: getSearchEngine( ) is deprecated. Replace by DKSearchEngineInfoDL.getSearchEngine( ).

[3313] Returns:

[3314] the search engine name; SM for text search, QBIC for image search

[3315] Throws: DKException,

[3316] Exception If error occurred

[3317] See Also:

[3318] getExtension

[3319] public void setSearchEngine(String aSearchEngine) throws DKException, Exception

[3320] Sets the search engine name. Note: setSearchEngine( ) is deprecated. Replace by DKSearchEngineInfoDL.setSearchEngine(..)

[3321] Parameters:

[3322] aSearchEngine—the search engine name; SM for text search, QBIC for

[3323] image search

[3324] Throws: DKException,

[3325] Exception If error occurred

[3326] See Also:

[3327] setExtension

[3328] public String getSearchIndex( ) throws DKException, Exception

[3329] Gets the search index; ie.“SearchService-IndexName” name. Note: getSearchIndex( ) is deprecated. Replace by DKSearchEngineInfoDL.getSearchIndex( ).

[3330] Returns:

[3331] the search index name

[3332] Throws: DKException,

[3333] Exception If error occurred

[3334] See Also:

[3335] getExtension

[3336] public void setSearchIndex(String aSearchIndex) throws DKException Exception

[3337] Sets the search index; ie.“SearchService-IndexName” name. Note: setSearchIndex( ) is deprecated. Replace by DKSearchEngineInfoDL.setSearchIndex(..).

[3338] Parameters:

[3339] aSearchIndex—the search index name like “SearchService-IndexName”

[3340] Throws: DKException,

[3341] Exception If error occurred

[3342] See Also:

[3343] setExtension

[3344] public String getSearchInfo( ) throws DKException, Exception

[3345] Gets the search information value; a three chars code, valid in the NLS language table that identifies the language. (ie. ENU is US English, JAP is Japanese..). Note: getSearchInfo( ) is deprecated. Replace by DKSearchiEngineInfoDL.getSearchInfo( ).

[3346] Returns:

[3347] the search infomation value

[3348] Throws: DKException,

[3349] Exception If error occurred

[3350] See Also:

[3351] getExtension

[3352] public void setSearchInfo(String aSearchInfo) throws DKException, Exception

[3353] Sets the search infomation value; a three chars code, valid in the NLS language table that identifies the language. (ie. ENU is US English, JAP is Japanese..). Note: setSearchInfo( ) is deprecated. Replace by DKSearchEngineInfoDL.setSearchInfo(..).

[3354] Parameters:

[3355] aSearchInfo—the three chars code, valid in the NLS language table

[3356] Throws: DKException,

[3357] Exception If error occurred

[3358] See Also:

[3359] setExtension

[3360] public boolean getIndex.Flag( )

[3361] Gets the flag that indicates a part object is indexed by a search engine. Note:

[3362] getIndexFlag( ) is deprecated. Replace by isCategoryOf(..) method of this class.

[3363] Returns:

[3364] true if a part object is indexed by a search engine false otherwise.

[3365] See Also:

[3366] isCategoryOf

[3367] public void setIndexFlag(boolean aFlag)

[3368] Sets the flag that indicates a part object is indexed by a search engine. Note: setIndexFlag( ) is deprecated.

[3369] Parameters:

[3370] aflag—a flag to indicate the part object is indexed by a search engine

[3371] public DKBlobDL concatenate(DKBlobDL aDKBlobDL) throws DKException, Exception

[3372] Concatenates this object content with another object content and returns a new DKBlobDL object containing the result. Note: concatenate( ) is deprecated.

[3373] Parameters:

[3374] aDKBlobDL—another DKBlobDL object

[3375] Returns:

[3376] a new DKBlobDL object containing the result

[3377] Throws: DKException,

[3378] Exception If error occurred

[3379] public DKBlobDL concatenate(byte aByteArr[ ]) throws DKException, Exception

[3380] Concatenates this object content with another stream and returns a new DKBlobDL object containing the result. Note: concatenate( ) is deprecated.

[3381] Parameters:

[3382] aByteArr—a byte array stream

[3383] Returns:

[3384] a new DKBlobDL object containing the result

[3385] Throws: DKException,

[3386] Exception If error occurred

[3387] public DKBlobDL subLob(int startpos,

[3388] int alength) throws DKException, Exception

[3389] Similar to subString, but returns the subString data in form of a new DKBlobDL object. Note: subLob( ) is deprecated.

[3390] Parameters:

[3391] startpos—the byte offset position to start

[3392] alength—the length of bytes to obtain

[3393] Returns:

[3394] a new DKBlobDL object containing the result

[3395] Throws: DKException,

[3396] Exception If error occurred

[3397] public void setRank(int aRank)

[3398] Sets the ranking value of a query

[3399] Parameters:

[3400] aRank—a ranking value

[3401] Overrides:

[3402] setRank in class dkXDO

[3403] public int getRank( )

[3404] Gets the ranking value of a query

[3405] Returns:

[3406] a ranking value

[3407] Overrides:

[3408] getRank in class dkXDO

[3409] public String getMimeType( ) throws DKException, Exception

[3410] Gets the MIME type represents this object's contentClass

[3411] Returns:

[3412] the MIME type

[3413] Throws: DKException,

[3414] Exception If error occurred

[3415] Overrides:

[3416] getMimeType in class dkXDO

[3417] public String mimeType( ) throws DKException, Exception

[3418] Gets the MIME type represents this object's contentClass

[3419] Returns:

[3420] the MIME type

[3421] Throws: DKException,

[3422] Exception If error occurred

[3423] public void setToBeIndexed( ) throws DKException, Exception

[3424] Indexes an existing part object by search engine

[3425] Throws: DKException,

[3426] Exception If error occurred

[3427] public String getCreatedTimestamp( ) throws DKException, Exception

[3428] Gets the data & time that the object was created

[3429] Returns:

[3430] the data & time that the object was created

[3431] Throws: DKException,

[3432] Exception If error occurred

[3433] public String getUpdatedTimestamp( ) throws DKException, Exception

[3434] Gets the data & time that the object was updated

[3435] Returns:

[3436] the data & time that the object was updated

[3437] Throws: DKException,

[3438] Exception If error occurred

[3439] public int getRetrievalAction( ) throws DKException, Exception

[3440] Gets the retrieval option to perform the retrieve action. Note: getRetrievalAction( ) is deprecated. Replace by getOption(int option).

[3441] Returns:

[3442] the retrieval option

[3443] Throws: DKException,

[3444] Exception If error occurred

[3445] See Also:

[3446] getOption

[3447] public void setRetrievalAction(int aRetriveAction) throws DKException, Exception

[3448] Note: setRetrievalAction( ) is deprecated Replace by setOption(int option, Object value)

[3449] Sets the retrieval option to perform the retrieve action.

[3450] Parameters:

[3451] the—retrieval option

[3452] Throws: DKException,

[3453] Exception If error occurred

[3454] See Also:

[3455] setOption

[3456] public int getSize( ) throws DKException, Exception

[3457] Gets the size of this object without retrieve object content.

[3458] Returns:

[3459] the object size

[3460] Throws: DKException,

[3461] Exception If error occurred

[3462] public Object getOption(int option) throws DKException, Exception

[3463] Gets the delete or retrieval option to perform the delete or retrieve action.

[3464] Returns:

[3465] a retrieval or delete option

[3466] Throws: DKException,

[3467] Exception If error occurred

[3468] public void setOption(int option

[3469] Object value) throws DKException, Exception

[3470] Sets the delete or retrieval option to perform the delete or retrieve action.

[3471] Parameters:

[3472] option—an option

[3473] The valid options are:

[3474] DK_OPT_DL_DELETE_OPTION: for delete

[3475] DK_OPT_DL_RETRIEVAL_ACTION: for retrieve

[3476] value—the option value

[3477] For DK_OPT_DL_DELETE_OPTION, the valid values are:

[3478] For Non-media objects only:

[3479] DK_DELETE_ITEM

[3480] Delete item if no more part left in the item.

[3481] DK_DELETE_OBJECT_ONLY(default if not set)

[3482] Don't delete the item, even if there is no more part left in

[3483] the item.

[3484] For Media objects only:

[3485] DK_DELETE NO_DROPITEM_MEDIA_AVAIL

[3486] Don't delete the item if there is no part left in the item.

[3487] Cannot delete media parts (media objects) when they are in

[3488] use.

[3489] DK_DELETE NO_DROPITEM_MEDIA_INUSE

[3490] Don't delete the item, even if there is no part left in the

[3491] item. User can delete media parts (media objects), even if

[3492] they are in use.

[3493] DK_DELETE_DROPITEM_MEDIA_AVAIL

[3494] Delete the item if there is no part left in the item. Cannot

[3495] delete media parts (media objects) when they are in use.

[3496] DK_DELETE_DROPITEM_MEDIA_INUSE

[3497] Delete the item if there is no part left in the item. Can

[3498] delete media parts (media objects), even if they are in use.

[3499] For DK_OPT_DL_RETRIEVAL_ACTION, the valid values are:

[3500] DK_RETRIEVAL_GET_IT

[3501] DK_RETRIEVAL_GET_IT_PREFETCH

[3502] DK_RETRIEVAL_NO_MOUNT

[3503] DK_RETRIEVAL_NO_MOUNT_PREFETCH

[3504] DK_RETRIEVAL_STAGE_IT

[3505] DK_RETRIEVAL_STAGE_IT_PREFETCH

[3506] Throws: DKException,

[3507] Exception If error occurred

[3508] public void setExtension(String extensionName,

[3509] dkExtension extensionObj) throws DKException, Exception

[3510] Sets the extension object.

[3511] Parameters:

[3512] extensionName—the extension name

[3513] The valid extension names are:

[3514] DKSearchEngineInfoDL

[3515] For an annotation object, user needs to set this extension object

[3516] to hold the affiliated informations.

[3517] DKAnnotationDL

[3518] For a search indexed object, user needs to set this extension

[3519] object to hold the search indexed informations.

[3520] DKMediaStreamInfoDL

[3521] For a media object, user needs to set this extension object to

[3522] hold the media user data.

[3523] DKStorageManageInfoDL

[3524] If user wants to associate this part with different storage

[3525] collection name, user needs to set this extension object to hold

[3526] the storage collection information.

[3527] extensionObj—a source extension object

[3528] Throws: DKException,

[3529] Exception If error occurred

[3530] public void addExtension(String extensionName,

[3531] dkExtension extensionObj) throws DKException, Exception

[3532] Adds the extension object.

[3533] Parameters:

[3534] extensionName—the extension name

[3535] extensionObj—a source extension object

[3536] Throws: DKException,

[3537] Exception If error occurred

[3538] Overrides:

[3539] addExtension in class dkXDO

[3540] public dkExtension getExtension(String extensionName) throws DKException, Exception

[3541] Gets the extension object.

[3542] Parameters:

[3543] extensionName—the extension name

[3544] The valid extension names are:

[3545] DKSearchEngineInfoDL

[3546] DKAnnotationDL

[3547] DKMediaStreamInfoDL

[3548] DKStorageManageInfoDL

[3549] Returns:

[3550] a dkExtension object

[3551] Throws: DKException,

[3552] Exception If error occurred

[3553] Overrides:

[3554] getExtension in class dkXDO

[3555] public void removeExtension(String extensionName) throws DKException

[3556] Removes the extension object.

[3557] Parameters:

[3558] extensionName—the extension name

[3559] The valid extension names are:

[3560] DKSearchEngineInfoDL

[3561] DKAnnotationDL

[3562] DKMediaStreamInfoDL

[3563] DKStorageManageInfoDL

[3564] Throws: DKException

[3565] If error occurred

[3566] Overrides:

[3567] removeExtension in class dkXDO

[3568] public boolean isCategoryOf(int categoryName) throws DKException, Exception

[3569] Checks the object category.

[3570] Parameters:

[3571] categoryName—the category name

[3572] The valid category names are:

[3573] DK_MEDIA_OBJECT

[3574] DK_INDEXED_object

[3575] Returns:

[3576] true if the object is the specified category; false otherwise.

[3577] Throws: DKException,

[3578] Exception If error occurred

[3579] public int retrieveObjectState(int object) throws DKException, Exception

[3580] Retrieves the state of search indexed object or media object.

[3581] Parameters:

[3582] object—the type of object

[3583] The valid input are:

[3584] DK_MEDIA_OBJECT

[3585] DK_INDEXED_object

[3586] Returns:

[3587] the object state

[3588] For media object, the valid states are:

[3589] 1: Pending, load in progress

[3590] 2: Load completed successfully

[3591] 3: Load failed

[3592] For search indexed object, the valid states are:

[3593] 256: to be updated

[3594] 512: to be deleted

[3595] 769: queued update

[3596] 770: queued delete

[3597] 1024: indexed

[3598] Throws: DKException,

[3599] Exception If error occurred

[3600] public void changeStorage( ) throws DKException, Exception

[3601] Changes the system-managed storage (SMS) criteria for an object. The collection name, management class name and storage class name will be all converted to upper case by the system. These names must be valid on the object server where user stores the object. If user changes the collection name and specify a null string as the class name, the function places the object in the default class for the specified collection. User cannot move the object from one server to another using this function, therefore user cannot change the StoreSite. If the change causes any physical movement of the object, it might be deferred until the storage management cycle runs on the server.

[3602] Throws: DKException,

[3603] Exception If error occurred

[3604] public int getPartId( )

[3605] Gets the part id of this XDO

[3606] Returns:

[3607] the part id

[3608] public void setPartId(intpartId)

[3609] Gets the part id of this XDO

[3610] Returns:

[3611] the part id

[3612] public String[ ] listStreamName( ) throws DKException, Exception

[3613] Returns a string array which contains a listing of all stream names in the current content. returns null if (multi)stream content not set (available). Note: if the content is not set, will attempt to retrieve the content from the object server.

[3614] Returns:

[3615] string array containing current stream names, else null.

[3616] Throws: DKException

[3617] (Exception) if error occurs.

[3618] public byte[ ] getStreamContent(String sName) throws DKException, Exception

[3619] Returns the content of the stream specified by sName. If the stream does not exist throws DKException. If this is not a (multi)stream object then returns content of primary stream (lobData).

[3620] Parameters:

[3621] sName—name of string to retrieve content.

[3622] Returns:

[3623] byte array stream content corresponding to sName, else content of

[3624] primary stream.

[3625] Throws: DKException

[3626] is thrown if this is a (multi)stream object and stream does not exists

[3627] with name sname.

[3628] public void setStreamContent(String sName,

[3629] byte aByteArray[ ]) throws DKException, Exception

[3630] Sets the content of the stream specified by sName to aByteArray. If the stream does not exist a new stream is added with streamName=sName and content=aByteArray. If this is not a (multi)stream object, the primary stream content is set to aByteArray instead.

[3631] Parameters:

[3632] sName—name of stream to set content.

[3633] aByteArray—content to set.

[3634] Throws: DKException

[3635] (Exception) if error occurs.

[3636] public long streamLength(String sName) throws DKException, Exception

[3637] Returns the length of the content of the stream specified by sName. If the stream does not exist throws DKException. If this is not a (multi)stream object then returns content of primary stream (lobData). Note: calls getStreamContent(String) for content.

[3638] Parameters:

[3639] sName—name of string to retrieve content's length.

[3640] Returns:

[3641] length of byte array stream content corresponding to sName, else length

[3642] of content of primary stream.

[3643] Throws: DKException

[3644] is thrown if this is a (multi)stream object and stream does not exists

[3645] with name sname.

[3646] public boolean isMultiStreamBlob( )

[3647] Returns true if current content is multistream, false otherwise.

[3648] public boolean isMultiStreamFlagSet( )

[3649] Returns true if the object server content is checked for Multistream, false otherwise.

[3650] 9. Federated Collection

[3651] A federated collection allows an application program to process data objects resulting from a query as a group or collection and at the same time preserves the sub-grouping relationships that exists between them. It provides the user with a mechanism:

[3652] to aggregate several collection of data objects while preserving each individual collection information

[3653] to treat these collections as one whole unit of collection, ignoring

[3654] collection boundaries

[3655] A federated collection is a collection containing DKResults objects, it is created to hold the results of DKFederatedQuery, which may come from several heterogenous datastores. Each DKResults contains the results of subquery of the federated query submitted to a specific native datastore associated with the federated datastore. To iterate over federated collection members (which are DKResults objects), a user should create and use dkIterator or DKSequentialIterator to pull each DKResults object. Then he could create another dkIterator on this DKResults to iterate over it and to process the result according to its datastore origin. Alternatively, the user can create a federated iterator, dkFederatedIterator, and use it to iterate over all element members across collection boundaries, regardless of which datastore the result came from. In theory, a federated collection can contains other nested collections up to any arbitrary depth. In the current implementation, a federated collection is not queryable. See Also: dkFederatedIterator, dkIterator, DKSequentialIterator.

[3656] An example class definition for DKFederatedCollection is set forth below.

[3657] The following methods are part of the DKFederatedCollection class:

[3658] public DKFederatedCollection( )

[3659] Default constructor

[3660] public int cardinality( )

[3661] Returns the number of all individual (leaf) elements (non-collection) across the collection boundaries. This is the total of all elements in each sub-collections.

[3662] Overrides:

[3663] cardinality in class DKSequentialCollection

[3664] public int memberCardinality( )

[3665] Returns the number of elements in the collection. The element could be a collection object, i.e. DKResults object, not necessarily a leaf element (non-collection).

[3666] public dkIterator createIterator( )

[3667] Creates a new dkFederatedIterator for this federated collection. This iterator can be used to iterate over the federated collection, across collection boundaries, returning a (non-collection) member one at a time.

[3668] Returns:

[3669] an iterator

[3670] Overrides:

[3671] createiterator in class DKSequentialCollection

[3672] public dkIterator createMemberIterator( )

[3673] Creates a new iterator for this federated collection. The new iterator would be supporting DKSequentialIterator interface. That is, the method “next” of this iterator would return a collection, such as DKResults object. User can then, create an iterator on this DKResults to iterate over its member.

[3674] Returns:

[3675] an iterator

[3676] public Object retrieveElementAt(dkIterator where) throws DKUsageError

[3677] Gets the element that the iterator is pointing at

[3678] Parameters:

[3679] where—location in collection to retrieve an object

[3680] Returns:

[3681] an element

[3682] Overrides:

[3683] retrieveElementAt in class DKSequentialCollection

[3684] public void addElement(Object element) throws DKUsageError

[3685] Adds an element to the end of the collection, and invalidates all of the current iterators.

[3686] Parameters:

[3687] element—element to be added

[3688] Overrides:

[3689] addElement in class DKSequentialCollection

[3690] public void addAllElements(dkCollection elements) throws DKUsageError

[3691] Adds all elements in the collection, and invalidates all of the current iterators.

[3692] Parameters:

[3693] elements—collection of elements to be added

[3694] Overrides:

[3695] addAllElements in class DKSequentialCollection

[3696] public void insertElementAt(Object element,

[3697] dkIterator where) throws DKUsageError

[3698] Adds a new element, after the element the iterator is currently pointing at. The iterator is advanced to the new element, invalidating all other iterators.

[3699] Parameters:

[3700] element—element to be added

[3701] where—location in collection

[3702] Overrides:

[3703] insertElementAt in class DKSequentialCollection

[3704] public void replaceElementAt(Object element,

[3705] dkIterator where) throws DKUsageError

[3706] Replaces the element the iterator is currently pointing at.

[3707] Parameters:

[3708] element—element to be added

[3709] iter—location in collection

[3710] Overrides:

[3711] replaceElementAt in class DKSequentialCollection

[3712] public void removeElementAt(dkIterator where) throws DKUsageError

[3713] Removes the element the iterator is currently pointing at. The iterator is advanced to the next element after this operation, invalidating all other iterators.

[3714] Parameters:

[3715] iter—location in collection

[3716] Overrides:

[3717] removeElementAt in class DKSequentialCollection

[3718] public void removeAllElements( )

[3719] Removes all elements in the collection Invalidates all other iterators.

[3720] Overrides:

[3721] removeAllElements in class DKSequentialCollection

[3722] public void sort( ) throws DKUsageError

[3723] Sort is not supported in the FederatedCollection. Exception will be thrown if this function is called.

[3724] Overrides:

[3725] sort in class DKSequentialCollection

[3726] public void sort(boolean order) throws DKUsageError

[3727] Sort is not supported in the FederatedCollection. Exception will be thrown if this function is called.

[3728] Overrides:

[3729] sort in class DKSequentialCollection

[3730] public void sort(dksort sortFunction,

[3731] boolean sortOrder) throws DKUsageError

[3732] Sort is not supported in the FederatedCollection. Exception will be thrown if this function is called.

[3733] Overrides:

[3734] sort in class DKSequentialCollection

[3735] A federated iterator is used to iterate over the collective members of DKFederatedCollection across collection boundaries. The next( ) method returns DDO objects until all collections are iterated over. This iterator is created by invoking the method createIterator( ) in the DKFederatedCollection object. See Also: dkIterator, DKSequentialIterator

[3736] An example class definition for dkFederatedIterator is set forth below.

[3737] The following methods are part of the dkFederatedIterator class:

[3738] public abstract Object next( ) throws DKUsageError

[3739] Returns the current element in the collection and advances the iterator to the next position. In case the element is a collection, it goes inside that collection and retrieves the first element recursively, until it finds an element which is not a collection. When the current collection is exhausted, this iterator will find the next collection and extract the first element (non-collection) from it.

[3740] Throws: DKUsageError

[3741] if already at the last item in collection

[3742] public abstract void reset( )

[3743] Resets the iterator to the beginning of DKFederatedCollection.

[3744] public abstract boolean more( )

[3745] Returns true if there are more elements in the DKFederatedCollection. In this case, an element implicitly means a collection member which is not a collection (a leaf).

[3746] public abstract Object previous( ) throws DKUsageError

[3747] Returns the current element in the collection and moves the iterator backward one position. In case the element is a collection, it goes inside that collection and retrieves the last element, until it finds an element which is not a collection. When the current collection is exhausted, this iterator will find the previous collection and extract the last element (non-collection) from it.

[3748] Throws: DKUsageError

[3749] if already at the first item in collection

[3750] public abstract Object at( ) throws DKUsageError

[3751] Returns the current element in the collection without moving the iterator position. The returned element is not a collection. Throws: DKUsage if collection is empty, or current position is invalid.

[3752] public abstract boolean setToFirst( )

[3753] Sets the iterator to the first element in this federated collection. The first element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3754] public abstract boolean setToLast( )

[3755] Sets the iterator to the last element in this federated collection. The last element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3756] public abstract boolean setToNext( )

[3757] Sets the iterator to the next element in this federated collection. The next element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3758] public abstract boolean setToPrevious( )

[3759] Set the iterator to the previous element in this federated collection. The previous element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3760] public abstract boolean setToFirstCollection( )

[3761] Sets the iterator to the first element in the first collection in this federated collection. The first element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3762] public abstract boolean setToLastCollection( )

[3763] Sets the iterator to the last element in the last collection in this federated collection. The last element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3764] public abstract boolean setToNextCollection( )

[3765] Sets the iterator to the first element in the next collection in this federated collection. The first element is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3766] public abstract boolean setToPreviousCollection( )

[3767] Sets the iterator to the last element in the previous collection in this federated collection. The first last is not a collection. Returns true if the operation is successful, otherwise it returns false.

[3768] 10. Sequential Collection

[3769] DKSequentialCollection is a subclass of dkCollection which supports sorting and sequential access in a bi-directional manner, i.e. forward and backward. A sequential collection is not queryable. DKSequentialCollection can create and support DKSequentialIterator, which is also bi-directional.

[3770] An example class definition for DKSequentialCollection is set forth below.

[3771] The following methods are part of the DKSequentialCollection class:

[3772] public DKSequentialCollection( )

[3773] Constructs a DKSequentialCollection.

[3774] public DKSequentialCollection(dkSort sortFunction)

[3775] Constructs a DKSequentialCollection with the given sort function.

[3776] Parameters:

[3777] sortFounction—sort function.

[3778] public int cardinality( )

[3779] Gets the number of elements in the collection.

[3780] Returns:

[3781] the number of elements.

[3782] public dkIterator createIterator( )

[3783] Creates a new iterator for this collection. The default is DKSequentialIterator object.

[3784] Returns:

[3785] an iterator

[3786] public Object retrieveElementAt(dkIterator iter) throws DKUsageError

[3787] Gets the element that the iterator is pointing at.

[3788] Parameters:

[3789] iter—location in collection to retrieve an object.

[3790] Returns:

[3791] an element

[3792] public void addElement(Object element) throws DKUsageError

[3793] Adds an element to the end of the collection, and invalidates all of the current iterators.

[3794] Parameters:

[3795] element—element to be added.

[3796] public void insertElementAt(Object element,

[3797] dkIterator iter) throws DKUsageError

[3798] Adds a new element, after the element the iterator is currently pointing at. The iterator is advanced to the new element, invalidating all other iterators.

[3799] Parameters:

[3800] element—element to be added.

[3801] iter—location in collection.

[3802] public void replaceElementAt(Object element,

[3803] dkIterator iter) throws DKUsageError

[3804] Replaces the element the iterator is currently pointing at.

[3805] Parameters:

[3806] element—element to be added.

[3807] iter—location in collection.

[3808] public void removeElementAt(dkIterator iter) throws DKUsageError

[3809] Removes the element the iterator is currently pointing at. The iterator is advanced to the next element after this operation, invalidating all other iterators.

[3810] Parameters:

[3811] iter—location in collection

[3812] public void removeAllElements( ) throws DKUsageError

[3813] Removes all elements in the collection and invalidates all other iterators.

[3814] public void setName(String name)

[3815] Sets the name of the collection.

[3816] Parameters:

[3817] name—collection name.

[3818] public String getName( )

[3819] Gets the name of the collection.

[3820] Returns:

[3821] collection name

[3822] public void setSortFunction(dkSort sortFunction)

[3823] Sets the sort function for sorting this collection.

[3824] Parameters: