Java API DITA Sample Application for IBM FileNet P8 Content Engine ReadMe

© Copyright IBM Corporation 2009, 2014 ALL RIGHTS RESERVED.

Table of Contents

Introduction

This sample application demonstrates how to use the Content Engine Java™ API to upload a DITA project (map, topics, images, etc.) to IBM® FileNet® P8. Once a DITA project is checked in, the sample application can download it from IBM FileNet P8 to a file system directory. This sample uses either the WSI (Web Services Interface) or EJB (Enterprise Java Beans) transport.

For detailed information, see DITA Publishing in the IBM FileNet P8 information center.

Contents

This sample code distribution contains the following files:

Prerequisites

Overview

This sample application demonstrates the following:

By using the appropriate runs script and configuration file, this sample application can be used with either the WSI or EJB transport.

This sample application can be run from a GUI interface (as described in the topics that follow) or the command line. If run from the command line, you must manually edit the appropriate configuration file. See Reference for the command line syntax and configuration file format.

To modify the sample application, you can edit one or more of the following source files.

Source file Description
CEConnection.java Establishes a connection to the Content Engine server.
DITAParser.java Parses a DITA file to map XML attributes to document properties.
DITAToolFrame.java The UI frame which controls upload and download.
GetDITADoc.java Downloads a DITA project (map, topics, images, etc.) to a local directory.
MainFrame.java The UI frame which controls login.
SampDITATool.java The main UI class.
StoreDITADoc.java Parses a DITA map and uploads DITA files to an object store.

Setting up the sample application

  1. Copy the files in the distribution to a working directory.
  2. Compile the application.
    1. Open the build script (build.bat for Windows or build.sh for Unix) with a text editor.
    2. Update the JAVA_HOME variable to the directory that contains the JDK you want to use.
    3. Update the CE_PATH variable to your Content Engine installation directory (for example, C:\Program Files\FileNet\ContentEngine).
    4. Save the build script.
    5. Run the build script.
  3. Update the run script for your environment.
    1. Open the run script appropriate for your environment with a text editor (see Contents for a list of run scripts).
    2. Update folder locations, classpath values, and Java options for your environment. The table below identifies some of the items that you might need to update.

      Value Description
      APP_PATH Specify the directory where the sample application resides. For example:
      • UNIX:  /sampditatool
      • Windows:  C:\sampditatool
      CE_PATH Specify the directory where the Content Engine is installed. For example:
      • UNIX:  /opt/FileNet/ContentEngine
      • Windows:  C:\Program Files\FileNet\ContentEngine
      JAAS Specify the path to the JAAS configuration file (login.conf.JBoss, login.conf.WebLogic, or login.conf.WebSphere). For example:
      • UNIX:  ${CE_PATH}/config/jaas.conf.JBoss
      • Windows:  %CE_PATH%\config\jaas.conf.WebSphere
      JAVA_HOME Specify the path to your JDK (or remove, if this variable is already set for your environment). For example:
      • UNIX:  /opt/jdk1.5.0_16
      • Windows:  C:\Program Files\Java\jdk1.5.0_16
      WSI_JAR For the WSI transport, specify the path to the WSI JAR files. For example:
      • UNIX:  ${CE_PATH}/tools/upgrade/stax-api.jar:${CE_PATH}/tools/upgrade/xlxpScanner.jar:${CE_PATH}/tools/upgrade/xlxpScannerUtils.jar
      • Windows:  %CE_PATH%\tools\upgrade\stax-api.jar;%CE_PATH%\tools\upgrade\xlxpScanner.jar;%CE_PATH%\tools\upgrade\xlxpScannerUtils.jar
      For the JBoss or WebLogic EJB transport, you will also have to specify the installation directory of the application server. For JBoss, for example:
      • UNIX:  /opt/jboss-4.0.5.GA
      • Windows:  C:\jboss-4.0.5.GA
  4. (WebSphere Application Client and EJB transport only) Update sas.client.props with the following values:

    Note: The sas.client.props file is located in the properties directory of the WebSphere Application Client installation directory (or the WebSphere Application Server installation directory, if you are developing on the Content Engine server).

