IBM Content Manager OnDemand Web Enablement Kit Java …

[Pages:314]Front cover

IBM Content Manager OnDemand Web Enablement Kit Java APIs

The Basics and Beyond

Develop Web applications by using ODWEK V8.4 Java APIs Gain insightful best practices, hints, and tips Tune and troubleshoot OnDemand Web applications

redbooks

Wei-Dong Zhu Mark Mikeal

Hassan A. Shazly Elliott Wade

Sebastian Welter

International Technical Support Organization IBM Content Manager OnDemand Web Enablement Kit Java APIs: The Basics and Beyond December 2008

SG24-7646-00

Note: Before using this information and the product it supports, read the information in "Notices" on page ix.

First Edition (December 2008) This edition applies to Version 8 Release 4 of IBM Content Manager OnDemand (program number 5724-J33). ? Copyright International Business Machines Corporation 2008. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi The team that wrote this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Part 1. Programming with the ODWEK Java APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. ODWEK Java API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Origin of the ODWEK Java APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Content Manager OnDemand system overview . . . . . . . . . . . . . . . . . . . . . 4

1.2.1 Content Manager OnDemand Library Server and Object Servers . . . 4 1.2.2 Content Manager OnDemand data . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.3 Content Manager OnDemand data model . . . . . . . . . . . . . . . . . . . . . 7 1.2.4 Content Manager OnDemand data indexing and loading . . . . . . . . . 10 1.3 ODWEK Java APIs function overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.3.1 Typical Web applications developed by using the

ODWEK Java APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.4 ODWEK Java APIs architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.5 ODWEK Java APIs components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.5.1 ODWEK Java and native shared library . . . . . . . . . . . . . . . . . . . . . . 14 1.5.2 Viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.5.3 ODWEK Java API distribution files . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.6 WEBi client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2. ODWEK Java API classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.1 Core API classes and their functional relationship . . . . . . . . . . . . . . . . . . 22

2.1.1 Core API classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.1.2 Functional relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.1.3 Server connection classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.1.4 Content Manager OnDemand data model classes . . . . . . . . . . . . . . 28 2.1.5 Search classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 2.1.6 Document data retrieval classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 2.1.7 Error handling class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 2.2 Sample console application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 2.3 Setting up a Web development environment by using Rational Application

Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

? Copyright IBM Corp. 2008. All rights reserved.

iii

Chapter 3. ODWEK Java API examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 3.1 Examples overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

3.1.1 Example files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 3.1.2 Program flow and control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 3.2 Making a connection to Content Manager OnDemand . . . . . . . . . . . . . . . 59 3.3 Obtaining a list of cabinets and folders . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 3.4 Displaying OnDemand folder information . . . . . . . . . . . . . . . . . . . . . . . . . 66 3.5 Obtaining a list of OnDemand folder search fields . . . . . . . . . . . . . . . . . . 70 3.6 Displaying an Content Manager OnDemand search results list . . . . . . . . 74 3.7 Retrieving and displaying an OnDemand document . . . . . . . . . . . . . . . . . 79 3.7.1 Viewing line data documents with the applet . . . . . . . . . . . . . . . . . . 84 3.8 Disconnecting from OnDemand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Chapter 4. Internet use case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 4.1 Use case overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 4.2 Connection pooling consideration for the use case. . . . . . . . . . . . . . . . . . 94 4.3 Sample application for the use case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Part 2. Best practices, hints, and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Chapter 5. Introduction to best practices, hints, and tips . . . . . . . . . . . . 107

Chapter 6. Connection pooling and connection handling . . . . . . . . . . . 111 6.1 Connection pooling overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

6.1.1 Benefits of connection pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 6.2 Connection pooling objects and pooling technique . . . . . . . . . . . . . . . . . 113

6.2.1 The ODServer class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 6.2.2 ODWEK Java API objects and threads . . . . . . . . . . . . . . . . . . . . . . 114 6.2.3 The ODWEK Java API pool levels . . . . . . . . . . . . . . . . . . . . . . . . . 117 6.3 A simple connection pool code example . . . . . . . . . . . . . . . . . . . . . . . . . 118 6.3.1 The pooling mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 6.3.2 Connection pool code functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 6.3.3 Connection pool code sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 6.4 Thread safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 6.4.1 Instance variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 6.4.2 Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 6.4.3 Implementing synchronization in the ODWEK Java APIs . . . . . . . . 130 6.4.4 Synchronizing servlet code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 6.5 Resource consumption control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 6.5.1 Connection initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 6.5.2 Logging off and terminating a client connection . . . . . . . . . . . . . . . 135 6.5.3 Allocation and release of resources and sessions . . . . . . . . . . . . . 136 6.6 Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 6.6.1 Inactivity timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

