IDM Web Services Toolkit for Unixdocumation.net.au/bojan/IWSTU_20.1_tech.pdfv20.1 rev 1 IDM Web...

Version 20.1 rev 1

IDM Web Services Toolkit for Unix

Technical Reference

Notices

PUBLISHERThis document is published anddistributed by Vignette Corporation. It wasdesigned and produced using FrameMakerpublishing software.

VERSIONIDM Web Services Toolkit for UnixTechnical Reference, version 20.1 rev 1(Publication Date: 22 December 2006)

DISCLAIMERVignette does not warrant, guarantee, ormake representations concerning thecontents of this document. All informationis provided "AS-IS," without express orimplied warranties of any kind including,without limitation, the warranties ofmerchantability, fitness for a particularpurpose, quality and title.

Any information provided by Vignettecustomers or partners was obtained afterthe implementation of Vignette softwareand may have changed as of thePublication Date. You may not achieve thesame results or benefits from usingVignette as described in this document.Nothing in this document is considered tobe part of any product documentation orspecification for any purpose. Vignettereserves the right to change the contents

of this document and the features orfunctionalities of its products and servicesat any time without obligation to notifyanyone of such changes.

COPYRIGHT AND TRADEMARKS

Copyright © 2006 Vignette Corporation. Allrights reserved. Vignette, the V Logo,e:fficiency and e:fficiency experts aretrademarks or registered trademarks ofVignette Corporation in the United Statesand other countries. All other company,product, and service names and brandsare the trademarks or registeredtrademarks of their respective owners.

SEND US YOUR COMMENTS

If you have comments or suggestions aboutthis manual, please send them to thisaddress:

[email protected]

A member of the Publications team willacknowledge your mail as soon aspossible.

You can also reach us at the followingaddress:

Vignette CorporationPublications Department1301 South MoPac Expressway, Suite 100Austin, TX 78746USA

© 2006 Vignette Corporation. All rights reserved.2 v20.1 rev 1

Table of Contents

Chapter 1. Introduction 5Purpose 5Overview 6

What are web services? 6Architecture 7

Chapter 2. IDM Server components 9Overview 9Setting up CORBA services 10Tracing 11Advanced Configuration 12

CORBA Services command line parameters 12Load balancing 13Retrieving large files 14

Chapter 3. Application Server component 15JBoss 15

Configuration 16Tracing configuration 19

Configuration variables in host.props 19Deployment of patches 20Configuration variables in vignette-ds.xml 20Configuration variables in WSTestConfig.xml 20Configuration variables in orb.props 20Configuration variables in IDMConfiguration.xml 21

Advanced configuration 24Configuration variables in ExceptionMessages.xml 25

Java Virtual Machine configuration 27IDM Web Services Test Client 28

Overview 28Usage 28Using the test client 28

v20.1 rev 1 3IDM Web Services Toolkit for Unix Technical Reference

Table of Contents

Chapter 4. Vignette Rendition Server 29

Chapter 5. Web Server component 31IDM Web Services J2EE Demo Client 31

Overview 31Prerequisites 31Configuration 32Using the Demo Client 33

Chapter 6. Applet Viewer 35Introduction 35Architecture 36Installing the applet viewer 37Developing applications using the applet viewer 38Configuring Java Advanced Imaging Support 41Configuring the applet viewer 42Repackaging into a web application archive 46Common issues 50

JRE 50Large TIFF images 50

Using the applet viewer 51Viewer applet toolbar 51Annotations 52Viewer applet context menu 54Multi-page documents 55Subpages 55

Appendix A. JBoss administration 57Managing JBoss Application Server 57

Startup 57Shutdown 57Accessing the console 57Web services console 57

Index 59


Chapter

1
Introduction
PurposeThe IDM Web Services Toolkit for Unix is a product that allows users to develop applications that interface with IDM Server using web-based standards and protocols.

This Technical Reference provides an overview of the product as well as configuration instructions. These instructions target the UNIX platform only.


1Chapter

OverviewWhat are web services?

A web service can be described simply as programmable application logic accessible using standard Internet protocols. Web services are not tied to any one operating system or programming language and so can be thought of as reusable web components. Applications can be constructed using multiple web services from various sources that work together regardless of where they reside or how they are implemented.

The following are a list of technologies used and their purpose, when used for building or using web services.

Extensible Markup Language (XML) is the standard used to represent data used by a web service with XML schemas used to describe the data types.

Simple Object Access Protocol (SOAP) is the communications protocol for web services. SOAP is a specification that defines an XML format for messages. SOAP messages are exchanged using the Hypertext Transfer Protocol (HTTP). IWSTU uses document-literal style SOAP, and complies with the Web Services Interoperability standards (WS-I).

A Web Services Description Language (WSDL) file is an XML document that describes a set of SOAP messages and how the messages are exchanged. A WSDL file is a contract between a web service consumer and the web service. As WSDL is XML, it is readable and editable but in most cases, it is generated and consumed by software.


Introduction

ArchitectureApplications written with the IDM Web Services Toolkit for Unix will follow the n-tier architecture consisting of presentation, business and data tiers. The following diagram depicts this architecture.

Data tier—IDM ServerThe data tier consists of IDM Server. It manages the storage and indexing of documents. Access to IDM Server from the business tier is achieved through IDM Web Services Repository Objects and IDM Server CORBA services.

TAO is used as the CORBA environment on IDM Server.

Business tier—application server, web serverThe business tier consists of application servers and web servers. In actual implementations or deployments, the business tier can be hosted on one physical server, serving the roles of an application server and web server.

The machine serving the role of a web server can be implemented using Java-based technologies on the UNIX platform or using .NET-based technologies on the Windows platform. The UNIX implementation is the subject of this manual.

The application server shown in the architecture diagram hosts the web services—exposing the IDM Web Services Toolkit API. Custom web applications or web pages are

Database

Application Server

Browser

Web Server

IDM Server

Custom Web Pages(ASP/JSP/other)

IDM Web Services

IDM ServerCORBA Services

HTTP

SOAP/HTTP

Rendition Server

SOAP/HTTP

Presentation tier

Business tier

Data tier

CORBA/IIOP

JDBC

ODBC


1Chapter

hosted on the web server and are capable of using the IDM Web Services Toolkit API exposed on the application server. Communication between these two machines is through SOAP over HTTP.

The IDM Web Services Toolkit uses the Vignette Rendition Server to convert documents on demand to a form that can be viewed in a web browser. The rendition server is also accessed by IDM Web Services Toolkit via Rendition Server Web Services.

Presentation tier—web browserThe presentation tier consists of an Internet browser running on a machine connected to the Internet.

A browser would access a web application simply by connecting to the web server and requesting for web pages using the HTTP protocol.

Deployment variationsTypically not all deployments will or can follow the exact configuration shown in the architecture diagram—that is, using individual machines for the different tiers. The architecture is flexible enough to allow variations in the deployment of the product. Typically it is the business tier where deployments can vary. The following are two examples of deployment configurations:

Example 1

One machine configured as IDM Server

One machine configured as the application server (hosting IDM Web Services)

One machine configured as the web server

One machine configured as a rendition server

Example 2

One machine configured as IDM Server

One machine configured as application server and web server

One machine configured as a rendition server


Chapter

2
IDM Server components
OverviewThis section describes the configuration of the software components of IDM Web Services Toolkit for Unix, that runs on the IDM Server machine.

For a typical system you should perform the procedures described in the following subsections. You might not be using some components, or you might have no need to change the factory defaults. In these cases, you can skip the corresponding sub-section after checking its applicability.


2Chapter

Setting up CORBA servicesTo set up CORBA services

1. Login to IDM Server as the instance user.

2. Copy the file oohoncho_tao.conf to the correct location:

cp $CTL_RUNTIME_DIR/is/admin/oohoncho_tao.conf $CTL_RUNTIME_DIR/is/config/oohoncho_tao.conf

(This is one command although it appears here as two lines.)

3. Use IDM System Administration to add the following service to the Custom Startup List.

Enter the command as

oohoncho_tao is/config/oohoncho_tao.conf

NOTE: The STARTUP file in $CTL_RUNTIME_DIR/is/config must contain the command

run oohoncho_tao is/config/oohoncho_tao.conf

4. Add the following section to the end of the file /etc/tower/profile.custom.<instance user>(This is the TAO Name Service Port number and the following is an example only):

NAMING_SERVICE_PORT=14888export NAMING_SERVICE_PORT

5. Logout and logon again to ensure that the profile is updated.

6. Stop and restart IDM Server to start up the CORBA services.

NOTE: In some cases, not all CORBA processes will start up. To resolve this, add sleepintervals between processes in oohoncho_tao.conf using the 'wait' command.



TracingAll of the CORBA services will log startup and shutdown messages to their trace files. All of these log files can also be found in $CTL_RUNTIME_DIR/is/log. Errors will also be logged to the file $CTL_RUNTIME_DIR/is/log/errorlog.

All CORBA service logging and trace information will be recorded in the following files:

_annotation_poa This log traces get/set annotation requests.

_general_poa This log contains tracing related to miscellaneous requests such as the request for number of pages of an IFN.

_import_poa This log traces image import and image deletion requests.

_library_poa This log traces library related requests.

_oohoncho_poa This log contains only start and stop information.

prcmaptbl This log traces messages from the Mapping Table Library which is used by the retrieval POA.

_queue_poa This log traces queue system related requests.

_retrieval_poa This log traces image retrieval/image rendition requests.

_security_poa This log contains only security-related information.

You must manually create these files on IDM Server if they do not already exist; otherwise, logging will not be possible. If you create the files manually, use IDM System Administration to create trace logs.


2Chapter

Advanced Configuration

CORBA Services command line parametersThe only CORBA servers that accept arguments are security_poa_tao and oohoncho_tao. These are described below.

security_poa_taoParameters for security_poa_tao must be added to oohoncho_tao’s configuration file.

