3
Working with Documents

This chapter covers the following topics:

• How Documents Are Stored in the Repository

• Connecting to the Repository

• Creating a New Document

• Putting a Document in a Folder

• Working with Attributes

• Searching for a Document

• Sample Code: Hello World

How Documents Are Stored in the Repository

The Internet File System repository provides persistent storage for all of your documents (files) in database tables. Documents are stored in the repository in two parts:

• Document attributes are stored in one database table.

  The attributes are stored in their appropriate datatypes as a set of columns in that database table.

• Document content is stored in a separate table.

  The content table stores the physical byte stream for document content as a LOB.

Documents and Folders

In Oracle iFS, documents are stored independently from folders. No single database table contains a folder and its associated documents. Conceptually, picture three separate tables:

• A table that stores documents (actually, one table for attributes and one for content)

• A table that stores folders

• A table that stores relationships between documents and folders

Oracle iFS uses the "reference model" rather than the "containership model." The "reference model" architecture allows multiple folders to include references to the same document, while only one copy of the document is actually stored. (This approach is also known as "multiple parents.") In the "containership model," if three folders contain the same document, there may be three copies of the document.

Connecting to the Repository

Before a program can perform any function in Oracle iFS, the current user must have a working session to provide a connection to the repository. This session allows the application to create and save documents to the repository. Creating this session is the first task of every Oracle iFS application.

Connecting to the repository is a two-step process:

1. Create an Instance of LibraryService.

2. Obtain an Instance of LibrarySession.

LibraryService is a factory class for LibrarySession. That is, LibraryService provides a method you can invoke to create a LibrarySession. The LibraryService.connect() method returns an instance of the class oracle.ifs.beans.LibrarySession. Each instance of LibrarySession represents an authenticated user session. The LibrarySession class provides the method used to create repository objects.

Step 1: Create an Instance of LibraryService

To create an instance of LibraryService, use the LibraryService constructor, which expects no parameters.

LibraryService ifsService = new LibraryService();

Step 2: Obtain an Instance of LibrarySession

To obtain an instance of LibrarySession, use the LibraryService.connect() method. The arguments for the connect() method are a Credential object and a ConnectOptions object, which must be created before invoking connect().

CleartextCredential credentials = new CleartextCredential(username, password);
ConnectOptions connectOpts = new ConnectOptions();
connectOpts.setLocale(Locale.getDefault());
connectOpts.setServiceName(servicename);
connectOpts.setServicePassword(servicepassword);

LibrarySession ifs = ifsService.connect(credentials,connectOpts);

where:

Parameter Name	Datatype	Description
credentials	CleartextCredential	Object containing the user name and password. - username is the Oracle iFS user name. - password is the Oracle iFS user password.
connectOpts	ConnectOptions	Object containing the locale, service name, and service password. - Locale is the standard Java Locale object. - servicename is the name of the Oracle iFS service to which the user is being connected. The properties file is located in the package oracle.ifs.server.properties. The properties file name must be of the form Service.properties. - servicepassword is the database password for the owner of the Oracle iFS schema.

The connect() Method

The connect() method is overloaded to allow Oracle iFS to use other types of credentials to validate Oracle iFS users. If the arguments provided to the connect() method are accepted, connect() returns an instance of LibrarySession.

The most common form of the connect() method, shown above, uses the Cleartext credential manager for user authentication.

Javadoc Reference

For more information about connecting to the repository, see the Oracle iFS Javadoc:

• oracle.ifs.beans.LibraryService

• oracle.ifs.beans.LibrarySession

• oracle.ifs.common.CleartextCredential

• oracle.ifs.common.ConnectOptions

Creating a New Document

Once you have a valid connection, you can create a new document and insert it into the repository.

Creating a document is a two-step process:

1. Create a Document Definition Object.

2. Create a New Document.

The method used to create a new repository object is LibrarySession.createPublicObject. This method expects a single argument, a definition object defining the object that is being created.

