Release 9.0.1.1.0
Part Number A90093-02
 Contents |
 Index |
| Oracle Internet File System Developer Reference Release 9.0.1.1.0 Part Number A90093-02 |
|
The Oracle Internet File System provides a number of mechanisms designed to enable a wide range of customizations and applications. One mechanism, the Java API, provides a powerful, object-oriented interface for working with information in Oracle 9iFS. Topics include:
The Java API fully exposes the functionality of the Oracle 9iFS server so that you can leverage its content management capabilities in your application. Since it is implemented in Java, you can use standards-based technologies, such as Java Server Pages, J2EE, and Java Beans, that are suitable for building Internet applications.
If the Java API is new to you, however, the Javadoc may not be the place to start. The Oracle 9iFS Java API includes over two hundred classes. Besides self-explaining classes, such as Document and Folder, the API includes many other classes whose purpose may not be immediately apparent, such as SystemObject classes, SchemaObject classes, Tie classes, Server-side classes, and Definition classes.
Think of this chapter as an orientation to one aspect of the development platform. As such, it is most likely to be useful in two scenarios: either as an introduction to the API, to be read in its entirety, or as a reference, to be scanned for specific information on classes, once you have determined your objective.
For an explanation of how documents and users are modeled in Oracle 9iFS, and a look at all the tools you can use to work within this platform, consult Chapter 1, "Getting Started with the Oracle Internet File System SDK".
The Java API is organized into a set of Java packages. Packages make it easier to browse through and work with the API. The packages organize the classes in the Java API according to how they are used by applications. Table 3-1lists the packages in the Java API.
Table 3-1 Packages in the Oracle 9iFS Java API
| Package name | Notes | See also |
|---|---|---|
|
oracle.ifs.adk.filesystem |
This package provides a simplified interface for working with files and folders. The IfsFileSystem class in this package performs higher-level functions, which, in turn, may execute multiple lower-level calls to other packages. This package exposes simple file and folder manipulation, including some versioning and file locking, but excluding security and full-text searching. |
|
|
oracle.ifs.adk.mail |
This class implements e-mail messaging. |
|
|
oracle.ifs.adk.security |
This package contains one interface for managing secure web access. |
|
|
oracle.ifs.adk.user |
The UserManager class creates and manages users. |
|
|
oracle.ifs.beans |
This package provides the primary interface for building custom applications which leverage the content management capabilities of Oracle 9iFS. The classes are also referred to as the bean-side Java classes. Use classes in this package to establish a repository session, and to perform discover, create, modify, and delete actions on Oracle 9iFS objects. |
Chapter 8, "Building Search Applications", Chapter 5, "Extending Content Types and Attributes" |
|
oracle.ifs.beans.parsers |
This package includes interfaces and classes required when creating custom parsers. |
Chapter 9, "Creating a Custom Parser", Chapter 10, "XML and the Oracle Internet File System" |
|
oracle.ifs.beans.resources |
The class in this package handles error codes and localized strings for the repository. |
|
|
oracle.ifs.common |
This package includes classes which are required for managing user sessions, collections, event notification, caching, localization and access to Oracle Text themes. |
|
|
oracle.ifs.management.domain |
This package includes two interfaces and one class used to build servers. Servers, previously called Agents, are used to automate tasks to be performed in the background against the Oracle 9iFS. This package is used instead of the deprecated package oracle.if.agents.common. |
|
|
oracle.ifs.search |
The classes in this package are used with the oracle.ifs.beans.Search class to construct and execute complex queries. |
|
|
oracle.ifs.server |
The classes in this package are also referred to as the server-side Java classes. The classes implement Oracle 9iFS behavior. While the oracle.ifs.beans package is used to access Oracle 9iFS functionality, these classes contain the code which implements the functionality. The server-side Java classes can be overridden to change how the Oracle 9iFS server performs certain tasks, such as insert, update and delete. |
|
|
oracle.ifs.server.renderers |
This package includes three renderer classes and one interface for creating custom renderers and using Oracle 9iFS XML rendering functionality. |
Chapter 11, "Creating a Custom Renderer", Chapter 10, "XML and the Oracle Internet File System" |
|
oracle.ifs.server.sql |
These classes allow execution of SQL statements on custom tables in the Oracle 9iFS schema. |
As you begin the process of designing and building custom applications, you may want to take a functional view of the classes in the API. This section places the APIs in task-based order.
At the top-level of the oracle.ifs.beans package, Oracle 9iFS provides two classes, LibraryService and LibrarySession, that act as the primary interface for connecting to the repository.
These classes are supported by several classes in the oracle.ifs.common package, including ChallengeResponseCredential, CleartextCredential, HTTPDigestCredential, TokenCredential, and ConnectOptions, which are used to construct the username, password, and other information required to connect to Oracle 9iFS.
Most of the classes in the Java API are used to manage various types of information stored in the repository. These classes descend from a top-level class in the oracle.ifs.beans package, LibraryObject. This class represents the basic unit of information in the repository. The class LibrarySession serves as a factory for creating instances of these classes.
Oracle 9iFS provides a flexible information model, allowing you to define special content types and create rules and behavior for each of these types. Since defining custom content types is so fundamental to any customization, several techniques are provided. You can use the Oracle9i Enterprise Manager tool, drop in an XML file, or use the Java API. The API includes a set of classes that descend from the SchemaObject class in the oracle.ifs.beans package, and allow you to define the structure of a content type, the tables used to store that type of information, and the Java classes that implement the content type's behavior.
Oracle 9iFS allows you to customize the behavior of content types by extending the Java classes which implement their behavior. The Oracle 9iFS Java API includes Tie classes which provide an orderly way to extend Java classes at any point in the class hierarchy. The naming convention, Tie<classname>, preserves the names of the Java classes for each content type, making your customization easier for you to implement, and easier for others to understand after the fact.
Each content type has a corresponding Definition class, which descends from the LibraryObjectDefinition class in the oracle.ifs.beans package. The Definition classes are used to create new content type instances. To create an instance of Document, for example, you would create a DocumentDefinition object and pass that to a method on LibrarySession to create the document. The resulting document is a persistent object stored in the Oracle 9iFS repository. The naming convention, <classname>Definition, preserves the names of the Java classes for the corresponding content type.
At the top level of the oracle.ifs.beans package, Oracle 9iFS provides four primary classes for searching the repository and working with search results: Selector, Search, SearchResultObject and FolderPathResolver.
Three sets of classes process information on the server. The oracle.ifs.beans.parsers package includes classes for automatically parsing information before it is stored in the repository. The oracle.ifs.server.renderers package includes classes for automatically rendering information being retrieved from the repository. The oracle.ifs.management.domain package includes classes for building servers that automate tasks that perform operations against the Oracle 9iFS server, for example, removing information that has expired.
Oracle 9iFS provides a set of classes for managing application connections to the repository. The two primary classes used to connect to the repository are LibraryService and LibrarySession. These classes are located at the top-level of the oracle.ifs.beans package. They are supported by a few other classes located in the oracle.ifs.common package used to hold the information required to authenticate the connection.
The LibraryService class is used to establish the connection to the Oracle 9iFS database schema. The LibraryService manages multiple client sessions for Oracle 9iFS. It is used to start and stop client sessions, time out latent sessions, trace sessions, manage events, and cache shared information across sessions. LibraryServices are configured with a service properties file located in the Oracle software home directory on the Oracle 9iFS server. Multiple LibraryServices can be run and configured separately to manage different types of client sessions.
For more information about configuring services with service property files, consult the Oracle 9iFS Setup and Administration Guide.
Table 3-2 lists the most commonly used methods on LibraryService.
Table 3-2 LibraryService MethodsThe LibrarySession class is used to represent each client session for Oracle 9iFS. Every time a user logs into Oracle 9iFS through a client, a LibrarySession is created to manage how the user interacts with Oracle 9iFS while logged in. The time the user is logged in is called a 'session'. The LibrarySession keeps track of the state of the user's session. It is also the primary factory for doing anything with Oracle 9iFS. For example, the LibrarySession is used to create, delete, and update instances of content types. It is used to construct and execute Searches.
Table 3-3 lists the most commonly used methods on LibrarySession.
Table 3-3 LibrarySession Methods
When the LibraryService establishes a connection, it must be passed a set of connection options, including the Oracle 9iFS server being connected to, and the user's credentials. The ConnectOptions class in the oracle.ifs.common package holds the connection information that is passed to the LibraryService, including the Locale, Service name, and Service password. The classes, ChallengeResponseCredential, CleartextCredential, HttpDigestCredential, and TokenCredential, are used to hold different types of user credentials which are used to authenticate the user's connection to Oracle 9iFS.
Table 3-4 lists the most commonly used methods on ConnectOptions.
Table 3-5 lists the most commonly used methods on ClearTextCredential.
|
setName() |
Determines the name of the user. |
|
setPassword() |
Determines the user's password. The password is passed unencrypted. |
Table 3-6 lists the most commonly used methods on ChallengeResponseCredential.
|
setName() |
Determines the name of the user. |
|
setChallenge() |
Determines the challenge. |
|
setResponse() |
Determines the response. |
|
setType() |
Determines the type of response. |
Table 3-7 lists the most commonly used methods on HTTPDigestCredential.
Table 3-8 lists the most commonly used methods on TokenCredential.
Virtually any type of information can be managed in Oracle 9iFS. Although it is pre-configured to manage documents, folders, users, and groups, you can add custom information types specific to your business, such as medical records, insurance claims, and engineering specifications.
Each type of information in Oracle 9iFS is defined as a content type, with a defined set of attributes and behaviors. Attributes are used to describe the type of information, like Name, Owner, Size, and Format. Behaviors define what you can do with the information, like listing the items in a folder, or fetching the content of a document.
Each content type consists of two parts:
For example, the Document content type consists of a set of tables that store the data for documents managed by Oracle 9iFS. In these tables, the documents' file contents are stored in a LOB column, and attributes like Name, Description, Format, and Size are stored in scalar columns. A set of Java classes, Document.class and S_Document.class, are used to implement the behavior of documents in Oracle 9iFS, like updating the content of the document, or summarizing the document's content. These behaviors are implemented by methods on the Java classes, respectively, setContent() and getSummary().
Information in the Oracle 9iFS repository is stored as data rows in the content type's tables. To leverage the capabilities of the RDBMS, and optimize the storage and retrieval of the information, the data may be normalized across several tables in the database. When you use Oracle 9iFS to manipulate information in the repository, the information is represented by the API as instances of the content type's Java classes. Representing information as instances of Java classes enables applications to manage information in an object-oriented manner. For example, you don't have to know how a document's attributes and file contents are stored across tables in the database. Instead, the whole document can be fetched with a single API call, and then manipulated as an object.
As illustrated in Figure 3-1, "Content Type Hierarchy", Oracle 9iFS organizes content types hierarchically to make it easier to define content types that are similar. A content type inherits the attributes and behavior from the content type that precedes it in the hierarchy. For example, Document and Folder share certain attributes such as Owner, Description, LockState, and behaviors like setOwner, getDescription, and lock. To make it easier to define their shared attributes and behaviors, Document and Folder descend from PublicObject. PublicObject defines the common attributes and behaviors for all information with which users work. All content types that descend from PublicObject inherit its attributes and behaviors. When appropriate, each content type may override certain attributes and behaviors which it inherited. Since the Oracle 9iFS server is implemented in Java, the content type hierarchy follows the rules of inheritance defined for the Java language.
The Oracle 9iFS content type hierarchy is fully extensible. You can extend the hierarchy to include custom content types that you use to manage business-specific types of information. When you create a custom content type, you first define the attributes and behaviors for your information. Then you choose a content type which your custom content type will extend. By extending another content type, your custom content type can inherit some of the attributes and behaviors already built into Oracle 9iFS. For example, to create a custom content type to manage a book, you might extend Document to inherit the attributes and behaviors for managing file content. You can then add more attributes and methods, and override the inherited methods, to customize how Oracle 9iFS manages books.
The Oracle 9iFS Java API includes classes which are used to define, instantiate and manage content types. The API's class hierarchy parallels the content type hierarchy.
At the top of the class hierarchy is LibraryObject, which defines attributes and behaviors that are common to all information managed by Oracle 9iFS. For example, everything managed by Oracle 9iFS has the attributes ID, a long number which uniquely identifies the object, and Name, a string which provides a more descriptive label for the object. LibraryObjects also define common behaviors, like deleting the information from the repository with the Java method free(). Below LibraryObject, the class hierarchy has two branches:
The PublicObject and SystemObject classes can be grouped according to their function:
The Oracle 9iFS Java API includes a set of PublicObject and SystemObject classes for managing three basic content types:
When you create custom content types, you will usually choose to extend one of these three according to your content type's physical structure and behavior. If your custom content type requires methods for managing unstructured content, you would extend Document. If your custom content type requires containership behavior, like adding items, removing items and listing contents, then you would extend Folder. If your custom content type does not possess unstructured content, nor containership qualities, but should be handled as a PublicObject, then you may choose to extend ApplicationObject.
Documents are information which possesses unstructured content. Figure 3-2, "Document Object Model" illustrates the three classes used to define documents:
The Document class possesses the basic attributes of any piece of information managed inOracle 9iFS, for example, Name, Description, Owner, Creator, CreateDate, LastModifier, LastModifyDate. It also possesses the attribute ContentObject for working with the document's unstructured content. The unstructured content of a document is not actually stored in the ContentObject attribute. Instead, the ContentObject attribute on the Document class references an instance of the ContentObject class, which is used to hold and manage the document's content.
The ContentObject class possesses attributes that are specific for unstructured content, such as Format, Language, and Media. It also possesses methods for manipulating the content, for example, getContentStream() and getFilteredContent().
Normalizing the document's content as a separate object gives you more flexibility when working with the document's content.
The format of the document's content is also managed with another class, Format. Format possesses attributes for managing information about a content format, such as its MimeType and Extension, and methods for working with the format, like isBinary(), which determines if the format is Binary or ASCII. An instance of Format is created to represent each known content format. Several Format instances are created automatically when Oracle 9iFS is installed. The Format attribute on the ContentObject references a Format instance that represents the format of the document's content.
Document descends from PublicObject. Therefore, it possesses attributes and behaviors that can be manipulated by application end users. ContentObject descends from SystemObject. It cannot be directly manipulated by an end user who does not have administrative privileges. Document provides the interfaces for end users to manipulate the document's ContentObject. Format also descends from SystemObject. Only users with administrative privileges can create and modify Format instances.
Table 3-9 lists the most commonly used attributes and methods on Document.
|
|
Determines the name of the document. |
|
setDescription() |
Provides a description of the document. |
|
setOwner() |
Determines which user owns the document. The owner of the document implicitly has full access rights to the document. The Owner attribute references an DirectoryUser. |
|
revokeAllAccess() |
Determines the AccessControlList for the document. The ACL attribute references an AccessControlList. |
|
Creator |
Determines which user originally created the document. The Creator attribute references a DirectoryUser. The Creator attribute is set by the Oracle 9iFS system. |
|
CreateDate |
Stores the date and time when the document was created. The attribute is set by the Oracle 9iFS system. |
|
LastModifier |
Determines which user who last modified the document. The LastModifier attribute references a DirectoryUser. The LastModifier attribute is set by the Oracle 9iFS system. |
|
LastModifyDate |
Stores the date and time when the document was last updated. The attribute is set by the Oracle 9iFS system. |
|
setExpirationDate() |
Determines when the document should expire. An application developer can create an agent that manages how the document is expired when this date is reached. |
|
setLanguage() |
Manipulates the document's unstructured content. The ContentObject attribute references a ContentObject that represents the document's content. The getContentObject() method can be used to retrieve the ContentObject instance. The ContentObject attribute holds the unique identifier for the ContentObject instance as its value. The getContentObject() method uses the identifier to retrieve the ContentObject instance, which you can then manipulate as an object. The setContent() method creates a new ContentObject instance, and sets the value of the ContentObject attribute with the new instance's identifier.NOTE: : Each time a non-versioned document is updated, the setContent() method creates a new ContentObject. For information about how documents are versioned, refer to Chapter 14, "Implementing Versioning in a Custom Application". Document also provides convenience methods for working with the ContentObject instance directly from the Document instance, like getFormat(), getContentSize(), and getContentReader(). |
Table 3-10 lists the most commonly used attributes and methods on ContentObject.
Table 3-11 lists the most commonly used attributes and methods on Format.
Folders are objects that contain other objects. Folders behave in the Oracle 9iFS clients like traditional file system folders and are used to organize the repository. As illustrated in Figure 3-3, "Folder Object Model", folders are primarily managed with two components:
Folder extends the PublicObject class and, therefore, inherits basic attributes, such as Name, Description, Owner, Creator, CreateDate, LastModifier, and LastModifyDate. It also possesses methods for managing the contents of the folder; e.g., addItem(), removeItem(), getItemCount(), and getItems().
The relationship between a folder and the items which it contains are represented by a FolderPathRelationship. FolderPathRelationship uses two attributes to represent the relationship; LeftObject, which references the folder, and RightObject, which references the object contained by the folder. The LeftObject and RightObject attributes on FolderPathRelationship can reference any instance of any class that extends PublicObject, including Document, Folder, and ApplicationObject. FolderPathRelationship also includes attributes and behavior that make it easier to work with path-oriented relationships. For example, FolderPathRelationship has built in logic to ensure that items within a folder are uniquely named, to prevent illegal file and folder names, and to make it easier to find items based on a relative folder path.
Since Folder extends PublicObject, it is the primary public interface for non-administrative users to manipulate folders. FolderPathRelationship descends from SystemObject and cannot be directly manipulated by non-administrative users. Folder provides the methods, such as addItem(), removeItem(), and getItems(), for creating, deleting and retrieving the instances of FolderRelationship.
Table 3-12 lists the most commonly used attributes and methods on Folder.
Table 3-13 lists the most commonly used attributes and methods on FolderRelationship.
ApplicationObject acts as a starting point for defining extended content types that should have the qualities of a PublicObject, but that don't have the qualities of a Document or Folder. ApplicationObject inherits all of the attributes and methods of PublicObject, but does not include any extended attributes or methods that have a special purpose.
For example, if you were implementing a application for managing customer relationships, you could create a Customer content type that possesses attributes about a customer, like Primary Contact, Telephone Number, and Address. Since a customer does not possess unstructured content, you would not extend Document. Since a customer does not possess containership behavior, you would not extend Folder. Therefore, ApplicationObject would provide a basis for this content type. By extending ApplicationObject, the Customer content type inherits the behavior and attributes of PublicObject, so that you can control how end users access and work with customer information.
Table 3-14 lists the most commonly used attributes and methods on ApplicationObject.
The classes discussed in the previous section are intended to manage different physical types of information. For example, Document manages information that has unstructured content. Folder manages information with containership behavior.
Oracle 9iFS also provides classes for apply extra metadata to different physical types of information:
These classes are used to describe the context of documents, folders, and other public objects. They describe how the information is used in a business, and how it relates to other information in the repository. The extra metadata can be used to search for information in the repository, or as the basis for business rules for how the information is managed by overrides and servers.
Oracle 9iFS provides a class, Category, that you can use to organize information into one or more business categories. By virtue of belonging to a category, you can add extra attributes and behaviors to your information. Since categories are managed as a separate classes, you can apply the same business metadata to different physical types of information.
As illustrated in Figure 3-4, "Category Object Model", you could create categories for Business White Papers, Proposals, Drafts for Legislature, and Bills, by extending Category. You could then specify additional attributes which are pertinent for each category. For example, Business White Papers may have the attributes Product Name and Marketing Campaign, while Request for Proposals may have the attributes Project and Cost.
A Microsoft Word file, stored as an instance of Document, could then be categorized as a Proposal by creating an instance of the Proposal class for that Document instance. The Proposal instance references the Document which is being categorized with an attribute named AssociatedPublicObject. In addition, the Proposal instance possesses values for each of the extra attributes pertinent to the Document's use as a Proposal. After the proposed project is initiated, the same Document can be embellished into a Business White Paper about the project's product. An instance of the Business White Paper class can be applied to the Document to add attributes that are now pertinent to its new use.
A Category can also possess custom behavior that is only applied when information is categorized as such. For example, the Bill class can possess methods that ensured that a Document can not become a Bill unless it had already been categorized as a Draft for Legislature. The Bill methods can then validate a Digital Signature attribute on the Draft for Legislature instance, to ensure that the Draft has been authorized to become a Bill.
The same Category can be applied to any physical type of information, including Documents, Folders, and ApplicationObjects. For example, you may have a folder containing a set of Adobe FrameMaker files which together comprise a Business White Paper. You can create an instance of the Business White Paper class for the Folder to store attributes about the Folder's use as a Business White Paper. Later, when the FrameMaker book is published as a single PDF file, the Document containing the PDF document can also be categoried as a Business White Paper.
Category classes are organized hierarchically to make it easier to define custom attributes and behavior. For example, you can create a Report class that extends Category with the attributes DateGenerated and DataSource. Then, you can extend the Report class to create a Financial Report with the attributes Quarter and Fiscal Year, and a Bug Report with the attributes Product Number and Component.
You can search for PublicObjects based on their Category metadata. To do so, create a Search including AttributeQualifications that specify the criteria about the Category, and a JoinQualification joining the Category with the PublicObject.
|
Note: For a detailed description of using Categories in your application, consult Chapter 6, "Applying Arbitrary Metadata and Behavior". |
Table 3-15 lists the most commonly used attributes and methods on Category.
Table 3-16 lists the most commonly used methods on PublicObject when working with Categories.
|
|
Applies new Category instances to an instance of PublicObject. |
|
getCategories() |
Retrieves one or all of the Category instances applied to the PublicObject. |
Every instance of PublicObject can possess a PropertyBundle. PropertyBundles are used to store ad-hoc metadata about a PublicObject instance in the form of name/value pairs, like a hash table. For example, you might store a list of translated values for a Document's Name attribute as {english/Guide, spanish/Guida}. The PublicObject instance possesses an attribute named PropertyBundle which references the PropertyBundle instance that contains the metadata.
As illustrated in Figure 3-5, "PropertyBundle Object Model", each name/value pair in the PropertyBundle is represented as an instance of the Property class. The Property instance references the PropertyBundle to which it belongs via an attribute named Bundle. The value of the Property may be of any datatype managed by Oracle 9iFS, including scalar datatypes, object datatypes, and arrays of scalar and object datatypes.
You can search for PublicObjects based on metadata contained in its PropertyBundle by creating a Search that includes PropertyQualifications which specify the criteria about the Properties on the PublicObject.
For a detailed description of using PropertyBundles in your application, consult Chapter 6, "Applying Arbitrary Metadata and Behavior".
Table 3-17 lists the most commonly used attributes and methods on PublicObject when working with PropertyBundles.
Table 3-18 lists the most commonly used methods on PropertyBundle.
Table 3-19 lists the most commonly used attributes and methods on Property.
Every instance of PublicObject also possesses a PolicyPropertyBundle. PolicyPropertyBundles are used to store a set of policies for how the PublicObject should be handled when certain operations are called.
As illustrated in Figure 3-6, "PolicyPropertyBundle Object Model", the PublicObject references its PolicyPropertyBundle via an attribute named PolicyBundle. Each policy in the PolicyPropertyBundle is represented as an instance of the Policy class. The Policy possesses attributes for the operation to which the policy applies, the fully qualified name of the Java bean that implements the behavior of the policy, and an enumerated key to identify the policy. The Policy is stored as the value of a Property in the PolicyPropertyBundle. The Property instance references the PolicyPropertyBundle to which it belongs via an attribute named Bundle.
For example, Oracle 9iFS uses PolicyPropertyBundles to implement the behavior of renderers. Renderers are used to convert the data for different content types into various formats and layouts. Each renderer is registered with an instance of the Policy class. The Operation attribute on the Policy identifies the operation that will be called by the application to render the information. The ImplementationName attribute on the Policy specifies a renderer's Java class. In the case of renderers, the ImplementationNum attribute is not used. Multiple renderers are associated with a content type by bundling the Policies in a PolicyPropertyBundle.
When Oracle 9iFS performs an operation on an instance of the content type, it first checks the PolicyPropertyBundle to determine if there is a policy for handling that operation. For example, when the FTP client renders a document's content, the Oracle 9iFS server first checks the PolicyPropertyBundle on Document for any Policy for the operation FtpRenderer. The PolicyPropertyBundle contains a Policy for this operation whose ImplementName attribute specifies the path of the ContentRenderer, oracle.ifs.server.renderers.ContentRenderer, which is used to render the Document content in a way that can be viewed in a FTP client.
For a detailed description of using PolicyPropertyBundles in your application, consult Chapter 6, "Applying Arbitrary Metadata and Behavior".
Table 3-20 lists the most commonly used attributes and methods on PublicObject when working with PropertyBundles.
Table 3-21 lists the most commonly used methods on PropertyBundle.
Table 3-22 lists the most commonly used methods on Property.
Table 3-23 lists the most commonly used methods on Policy.
Oracle 9iFS provides another class, Relationship, for associating PublicObjects with one another. As illustrated in Figure 3-7, "Relationship Object Model", Relationship possesses two attributes, RightObject and LeftObject, which reference the PublicObject on each side of a relationship.
Modelling associations between PublicObjects with an intermediary Relationship is ideal for managing many-to-many relationships. Relationship provides an efficient way to retrieve PublicObjects on either side of a relationship. You can use Relationship to retrieve all PublicObjects that reference a specific PublicObject as the RightObject, or retrieve all PublicObjects that reference a specific PublicObject as the LeftObject. In either case, the query is optimized by a unique key index on the RightObject and LeftObject attributes.
Relationship provides basic methods, getRightObject() and getLeftObject(), for retrieving the PublicObject from each side of a specific relationship. PublicObject also provides convenience methods for quickly retrieving all of a PublicObject's relationships and related PublicObjects. For example, the getLeftwardRelationshipObjects() method retrieves all PublicObjects related to it as the LeftObject. Relationships also provide a powerful way for administrators to search for information based on the attributes and/or content of related information. For example, administrators can search for all folders that contain a document owned by Joe Smith. The search application would construct a Search that includes SearchQualifications pertaining to the related PublicObjects and a JoinQualification that joins the related PublicObjects with Relationship.
Search, SearchQualification and JoinQualification are all covered in depth in Chapter 8, "Building Search Applications".
Relationships also allow you to store extra attributes and behaviors for PublicObjects that are only applicable within the context of their relationship. You can extend the Relationship class to create custom types of relationships that possess additional attributes and behaviors. For example, the FolderPathRelationship class extends Relationship to implement logic that ensures that items within the same folder have unique names. You can create custom Relationship classes for managing associations between letters and their attachments, research documents and their reference materials, word processing documents and their HTML, PDF and XML renditions, or compound documents and their components.
For a detailed description of using Relationships in your application, consult Chapter 6, "Applying Arbitrary Metadata and Behavior".
Table 3-24 lists the most commonly used attributes and methods on Relationship.
Table 3-25 lists the methods on PublicObject when working with Relationships.
Oracle 9iFS provides a set of classes for versioning PublicObjects. Versioning is a way to keep track of all changes made to a PublicObject throughout its lifecycle. For example, an organization may need to track all changes made to a document's content and/or attributes by recording who made the change, when, and in what sequence. The organization may keep backups of each "version" of the document as a record of what the document looked like at a particular point in time.
Oracle 9iFS provides a flexible versioning model capable of supporting a wide variety of processes for authoring and publishing information. With Oracle 9iFS, any PublicObject can be versioned. If you plan to version other classes of objects, it is important to take into account the disk space and performance cost involved. For example, to version folders, you can store a separate instance of Folder for each modification made to the folder's attributes. You can also track the items contained by each version of the folder by creating separate instances of FolderPathRelationship that reference the specific version of the folder as the LeftObject. However, you should consider the amount of additional disk space it will require to store the data for the separate instances of Folder and FolderPathRelationship in the database. In addition, you should consider how the additional instances will impact your application's performance when searching for folders or items contained in a folder.
Versioning is discussed at length in Chapter 14, "Implementing Versioning in a Custom Application".
As illustrated in Figure 3-8, "Versioning Object Model", Oracle 9iFS uses three classes to version PublicObjects: Family, VersionSeries, and VersionDescription.
The Oracle 9iFS clients and protocols implement a serial versioning model for documents only. In a serial versioning model, the document's Family only includes one VersionSeries that contains all of the document's versions. Each version must, therefore, be made sequentially, one after another.
The Oracle 9iFS versioning model is capable of supporting custom applications with more complex versioning paradigms, such as parallel or branched versioning.
Instances of most PublicObjects can be versioned. The PublicObject's Family can contain multiple VersionSeries to represent separate sequences of changes that may have been made in parallel, and which may branch from and merge into one another.
Different VersionDescriptions in a VersionSeries may reference different classes of objects, thus representing changes in the state of a PublicObject from one class to another. For example, the first version may have been a instance of Folder that contains a set of FrameMaker files comprising a book. For the second version, the FrameMaker book may be converted to a PDF file which is stored as an instance of Document.
VersionDescriptions can also reference the same instance of PublicObject. For example, a document may have a "work-in-progress" VersionSeries and a "published" VersionSeries. The third version of the "work-in-progress" VersionSeries may represent the first version in the "published" VersionSeries. In this case, the VersionDescriptions representing the third "work-in-progress" version and first "published" version can reference the same instance of Document.
Table 3-26 lists the most commonly used attributes and methods on Family.
Table 3-27 lists the most commonly used attributes and methods on VersionSeries.
Table 3-28 lists the most commonly used attributes and methods of VersionDescription.
|
|
Tracks the version series to which this version belongs, the sequence number assigned to the version within the version series, and any comments supplied by the user when creating the version. |
|
setVersionLabel() |
The VersionLabel attribute stores a custom label for the version in the version series. A versioning application can store a version label which complies with an organization's revision numbering scheme.Foot 1 |
|
isLatestVersionDescription() |
Determines if the version is the last version in the version series. |
|
getPublicObject() |
Each version is ultimately stored as an instance of PublicObject. The PublicObject attribute on the VersionDescription references the PublicObject instance which constitutes that version. The getPublicObject() method is used to obtain the PublicObject. |
|
1
For example, while Oracle 9iFS automatically numbers the versions with sequential integers (1, 2, 3), the organization may wish to label the versions (Draft A, Draft B, Draft C, Release 1.0). |
Illustrated in Figure 3-9, "ACL Object Model", Oracle 9iFS primarily uses three classes to control access to information: AccessControlList, ClassAccessControlList, and SystemAccessControlList. These classes descend from PublicObject. Therefore, they are the primary interface for end users to control access to information. They are supported by four other classes: AccessControlEntry, AccessLevel, PermissionBundle, and ExtendedPermission.
Security is discussed in detail in Chapter 15, "Security".
AccessControlList represents a list of users and groups who have been granted specific permissions to information in the repository. An instance of AccessControlList can be applied to one or more documents, folders, or any PublicObject. In this manner, the AccessControlList serves as a central place for defining and applying security for information in the repository.
Every instance of PublicObject possesses an attribute, ACL, that is used to assign an AccessControlList to the instance. Before allowing a user to perform an action on the PublicObject instance, Oracle 9iFS first checks the AccessControlList referenced by the ACL attribute to determine if the user has been granted permission to perform that action.
Since AccessControlList descends from PublicObject, it also possesses an ACL attribute. This attribute is used to govern which users and groups can grant and revoke permissions in the AccessControlList, and delete the AccessControlList.
Table 3-29 lists the most commonly used attributes and methods on AccessControlList.
AccessControlEntry is used to represent each set of permissions granted to a user or group in the AccessControlList. AccessControlEntry possesses attributes and methods for determining the user or group, the permissions, and whether the permissions are being granted or revoked. Each instance of AccessControlEntry references the AccessControlList to which it belongs via an attribute ACL.
Table 3-30 lists the most commonly used attributes and methods on AccessControlEntry.
Each permission that can be granted or revoked on information in the repository is represented with the AccessLevel class. AccessLevel possesses a set of constants that are used to designate different permissions, including the permission to discover that the information exists, create instances of a class, set attributes and/or content, and delete information. AccessLevel provides an extensive list of permissions which give you fine control over how information is accessed. The following permissions are represented by constants on the AccessLevel class:
Table 3-31 lists the most commonly used constants and methods on AccessLevel.
ExtendedPermission defines custom access permissions. For example, you may define an custom permission for the ability to digitally sign a document to support an application for managing legal contracts. To define the custom permission, you would create an instance of the ExtendedPermission class that is uniquely named (e.g., 'Sign') to identify the custom permission.
Subsequently, you can grant and revoke the ExtendedPermission in an AccessControlEntry using AccessLevels. You can construct an AccessLevel to hold the ExtendePermissions as easily as standard permissions. The AccessLevel class in the Java API provides a set of methods for working with ExtendedPermissions. The AccessLevel can then be granted or revoked to a user in an AccessControlEntry of an AccessControlList.
Table 3-32 lists the methods on AccessLevel that are used to work with ExtendedPermissions.
After an ExtendedPermission has been applied to an AccessControlList, you can create custom applications which use the ExtendedPermission to control how users can work with PublicObjects. Your application would implement an override to check if a user has been granted the ExtendedPermission on a PublicObject, and then allow or disallow the user to perform operations based on its findings.
Table 3-33 lists the methods on S_PublicObject that are used to work with ExtendedPermissions.
To manage access more broadly than the permissions defined by AccessLevel, you can use PermissionBundle to group AccessLevels. PermissionBundles are stored persistently in Oracle 9iFS, and can be used to represent higher-level security settings which may be granted to users. For example, you might group the Discover, Add Item, and Remove Item permissions together into a Modify Folder Permission Bundle to more easily grant users the ability to modify folders.
Table 3-34 lists the most commonly used attributes and methods of PermissionBundle.
|
|
Determines the AccessLevels in the PermissionBundle. |
ClassAccessControlList extends AccessControlList. Therefore, it also employs AccessControlEntries, AccessLevels, ExtendedPermissions, and PermissionBundles. ClassAccessControlLists are specialized to manage how users can work with a content type. Administrators use ClassAccessControlLists to control which users and/or groups can instantiate and delete a content type. ClassAccessControlLists have an extended UniqueName attribute to ensure that they are uniquely named in Oracle 9iFS.
SystemAccessControlList also extends AccessControlList.
SystemAccessControlLists are used to represent system-wide AccessControlLists that have a UniqueName attribute. They can only be created by administrative users. Oracle 9iFS includes four instances of SystemAccessControlList on installation:
SystemAccessControlLists have an extended UniqueName attribute to ensure that they are uniquely named in Oracle 9iFS.
Illustrated in Figure 3-10, "Directory Object Model", Oracle 9iFS provides a set of classes for managing information about users and groups. DirectoryUser and DirectoryGroup, which descend from PublicObject, serve as the primary interfaces for representing users and groups who work with information in the Oracle 9iFS repository. These classes are supported by a few SystemObject classes that are used to represent each user's preferences for working in the repository, and how users are related to groups.
For information on managing directories in your application, consult Chapter 15, "Security".
Each user that can log into Oracle 9iFS is represented by an instance of the DirectoryUser class.
DirectoryUser possesses attributes and methods for managing the user, including assigning the user administrative privileges, uniquely naming the user, and specifying the credential manager that is used to authenticate the user.
Table 3-35 lists the most commonly used attributes and methods on DirectoryUser.
Oracle 9iFS provides a set of SystemObject classes for managing a user's preferences for working in the Oracle 9iFSrepository.
Table 3-36 lists the most commonly used attributes and methods on PrimaryUserProfile.
Table 3-37 lists the most commonly used attributes and methods on ExtendedUserProfile.
Table 3-38 lists the most commonly used attributes and methods on ContentQuota.
Users can be organized into groups. A group can contain any number of users. Groups can also contain other groups. In this manner, groups can be arranged into inclusive hierarchies.
Groups can be created to represent users who have something in common. For example, you can create groups for the various roles that users may have (e.g. Manager, Developer, Writer). You can also create groups to represent different companies divisions or projects (e.g., Marketing, Sales, Development).
Groups are useful for consistently granting access to information across a number of users. For example, you can grant all managers read access to documents in the repository by creating an AccessControList that designates the Manager group as the Grantee of an AccessControlEntry.
Groups are represented in Oracle 9iFS by two classes, DirectoryGroup and GroupMemberRelationship. DirectoryGroup descends from PublicObject and, therefore, acts as the primary interface for managing group membership. GroupMemberRelationship, which descends from SystemObject, represents the relationship between a user and a group. An instance of GroupMemberRelationship is created to represent each user's or group's membership.
You can extend DirectoryGroup to classify groups and to add extra attributes and behaviors that are special for those types of groups. For example, you can create a Division group that extends DirectoryGroup to include the attributes Vice President and Mission Statement. You can also extend GroupMemberRelationship to manage extra metadata about each user's membership in the Division group, like Team Role.
Table 3-39 lists the most commonly used attributes and methods on DirectoryGroup.
Table 3-40 lists the most commonly used attributes and methods on GroupMemberRelationship.
|
|
The LeftObject attribute references the DirectoryGroup. |
|
getRightObject() |
The RightObject attribute references a user or group who belongs to the DirectoryGroup. |
Oracle 9iFS uses another set of classes to maintain a registry of all content types that it manages. These classes descend from the SchemaObject class in the oracle.ifs.beans package. The function of the classes is to record metadata about each content type, like the content type's attributes, the Java classes that implement the content type's behavior, and how instances of the content type are stored in the database.
Illustrated in Figure 3-11, "SchemaObject Model", the classes used to create this registry include ClassObject, Attribute, AttributeDefault, AttributeDomain, ClassDomain.
Each content type in Oracle 9iFS is represented by an instance of the ClassObject class. Each of the content type's attributes are represented by instances of the Attribute class. The ValueDefault, ValueDomain and ClassDomain classes are used to define constraints on content type attributes.
ClassObject possesses attributes and behaviors for registering content types in Oracle 9iFS. The ClassObject records the name and description of the content type, the table in which instances of the content type will be stored, and the Java classes that are used to implement the behavior of the content type.
Table 3-41 lists the most commonly used attributes and methods on ClassObject.
Attribute possesses attributes and methods for registering content type attributes. Attribute records metadata like the attribute's name, datatype, scale and length. It also records the name of the column which is used to store the values of the attribute.
Table 3-42 lists the most commonly used attributes and methods on Attribute.
|
|
Determines the name of the attribute (e.g., 'Owner', 'CreateDate'). Once an Attribute instance is created to represent an attribute for a content type, its Name cannot be changed. |
|
getDatabaseObjectName() |
Determines the column in the database that is used to store instances of the content type. The column will be located in the table specified for the attribute's ClassObject. Once a Attribute instance is created to represent a content type, the DatabaseObjectName cannot be changed. |
|
getDefiningClass() |
Determines the ClassObject for the content type to which the attribute belongs (e.g., 'Document', 'Folder'). |
|
getDataScale() |
Determines the attribute's datatype, length and scale. The attribute can be a scalar datatype, such as Integer, String, and Date, an Oracle 9iFS object datatype, like PublicObject, SystemObject, and DirectoryObject, or an array of those types. |
|
isUpdatable() |
Places constraints on the attribute's value. The ValueDefault, ValueDomain and ClassDomain constraints are discussed in these sections: "ValueDefault", ."ValueDomain", and "ClassDomain". |
|
setReferentialIntegrityRule() |
Determines the referential integrity rule that will be imposed if the attribute's value references an object. The RIRULE_CLEAR constant is used to indicate that the attribute's value should be set to NULL if the referenced object is deleted. The RIRULE_RESTRICT constant is used to indicate that Oracle 9iFS should prevent an object from being deleted while it is referenced by this attribute. |
The value of an attribute may be defaulted automatically when an instance of the content type is created. Defaulting the attribute's value makes it easier for end users to create new instances, without having to manually enter the value of every attribute. If the attribute is usually going to be set to a certain value, then that value can be automatically set by Oracle 9iFS.
Default values are represented as instances of ValueDefault. ValueDefaults provide a generic way to set the default value for an Attribute when the value may be of any datatype. ValueDefaults hold the value in a PropertyBundle. ValueDefaults possess attributeOracle 9iFSs and methods for uniquely identifying and retrieving default values in the Oracle 9iFS system.
Table 3-43 lists the most commonly used attributes and methods on ValueDefault.
The value of an attribute may be restricted to a domain of enumerated values, or a domain range of values. A domain range may require that the value be less than, less than or equal, greater than, greater than or equal, between, and between or equal to specified boundaries. Constraining attribute values to a domain helps to ensure that end users enter a valid value. For example, the value for a PublicationDate attribute may be restricted to be after the year 2000. The value of a Publisher attribute may be restricted to one of the following {'ACME Publishing', 'GreenTree Publishing', 'Atlantis Publishing'}.
The domain being imposed on an attribute's value is registered in Oracle 9iFS as an instance of ValueDomain. The domain range or enumerated values are held in a PropertyBundle. A set of constants on the ValueDomain are used to indicate the type of domain being applied to the value.
Table 3-44 lists the most commonly used attributes and methods on ValueDomain.
If an attribute value references an object (e.g., PublicObject, System Object, SchemaObject, DirectoryObject) or an array of objects, the value can be restricted to one or more content types. For example, if the attribute has the datatype PublicObject, you can require that the values are instances of Document. You can also specify whether or not the values can be instances of a subclass of Document.
This type of constraint is registered in Oracle 9iFS as an instance of ClassDomain. ClassDomains give you more control over managing how objects are related to one another via attributes. This is particularly useful when building compound document management applications. For example, you may create a content type, PurchaseOrder, that possesses an attribute, Ordered_Products, that must references instances of a Product content type. You could specify that the Ordered_Products attribute has a datatype of PublicObject, and has a ClassDomain of Product.
Table 3-45 lists the most commonly used attributes and methods on ClassDomain.
As discussed in "Managing Information", every content type managed by Oracle 9iFS consists of a set of tables for storing the data, and a set of Java classes for implementing the behavior of the content type. Each content type can possess three Java classes:
oracle.ifs.server package. The naming convention of the server-side Java classes, S_<classname>, draws a parallel to the beans-side class.
When you create a new content type, it automatically possesses the behavior of the content type that it extends. For example, if you create a new content type, SimpleImage, that extends Document, it possesses the behavior implemented with the oracle.ifs.beans.Document class and oracle.ifs.server.S_Document class. It is only necessary to create custom Java classes for the content type if you wish to customize its behavior.
Oracle 9iFS provides a set of classes, Tie classes, that provide a convenient interface for extending the Java classes to implement custom behavior. Every bean-side and server-side Java class has a corresponding Tie class. For example, the Document Java class has a corresponding TieDocument, and the S_Document has a corresponding S_TieDocument. The Tie classes extend its corresponding the bean-side or server-side Java class.
When you wish to extend the behavior of a content type, you create a custom Java classes that extend or replace the Tie classes. Since the Tie classes extend the bean-side and server-side Java classes, your custom Java classes inherit the behavior implemented by the Oracle 9iFS classes.
Oracle 9iFS provides another set of classes, Definition classes, that are used to create instances of content types.
Each content type managed by Oracle 9iFS possesses a Definition class. The naming convention for the Definition classes, <classname>Definition, draws a parallel to the bean-side Java class for the content type. All Definition classes are located in the oracle.ifs.beans package, and extend the top-level class LibraryObjectDefinition.
Definition classes are used to assemble a structure that temporarily holds the information data. The structure is then used to instantiate a bean-side Java class and store the information persistently in the repository.
Definition classes give custom applications greater flexibility when creating several instances that are similar. For example, if you need to create multiple Documents that have the same Owner and Format, you can create a Definition to hold the Owner and Format values, then use it as a template to create each Document.
Definitions also make it easier to instantiate complex content types. When creating content types comprised of multiple components, you can create Definitions for each component and then instantiate the content type in a single call. For example, a versioned document is comprised of four components: a Document, VersionDescription, VersionSeries, and Family. You can create Definitions of each of these components, and then create all four persistent objects with a single call to the Oracle 9iFS API.
The Oracle 9iFS Java API provides a set of Java classes to search and retrieve information of any type of information in the repository. These classes allow you to specify criteria about the information you want to retrieve, including:
For more information about Oracle Text, consult the Oracle 9iFS Setup and Administration Guide.
Oracle 9iFS provides two interfaces for searching the repository and working with search results.
Selectors provide a convenient way to execute simple queries in the repository. If you need to search against a single class of information with static criteria about its attributes, you can create an instance of the Selector class to construct and execute the query.
select all Documents whose Owner is 'user1' and whose Name ends with '.html'
Illustrated in Figure 3-12, "Selector Object Model", Selectors are constructed from three components: a string specifying the class, a string specifying the search criteria, and a SortSpecification object that specifies the sort criteria.
Selectors operate under the following rules:
Table 3-46 lists the most commonly used attributes and methods of the Selector class.
The Oracle 9iFS Java API also provides a SortSpecification class to construct the sort criteria for the Selector. The SortSpecification is set on the Selector with the setSortSpecification() method.
Table 3-47 lists the most commonly used attributes and methods of the SortSpecification class.
The Search interface provides a more robust interface for constructing and executing complex queries in the repository. Searches can query against multiple classes of information based on dynamic criteria about their attributes, content, folders, other inter-relationships, and ad-hoc information.
"find all Documents and Folders which are in my Home Folder, whose ModifiedDate is less than <VariableDate>, and whose Name contains 'XML' or whose Content contains 'XML' "
The Search interface enables you to assemble complex queries in an object-oriented manner using Java constructs. Figure 3-13, "Search Object Model" illustrates how each component of the SQL select statement for your query against the repository can be expressed as a Java object, including the FROM clause, the WHERE clause, each EXPRESSION in the WHERE clause, and the ORDER BY clause. These various components can then be assembled dynamically into a Java construct, or specification, which is then passed to a Search object that is used to execute the query. When Oracle 9iFS executes the query, it automatically generates the SQL select statement and runs the query against the repository. Subsequently, Oracle 9iFS returns the results of the query as an array of information objects which you can read and manipulate.
Table 3-48 illustrates how the components of a SearchSpecification map to the components of a SQL query.
Table 3-48 SQL to Java comparison
In this manner, the Oracle 9iFS Search interface enables you to programmatically assemble complex queries in an object-oriented manner. Using a Java structure to define your query gives you the flexibility to manipulate each component, dynamically modify the query, and run it multiple times against the repository. It also frees you from having to know the complexities of the Oracle 9iFS underlying schema.
The Oracle 9iFS Search interface provides a set of Java classes to construct the various components of a search, execute the query, and then work with the search results.
To execute a Search in Oracle 9iFS, first construct a SearchSpecification. A SearchSpecification temporarily holds all of the components of the Search until you execute the query.
As illustrated in Figure 3-14, "SearchSpecification Components", SearchSpecifications are constructed from three components:
There are two types of SearchSpecifications, AttributeSearchSpecification and ContextSearchSpecification. When assembling a Search, construct an AttributeSearchSpecification or a ContextSearchSpecification, depending on the search criteria.
is used when constructing a Search which does not specify criteria based on the content of documents.
Oracle 9iFS automatically optimizes the search in accordance with the nature of its criteria. The same Search (e.g., Documents whose Owner = "user1") performs better if constructed with an AttributeSearchSpecification than if constructed with a ContextSearchSpecification.
Table 3-49 lists the most commonly used methods of the AttributeSearchSpecification class.
is used when constructing a Search that contains content criteria (e.g., select Documents whose Content contains 'XML'). The SearchQualification component of a ContextSearchSpecification should have at least one ContextQualification.
When Oracle 9iFS executes a Search based on a ContextSearchSpecification, it automatically includes the tables that store document content in the repository, and construct the corresponding contains() clauses in the SQL statement.
Since ContextSearchSpecification extends AttributeSearchSpecification, it possesses the same methods defined in Table 3-49.
Table 3-50 lists the additional methods provided with the ContextSearchSpecification class.
SearchClassSpecification constructs the 'FROM' clause in the SQL select statement. However, since Oracle 9iFS works with information in an object-oriented manner, the SelectClassSpecification object specifies a list of classes that should be queried rather than a list of tables as it would in SQL.
Oracle 9iFS returns a list of information objects as the results of a search, not an array of the attributes of these objects. Each information object must be an instance of a class specified in the SearchClassSpecification. Your application can then access all data comprising each information object (e.g., attributes, content), or perform operations on each object (e.g., check-in, check-out). For these reasons, it is not necessary to specify a select list as you would in a SQL select statement. The select list for an Oracle 9iFS search is always 'SELECT *'.
Table 3-51 lists the most commonly used methods of the SearchClassSpecification class.
SearchQualification is an abstract class for holding the criteria of the search. It is used by Oracle 9iFS to construct the 'WHERE' clause in the SQL select statement.
A SearchQualification can specify criteria based on various conditions, like owner = 'user1' and contains ('XML'). The criteria is defined in the SearchQualification by assembling a group of objects that represent the conditions.
As illustrated in Figure 3-15, "SearchQualification Assembly", the 'WHERE' clause is constructed by nesting multiple instances of the SearchQualification's subclasses.
The AttributeQualification represents a condition about the value of an attribute. Attribute can be of any datatype supported by Oracle 9iFS.
"find all documents where the owner is jdoe"
Table 3-52 lists the most commonly used constants and methods of the AttributeQualification class.
The FolderRestrictQualification represents a condition that the search should be limited to a specified folder or folder branch.
"find all documents in my home folder"
Table 3-53 lists the most commonly used methods of the FolderRestrictQualification class.
The ContextQualification represents a condition about the content of a document.
"find all documents containing the word 'XML' "
Table 3-54 lists the most commonly used constants and methods of the ContextQualification class.
|
|
Determines the Name of the ContextQualification. The name can be used to include the relevancy score generated by Oracle Text as sort criteria. |
|
|
Used when including the relevancy score generated by Oracle Text in SearchSortSpecification. The constant is prefixed to the Name of the ContextQualification, and is used by Oracle 9iFS to generate the correct SQL syntax in the ORDER BY clause. |
|
setQuery() |
These methods are used to determine the text query string that is passed to Oracle Text as the criteria for the content search. The query string is passed by Oracle 9iFS, unmodified, into the text string argument of the CONTAINS() SQL function which calls Oracle Text to execute a content query. Since it is not modified by Oracle 9iFS, the query string may include any number of tokens, expansion operators and join operators in accordance with the syntax required by Oracle Text. Foot 1 |
|
1
For more information about syntax rules for text query strings against Oracle Text, consult the Oracle SQL Reference Manual. |
The ExistenceQualification represents a condition that an attribute's value matches one of a list of possible values, or that an attribute's value matches the value of an attribute of another object.
"find all reports where the report number is one of the following: 3a, 3b, 6a" "find all documents where the name of a document matches the name of a folder"
Table 3-55 lists the most commonly used methods of the ExistenceQualification class.
The PropertyQualification represents a condition about a property in the information's PropertyBundle.
" find all documents where the italian_title_translation property = 'Vino di Italia' "
Metadata about information in Oracle 9iFS can not only be stored as attributes, but can also be stored in a PropertyBundle. A PropertyBundle bundles together several Properties, each comprised of a name/value pair. PropertyBundles are used to store ad-hoc metadata that is easiest to work with like a hash table.
Table 3-56 lists the most commonly used methods of the PropertyQualification class.
The FreeFormQualification allows you to include any other types of conditions via a free-form string of SQL syntax. The SQL syntax specified with a FreeFormQualification is inserted unparsed into the SQL select statement generated by Oracle 9iFS from the SearchSpecification.
Table 3-57 lists the most commonly used methods of the FreeFormQualification class.
|
|
Determines the String that contains the SQL expression |
When specifying multiple conditions for the search criteria, you can control how they are combined using JoinQualifications and SearchClauses. JoinQualification is used to construct a join when including conditions about related object information.
"find all documents where owner's name is 'wtalman' "
This search requires that the document's metadata be joined with metadata about the document's owner. In SQL this might be expressed as:
SELECT * FROM Document d, DirectoryUser u WHERE d.owner = u.id AND u.name = 'wtalman'
In this case, you can specify how document information will be joined with user information (e.g., d.owner = u.id) with a JoinQualification. Then you would create an AttributeQualification to specify the condition pertaining to the user metadata (e.g. u.name = 'wtalman').
Table 3-58 lists the most commonly used methods of the JoinQualification class.
|
|
Determines the left-hand side and right-hand side of the join condition. |
|
|
Retrieves the class for an either Attribute specified in the join condition. |
The SearchClause represents clauses in a SQL WHERE statement that combine conditions into more complex criteria using operators.
For more information on operators and precedence, refer to the Oracle SQL Reference Manual.
SearchClauses are used to combine two conditions into Boolean criteria with the operators AND and OR.
"find all documents where name = 'User Guide' AND modification_date > 'January 01, 2001' "
After creating two AttributeQualifications to represent the conditions for the owner and modification date attributes, a SearchClause is created to assemble the two AttributeQualifications along with the operator used to combine them.
SearchClauses are also used to specify negative criteria about a single condition with the operator NOT.
"find all documents which are NOT in my home folder "
After creating the FolderRestrictQualification for my home folder, a SearchClause is created to precede the condition with a NOT operator.
SearchClauses are used to combine three or more conditions by nesting SearchClauses within SearchClauses.
"find all documents where name = 'User Guide' OR description = 'User Guide' AND modification_date > 'January 01, 2001'
After creating three AttributeQualifications to represent each condition, a SearchClause is used to combine two AttributeQualifications. A second SearchClause is used to combine the third AttributeQualification with the first SearchClause. In this manner, SearchClauses are used to assemble all conditions (AttributeQualifications, FolderRestrictQualifications, etc.) in the SearchQualification.
Table 3-59 lists the most commonly used constants and methods of the SearchClause class.
SearchSortQualification specifies the sort order for the search results. It is used by Oracle 9iFS to construct the 'ORDER BY' clause in the SQL select statement.
Table 3-60 lists the most commonly used constants and methods of the SearchSortQualification class.
The Oracle 9iFS search object model provides another type of object, Search, to execute the query. Once the SearchSpecification is assembled, it is used to create a new Search. The Search is then used to:
When the Search is executed, Oracle 9iFS constructs a SQL select statement, thereby handling the complexities of querying against the database schema. This allows you to construct searches for information in an object-oriented manner, without having to know how the information is stored across various tables in the database. To explicitly specify a portion of the SQL select statement, you can use the FreeFormQualification object.
Table 3-61 lists the most commonly used methods of the Search class.
When a Search is executed, Oracle 9iFS returns an array of result hits for each piece of information which met the search criteria. The result hits are sorted in the array according to the sort criteria specified in the SearchSpecification. Each result hit is represented in the array by a SearchResultObject.
The SearchResultObject can be used to retrieve the actual information object that incurred the result hit. The information object is represented as a LibraryObject. LibraryObject is used to represent any piece of information stored in the repository. The LibraryObjects returned must have one of the content types specified in the SearchClassQualification. Each LibraryObject consists of any attributes and content pertaining to the information's content type.
By retrieving the LibraryObject from the SearchResultObject, a search application can display and manipulate any of the information's attributes and content without having to make a second call to retrieve the information from the repository. However, if the search application needs to display or manipulate related information (e.g., the attributes of a parent folder), then the application will need to perform a second operation to retrieve the related information from the repository.
Table 3-62 lists the most commonly used methods of the SearchResultObject class.
|
|
Returns the LibraryObject that incurred the search result hit, a.k.a. SearchResultObject. |
Oracle 9iFS provides three packages of classes for automating server-side processing of information in the repository:
The oracle.ifs.beans.parsers package provides a set of interfaces for building parsers that pre-process information being imported into Oracle 9iFS. It also includes a set of classes that implement the interfaces to provide parsing functionality. You can build custom parsers by implementing the interfaces or extending the classes in this package.
For example, the IfsSimpleXmlParser class constitutes the parser included with Oracle 9iFS for parsing XML files. The IfsSimpleXmlParser receives the input stream for the XML file, parses it to generate a DOM tree of its components, and then creates an instance of the content type that corresponds to the XML file's schema.
For instructions on implementing parsers, see Chapter 9, "Creating a Custom Parser".
The converse of parsers, the oracle.ifs.server.renderers package provides interfaces and classes for pre-processing information being exported from Oracle 9iFS. You implement its interfaces, or extend its classes to build custom renderers.
For example, the SimpleXmlRenderer class implements the Renderer interface to provide XML rendering functionality with Oracle 9iFS. The SimpleXmlRenderer receives an instance of a content type and converts it into an XML file.
For instructions on implementing renderers, see Chapter 11, "Creating a Custom Renderer".
The oracle.ifs.management.domain package provides a set of interfaces and classes to build servers. Servers automate tasks which are performed in Oracle 9iFS. Servers may initiate these tasks at certain times of day, or when certain events occur in Oracle 9iFS.
The abstract class IfsServer in this package serves as the base class for all servers for Oracle Oracle 9iFS. Since the IfsServer class implements the Server interface, any server extending this class can be managed with Oracle 9iFS Server Manager.
For instructions on implementing servers, see Chapter 13, "Creating Custom Servers".
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|