iv IBM Content Manager OnDemand Web Enablement Kit Java APIs: The Basics and Beyond

6.6.2 Other timeouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 6.6.3 Implementing an application timeout by using the ODServer.cancel()

method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 6.6.4 Recommended timeout implementation for a Web application . . . . 141

Chapter 7. Globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 7.1 Globalization overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 7.2 Content Manager OnDemand character conversion architecture . . . . . . 146

7.2.1 Index data and annotations conversions. . . . . . . . . . . . . . . . . . . . . 147 7.2.2 UTF conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 7.2.3 Document data conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 7.3 Code page conversion in ODWEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 7.3.1 API conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 7.3.2 Browser conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 7.3.3 Document data conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 7.4 The ICU conversion library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 7.5 Using Unicode as the database code page. . . . . . . . . . . . . . . . . . . . . . . 152 7.6 ODWEK language configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 7.7 Integrating custom code pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 7.7.1 Locations that require configuration . . . . . . . . . . . . . . . . . . . . . . . . 156 7.7.2 ICU and ICONV. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 7.7.3 Customizing code page mappings for ICU . . . . . . . . . . . . . . . . . . . 158 7.8 Globalizing applications by using ICU . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Chapter 8. Folder searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 8.1 Criteria and SQL searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

8.1.1 Criteria search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 8.1.2 SQL search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 8.2 Sort fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 8.3 Search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 8.3.1 Query and display order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 8.3.2 Search result size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 8.3.3 Searching by date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 8.3.4 Selecting a document from the search result list . . . . . . . . . . . . . . 171 8.4 Callbacks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 8.4.1 Why use callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 8.4.2 Searching with callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 8.4.3 Callback search example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Chapter 9. Document retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 9.1 The importance of a retrieval strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . 180

9.1.1 AFP documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 9.1.2 Large objects versus small objects . . . . . . . . . . . . . . . . . . . . . . . . . 181 9.1.3 Requiring only a small part of a large object . . . . . . . . . . . . . . . . . . 181

Contents v

9.1.4 Delivering documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 9.2 Retrieval API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

9.2.1 Retrieval APIs in the ODHit class . . . . . . . . . . . . . . . . . . . . . . . . . . 182 9.3 AFP resource retrieval and custom caching . . . . . . . . . . . . . . . . . . . . . . 185 9.4 Segmented retrieval and large object support. . . . . . . . . . . . . . . . . . . . . 187

9.4.1 Retrieving segmented documents. . . . . . . . . . . . . . . . . . . . . . . . . . 189 9.4.2 Obtaining segment information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 9.5 Avoiding memory issues for large files . . . . . . . . . . . . . . . . . . . . . . . . . . 190 9.6 Getting document type information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 9.7 Retrieving converted data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 9.7.1 Supported data conversions and viewers . . . . . . . . . . . . . . . . . . . . 195

Chapter 10. Applets, plug-ins, and transforms. . . . . . . . . . . . . . . . . . . . . 197 10.1 ODWEK plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

10.1.1 AFP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 10.1.2 Image viewer plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 10.2 ODWEK Java applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 10.2.1 Configuring and using the ODWEK applets . . . . . . . . . . . . . . . . . 202 10.2.2 Line data applet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 10.2.3 AFP2HTML applet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 10.3 AFP2WEB Transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 10.3.1 Configuring the AFP2WEB Transform . . . . . . . . . . . . . . . . . . . . . 205 10.3.2 Integrating the AFP2WEB Transform in ODWEK . . . . . . . . . . . . . 209 10.4 Xenos transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 10.4.1 Configuring ODWEK to use Xenos transforms . . . . . . . . . . . . . . . 211

Chapter 11. Document storing and updating . . . . . . . . . . . . . . . . . . . . . . 215 11.1 Updating document indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

11.1.1 Use cases for the update API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 11.1.2 Update methods in the ODWEK Java APIs . . . . . . . . . . . . . . . . . 216 11.1.3 Hints and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 11.2 Storing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 11.2.1 The storeDocument() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 11.2.2 How the storeDocument() method works . . . . . . . . . . . . . . . . . . . 220 11.3 Deleting documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Chapter 12. Memory and performance . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 12.1 Scope of performance tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 12.2 Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

12.2.1 Optimizing native memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 12.3 Java heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 12.4 The Java stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 12.5 Garbage collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

12.5.1 Garbage collection phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

vi IBM Content Manager OnDemand Web Enablement Kit Java APIs: The Basics and Beyond

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download