2
API Overview

This chapter covers the following topics:

• Introducing the Oracle iFS Java API

• The LibraryObject Class

• The oracle.ifs.beans Class Hierarchy

• The PublicObject Class

• Document and Folder Classes

• Security Classes

• Session Classes

• Tie Classes

• Server Classes

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:

• Classes for storing documents and attributes, such as Document and Folder.

• Classes that provide document management functionality, such as check-in/check-out and version control.

• Classes that provide security, such as Users, Groups, and ACLs.

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:

• Scan the classes highlighted in this chapter.

• Consult the Javadoc for each of these key classes.

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
oracle.ifs.agents.common	Classes used to create and manage agents.
oracle.ifs.beans	The most important package. Contains most of the classes used by application developers.
oracle.ifs.beans.parsers	Classes used to create custom parsers.
oracle.ifs.search	Classes used for search functionality.
oracle.ifs.server	Server-side classes for managing objects in the database.
oracle.ifs.server.renderers	Classes used create custom renderers.
oracle.ifs.common	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:

• Updating an object

• Deleting an object

• Setting/getting attributes for an object

LibraryObject has three subclasses, which are abstract superclasses for the objects below them in the hierarchy:

• PublicObject

• SystemObject

• SchemaObject

The following table describes the purpose of the three LibraryObject subclasses.

Class	Purpose	Direct Interaction with End Users?
PublicObject	The superclass for all objects that end users deal with directly, such as documents and folders.	Yes
SystemObject	The superclass for all system-wide utility classes. These classes are used to help manage PublicObjects.	No
SchemaObject	The superclass for classes that manage how all repository information is stored and managed.	No

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:

java.lang.Object
  +--oracle.ifs.beans.LibraryObjectDefinition
        +--oracle.ifs.beans.PublicObjectDefinition
               +--oracle.ifs.beans.DocumentDefinition

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:

• The class hierarchy of the oracle.ifs.beans package, which contains the most frequently used classes.

• The most commonly used individual classes and their unique attributes.

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:

• PublicObject

• SystemObject

• SchemaObject

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:

• Definition classes are used to group attributes before creating a PublicObject.

• Tie classes are used to add behavior to all subclasses of a specific PublicObject.

• Server classes (preceded with an S_) are used to work with objects inside the Oracle iFS respository.

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:

• Classes that end users deal with directly, such as Document and Folder objects.

• Classes that play a supporting role, such as Groups and Access Control Lists.

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:

• Public objects are the only objects that appear in folders.
  • Foldering is not required: A public object can exist as an unfoldered object.

  • In addition, a public object can appear in multiple folders.

• Public objects are access-controlled. Methods implemented on this class can be used to grant, revoke, set, and inquire on permissions.

• Public objects have a large set of attributes, some of which you must set and others that are set automatically:
  • Some attributes are system-set, such as the CreateDate and LastModifyDate attributes.

  • Other attributes can be set from the API, such as the Owner, Description, and ACL (Access Control List) attributes.

• Public objects are the only objects that can be versioned.

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:

• Inherited: The Document class inherits a set of common attributes from the PublicObject class, such as Owner and CreateDate.

• Class-specific: The Document class also includes attributes specific to the Document class, such as ContentObject and ReadByOwner.

Public Object Attributes

The following table lists the attributes of the PublicObject class. Use this list for two purposes:

• To find out if there is an attribute defined "out-of-the-box" that will meet your needs.

