print Printer View e-mail E-mail this page Bookmark Bookmark
Oracle CM SDK Web Starter App II Readme

Oracle CM SDK Web Starter Application II

This Readme contains the following sections:

I. Overview

The Oracle CM SDK Web Starter Application II is a sample application developed by the Oracle CM SDK team.

This sample application is based on the original Oracle CM SDK Web Starter Application. The Web Starter Application II includes all the functionality of the original Web Starter Application, plus several additional features, including:

  • Support for versioned files
  • Assignment of access levels
  • Assigning keywords to documents
  • Searching based on those keywords

In addition, it has been developed using STRUTS, a standard Web application framework. The Web Starter Application II is ideal as a starting point for Oracle CM SDK custom development.

This sample application is intended as a tool to help developers understand the challenges of building a Web application using Oracle CM SDK. It also provides example solutions to common issues.

This sample application is not intended to teach Web application development, or the CM SDK API. To learn more about the CM SDK API, refer to the oracle.ifs.examples.api package.

The Web Starter Application II is provided as sample code and may not be of production quality in all concerns. Where appropriate, however, accepted practices and proven design patterns have been followed. The following design goals were kept in mind:

Design Goals

  • Use standard technologies
  • Use a standard Web application framework
  • Modular design
  • Reusable
  • Extensible
  • Scalable
  • Keep the example as simple as possible
  • Separate user interface code from business code
  • Minimize Java code in JSPs
  • Demonstrate how to support multiple languages
  • Demonstrate ADA compliance
  • Use simple HTML and minimal Javascript to avoid browser issues

The Web Starter Application II provides the following basic functionality:

Basic Functionality

  • Establishes a user session
  • Lists the contents of a folder
  • Drills down into a folder, displaying its contents
  • Navigates up to a parent folder
  • Uploads files into a folder
  • Creates a folder
  • Uses a doc servlet to display the contents of a document
  • Searches for documents and folders by name, content, keywords, and starting folder (folder restricted query)
  • Renames a document or folder
  • Moves a document or folder
  • Copies a document or folder
  • Modifies the description on a document or folder
  • Disconnects a user session
  • Makes a document versioned
  • Checks out a versioned document for exclusive write access
  • Checks in a checked out document
  • Cancels a checkout, reverting to the previous version
  • Views a versioned document's history
  • Sets access privileges on documents and folders
  • Looks up Access levels via a list of values page
  • Assigns keywords to documents or folders

II. Common Web Application Issues

Minimize Browser Issues

One common problem with Web applications is inconsistent behavior caused by various browsers and browser versions. Keep the user interface basic and use simple HTML controls to minimize these type of issues. In this sample application:

  1. No Frames are used
  2. No Dynamic HTML is used
  3. No modal dialog windows are used
  4. Standard HTML controls are used
  5. There is only a minimal use of Javascript
  6. Most browsers should work, but Microsoft Internet Explorer v6.028 was used for testing

Application State

HTTP is a stateless protocol, but most Web applications need to keep application state. The Java Servlet API provides a way to store application state in the HTTP Session. Application state and each page's state are stored in the HTTP Session using the Java Servlet API.

  1. A logon bean is stored upon successful logon. This allows actions to easily check to make sure the user has successfully logged on and their session has not timed out.
  2. Support for multiple browser windows is accomplished by having a unique key for each open browser window that is passed between pages. Each HTML page has its own unique key. The combination of the browser window key and the HTML page key is used to store a window's state. This avoids sub windows having to know about who called it and what data to send back.

User Logged On Check

Many Web applications require user authentication and should check on each request if the user is logged on.

  1. The logon bean stored in the HTTP Session is used to check if the user has logged on successfully and whether it is still valid, as it will timeout without activity.
  2. The FileAction class, a base Action class, verifies that a user is logged on. All actions that extend this class inherit this behavior. The logon action overrides this check since its function is to log a user on.

Internationalization and Localization

