4
Creating an Oracle Internet File System Document

This chapter explains how to programmatically work with the out-of-the-box Document class to create a generic Document object. Understanding the process of creating an instance of the standard Document will provide a base on which customization concepts can be built.

This chapter covers the following topics:

• Understanding How Files Are Stored in the Oracle 9iFS Repository

• Understanding the Steps to Creating a Document Object

• Creating a Document Object

• Adding a Document to a Folder

• Reviewing the Complete Application

Understanding How Files Are Stored in the Oracle 9iFS Repository

This section provides a brief conceptual overview describing how file information is organized and stored in an Oracle9i database. Some of the details have been simplified.

Understanding How Files Are Stored in a File System

In a standard file system, files are stored in two parts. This discussion deals with a specific implementation that many people will find familiar: the DOS file system known as FAT. The metadata, or file attributes, are stored in the File Allocation Table (FAT). Metadata includes the name and path of the file, the creation and modification dates, etc. The content of the document is stored in logical divisions of the disc known as sectors. The FAT keeps track of the location of the sectors of the file that, when reconstructed, constitute the body of the document. Figure 4-1 shows a simplified representation of a file stored on a local hard disk.

Figure 4-1 Document stored on a hard disk

Text description of the illustration fat.gif

Understanding How Files Are Stored in the Oracle 9iFS Repository

In Oracle 9iFS, the metadata and document content are stored separately. The metadata are stored in several tables in the Oracle 9iFS schema, while the content is stored as a LOB in the table ODMM_CONTENTSTORE. The Document's unique ID number is the foreign key used to join the information stored in several tables to construct the Document object. Figure 4-2 presents a simplified diagram of how documents are stored in the Oracle 9iFS repository.

Figure 4-2 Document stored in the Oracle 9iFS Repository
Text description of the illustration pubobj.gif

Table 4-1 describes the schema tables used to store metadata for a Document.

Table 4-1 Tables Used to Store Document Metadata

Table	Description
ODM_PUBLICOBJECT	This table stores the basic information common to any file that can appear in a folder and be directly modified by an end-user. It stores attributes such as the name, last modification date, creator, owner, and more.
ODM_DOCUMENT	The Document subclass of PublicObject only requires two additional attributes: ReadByOwner, which is a Boolean flag indicating that the file has been read (primarily used for electronic mail documents) and ContentObject, the ID number of the body of the document, stored in the table ODMM_CONTENTSTORE.
ODMM_CONTENTSTORE	This table stores information about the format and language of the document, and stores the body of the document as a BLOB. (In truth, there are two tables used to store content, ODMM_CONTENTSTORE for indexed data, and ODMM_NONINDEXEDSTORE for non-indexed data.)

The tables ODM_PUBLICOBJECT and ODM_DOCUMENT effectively take on the role of the File Allocation Table, while the ODMM_CONTENTSTORE table is used to store the body of the document.

Storing documents in this way enables the document content to be indexed and queried as a relational database field. When the time comes to treat the indexed data as a document (for example, when the file is copied from Oracle 9iFS to a local disk), the document is reconstructed by sending its metadata to the local file system, then sending the document content object as a byte stream.

All of this processing is transparent to the end-user, and much of the overhead of manipulating the data is handled for the application developer by Oracle 9iFS. This overview is intended to give a general sense of how the information is handled "behind the scenes," so that the process of creating documents in the system will be easier to understand.

Understanding the Steps to Creating a Document Object

Now that you have a sense of how documents are stored in Oracle 9iFS, the time has come to discuss how documents can be loaded programmatically into the Oracle 9iFS repository. There are four essential steps to creating a document in Oracle 9iFS.

1. Establish a connection to the Oracle 9iFS server.

2. Create a DocumentDefinition, a runtime version of the document with the attributes and content.

3. Create a persistent Document object in the repository, based on the DocumentDefinition.

4. Place the new Document in a Folder.

Connecting to the Repository

Before any work can be done inside the Oracle 9iFS repository, your application must establish a connection, called a LibrarySession, with the Oracle 9iFS server. The first step is to instantiate an object representing a LibraryService, essentially the server to which you want to connect. You then pass the LibraryService a set of valid credentials, and the LibraryService returns a new LibrarySession. The LibrarySession is a handy class that is used to access useful information about the current work session, and is used as a parameter in most of the commands that modify information in the Oracle 9iFS Repository.

Example 4-1 Establishing a Connection to the Oracle 9iFS Server

This is the bare bones of an Oracle 9iFS application. This program establishes a connection, then disconnects. The constructor for this class accepts an array of four arguments.

package oracle.ifs.examples.documentation.connection;
import oracle.ifs.beans.LibraryService;
import oracle.ifs.beans.LibrarySession;
import oracle.ifs.common.CleartextCredential;
import oracle.ifs.common.IfsException;

