Oracle Internet File System Developer's Guide Release 1.1 Part Number A75172-04 |
|
This chapter covers the following topics:
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:
The attributes are stored in their appropriate datatypes as a set of columns in that database table.
The content table stores the physical byte stream for document content as a LOB.
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:
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.
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:
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.
To create an instance of LibraryService, use the LibraryService constructor, which expects no parameters.
LibraryService ifsService = new LibraryService();
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:
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.
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
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:
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:
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.
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.
To 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".
To create a new document (or other PublicObject), call the ifsSession.createPublicObject() method, passing the DocumentDefinition as a parameter.
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 |
---|---|---|
|
LibraryObjectDefinition |
Definition of the attributes of the object that is being created. |
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:
DirectoryUser thisUser = ifsSession.getDirectoryUser(); PrimaryUserProfile userProfile = ifsSession.getPrimaryUserProfile(thisUser); Folder homeFolder = userProfile.getHomeFolder(); homeFolder.addItem(doc);
Working with attributes includes three functions:
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.
In Oracle iFS, you can get attribute values in two ways:
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();
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);
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 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:
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);
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:
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:
The newAttributeValue() method is overloaded to handle each of the possible Oracle iFS datatypes.
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.
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().
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()); }
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); }
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:
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();
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 |
---|---|---|
|
LibrarySession |
Current instance of LibrarySession. |
|
String |
Name of the class containing the attributes being searched on. |
|
String |
Search criteria. |
The search is performed the first time a method is invoked that accesses the result set.
To specify additional information about the search, use the following methods:
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); } } }
The following code example demonstrates:
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(); }