In order to support multiple languages and character sets:

  1. Use UTF8 encoding because it supports multibyte character sets.
  2. Specify UTF8 in JSPs header directive to create the pages using UTF8.
  3. Specify UTF8 in the controller servlet when processing a request.
  4. Put all localizable strings in a resource file for easy translation. Struts provides a string resource file ApplicationResources.properties, and tags that will get these strings for JSPs.
  5. Get the language to use from the browser via the request header.
  6. Build the Locale from the language, for display formatting (for example, dates).
  7. To see Localization work, do the following:
    • Create a copy of ApplicationResources.properties
    • Translate it to another language, naming the file appropriately (for example, ApplicationResources_es.properties for Spanish)
    • Put the file in the classpath
    • Set your browser preference to use that language (for example, es)
    • Logon

Application Flow

Web applications often require frequent changes. To help facilitate this, avoid hard coding URLs in both pages and Actions that handle requests.

  1. STRUTS provides a way for pages to use logical mappings, avoiding hard coding URLs; the logical mappings are stored in struts-config.xml.
  2. STRUTS provides for Actions to use logical outcomes, avoiding hard coding of URLs; the logical outcome mappings are stored in struts-config.xml.
  3. STRUTS provides struts-config.xml to define what form fields should be captured from a request.

Separate User Interface Logic

To promote reusability and maintainability, keep user interface logic separate from business logic.

  1. STRUTS provides the Action class to handle user events.
  2. STRUTS provides a tag library for standard user interface logic.
  3. A custom tag library is provided as part of this application.
  4. Bean user interface helper classes were developed.
  5. Model-specific code is located Model package.

Back Button Issues

Using the back button can have unexpected results.

  1. STRUTS provides for the generation and expiration of tokens to help address back button issues.
  2. No back button code is used in this application.
  3. Browser versions may affect back button behavior.

Reusable Windows

Creating pages that can be called from multiple places to perform some function and return to the caller can be useful.

  1. The following are reusable windows:
    • properties.jsp
    • listOfValues.jsp
    • selectFolder.jsp
    • checkIn.jsp
  2. A form field, returnToCallerForward, specifies the logical outcome for a reusable window and is specified by the calling window. This maps via struts-config.xml back to the calling page.

Handling Large Result Sets

Web applications should handle large result sets.

  1. Results should be displayed one page at a time.
  2. Use drop down lists carefully, because they do not scale.
  3. Use a list of values feature for picking a value from a large set.
  4. Provide a way to filter results.
  5. Provide searching as a way to limit results.

Logging

Web applications should support logging. In this sample application:

  1. Oracle CM SDK standard node logging is used.
  2. Standard servlet logging is used in development standalone mode.

User Interface Styles

This sample application provides support for customizable User Interface Styles.

  1. HTML is linked to the CSS style by use of the class attribute.
  2. User interface style is defined by CSS style sheets.
  3. The file webstarterapp.css contains the style sheet actually used.
  4. To change the style, edit the file webstarterapp.css. Two additional style sheets have been provided as examples.

Developer Features

These features are provided for development, not production, environments.

  1. Debug mode is provided via a servlet configuration property in the web.xml file. It provides extra messages to help find problems.
  2. Debug messages are sent to System.out or to the log via a servlet configuration property in the web.xml file.
  3. Standalone mode allows the application to be run outside the Oracle CM SDK domain environment. This eliminates creating OC4J instances, HTTP nodes, and Oracle CM SDK server configuration.
  4. The application can be run from JDeveloper using its embedded OC4J server.
  5. A display object page is accessible via .../displayObject.do?poPath=:docid or displayObject.do?poPath=/path

 

III. Application Specifics

Application Components