• To choose a unique name for any custom attributes. Because attribute names must be unique within Oracle iFS, names of all pre-defined attributes of classes in the Oracle iFS API are reserved words, and may not be used to identify custom attributes.

  
  

  Attribute	Datatype	Comments
  Name	String (700)	Name of the document. Required.
  Description	String (2000)	Detailed description of the document.
  Owner	DirectoryObject	Owner of the document. Set by system. (Can also be set explicitly.)
  ACL	PublicObject	ACL assigned to this document.
  Family	PublicObject	The Family related to this document. Used in connection with versioned document. For non-versioned documents, value is NULL.
  ResolvedPublicObject	PublicObject	Used by non-document objects. Not relevant to documents.
  CreateDate	Date	Date the document was created.
  Creator	DirectoryObject	User who created the document.
  LastModifyDate	Date	Date the document was modified.
  LastModifier	DirectoryObject	User who modified the document.
  Deletor	PublicObject	Reserved for future use.
  PolicyBundle	PublicObject	Can be used to control any behavior overrides for this object. Used to map the desired renderer.
  PropertyBundle	PublicObject	Used for storing ad hoc name/value pairs.
  SecuringPublicObject	PublicObject	Not relevant for documents. Indicates that security for this object is based on the ACL for another object.
  ExpirationDate	Date	Date the document will be deleted.
  LockState	Integer	Indicates that document has some type of lock. Locks can be set on a permanent or session basis.
  Flags	Integer	Reserved for system use. Used by protocol servers to store miscellaneous status bits.
  LockedForSession	Long	Indicates that the document is locked for the current session. Attribute holds the session identifier.
  ID*	Long	Unique numeric identifier for current object. Set by system.
  ClassID*	Long	Unique numeric identifier for class of current object. Set by system.

*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:

• It is a standard Oracle iFS document.

• You do not need to define a custom document class to store this document in Oracle iFS.

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	Document	Holds content data.
	DocumentDefinition	Used to build a document in memory. Note that all classes used to create objects, such Folder and Family, also have corresponding Definition classes.
	ContentObject	Holds a reference to the actual document content.
Organization	Folder	Groups objects together.
Versioning	Family	Groups a series of related versioned public objects.
	VersionSeries	Groups a series of related versioned public objects within a family. A family can have more than one series.
	VersionDescription	Creates an individual versioned public object within a VersionSeries object.
Security	AccessControlList (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.
	AccessControlEntry	An entry in an Access Control List (ACL), specifying access privileges for a single user or group.
Support Objects	ApplicationObject	Acts as superclass for custom objects.
	PropertyBundle	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:

• Start with the PublicObject class, because it is the abstract class from which all user-related classes inherit.

• Then check the subclass of PublicObject that you are interested in, such as the Document class.

• To familiarize yourself with the attributes of the class, see the related Definition class, such as the DocumentDefinition class.

Document and Folder Classes

Four classes are used to work with folders, documents (files), and their contents:

• The Document Class

• The DocumentDefinition Class

• The ContentObject Class

• The Folder Class

If your application deals with a document (file), you will need to create three objects:

• A Document object to store the attributes and a reference to the ContentObject in the repository.

• A DocumentDefinition object to hold the attributes of the file. The DocumentDefinition object is transitory and is used to create the Document object.

• A ContentObject to store the actual content of a Document object.

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
ContentObject	ContentObject	The ObjectID of the ContentObject that holds the content for this document.
ReadByOwner	Boolean	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
CharacterSet	String	Character set used to represent the language for this ContentObject.
Content	Long	A pointer to the actual content of the document.
ContentSize	Long	Size of content in bytes.
Format	SystemObject	Format/MIME type for this ContentObject.
Language	String	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
Shared	Boolean	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
AccessLevel	Long	Required.
Acl	PublicObject	ACL with which this ACE is associated. Required.
ExtendedPermissions	SystemObject Array	Optional.
Granted	Boolean	Indicates whether this grantee has this permission. Default is TRUE. Required.
Grantee	DirectoryObject	DirectoryUser object for person or group this permission is for. Required.
PermissionBundles	SystemObject Array	Optional.
SortSequence	Long	Required.

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 LibraryService Class

• The LibrarySession Class

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:

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.

Note: 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:

• The bean-side representation, known by the object name, such as "Document." The bean-side classes are stored in the oracle.ifs.beans package.

• The server-side representation, known by the object name preceded with "S_", such as "S_Document." The server-side classes are stored in the 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:

• Renderers

• Overrides

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:

• Chapter 6, "Using Renderers", "Using Server-Side Classes with Renderers".

• Chapter 9, "Using Overrides", "Attributes and Server-Side Classes".