A LibraryObjectDefinition object is created using the LibraryObjectDefinition constructor. This constructor expects a single argument, which is a valid LibrarySession object. Instances of LibraryObjectDefinition are transient; they do not map to repository objects. A LibraryObjectDefinition object specifies:

• The class of object being created.

• Initial values for some or all attributes of the new object.

Why Create a Definition First?

In Oracle iFS, you create a Definition object prior to creating any PublicObject.
The Oracle iFS architecture requires that you create the Definition object for reasons of efficiency and speed. The definition object is a transient, in-memory object. Once the object has been created in the repository, the definition object is discarded. By assembling the definition object in its entirety first, before creating the actual document object, you may save many trips to the repository. By creating the definition object, you "build" the object in memory first. Then, when the object is complete, you pass all the attributes in a single database call.

Creating PublicObjects

The PublicObject class is the superclass for all the objects that end users manipulate directly. These objects include both frequently used objects, such as Document and Folder objects, and supporting objects, such as Access Control lists. This topic focuses on creating a Document object by passing a DocumentDefinition to the createPublicObject() method. However, the same process is used for all PublicObjects. For example, to create a folder, you would create a Folder Definition and pass it to the createPublicObject() method.

Create a Document Definition Object

To create a Document Definition object:

1. Create a new instance of DocumentDefinition, passing in the current session.

2. Specify the object's attributes.

Sample: Create a Document Definition Object

DocumentDefinition newDocDef = new DocumentDefinition(ifsSession);

newDocDef.setAttribute("NAME", AttributeValue.newAttributeValue
   ("Hello_World.txt"));
newDocDef.setContent("Hello World");

For more information about setting attributes, see "Setting Attributes".

Create a New Document

To create a new document (or other PublicObject), call the ifsSession.createPublicObject() method, passing the DocumentDefinition as a parameter.

Sample: Create a Document Object

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

Note that the return from the createPublicObject() method is cast to the appropriate object type (in this example, a Document object).

The createPublicObject method() method takes one parameter:

Parameter Name	Datatype	Description
newDocDef	LibraryObjectDefinition	Definition of the attributes of the object that is being created.

Putting a Document in a Folder

By default, new instances of PublicObject and its subclasses, such as Document, are created unfoldered. If you want users to be able to navigate to an object, the object must be foldered, so it is important to folder new documents as soon as they have been created. (Users can use the Find function to find foldered objects only.)

To add an item to a folder, use the Folder.addItem() method, which takes a single argument: the object to be added to the folder. You also need to specify which folder or folders the object should be added to. Frequently, an application requires that a document be placed in a user's home folder. To do this, you need to access the current user's home folder, using the getHomeFolder() method, which is a three-step process:

1. Use theLibrarySession.getDirectoryUser() method to obtain the DirectoryUser object for the current user.

2. Once you have obtained the DirectoryUser object, pass it to the getPrimaryUserProfile() method.

3. Once you have obtained the PrimaryUserProfile object, invoke the getHomeFolder() method on it.

Sample: Putting a Document in a Folder

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

homeFolder.addItem(doc);

Working with Attributes

Working with attributes includes three functions:

• Getting Attributes

• Setting Attributes

• Defining Explicit Getters and Setters

Note that while the standard convention is to call methods that access attribute values "accessor methods" and methods that change attribute values "mutator methods," the more common terms, "getter" and "setter" methods, are used here.

Getting Attributes

In Oracle iFS, you can get attribute values in two ways:

• Using an Explicit Getter Method

• Using the Generic getAttribute() Method

Using an Explicit Getter Method

Explicit getter methods are often provided by the definition object to simplify getting attribute values. If the attribute you want to set has an explicit getter method defined for it, using that method is the easiest and most efficient way to get the value of an attribute.

In the following example, an explicit getter method is used to get the value of Dateofbirth.

