Download Best practices for large document and resource caching in an

Debugging a Custom Content Manager OnDemand Web
Enablement Kit Java API Web Application.
12/15/2007
Author: Bob Lichens
Software Engineer
IBM Content Management OnDemand Development
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 1 of 9
This article will delineate how to debug the most common mistakes made while writing a Java™
application which uses the IBM® Content Manager OnDemand Web Enablement Kit Application
Programming Interface set (referred to hereafter as simply ODWEK). It will direct you in gathering
information that support will need to assist with problematic applications. Following this guide will
promote robust application development and reduce the need for support calls.
What is IBM OnDemand Web Enablement Kit Java APIs (ODWEK)?
The ODWEK Java API provides industry standard Java™ classes that can be used by a customer to
write a custom web application that can access data stored on the OnDemand Server. This custom
application can, for example, permit the end user to logon to an OnDemand server, get a list of folders,
search a specific folder, generate a hitlist of matching documents and retrieve those documents for
viewing. There are also many APIs to provide advanced functionality as well.
Prerequisites: This document addresses features and functionality that are only available in ODWEK
Versions 7.1.2.5 or later (including ODWEK 8.4.0.0 and later).
ODWEK Java API Coding “Best Practices”
The OnDemand development team has prepared a document with recommendations of how to best use
the ODWEK Java APIs for performance and endurance savvy applications. Please read the IBM
TechDoc “Best practices for building Web Applications using IBM Content Manager OnDemand Java
API’s” <link > to make sure you fully understand how the ODWEK Java APIs interface with the JVM
and OnDemand Systems to avoid common coding mistakes.
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 2 of 9
How to enable ODWEK Trace engine
1.) In the ODConfig initialization calls you can specify traceDir and traceLevel parameters.
public ODConfig(String afpViewer,
String lineViewer,
String metaViewer,
long maxHits,
String appletDir,
String language,
String tempDir,
String traceDir,
int traceLevel)
Trace Levels are
traceLevel = 1 Error trace only
traceLevel = 2 Error and Warnings
traceLevel = 3 Error, Warnings, and Info
traceLevel = 4 All, includes all of the above and complete flow tracing
Tip: Tracing can be set to many different levels by the traceLevel parameter. When troubleshooting an
ODWEK issue, set the trace level to the highest level, unless otherwise specified by IBM support.
Tip2: The lower trace levels are ideal for monitoring an ODWEK application that is in a steady state,
while higher levels are typically used for troubleshooting a current ODWEK issue. For example, setting
the trace at lower levels, Trace=1, creates minimal overhead while alerting you of only error conditions.
2.) A new arswww.trace trace file is created in the directory referenced by the TraceDir parameter each
time the ODWEK application is restarted.
3.) Previous arswww.trace files are renamed to arswww.trace<timestamp> and will need to be manually
deleted at regular intervals to avoid exhausting the traceDir file system.
The Anatomy of Arswww.trace Output.
The arswww.trace logging functionality provides details on the Native/JNI activity of the ODWEK
processes. From the arswww.trace file you can gather in depth details on ODExceptions that may have
been thrown, detailed error messaging specific to the Native/JNI layer that can help diagnose
OnDemand Server problems, and other ODWEK specific errors. The arswww.trace includes
timestamps with sub second granularity which can be a valuable tool in debugging suspicious
performance and hang conditions. This timestamp information can be used to help isolate possible
bottlenecks in ODWEK, the Java™ Application Server, and OnDemand Server request processing. At
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 3 of 9
TraceLevel=4, ODWEK will provide complete Native/JNI function flow tracing. You can see exactly
which methods are in use by your program, and where time may be spent in relation to each call.
The arswww.trace output includes the following columns, output in Comma Separated Format. The
values displayed are
PID
= This is the Parent process id.
PPID
= This is the current working/child process id.
TID
= The current thread id for this request. Typically maps to an end user
session.
DATE
= Date in Month/Day/Year format.
TIME
= Transaction timestamp.
LEVEL
= Level of message.
Possible Msg Types are:
ERROR
= Error messages.
WARNING = Warning messages
INFO
= Informational messages. Typically to assist in
problem determination.
ENTER
= Function Flow messaging.
RETURN = Function Flow messaging.
FUNCTION = The Native function name where the message is generated.
NOTE: Function names with “Java_com_ibm_edms_od_” pre-pended
indicate the base JNI call that is made directly from Java™ Virtual Machine. All other
functions are internal ODWEK methods that are called within this
JNI function.
OUTPUT
= This is where the actual message text will be displayed. This will
be a string with additional message details. In the case of an
ENTER/RETURN Message type, you will see a numeric value that
represents the ODWEK Session ID for this function call.
Here is an example of the raw arswww.trace output for a typical ODHit.retrieve() call, with TraceLevel
set to 4.
PID,PPID,TID,DATE,TIME,LEVEL,FUNCTION,OUTPUT
4196,3272,316,12/17/07,13:59:42.145,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,DocID = v7126-19459-19460-19461-ACF11FAAA-0-27629619-0-2762961985-68-0-1-0-^^ATEST TIFF
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 4 of 9
4196,3272,316,12/17/07,13:59:42.145,ENTER,apiP_OpenFolderByName,
4196,3272,316,12/17/07,13:59:42.145,INFO,apiP_OpenFolderByName,Opening [test-LargeTiff]
4196,3272,316,12/17/07,13:59:42.145,RETURN,apiP_OpenFolderByName,RC=0
4196,3272,316,12/17/07,13:59:42.145,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,Doc Type is 'T'
4196,3272,316,12/17/07,13:59:42.145,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,pViewer = native
4196,3272,316,12/17/07,13:59:42.145,ENTER,Util_updateSessionViewOpts,
4196,3272,316,12/17/07,13:59:42.145,RETURN,Util_updateSessionViewOpts,
4196,3272,316,12/17/07,13:59:42.145,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,Retrieve Data Compressed.
4196,3272,316,12/17/07,13:59:44.999,ENTER,JNIDataCallback,
4196,3272,316,12/17/07,13:59:46.181,RETURN,JNIDataCallback,RC=0
4196,3272,316,12/17/07,13:59:46.191,ENTER,JNIDataCallback,
4196,3272,316,12/17/07,13:59:46.191,RETURN,JNIDataCallback,RC=0
4196,3272,316,12/17/07,13:59:46.291,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,Document segment written to file [27629619] bytes
4196,3272,316,12/17/07,13:59:46.301,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,Document Compression Type is 'D'
4196,3272,316,12/17/07,13:59:46.301,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,DocType = T
4196,3272,316,12/17/07,13:59:46.301,INFO,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,AFP Viewer = 8
4196,3272,316,12/17/07,13:59:46.751,RETURN,Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve,1167736032 RC=0
The following table shows the arswww.trace details for the same ODHit.retrieve() call. (As viewed in
Excel CSV format for clarity.)
PPID
3272
PID
4196
TID
316
DATE
12/17/2007
TIME
13:59:42
LEVEL
ENTER
FUNCTION
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
OUTPUT
1167736032
DocID = v7126-19459-19460-19461-ACF11FAAA-0-27629619-0-27629619-85-68-0-1-0^TEST TIFF
3272
3272
3272
4196
4196
4196
316
316
316
12/17/2007
12/17/2007
12/17/2007
13:59:42
13:59:42
13:59:42
INFO
ENTER
INFO
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
apiP_OpenFolderByName
apiP_OpenFolderByName
3272
3272
3272
3272
4196
4196
4196
4196
316
316
316
316
12/17/2007
12/17/2007
12/17/2007
12/17/2007
13:59:42
13:59:42
13:59:42
13:59:42
RETURN
INFO
INFO
ENTER
apiP_OpenFolderByName
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
Util_updateSessionViewOpts
3272
3272
3272
4196
4196
4196
316
316
316
12/17/2007
12/17/2007
12/17/2007
13:59:42
13:59:42
13:59:45
RETURN
INFO
ENTER
Util_updateSessionViewOpts
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
JNIDataCallback
3272
3272
4196
4196
316
316
12/17/2007
12/17/2007
13:59:46
13:59:46
RETURN
ENTER
JNIDataCallback
JNIDataCallback
RC=0
3272
4196
316
12/17/2007
13:59:46
RETURN
JNIDataCallback
3272
3272
3272
3272
4196
4196
4196
4196
316
316
316
316
12/17/2007
12/17/2007
12/17/2007
12/17/2007
13:59:46
13:59:46
13:59:46
13:59:46
INFO
INFO
INFO
INFO
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
RC=0
Document segment written to file [27629619]
bytes
Document Compression Type is 'D'
DocType = T
AFP Viewer = 8
3272
4196
316
12/17/2007
13:59:47
RETURN
Java_com_ibm_edms_od_ArsWWWInterface_apiRetrieve
1167736032 RC=0
Opening [test-LargeTiff]
RC=0
Doc Type is 'T'
pViewer = native
Retrieve Data Compressed.
* See ODWEK Error Reporting Section at the end of this document regarding more details on what
errors can be thrown and how the error codes that ODWEK reports are generated.
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 5 of 9
How to prepare for getting support from the IBM Software Support.
If you are unable to determine the root cause of a problem with ODWEK, you can open a Problem
Management Record with the IBM Software Support Team.
General IBM OnDemand Web Enablement Kit Support site
To speed up the Problem Determination process, it is required that you gather the arswww.trace and
other diagnostic information as is detailed in “MustGather: IBM Content Manager OnDemand Web
Enablement Kit Java API “
To avoid unnecessary delays, it is recommended to collect all MustGather documentation for your
specific problem scenario you are experiencing before contacting IBM Software Support.
Details are found here;
http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg21145599#generalMustGather
Additional Resources/Links.
Review the Redbook, White Paper, and Tech Notes sections/links at the following support page.
http://www-306.ibm.com/software/data/ondemand/mp/support.html
ODWEK Redbook: How to Deploy a Sample ODWK Client.
ODWEK Implementing Web Applications with IIforC and ODWEK.
<Link to Resource White Paper>
<Link to Thread/Connection Pool Paper>
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 6 of 9
ODWEK Error Reporting.
ODWEK has two methods of reporting error conditions to the client developer. The main method is via
the ODException class. Additional details for those exceptions and other errors are logged to the
arswww.trace file.
The ODException class is an extension of the Java Exception class and will report errors in ODWEK
processing via a thrown Exception in your custom Java code. You must handle these ODExceptions as
you would any other Java Exception. The ODException will include a ExceptionID, which is the error
code returned to ODWEK by the OnDemand Server , and/or an Exception String which will contain
additional details on the error that occurred. NOTE: It is recommended that you run your ODConfig
with TraceLevel=1, so all ERROR details are written to the arswww.trace. The arswww.trace will have
additional information that may not be included in an ODException.
For ODException.ID details, please see the “IBM CM OnDemand Messaging and Codes Guide” for
detailed descriptions of errors that can be generated at the OnDemand Server. The guide lists the error
codes with server specific prefix (“ARS”) as used in the OnDemand System Log, but the integer maps
correctly to the ODException.ID that is returned in the ODWEK Java APIs.
Additional errors can be thrown by several OnDemand sub-components that ODWEK relies on at the
Mid-Tier. These messages are logged in the arswww.trace with CSV_RC=<num> and
CSV_ID=<Num>. We try to also include a string detail with each error. Here is a brief snapshot of how
the CSV_RC and CSV_ID are mapped in ODWEK.
CSV_RC
ERROR
0
CSV_RC_OKAY
1
CSV_RC_OKAY_WITH_MESSAGE
2
CSV_RC_CANCEL
3
CSV_RC_PASSWORD_CHANGE
4
CSV_RC_DOC_UNAVAILABLE
5
CSV_RC_INVALID_SEARCH
6
CSV_RC_NO_PERMISSION
7
CSV_RC_TIMEOUT
8
CSV_RC_DATA_CONVERSION_ERROR
9
CSV_RC_MISC_ERROR
10
CSV_RC_EXISTS
CSV_ID
ERROR
CSV_ID
ERROR
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 7 of 9
0
CSV_MSG_NO_MESSAGE
47
CSV_MSG_LATEST_CANNOT_BE_USED
1
CSV_MSG_NOT_ENOUGH_MEMORY
48
CSV_MSG_TOO_MANY_HITS
2
CSV_MSG_INCOMPAT_CLIENT_SERVER
49
CSV_MSG_DOC_UNAVAILABLE
3
CSV_MSG_SERVER_CANNOT_INIT
50
CSV_MSG_MISC_UNAVAILABLE
4
CSV_MSG_SERVER_CANNOT_CONNECT
51
CSV_MSG_DEF_LOGVIEW_DELETED
5
CSV_MSG_SERVER_DLL_NOT_FOUND
52
CSV_MSG_TOO_MANY_LOGVIEWS
6
CSV_MSG_SERVER_TIMEOUT
53
CSV_MSG_CDROM_VERSION
7
CSV_MSG_SERVER_DATA_CHANGED
54
CSV_MSG_CDROM_PROC_ADDRESS
8
CSV_MSG_SERVER_FAILED_LOGON
55
CSV_MSG_CDROM_FOLDER_EXISTS
9
CSV_MSG_SERVER_FAILED_SEARCH
56
CSV_MSG_CDROM_STAGING_DRIVE
10
CSV_MSG_SERVER_FAILED_FOLDER
57
CSV_MSG_CDROM_CLEAN
11
CSV_MSG_SERVER_FAILED_NQ_RET
58
CSV_MSG_CDROM_SETUP
12
CSV_MSG_SERVER_FAILED_NQ_UPD
59
CSV_MSG_CDROM_DATA
13
CSV_MSG_SERVER_FAILED_DOC_RET
60
CSV_MSG_CDROM_RESOURCE
14
CSV_MSG_SERVER_FAILED_DOC_UPD
61
CSV_MSG_CDROM_INDEX_OPEN
15
CSV_MSG_SERVER_FAILED_DOC_STO
62
CSV_MSG_CDROM_INDEX_VERSION
16
CSV_MSG_SERVER_FAILED_DOC_DEL
63
CSV_MSG_CDROM_INDEX_UPDATE
17
CSV_MSG_SERVER_FAILED_RES_RET
64
CSV_MSG_CDROM_UNKNOWN_FIELD
18
CSV_MSG_SERVER_FAILED_STOSET
65
CSV_MSG_CDROM_ANNOTATION
19
CSV_MSG_SERVER_FAILED_STOSET_ADD
66
CSV_MSG_CDROM_ARS_LAYOUT
67
CSV_MSG_CDROM_FLD_LAYOUT
20
CSV_MSG_SERVER_FAILED_STOSET_NODEADD
21
CSV_MSG_SERVER_FAILED_USER
68
CSV_MSG_CDROM_SOFTWARE
22
CSV_MSG_SERVER_FAILED_NOTE_RET
69
CSV_MSG_CDROM_VOLUME
23
CSV_MSG_SERVER_FAILED_NOTE_STO
70
CSV_MSG_CDROM_MANIFEST_OPEN
24
CSV_MSG_SERVER_FAILED_NOTE_DEL
71
CSV_MSG_CDROM_ORIGINAL_OPEN
25
CSV_MSG_SERVER_FAILED_APPL
72
CSV_MSG_CDROM_DESTINATION_OPEN
26
CSV_MSG_SERVER_FAILED_QPRT
73
CSV_MSG_CDROM_FILE_COPY_READ
27
CSV_MSG_SERVER_FAILED_PRT
74
CSV_MSG_CDROM_INVALID_FOLDER
28
CSV_MSG_INVALID_USER_OR_PASS
75
CSV_MSG_EXT_SERVER_ERROR
29
CSV_MSG_PASSWORD_TOO_SHORT
76
CSV_MSG_EXT_SERVER_RC_ERROR
30
CSV_MSG_PASSWORD_EXIT_ERROR
77
CSV_MSG_INVALID_FOLDER_NAME
31
CSV_MSG_NEW_PASSWORD_MISMATCH
78
CSV_MSG_INVALID_OPERATOR
32
CSV_MSG_INCORRECT_OLD_PASSWORD
79
CSV_MSG_INVALID_CHOICE
33
CSV_MSG_OPERATION_IN_PROGRESS
80
CSV_MSG_INVALID_SEGMENT_NUM
34
CSV_MSG_DATA_CONVERSION_ERROR
81
CSV_MSG_INVALID_CDROM_FOLDER
35
CSV_MSG_NO_PERMISSION
82
CSV_MSG_INVALID_LOGVIEW_OPR
36
CSV_MSG_READ_ONLY
83
CSV_MSG_INVALID_NQ_OPERATION
37
CSV_MSG_NO_APPL_GROUPS
84
CSV_MSG_INVALID_PRTOPT
38
CSV_MSG_NO_VALUES_SPECIFIED
85
CSV_MSG_SERVER_FAILED_GROUP
39
CSV_MSG_VALUE_NOT_SPECIFIED
86
CSV_MSG_SERVER_FAILED_PRINTER
40
CSV_MSG_TOO_MANY_VALUE_CHARS
87
CSV_MSG_SERVER_FAILED_APPLGROUP
41
CSV_MSG_ONLY_ONE_VALUE_GIVEN
88
CSV_MSG_SERVER_FAILED_STOSET_DELETE
42
CSV_MSG_INVALID_INTEGER
89
CSV_MSG_SERVER_FAILED_STOSET_UPDATE
43
CSV_MSG_INVALID_DECIMAL
90
CSV_MSG_SERVER_FAILED_STOSET_NODEDELETE
44
CSV_MSG_INVALID_DATE
91
CSV_MSG_SERVER_FAILED_STOSET_NODEUPDATE
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 8 of 9
45
CSV_MSG_INVALID_RANGE
92
CSV_MSG_APPLGRPS_EXISTS_IN_SET
46
CSV_MSG_INCOMPATIBLE_VALUES
93
CSV_MSG_SERVER_ALREADY_EXISTS
“Debugging a Custom IBM Content Manager OnDemand Web Enablement Kit Java API Web Application .”
Rev: 12/15/2007
© Copyright International Business Machines Corporation 2007. All rights reserved. US Government Users Restricted
Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Page 9 of 9