1
Getting Started with the Oracle Internet File System SDK

This chapter provides an overview of the requirements for writing an application based on the Oracle Internet File System (Oracle 9iFS) software development kit. You should read this chapter first, then branch out to learn the specifics of different application components and tasks. In addition, Chapter 2, "The Anatomy of Oracle 9iFS", is critical for its detailed overview of the Oracle 9iFS architecture from a developer's perspective. Equally important is Chapter 3, "Java API Overview", which provides an overview of the Java API that is central to Oracle 9iFS applications.

Topics include:

• Development Skills

• Development Roles

• Tools for Oracle 9iFS Development

• Documentation

• Why Choose the Oracle 9iFS SDK?

• The Java API

• Basic and Advanced Development Tasks

• Maintaining Oracle 9iFS Applications

• The Oracle 9iFS Development Environment

• System Configuration Files

• Deploying Your Application

• The Command-Line Utilities Protocol Server (CUP)

• Configuring Your Development Environment

• Oracle 9iFS Application Examples

• Sample Code Provided with Oracle 9iFS

Development Skills

Writing an Oracle 9iFS application requires some combination of the following skills:

Required Skills

1. Installing, configuring, and administering the Oracle9i database. You need to be able to install and manage the Oracle9i database, the repository for the file system. Only basic database administration skills are required, however.

2. Installing, configuring, and administering Oracle 9iFS. Whether you install Oracle 9iFS as part of the Oracle9i database or the Oracle9i Application Server, you also need to be able to install and manage the Oracle 9iFS components. Wherever you install Oracle 9iFS --on the same machine as the database or on a middle-tier machine--is where you will also be hosting many of your application components. Intermediate Oracle 9iFS administration skills are required, particularly when troubleshooting issues during the development process.

3. Programming in Java. Most application components require some Java skill.

Optional Skills

1. Writing XML configuration files. For many application development tasks, such as creating application users or registering parsers, you can write XML configuration files. Editing these configuration files requires knowledge of the XML syntax for 9iFS system configuration.

2. Developing servlets or Java Server Pages. To write a custom web user interface, you need a combination of Java and HTML skills--Java to call the Oracle 9iFS API, and HTML to design the pages that form your web user interface.

3. Querying database contents through SQL. If you want to create a custom view to query the contents of the Oracle 9iFS schema, you need both Java and SQL skills.

4. Performing DDL and DML operations through SQL. If you are embedding your own data definition (DDL), data manipulation (DML), or transaction processing (TPL) operations in your Java code, you need both Java and SQL skills. For more information on this feature, see Chapter 16, "Managing Sessions and Transactions".

Development Roles

Not everyone on your development team needs to master all of these skills, however. As the size of your development team grows, so, too, does the ability for different team members to specialize in different development roles. Some common specializations include:

• Architect. The architect focuses on drafting the list of application components, determining how they interact with one another, application logic, and overall user interface requirements.

• Web user interface designer. The user interface designer may focus exclusively on designing a web user interface without ever writing more than static pages to "dummy" how the user interface will work. Increasingly, user interface designers also need to program in Java to write the functionality behind the user interface.

• Java developer. The Java developer focuses on Java development tasks, such as implementing the beans behind a web user interface or writing an agent.

This division of labor is important for determining which components of the Oracle 9iFS SDK a developer needs to learn. While the architect needs a broad understanding of the SDK and its capabilities, a web user interface designer need only know how the HTTP protocol server works, where to deploy the servlet and JSP code, and how to call the Java API in whatever beans the developer writes.

Tools for Oracle 9iFS Development

To write applications for Oracle 9iFS, we recommend you have the following tools available to you:

• A Java IDE. Since Java code is part of all Oracle 9iFS applications, you need a Java IDE. Oracle JDeveloper is an ideal IDE for Oracle 9iFS development, not only because of the breadth of its development, testing, and deployment features, but also because the Oracle 9iFS application libraries are installed with this tool. Make sure that your Java IDE has a compatible JDK version.