public class SimpleConnection 
{
  /*
   * Connect to the Oracle 9iFS server. The arguments (args) are 
   *   IfsService, IfsServicePassword, UserName, UserPassword.
   */
  public void static main (String[] args)
  {
    // Use the IfsService and IfsServicePassword to start the service.
    LibraryService service =
      LibraryService.startService(args[0], args[1]); 

    /*
     * Use the UserName and UserPassword to instantiate a 
     *   CleartextCredential object.
     */
    CleartextCredential cred = 
      new CleartextCredential(args[2], args[3]); 
    LibrarySession ifsSession = service.connect(cred, null);

    // This is the place where you insert the part of the 
    // program that actually does something.

    //Disconnect the session.
    session.disconnect();
  }
}

Creating a Document Object

Objects are created in Oracle 9iFS in two stages. The first step is to create an object definition, which defines the attributes of the object you want to create. The second step is to instantiate the object on the server. This enables the Oracle 9iFS repository to create the object as the result of a single transaction, rather than an individual transaction to set each attribute.

Creating a DocumentDefinition Object

The constructor for the DocumentDefinition class requires only the current LibrarySession as a parameter.

For example, the following line of code instantiates a new DocumentDefinition named newDocDef, using the LibrarySession session created in the earlier example.

DocumentDefinition newDocDef = new DocumentDefinition(session);

Setting Document Attributes

Once a DocumentDefinition is created, the next step is to populate its attributes. There is a small conversion issue, however, because the datatypes used in Java are not always compatible with the datatypes used by the Oracle9i database. In some cases, Oracle 9iFS objects are used as attributes for other objects; for example, a Document's owner is identified by DirectoryUser object ID. In order to format information to handle the special needs of the Oracle 9iFS repository, all attributes are first instantiated as AttributeValue objects. AttributeValue objects are interpolators, formatting Java values to prepare them for insertion to the Oracle 9iFS repository, and also to format values stored in the repository before they are returned to Java programs.

The AttributeValue class has overloaded constructors to accept every datatype, as single or array values, that can be stored in Oracle 9iFS. To insert a value from a Java application to DocumentDefinition, you first instantiate it as an AttributeValue, then use the value as an argument to the setAttribute() method.

For more information on the datatypes available for AttributeValue objects, see the Javadoc for the AttributeValue class.

Setting a Document object's content is handled in a different manner. The content is not metadata, and so is not stored in the Attributes table. The DocumentDefinition() class provides several methods by which the content can be specified. The simplest case is to pass a String directly to the setContent() method, but the more common method would be to use the setContentPath() method, which takes as an argument the path to a file on the local disk from which the new Document object will take its content.

Example 4-2 Setting Values in a DocumentDefinition

This code snippet shows the creation process for the DocumentDefinition, instantiating a new DocumentDefinition, and setting the AttributeValues for the Document's Name and Content attributes.

DocumentDefinition newDocDef = DocumentDefinition(session);

newDocDef.setAttribute(PublicObject.NAME_ATTRIBUTE, 
  AttributeValue.newAttributeValue("HelloWorld.txt"));

newDocDef.setContent("Hello world.");

Creating the Document

Once the DocumentDefinition has been created, the Document object itself can be created in a single transaction, using the LibrarySession.createPublicObject() method. All PublicObjects are created using this method. By passing this method a DocumentDefinition, the Oracle 9iFS API knows that the specific type of PublicObject to be created will be a Document.

Example 4-3 Creating a Persistent Document Object

This line of code will create a persistent document based on the DocumentDefinition created in Example 4-2. The resulting document is instantiated as a runtime Document object to allow the program to reference it for further processing.

Document doc = (Document) ifsSession.createPublicObject(newDocDef);

Adding a Document to a Folder

By default, new instances of PublicObject and its subclasses are created unfoldered. To enable users to navigate to the Document using a directory interface, new documents should be foldered as they are created.

Understanding How Document and Folder Relationships Are Represented in a File System

In a standard file system, a document's path is embedded in its definition in the File Allocation Table. For example, if the file myDoc.txt is stored in the directory myFolder, the entry in the FAT would be similar to this:

\myFolder\myDoc.txt

The only means of referencing the specific instance of the document is via the embedded path. Multiple copies of the document can be placed in other directories, but they are separate documents; that is, if the original is updated, the copies are not.

Microsoft Windows allows you to create shortcuts to documents, but a shortcut is itself a document with the sole purpose of pointing to a file's location. If the file is deleted, the shortcut will still exist, but it will point to nothing.

Understanding How Document and Folder Relationships Are Represented in Oracle 9iFS

In Oracle 9iFS, Folders are PublicObjects. In fact, the Folder subclass introduces no new attributes beyond those provided by the PublicObject class.

Documents and subfolders are associated with Folder objects by creating a Relationship object (more specifically, a FolderPathRelationship, which inherits the attributes of interest from the Relationship class). The Folder ID is stored as the LEFTOBJECT in the Relationship record, and the Document ID is stored as the RIGHTOBJECT.

Figure 4-3 A Folder/Document Relationship

Text description of the illustration leftrite.gif

Folders are associated with other Folder objects in the same way. The ID of the "parent" is stored as the LEFTOBJECT, and the ID of the "child" is stored in the RIGHTOBJECT column.