Notes

Running the sample application

Configuring the Content Engine server connection

  1. Verify that you have performed all of the steps describe in Setting up the sample application.
  2. Execute the run script for your environment.
  3. In the Connection Parameters dialog box, complete the following fields:
  4. Click Test Connection. If the server connection is configured correctly, a "Connection to CE successful" message is displayed. If the server is not configured correctly, review the command prompt transcript to identify errors.

    Note: When you click Test Connection, the field values in the Connection Parameters dialog box are written to the configuration file.

  5. Click Open Dita Tool. The Dita Sample dialog box appears.

Uploading a DITA project

  1. On the Upload tab of the Dita Sample dialog box, complete the following fields:
  2. Optional: Simulate the upload.
    1. Select the Simulate check box.
    2. Click Upload.
    3. Verify the list of files that will be checked in.
  3. Perform the upload.
    1. Deselect the Simulate check box.
    2. Click Upload.

Note: When you click Upload, the field values entered on the Upload tab are written to the configuration file. See Configuration file for details.

Downloading a DITA project

  1. On the Download tab of the Dita Sample dialog box, complete the following fields:
  2. (Optional) Simulate the download.
    1. Select the Simulate check box.
    2. Click Download.
    3. Verify the list of files that will be copied from IBM FileNet P8.
  3. Perform the download.
    1. Deselect the Simulate check box.
    2. Click Download.

Note: When you click Download, the field values entered on the Download tab are written to the configuration file. See Configuration file for details.

Reference

Command line syntax

When running the sample application from the command line (in non-GUI mode), use the following syntax:

run_script [-H] | [-U] | [-D] -F file_name

where:

run_script The name of the run script appropriate for your environment. See Contents for a list of available run scripts.
-H Help. Displays all the application startup flags.
-U Non-GUI upload. The upload will commence using the information in the configuration file (no user prompting will occur).
-D Non-GUI download. The download will commence using the information in the configuration file (no user prompting will occur).
-F file_name The path to the configuration file. See Contents for a list of available configuration files.

For example, the following command (for a WSI/WebSphere/Windows environment) will copy a DITA project from IBM FileNet P8 without prompting, using the option specified in the configuration file conf\ditatoolwswsi.xml:

ditatoolwswsi -D -F conf\ditatoolwswsi.xml

Configuration file

The settings for the sample application are saved in a configuration file, which uses the XML DTD for java.util.Properties (http://java.sun.com/dtd/properties.dtd). The table below describes the settings:

XML key Description
basedir Specifies the local directory that contains the DITA map for the project to be checked in (for example, /dita/myproject/).
domain Specifies the name of the IBM FileNet P8 domain where the object store resides (for example, mydomain).
DownloadDir Specifies the destination directory for a DITA project download (for example, /sampditatool/download).
filename Specifies the name of the DITA map to upload or download (for example, articles/DITA-articles.ditamap).
os Specifies the name of the object store where the DITA files reside, or will reside (for example, OS1).
p8base Specifies the Content Engine folder where the DITA files will be checked in (for example, /DITAProjects).
pass Specifies the password for the Content Engine user.
simulateDl Specifies whether to simulate the download. If set to true, the sample application returns a list of files that would be downloaded from the Content Engine, without actually retrieving the files.
simulatePub Specifies whether to simulate the upload. If set to true, the sample application returns a list of files that would be uploaded to IBM FileNet P8, without actually checking in the files.
stanza Specifies the name of the stanza in the JAAS configuration file (typically, FileNetP8 for the EJB transport and FileNetWSI for the WSI transport).
uri Specifies the URI for the Content Engine server connection.
user Specifies a Content Engine user name that has permissions to check in and check out files from the P8 base directory as specified by the p8base value (for example, CEAdmin).

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY  10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
3-2-12, Roppongi, Minato-ku, Tokyo 106-8711 Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA  95141-1003
U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.

Trademarks