• An XML editor. Whether you are writing XML configuration files, or you are writing an application that works with XML files, an XML editor is also an important tool. Again, Oracle JDeveloper includes the necessary features, in this case, a built-in XML editor.

• A text editor. At times, you may need a text editor to modify the system configuration files that Oracle 9iFS stores externally (in other words, not in the database schema where Oracle 9iFS stores all file system contents, but in the file system where Oracle 9iFS is running).

• The Oracle 9iFS extensions to the Oracle Enterprise Manager (OEM). Both the Oracle 9iFS Manager components and the Oracle 9iFS dashboard are useful tools for application development and testing. The Oracle 9iFS Manager is extremely useful for incremental development, such as creating a new subclass, and then testing the results. The Oracle 9iFS Manager also lets you monitor many application components, such as agents, and provides you with a complete view into all the objects defined and registered in the file system, including custom objects.

• A web authoring tool. If you are designing a custom web user interface, a web authoring tool like Macromedia Dreamweaver is a useful addition to your development arsenal.

• Command-line utilities. These utilities let you execute individual commands through a command-line interface or run setup or cleanup scripts that execute multiple commands.

Documentation

Several important documentation resources are installed with Oracle 9iFS.

Core Documentation

The jumping-off point for the Oracle 9iFS documentation is in the following directory (as measured from Root):

\ifs\doc\9iFS\index.htm 

The Oracle Technology Network

In addition, the Oracle Technology Network (OTN) is a central publishing site for additional technical collateral about Oracle 9iFS and other Oracle products. The Oracle 9iFS section of OTN includes the following:

• Product downloads and documentation.

• Technical briefs, how-to articles on Oracle 9iFS development tasks.

• Sample applications.

• Links to training and other educational materials.

• A discussion group where you can post questions to be answered by the Oracle 9iFS product team and other forum participants.

Related Documents

This guide refers to the following user guides and reference manuals:

Why Choose the Oracle 9iFS SDK?

Broadly speaking, there are several reasons why you might base your applications on this development platform:

1. Pre-built content management components. Many of the content management features--versioning, content-based searching, extensible metadata, check-in/check-out, locking--used in a wide array of applications are pre-built, re-usable components in Oracle 9iFS, saving you the time needed to write and test these pieces.

2. Database storage. Since Oracle 9iFS uses the Oracle9i database as its repository for the file system, the features and capabilities that the database provides--for example, scalability to terabytes of content and thousands of users--are also available to anyone using Oracle 9iFS. Storing content in the database also lets Oracle 9iFS and your applications use database features like Oracle Text, the text indexing and retrieval engine in the Oracle9i database.

3. Server-side logic. To enforce business rules or application logic, you need to create server-side intelligence that is currently not built into other file systems. While such server-side logic is difficult (if not impossible) to implement on other file servers, it is relatively easy to implement on Oracle 9iFS.

4. Built-in protocol access to the same content and server-side application components. Oracle 9iFS comes with several protocol servers--SMB, HTTP, WebDAV, FTP, NFS, and IMAP4--that all provide access to the same files and folders. The same application logic will apply to file system operations (insert, delete, update, and so forth), regardless of the protocol used to access the server.

5. Parsing and rendering of content. Oracle 9iFS includes in its SDK a generic parsing and rendering framework.

6. XML capabilities. Because of the popularity of XML as a structured data format, Oracle 9iFS also includes a default XML parser and renderer, plus XML features like DTD validation.

7. Heterogeneous file data. Oracle 9iFS was designed to store any type of file, including content normally stored in separate kinds of repositories (for example, XML and e-mail).

8. Files and relational data. Since the database is the repository for the file system, Oracle 9iFS makes it possible to write applications that easily bridge these two worlds, while at the same time simplifying both development and administration by storing both types of content on the same server.