The Web Starter Application II consists of the following parts:

  1. A controller servlet that gets all requests and dispatches to the appropriate Action
    • WebStarterAppServlet is the controller servlet
  2. An Oracle CM SDK server that interfaces with the Oracle CM SDK repository to get connections
    • WebStarterAppServer is the Oracle CM SDK server
  3. Actions that handle specific requests, and forward/redirect to a View
    • There are 32 Action classes. Their names end with "Action."
    • Examples are:
      • BrowseDirectoryAction - displays a directory at the provided path
      • LogonAction - logs a user into the system
      • DeleteAction - deletes the specified items from the specified directory
  4. Views via JSPs display the user interface
    • There are 21 JSPs
    • Examples are:
      • browseDirectory.jsp - displays a directory's contents
      • copy.jsp - copies items from one folder to another
      • delete.jsp - deletes items from a folder
  5. JSP tag classes for JSPs to use
    • There are twelve custom tags classes. Their names end with "Tag."
    • Examples are:
      • LoopTag - loops through a collection of PublicObjects
      • AttributeTag - displays an attribute of a PublicObject
      • MultiPageTag - displays links to pages for a multipage result set
  6. Helper classes to pass data from the action to the view via the request
    • There are two helper classes:
      • CollectionBean - holds a collection of PublicObjects
      • LogonBean - used to store the user's Oracle CM SDK session in the HttpSession
  7. Utility classes for various functions
    • There are five Utility classes:
      • Constants - defines constants like http parameter names
      • HttpUtils - helper methods to address issues like localization
      • IfsUtils - centralizes Oracle CM SDK-specific calls
      • StringResourceUtils - helps with String resources
      • VersionUtils - contains generic version operations
  8. Utility Public Object classes
    • There are eight Utility Public Object classes. These classes define the file operations behavior based on whether the source and/or destination file is versioned. A factory is used to return the correct class that implements the UtilsPublicObjectInterface. This allows the caller to have no versioning code. This helps modularize the versioning code in a single set of objects, and simplifies the logic by having separate small classes for each case:
      • UtilsPublicObjectInterface defines the interface a UtilsPublicObject must implement
      • UtilsPublcObjectFactory returns the correct implementation
      • UtilsPublicObject handles non-versioned objects no collision
      • UtilsVersionObject handles versioned objects no collision
      • UtilsNonVersionedToNonVersioned handles non-versioned collision with non-versioned
      • UtilsNonVersionedToVersioned handles non-versioned collision with versioned
      • UtilsVersionedToNonVersioned handles versioned collision with non-versioned
      • UtilsVersionedToVersioned handles versioned collision with versioned
  9. Resource files used for localization
    • ViewController/src/resources/ApplicationResource.properties - localizable application strings
    • Model/src/Resources/StringResources - localizable model strings
  10. Images used by the application
    • brand.gif - branding images
    • default.gif - default document gif for a folder item
    • folder.gif - icon for a folder
    • gb-logout.gif - logout button
    • lov.gif - list of values button icon
    • oraclelogo.gif - Oracle Corporation gif
    • checkin_disabled.gif icon for disabled check in
    • checkin_enabled.gif icon for enabled check in
    • checkout_disabled.gif icon for disabled check out
    • checkout_enabled.gif icon for enabled check out
    • eyeglasses_24x24_transparent.gif icon for properties page link
    • makeversioned_disabled.gif icon for disabled make version link
    • makeversioned_enabled.gif icon for enabled make version link
    • reverseicon_disabled.gif icon for disabled cancel checkout link
    • reverseicon__enabled.gif icon for enabled cancel checkout link
    • revisionhistory_disabled.gif icon for disabled version history link
    • revisionhistory__enabled.gif icon for enabled version history link
    • versioned.gif icon for versioned documents
  11. A servlet to display the contents of documents, named DocServlet
  12. A Style sheet used to control html style
    • The style sheet is:
      • /styes/webstarterapp.css
    • Additional style sheets are provided as example alternate styles
      • webstarterappPurple.css - same as webstarterapp.css initially
      • webstarterappBlue.css - example alternate style
      • webstarterappOra.css - example alternate style

Application Flow

  1. A JSP sends a request to the Controller servlet specifying an action.
  2. STRUTS translates a logical link to the real URL via struts-config.xml.
  3. STRUTS extracts form fields into a JavaBean.
  4. The Controller servlet instantiates an action, and gives the action both the request and the filled-in Javabean.
  5. The action verifies data, does processing, adds to the request, and forwards/redirects to a logical forward.
  6. STRUTS translates the logical forward to a real forward via struts-config.xml. The forward is to another action or a JSP.
  7. The JSP calls Tags to determine dynamic content and to format content.
  8. The browser displays the page and the cycle repeats.

IV. Deploying the Application Manually

This sample application does not come already deployed.

Below is an example of how to deploy the Oracle CM SDK Web Starter Application II manually. You can use these steps as a guide to deploy your own custom Oracle CM SDK application. The steps are essentially the same as for the original Web Starter App, except for the fact that the IFS.SERVER.Class Server Property needs to be changed.