security_poa_tao <tablename> <tablesize> <numberofsegments> [destroy]

where

<tablename> A name for the login table. (This table is created automatically in memory; it is not a database table.)

<tablesize> The number of users to support.

<numberofsegments> The number of shared memory segments used. More segments will reduce locking contention but will require more IPC resources.

Locking contention can occur under a heavy usage scenario, for example, 1000 users with 2 or more security_poas used.

Each shared memory segment holds a subset of the in-memory session information table and access to the segment is controlled by a semaphore. Increasing the number of segments allows multiple security_poas concurrent access to session information, provided that the session information is held in separate segments. However, the higher the number of segments, the more system resources would be required; hence, the semaphore and shared memory limit values must be set appropriately.

Note that IPC default limits for some systems are very low, so configuration of the operating system will be required.

destroy Destroy the login table when all instances of the security_poa_tao server are shut down. The pre-configured value is that the parameter is omitted, so the table will not be deleted. (If you wish to specify this option, the word destroy must be in lower case.)

oohoncho_taoThe honcho daemon starts oohoncho_tao , so configuration parameters must be added to $CTL_RUNTIME_DIR/is/config/STARTUP.

oohoncho_tao <configFileName> [-special <prefix>]

where

<configFileName> A configuration file name; for example, is/config/oohoncho.conf. (If the path does not start with “/” or “.”, the string $CTL_RUNTIME_DIR/ will be prepended automatically).

-special <prefix> Start an instance of oohoncho_tao with the specified prefix. The prefix is used in the construction of the name for CORBA purposes. For example, if a prefix of _test was specified on a host named devbox, the CORBA name would be devbox_test_oohoncho.



Load balancing

OverviewA load balancing facility is provided in IDM Server CORBA services. The load balancing facility distributes requests from Java clients, run on one or more application servers, among multiple CORBA servers running on IDM Server. Load balancing provides the following functions:

• Automatically distributes CORBA client requests to the least loaded instance of an appropriate CORBA server type.

• Optimizes distribution of requests from distributed clients.

• Allows targeting of requests to specific server instances when required.

• Centrally starts and stops all CORBA servers according to configuration.

• Allows partitioning of CORBA server systems on a single IDM Server for testing and upgrading purposes.

The core of the load balancing system is a single instance of the CORBA server, named oohoncho_tao. This server starts a group of other CORBA servers and keeps an entry for each in a table in its own memory space. See Configuration immediately below for configuration details.

ConfigurationThe load balancing system is configured by modifying the configuration file for oohoncho_tao. In most cases, changes to this configuration file will not be required. If you do need to make changes, do so after installing the IDM Server CORBA Services on IDM Server.

The configuration file for oohoncho_tao is located in the $CTL_RUNTIME_DIR/is/config directory. Example contents of this file are as follows (but note that other information in the file relates to startup of the Naming Service, is ORB-dependent, and should not be changed):

_security_poa 2 1 1 1 security_poa_tao idmsvr 1000 2_retrieval_poa 2 1 1 1 retrieval_poa_tao_import_poa 2 1 1 1 import_poa_tao_annotation_poa 2 1 1 1 annotation_poa_tao_general_poa 2 1 1 1 general_poa_tao_queue_poa 20 1 2 1 queue_poa_tao

The format of these entries is:

<typeName> <maxRequests> <minProcesses> <maxProcesses> <reserved> <exepath> [<parameters>]

where

<typeName> The POA_NAME identifies a server process in a CORBA environment. This name is hard-coded in the IDL (Interface Definition Language) files, and cannot be modified.

<maxRequests> This parameter is used for load balancing. It is the number of requests pending on an instance of a server. When this number is exceeded, oohoncho_tao will fork a new server if the <maxProcesses> value has not been reached.

<minProcesses> This parameter is used for load balancing. It is the number of server processes initially started and maintained. The minimum value is 1. If a particular server should not be started, it is best to comment out the whole line rather than set this field to zero.

<maxProcesses> This parameter is used for load balancing. It is the maximum number of server processes that can be started. The minimum


2Chapter

value is 1 while the maximum value is dependent on IDM Server resources.

<reserved> Reserved. The value should be set to 1.

<exepath> The path to the server executable. If it does not start with “/” or “.”, the string “$CTL_RUNTIME_DIR/is/system/” will be prepended. Thus, only the executable name should normally be necessary here.

<parameters> Arguments for the server process command line; see CORBA Services command line parameters on page 12.

Retrieving large filesWhen retrieving large (say, greater than 2 MB) files via the API function DocServices.getDocument(), it is best to configure the IDM Server CORBA processes to break the image up into smaller, manageable sizes to avoid exceeding system resource limits.

To do this, you will need to configure the system variable Data transfer block size (MB) (tdp_data_trans_block_size). This variable controls the image chunk size that is transmitted between the IDM Server CORBA processes and the application server.


Chapter

3
Application Server component
This chapter describes the configuration required for the Application Server component.

The following environment variables are used throughout this section:

• AS_HOME is the installation directory of the application server.

• AS_CONFIG_DOMAIN is the path of a defined domain.

• AS_CONFIG_DOMAIN/idm is the base directory for IDM products on the application server.

JBossThe application server used to host the IDM Web Services is JBoss, a popular open source (LGPL licensed) J2EE application server containing the following features:

• Full microkernel approach based on Java Management eXtensions (JMX)

• Fully hot-deployable and cyclable service layer with Service Archive format (SAR)

• Fully automated and internet based installation with hot-deploy of applications

• Full J2EE 1.4 support

• Full security implementation and JAAS integration

• Full clustering of any java objects (EJB, HTTP, POJO)

• Ground-breaking Aspect Oriented Programming (AOP)

• Fully supported by the JBoss Group

For more information about JBoss Application Server please refer to Appendix A, JBoss administration or go to www.jboss.org/index.html.


3Chapter

Configuration

To configure IDM Web Services for a typical installation

This procedure does not list all configurable parameters; for these details, see Advanced configuration on page 24.

In this procedure, add or modify the relevant files with the values highlighted in bold.

1. Ensure that the installation has been carried out:

2. Ensure that the $JAVA_HOME variable is set to the correct installation location of Java; otherwise, set it as follows.

export JAVA_HOME=<where Java SDK is installed>export PATH=$JAVA_HOME/bin:$PATH

3. The IDM Web Services Toolkit for Unix Application Server component does not support clustering, in that you cannot have two IDM Web Services Toolkit for Unix Application Servers configured to communicate with the same IDM Web Services Toolkit for Unix Repository Serve component. By default JBoss application servers belong to the same cluster called DefaultPartition, so if an instance of JBoss is already configured on the LAN, the IDM Web Services Toolkit for Unix Application Server must be changed to either have a unique cluster configuration or to disable clustering altogether.

To configure the IDM Web Services Toolkit for Unix Application Server to have a unique cluster configuration, edit the file $AS_HOME/bin/run_IDMDomain.sh and change the line:

./run.sh -c IDMDomain

to be:

./run.sh -c IDMDomain -g <cluster partition name> -u <cluster partition UDP group>

where <cluster partition name> is a unique name within the same LAN, for example IDM_PARTITION.

<cluster partition UDP group> is a unique UDP multicast address, for example 222.1.2.3.

To configure the IDM Web Services Toolkit for Unix Application Server to disable clustering, perform the following steps:

• rm -fr $AS_CONFIG_DOMAIN/farm

• rm -fr $AS_CONFIG_DOMAIN/deploy-hasingleton

• rm $AS_CONFIG_DOMAIN/deploy/cluster-service.xml

• rm $AS_CONFIG_DOMAIN/deploy/tc5-cluster-service.xml

• rm $AS_CONFIG_DOMAIN/deploy/deploy.last/farm-service.xml

• rm $AS_CONFIG_DOMAIN/deploy/deploy-hasingleton-service.xml

