Skip Headers

Oracle Content Management Software Development Kit (SDK) Developer Reference
Release 9.0.3

Part Number A96698-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

4
Creating an Oracle Content Management SDK 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 CM SDK 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 fat.gif follows.

Text description of the illustration fat.gif

Understanding How Files Are Stored in the Oracle CM SDK Repository

In Oracle CM SDK, the metadata and document content are stored separately. The metadata are stored in fields across several tables in the database, while the content is stored as a LOB field in another table. The Document's unique ID number is the foreign key used to join the information stored in several tables to construct the Document object.

Storing documents in this way enables the document metadata and content to be indexed and queried as a relational database fields. When the time comes to treat the indexed data as a document (for example, when the file is copied from Oracle CM SDK 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 CM SDK. 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 CM SDK, the time has come to discuss how documents can be loaded programmatically into the Oracle CM SDK repository. There are four essential steps to creating a document in Oracle CM SDK.

  1. Establish a connection to the Oracle CM SDK 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 CM SDK repository, your application must establish a connection, called a LibrarySession, with the Oracle CM SDK 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 CM SDK Repository.

Example 4-1 Establishing a Connection to the Oracle CM SDK Server

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


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

public class SimpleConnection 
{
  public static void main(String[] args) throws IfsException
  {
    try {
      // Connect to the Oracle CM SDK server. The arguments (args) are
      // IfsService, IfsSchemaPassword, ServiceConfiguration, Domain, 
      // UserName, UserPassword

      System.out.println("Connecting...");
      
      // Use the IfsService and IfsServicePassword to start a LibraryService
      LibraryService service = LibraryService.startService(args[0], args[1],
                                                           args[2], args[3]);

      // Create a CleartextCredential object, which encapsulates the 
      // username and password.
      CleartextCredential cred = new CleartextCredential(args[4], args[5]);

      // Start a LibrarySession by passing the credentials to the service
      LibrarySession ifsSession = service.connect(cred, null);

      /* This is the place where you add code that actually does something.
       * To show that we're connected, we'll query the repository for
       * the name of the user who has logged in.
      */ 
      
      DirectoryUser du = ifsSession.getDirectoryUser();
      System.out.println("Current user: " + du.getName());

      // Disconnect from the LibrarySession.
      ifsSession.disconnect();
      System.out.println("Disconnected.");
    } 
    catch (Exception e)
    {
      e.printStackTrace();
    }
  }
}

Creating a Document Object

Objects are created in Oracle CM SDK 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 CM SDK 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 CM SDK 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 CM SDK repository, all attributes are first instantiated as AttributeValue objects. AttributeValue objects are interpolators, formatting Java values to prepare them for insertion to the Oracle CM SDK 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 CM SDK. 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.

For this example, we are setting only the name of the file and its content. The name attribute has its own method, setName(), that can be used to set the value. this is the filename that will be displayed when the file is listed in an Oracle CM SDK folder.

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 using the setName and setContent methods to set for the Document's Name and Content attributes, respectively.


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

// Set the Name attribute for the new document.
newDocDef.setName("HelloWorld.txt");

// Set the content of the document.
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 CM SDK 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 CM SDK

In Oracle CM SDK, 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-2 A Folder/Document Relationship

Text description of leftrite.gif follows.

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-3 A Folder/Subfolder Relationship

Text description of foldrsub.gif follows.

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 CM SDK. 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 CM SDK repository.

Figure 4-4 A Document with Multiple Parent Folders

Text description of multipar.gif follows.

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 CM SDK repository. Example 4-5, "HelloWorld.java" shows the complete application.

Example 4-5 HelloWorld.java

// Copyright (c) 2001, 2002 Oracle Corporation. All rights reserved.

package oracle.ifs.examples.devdoc.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 server
import oracle.ifs.beans.LibraryService;
import oracle.ifs.beans.LibrarySession;

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

// Class used to create the persistent Document object in the repository
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 specific exceptions
import oracle.ifs.common.IfsException;
import oracle.ifs.common.ParameterTable;

/*
 * HelloWorld class. This class demonstrates the steps needed to
 * connect to the repository, create a new document,
 * insert the document in a folder, and disconnect from the server.
 */
 
public class HelloWorld
{
  /* Connect to the server. The arguments are IfsService,
   * IfsServicePassword, ServiceConfigurationName, DomainName, UserName, UserPas
sword. The syntax
   * to run the program is:
   * java oracle.ifs.examples.devdoc.helloworld.HelloWorld ifsService
   *  cmsdk SmallServiceConfiguration ifsDomain system manager
   */

  public static void main(String[] args) throws IfsException
  {
    /* As a rule, you should always use VerboseMessages in your
    *  classes, because it will result in better error message output to
    *  help you with your debugging. Set the value to true at the start
    *  of each of your programs.
    */

    IfsException.setVerboseMessage(true);
    try
    {

      // Obtain the arguments.
      ParameterTable params = new ParameterTable(args);

      String user = null;

      String password = null;

      String service = null;

      String schemapassword = null;

      String serviceconfig = null;

      // The domain is a string comprised of the following:
      // ifs://<hostname>:<SQL*Net Listener Port - default 1521>:
      // <TNS Database Service Name>:<Schema Name>
      String domain = null;

      user = params.getString("user", "system");

      password = params.getString("password","manager");

      service = params.getString("service","IfsServiceDefault");

      schemapassword = params.getString("schemapassword","ifssys");

      serviceconfig = params.getString("serviceconfig", "SmallServiceConfigurati
on");

      domain = params.getString("domain");

      System.out.println("Running with arguments : ");

      System.out.println("  user = " + user);

      System.out.println("  password = " + password);

      System.out.println("  service = " + service);

      System.out.println("  schemapassword = " + schemapassword);

      System.out.println("  serviceconfig = " + serviceconfig);

      System.out.println("  domain = " + domain);

      System.out.println("---------Results----------");

      // Start the LibraryService.
      LibraryService lsrvc = LibraryService.startService(service, 
                                 schemapassword, serviceconfig, domain);
      System.out.println("Serivce obtained.");

      // Create a CleartextCredential object that encapsulates the user's
      //  log in information.
      CleartextCredential cred = new CleartextCredential(user, password);

      System.out.println("Credentials set.");

      // Connect (create a LibrarySession) using the Service and
      //  CleartextCredential objects.
      LibrarySession ifsSession = lsrvc.connect(cred, null);

      System.out.println("Session obtained.");

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

      // Set the Name attribute for the new document.
      newDocDef.setName("Helloworld.txt");

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

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

      System.out.println("New document created :  " + doc.getName());

      // Begin the foldering process. First, instantiate a DirectoryUser
      // object that represents 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();

      System.out.println("User's home folder obtained : " + homeFolder.getName()
);

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

      System.out.println("Document added to folder.");

      // Close the connection.
      ifsSession.disconnect();

    }
    catch (Exception e)
    {
      e.printStackTrace();
    }
  }
} 

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 Content Management SDK".

  2. Compile HelloWorld.java.

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

  4. Run the class by entering the following command at the command line:

    java HelloWorld
    service=<service name>
    schemapassword=<schema password>
    serviceconfig=<service configuration>
    domain=<domain>
    user=<user name>
    password=<user password>

  5. The document HelloWorld.txt will appear in the home folder of the user identified by the user name and user password arguments used in Step 4.


Go to previous page Go to next page
Oracle
Copyright © 1999, 2002 Oracle Corporation.

All Rights Reserved.
Go To Table Of Contents
Contents
Go To Index
Index