There are four main steps to manually deploy an Oracle CM SDK Web application. These are:

  1. Creating a new HTTP node
  2. Creating an OC4J instance
  3. Deploying the custom application
  4. Restarting the Oracle CM SDK domain and OC4J instance and accessing the application

Once these steps are completed, you should be able to access the test application. The steps below show how to accomplish this using the Oracle Enterprise Manager Application Server Control. Note that you must already have a working installation of Oracle CM SDK.

Creating a New HTTP Node

  1. Access the Oracle Enterprise Manager Application Server Control (http://hostname.domain:1810)
  2. Enter the Application Server Control administrator username and password (ias_admin/ias_admin password).
  3. Navigate to the Application Server Instance where Oracle CM SDK is installed.
  4. The Oracle CM SDK domain and the Oracle CM SDK OC4J instances are displayed. For example:
    • Content Management SDK (my_cmsdk_schema) for the Oracle CM SDK domain in 10g (9.0.4)
    • iFS_myhost:1521:myhost.us.oracle.com:MY_SCHEMA for the Oracle CM SDK domain in Release 2 (9.0.3)
    • OC4J_iFS_cmsdk for the Oracle CM SDK HTTP node
  5. Click the Oracle CM SDK domain link.
  6. Click Server Configurations under the Configuration heading.
  7. Select HttpAdminServerConfiguration and click Create Like.

    8. Enter the following information for the HttpAdminServer:

    • Name: TestWebStarterAppServerConfig (Note: Any name can be entered)
    • Access Control: Private
    • Leave Abstract unchecked
    • In the Properties section, remove all except IFS.SERVER.Class and IFS.SERVER.SESSION.User
    • Edit the IFS.SERVER.Class property to have the value model.WebStarterAppServer
    • The properties section should then look like:
      • IFS.SERVER.Class = model.WebStarterAppServer
      • IFS.SERVER.SESSION.User = system
  8. Click OK to save the TestWebStarterAppServerConfig Server.
  9. On the Server Configuration page, click the Domain link at the top of the page to return to the Oracle CM SDK Home page.
  10. Click Node Configurations under the Configuration heading.
  11. Select the current HTTP node and click Create Like.

    12. Enter the following information for the HTTP Node:

    • Name: TestHttpNode (Note: Any name can be entered)
    • Select Active.
    • In the Servers section, select HttpAdminServerConfiguration and click Remove.
    • In the Servers section, click Add. Enter the following on the Add Server page:
      • Name: WebStarterAppServer
      • Configuration: TestWebStarterAppServerConfig
      • Service: IfsDefaultService
      • Initial Priority: 5
      • Select Active and Initially Started
      • Select OK.
    • Select OK on the New Node Configuration page.

Creating an OC4J Instance

  1. On the Application Server Home page in the Application Server Control, click Create OC4J Instance.
    • Enter the OC4J Instance Name: TestInstance
    • Click Create.
  2. On the Oracle CM SDK middle tier, navigate to ORACLE_HOME/j2ee/TestInstance/config/oc4j.properties.
  3. First, create a backup of the oc4j.properties file. Then add the following lines:

    IFS.DOMAIN.NODE.IfsHome=ORACLE_HOME/ifs/cmsdk
    IFS.DOMAIN.Name=ifs://db_host:db_port:db_service:cmsdk_schema
    IFS.DOMAIN.NODE.Name= TestHttpNode

    IFS.DOMAIN.NODE.OracleHome=ORACLE_HOME/

    Note: These lines can be found in ORACLE_HOME/j2ee/OC4J_iFS_cmsdk/config/oc4j.properties. Copy over these four lines into the oc4j.properties of the TestInstance and then change the IFS.DOMAIN.NODE.Name to match the TestHttpNode that you created.

  4. Save the file.
  5. On the Oracle CM SDK middle tier, navigate to ORACLE_HOME/opmn/conf/. In this directory, you will find a file called opmn.xml. Make a backup of this file before proceeding.
  6. Scroll down to the bottom of this file and locate the OC4J_iFS_cmsdk entry. Copy the following environment section from OC4J_iFS_cmsdk to the TestInstance section:

    <environment>
      <prop name="PATH" value="E:\Portal90201\bin"/>
      <prop name="NLS_LANG" value=".UTF8"/>
    </environment>
  7. Save the opmn.xml file.
  8. Stop and restart the Process Manager (OPMN).

    For Windows: In Services, restart your %ORACLE_HOME%ProcessManager

    For UNIX: Use the following commands:

    • opmnctl stopall
    • opmnctl startall

Deploying the WebStarterApplication to the TestInstance

  1. From the Application Server Home page in the Application Server Control, click the TestInstance link.
  2. Click Deploy EAR File, then click Next.
  3. On the Select Application page, enter the following values:
    • J2EE Application: The location of the WebStarterApp EAR file
    • Application Name: TestWebStarterApp (Note: You can select any name you wish)
  4. Click Next.
  5. On the URL Mapping for Web Modules page, take the default of /webstarterapp (Note: Any name can be entered.)
  6. click Finish and then click Deploy.

Restarting the Oracle CM SDK Domain and OC4J Instance and Accessing the Application

  1. Return to the Application Server Home page in the Application Server Control.
  2. Select the Oracle CM SDK domain link. For example:
    • Content Management SDK (my_cmsdk_schema) in 10g (9.0.4)
    • iFS_myhost:1521:myhost.us.oracle.com:MY_SCHEMA in Release 2 (9.0.3)
  3. Click Start Local Components. Enter the OS Administrator username and password and click OK.
  4. Return to the Application Server Home page. Select TestInstance and click Restart.
  5. In a new browser window, enter the following URL:

    6. http://hostname.domain:port/webstarterapp

    Then, enter an Oracle CM SDK username and password.

Setting Up Development Environments Using Oracle JDeveloper Embedded OC4J Server

This section describes the following scenarios:

Setting Up a Development Computer, Single Stack

  1. Install Oracle Application Server.
  2. Install and configure Oracle CM SDK, creating an Oracle CM SDK domain, OC4J instance, and other components.
  3. Install Oracle JDeveloper.
  4. Extract the webstarterapp.ear file.
  5. In JDeveloper:
    • Create a new project using the webstarterapp.war file from the webstarteapp.ear file.
    • Under Project Properties > Libraries:
      • Create a new Library pointing to iasHome/ifs/cmsdk/lib/cmsdk.jar
      • Create a new Library pointing to iasHome/jlib/uix2.jar
      • Create a new Library pointing to iasHome/jdbc/lib/classes12.jar
      • For Oracle CM SDK 10g (9.0.4), create a new Library pointing to iasHome/jlib/emPid.jar

        Note: Windows users should use backslashes when specifying path names.

    • Compile the project.
  6. Using the Application Server Control:
    • Create a ServerConfiguration for the WebStarterAppServer.
    • Create a new HTTP node.

      • Note: See the section in this document Creating an OC4J Instance for details.

  7. In Oracle JDeveloper:
    • Under Project Properties > Runner, set the virtual machine Java options:

      -DIFS.DOMAIN.Name=your_domain -DIFS.DOMAIN.NODE=yourNodeName

      • Notes:

      • Optionally turn off compile before running (Project Properties > Runner > Options).
      • Set default run target to index.jsp.

  8. Test
    • In the Application Server Control:
      • Restart the Oracle CM SDK domain. This ensures your HttpNode is part of the domain and that you want JDeveloper to start it. The Http node will be asked to run by the WebStarterAppServlet.
      • Restart the Oracle CM SDK OC4J instance.

        Note: You do not have to restart the Oracle CM SDK domain every time you run the Web application from Oracle JDeveloper, unless you change the server class WebStarterAppServer. If you are having problems, however, it is something to try.

    • In Oracle JDeveloper:
      • Run the project. The logon page appears.
      • Attempt to log in using guest.
      • The log file can be found at:

        JDeveloperHome/jdev/workspace/workspace-oc4j-app.log

        Note: Make sure to terminate the embedded OC4J server before running the project again.

Setting Up a Development Computer, Two Tier

Box A

  1. Install Oracle Application Server.
  2. Install Oracle CM SDK into the Oracle Application Server Oracle home.
  3. Configure a new Oracle CM SDK schema.

Box B

  1. Install Oracle Application Server.
  2. Install Oracle CM SDK into the Oracle Application Server Oracle home.
  3. Configure Oracle CM SDK, selecting the option to configure against an existing domain. When prompted, deselect Domain Controller and Node (leaving just the HTTP Node selected).
  4. Install Oracle JDeveloper into a seperate Oracle home.
  5. Extract the webstarterapp.ear file.
  6. In Oracle JDeveloper:
    • Create a new project using the webstarterapp.war file from the webstarteapp.ear file.
    • Under Project Properties > Libraries, create a new Library called CMSDK pointing to:

      • iasHome/ifs/cmsdk/lib/cmsdk.jar;
      iasHome/jlib/uix2.jar;
      iasHome/jdbc/lib/classes12.jar;
      iasHome/jlib/emPid.jar;
      iasHome/jlib/gss-1_1.zip

      Note: Windows users should use backslashes when specifying path names.

  7. Using the Application Server Control:
    • Create a ServerConfiguration for the WebStarterAppServer.
    • Create a new HTTP node.

      • Note: See the section in this document Creating an OC4J Instance for details.

  8. In Oracle JDeveloper:
    • Under Project Properties > Runner, set the virtual machine Java options:

      -DIFS.DOMAIN.Name=your_domain -DIFS.DOMAIN.NODE=yourNodeName

      • Notes:

      • Optionally turn off compile before running (Project Properties > Runner > Options).
      • Set default run target to index.jsp.

  9. Using the Application Server Control:
    • Restart the Oracle CM SDK domain (from Box A). This ensures your HttpNode is part of the domain and that you want Oracle JDeveloper to start it. The Http node will be asked to run by the WebStarterAppServlet.
    • Restart the Oracle CM SDK OC4J instance (for both Box A and Box B).

      • Note: You do not have to restart the Oracle CM SDK domain every time you run the Web application from Oracle JDeveloper, unless you change the server class WebStarterAppServer. If you are having problems, however, it is something to try.

  10. In Oracle JDeveloper:
    • Run the project. The logon page appears.
    • Attempt to log in using guest.
    • The log file can be found at at:

    JDeveloperHome/jdev/workspace/workspace-oc4j-app.log

    Note: Make sure to terminate the embedded OC4J server before running the project again.

Setting Up a Standalone Development Environment

This setup is intended for development only and should not be used in production. It avoids having to install Oracle Application Server and Oracle CM SDK on a development computer, but because it requires the use of the schema password, it is not secure.

  1. Assume Oracle Application Server and Oracle CM SDK are installed on another computer.
  2. Install Oracle JDeveloper.
  3. Extract the webstarterapp.ear file.
  4. Copy the required jars listed below in step 5 to the development machine.
  5. In Oracle JDeveloper:
    • Create a new project using the webstarterapp.war file from the webstarteapp.ear file.
    • Under Project Properties > Libraries:
      • Create a new Library pointing to iasHome/ifs/cmsdk/lib/cmsdk.jar
      • Create a new Library pointing to iasHome/jlib/uix2.jar
      • Create a new Library pointing to iasHome/jdbc/lib/classes12.jar
      • For Oracle CM SDK 10g (9.0.4), create a new Library pointing to iasHome/jlib/emPid.jar

        • Note: Windows users should use backslashes when specifying path names.

    • Compile the project.
  6. In Oracle JDeveloper:
    • Under Project Properties > Runner, set the virtual machine Java options:

    -DIFS.DOMAIN.Name=your_domain -DIFS.STANDALONE.Mode=true -DIFS.SCHEMA.PASSWORD=your_schema_password

    • Optionally turn off compile before running (Project Properties > Runner > Options).
    • Set default run target to index.jsp.
  7. Test in JDeveloper:
    • Run the project. The logon page appears.
    • Attempt to log in using guest.
    • The log file can be found at:

    JDeveloperHome/jdev/workspace/workspace-oc4j-app.log

    Note: Make sure to terminate the embedded OC4J server before running the project again.

Copyright © 2004, Oracle. All rights reserved.
E-mail this page
Printer View Printer View
Oracle Is The Information Company About Oracle | Oracle RSS Feeds | Careers | Contact Us | Site Maps | Legal Notices | Terms of Use | Privacy