• rm $AS_CONFIG_DOMAIN/deploy/jms/*

• cp –R $AS_HOME/server/default/deploy/jms/* $AS_CONFIG_DOMAIN/deploy/jms

• vi $AS_CONFIG_DOMAIN/deploy/jbossweb-tomcat55.sar/META-INF/jboss-

service.xml and delete the line containing the following:

<depends>jboss.cache:service=TomcatClusteringCache</depends>

It is recommend to disable the clustering option instead of creating a unique cluster partition name.


4. Change the logging configuration of the JBoss application server for the IDM domain to prevent it from filling up the disk. Edit the contents of the file $AS_CONFIG_DOMAIN/conf/log4j.xml as shown in bold italics below:



<appender name="FILE" class="org.jboss.logging.appender.DailyRollingFileAppender"><param name="File" value="${jboss.server.home.dir}/log/server.log"/><param name="Append" value="false"/><param name="Threshold" value="ERROR"/>

<param name="DatePattern" value="'.'yyyy-MM-dd"/>



<layout class="org.apache.log4j.PatternLayout"><param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>



</layout></appender>

5. For AIX, HP-UX and HP-UX Itanium, update the contents of the file $AS_CONFIG_DOMAIN/deploy/iiop-service.xml by adding the line shown in bold below:

<mbean code="org.jboss.iiop.CorbaORBService" name="jboss:service=CorbaORB"><attribute name="SunJDK14IsLocalBugFix">false</attribute><attribute name="ORBClass">org.jacorb.orb.ORB</attribute>

6. Update the contents of the file AS_CONFIG_DOMAIN/idm/config/IDMConfiguration.xml. Find the lines:

<NameValue><Name>datasource.ref</Name><Value>datasource name</Value>

</NameValue><NameValue><Name>jdbc.table.schema</Name><Value>TOWER</Value>

</NameValue>

Replace datasource name with whichever of the following corresponds to the commercial database used by your IDM Server:

• java:/OracleDS

• java:/DB2DS

• java:/SQLServerDS

The value of this configuration variable must match datasource.ref in $AS_CONFIG_DOMAIN/idm/config/idm/default/host.props. Refer to the section Advanced configuration on page 24 for details of configuration variables in host.props and orb.props.

3Chapter

If you are using an IDM Server database user ID other than tower, set the value of jdbc.table.schema to match the user ID you have configured on IDM Server. The user ID should be specified in upper case.

7. In a production system, it is advisable to place the retrieval cache ($AS_CONFIG_DOMAIN/idm/cache) in a separate mounted file system. The cache stores all the renditions retrieved for each session separately. At regular intervals the cached renditions will be removed once the session has expired. The size of the partition required will depend on the number of simultaneous sessions, the number of pages retrieved per session, and the size of the rendered pages. A safety factor should be included since there can be a delay before the renditions for an expired session are removed. The location of the cache and clean-up delay can be adjusted. See Configuration variables in IDMConfiguration.xml on page 21 for these settings.

8. If you are using application server tracing, it is advisable to place the logs directory ($AS_CONFIG_DOMAIN/idm/logs) in a separate magnetic disk partition. The size of the partition required will depend on the number of simultaneous sessions, the client access rate, and the configured TraceOutputSeverity. See Tracing configuration on page 19.

9. The file vignette-ds.xml is located in $AS_CONFIG_DOMAIN/deploy and you must manually configure the variables in this file. See Configuration variables in vignette-ds.xml on page 20.

You do not need to set up the CLASSPATH for the application server because the installation process will do it automatically.



Tracing configurationThe whole of IWSTU that executes on the JBoss application server logs messages using standard Java logging which is configured using the configuration file $AS_CONFIG_DOMAIN/conf/iwstu.logging.properties.

To enable this, the following configuration appears in the file $AS_HOME/bin/run_IDMDomain.sh:

-Djava.util.logging.config.file=$AS_CONFIG_DOMAIN/conf/iwstu.logging.properties

By default, only severe messages will be logged. Logging is configured to cycle through 5 files which are limited to 5 million bytes in capacity. Log messages will be logged using the SimpleFormatter. For convenience, each part of IWSTU capable of logging has an entry in this configuration file which is commented out and may be uncommented to allow finer control of the logging.

NOTE: If you modify any of the configuration details, you must restart the JBossApplication Server for the changes to take effect.

Configuration variables in host.propsThe configuration values contained in the host.props property file relate to locating the CORBA services on IDM Server and login information. The file is located in the $AS_CONFIG_DOMAIN/idm/config/idm/default directory. If another server’s Corba Services is to be connected to, manually change the host name to that of the other server.

IDM_HOSTNAME

This is the primary hostname of the IDM Server; for example, sundev2. This cannot be an alias or IP address such as localhost or imagestore. If the primary host name of IDM Server is changed, this entry must be changed correspondingly. The primary host name should be specified without trailing spaces and should not be a fully qualified name; e.g., sundev2.acme.com.

ALTERNATE_SYS

If you wish to run another instance of the oohoncho CORBA service on IDM Server, you must make changes on both the application server and IDM Server. On the application server, the only change required is to set this ALTERNATE_SYS parameter. It supplies a suffix for the name of the alternative instance; for example, if you set this parameter to _dev, the alternative instance will be named oohoncho_dev. (By default, this configuration variable is commented out; no alternative instance of oohoncho will run.) On IDM Server, you must add an entry to the file $CTL_RUNTIME_DIR/is/config/HANDLERS file similar to the following. Note that the value of the ALTERNATE_SYS parameter (_dev in this example) appears twice in this entry:

oohoncho_dev 8 oohoncho_tao <conf file path> -special _dev

LICENSE_TYPE

This variable must be set to the value 1.

APPLICATION_REF

This variable is not yet supported.

datasource.ref

This is the JDBC datasource name. This must be whichever of the following corresponds to the database used by your IDM Server:


3Chapter

• java:/OracleDS

• java:/DB2DS


The value of this configuration variable must match the value of datasource.ref in $AS_CONFIG_DOMAIN/idm/config/IDMConfiguration.xml.

Deployment of patchesWhen deploying patches for IDM Web Services Toolkit for Unix on the application server or web server, it is important that only one copy of each released jar file exist in the JBoss runtime directories. Otherwise, JBoss could pick up and deploy the previous versions. To backup existing versions of released jar objects, it is best to move them to some backup directory and not use the backup option of the patch release program.

Configuration variables in vignette-ds.xmlThe file vignette-ds.xml is located in $AS_CONFIG_DOMAIN/deploy.

This file is the equivalent of the ODBC datasource. It contains the JNDI name for Oracle (OracleDS), DB2 (DB2DS) and SQL Server (SQLServerDS) JDBC datasources together with their connection details. These datasources are configured to use DataDirect Connect for JDBC drivers.

If you are using or changing to an Oracle database, you must manually change the Oracle hostname (DB_HOSTNAME), port number (DB_PORTNUM), SID (ORACLE_SID), user (DB_USER) and user password (DB_PASSWORD).

If you are using or changing to a DB2 database, you must manually change the DB2 hostname (DB_HOSTNAME), port number (DB_PORTNUM), database (DB2_DATABASE), user (DB_USER) and user password (DB_PASSWORD).

If you are using or changing to an SQL Server database, you must manually change the SQL Server hostname (DB_HOSTNAME), port number (DB_PORTNUM), database (MSSQL_DATABASE), user (DB_USER) and user password (DB_PASSWORD).

The values for the active data source must match those contained in $CTL_RUNTIME_DIR/is/config/install and $CTL_RUNTIME_DIR/is/config/odbc.ini of IDM Server.

Vignette recommends you comment out unused data sources to reduce memory usage by the Application Server.

Configuration variables in WSTestConfig.xmlWSTestConfig.xml is located in $AS_CONFIG_DOMAIN/idm/config.

WSTestConfig.xml is the configuration file used by the WSTest java class, which is executed when IDM Web Services Test Client is run. This configuration file contains values that detail the URL information to the web services. These URLs can be set to point to either a UNIX J2EE-based URL hosted by JBoss, or Windows-based URL hosted by .NET.

Configuration variables in orb.propsThis file specifies where the application server can access the CORBA objects. This can be on the same or different machine to the application server.

The following lines are modified automatically on installation. No other lines in this file should be modified.

If another server’s CORBA services are to be connected to, manually change the host name and naming services port number to that of the other server.



If multiple CORBA services are to be connected to at any one time then:

1. Create a new directory in $AS_CONFIG_DOMAIN/idm/config/idm.. It is advisable to name the new directory the host name of the CORBA Services Server.

2. Copy the files from the default directory into the new directory.

3. Configure the orb.props file within the new directory to point to another setup of CORBA services.

NOTE: Each configuration of the IDM Web Services Toolkit Application Server canonly be connected to one instance of the CORBA Services at any given time.

ORBInitRef.NameService corbaloc:iiop:<IDMHOSTNAME>:<NAME_SERVICE_PORT>/NameService

where

<IDMHOSTNAME> Must be set to the host name of IDM Server. The host name should not be a fully qualified name; e.g., sundev2.acme.com.

<NAME_SERVICE_PORT>Must be set to the Naming Service port number. This value should be the one set up as described in Setting up CORBA services (page 10) for the NAMING_SERVICE_PORT variable in the file/etc/tower/profile.custom.<instance user>.

Configuration variables in IDMConfiguration.xmlThe configuration values contained in the file IDMConfiguration.xml (located in $AS_CONFIG_DOMAIN/idm/config) control the on-demand rendering capability of the IDM Web Services.

This XML file contains a list of name/value pairs. The currently recognized names are listed below.

jndi.initial.context.factory

The class name of initial context factory used to look up a JNDI entry. The value of this variable is vendor-specific and is defaulted to a JBoss-specific value.

provider.url

The URL of the JNDI content tree. The value of this variable is vendor-specific and is defaulted to a JBoss specific value.

datasource.ref

This is the JNDI lookup name for the JDBC DataSource reference. It must be whichever of the following corresponds to the database used by your IDM Server:

• java:/OracleDS

• java:/DB2DS


The value of this configuration variable must match datasource.ref in $AS_CONFIG_DOMAIN/idm/config/idm/default/host.props.

jdbc.table.schema

The JDBC table schema used in the execution of database search queries. This must be the same as the database user of IDM Server and must be in uppercase.


3Chapter

Doctype.UserCleanupInterval

The time interval in seconds between successive removals from the cache of document type information for expired tickets. The default value is 300 seconds.

Renderer.CacheDirectory

The name of the directory where converted images will be cached. This directory must be set to the path equivalent to $AS_CONFIG_DOMAIN/idm/cache.

IDMCache.CleanupInterval

The time interval in seconds between successive removals from the cache of images for expired tickets. The default value is 600 seconds.

RenderManager.url

This is the URL of the RenderManager of the Rendition Server. Only the IP address requires modification in the supplied sample file. This name/value pair is mandatory.

RenderManager.retry

This is the maximum number of retries when attempting to obtain a RenderAgent from RenderManager. If this name/value pair does not exists, the default value is 5.

RenderManager.sleep

This is duration of sleep in seconds between retry attempts. If this name/value pair does not exists, the default value is 1 second.

Renderer.XXX

The name of the renderer type in the Rendition Server. There will be as many name/value pairs as the number of file extensions to be supported. Note that the file extension must be in uppercase; for example, Renderer.AFP. Its corresponding value will be AFPRenderer. The example file contains all the currently supported file extensions, and does not require any modification.

RenderAgent.timeout

This is the timeout in milliseconds used when waiting for a reply from the Rendition Server.

NOTE: The following parameters—height, width, zoomfactor, force8bits, convtype, andcoloron—DO NOT need to be modified. They are NOT active values; they merely map fieldnames from IDM Server to the Windows Rendering Server. See the IDM SystemAdministration User Guide to set the value of these fields on IDM Server.

HEIGHT

The name of the height rendering parameter as recognized by the Rendition Server. The supplied value does not require modification (see the NOTE above).

WIDTH

The name of the width rendering parameter as recognized by the Rendition Server. The supplied value does not require modification (see the NOTE above).

ZOOMFACTOR

The name of the zoom factor rendering parameter as recognized by the Rendition Server. The supplied value does not require modification (see the NOTE above).



FORCE8BITS

The name of the force 8 bits rendering parameter as recognized by the Rendition Server. The supplied value does not require modification (see the NOTE above).

CONVTYPE

The name of the conversion type rendering parameter as recognized by the Rendition Server. The supplied value does not require modification (see the NOTE above).

COLORON

The name of the full color rendering parameter as recognized by the Rendition Server. The supplied value does not require modification (see the NOTE above).

CallStack.Depth

This specifies how deep the call stack will be when it is included in the exception thrown by the webservices.

Variables relating to SSO configuration

You will need to configure SSO (Single Sign On) between the IDM Web Services Toolkit and the Web Services Client Application with the help of a configuration variable SSOConfigFile in $AS_CONFIG_DOMAIN/idm/config/IDMConfiguration.xml.

The value of the configuration variable SSOConfigFile should be the full path of the properties file iwstusso.properties. This file contains the security key that must match with the corresponding security key in the Web Services Client Application.

You may also need to configure SSO between IDM Server and the IDM Web Services Toolkit with the help of two other configuration variables: the sso_password configuration variable in the IDM Server configuration file $CTL_RUNTIME_DIR/is/config/install and the SSOPassword in $AS_CONFIG_DOMAIN/idm/config/IDMConfiguration.xml. By default, they are set to the same value and hence do not need changing.


3Chapter

Advanced configurationEncrypted data source password

IDM Web Services Toolkit for Unix allows you to use an encrypted data source password. This means that the server stores an encrypted version of the password. Persons who have access to the password files cannot retrieve passwords from them and security is enhanced.

Encrypted passwords are held in the login-config.xml file.

To use an encrypted data source password

You must carry out these instructions for each data source you wish to configure.

1. Generate an encrypted password:

java -cp "$AS_HOME/lib/jboss-jmx.jar:$AS_HOME/lib/jboss-common.jar:$AS_HOME/server/default/lib/jboss-jca.jar:$AS_HOME/server/default/lib/jbosssx.jar" org.jboss.resource.security.SecureIdentityLoginModule <cleartext password>

(This is a single command, although it prints here as 3 lines.)

2. Open vignette-ds.xml, located in $AS_CONFIG_DOMAIN/deploy, for editing.

3. Look for the <local-tx-datasource> tags.

The file contains three <local-tx-datasource> tags which define data sources for Oracle, DB2 and SQLServer. The example here illustrates how to modify a DB2 data source definition. You should choose and modify the one appropriate to your environment.

The <local-tx-datasource> tag will resemble

<local-tx-datasource> <jndi-name>DB2DS</jndi-name> <connection-url>jdbc:vignette:db2://DB_HOSTNAME:DB_PORTNUM</connection-url> <driver-class>com.vignette.jdbc.db2.DB2Driver</driver-class> <user-name>DB_USER</user-name> <password>DB_PASSWORD</password> <connection-property name="DatabaseName"> DB2_DATABASE </connection-property></local-tx-datasource>

Note the <user-name> and <password> tags.

4. Remove the <user-name> and <password> tags and replace them with a <security-domain> tag that maps to the login-config.xml entry, thus:

<local-tx-datasource> <jndi-name>DB2DS</jndi-name> <connection-url>jdbc:vignette:db2://DB_HOSTNAME:DB_PORTNUM</connection-url> <driver-class>com.vignette.jdbc.db2.DB2Driver</driver-class> <security-domain><security domain></security-domain> <connection-property name="DatabaseName"> DB2_DATABASE </connection-property></local-tx-datasource>

Replace <security domain> with the name of an application-policy entry in login-config.xml. This name must be unique. You will create the entry in step 7.

5. Save and close.

6. Open login-config.xml, located in $AS_CONFIG_DOMAIN/conf, for editing.

7. Create an application-policy entry in login-config.xml:



<policy>...<application-policy name = "<security domain>"><authentication><login-module

code="org.jboss.resource.security.SecureIdentityLoginModule" flag="required">

<module-option name = "username"><user name></module-option><module-option name = "password"><encrypted password></module-option><module-option name="managedConnectionFactoryName">

jboss.jca:service=LocalTxCM,name=<database name></module-option>

</login-module></authentication>

</application-policy>...</policy>

The <security domain> is the name you used in step 4.

The <user name> is an appropriate user name.

The <encrypted password> is the encrypted password you generated in step 1.

The <database name> is the data source’s JNDI name as defined in vignette-ds.xml.

8. Save and close.

This completes the configuration of an encrypted password for the data source. Repeat the instructions for each data source you wish to configure.

Configuration variables in ExceptionMessages.xmlSOAP exception messages are configured by means of variables in ExceptionMessages.xml, located at $AS_CONFIG_DOMAIN/idm/config.

This file specifies the message strings and the corresponding formats for all of the SOAP exceptions messages as supported in the IDM Web Services Toolkit.

Exceptions and their messages are defined in an <object> tag. The message text is defined in a <template kind="soapmsg">...</template> tag inside the <object> tag. For example, the message for InvalidParameterException is defined thus:

<object type="InvalidParameterException"><template kind="soapmsg">The value supplied to '<param name="parameterName"/>' was deemed to be invalid because the value supplied was '<param name="parameterValue"/>'. Please review the documentation for exact details on what are acceptable values for the '<param name="parameterName"/>' parameter.</template></object>

As shown in this example, such a message can contain tags of the form

<param name="name of the parameter"/>

Such a tag will be replaced by the specified exception parameter’s value at runtime when the exception is thrown. For a list of parameter names refer to the IDM Web Services Toolkit 20.1 API Reference.

Any non-structured parameter may appear here. For example, available parameters for InvalidParameterException are: message, wsName, wsMethodName, parameterName, and parameterValue. A parameter’s name may occur multiple times in a message.

To modify an exception’s message

1. Open the ExceptionMessages.xml file for editing.


3Chapter

2. Find the name of the exception in a tag of the form

<object type="name of the exception">

The message text will follow inside a <template kind="soapmsg"> tag.

3. Change the message text at will.

4. Save and close.

You would typically use this feature to translate messages from English into another language. Since ExceptionMessages.xml is a Unicode file (encoded using UTF-8), exception messages may be translated into any language supported by Unicode—that is, practically any known language.



Java Virtual Machine configurationThe Java Virtual Machine (or JVM) heap size should be configured appropriately in order to support retrieval and importing of large files in JBoss. The configuration of the heap size is largely determined by the amount of memory available.

As an example, on a 512 Mb SUN machine, settings of Xms=128M, Xmx=512M allow for retrieval and importing of documents up to 4 Mb in size.

Documentation of JVM heap settings can be obtained by running “java -X” in a command/shell prompt. Some heap settings may not be available on all platforms and they may have different default values.

-Xms Initial Java heap size in megabytes. For example-Xms64m

-Xmx The maximum Java heap size in megabytes. For example-Xmx256m

-Xmn Only available on HP-UX. New generation Java heap size in megabytes. For example-Xmn256m

When running on AIX JBoss requires this additional Java Virtual Machine parameter to start up properly:

-Djava.net.preferIPv4Stack=true

Configuration changes should be made to the JAVA_OPTS variable in $AS_HOME/bin/run_IDMDomain.sh. The application server requires a restart for the changes to take effect.


3Chapter

IDM Web Services Test ClientOverview

The IDM Web Services Test Client (WSTest) is an interactive text-based console program that allows testing of the IDM Web Services API. It is written in Java.

To use the test client, the IDM Web Services Toolkit should have been installed and configured on the application server.

The test client should be run on the application server, since the application server has a Java Runtime Environment and the necessary configuration files (if used).

UsageTo run the test client, perform the following step:

Login as the UNIX tower user on the application server.

cd $AS_CONFIG_DOMAIN/client./run_wstest.sh

Using the test clientOnce the test client is up and running, a menu will appear listing the possible operations that exercise the IDM Web Services API. Simply make a selection and follow the prompts requesting for information.


Chapter

4
Vignette Rendition Server
The product Vignette Rendition Server provides a rendering server for on-demand renditions. For each file type supported for conversion, a Java class is provided which renditions from the Rendition Server.

Please refer to the Vignette Rendition Server Technical Reference for instructions on installing and configuring a Windows rendering server.

Note that if you do not set up the IDM Server rendering parameters, rendering will be done in accordance with default settings. For details on how to configure the rendering parameters refer to the IDM System Administration User Guide.

Within IDM Server, the MIME types file $CTL_RUNTIME_DIR/is/config/mimetypes determines which file extensions require on-demand rendering.

NOTE: Only rendition to .png file format is supported with IDM Web Services Toolkit forUnix.


4Chapter


Chapter

5
Web Server component
IDM Web Services J2EE Demo Client

OverviewThe IDM Web Services J2EE Demo Client Web Application is a web-based application developed to test the IDM Web Services Toolkit. It also provides sample code for development involving the IDM Web Services API and so may be used as a test harness.

The demo client allows the following operations supported by the IDM Web Services API:

• Validating passwords, login, and logout

• Searching document collections

• Inserting or importing new documents

• Deleting existing documents

• Updating document titles

• Viewing multi-page or multi-section documents

• Logging custom events

• Accessing queue systems

• Creating versioned document revisions

• Searching revision collections

• Checking in/out and publishing the revisions

• Searching a checked-out revisions list and browsing the details

It is also possible to use the IDM Web Services Demo Client for Windows as a test client. For instructions on installation and configuration, and on this usage, please refer to the IDM Web Services Toolkit for Windows Release Note and the Configuring IDM Web Services: Web Server component chapter of the IDM Web Services Toolkit for Windows Technical Reference.

PrerequisitesThe demo client requires the following additional Vignette products and product components to be installed and configured correctly:

• IDM Server

• IDM Web Services Toolkit (Application Server)

The demo client needs to be deployed on to a web server, and requires a client web browser to operate.

The IDM Web Services J2EE Demo Client can be used in the following web browsers:

• Microsoft Internet Explorer 6.0 SP1


5Chapter

• Netscape Navigator 7.1

Use of the demo client in any other browsers is not supported and may not work. The applet viewer component does not work when using Netscape Navigator 7.1.

ConfigurationThere are three items of configuration for the demo client:

• Java class path

• Path to SSO properties file

• Web Services URI

Java class pathThe Java class path should be modified to include the $WS_DEMO_CLIENT/runtime directory in order for the wsdemoclient.properties and appletviewer.properties files to be picked up by the web server. There are various ways the Java class path can be set and you should use the most appropriate way for your web server.

To modify the Java class path if your web server is JBoss 4.0.3

1. Open the $AS_HOME/bin/run_IDMDomain.sh file for editing.

2. Locate the JBOSS_CLASSPATH environment variable and append $WS_DEMO_CLIENT/runtime to the variable definition.

3. Close the file.

4. Restart JBoss.

To modify the Java class path if your web server is Tomcat 5.x

1. Edit $CATALINA_HOME/bin/catalina.sh.

2. Locate a section with "elif [ "$1" = "start" ] ; then", and add "CLASSPATH=$CLASSPATH:$WS_DEMO_CLIENT/runtime" after the elif line, as follows:

elif [ "$1" = "start" ] ; thenCLASSPATH=$CLASSPATH:$WS_DEMO_CLIENT/runtime

$CATALINA_HOME should be defined in the .profile for the username that installed Tomcat 5.x. This variable must refer to the installation directory of Tomcat 5.x.

3. Close the file.

4. Restart Tomcat 5.x.

Path to SSO properties fileIn order to support SSO (Single Sign On) you must set the path to an SSO configuration file in the file $WS_DEMO_CLIENT/runtime/wsdemoclient.properties.

To configure the path to the SSO configuration file

1. Edit the file $WS_DEMO_CLIENT/runtime/wsdemoclient.properties.

2. Set the variable sso.config.file as follows:

sso.config.file=<WS_DEMO_CLIENT>/runtime/wsdemoclientsso.config

(Remember to set <WS_DEMO_CLIENT> to its correct value.)

3. Close the file.


Web Server component

Web Services URIThe web services URL for the client can be configured using the following configuration settings found in the file $WS_DEMO_CLIENT/runtime/wsdemoclient.properties:

sso.config.file the full path of the file wsdemoclientsso.config

The file wsdemoclientsso.config contains the configurable security key used to communicate with the webservices.

SysServicesURI the URL for the system web services

AppServicesURI the URL for the application web services

DocServicesURI the URL for the document web services

LibServicesURl the URL for the library web services

QueueServicesURI the URL for the queue web services

Using the Demo ClientBefore using the Demo Client, ensure that you have deployed the Demo Client on the web server.

To deploy the Demo Client

1. Deploy the .war file.

On JBoss 4.0

Perform the following:

cp $WS_DEMO_CLIENT/runtime/ws_demo_client_api_test.war <WS_config_domain>/deploy

Where <WS_config_domain> is the JBoss domain for the web server.

On Tomcat 5.x

Perform the following:

cp $WS_DEMO_CLIENT/runtime/ws_demo_client_api_test.war <Tomcat dir>/webapps

Where <Tomcat dir> is the installation directory of Tomcat 5.x.

2. Use this URL to connect to the Demo Client:

http://<host_name>:<port number>/ws_demo_client_api_test

Where <host_name> is the name of the web server hosting IDM Web services J2EE Demo Client and <port number> is the port the Web Server is configured to run on.

Once you have connected to the Demo Client, you will be prompted with a login page requesting a document repository login.

3. Enter the document repository login.


5Chapter


Chapter

6
Applet Viewer
IntroductionThis optional component of the IDM Web Services Toolkit product allows developers to integrate a viewing application into their custom web application developed using the IDM Web Services Toolkit for UNIX.

This chapter is targeted at developers of custom web applications.

The viewing application is a Java-based component, the “applet viewer”, that allows viewing of images retrieved from an IDM Server. The applet viewer provides the following functionality:

• Support for TIFF, JPEG, PNG, GIF file formats

• Display and saving of annotations

• Client based image zooming and rotation

• Viewing of sub-pages

The applet viewer is only supported on Internet Explorer.


6Chapter

ArchitectureThe following diagram describes how the applet viewer fits into an n-tier application developed using the IDM Web Services Toolkit.

The applet viewer is downloaded from the customer web server when the custom web application is accessed.

Browser

Viewer Applet

Web Serv ices Server

IDM Web Services Toolkit

IDM Server

Customer Web Server

Viewer Applet configuration file

Viewer Applet ASPX/JSP pages

HTTP

HTTP/SOAP


Applet Viewer

Installing the applet viewerThe applet viewer package is installed as part of the IDM Web Services Toolkit for UNIX (the Web Server Component).

After a successful installation, the applet viewer package can be found in the directory $WS_DEMO_CLIENT/development/AppletPak. As is, the applet viewer package will not run; it requires integration with a custom web application and re-packaging into a web application archive (.war) file.

The five steps listed in the following sections should be completed in the listed order.

1. Developing applications using the applet viewer

2. Configuring Java Advanced Imaging Support

3. Configuration of the applet viewer

4. Repackaging into a web application archive

5. Deployment of the web application


6Chapter

Developing applications using the applet viewer

In order to use the applet viewer within the custom web application you need to perform the following:

1. Sharing and storage of ticket in the Session object of the web server

The applet viewer web (JSP) pages utilize the IDM Web Services Toolkit API for retrieval of images and retrieval and saving of annotations. In order to function correctly, these web pages need access to the current ticket. As the applet viewer does not log into IDM Server, it assumes that the custom web application will and that this ticket is stored in the Session object of the web server with an index value of “ticket”.

For example, each web service invocation by the applet viewer web pages is performed as follows:

// sessObj variable is of type javax.servlet.http.HttpSessionstring ticket = (string)sessObj.getAttribute("ticket"); // retrieve ticketValidate the ticket using isValid() // validate ticketCall relevant web service method // invoke web servicesessObj.setAttribute("ticket", ticket); // store new ticket

Your custom web application should follow a similar coding strategy.

2. Loading the applet viewer

Loading the applet viewer is a case of invoking a particular web page with an appropriate query string. That particular web page is called ViewerApplet.jsp. The required and optional query parameters for this page are:

Required Parameters:

appname The IDM Application of the requested document

ifn The IFN of the requested document in SSN/DS-ID format

Optional Parameters:

Pg Number of the page to display. This value should be between 1 and the number of pages in the document. The default value is 1.

npages The total number of pages in the requested document. If this parameter is not supplied, this value will be automatically determined. This particular parameter enables/disables the next page/previous page/goto page toolbar buttons.

If this parameter is supplied, then this value will be used regardless of the actual number of pages. For example, npages can be set to 97 even if the document contains only 15 pages.

Examples

Assume that ifn 2/6-1 has 4 pages.

http://testserver/customApp/AppletPak/jsp/viewer/ViewerApplet.jsp?appname=demo&ifn=2/6-1&npages=4&pg=2

This example will load the second page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

http://testserver/customApp/AppletPak/jsp/viewer/ViewerApplet.jsp?appname=demo&ifn=2/6-1

This example will load the first page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.


Applet Viewer

3. Loading an image into an existing instance of the applet viewer

The downloading of the applet viewer every time an image is retrieved can result in wasted bandwidth but more importantly, unacceptable application response. In most cases, it is desirable to download the applet viewer once and load subsequent images into the existing instance of the applet viewer. Again, to do this, it is a case of invoking the appropriate web page with an appropriate query string. This particular web page is called ImageLoader.jsp and the query parameters are the same as those for ViewerAppplet.jsp described in point 2.

Exampleshttp://testserver/customApp/AppletPak/jsp/viewer/ImageLoader.jsp?appname=demo&ifn=2/6-1&npages=4&pg=2

This example will load the second page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

http://testserver/customApp/AppletPak/jsp/viewer/ImageLoader.jsp?appname=demo&ifn=2/6-1

This example will load the first page of 2/6-1 with the next page/previous page/goto toolbar buttons enabled.

4. Tying things together

While points 2 and 3 describe how to load the initial and subsequent images into the applet viewer, some javascript is required to tie these two steps together in a custom web application for seamless operation.

The first thing to understand is that the result of the invocation of ViewerApplet.jsp is a HTML page with the applet viewer tags embedded inside. Additionally there are two frames in this HTML page—one frame to contain and display the applet viewer and another invisible frame that is used to invoke the applet viewer to load subsequent images.

The loading of the subsequent images into the applet viewer is achieved by changing the location property of the second invisible frame with an invocation to the ImageLoader.jsp page. This step is best illustrated with a commented example from the IDM Web Services Demo Client.

The following script can be found in 'resultForm.jsp' in the ws_demo_client_api_test

<SCRIPT language="javascript"><!--

// global array of child pages opened by this pagevar _arrayWin = new Array();

// open a new child window with the given urlfunction openChildWindow(url){

_arrayWin[_arrayWin.length] = window.open(url);return false;

}

// checks whether the specified window has the applet// viewer loaded. Returns true or false.function isAppletWindow(win){

if (win && win.open && !win.closed && win.frames.length >= 2 && win.frames[0] != null){

// If the location property of the first frame// contains 'ViewerApplet', then the applet is loadedframeLocation = win.frames[0].location.toString();if (frameLocation.indexOf("ViewerApplet") != -1){

6Chapter

return true;}

}return false;

}

// open a new child window for the applet viewerfunction openAppletWindow(queryStr){

var loadAppletUrl = 'AppletPak/jsp/viewer/ViewerApplet.jsp?' + queryStr;

var nextImageUrl = 'AppletPak/jsp/viewer/ImageLoader.jsp?' + queryStr;var win;var appletViewerOpen = false;

// loop through the child windows of this page and // locate the applet viewer window.for (i = 0; i < _arrayWin.length; i++){

win = _arrayWin[i];appletViewerOpen = isAppletWindow(win);if (appletViewerOpen){

break;}

}

if (!appletViewerOpen){

// no applet viewer window has been opened_arrayWin[_arrayWin.length] = window.open(loadAppletUrl);

}else{

// an applet viewer window has been opened so// load the image into the existing applet// the loading of the image is achieved by changing// the location of the second frame in the applet pagewin.frames[1].location = nextImageUrl;

}return false;

}--></SCRIPT>

NOTE: The above code only works with Microsoft Internet Explorer.


Applet Viewer

Configuring Java Advanced Imaging Support

Java Advanced Imaging (JAI) Support is software used by the applet viewer to help display TIFF and JPG images. The JAI software package is installed if the applet viewer detects that it is not available.

To ensure that JAI support for the applet viewer is correctly downloaded

This procedure requires that you have a JDK installed, so that you can use tdpviewer.jar.

If there is no JDK installed, you can transmit MANIFEST.MF and tdpviewer.jar to some other machine that does have a JDK (via binary mode FTP or some other mechanism), perform the following operations, with suitable adjustments to the paths, and then transmit the files back.

1. Ensure that you have a JDK installed.

2. Change directory to <custom web app dir>\AppletPak\JRE.

3. Open MANIFEST.MF for editing, and look for the line reading

jai-Implementation-URL: http://172.16.1.233/tower/jsp/jre/jai_win.jar

Change the URL to a value with the following convention:

http://<custom web server hostname or IP address>/<custom web app dir>/AppletPak/jre/jar-win.jar

For example:

http://testserver/demoapp/AppletPak/jre/jar-win.jar

If the default port number of 80 is not being used, specify the custom port number as part of the custom web server hostname.

4. Change directory to <custom web app dir> and run the following command:

jar -ufm viewer/tdpviewer.jar jre/MANIFEST.MF


6Chapter

Configuring the applet viewerThe configuration file appletviewer.properties, included as part of the installation, does not work in isolation. The configuration file must be included as part of the deployment of the custom web application. At runtime, the configuration file is located using the classpath of your web application container.

The following are descriptions of the configuration values used by the applet viewer:

Configuration variable Description

av.Logger.TraceLevel This is a trace switch controlling the amount of tracing information output by the applet viewer web pages to the configured trace file.

1 = traces error messages only2 = traces errors and warnings3 = traces informational messages4 = verbose/debug trace information

Default value is 3

av.Logger.Filename The name and location of trace file used by the applet viewer web pages.

Default value is

LOGFILE_PATH/appletviewer.log

av.DocServices.URL This is a URL to the DocServices web service. A valid URL must be entered for this variable.

Default value is

http://<WS_hostname>:<WS_portnum>/vidm_wst_server/DocServices

Where <WS_hostname> and <WS_portnum> are the appropriate application server hostname and port number.

av.SysServicesURL This is a URL to the SysServices web service. A valid URL must be entered for this variable.

Default value is

http://<WS_hostname>:<WS_portnum>/vidm_wst_server/SysServices

Where <WS_hostname> and <WS_portnum> are the appropriate application server hostname and port number.

av.props.display This variable controls how the image is displayed within the applet viewer window.

0 = Original image size1 = Fit to width2 = Fit to height3 = Fit to windowOther values = Original image size

Default value is 0.

av.props.extractrgn Enables or disables the extract region button in the applet viewer toolbar. The button should be disabled as this functionality is not available.

0 = disabled1 = enabled

Default value is 0.


Applet Viewer

av.props.blankrgn Enables or disables the blank region button in the applet viewer toolbar. The button should be disabled as this functionality is not available.


Default value is 0.

av.props.emailfax Enables or disables the email/fax button in the applet viewer toolbar. The button should be disabled as this functionality is not available.


Default value is 0.

av.props.docexport Enables or disables the document export button in the applet viewer toolbar. The button should be disabled as this functionality is not available.


Default value is 0.

av.props.maxsubpages Configures the maximum number of sub-pages that can be displayed for a particular page.

Default value is 10 sub-pages.

av.props.maxzoomheight The maximum zoom height of image (in pixels).

Default value is 1200 pixels.

av.props.maxzoomwidth The maximum zoom width of image (in pixels).


av.props.minzoomheight The minimum zoom height of image (in pixels).


av.props.minzoomwidth The minimum zoom height of image (in pixels).


av.props.imagetype Controls the type of image displayed in the applet viewer—that is color, grayscale or black and white.

color = as a color image gray = as a grayscale image mono = blank and white image

The default value is color.

av.props.sizefactor The annotation size factor which is the ratio between the image size and the initial annotation. The size factor is specified in percentage. Possible size factors range from 1 to 50.

The default value is 10.

av.props.highlights Defines the number of highlight buttons in the applet viewer annotation toolbar.

Default value is 4.

av.props.highlight.color.n Color property of the nth highlight definition.

av.props.highlight.translucency.n Translucency property of the nth highlight definition. Possible values are OPAQUE or TRANSLUCENT.

av.props.underlines Defines the number of underline buttons in the applet viewer annotation toolbar.

Default value is 2.

av.props.underline.color.n Color property of the nth underline definition.



6Chapter

av.props.underline.width.n Width property of the nth underline definition in pixels. This controls the thickness of the underline.


av.props.stickynotes Defines the number of sticky notes buttons in the applet viewer annotation toolbar.

Default value is 3.

av.props.stickynote.color.n Color property of the nth sticky note definition.

av.props.stickynote.maxnumchar.n Maximum number of characters property of the nth sticky note definition. This controls the number of characters allowed in a sticky note.

Default value is 1024 characters.

av.props.margincomments Defines the number of margin comment buttons in the applet viewer annotation toolbar.

Default value is 2.

av.props.margincomment.color.n Color of the nth margin comment definition.

av.props.margincomment.font.n Font property of the nth margin comment definition. Possible values are TIMESROMAN and SERIF.

av.props.margincomment.charheight.n Character height property of the nth margin comment definition in points.

Default value is 240 points.

av.props.margincomment.style.n Style property of the nth margin comment definition.

av.props.freehands Defines the number of freehand buttons in the applet viewer annotation toolbar.

Default value is 3.

av.props.freehand.color.n Color property of the nth freehand definition.

av.props.freehand.width.n Width property of the nth freehand definition in pixels. This controls the thickness of the freehand.


av.props.ellipses Defines the number of ellipses buttons in the applet viewer annotation toolbar.

Default value is 2.

av.props.ellipse.color.n Color property of the nth ellipse definition.

av.props.ellipse.width.n Width property of the nth ellipse definition in pixels. This controls the thickness of the ellipse.


av.props.smoothshape Enables or disables anti-aliasing of images when zooming.

0 = disable 1 = enable

Default value is 1.

av.props.showsavedialog Enables or disables notification to save annotations if annotations have not been saved.

0 = disable1 = enable

Default value is 1.



Applet Viewer

NOTES:

1. Settings for line width and character height are provided for compatibility with other IDM products only; they have no effect in the applet viewer.

2. Available color names are the standard Java color names: BLACK, BLUE, CYAN, DARKGRAY, GRAY, GREEN, LIGHTGRAY, MAGENTA, ORANGE, PINK, RED, WHITE and YELLOW. Colors can also be specified as RGB values, in the form “<red value>.<green value>.<blue value>”, where each value lies in the range 0–255. For example, “0.0.0” is black and “255.255.255” is white.

av.props.loadzoomdialog Enables or disables the zoom factor dialog for TIFF images. This setting is not available in the applet viewer package.

0 = disable1 = enable

Default value is 1.

av.sso.config.file The full path to the applet viewer’s SSO (that is, Single Sign-On) configuration file:

<WS_DEMO_CLIENT>/runtime/appletviewersso.configThis file contains the configuration security key used to communicate with the web services.



6Chapter

Repackaging into a web application archive

This section describes the steps required to package the applet viewer and custom web application into an archive that can be deployed to the application server. For the purposes of this exercise, we will assume the custom web application is named TestApp and is located in a directory named TestApp. It is also assumed that the previous three sections have been completed.

1. Copy all of the contents of $WS_DEMO_CLIENT/development/AppletPak into the custom web application directory. For example:

cp -r $WS_DEMO_CLIENT/development/AppletPak TestApp

where WS_DEMO_CLIENT is the directory where the J2EE demo client is installed.

2. Extract the applet viewer JSP and servlet code.

cd TestAppmkdir WEB-INF/classes

(assumes there is a WEB-INF directory, if not create it first)

cd WEB-INF/classesjar xvf ../../AppletPak/appletpakcode.jarrm -rf META-INF

You should now have a set of class files in the WEB-INF/classes directory.

3. Copy the Java Web Services Developers’ Pack libraries to your web application:

cd TestAppmkdir WEB-INF/libcd WEB-INF/libcp $WS_DEMO_CLIENT/development/JWSDPPak/* . (Note the dot)

4. Web application deployment file

Every J2EE web application has a deployment file named web.xml. This file instructs the application server to setup the desired environment for your web application. This file is located in the WEB-INF directory. In this example, this would be TestApp/WEB-INF.

The content of $WS_DEMO_CLIENT/development/AppletPak/config/web.xml needs to be merged to the deployment file of the custom web application. This is a manual process and essentially involves cutting and pasting the relevant sections from one file to another.

NOTE: Group your sections together. For example, group all “context-param”information together. Otherwise your web application may not deploy correctly.

For example, the deployment file of the TestApp web application could look like the following:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app><context-param>

<param-name>traceFile</param-name>


Applet Viewer

<param-value>/tmp/TestApp.log</param-value><description>

Trace file of web application</description>

</context-param>

<servlet><servlet-name>ViewerGetConfig</servlet-name><servlet-class>

com.towertechnology.servlet.ViewerGetConfig</servlet-class>

</servlet><servlet>

<servlet-name>ViewerDocRetriever</servlet-name><servlet-class>

com.towertechnology.servlet.ViewerDocRetriever</servlet-class>

</servlet><servlet>

<servlet-name>ViewerGetAnnot</servlet-name><servlet-class>

com.towertechnology.servlet.ViewerGetAnnot</servlet-class>

</servlet><servlet>

<servlet-name>ViewerSetAnnot</servlet-name><servlet-class>

com.towertechnology.servlet.ViewerSetAnnot</servlet-class>

</servlet><servlet>

<servlet-name>InitServlet</servlet-name><servlet-class>

com.towertechnology.servlet.InitServlet</servlet-class><load-on-startup>1</load-on-startup>

</servlet><servlet-mapping>

<servlet-name>ViewerGetConfig</servlet-name><url-pattern>/AppletPak/ViewerGetConfig</url-pattern>

</servlet-mapping><servlet-mapping>

<servlet-name>ViewerDocRetriever</servlet-name><url-pattern>/AppletPak/ViewerDocRetriever</url-pattern>


<servlet-name>ViewerGetAnnot</servlet-name><url-pattern>/AppletPak/ViewerGetAnnot</url-pattern>


<servlet-name>ViewerSetAnnot</servlet-name><url-pattern>/AppletPak/ViewerSetAnnot</url-pattern>

</servlet-mapping></web-app>

Note that in the above listing, there is a setting named traceFile, which we will assume is a setting required by the TestApp web application.

5. Copy $WS_DEMO_CLIENT/development/AppletPak/config/appletviewer.properties to a directory that can be located by the application server or web server classpath.

6. Edit appletviewer.properties (in its new location) and modify the following configuration variables:


6Chapter

• av.Logger.Filename (location of trace file)

• SysServices.URL

• DocServices.URL

7. Remove the AppletPak config directory which is not required in the war file

rm -rf TestApp/AppletPak/config

8. Creating the archive

To archive the whole web application, simply execute

jar cvf TestApp.war -C TestApp/ .

(note that there is a space and a dot after the forward slash

This command should be run in the parent directory of TestApp.

To verify that you have packaged the application correctly, execute

jar tvf TestApp.war

You should see output similar to the following:

0 Mon Oct 18 14:12:02 EST 2004 META-INF/53 Mon Oct 18 14:12:02 EST 2004 META-INF/MANIFEST.MF0 Mon Oct 18 14:12:02 EST 2004 WEB-INF/0 Mon Oct 18 14:12:02 EST 2004 WEB-INF/classes/0 Mon Oct 18 14:11:50 EST 2004 WEB-INF/classes/com/0 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/0 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/0 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/generic/0 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/security/0 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/0 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/1336 Mon Oct 18 14:11:50 EST 2004 WEB-INF/classes/com/towertechnology/jsp/generic/DocInfo.class851 Mon Oct 18 14:11:50 EST 2004 WEB-INF/classes/com/towertechnology/jsp/generic/Params.class2701 Mon Oct 18 14:11:50 EST 2004 WEB-INF/classes/com/towertechnology/jsp/generic/TdpJbError.class1491 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/generic/TdpJbException.class1147 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/security/WebAppInitializer.class1761 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/security/WebAppMonitor.class2961 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/Base64.class3780 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/DataConverter.class1814 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/FileLogger.class3049 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/Logger.class303 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/Traceable.class2330 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/jsp/util/ResourceLocator.class625 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/InitServlet.class3667 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/ServletUtil.class9483 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/ViewerDocRetriever.class


Applet Viewer

5226 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/ViewerGetAnnot.class3471 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/ViewerGetConfig.class8177 Mon Oct 18 14:11:52 EST 2004 WEB-INF/classes/com/towertechnology/servlet/ViewerSetAnnot.class0 Mon Oct 18 14:11:56 EST 2004 AppletPak/0 Mon Oct 18 14:11:56 EST 2004 AppletPak/viewer/0 Mon Oct 18 14:12:00 EST 2004 AppletPak/jre/0 Mon Oct 18 14:12:00 EST 2004 AppletPak/config/0 Mon Oct 18 14:11:56 EST 2004 AppletPak/jsp/0 Mon Oct 18 14:12:00 EST 2004 AppletPak/jsp/misc/0 Mon Oct 18 14:12:00 EST 2004 AppletPak/jsp/viewer/0 Mon Oct 18 14:12:02 EST 2004 AppletPakTest/328461 Mon Oct 18 14:11:56 EST 2004 AppletPak/viewer/tdpviewer.jar10237888 Mon Oct 18 14:11:58 EST 2004 AppletPak/jre/jre-win.exe5482423 Mon Oct 18 14:12:00 EST 2004 AppletPak/jre/jai_win.jar413 Mon Oct 18 14:12:00 EST 2004 AppletPak/jre/MANIFEST.MF2062 Mon Oct 18 14:12:00 EST 2004 AppletPak/jsp/misc/ViewerError.jsp…

9. Deployment

Now deploy the web application (TestApp.war) to your application server or web server. If the web application does not deploy, ensure that the application server or web server can locate appletviewer.properties using the classpath. Note that modifications to the classpath may require that your application server or web server be restarted.

To use your web application, start a web browser and enter a URL with the following format:

http://<app server - web server hostname>:<port number>/<name of war file>

For example:

http://testbox:8080/TestApp


6Chapter

Common issues

JREThe applet viewer requires the presence of the Sun Java Runtime Environment on the user’s PC in order to function. Ideally this should already be installed but if it is not installed, the user will be prompted to download and install the Sun JRE plug-in. The plug-in will be downloaded from AppletPak/JRE/jre-win.exe on the customer web server. If an earlier version of the Sun Java Runtime Environment is installed on the user’s PC Vignette recommends that you uninstall it and install the current version in its place.

For the correct versions, please consult the Supported Platforms Matrix.

NOTE: In some cases, the download of the Sun JRE may not have the requiredAuthentiCode. If this occurs, the browser settings must be changed to allow the downloadof unsigned ActiveX controls, or an error message will be displayed. The browser settingonly needs to be enabled for the download, and once the JRE has been downloadedsuccessfully, the setting should be changed back to disabled.

The system administrator can supply the AuthentiCode for the JRE themselves, in whichcase the browser setting is irrelevant. In this configuration, the user will be prompted todownload the Sun JRE plug-in every time a document is selected until the Sun JRE isinstalled.

A message Unsupported document type will be displayed in the applet’s status bar if a document’s format is not supported by JRE/JAI (only GIF, TIFF, PNG, JPEG are supported).

The viewer applet supports English and German languages. The required language must be installed on the machine and the Windows locale must be set to the appropriate country.

Large TIFF imagesWhen the applet viewer is used to view a TIFF image, best efforts are made to display the image as close as possible to its original size. If the image viewed is too large, a Java Virtual Machine (JVM) “out of memory” exception may be thrown.

The larger the image, the longer it will take to appear on screen. If this exception is being thrown, it can be resolved by increasing the amount of memory available to the JVM. This can be done by setting minimum and maximum heap limit for the JVM.

To set the minimum and maximum heap limits for the Java Virtual Machine

1. Open the Java plug-in control panel at Start -> Settings -> Control Panel -> Java plug-in

2. Select the Advanced tab.

3. In the Java Runtime Parameters text box, enter the following:

-Xms128m -Xmx256m

These values are illustrative only; the values configured are dependent on the physical memory installed on the PC. More information about these parameters can be obtained from the Sun web site.


Applet Viewer

Using the applet viewerThe applet viewer runs within a browser window or within a frame. This is dependent on how the custom web application has been designed to display the applet viewer. In any case, a toolbar is displayed above the displayed image. The current page and subpage number are shown in the status bar at the lower right-hand corner of the window. The applet viewer can be resized by clicking and dragging the sides or corners of the display window or frame.

The scale (resolution) of the initial display is the original size of the image but you can use the zoom in, zoom out and zoom to rectangle functions to change the scale of the displayed image.

When positioned over the displayed image (with zoom to rectangle disabled), the mouse pointer takes the shape of a four-pointed arrow. You can click-and-drag the image to reposition it in the frame, as an alternative to using the scroll bars.

Viewer applet toolbarThe complete viewer applet toolbar is shown below. Note that, depending on your applet viewer configuration, you might not have access to all toolbar functions.

Viewer applet toolbar

First page: Display the first page of the document. This option will be visually disabled if the first page is currently displayed.

Previous page: Display the previous page of the document. This option will be visually disabled if the first page is currently displayed.

Go to page: Display a dialog where you can enter the required page of the document. This option will be visually disabled if the current document has only one page..

Next page: Display the next page of the document. This option will be visually disabled if the last page is currently displayed.

Last page: Display the last page of the document. This option will be visually disabled if the last page is currently displayed.

Zoom to rectangle: Enlarge a selected rectangular area to the limit of the frame. To define the rectangular area, position the pointer (a hand) over one corner of the rectangle; when you hold down the left mouse button, the pointer changes to a cross-hair. Move the cross-hair to the opposite corner of the rectangle, then release the button.

Zoom in: Enlarge the currently displayed image by a factor of 1.5 both vertically and horizontally.

Zoom out: Reduce the currently displayed image by a factor of 1.5 both vertically and horizontally.

Fit to width: Scale the displayed image to occupy the width of the frame.

Fit to height: Scale the displayed image to occupy the height of the frame.

Restore original size: Rescale the displayed image to its default size.


6Chapter

AnnotationsIf your user ID is set up to do so, you can use the viewer applet to add annotations to a document. Annotations can take several forms:

• Overlay highlight—an opaque rectangle that you can draw anywhere on the image.

• Underlay highlight—a transparent rectangle that you can draw over any part of the image.

• Freeform line—a line of any shape and length that you can draw over any part of the image.

• Straight line—generally used to underline text.

• “Sticky note”—a “piece of sticky paper” on which you can type any text.

• Margin note—a textual note that you can write anywhere on the image.

• Oval—a closed oval line of any size that you can draw around any part of the image.

The annotations toolbarThe default annotations toolbar is shown below. Note that your system administrator might have given you a different selection of colors for some or all types of annotation.

Annotations toolbar

Rotate to left: Rotate the displayed image 90 degrees anti-clockwise.

Rotate 180 degrees: Rotate the displayed image 180 degrees.

Rotate to right: Rotate the displayed image 90 degrees clockwise.

Annotations: Toggle to show or hide the annotations toolbar. (See Annotations on page 52.)

Print: Print the current document, including any annotations.

Overlay highlight (black):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. The rectangle will be filled with the chosen color and will be opaque. Use these like a conventional marker pen.

Overlay highlight (white):

Underlay highlight (yellow):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. The rectangle will be filled with the chosen color and will be transparent. Use these like a conventional highlighter pen.

Underlay highlight (green):

Freeform line (green):

Holding down the left mouse button, use the cross-hair cursor to draw a line of any shape and length (including curves, loops, and polygons) in the chosen color.Freeform line

(blue):

Freeform line (white):


Applet Viewer

Viewing annotationsWhenever an annotated document is displayed, all annotations are visible. However, although “sticky notes” are visible, the text in them is not visible. You can view (and, if you wish, modify) the text by double clicking the note; the text then appears in a pop-up window. Other annotations may be moved or resized by dragging them or by clicking and dragging their edges.

Saving annotationsUsually, any additions or changes you make to the annotations on a page will be saved when you click on the Save Annotations button, or when you move to another page of the document. (If you move to a different document without saving your new annotations, they will be lost.) However, it can happen that another user has made and saved changes to the same annotation at the same time. In such a case, your changes will not be saved, because they would over-write the other user’s changes that have already been saved. Instead, you will receive a message telling you that there is a conflict, and that one or more annotation changes have not been saved.

Underline (blue):

Holding down the left mouse button, use the cross-hair cursor to draw a straight line of any length in the chosen color.

Underline (red):

Oval (red):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. An oval ring (ellipse) of the chosen color will be drawn to the edges of the rectangle.Oval

(gray):

Sticky note (pink):

Click where you want to place the sticky note. A pop-up window will then allow you to type any text onto the note. The note will appear as a rectangle of the chosen color.Sticky note

(green):

Sticky note (blue):

Margin comment (red):

Holding down the left mouse button, use the cross-hair cursor to draw a rectangle. A pop-up window will then allow you to type any text as a note. The text will appear in the chosen color.Margin comment

(yellow):

Save annotations: Save all annotations attached to the current document. Annotations will be saved automatically if you move to another page of the document (but refer to Saving annotations on page 53). This button is only available if you have relevant permission; check with your system administrator.)

Delete annotations: Remove all annotations from the document. (To delete a single annotation, right-click on it, then choose Annotation > Delete.)


6Chapter

Viewer applet context menuIn the viewer applet, the following facilities are available through the context menu, displayed by right-clicking on the image:

Menu option

Submenu option

Purpose

Properties Displays the properties of the current document page/subpage (the page/subpage under the pointer when you right-clicked).

Undo Reverses the last annotation change (disabled if the last action cannot be undone). Multiple undo is supported; actions will be undone in reverse sequence.

Close Subpage Closes the current document subpage (the subpage under the pointer when you right-clicked).

Page Closes the current document page (the page under the pointer when you right-clicked).

Document Closes the current dcoument.

Reload Subpage Reloads the subpage.

Page Reloads the page.

Document Reloads the document.

Order Vertical If multiple pages or subpages are open, they will be arranged in page/subpage number sequence from left to right.

Horizontal If multiple pages or subpages are open, they will be arranged in page/subpage number sequence from top to bottom.

Select Select Subpage The current subpage or page is selected (e.g., for printing); a broken line is drawn around it in the display frame. Disabled if the current subpage or page is already selected.

Unselect Subpage

If the current subpage or page is selected, as shown by a broken line around it in the display frame, it will be unselected, and the broken line around it will be removed. Disabled if the current subpage or page is not selected.

Select All All displayed subpages or pages are selected (e.g., for printing); a broken line is drawn around them in the display frame. Disabled if all displayed subpages or pages are already selected.

Unselect All All currently selected subpages (or pages) are unselected; the broken line around them is removed. Disabled if no displayed subpages or pages are selected.

Options Zoom On Server If checked, all requests for zoom in or out will be processed on the server, and the resultant image sent to the browser.If unchecked, all requests for zoom in or out are processed locally.

Smooth Shape If checked, “anti-aliasing” will be applied in order to smooth transitions between colors. Anti-aliasing improves the appearance of continuous-tone (photographic) images, but is generally unsuitable for bitmap images.If unchecked, anti-aliasing is not performed.Note that anti-aliasing of large images can impose a heavy processing load.

Show Save Dialog

If checked, you will be prompted to confirm saving any changed annotations when you move to another page of the document.If unchecked, changed annotations will be saved without prompting when you move to another page of the document.

Show On Load Zoom Dialog

If checked, then whenever a “big tiff” document (document whose size prevents a display in max. zoom, defined by the system administrator in ttuws.props) is requested, a message will be displayed.


Applet Viewer

Multi-page documentsIf the displayed document contains multiple pages, the viewer applet can display more than one at the same time. If you already have a page open, opening another page (with Next Page, Previous Page, or Goto Page) will open the new page without closing any current page.

It is possible to zoom out on all open pages to reduce them to “thumbnail” size. You can click-and-drag individual pages. The zoom, scale, and rotate buttons on the toolbar act on the last page you clicked on.

You can navigate through multi-page (or multi-subpage) documents using the keyboard:

SubpagesIf the displayed document page includes subpages, a small subpage navigation bar appears below the vertical scroll bar in the display frame.

Viewer applet showing document with subpages

The subpage navigation bar looks like this:

Subpage navigation bar

Image type

Monochrome Sets color depth to monochrome.

Gray Sets color depth to gray scale.

Full Color Sets color depth to full color.

Function Key

Previous Page PageUp

Next Page PageDown

Previous Subpage Ctrl+PageUp

Next Subpage Ctrl+PageDown

Menu option

Submenu option

Purpose

Document display

Subpage navigation bar


6Chapter

Go to the previous subpage.

Display a dialog allowing you to enter the number of the subpage you want to navigate to. If the number you enter is greater than the number of subpages, the last subpage will be displayed.

Go to the next subpage.


Appendix

A
JBoss administration
Managing JBoss Application Server

Startup

NOTE: Ensure that IDM Server and all CORBA services have started up before proceedingto start up the JBoss Application Server.

To startup the JBoss Application Server for the IDM domain

1. Ensure that you are logged in as the tower user:

2. Perform

cd $AS_HOME/bin./run_IDMDomain.sh &

Shutdown

To shutdown the JBoss Application Server

1. Ensure that you are logged in as the tower user:

2. Perform

cd $AS_HOME/bin./shutdown.sh –S

Accessing the console

To access the administration console of the JBoss Application Server

1. Start a web browser.

2. Enter the following URL: http://<as_host_name>:8080.

where <as_host_name> is the host name of the server hosting the JBoss Application Server.

Web services consoleThis console allows a user to check what web services have been deployed in JBoss.

1. Start a web browser


AAppendix

2. Enter the following URL:

http://<as_host_name>:8080/ws4ee

where <as_host_name> is the host name of the server hosting the JBoss application server.


Index

.

.NET 7, 20

AAnnotations 52

saving 53viewing 53

appletviewer.properties 32, 42–45, 47, 49AS_CONFIG_DOMAIN 15AS_HOME 15

Cconfiguration, Java Virtual Machine 27

DDB2 17, 20, 21demo client, J2EE 31

Eencrypted password 24English language 26, 50exceptions messages, SOAP 25

GGerman language 50

Hhost.props 17, 19–20

IIDMConfiguration.xml 17, 21–23iiop-service.xml 17Internet Explorer 35iwstu.logging.properties 19

IDM Web Services Toolkit fov20.1 rev 1

JJ2EE demo client 31Java Virtual Machine 27, 50

configuration 27JVM. See Java Virtual Machine.

Llanguage

English 50German 50other than English 26

log4j.xml 17login-config.xml 24

N.NET 7, 20

OOracle 17, 20, 21orb.props 20–21

Ppassword 20

encrypted 24

Rrendering 29

SSingle Sign-On. See SSO.SOAP 6, 8

exceptions messages 25SQL Server 17, 20, 21SSO 23, 32, 33, 45subpages 55

r Unix Technical Reference 59

Index

Ttest harness. See demo client.Toolbars

annotations 52viewer applet 51

ttuws.props 54

UUnicode 26username 20UTF-8 26

Vvignette-ds.xml 18, 20–25

WWeb Services Interoperability standards 6web.xml 46wsdemoclient.properties 32, 33wsdemoclientsso.config 33WS-I. See Web Services Interoperability stan-dards 6WSTestConfig.xml 20


IDM Web Services Toolkit for Unixdocumation.net.au/bojan/IWSTU_20.1_tech.pdfv20.1 rev 1 IDM Web...

Documents

Transcript of IDM Web Services Toolkit for Unixdocumation.net.au/bojan/IWSTU_20.1_tech.pdfv20.1 rev 1 IDM Web...