9. A standards-based SDK. Since the Oracle 9iFS SDK requires only Java and, perhaps, XML, HTML, or SQL to use, you can use the skills you have already acquired in programming in these languages.

10. Complete transparency to end users. Last of all, the file system looks and acts like any file server that your users already know. Therefore, all their applications work automatically with Oracle 9iFS, and they do not need to learn any special skills to connect to the server via any of the network protocols.

Customizations or Applications?

Development with the Oracle 9iFS SDK can run the gamut from customizing how the file system behaves or presents data in particular instances to complete applications with their own set of custom user interfaces, application logic, and other components. In other words, a single development project can range from the very small to the very large, depending on your objectives.

A customization builds on Oracle 9iFS as a file server. It may change file system behavior in some circumstances (for example, changing the way the delete operation works (see Chapter 17, "Customizing Content Type Behavior"), or it may change how the system presents data to the user (for example, by implementing a custom renderer for some types of XML content). However, the point of this kind of development project is to modify the file server, not to replace it.

In contrast, many large-scale applications do away with the "file server application" altogether. These applications may only run one or two protocol servers (generally HTTP for web application access and, perhaps, FTP for mass upload and download of content). The authors of these applications want the Oracle 9iFS SDK more than they want the file server, since they can then easily work beyond the assumptions that the protocol servers need to follow.

This manual is written for both types of developers: those interested in customizations, as well as those who want to build applications that may or may not use the Oracle 9iFS protocol server and the out-of-the-box web interface.

How Many Applications?

One of the chief advantages of the Oracle 9iFS SDK is the ease with which you can develop and host multiple applications on the same server. The same content, consolidated on a single Oracle 9iFS server from multiple legacy file servers, can be the target of multiple applications and customizations. For example, files that were managed by a digital asset management system written for Oracle 9iFS can then be staged for your web site through a web content management system deployed on the same file server.

The Java API

The single most important aspect of the Oracle 9iFS SDK you can learn is the Java API. Since Oracle 9iFS is written in Java, the object hierarchy behind this file system is exposed to you, the developer. All the objects that form the file system -- documents, folders, users, groups, attributes, and so forth -- exist as Java objects. These standard classes include methods that you can call in your Java code.

Before writing any Java code, you should review the API overview chapter in this manual. Successful development with the Oracle 9iFS SDK depends on understanding not only individual Java objects, but also how these objects relate to one another. For example, a user in Oracle 9iFS terms actually consists of a DirectoryUser object as well as other Java objects. To learn about the Java API, see Chapter 3, "Java API Overview".

Basic and Advanced Development Tasks

This manual classifies development tasks into basic and advanced. Basic tasks are those that you are most likely to perform when writing Oracle 9iFS applications, such as subclassing. Basic tasks often require less technical expertise to perform. Advanced tasks, in contrast, are both less common and more demanding.

Table 1-3 summarizes basic and advanced Oracle 9iFS development tasks:

Maintaining Oracle 9iFS Applications

A single Oracle 9iFS system may be home to several customizations and applications. You therefore need to back up both the file system contents and your application components.

• File system contents. Regardless of the applications you have deployed, you need to be able to recreate the file system, including its contents (files and folders) as well as the users, groups, ACLs, and other pieces that define it. For information on using the Oracle 9iFS Import/Export Utility, see Chapter 7, "Migrating, Backing Up, and Restoring Data," in the Oracle Internet File System Setup and Administration Guide.

• Application components. Since several application components, such as agents and parsers, are stored in the file system along with other Oracle 9iFS components, you need to back up these files as well as the contents of the database.

Because you may need to re-create the application components on an Oracle 9iFS instance, or you may need to install the same application on multiple middle-tier machines. We strongly recommend that you script the installation of your application components. Scripts can deploy components on the file system where Oracle 9iFS is running. They can also insert components into Oracle 9iFS, both through standard protocols, like FTP, as well as the special protocol, CUP.

The Oracle 9iFS Development Environment

Chapter 2, "The Anatomy of Oracle 9iFS" provides a complete overview of the Oracle 9iFS architecture. However, this section quickly summarizes the components of an Oracle 9iFS application, as well as provides advice on when to use each type of component.

Oracle 9iFS Application Components

An Oracle 9iFS application can consist of some or all of the following components. The skills needed to write and deploy each component are noted for each application component.

• Standard classes. You can extend the standard classes (for example, PublicObject, DirectoryUser) that define Oracle 9iFS by adding new attributes to them.

• Custom classes. More frequently than extending standard classes, you will create subclasses of these standard classes.

• Parsers. Parsers perform processing before inserting or updating a document. For example, a common use of a parser is to extract the contents of a file and externalize them as Oracle 9iFS attributes.

• Renderers. A renderer changes the stream for a file or folder request, effectively changing how the file or folder appears to the end user.

• Agents. An agent is a process that can either respond to an event or check at regular intervals to see if a particular system condition exists (for example, a new file has appeared in a folder) to which it needs to respond.

• Overrides. An override effectively changes the processing that a method on a standard class (for example, AddItem() on a folder) performs when invoked.

• Custom web user interfaces. A custom web user interface can either enhance or replace the web user interface provided with Oracle 9iFS. You can use either servlets or Java Server Pages (JSPs) to write a custom web user interface.

Which Component to Use?

Just looking at the previous list, however, may not make it immediately obvious which components you need to use when performing a particular task. Table 1-4 summarizes the components needed to achieve common development goals:

Your development project may include only some of these components.

System Configuration Files

Oracle 9iFS uses two types of system configuration files:

1. Files stored in the external file system. These plain text files use a proprietary format (.ADM and .DEF) for storing configuration settings. Generally, these files determine how the protocol servers and other Oracle 9iFS application components run; they do not customize the object hierarchy in Oracle 9iFS. These files are stored in the /settings subdirectory of the directory in which Oracle 9iFS is installed.

2. XML files inserted into Oracle 9iFS. These files must follow a specific syntax that the Oracle 9iFS XML parser understands. These files often create or modify objects in the Oracle 9iFS SDK, such as setting the attributes on a folder or creating a new user.

Note that Oracle 9iFS now stores less configuration information in the file system where the Oracle 9iFS application components are installed than in previous versions of the Oracle Internet File System. For more information on configuring Oracle 9iFS, see the Oracle Internet File System Setup and Administration Guide.

Which Tool for which Component?

As you can see, whenever you perform a development task, you frequently can choose among writing Java code, creating an XML configuration file, or using the Oracle 9iFS Manager to perform the customization. However, you cannot use all three of these tools for all development tasks. In many cases, your choices may be limited to one or two of these tools.

Table 1-5 summarizes the tools available for developing each of these application components.

Deploying Your Application

Once you develop your application components, you need to deploy them. Table 1-6 summarizes where you store these components:

In Table 1-6, the entry File system under Where deployed means that you deploy the application component in the same file system where Oracle 9iFS is deployed. The required and recommended directories are subdirectories of the directory where Oracle 9iFS is installed. The entry, Oracle 9iFS, on the other hand, means that you can deploy the application component by inserting it into Oracle 9iFS (for example, by uploading an XML file through FTP).

As you can see, the /custom_classes directory is designed for storing Java application components. You can deploy these components in a different directory; however, you may then need to modify your CLASSPATH settings to include this additional directory. For more information on setting the CLASSPATH, see "CLASSPATH Configuration".

Restarting After Customization

Deploying an application component may require restarting the Oracle 9iFS server processes. Oracle 9iFS maintains several caches which may not be immediately refreshed when you deploy one of these components. Additionally, changes to system settings may not apply until you have restarted the protocol servers. For instructions on starting and stopping the Oracle 9iFS Java processes (the repository, protocol servers, and agents), see Chapter 2, "Administering an Oracle 9iFS Domain, in the Oracle Internet File System Setup and Administration Guide.

Table 1-7 summarizes whether you need to restart any Oracle 9iFS processes after deploying an application component.

The Command-Line Utilities Protocol Server (CUP)

Oracle 9iFS includes a special protocol server, CUP, designed for both administrators and developers to use. Through CUP, you can invoke many Oracle 9iFS commands, such as viewing extended attributes, that are not part of FTP or other protocol servers. CUP is useful both when you do one-off prototyping tasks as well as executing scripts to deploy or update application components.

For information on running CUP, see Appendix A: "Command Line Utilities Reference," in the Oracle Internet File System Setup and Administration Guide.

Configuring Your Development Environment

General Configuration

When writing any Java code for Oracle 9iFS, you need to edit your JDK and JRE settings to work with the Java class archives (.JAR files) required for Oracle 9iFS development. Table 1-8 summarizes the required settings:

java.sun.com/products/jdk/1.2/docs/tooldocs/solaris

java.sun.com/products/jdk/1.3/docs/tooldocs/solaris 

java.sun.com/products/jdk/1.2/docs/tooldocs/win32

java.sun.com/products/jdk/1.3/docs/tooldocs/win32

java.sun.com/products/jdk/1.2/docs/tooldocs/tools.html

java.sun.com/j2se

CLASSPATH Configuration

You also need to set some specific elements of the CLASSPATH used by the JDK and JRE:

JDK/JRE Certification

Note that the Oracle 9iFS SDK is certified for use with only specific versions of the Sun JDK and JRE. For a list of the certified versions, consult Chapter 2, "Preinstallation," of the Oracle Internet File System Installation Guide. You should also consult the release notes for any updates to JDK/JRE certification.

Oracle 9iFS Application Examples

To illustrate the different components of the Oracle 9iFS SDK in action (and to help you scope your own projects), here are four sample applications. Note that we have provided some examples of the sorts of implementation decisions a developer might take with these sorts of applications. By no means are these decisions the only ones possible; in fact, the flexibility the Oracle 9iFS SDK gives you when making these sorts of implementation decisions is one of the great strengths of this platform.

Notifying Users of Changes

Suppose your users want to have a special directory in Oracle 9iFS for shared documents. Whenever the contents of the directory change (in other words, when someone adds, deletes, or updates a file), the users want to receive an e-mail notifying them of the change.

From an Oracle 9iFS perspective, this is a relatively simple application. To create this functionality, you can tap into the agent framework for Oracle 9iFS, adding a new agent that maintained a list of the directory contents, regularly checks to see if the contents had changed, then notifies the members of the e-mail list when it detects a change.

Writing the application would entail the following steps:

1. Create the Oracle 9iFS users. Assuming these users were not already defined as Oracle 9iFS users, you first need to create them through the Oracle 9iFS Manager (an extension to the Oracle9i Enterprise Manager administrative interface) or through XML configuration files. Actually, the users who receive the e-mail need not be Oracle 9iFS users at all: the agent can use the Oracle 9iFS SMTP server to send an e-mail to any mail server. The users then need to access the directory in Oracle 9iFS through the guest account if they do not have their own 9iFS accounts.

2. Write the agent. The agent is a Java application that makes calls to the Oracle 9iFS Java API. In this case, the agent calls the API to review the contents of the directory and compare the current contents to a file listing the original contents.

3. Deploy the agent.

4. Register the agent.

5. Make sure the SMTP process is running.

6. Change the security on the directory to ensure that no one can delete it.

Content Management System

Your company wants to implement an internal web site. However, it does not want the overhead of an expensive, difficult-to-maintain web content management system. Instead, it would rather build a simple application on top of the file server that everyone shares. The company also wants to keep a careful eye on this project, since it has other kinds of content management applications planned for the future.

The point of the content management system is to author and stage content in Oracle 9iFS. The application could publish the web site in place, simply by changing the access control list (ACL) for all the site's content to Published, thereby making it world-readable. Some web site administrators might prefer, on the other hand, to stage the web site in Oracle 9iFS, then copy the staged content to a live web server.

Whichever approach the development team and the web site administrator choose to take, implementing this application looks largely the same:

1. Define the category needed to track the status of content for the web site.

2. Create the directories used to stage content.

3. Create the Review sub-directory under every user's Home directory.

4. Write the agent that links content for review to a user's Home directory/

5. Write the beans behind the web user interface.

6. Design the web user interface.

7. Convert the HTML pages into either Java Server Pages (JSPs) or servlets.

XML-Based Insurance Claim System

A hypothetical insurance company has made the decision to standardize all insurance claims as XML files. Each claim conforms to an industry-standard DTD (Document Type Definition), so all elements are well understood. What is critical about this switch to XML is the opportunity to mine the XML for business intelligence. However, the analysis tools the company uses are written for relational data, not for XML. Fortunately, through parsing, Oracle 9iFS presents a way to convert file-based XML content into relational data.

Implementing this insurance claim system requires the following steps:

1. Create a subclass based on the DTD. The subclass includes a document attribute corresponding to each element from the XML file you want to parse.

2. Decide whether you want to validate XML content based on the DTD. See Chapter 10, "XML and the Oracle Internet File System" for details on how to enable DTD validation.

3. Associate this subclass with the XML parser.

4. Design a JSP for viewing the XML on the web.

5. Write the beans behind that the JSP calls.

6. Associate the subclass with the main JSP.

7. Create a custom view based on the parsed XML content. The view joins the content in the base table used to store all documents and their common attributes, ODM_DOCUMENT, as well as the table Oracle 9iFS created to store the parsed attributes.

Additional features for this application are easy to imagine. For example, you might write an agent that looks at the total dollar amount of each claim and alerts investigators about any claims over a specific amount. The XML content might be rendered in a more human-readable form for users accessing it through a web application.

Document Repository

A document repository needs only a few extra features above what Oracle 9iFS provides out of the box. A sample document repository might need categories (for example, BookInformation, JournalInformation, and so forth). Users may be required to enter settings for these categories' attributes before other users can see the files they have uploaded. You may want to design a custom search web page that combines content-based searching with category searches. Other web pages would let you browse categories and see all files that fall under a particular setting (for example, all books that are Westerns).

This project requires following steps:

1. Define the categories for use in the document repository.

2. Develop an agent that sets the ACL for a file to Private (in other words, visible only to that user) until the user who uploaded the file enters the required attribute settings. The same agent would then set the ACL to Published, making it world-readable.

3. Build the custom web user interfaces needed to perform content and category searches.

Changing the Way Delete Works

In many organizations, document retention requirements or other business rules make it necessary to prevent users from ever actually deleting a file. In the most extreme examples, every version of every file needs to be somehow maintained, so that regulatory agencies can completely reconstruct a paper trail if necessary. In others, an administrator or manager needs to review a document first before it is purged from the system, but the document doesn't necessarily need to be stored in perpetuum.

Clearly, this requirement--effectively changing how the delete operation works in a file system--is no small feat in a standard file system. In Oracle 9iFS, however, modifying the delete operation requires a single override to complete.

Sample Code Provided with Oracle 9iFS

For your reference, the Oracle 9iFS product installation includes a directory, /Samples, that includes a large amount of sample code. In addition, throughout this manual, you will see inline examples of Oracle 9iFS Java and XML code.

Table 1-10 summarizes the sample code located in the Samples subdirectory of your Oracle 9iFS installation. Note that the Utilities classes cited are helper classes used in other examples, so you may need to review both the helper class and its associated classes to fully understand how the example works.

Note that these examples are for your edification only. They are not designed to be actual reusable application components.

Running the Examples

If you want to run these samples, execute GlobalSetup.java first. After you have finished, execute GlobalCleanup.java to return Oracle 9iFS to its state before running the examples.