Figure 4-4 A Folder/Subfolder Relationship

Text description of the illustration foldrsub.gif

This provides greater flexibility for end users. The same document can appear in multiple folders, but is stored only one time in Oracle 9iFS. If the document is updated in one location, it is updated in all locations, since all folders are pointing to the same object. If the file is deleted from one of its parent folders, it remains in the system and is displayed in all of its other parent folders. Only when all instances of the document have been deleted from all parent folders is the document removed from the Oracle 9iFS repository.

Figure 4-5 A Document with Multiple Parent Folders

Text description of the illustration multipar.gif

Associating a Document with a Folder

You associate a Document with a Folder by instantiating the persistent Folder object as a runtime Java object, then use the Folder.addItem() method to add the Document object to the Folder.

Example 4-4 Adding a Document to a Folder

This code snippet adds the Document object created in Example 4-3 to the user's home folder.

DirectoryUser thisUser = session.getDirectoryUser();
PrimaryUserProfile userProfile =
  ifsSession.getPrimaryUserProfile(thisUser);
Folder homeFolder = userProfile.getHomeFolder();
homeFolder.addItem(doc);

Reviewing the Complete Application

The code samples in this chapter have illustrated each of the steps needed to create a Document object in the Oracle 9iFS repository. Example 4-5, "HelloWorld.java" shows the complete application.

Example 4-5 HelloWorld.java

package oracle.ifs.examples.documentation.helloworld;

// Class used to represent the current user at runtime
import oracle.ifs.beans.DirectoryUser;

// Class used to instantiate the Document object at runtime
import oracle.ifs.beans.Document;

// Class used to define the attributes of the new Document object
import oracle.ifs.beans.DocumentDefinition;

// Class used to represent a Folder object at runtime
import oracle.ifs.beans.Folder;

// Classes used to create the connection to the Oracle 9iFS server
import oracle.ifs.beans.LibraryService;
import oracle.ifs.beans.LibrarySession;

// Class used to access information about the current user; in this 
//  program, used to access the user's home folder.
import oracle.ifs.beans.PrimaryUserProfile;

// Class used to create the persistent Document object in the repostiory
import oracle.ifs.beans.PublicObject;

// Class used to hold the user's authentication information
import oracle.ifs.common.CleartextCredential;

// Class used to trap and report 9iFS specific exceptions
import oracle.ifs.common.IfsException;

/* 
 *  HelloWorld class. This class demonstrates the steps needed to 
 *  connect to an instance of Oracle 9iFS, create a new document,
 *  insert the document in a folder, and disconnect from the Oracle
 *  9iFS server.
 */

public class HelloWorld throws IfsException
{

  /*
   * Connect to the Oracle 9iFS server. The arguments are IfsService,
   * IfsServicePassword, UserName, UserPassword.
   */
  public void static main (String[] args)
  {
    // Start the LibraryService.
    LibraryService service =
      LibraryService.startService(args[0], args[1]); 

    // Create a CleartextCredential object with the user's login 
    //   information.
    CleartextCredential cred = 
      new CleartextCredential(args[2], args[3]); 

    // Connect using the Service and Credential information.
    LibrarySession ifsSession = service.connect(cred, null);

    // Instantiate an empty DocumentDefinition object.
    DocumentDefinition newDocDef = DocumentDefinition(ifsSession);

    // Set the Name attribute for the new document.
    newDocDef.setAttribute(PublicObject.NAME_ATTRIBUTE,
      AttributeValue.newAttributeValue("HelloWorld.txt"));

    // Set the content of the new document.
    newDocDef.setContent("Hello world.");

    // Create the document in the Oracle 9iFS repository.
    Document doc = (Document) ifsSession.createPublicObject(newDocDef);

    // Begin the foldering process. First, instantiate a DirectoryUser
    //   object representing the current user.
    DirectoryUser thisUser = ifsSession.getDirectoryUser();

    // Get the PrimaryUserProfile information for the current user.
    PrimaryUserProfile userProfile =
      ifsSession.getPrimaryUserProfile(thisUser);

    // Instantiate a runtime representation of the user's home folder.
    Folder homeFolder = userProfile.getHomeFolder();

    // Insert the new document to the user's home folder.
    homeFolder.addItem(doc);

    // Close the connection to Oracle 9iFS.
    session.disconnect();
  }
}

Running the HelloWorld.java Application

To run the HelloWorld.java application:

1. Ensure that you have set up your development environment as described in Chapter 1, "Getting Started with the Oracle Internet File System SDK".

2. Compile HelloWorld.java.

3. Place the resulting package structure, /examples/devdoc/helloworld/HelloWorld.java in the $IFS_HOME/custom_classes directory.

4. Run the class by entering the following command at the command line:
   
   java HelloWorld <serviceName> <schemaPassword> <userName> <userPassword>

5. The document HelloWorld.txt will appear in the home folder of the Oracle 9iFS user identified by the userName and userPassword arguments used in Step 4.