Oracle Internet File System Developer's Guide
Release 1.1

Part Number A75172-04






Go to previous page Go to next page

API Overview

This chapter covers the following topics:

Introducing the Oracle iFS Java API

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 Oracle iFS API Packages

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.

Package Name  Description 


Classes used to create and manage agents. 


The most important package. Contains most of the classes used by application developers. 


Classes used to create custom parsers. 

Classes used for search functionality. 


Server-side classes for managing objects in the database. 


Classes used create custom renderers. 


Utility classes used by both bean-side and server-side classes.  

The LibraryObject Class

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.

Class  Purpose  Direct Interaction with End Users? 


The superclass for all objects that end users deal with directly, such as documents and folders. 



The superclass for all system-wide utility classes.
These classes are used to help manage PublicObjects.  



The superclass for classes that manage how all repository information is stored and managed.  


The LibraryObjectDefinition Class

To create any Oracle iFS object is a two-stage process:

  1. Build the definition of the object, using the appropriate Definition class, such as DocumentDefinition.

  2. Pass the Definition object to the createPublicObject() method (or its analogue in other classes, createSystemObject() or createSchemaObject()).

All Definition classes inherit from LibraryObjectDefinition and PublicObjectDefinition, as shown in the following class hierarchy:


The oracle.ifs.beans Class Hierarchy

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:

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.




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).

The PublicObject Class

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:

Characteristics of Public Objects

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:

Public Object 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.

Do You Need to Create a Custom Oracle iFS Document?

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.

User-related Classes

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.)

Function  Key Classes  Purpose 

Hold Content 


Holds content data. 



Used to build a document in memory.

Note that all classes used to create objects, such Folder and Family, also have corresponding Definition classes. 



Holds a reference to the actual document content.




Groups objects together.




Groups a series of related versioned public objects. 



Groups a series of related versioned public objects within a family. A family can have more than one series. 



Creates an individual versioned public object within a VersionSeries object.



(and subclasses) 

Contains a list of security entries called Access Control Entries (ACEs) that grant or revoke privileges on the object to a user or group. 



An entry in an Access Control List (ACL), specifying access privileges for a single user or group. 

Support Objects 


Acts as superclass for custom objects. 



Used for managing custom lists of name/value pairs. 

Javadoc for User-Related Classes

To understand a given user-related class, consult the Javadoc for these three classes related to whichever class you choose:

Document and Folder Classes

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.

The Document Class

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:

Attribute  Datatype  Description 



The ObjectID of the ContentObject that holds the content for this document. 



A flag that indicates whether the document owner has read the current content. Used by IMAP to indicate whether the text of a message has been read. 

The DocumentDefinition 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.

The ContentObject 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:

Attribute  Datatype  Description 



Character set used to represent the language for this ContentObject. 



A pointer to the actual content of the document. 



Size of content in bytes. 



Format/MIME type for this ContentObject. 



Language for this ContentObject. 

The Folder 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 Classes

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.

The AccessControlList Class

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 



Indicates whether this ACL is shared. Default value is TRUE. 

The AccessControlEntry Class

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:

Attribute  Datatype  Description 






ACL with which this ACE is associated. Required. 


SystemObject Array 




Indicates whether this grantee has this permission. Default is TRUE. Required. 



DirectoryUser object for person or group this permission is for. Required. 


SystemObject Array 





Session Classes

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.

The LibraryService 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.

The LibrarySession Class

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

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:


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.


If you place custom code directly in TieDocuments, be sure to alter your CLASSPATH so the reference to the customized class precedes the reference to the repository .jar file. 

Server Classes

In the Oracle iFS Java class hierarchy each Oracle iFS object has two representations:

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:

Go to previous page Go to next page
Copyright © 2000 Oracle Corporation.

All Rights Reserved.