Date dob = getDateofbirth();

Using the Generic getAttribute() Method

Generically, the LibraryObject.getAttribute() method is used to get an attribute. The method takes one parameter, the name of the required attribute. This argument should be supplied using the static variable defined in the instance Bean.

The getAttribute() method returns an instance of the class oracle.ifs.common.AttributeValue. The AttributeValue class provides a set of getDataType() methods that return the value of the attribute in the required format. To use the getDataType() methods, you must pass in a valid LibrarySession.

In the following example, the getString() method is used to get the value of Fullname from the AttributeValue object returned by getAttribute().

AttributeValue av = getAttribute(FULLNAME_ATTRIBUTE);
String fullName = av.getString(ifsSession);

Setting Attributes

When you create a Definition object, you can specify initial values for some or all attributes of the new object. In Oracle iFS, you can set attribute values in two ways:

• Using an Explicit Setter Method

• Using the Generic setAttribute() Method

Using an explicit setter method is the simplest approach. However, explicit setters are provided only for tricky attributes. For all other attributes, you must use the generic approach. In the example of creating a DocumentDefinition object, you saw both ways in action:

• Setting the Name attribute required the generic approach, setAttribute().

• Setting the Content used an explicit setter method, setContent().

Using an Explicit Setter Method

Explicit setters are occasionally provided by the Definition object to simplify setting attribute values. If the attribute you want to set has a setter defined for it, using that method is the easiest and most efficient way to set an attribute.

The following sample code demonstrates using an explicit setter method, setDateofbirth().

Date now = new Date();
def.setDateofbirth(now);

Using the Generic setAttribute() Method

Because specific setter methods are not available for all attributes, there is a generic setAttribute() method to fall back on.

To set the value of an attribute, use the LibraryObject.setAttribute() method. This method takes two arguments:

• The name of the required attribute. This argument should be supplied using the static variable defined in the instance Bean.

• An instance of oracle.ifs.common.AttributeValue that contains the new value for the attribute.

To create the AttributeValue object, use the static method AttributeValue.newAttributeValue(). This method is overloaded to allow it to handle each of the possible Oracle iFS datatypes.

Using setAttribute() is a two-step process:

1. Create an attribute object containing the new value of the attribute using the AttributeValue.newAttributeValue() method.

   The newAttributeValue() method is overloaded to handle each of the possible Oracle iFS datatypes.

2. Pass the attribute name and the attribute object to the setAttribute() method.

The following sample code demonstrates the two steps:

AttributeValue av = AttributeValue.newAttributeValue("blue");
setAttribute(FAVORITECOLOR_ATTRIBUTE,av);

As a matter of good coding practice, you can supply the attribute name using a static variable defined in the instance Bean, as demonstrated by FAVORITECOLOR_ATTRIBUTE in the example above.

Both setAttribute() and newAttributeValue() can throw oracle.ifs.common.
IfsException.

Defining Explicit Getters and Setters

It is good programming practice to always provide getter and setter methods for each attribute defined by a custom type. These methods are simply wrappers for the generic getAttribute() and setAttribute() method. When defining explicit getter and setter methods in an instance Bean, access the current LibrarySession using the inherited method PublicObject.getSession().

Sample Code: Defining an Explicit Getter Method

public String getFullname()
  throws IfsException
{
   AttributeValue av = getAttribute(FULLNAME_ATTRIBUTE);
   return av.getString(getSession());
}

public Date getDateofbirth()
  throws IfsException
{
   AttributeValue av = getAttribute(DATEOFBIRTH_ATTRIBUTE);
   return (Date) av.getDate(getSession());
}

Sample Code: Defining an Explicit Setter Method

public void setFullname(String newValue)
  throws IfsException
{
   AttributeValue av = AttributeValue.newAttributeValue(newValue);
   setAttribute(FULLNAME_ATTRIBUTE,av);
}

