Oracle Internet File System Developer's Guide Release 1.1 A75172-04 |
|
This chapter covers the following topics:
The Oracle Internet File System Java API provides classes and methods that allow you to customize all of the functionality included in the out-of-the-box Oracle iFS interfaces. These classes include:
Because the functionality is extensive, the API includes a large number of classes, which are organized into packages for ease of use. Because the large number of classes means that the Javadoc is extensive, this chapter provides a quick introduction to a few of the most frequently used Oracle iFS classes.
A good way to begin the process of familiarization with Oracle iFS would be to:
The classes of the Oracle iFS API are organized into 25 packages. You can see this complete structure by going to the Oracle iFS Javadoc and clicking on the link labelled "Overview." Of these 25 packages, seven contain the classes that are most frequently used for developing Oracle iFS custom applications. The following table describes the types of classes included in each of these seven packages.
The LibraryObject class forms the highest level of the class hierarchy of the oracle.ifs.beans
package. All classes that represent persistent objects in oracle.ifs.beans
inherit from LibraryObject, so LibraryObject is the base class for these objects, providing functionality common to all the classes. For example, the methods that provide the following functions are located in the LibraryObject class:
LibraryObject has three subclasses, which are abstract superclasses for the objects below them in the hierarchy:
The following table describes the purpose of the three LibraryObject subclasses.
To create any Oracle iFS object is a two-stage process:
All Definition classes inherit from LibraryObjectDefinition and PublicObjectDefinition, as shown in the following class hierarchy:
java.lang.Object +--oracle.ifs.beans.LibraryObjectDefinition +--oracle.ifs.beans.PublicObjectDefinition +--oracle.ifs.beans.DocumentDefinition
You can use the classes of the oracle.ifs.beans
package as-is, if they meet your requirements. You can also subclass these classes to create custom classes. Deciding which class you want to subclass is a key decision, because it determines the functionality your custom class inherits. To make that decision, you need to become familiar with:
oracle.ifs.beans
package, which contains the most frequently used classes.
Most of the application development work you do will use the classes that make up the three subclasses of LibraryObject. Before you begin working with these classes, you may find it useful to review this abbreviated class hierarchy, which includes the three LibraryObject subclasses:
To provide a starting point, several of the most commonly used classes are described later in this chapter. All of the classes are described in the Javadoc.
PublicObject AccessControlList SystemAccessControlList ClassAccessControlList ApplicationObject ContentQuota PropertyBundle PolicyPropertyBundle ValueDefaultPropertyBundle ValueDomainPropertyBundle ServerDetail ServerRequest ServerSubClass Category MountPoint DirectoryObject DirectoryGroup AdministrationGroup DirectoryUser Document MailDocument Family Folder Mailbox Message MailFolder SearchObject SelectorObject Template UserProfile PrimaryUserProfile ExtendedUserProfile EmailExtendedUserProfile VersionSeries VersionDescription SystemObject AccessControlEntry AuditEntry AuditRule ContentObject ExtendedPermission Format Media MediaFile MediaLob MediaBlob MediaReference PermissionBundle Policy Property Relationship BranchRelationship FolderRelationship FolderPathRelationship BodyPartPathRelationship GroupMemberRelationship NamedRelationship SchemaObject Attribute ClassDomain ClassObject ValueDomain ValueDefault
Three groups of special classes are closely related to corresponding PublicObject classes, so they are not included in this list:
This list of classes is also abbreviated to include only the more commonly used classes. For a complete Oracle iFS class hierarchy, see the Oracle Internet File System Class Reference, which provides a listing of the class hierarchy and describes the attributes of the Java classes. Access the Class Reference in the Documentation section of the Oracle iFS listing on OTN (Oracle Technology Network).
Of all the classes in the Oracle iFS API, PublicObject is the most significant. PublicObject is the abstract superclass for all user-related classes and thus defines the attributes and methods that are common to all of these classes. Oracle iFS maintains all of the attributes defined by PublicObject automatically. For example, Oracle iFS will ensure that each file has a Name attribute. For a list of these attributes, see"Public Object Attributes".
These attributes are important because you can use them, as-is, in your custom type definition files. That means that the names of these pre-defined attributes are Oracle iFS keywords, so you cannot use them for custom attributes. For example, Name and Description are PublicObject attributes, so if you need to define a custom class that has a similar attribute, you must call that attribute something other than Name or Description, such as ApproverName or DocumentDescription.
Because PublicObject is an abstract class, it is never directly instantiated. Rather, the user-related classes are subclasses of PublicObject. Two general types of user-related classes are subclassed from PublicObject:
Because the repository is based on a single inheritance tree, each class inherits attributes and methods from PublicObject. Thus, all classes that inherit from PublicObject share some common characteristics:
These subclasses inherit all the attributes of the PublicObject class, as well as a set of attributes specific to the subclass. For example, the Document class has two sets of attributes:
The following table lists the attributes of the PublicObject class. Use this list for two purposes:
*An intrinsic identifier, not a PublicObject attribute. Included in this list because this identifier name is also a reserved word, and may not be used for custom attributes.
Assuming that your goal as a developer is to create custom applications quickly, the first question to consider is, "Will a standard Oracle iFS document meet the needs of my application?"
The answer depends on whether the attributes of your document are adequately described in the list of standard attributes defined for the Oracle iFS Document class.
To decide whether your document is a "standard Oracle iFS document," consult the list of "Public Object Attributes". If your document can be defined using only these standard attributes:
If your document has custom attributes that need to be specifically defined, see Chapter 4, "Creating Custom Classes".
In special circumstances, you may need to create a custom subclass even though your application does not require defining any custom attributes. For example, if your application requires identifying all files of a certain type, such as Word files or HTML files, and then manipulating the file contents or attributes in specific way, you would need to define that type as a custom class.
Another way to quickly familiarize yourself with some of the key classes of the Oracle iFS Java API is to consider the key user-related classes by function. The following table lists the key classes that belong to each group and the purpose of the group. (This table includes some classes that are not described in this chapter. For more information about these classes, consult the Javadoc.)
To understand a given user-related class, consult the Javadoc for these three classes related to whichever class you choose:
PublicObject
class, because it is the abstract class from which all user-related classes inherit.
Document
class.
DocumentDefinition
class.
Four classes are used to work with folders, documents (files), and their contents:
If your application deals with a document (file), you will need to create three objects:
In addition, if you want to place the file in a folder, you will need to create a Folder object.
Package Name: oracle.ifs.beans
Class Name: Document
ParentClass: PublicObject
Purpose: Adds the ability to store and manage the content of a file.
Methods: The Document class provides a number of methods specific to getting and setting the associated ContentObject.
Uses: Use the Document class to store a document or file.
Attributes: The following attributes are unique to the Document class:
Package Name: oracle.ifs.beans
Class Name: DocumentDefinition
ParentClass: PublicObjectDefinition
Purpose: The DocumentDefinition class is used to construct a Document object. This subclass of PublicObjectDefinition sets the default ClassObject to "DOCUMENT". An instance of a DocumentDefinition is passed to LibrarySession.createDocument() to actually construct the new document.
Methods: The DocumentDefinition class provides a number of methods specific to storing and manipulating content.
Uses: Use the DocumentDefinition class to create a transient, in-memory object to hold the attributes of a Document object while you are creating it. Once the Document Definition is passed to the createDocument() method, the definition object is discarded.
Attributes: The attributes for the DocumentDefinition class are the same as those for the Document class.
Package Name: oracle.ifs.beans
Class Name: ContentObject
ParentClass: SystemObject
Purpose: Stores the actual content of a document.
Methods: The ContentObject class provides a number of methods specific to getting and setting its attributes, including content, content size, and format.
Attributes: The following attributes are unique to the ContentObject class:
Package Name: oracle.ifs.beans
Class Name: Folder
ParentClass: PublicObject
Purpose: Adds the ability to manage references to other files.
Methods: The Folder class provides methods to manipulate items in a folder, such as getItems().
Uses: Create a custom subclass of the Folder class if you need an object that manages references to other objects.
Attributes: The Folder class does not contain any unique attributes.
Security in Oracle iFS is provided by AccessControlLists (ACLs), which provide security information for a specific object through a collection of AccessControlEntries (ACEs). Each ACE grants or revokes specific permissions related to that object toa user or group.
Package Name: oracle.ifs.beans
Class Name: AccessControlList
ParentClass: PublicObject
Purpose: Used to specify access rights to documents.
Methods: The AccessControlList class provides specific methods to manipulate AccessControlEntries.
Uses: Use the AccessControlList class to acquire information about a group of AccessControlEntries.
Attributes: The following attributes are unique to the AccessControlList class:
Attribute | Datatype | Description |
---|---|---|
|
Boolean |
Indicates whether this ACL is shared. Default value is TRUE. |
Package Name: oracle.ifs.beans
Class Name: AccessControlEntry
ParentClass: SystemObject
Purpose: Used to specify access rights for a specific user or group.
Methods: The AccessControlEntry class provides specific methods to obtain information from AccessControlEntries.
Uses: Use the AccessControlEntry class to acquire information about a specific AccessControlEntry.
Attributes: The following attributes are unique to the AccessControlEntry class:
If a user wants to add data to or retrieve data from the Oracle iFS repository, that user must have a working session to create the connection to the repository. Creating this session is the first task of every Oracle iFS application, and requires the following classes:
The LibrarySession class is a lynch-pin class in Oracle iFS. All persistent objects, that is, objects stored in the Oracle iFS repository, are created from the LibrarySession class.
Package Name: oracle.ifs.beans
Class Name: LibraryService
ParentClass: java.lang.Object
Purpose: The LibraryService class is used for connecting to the Oracle iFS server and launching sessions via the LibrarySession object.
Methods: The LibraryService class is a factory class for LibrarySession. The LibraryService class has a public constructor and one method, the connect() method. The connect() method either returns a LibrarySession or throws an exception indicating a connect failure.
Uses: Use the LibraryService class to create an instance of LibrarySession.
Package Name: oracle.ifs.beans
Class Name: LibrarySession
ParentClass: java.lang.Object
Purpose: Each instance of LibrarySession represents an authenticated user session, that is, a repository connection.
Methods: The LibrarySession class provides the key methods used to create and free repository objects.
Uses: Use the LibrarySession class to manipulate all persistent objects.
Tie classes allow you to alter the out-of-the-box behavior of the Oracle iFS classes by "tie-ing" into the hierarchy at any level. Each Tie class provides an implementation class for its corresponding Oracle iFS class. Thus, the implementation class for Document is TieDocument. Because Tie classes provide the implementation classes for Oracle iFS classes, the way to alter the behavior of Document and all its subclasses is to extend TieDocument. Tie classes allow you to insert changed behavior in a single place, which leads to cleaner code and ease of maintenance.
Tie classes are "empty" classes that hold a place in the Oracle iFS hierarchy so you can customize the behavior of existing Oracle iFS classes and have the new behavior become part of the inheritance structure. When you write Java code to change the functionality of the Document class, your new class extends not Document, but TieDocument.
To understand Tie classes, you need to know that the Tie classes come below their corresponding classes in the Oracle iFS class hierarchy. For example, consider the following hierarchy for TieDocument:
java.lang.Object +--oracle.ifs.beans.LibraryObject +--oracle.ifs.beans.TieLibraryObject +--oracle.ifs.beans.PublicObject +--oracle.ifs.beans.TiePublicObject +--oracle.ifs.beans.Document +--oracle.ifs.beans.TieDocument
Suppose that you want to subclass the Document class, creating three new classes: Reports, Specs, and Memos. Assume that there is common functionality you want to include in Document itself, so that all three new classes, as well as all future subclasses of Document, will inherit that behavior. This common functionality could be that the Description field should always contain the company name followed by name of the user who is creating or modifying the document. One approach would be to place the code for the common Description functionality in each of the new subclasses. However, this would mean the code would be in three places (and possibly more, in the future), which would add complexity and increase future maintenance requirements.
For clarity and ease of maintenance, it would be preferable to alter the behavior of the base Document class, so that all three new subclasses, as well as any future subclasses, would inherit the behavior. However, because the Document class is part of the Oracle iFS API, you cannot extend it directly. Tie classes are provided for this purpose. Tie classes provide the implementation classes for the Oracle iFS classes, so the way to alter the behavior of Document and all its subclasses is to extend TieDocument.
Returning to our example, the way to achieve the preferred implementation is to add the new Description functionality in one place: the TieDocument class. Then, if Reports, Specs, and Memos all subclass TieDocument, they will automatically inherit the new behavior. For an example of a class that extends TieDocument, see "Sample Code: Create an Instance Class Bean", in Chapter 4, "Creating Custom Classes".
Tie classes are provided for both bean-side and server-side classes, so there is both a TieDocument and an S_TieDocument class.
Tie classes are only relevant to existing Oracle iFS classes. When you extend your own custom classes, you have access to your original code, and can extend the base class. For example, to create a custom StatusReports class that inherits functionality from your custom class Reports, simply extend Reports.
In the Oracle iFS Java class hierarchy each Oracle iFS object has two representations:
oracle.ifs.beans
package.
oracle.ifs.server
package.
Most application work is done with the bean-side classes. However, two types of customization require working with objects in the database and need to use the server-side classes:
Until you work with renderers or overrides, you only need to be concerned with the bean-side classes. Behind the scenes, however, Oracle iFS uses the S_ classes, such as S_Document, for processing that must be carried out on the document in the database. When you encounter S_ classes in the sample code, you know that you are dealing with the server-side representation of the object.
For more information on using server-side classes for specific types of customization, see:
|
Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|