Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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