public void setDateofbirth(Date newValue)
  throws IfsException
{
   AttributeValue av = AttributeValue.newAttributeValue(newValue);
   setAttribute(DATEOFBIRTH_ATTRIBUTE,av);
}

Searching for a Document

To perform a simple attribute-based search of the repository, use an instance of the class oracle.ifs.bean.Selector. The Selector class creates and executes simple searches. That is, Selectors search only one class (no joins are supported).

To perform a search:

1. Specify the search criteria.

   The search selection takes the form of a SQL WHERE clause (without the word "WHERE"). For example, to search based on the Name attribute, use the following criteria:

   NAME_ATTRIBUTE + "= '" + name + "'"
   
   

   To search for Owner or Creator, you need the DirectoryUserID:

   OWNER_ATTRIBUTE + "=" + directoryUser.getId();
   
   

2. Construct a Selector object, passing in the class to be searched and the search criteria.

3. Call the getItems() method to run the query.

Note that instances of this class do not persist, but must be created for each search.

A Selector object is created using the constructor defined in the Selector class. This constructor expects three arguments:

Name	Datatype	Description
session	LibrarySession	Current instance of LibrarySession.
name	String	Name of the class containing the attributes being searched on.
search	String	Search criteria.

The search is performed the first time a method is invoked that accesses the result set.

Specific Search Methods

To specify additional information about the search, use the following methods:

Method	Description
Selector.setRecursiveSearch()	Use to specify that the search should include objects of this class and also objects of its subclasses.
Selector.setSearchSelection()	Use to change the search criteria. This method expects to be passed a single argument that defines the new search criterion.
Selector.setSortSpecification()	Use to control the ordering of search results.

Sample Code: Attribute-based Search

public static void findMatchingFiles(LibrarySession ifsSession, String name)
   throws IfsException
{
   String search = PublicObject.NAME_ATTRIBUTE
                 + "= '" + name +"'";
   Selector mySelector = new Selector (ifsSession, Document.CLASS_NAME, search);
   LibraryObject[] objs = mySelector.getItems();
   int count = (objs == null) ? 0 :objs.length;
   if (count == 0)
   {
     System.out.println("Search did not find any documents.");
   }
   else
   {
     for (int i = 0; i < count; i++)
     {
        Document myDocument = (Document)objs[i];
        String path = myDoc.getAnyFolderPath();
        System.out.println("Found a document at: " + path);
     }
   }
}

Sample Code: Hello World

The following code example demonstrates:

• Connecting to the repository.

• Constructing a new DocumentDefinition.

• Creating a new Document.

• Obtaining the current user's home folder.

• Adding the new Document to the home folder.

• Disconnecting from the repository.

  
  public static void HelloWorld()  throws IfsException
   {
     //Connect to the repository.
     LibraryService ifsService = new LibraryService();
  
     CleartextCredential me = new CleartextCredential(username, password);
     ConnectOptions connectOpts = new ConnectOptions();
     connectOpts.setServiceName(servicename);
     connectOpts.setServicePassword(servicepassword);
  
     LibrarySession ifsSession = ifsService.connect(me,connectOpts);
  
     //Create a new DocumentDefinition and a new Document.
     DocumentDefinition newDocDef = new DocumentDefinition(ifsSession);
     newDocDef.setAttribute("NAME", AttributeValue.newAttributeValue
        ("Hello_World.txt"));
     newDocDef.setContent("Hello World");
     Document doc = (Document) ifsSession.createPublicObject(newDocDef);
  
     //Obtain the user's home folder and add the new Document to it.
     DirectoryUser thisUser = ifsSession.getDirectoryUser();
  
     PrimaryUserProfile userProfile = ifsSession.getPrimaryUserProfile(thisUser);
     Folder homeFolder = userProfile.getHomeFolder();
     
     homeFolder.addItem(doc);
  
     //Disconnect from the repository.
     ifsSession.disconnect();
  }