IBM Enterprise Information Portal A Primer

Document Sample
IBM Enterprise Information Portal A Primer Powered By Docstoc
					IBM Enterprise
Information Portal
A Primer
Introduction to the IBM Enterprise
Information Portal (EIP)

EIP installation and
configuration

Java and Notes
sample code




                                     Peter Wilkinson
                                         Eun Jin Kim
                                     Seung-Hun Paik
                                         PJS Prabhu



ibm.com/redbooks
                                               SG24-5749-00

International Technical Support Organization

IBM Enterprise Information Portal
A Primer

October 2000
     Take Note!
  Before using this information and the product it supports, be sure to read the general information in
  Appendix C, “Special notices” on page 177.




First Edition (October 2000)

This edition applies to Version 6.1 of the IBM Enterprise Information Portal, Program Number 5801-AAR
for use with the Windows NT Operating System.

Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. QXXE Building 80-E2
650 Harry Road
San Jose, California 95120-6099

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 2000. All rights reserved.
Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is
subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents

                  Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

                  Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix

                  Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
                  The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
                  Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

                  Chapter 1. Enterprise Information Portal: an overview . .                                 .   .   .   .   ..   .   .   .   .   .1
                  1.1 The IBM Enterprise Information Portal: an introduction . .                            .   .   .   .   ..   .   .   .   .   .1
                  1.2 Corporate portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .        .   .   .   .   ..   .   .   .   .   .2
                  1.3 Public portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .     .   .   .   .   ..   .   .   .   .   .3
                  1.4 EIP benefits — fact or fiction? . . . . . . . . . . . . . . . . . . . .               .   .   .   .   ..   .   .   .   .   .3
                     1.4.1 Competitive advantage . . . . . . . . . . . . . . . . . . . . . .                .   .   .   .   ..   .   .   .   .   .3
                     1.4.2 Increased ROI . . . . . . . . . . . . . . . . . . . . . . . . . . . .            .   .   .   .   ..   .   .   .   .   .4
                     1.4.3 Increased employee productivity . . . . . . . . . . . . . .                      .   .   .   .   ..   .   .   .   .   .5
                     1.4.4 Increased effectiveness . . . . . . . . . . . . . . . . . . . . .                .   .   .   .   ..   .   .   .   .   .5
                     1.4.5 Decreased cost of information . . . . . . . . . . . . . . . .                    .   .   .   .   ..   .   .   .   .   .6
                     1.4.6 Increased collaboration . . . . . . . . . . . . . . . . . . . . .                .   .   .   .   ..   .   .   .   .   .6
                     1.4.7 Universal access to enterprise resources . . . . . . . .                         .   .   .   .   ..   .   .   .   .   .7
                     1.4.8 A unified view of enterprise data and information . .                            .   .   .   .   ..   .   .   .   .   .7
                     1.4.9 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .         .   .   .   .   ..   .   .   .   .   .8

                  Chapter 2. Content Manager installation . . . . . . . . . . . . . . . . . . .                                  .   .   .   . .9
                  2.1 Software requirements for Content Manager installation. . . . . . .                                        .   .   .   . .9
                  2.2 System configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                     .   .   .   . 10
                  2.3 Prerequisites for Content Manager installation . . . . . . . . . . . . . .                                 .   .   .   . 11
                     2.3.1 Install DB2 UDB 5.2 and SDK 5.2 . . . . . . . . . . . . . . . . . . . .                               .   .   .   . 11
                     2.3.2 Install Visual C++ 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                      .   .   .   . 12
                     2.3.3 Set Visual C++ environment variables . . . . . . . . . . . . . . . .                                  .   .   .   . 14
                  2.4 Content Manager installation for Windows NT . . . . . . . . . . . . . .                                    .   .   .   . 17
                     2.4.1 Starting the installation and selecting the components . . . .                                        .   .   .   . 17
                     2.4.2 Text Search management option . . . . . . . . . . . . . . . . . . . .                                 .   .   .   . 18
                     2.4.3 Setting client/server configuration options . . . . . . . . . . . . .                                 .   .   .   . 20
                     2.4.4 Installing the Library Server . . . . . . . . . . . . . . . . . . . . . . . .                         .   .   .   . 22
                     2.4.5 Installing the Object Server. . . . . . . . . . . . . . . . . . . . . . . . .                         .   .   .   . 22
                     2.4.6 Generating a network table. . . . . . . . . . . . . . . . . . . . . . . . .                           .   .   .   . 23
                     2.4.7 Installing the System Administration Client and Gateway . .                                           .   .   .   . 24
                     2.4.8 Copy Content Manager files and complete the Installation .                                            .   .   .   . 25
                  2.5 Starting and stopping the servers . . . . . . . . . . . . . . . . . . . . . . . .                          .   .   .   . 27
                     2.5.1 Starting the Library Server . . . . . . . . . . . . . . . . . . . . . . . . .                         .   .   .   . 27



© Copyright IBM Corp. 2000                                                                                                                       iii
                    2.5.2 Starting the Object Server . . . . . . . . . . . . . . . . . . . . . . . . . . .                    .   . 28
                    2.5.3 Stopping the servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                 .   . 28
                 2.6 Starting the System Administration program . . . . . . . . . . . . . . . . . .                           .   . 29
                    2.6.1 Starting and stopping the System Administration Client . . . . .                                    .   . 29
                    2.6.2 Starting and stopping the System Administration Gateway . . .                                       .   . 31
                    2.6.3 Run System Administration as an applet from a Web browser                                           .   . 32

                 Chapter 3. Installing and configuring the IBM EIP . . . . . . . .                       .   .   ..   .   .   .   . 37
                 3.1 EIP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   .   .   ..   .   .   .   . 37
                 3.2 EIP prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   .   .   ..   .   .   .   . 41
                 3.3 Installing and configuring EIP components . . . . . . . . . . . . .                 .   .   ..   .   .   .   . 42
                    3.3.1 Installing and configuring EIP on the server machine .                         .   .   ..   .   .   .   . 42
                    3.3.2 Installing and configuring EIP on the client machine . .                       .   .   ..   .   .   .   . 48
                 3.4 Final tasks to be completed . . . . . . . . . . . . . . . . . . . . . . . .         .   .   ..   .   .   .   . 50
                    3.4.1 Defining content servers and running server inventory                          .   .   ..   .   .   .   . 50
                    3.4.2 Creating federated entities . . . . . . . . . . . . . . . . . . . . .          .   .   ..   .   .   .   . 52
                    3.4.3 Creating and mapping federated attributes . . . . . . . . .                    .   .   ..   .   .   .   . 53
                    3.4.4 Creating federated text indexes . . . . . . . . . . . . . . . . .              .   .   ..   .   .   .   . 55
                    3.4.5 Creating search templates . . . . . . . . . . . . . . . . . . . . .            .   .   ..   .   .   .   . 56

                 Chapter 4. Java client for Content Manager using WebSphere . .                                       .   .   . . 57
                 4.1 Getting ready for developing the application . . . . . . . . . . . . . . . .                     .   .   . . 57
                    4.1.1 Configuring IBM WebSphere Application Server . . . . . . . . .                              .   .   . . 57
                    4.1.2 Environment variables for compiling a Java program . . . . .                                .   .   . . 58
                    4.1.3 Loading the sample data into the Content Manager server .                                   .   .   . . 59
                 4.2 The client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .         .   .   . . 65
                    4.2.1 The input screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .           .   .   . . 65
                    4.2.2 A parametric search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .             .   .   . . 66
                    4.2.3 A text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .         .   .   . . 70
                    4.2.4 A combined search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .             .   .   . . 74
                 4.3 The Java servlet programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .              .   .   . . 76
                    4.3.1 The running environment . . . . . . . . . . . . . . . . . . . . . . . . . .                 .   .   . . 76
                    4.3.2 The servlets flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .           .   .   . . 76
                    4.3.3 Condition/Input - MSInput . . . . . . . . . . . . . . . . . . . . . . . . . .               .   .   . . 78
                    4.3.4 Servlet for listing the query result — MSList . . . . . . . . . . . .                       .   .   . . 86
                    4.3.5 Servlet for showing content of a document — MSContent .                                     .   .   . 100
                    4.3.6 Servlet for showing metadata of a document — MSMeta . .                                     .   .   . 106
                    4.3.7 Servlet for showing text object of a document — MSText . .                                  .   .   . 109
                    4.3.8 Compilation and configuration of a servlet . . . . . . . . . . . . .                        .   .   . 113

                 Chapter 5. Lotus Notes client for content servers using EIP.                                .   ..   .   .   . 117
                 5.1 Preparing for development . . . . . . . . . . . . . . . . . . . . . . . . . .           .   ..   .   .   . 117
                 5.2 Setting up the Windows development environment. . . . . . . .                           .   ..   .   .   . 118
                 5.3 Setting up the Lotus Domino development environment . . . .                             .   ..   .   .   . 119


iv   IBM Enterprise Information Portal - A Primer
5.4 Writing an Agent using Java in Lotus Domino. . . . . . . . . . . . . . .                             .   .   . 122
   5.4.1 How to write inline Java in an Agent . . . . . . . . . . . . . . . . . .                        .   .   . 124
   5.4.2 How to import Java in an Agent . . . . . . . . . . . . . . . . . . . . .                        .   .   . 124
5.5 Passing parameters to the Java Agent . . . . . . . . . . . . . . . . . . . .                         .   .   . 126
   5.5.1 Option 1: Passing values using the user profile . . . . . . . . .                               .   .   . 126
   5.5.2 Option 2: Passing values using the environment variables .                                      .   .   . 127
   5.5.3 Option 3: Passing values using the in-memory document . .                                       .   .   . 127
5.6 The Lotus Notes client application . . . . . . . . . . . . . . . . . . . . . . .                     .   .   . 128
   5.6.1 Designing the Login form . . . . . . . . . . . . . . . . . . . . . . . . . .                    .   .   . 132
   5.6.2 Designing the Search form . . . . . . . . . . . . . . . . . . . . . . . . .                     .   .   . 139
   5.6.3 Designing the User Profile form . . . . . . . . . . . . . . . . . . . . .                       .   .   . 144
   5.6.4 Federated Datastore and the EIP Java APIs . . . . . . . . . . . .                               .   .   . 145
   5.6.5 Creating the Java Agents . . . . . . . . . . . . . . . . . . . . . . . . . .                    .   .   . 149
   5.6.6 Placing the components in a frameset . . . . . . . . . . . . . . . .                            .   .   . 164

Appendix A. Environment: hardware and software configurations . . 167
A.1 NT servers: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
A.2 AIX servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
A.3 Digital library servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
A.4 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
A.5 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Appendix B. Installing and configuring IBM WebSphere V.2.02 . . . . . 169
B.1 IBM WebSphere Application Server components. . . . . . . . . . . . . . . . . . 169
B.2 Preparing to install the IBM WebSphere Application Server. . . . . . . . . . 170
   B.2.1 Prerequisites for IBM WebSphere installation on Windows NT . . . 170
   B.2.2 Additional tasks to complete before installation . . . . . . . . . . . . . . . 171
B.3 Installing the IBM WebSphere Application Server on Windows NT . . . . 172
B.4 Starting and stopping Application Server . . . . . . . . . . . . . . . . . . . . . . . . 173
   B.4.1 Starting the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
   B.4.2 Stopping the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
B.5 Customizing configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
   B.5.1 Starting the Application Server Manager . . . . . . . . . . . . . . . . . . . . 174
   B.5.2 Using the Application Server Manager . . . . . . . . . . . . . . . . . . . . . . 175
   B.5.3 Configuring servlets, aliases, and filtering . . . . . . . . . . . . . . . . . . . 176
   B.5.4 Logging off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Appendix C. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Appendix D. Related publications . . .                       .......      ......     .......      ......         .   181
D.1 IBM Redbooks . . . . . . . . . . . . . . . . .           .......      ......     .......      ......         .   181
D.2 IBM Redbooks collections . . . . . . . .                 .......      ......     .......      ......         .   182
D.3 Referenced Web sites . . . . . . . . . . .               .......      ......     .......      ......         .   182



                                                                                                                       v
                 How to Get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
                 IBM Redbooks fax order form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

                 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

                 List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

                 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

                 IBM Redbooks review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199




vi   IBM Enterprise Information Portal - A Primer
Figures

                  1.    DB2 UDB 5.2 Username and Password for the Administration Server . . . 12
                  2.    Visual C++ 6.0 Standard Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
                  3.    Visual C++ 6.0 Setup Environment Variables . . . . . . . . . . . . . . . . . . . . . . 14
                  4.    User Profiles of System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
                  5.    Environment of System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
                  6.    Command Prompt screen for checking environment variables . . . . . . . . . 16
                  7.    Component Selection for Content Manager. . . . . . . . . . . . . . . . . . . . . . . . 18
                  8.    Answering for Text Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
                  9.    Selection of Open All Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
                  10.   System Admin Client Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
                  11.   Setting Client/Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
                  12.   Installing Library Server Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
                  13.   Installing Object Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
                  14.   Generating Network Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
                  15.   Installing System Administration Client and Gateway . . . . . . . . . . . . . . . . 25
                  16.   Start Copying Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
                  17.   Content Manager Installation complete . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
                  18.   Library Server Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
                  19.   Object Server Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
                  20.   System Administration Client Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
                  21.   System Administration Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
                  22.   System Administration Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
                  23.   Logon to System Admin Gateway Workstation from a Web browser . . . . 33
                  24.   System Administration Program Logon from a Web browser . . . . . . . . . . 34
                  25.   System Administration Program from a Web browser . . . . . . . . . . . . . . . . 35
                  26.   Local configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
                  27.   Remote configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
                  28.   Component selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
                  29.   Text Search Server/Client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 45
                  30.   Component selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
                  31.   Network Table Generation for DL/VI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
                  32.   Defining a content server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
                  33.   Initialization parameters tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
                  34.   Federated entity definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
                  35.   Federated attribute definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
                  36.   Federated attribute mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
                  37.   Text Server Administration using the System Administration Client . . . . . 61
                  38.   Creating Text Index using the System Administration Client . . . . . . . . . . . 62
                  39.   After Creating the Text Index TMINDEX . . . . . . . . . . . . . . . . . . . . . . . . . . 63
                  40.   Input area for parametric search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65



© Copyright IBM Corp. 2000                                                                                                      vii
                  41.   Input area for Text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
                  42.   An example of parametric search input . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
                  43.   An example of parametric search result . . . . . . . . . . . . . . . . . . . . . . . . . . 69
                  44.   An example of a document content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
                  45.   An example of a text search input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
                  46.   An example of the text search result list . . . . . . . . . . . . . . . . . . . . . . . . . . 72
                  47.   An example of the content of a text object. . . . . . . . . . . . . . . . . . . . . . . . . 73
                  48.   An example of a combined search input . . . . . . . . . . . . . . . . . . . . . . . . . . 74
                  49.   An example of a combined search result list . . . . . . . . . . . . . . . . . . . . . . . 75
                  50.   The running environment of our application. . . . . . . . . . . . . . . . . . . . . . . . 76
                  51.   The flows among the Java servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
                  52.   Adding a servlet in the IBM WebSphere Application server . . . . . . . . . . 115
                  53.   The different panes in Lotus Domino Designer . . . . . . . . . . . . . . . . . . . . 122
                  54.   Creating an agent which uses Java code . . . . . . . . . . . . . . . . . . . . . . . . 123
                  55.   Importing Java files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
                  56.   Sample Notes application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
                  57.   Before Login. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
                  58.   After a successful login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
                  59.   Composing the query expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
                  60.   Designing the Login form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
                  61.   Hide when formula for the first section of the Login form. . . . . . . . . . . . . 135
                  62.   Designing Search form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
                  63.   Designing the User Profile form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
                  64.   Designing the FSLogin Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
                  65.   Defining the Java agent files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
                  66.   Designing a frameset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
                  67.   Defining the content for a frame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
                  68.   Database launch option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
                  69.   Application server components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
                  70.   Application server plug-ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173




viii   IBM Enterprise Information Portal - A Primer
Tables

                  1.   Hardware configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
                  2.   Software configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
                  3.   RMI Server hardware and software requirements . . . . . . . . . . . . . . . . . . 41
                  4.   EIP database hardware and software requirements . . . . . . . . . . . . . . . . . 41
                  5.   EIP client hardware and software requirements . . . . . . . . . . . . . . . . . . . . 41
                  6.   Development system hardware and software requirements . . . . . . . . . . 117




© Copyright IBM Corp. 2000                                                                                                   ix
x   IBM Enterprise Information Portal - A Primer
Preface

                  This IBM Redbook is the first in a series addressing the IBM Enterprise
                  Information Portal and its associated family of products.

                  The primary aim of this redbook is to assist you to install, tailor, and configure
                  the IBM Enterprise Information Portal. Additionally, this book covers the
                  installation of the EIP prerequisites, such as WebSphere.

                  Also included are Java and Lotus Notes client applications to access data in a
                  Content Manager database.


The team that wrote this redbook
                  This redbook was produced by a team of specialists from around the world
                  working at the International Technical Support Organization San Jose Center.

                  Peter Wilkinson is a consultant for the International Technical Support
                  Organization at the Almaden Research Center in San Jose, California. He
                  has 24 years of experience with IBM, the last four years in the Content
                  Management field. Before joining the ITSO in 1999, Peter was the Content
                  Management segment manager for Australia and New Zealand.

                  Eun Jin Kim is an I/T Specialist in IBM Korea. She has two years of
                  experience in the Content Management field. She holds a master’s degree in
                  Computer Science from Korea Advanced Institute of Science and Technology.
                  Her areas of expertise include Digital Library and Internet programming. She
                  has written extensively on Java servlet development.

                  Seung-Hun Paik is an Advanced Business Analyst in the Document
                  Management Services Team of LG-EDS Systems Inc., in Korea. He has ten
                  years of experience in the IT services field, the last four years in the area of
                  EDMS Business Development. His areas of expertise include Imaging, EDM,
                  COLD, and Workflow solutions. Before joining LG-EDS Systems four years
                  ago, he worked as a application engineer for Imaging solutions in the Wang
                  Laboratory, Korea Open Software Department. He has written extensively on
                  Content Manager.

                  PJS Prabhu is a Senior Software Engineer in IBM India. He has seven years
                  of experience in the IT industry, the last two years in Content Management.
                  He holds a master’s degree in Computer Science from Bharathidasan
                  University. His areas of expertise include Lotus Notes, C++, Java, and Web
                  development. He has written extensively on EIP, Lotus Notes, and Java.



© Copyright IBM Corp. 2000                                                                        xi
                  Thanks to the following people for their invaluable contributions to this project:

                  Will Carney
                  International Technical Support Organization, San Jose Center

                  Peter Mandel
                  IBM Santa Teresa

                  Jim Reimer
                  IBM Santa Teresa


Comments welcome
                  Your comments are important to us!

                  We want our redbooks to be as helpful as possible. Please send us your
                  comments about this or other redbooks in one of the following ways:
                   • Fax the evaluation form found in “IBM Redbooks review” on page 199 to
                     the fax number shown on the form.
                   • Use the online evaluation form found at ibm.com/redbooks
                   • Send your comments in an Internet note to redbook@us.ibm.com




xii   IBM Enterprise Information Portal - A Primer
Chapter 1. Enterprise Information Portal: an overview

                  Enterprise Information Portals connect users with everything and
                  everyone they need to support their job role, and provide the tools
                  required to work together.

                  Enterprise Information Portals are applications that enable companies to
                  provide access to internally and externally stored information. They offer
                  users within and external to the enterprise, a single window to personalized
                  information needed to make informed business decisions. They are an
                  amalgamation of software applications that consolidate, manage, analyze
                  and distribute information across and outside of an enterprise.

                  An Enterprise Information Portal (EIP) is a browser-based system that
                  provides access to vital business information in the same manner that content
                  portals like Yahoo are the gateway to content on the Web.

                  The essential characteristics of EIPs are:
                    • EIPs use both "push" and "pull" technologies to present information to
                      users through a standardized Web-based interface.
                    • EIPs provide "interactivity" – the ability to “question” and to share
                      information on user’s desktops.
                    • EIPs integrate disparate applications including Content Management,
                      Business Intelligence, Data Warehouse/Data Mart, Data Management,
                      and other data external to these applications into a single system that can
                      share, manage and maintain information from one central user interface."
                    • EIPs are able to access both external and internal sources of data and
                      information. They are able to support a bi-directional exchange of
                      information with these sources. and are able to use the data and
                      information acquired for further processing and analysis.

                  This means that groupware, e-mail, workflow, and desktop applications - even
                  critical business applications - must be accessable through the portal.




1.1 The IBM Enterprise Information Portal: an introduction
                  The IBM Content Management family of products has been extended to
                  facilitate Enterprise Information Portals. This family of products has
                  progressed in this direction for the past two years with products such as



© Copyright IBM Corp. 2000                                                                       1
                 Content Connect (EDMSuite), Grand Portal (Digital Library), and Domino
                 Extended Search (Lotus). These efforts have now been rationalized to
                 provide a unified suite of federated search gateway functions spanning a
                 broad range of enterprise sources and targets.

                 The IBM Enterprise Information Portal (EIP) is a federated search gateway
                 that provides a rich development environment for the composition of mass
                 customized applications or views. EIP provides the solution builder with a
                 palette of GUI and non-GUI object oriented parts from which to compose the
                 view an enterprise wants to have of their resources. These parts are available
                 in C++, ActiveX, Java, LSX, and as Dynamic Page Builder components.
                 Application development tools, such as Visual Cafe, NetFusion, WebSphere,
                 and Net.Data can be used to place and tailor the EIP parts for the user's
                 application and view. Administrative GUI is used to specify and tailor the
                 enterprise sources and targets that are used for each user set, independent
                 of the application developed.

                 To further improve the IBM EIP with properties which are seen as critical for
                 Enterprise Portals, both the DB2 Knowledge Portal development activities
                 and MQ Series Workflow integration will be completed in the year 2000 and
                 highlighted as part of the EIP focus. With the DB2 Knowledge Portal and MQ
                 Series Workflow additions, this product will be a very capable and competitive
                 market entry in the new field of Enterprise Information Portals.


1.2 Corporate portal
                 A term closely related to EIP is the Corporate Portal, emphasising
                 user-centric focus, as well as work flow and task integrative functions.
                 Corporate portals are centralizing enterprise information access in a
                 graphically rich, application-independent interface that mirrors
                 "knowledge-centric" work flow, and as providing a single point of integration
                 through the enterprise." Corporate portals integrate the "islands of
                 automation" formed by today’s application-based desktops, and eventually
                 will create an integrated business environment providing information access,
                 delivery, and work support across organizational dimensions.

                 The purpose of corporate portals is to expose and deliver business-specific
                 information to help today’s computer workers stay ahead of the competition.
                 Being competitive requires a bi-directional model that can support knowledge
                 workers’ increasingly sensitive needs for interactive information-management
                 tools.

                 There are four types of corporate portals.



2   IBM Enterprise Information Portal - A Primer
             • Enterprise Information Portals connect people with information by
               organizing large collections of content on the basis of subjects or themes
               they contain.
             • Collaborative portals enable teams of users to establish virtual project
               areas or communities along with the tools for collaboration they offer, and
               to work cooperatively within these communities.
             • Expertise portals link people together based on their skills and expertise,
               as well as their information needs.
             • Knowledge portals do everything the first three types do and an
               unspecified something "more."


1.3 Public portal
            The corporate portal and the public portal have fundamentally different
            purposes. Public portals have a uni-directional relationship with their viewers.
            Their purpose is to attract large numbers of repeat visitors and to build online
            audiences who have compelling demographics and tend to buy what portal
            advertisers are selling.


1.4 EIP benefits — fact or fiction?
            The following is a summary of the implied benefits of EIPs. The question
            about each claimed benefit is whether the arguments supporting it describe a
            direct connection of EIP effects to corporate goals, or whether they are
            speculative and hypothetical.

1.4.1 Competitive advantage
            The argument for competitive advantage assumes that valuable information is
            currently still in disparate, non-integrated, corporate data stores.
            Corporations that can access all their stored information will have a
            competitive advantage, because they have access to timely and accurate
            information (for example, marketing, performance, and customer
            relationships). Also, having this information allows them to develop better
            forecasts, to adapt faster to changes, and to provide better support for
            decisions than their competition. The key to getting such information, and the
            resulting competitive advantages, is said to be EIP software. Why? Because
            EIP software combines and integrates internal and external information, and
            standardizes, indexes, analyzes, publishes, and distributes all the information
            needed in a user’s job role. So, the user’s job performance is affected, and
            specifically the efficiency, quality, effectiveness, net benefit, and cost of the



                                             Chapter 1. Enterprise Information Portal: an overview   3
                 user’s job performance is improved. As part of the user’s job is to cooperate
                 with others in the enterprise, the performance of the tasks the user
                 participates in will also be enhanced; and so on up the business process
                 hierarchy, until business processes show an increase in efficiency, quality,
                 effectiveness, and net benefit.

                 While this argument is credible, in many corporations information may no
                 longer be locked away. It may be available through relatively new ERP or data
                 warehousing applications. It may be managed and published and distributed
                 by content management applications. It may be analyzed by business
                 intelligence applications. Previous corporate investments in new IT systems
                 may already have enhanced the competitiveness of many corporations.

                 That doesn’t mean that an EIP application may not further enhance
                 competitiveness (it almost certainly will), but to base the argument on
                 "locked-up" data stores may not be as appropriate as it was at the beginning
                 of the data warehousing boom.

1.4.2 Increased ROI
                 Another frequently mentioned benefit of EIPs is that they increase Return On
                 Investment (ROI). The argument here is that packaged EIP applications
                 should produce higher ROI than other IT applications for the following
                 reasons:
                   • Packaged applications are less expensive than customized systems
                   • Packaged applications contain functionality specific to particular industry
                     vertical markets
                   • Packaged applications are easier to maintain
                   • They are faster to deploy

                 The adoption of packaged applications is a general trend in IT, and while it is
                 hard to argue that packaged applications may produce ROI benefits, they
                 also may not necessarily be associated with EIP solutions. While EIPs may
                 be focused on packaged vertical applications, they also may not. It depends
                 on the particular EIP project being implemented.

                 There is no exclusivity for EIP applications in participating in this trend.
                 Packaged DSS, or Content Management, or ERP applications may be offered
                 and implemented outside of an EIP framework. So if a corporation is
                 considering a packaged application implementation, it will need to choose
                 between those within and external to an EIP framework, and it will need to
                 face the question of the marginal improvement in ROI forecasted in case of
                 EIP implementation.


4   IBM Enterprise Information Portal - A Primer
            Another problem with the ROI argument is the claim that packaged
            applications are easier to maintain than custom applications. While this is
            true for each individual packaged application, is a system of packaged
            applications easier to maintain if the goal is enterprise application
            integration? Not necessarily, as the history of attempts to integrate SAP and
            other ERP packaged applications in a broader enterprise framework seems to
            show. Packaged applications can easily become stovepipes representing
            differing and incompatible definitions of the same critical concepts and
            differing business models.

            One of the advantages of implementing packaged applications in an EIP
            framework may prove to be the tighter coupling of applications provided by an
            EIP solution. But tighter integration is problematic and depends on the EIP
            architecture.

            Front-end integration involving mere placement of different packaged
            applications on the portal screen, and the portal’s ability to aggregate content
            from different applications is unlikely to offer a great increase in ROI over
            stand-alone, non-portal packaged application implementations.

1.4.3 Increased employee productivity
            This argument refers to productivity in the very narrow sense of improving the
            cycle time involved in information gathering. One version of the argument is
            that if users now spend x amount of time surfing the web to gain information,
            they can be expected to spend x-y amount of time getting the same amount of
            information when they use a portal. If we multiply y times the number of
            employees in an organization, we have the gross amount of time saved by the
            portal, which, of course, can easily be converted to a benefit in dollars.

            This sounds like the simplest and most straightforward argument for realizing
            a benefit from an EIP. However, it is not so easy to demonstrate, and requires
            detailed studies to gauge the effects of portal introduction. The portal may
            speed up cycle time and therefore produce increased efficiency, but whether
            that really produces a benefit in dollars depends on whether the time freed up
            is used for a productive purpose in the broad sense of the term. If the portal
            saves 15 minutes of surf time per employee per person day that won’t
            translate into actual savings unless the 15 minutes gained contributes to
            quality, effectiveness, and net benefit.

1.4.4 Increased effectiveness
            The claim of increased effectiveness is based on the idea that portals not only
            make available new information to users that was not available before, but



                                             Chapter 1. Enterprise Information Portal: an overview   5
                 also provide that information in an integrated and personalized way.
                 Integration and personalization focus information on the job role of the user,
                 and therefore lead to improved job performance, and eventually to a more
                 knowledgeable and effective organization.

                 Here is another credible argument requiring further analysis and
                 demonstration. First, because we don’t know yet whether portals provide
                 enough of an increased focus to increase effectiveness. And second,
                 because we don’t know whether the increased actual exposure to information
                 provided by portals may have the negative effect of further diffusing employee
                 attention away from job roles.

1.4.5 Decreased cost of information
                 The benefit of decreased cost of information is a consequence of both
                 Web-based publishing and the automated character of portals. For
                 companies that still distribute information on paper, portals promise big
                 savings. For companies already involved in Web publishing, portals offer the
                 possibility of saving on Web administration personnel costs.

                 The assumed savings in delivering information over the Web are not
                 exclusive to the portal alternative. This benefit applies to any Web-based
                 publishing application. The savings from Web administration are a clear
                 benefit of EIPs, but are clearly only a small part of any justification for EIP
                 applications.

1.4.6 Increased collaboration
                 One of the most important benefits of EIPs may be increased collaboration
                 within the enterprise. Increased collaboration translates to a more sustained
                 common effort to accomplish corporate goals and to greater integration of
                 corporate environments, especially across departmental and geographic
                 barriers. One of the major problems of modern decentralized enterprises is
                 fragmentation and isolation of its components, and collaboration through
                 portal structures could provide a compelling solution.

                 However, it’s important to note that collaboration across formal boundaries
                 can also have the effect of lessening integration within an organization’s
                 formal structures. While this often is an effect to be welcomed, it is not always
                 advantageous. Careful analysis is needed in order to validate this prospective
                 benefit for any enterprise contemplating an EIP.




6   IBM Enterprise Information Portal - A Primer
1.4.7 Universal access to enterprise resources
            An appealing aspect of EIPs is their promise to provide universal access to
            enterprise information and knowledge resources. The cost-effectiveness of
            the Internet as the foundation for such access is the key point. It is finally
            possible to use both "push" and "pull" technologies to ensure that users have
            the right information available to them at the right time and at the right price
            (for the enterprise).

            The appeal of this argument rests on a few assumptions. The first is that the
            Internet requires a universal portal if it is to provide this advantage. This is not
            the case, as a series of Web applications not integrated into a portal could
            also provide such access. The question is the marginal benefit provided by
            the portal, not the benefit provided by universal access, which might be
            delivered without a portal.

            The second is that it is also assumed that universal access to information is
            itself a benefit. But many people argue that we currently have an information
            glut, and that mere access to information is not a benefit. Portals can
            organize this glut in such a way as to bring it under control, but this power of
            organization is clearly a function of individual portals, with specific
            architectures, implemented in specific situations, having an impact on specific
            business processes, tasks and job roles. It is not a general benefit of all
            portals. In particular, the best way to alleviate an information glut is to
            synthesize information and to produce new knowledge. Knowledge
            production however, may or may not be effectively supported by a particular
            EIP implementation. If it is not, the universal access to information provided
            by an EIP can carry with it costs as well as benefits.

1.4.8 A unified view of enterprise data and information
            Another benefit claimed for EIPs is that they produce a common view of data
            and information in the enterprise. The common view is justified by pointing to
            a number of favorable assumed consequences.
             • The existence of such an enterprise view may have a positive impact on
               the education, socialization, and integration of new employees in a
               corporation.
             • Widely distributed employees are presented with the same view of
               company information wherever they work in the world. This helps them to
               identify with the company and to feel a part of it.
             • The existence and availability of the common view helps employees share
               information, and cuts down dependency on a few key employees for
               information.



                                               Chapter 1. Enterprise Information Portal: an overview   7
                   • Since the common view contributes to the education of new employees, it
                     also empowers them to more easily deal with and handle the increasing
                     complexity of the products being produced by the most sophisticated
                     companies.
                   • Since the common view is dynamically maintained and integrated, and
                     also comprehensive, it is an aid to competitive intelligence in the business,
                     and helps support more effective selling and customer service.

                 These consequences of the common view provide some strong benefit claims
                 for proponents of EIPs. But there are still problems with the argument. First,
                 the common view of an enterprise does not need to be created and
                 maintained by an EIP. Other applications such as Web-enabled distributed
                 data warehouses, integrated ERP applications with a common ERP
                 backbone, and document management applications with an object model of
                 content running on an application server, may be much closer to providing a
                 common view than many EIP solutions.

                 Second, all of the favorable consequences of the common view are plausible
                 in theory, but they are vaguely stated. A common view of the enterprise
                 produced by an EIP should deliver the above benefits, but to what degree in
                 absolute terms and in comparison to competing applications like DW, Content
                 Management, and ERP?

1.4.9 Conclusion
                 Most discussions of EIP promote potential effects of the introduction of EIP
                 software in an ad hoc manner, and an assertion that these outcomes are
                 unequivocal benefits. This approach is instinctive rather than analytical, and it
                 does not address the relationship of the claimed or envisioned outcomes to
                 corporate goals or business processes.

                 An EIP is a composite of a number of applications, and therefore previously
                 established justifications for Data Warehouses, Content Managers, and
                 ERP-based DSS applications must be taken into account.

                 To provide an EIP justification, analysis is necessary that will compare
                 specific EIP and other IT alternatives through the impact they make on
                 various business processes, goals, and objectives, and finally translate any
                 differences in impact on goals and objectives into differences in benefits and
                 costs produced by the alternatives.




8   IBM Enterprise Information Portal - A Primer
Chapter 2. Content Manager installation

                  This chapter describes one example of a Content Manager installation, based
                  on the Windows NT platform for a Web enabled system configuration. We
                  outline the steps for installing and configuring the necessary Content
                  Manager components for this example, based on our configuration (See
                  Appendix A, “Environment: hardware and software configurations” on page
                  167). For detailed information concerning this installation as well as other
                  platforms and configurations refer to the IBM Content Manager for
                  Multiplatforms: Planning and Installation Guide, GC26-9831.

                  This chapter includes the following sections:
                    • Software requirements for Content Manager installation
                    • System configuration
                    • Prerequisites installation
                    • Content Manager installation
                    • Starting and stopping the servers
                    • Starting the System Administration Program


2.1 Software requirements for Content Manager installation
                  The software requirements for using the Content Manager on Windows NT
                  are:
                  1) Object Server
                      - DB2 UDB 5.2 or higher
                      and
                      - DB2 UDB SDK 5.2 or higher
                      or
                      - Oracle NT version 8.0
                  2) Library Server
                      - Microsoft Visual C++ 6.0
                      either
                      - DB2 UDB & SDK 5.2+
                      or
                      - Oracle NT 8.0 (as above)



© Copyright IBM Corp. 2000                                                                   9
                 3) Java System Administration
                     - JRE 1.1.7

                 For more detail information, refer to the IBM Content Manager for
                 Multiplatforms: Planning and Installation Guide, GC26-9831.


2.2 System configuration
                 This installation description is for the following system configuration:
                 1. Library Server, Object Server, Digital Library Administrator and the
                    Internet Connection Server, all running on the same system, under
                    Windows NT Server 4.0.
                 2. Clients running on separate Windows NT workstations.

                 Select US_ENGLISH as the default language, with the language code of
                 ENU. If you want to define a language other than English as your server's
                 default language and use a different default code page, you must create a
                 new language definition. For further information, refer to the IBM Content
                 Manager for Multiplatforms: Planning and Installation Guide, GC26-9831.

                 Also, this section describes the hardware and software that we used for the
                 installation described in this redbook. For the minimum prerequisites, see the
                 IBM Content Manager for Multiplatforms: Planning and Installation Guide,
                 GC26-9831.

                 We use three nodes connected through a token ring network with TCP/IP. Our
                 machines consist of one Windows NT Server and two Windows NT
                 Workstation systems. Table 1 lists our hardware configuration.
                 Table 1. Hardware configuration

                                                    Server                   Workstations

                  Machine type                      IBM PC 300PL             IBM PC 300PL

                  Memory                            128 MB                   64 MB

                  Disk space                        3.1 GB                   6.1 GB

                  Other peripherals                 IBM Token-Ring PCI       IBM Token-Ring PCI
                                                    Family Adapter, CD-ROM   Family Adapter, CD-ROM




10   IBM Enterprise Information Portal - A Primer
            Table 2 lists our software configuration.
            Table 2. Software configuration

                                              Server                        Workstations

             Operating system                 Windows NT Server 4.0         Windows NT Workstation
                                                                            4.0

             Software tools                   - Netscape Communicator       - Netscape Communicator
                                              4.61                          4.61
                                                                            - Adobe FrameMaker 5.5
                                                                            - Paint Shop Pro 5.01

             Content Manager                  - DB2 UDB 5.2
             prerequisites                    - DB2 UDB SDK 5.2
                                              - Microsoft Visual C++ 6.0
                                              - Lotus Domino Go
                                              WebServer 4.6.2

             IBM Content Manager              - Library Server
                                              - Object Server
                                              - System Admin. Client
                                              - System Admin. Gateway



2.3 Prerequisites for Content Manager installation
            This section describes the related prerequisites for Content Manager
            installation. The prerequisites to install Content Manager are:
             • Install DB2 UDB 5.2 and SDK 5.2, then reboot the system and log on as
               user DB2ADMIN
             • Install Visual C++ 6.0, then reboot the system and log on as user
               DB2ADMIN
             • Set Visual C++ environment variables

2.3.1 Install DB2 UDB 5.2 and SDK 5.2
            This section describes the installation of DB2 UDB 5.2 and SDK 5.2 for the
            server machine.

            Note: DB2 version 2.x is not supported by Content Manager Version 3. You
            need to upgrade to IBM DB2 UDB 5.2 or later.

            Follow these steps:
            1. Insert the DB2 UDB CD-ROM in your CD-ROM drive and click OK to start
               DB2 installation.



                                                              Chapter 2. Content Manager installation   11
                 2. Select Enterprise Edition as the install option. Follow the DB2 installation
                    program instructions.
                 3. When you enter the username and password for the administration server,
                    because of a limitation of DB2/NT, the administrator user name must be
                    modified so that it is less than or equal to eight characters, for example we
                    use DB2ADMIN (as shown in Figure 1). From now on when you are
                    working on the server, always log on as DB2ADMIN.




                 Figure 1. DB2 UDB 5.2 Username and Password for the Administration Server

                 4. When the DB2 UDB Enterprise Edition installation is complete, do not
                    reboot your system.
                 5. Next you will install the DB2 UDB Software Developer’s Kit (SDK) 5.2.
                    Place the SDK CD in your CD-ROM drive and click OK. This starts the
                    SDK installation.
                 6. Follow the DB2 SDK installation instructions.
                 7. When the DB2 SDK setup has completed, reboot the system and log on as
                    user DB2ADMIN.

2.3.2 Install Visual C++ 6.0
                 This section describes the installation of Microsoft Visual C++.




12   IBM Enterprise Information Portal - A Primer
Start the installation program by the inserting the Visual C++ 6.0 CD-ROM
and then follow the instructions. For detailed information, refer to related
documentation.

When you install Visual C++ 6.0, select the typical installation (as shown in
Figure 2), and also, select the installation option that allows you to set
environment variables in the user settings (as shown in Figure 3).




Figure 2. Visual C++ 6.0 Standard Setup




                                          Chapter 2. Content Manager installation   13
                 Figure 3. Visual C++ 6.0 Setup Environment Variables

                 When you have finished these settings, move them from user settings to
                 system settings. Ensure that in your INCLUDE setting, the DB2 \INCLUDE
                 directory is listed before the Visual C++ \INCLUDE directory.

                 When Visual C++ standard Edition installation is complete, reboot the system
                 and log on as user DB2ADMIN.

2.3.3 Set Visual C++ environment variables
                 This section describes the setting of Visual C++ environment variables for the
                 server machine.

                 If you will be installing server components such as an object server or library
                 server, you must ensure that the Visual C++ environment variables are
                 correctly set on the workstation where your library server will be installed.
                 When Visual C++ is first installed, the environment variables are set up as
                 user variables, not system variables. Therefore, the Visual C++ environment
                 is not automatically available to every user of the library server.

                 Verify that the Library Server user has the correct Visual C++ directories.

                 If you have not installed Visual C++ on your machine, make sure that you
                 install it from the Library Server Administrator user ID.

                 If Visual C++ has already been installed on your machine, make sure that the
                 PATH, LIB, and INCLUDE environment variables for the Library Server
                 Administrator contain entries for the Visual C++ directories.


14   IBM Enterprise Information Portal - A Primer
To copy the user profile of the user account that installed Visual C++, follow
these steps so that other users can access the Content Manager Server:
1. Select Start -> Settings -> Control Panel -> System -> User Profile.
2. Select the user ID of the user that installed Visual C++.
3. Click Copy To to copy the user variables to another user as shown in
   Figure 4.




Figure 4. User Profiles of System Properties

These Visual C++ environment variables must follow the DB2 environment
variables in the LIB and INCLUDE text boxes. To change the order of the
environment variables:
1. Select Start -> Settings -> Control Panel.
2. Double-click the System icon, and click the Environment tab.
3. Select and change the LIB and INCLUDE variables so that %include% is
   in front of the Visual C++ values (as shown in Figure 5).

As an alternative, you can change the user environment variables into system
environment variables, so that all users have access to the Visual C++
environment. If you change user variables to system variables, make sure
that you place the Visual C++ values after any DB2 values.



                                               Chapter 2. Content Manager installation   15
                  Figure 5. Environment of System Properties

                  Figure 6 shows the command prompt screen where you can verify the
                  environment variables.




Figure 6. Command Prompt screen for checking environment variables



16    IBM Enterprise Information Portal - A Primer
2.4 Content Manager installation for Windows NT
            The following sections guide you through the steps required to install the
            Content Manager for Windows NT. For detail information related the
            installation, see the IBM Content Manager for Multiplatforms: Planning and
            Installation Guide, GC26-9831.

            The steps to install the Content Manager are:
            1. Start the installation and selecting the components
            2. Answer for the question related Text Search management
            3. Set client/server configuration options
            4. Install the library server
            5. Install the object server
            6. Generate a network table
            7. Install the system administration client and gateway
            8. Copy Content Manager files and complete installation

2.4.1 Starting the installation and selecting the components
            Start the Content Manager installation from the CD-ROM. From an MS-DOS
            prompt, Type: x:\win\[lang_code]\setup, where x is your CD-ROM drive and
            lang_code is the language you are using. English is \ENU.

            When the setup program begins, follow the instructions in the installation
            wizard on Windows.

            When the Component Selection window opens, select all of the components
            listed (as shown in Figure 7 on page 18). This installs all of the components
            that are available on the Windows NT Server. Then verify that you have
            enough disk space. The installation wizard verifies that you have the correct
            prerequisites for installing Content Manager.




                                                         Chapter 2. Content Manager installation   17
                 Figure 7. Component Selection for Content Manager


2.4.2 Text Search management option
                 After you click the Next button on the Component Selection window, a
                 question box is shown (Figure 8). Select No in our configuration.




                 Figure 8. Answering for Text Search

                 If you have installed the text search server software on your machine, select
                 Yes for Text Search management.




18   IBM Enterprise Information Portal - A Primer
When you select Yes without installing the text search server software on
your machine, you have to change the System Administration Client
Properties after the Content Manager installation. Follow these steps:
1. Right-click Start.
2. Select Open All Users (as shown in Figure 9) and then select Start Menu
   window where some objects appear.
3. Select the Programs icon in the Start Menu, and then select the IBM DB2
   Digital Library and EDMSuite VisualInfo in the Programs.
4. Right-click System Admin Client, and select Properties.
5. Select Shortcut in System Administration Client Properties, and remove -t
   option in the Target (as shown in Figure 10).




Figure 9. Selection of Open All Users




                                        Chapter 2. Content Manager installation   19
                 Figure 10. System Admin Client Properties




2.4.3 Setting client/server configuration options
                 In the Client/Server Configuration window, you specify whether you will be
                 using the DB2 or Oracle database with Content Manager. Also, you will need
                 to specify how to generate the network table.

                 Select the following options that allows you to set the Client/Server
                 Configuration as shown in Figure 11.




20   IBM Enterprise Information Portal - A Primer
Figure 11. Setting Client/Server Configuration

Select IBM DB2 for Database Creation.

Select both databases (Library Server Database and Object Server
Database) to create them.

If you want to replace one or more existing databases with new databases of
the same name, select Replace existing server database(s). If you do not
select this, and a database of the same name exists, the installation program
will not create a new database. For information on using or replacing existing
databases, see the IBM Content Manager for Multiplatforms: Planning and
Installation Guide, GC26-9831.

Select the option to generate a new network table. This option generates the
network table for the target workstation based on the installation information
you enter. For further information, see "Network table file for Windows
components" on the IBM Content Manager for Multiplatforms: Planning and
Installation Guide, GC26-9831.

When you are have completed entering this information, click Next.




                                                 Chapter 2. Content Manager installation   21
2.4.4 Installing the Library Server
                 Because we selected Library Server Database on the Client/Server
                 Configuration window, the Library Server Database window will open.

                 For creating a DB2 Library Server database on the your new or existing DB2
                 database, enter the Library Server database name, the database drive,
                 database description, and the Object Server database name. Use the default
                 values for Variable character lengths as shown in Figure 12.




                 Figure 12. Installing Library Server Database

                 We didn't check the enable Unicode support box because we used the default
                 language US_ENGLISH. If you want to enable Unicode support for your
                 database, check the enable Unicode support box.

                 When you complete your Library Server settings, click Next.

2.4.5 Installing the Object Server
                 Because we selected Object Server Database on the Client/Server
                 Configuration dialog, the Object Server Database window will open.

                 For creating a DB2 object server database on the your new or existing DB2
                 database, verify, enter, and click that the Object Server database attributes
                 are correct (see Figure 13).


22   IBM Enterprise Information Portal - A Primer
            Figure 13. Installing Object Server Database

            If you check the check box following Do you want to enable the Media
            Object Server feature?, the VideoCharger component will be installed.
            Check the box if you want to enable Content Manager to communicate with
            the VideoCharger component. You might choose to attach a media archiver to
            the Content Manager and VideoCharger to serve as the de-staging area for
            media objects. For more information, see the IBM Content Manager for
            Multiplatforms: Planning and Installation Guide, GC26-9831.

            When you complete your object server settings, click Next.

2.4.6 Generating a network table
            Since we selected Generate a new network table on the Client/Server
            Configuration dialog, the Network Table Generation window opens. It prompts
            you for information about the Library Server and Object Server. This
            information refers to the servers that connect to the workstation where you
            are currently installing components.

            Select the platforms for the Library Server and Object Server. In our case, we
            are using Windows NT. Also check the Server name, Port number and Host
            name for both the Library and the Object Server as shown in Figure 14.




                                                           Chapter 2. Content Manager installation   23
                 Figure 14. Generating Network Table

                 When you complete your network table generation settings, click Next.

2.4.7 Installing the System Administration Client and Gateway
                 Because we are installing the System Administration Components, the
                 System Administration Gateway window opens. Enter a unique number that
                 identifies the System Administration Gateway's TCP/IP port to the System
                 Administration Client and the TCP/IP host name for the machine that contains
                 the System Administration Gateway as shown in Figure 15.

                 When you have completed your system administration gateway configuration,
                 click Next.




24   IBM Enterprise Information Portal - A Primer
            Figure 15. Installing System Administration Client and Gateway


2.4.8 Copy Content Manager files and complete the Installation
            The Start Copying Files dialog opens to complete the installation, (as shown
            in Figure 16). It asks you to confirm the parameters you have entered. If any
            parameters are incorrect, you can return to previous dialogs by clicking on the
            Back button. Otherwise, the installation program will begin installing the
            program files.




                                                             Chapter 2. Content Manager installation   25
                 Figure 16. Start Copying Files

                 When the installation is complete, you will see the following message window
                 (see Figure 17). Choose Yes to restart the workstation and click Finish.




                 Figure 17. Content Manager Installation complete




26   IBM Enterprise Information Portal - A Primer
            If you receive an error message during the installation, consult the IBM DB2
            IBM Content Manager for Multiplatforms: Planning and Installation Guide,
            GC26-9831, or the IBM Content Manager for Multiplatforms: Messages and
            Codes, SC27-0874.

            If you received a message during installation, you can view it in the
            frnninst.log file in your Windows NT directory. For example:
            c:\winnt\frnninst.log



2.5 Starting and stopping the servers
            This section describes how to start and stop the Library Server and the
            Object Server of Content Manager.

            For other platforms and configurations refer to the IBM Content Manager for
            Multiplatforms: Planning and Installation Guide, GC26-9831.

2.5.1 Starting the Library Server
            To start a Library Server:
            1. Click Start on the Windows task bar.
            2. Select Programs - IBM DB2 Digital Library and EDMSuite VisualInfo -
               Library Server (LIBSRVRN) and wait until the server's state says
               Accepting requests, as shown in Figure 18.




            Figure 18. Library Server Status




                                                      Chapter 2. Content Manager installation   27
2.5.2 Starting the Object Server
                 To start an Object Server:
                 1. Click Start on the Windows task bar.
                 2. Select Programs - IBM DB2 Digital Library and EDMSuite VisualInfo -
                    Object Server (OBJSRVRN) and wait until the server's state says
                    Accepting requests, as shown in Figure 19.




                 Figure 19. Object Server Status




2.5.3 Stopping the servers
                 Before stopping your Library Server or Object Server, ensure that there is no
                 activity on the server:
                 1. Ensure that the library server or object server has completed all
                    transactions.
                     For Windows NT, click Refresh Now on the server graphical interface to
                     view the current status. If transactions are being processed, you can use
                     the command utility with the Pause command to stop the server from
                     receiving new transactions. For additional information about the command
                     utility, refer to the IBM Content Manager for Multiplatforms: Planning and
                     Installation Guide, GC26-9831.
                 2. Ensure that there are no clients logged on to the library server. Use the
                    system administration program to verify that no clients are logged on to



28   IBM Enterprise Information Portal - A Primer
               the library server. Select License - List users to list the users currently
               using your system. If necessary, you can use the Log off button on the
               List Users window to force a user off the system.
            3. Ensure that the object server functions (the de-stager, purger, media
               de-stager, media purger, and migrator) are not active.

            Stop the Library Server before stopping the object server, to ensure that no
            client activity is pending and all client transactions have completed.

            For Windows NT, the server graphical interface displays the status. Click
            Refresh to determine if an object server function is enabled. Select the
            function that you want to stop and click Disable.

            To stop a library server or an object server, click Shut Down.


2.6 Starting the System Administration program
            You can use the system administration program for most of your
            administration tasks. The system administration program consists of two
            parts: the system administration client, and the system administration
            gateway. If you install the client and gateway on different workstations, both
            parts must be active for you to run the system administration program. The
            library server that you want to work with must also be active before you start
            the system administration client. The system administration program runs on
            Windows NT or Windows 95. You can run the system administration program
            as a local application or as an applet from a Web browser.

            For additional information on using the program and on the functions the
            program provides, see the IBM Content Manager for Multiplatforms: System
            Administration Guide, GC26-0868, or the on-line help that is available from
            every window.

            This section has instructions for:
            - Starting and stopping the System Administration Client
            - Starting and stopping the System Administration Gateway
            - Running the System Administration Program as an applet

2.6.1 Starting and stopping the System Administration Client
            If you install the system administration gateway on a different workstation, the
            gateway must be active before you start the system administration client. The
            library server that you want to work with must also be active.




                                                      Chapter 2. Content Manager installation   29
                 To start the system administration client:
                 1. Click Start on the Windows task bar.
                 2. Select Programs - IBM DB2 Digital Library and EDMSuite VisualInfo -
                    System Admin Client, and log on with the default user ID = FRNADMIN,
                    and password = PASSWORD as shown in Figure 20. Then the system
                    administration client window appears (as shown in Figure 21).




                 Figure 20. System Administration Client Logon

                 For performance reasons, when you install the system administration client
                 and gateway on the same workstation, the client bypasses the gateway and
                 communicates with the servers through the client toolkit. If there are no
                 remote system administration clients that are using the local gateway, you
                 can stop the gateway to improve system performance.




30   IBM Enterprise Information Portal - A Primer
           Figure 21. System Administration Client

           To stop the system administration client, close the System Administration
           window.

           For additional information about the system administration client, refer to the
           IBM Content Manager for Multiplatforms: System Administration Guide,
           GC26-0868.

2.6.2 Starting and stopping the System Administration Gateway
           To start the system administration gateway:
           1. Click Start on the Windows task bar.
           2. Select Programs - IBM DB2 Digital Library and EDMSuite VisualInfo -
              System Admin Gateway, and wait until the message System Admin
              Gateway Started appears, as shown in Figure 22.




           Figure 22. System Administration Gateway



                                                      Chapter 2. Content Manager installation   31
                 To stop the gateway, click Shut Down on the System Admin Gateway
                 window.

                 Before you stop the system administration gateway, ensure that no clients are
                 using it.

2.6.3 Run System Administration as an applet from a Web browser
                 You can use a Web browser to run the system administration program, and
                 you do not need to install the system administration client on every
                 workstation that you want to use for system administration. The system
                 administration program supports the following Web browsers:
                 - Netscape Navigator, version 3.0 or higher
                 - Microsoft Internet Explorer, version 4.0 or higher

                 To set up the system administration program to run from a Web browser:
                 1. Install the following software on the workstation that you want to use as
                    the Web server:
                     The Web server software
                        For information on using the Web server software, refer to the
                        documentation for your Web server software.
                     The system administration gateway
                        The gateway must be active before you start the system administration
                        program from the Web browser.
                     The system administration client
                 2. Install a supported Web browser on the workstation that you want to use
                    for system administration and use the sample HTML file provided to
                    automatically install the required Java plug-in.
                     For automatically installing the Java plug-in for your Web browser, refer to
                     the IBM Content Manager for Multiplatforms: System Administration
                     Guide, GC26-0868

                 To start the system administration program from a Web browser:
                 1. Log on from Web browser to the workstation where the system
                    administration gateway is installed, as shown in Figure 23.




32   IBM Enterprise Information Portal - A Primer
Figure 23. Logon to System Admin Gateway Workstation from a Web browser

2. As a system administration client, log on with the default user ID =
   FRNADMIN and password = PASSWORD (see Figure 24). Then the
   system administration applet window appears (as shown in Figure 25).




                                              Chapter 2. Content Manager installation   33
Figure 24. System Administration Program Logon from a Web browser




34    IBM Enterprise Information Portal - A Primer
Figure 25. System Administration Program from a Web browser

                  To stop the system administration client, close the system administration
                  applet window.

                  For additional information about the system administration client, refer to the
                  IBM Content Manager for Multiplatforms: System Administration Guide,
                  GC26-0868 .




                                                              Chapter 2. Content Manager installation   35
36   IBM Enterprise Information Portal - A Primer
Chapter 3. Installing and configuring the IBM EIP

                  The Enterprise Information Portal (EIP) version 6.1 is a comprehensive
                  product, that is, its components work together to provide a solution uniquely
                  suited to your enterprise. Centered on a multiple-tier architecture, EIP
                  includes an administration program for managing searches, a client for
                  running searches, and connector classes for connecting to disparate content
                  servers such as Digital Library and VisualInfo, ImagePlus for OS/390,
                  OnDemand, and Domino.Doc.

                  This chapter describes how to install EIP version 6.1 on your system to run
                  the client applications which are described in this book.


3.1 EIP configuration
                  Because it has a multiple tier architecture, EIP can be configured in several
                  ways. EIP is used to run federated searches. A federated search is a search
                  that runs against disparate content servers. This section describes two of the
                  possible EIP configurations using Local and Java Remote Method Invocation
                  (RMI), which are used to demonstrate the client applications discussed in this
                  book.

                  You must install the following components to run a federated search:

                  EIP database
                  A DB2 Universal Database is used as a repository for the information
                  required to search the content servers. The EIP database stores the
                  information managed by the administration program and the data used to run
                  federated searches. Installing the administration program installs the
                  federated access runtim e, a set of files that you must install to connect to the
                  EIP database.

                  EIP administration program
                  The EIP administration program manages the data used for federated
                  searches, and the users that run federated searches.The system
                  administrator uses the EIP administration program to define each content
                  server and store the server definitions in the EIP database. The system
                  administrator maintains an inventory of the search fields for all content
                  servers. The system administrator creates search templates and identifies
                  the users who can access them. All of this information is stored in the EIP
                  database.




© Copyright IBM Corp. 2000                                                                      37
                 Content server runtimes
                 There is a runtime for each supported content server that contains the
                 connector class to access to the content server. You must install the
                 appropriate runtimes to access the content servers. For example, if you want
                 to connect to Domino.Doc servers you must install the Domino.Doc access
                 runtime from the EIP CD. The EIP CD ships with a federated access runtime
                 and a runtime for each content server. The federated access runtime contains
                 the connector class for the EIP database. You can install runtimes on your
                 client workstations or on your Remote Method Invocation (RMI) sever.

                 EIP client
                 Whether you use the EIP, run the EIP thin client from your Web server, or
                 write your own client, you must install a client that works with the connector
                 classes.In this case you will install the client applications which are described
                 in this book.

                 Local configuration
                 The Java client application discussed in this book, uses a local configuration
                 as shown in Figure 26.



                  Local Configuration
                                                            EIP Client
                                                            program




                                Content Server      Content Server       Content Server




                                                    Web Server

                 Figure 26. Local configuration

                 In a local configuration, EIP runtimes are installed on the EIP client
                 workstations or the Web server in our case. A local configuration is beneficial



38   IBM Enterprise Information Portal - A Primer
because all the clients run independently. However, the local configuration
requires that all of the necessary runtimes are installed on each client.

Remote configuration with RMI server
The Lotus Notes client application discussed in this book, uses a RMI server
configuration as shown in Figure 27.



 Remote Configuration

                                               Web Server




                                                             EIP Client
                              RMI Server                     program




             Content Server       Content Server    Content Server

Figure 27. Remote configuration

In a remote configuration the Notes client is connected over the LAN to an
RMI server. Remote Method Invocation (RMI) allows the client to call
runtimes on the RMI server, so the necessary runtimes can be shared.
Because all the necessary runtimes can be shared on the RMI server, the
remote configuration is easily maintained and scales well.

For more details on how to configure EIP, please refer to the “IBM Enterprise
Information Portal for Multiplatforms, User’s and Administrator’s guide”.

Creating clients for EIP
You must install the toolkits to create custom client applications. You can use
the EIP federated access and content server toolkits to create customized
applications that can perform federated searches. The toolkits provide:
 • Java and C++ classes
 • Content server-specific samples


                                            Chapter 3. Installing and configuring the IBM EIP   39
                 You can install the toolkits by selecting the installation component Toolkits
                 and Runtimes. If you do not write your client in Java, you cannot use the RMI
                 server.

                 For information about creating customized applications see OO and Internet
                 Application Programming Guide and OO and Internet Application
                 Programming Referenc e.

                 If you want to develop a custom client you must install the appropriate
                 toolkits.

                 For example, if you are having Java application and you want to extend its
                 features to include federated searches using Domino.Doc, OnDemand, and
                 Digital Library and VisualInfo servers, you should install the following
                 components on your development workstation:
                  • Federated access toolkit
                  • Digital Library and VisualInfo toolkit
                  • Domino.Doc toolkit
                  • OnDemand toolkit




40   IBM Enterprise Information Portal - A Primer
3.2 EIP prerequisites
            To run the client application which are described in this book, you need to
            have the minimum hardware and software which are listed in Table 3, Table 4
            and Table 5.
            Table 3. RMI Server hardware and software requirements

             Category                      Required hardware / software

             Processor                     400 Mhz Intel Pentium II

             RAM                           128 MB

             Storage                       2 GB

             Display and Adapter           1024x768x256

             Operating system              Windows 95, Windows 98, or Windows NT 4.0 with service
                                           pack 4 or greater

             Network support               Microsoft Networking Services

            Table 4. EIP database hardware and software requirements

             Category                      Required hardware / software

             Processor                     400 Mhz Intel Pentium II

             RAM                           128 MB

             Storage                       1 GB

             Display and Adapter           1024x768x256

             Operating system              Microsoft Windows NT 4.0 with servicepack 4 or greater

             Database                      DB2 Universal Database (UDB) Version 5.2 or 6.1

             Network support               Microsoft Networking Services



            Table 5. EIP client hardware and software requirements

             Category                      Required hardware / software

             Processor                     400 Mhz Intel Pentium II

             RAM                           64 MB

             Storage                       2 GB

             Display and Adapter           1024x768x256




                                                     Chapter 3. Installing and configuring the IBM EIP   41
                  Category                          Required hardware / software

                  Operating system                  Windows 95, Windows 98, or Windows NT 4.0 with service
                                                    pack 4 or greater

                  Web browser                       Netscape Navigator 3.0 or later
                                                    Microsoft Internet Explorer 3.02 or later

                  Network support                   Microsoft Networking Services

                 For a detailed list of EIP prerequisites, please refer to the “IBM Enterprise
                 Information Portal for Multiplatforms, User’s and Administrator’s guide”.


3.3 Installing and configuring EIP components
                 To demonstrate the client applications which are discussed in this book, we
                 will use a server machine and a client workstation machine to install the EIP
                 components.

                 This section describes the procedures to be followed for installing various EIP
                 components both in the server as well as in the client. Before installing the
                 components, ensure that your system meets all the prerequisites for the
                 respective systems.

                 Note: When you install the EIP, the windows client for OnDemand will be
                 automatically installed. Optionally you can also install Net.Data in your
                 machine. To install, follow the steps during the installation.

3.3.1 Installing and configuring EIP on the server machine
                 This section describes how to install and configure the EIP components on
                 the server. See the component selection screens in Figure 28 and Figure 29.




42   IBM Enterprise Information Portal - A Primer
Figure 28. Component selection

                 Important: You must install DB2 UDB on the Windows NT, before you install
                 the EIP database and you must install the EIP database using your DB2
                 administrator user ID.
                 1. Insert the Enterprise Information Portal CD in the CD drive.
                 2. Click Start—>Run on the Windows taskbar.
                 3. In the Run window, type:
                     D:\WIN\ENU\Setup.exe
                     Where D is your CD drive,WIN is the directory for windows installation files
                     and ENU is the three-character abbreviation for your workstation’s locale.
                 4. Click OK and follow the instructions in the installation program.
                 5. When your are prompted with the Component selection Dialogbox, select
                    the necessary components:
                     a. Under Component, select Administration.
                     b. Under Subcomponent, select both Administration program and the
                        EIP database.


                                                     Chapter 3. Installing and configuring the IBM EIP   43
                     c. Under Component, select Runtimes.
                     d. Under Subcomponent, select all necessary runtimes
                     e. Under Component, select Features.
                     f. Under Subcomponent, select both the Text Search Server and Client.
                     g. Click Next to continue the installation program.
                 6. Generate a new network table for the DL/VI runtimes.
                 7. Configure the Text Search Server / Client.
                 8. The installation program creates a DB2 UDB database for you. When you
                    are prompted, enter one to eight alphanumeric characters as your
                    database name, for example, eipdb and a drive where you want to create
                    the database.
                     Record the name of your EIP database for reference.
                     If nothing is entered, the database name defaults to cmbdb and the drive
                     defaults to the drive on which DB2 is installed.
                 9. When you finish the installation program, reboot your server.
                 10.Ensure that the variables in cmbcs.ini are set to “local”




44   IBM Enterprise Information Portal - A Primer
Figure 29. Text Search Server/Client configuration

Configuring your RMI Server

After you install the content server runtimes, you must configure your RMI
server. To configure the RMI server:
1. From the EIP installation directory, open cmbregist.bat in a text editor.
2. You can change the port number in the following line, or accept the default
   port number, 1919:
   set remotePort=1919
3. Change the following line to match your configuration:
   %CMBROOT%\jre\bin\jre -cp %classpath%
   -Djava.rmi.server.codebase=http://com.ibm.mm.sdk.remote.DKRemoteMa
   inImp %remotePort% 0 10 TS QBIC DL JDBC Fed V4 IP DD OD DES
   where:
   0 Change 0 to a number that represents the maximum number of
   connections that the RMI server can concurrently process. The default is 0
   which is used to indicate there is no maximum number of connections for


                                          Chapter 3. Installing and configuring the IBM EIP   45
                     this RMI server. This is the suggested setting for a single or master RMI
                     server.
                     10 Is the number of server types that are supported by the RMI server.
                     TS QBIC DL JDBC Fed V4 IP DD OD DES are the server types supported
                     by the RMI server. You can type the RMI server variables in any order.
                 4. After you change the variables in the file, ensure that the number you
                    typed before the list of RMI server variables matches the number of server
                    variables listed.
                 5. Save cmbregist.bat.
                 6. From the EIP installation directory, open cmbcs.ini in a text editor.
                 7. Since we have installed all the runtimes in the server itself, set all the
                    runtimes to be “local”.
                 8. Save cmbcs.ini.
                 9. Start the RMI server by running the cmbregist command.

                 For more details on how to setup the variables on cmbregist.bat and
                 cmbcs.ini please refer to the “ IBM Enterprise Information Portal for
                 Multiplatforms, User’s and Administrator’s guide”.

                 Managing Text Search Server
                 1. To start the Text Search server, open the MS-DOS window.
                 2. Change directory to the CMBROOT (or) if the CMBROOT is in the path
                    proceed to the next step.
                 3. At the command prompt enter:
                     imlss -start dlinst
                     Where dlinst is the name of your text search server instance chosen at
                     installation time or when using the imlcfgsv command utility.
                 4. To stop the Text Search server, open the MS-DOS window.
                 5. Change directory to the CMBROOT (or) if the CMBROOT is in the path
                    proceed to the next step.
                 6. At the command prompt enter:
                     imlss -stop dlinst
                     Where dlinst is the name of your text search server instance chosen at
                     installation time or when using the imlcfgsv command utility.
                 7. To view the status of the Text Search server, open the MS-DOS window.




46   IBM Enterprise Information Portal - A Primer
8. Change directory to the CMBROOT (or) if the CMBROOT is in the path
   proceed to the next step.
9. At the command prompt enter:
   imlss -status dlinst
   Where dlinst is the name of your text search server instance chosen at
   installation time or when using the imlcfgsv command utility.

Text Search Server Administration
You can administer the Text Search server using the Digital Library /
VisualInfo System Administration client.

While installing the text search server, you will be prompted whether you want
to update the system admin client's shortcut to enable the administration of
the text search server from the system admin client.

If you have clicked "YES", the installation procedure will update your DL/VI
system administration client shortcut. Next time when you start the system
administration client it will search for the text search server.

If you have clicked "NO" and later you want to add the administration of the
Text search server to the DL/VI system admin client follow the steps:
1. Open the Properties dialog box for the DL/VI system administration
   shortcut.
2. Click on the Shortcut tab.
3. Add a -t to the target field.
   The target field should read:
   %cmbroot%\frnnacl.exe sa.client.SajcAdmin hostname -p 6021 -t -l en US
   Where %cmbroot%\frnnacl.exe sa.client.SajcAdmin specifies the application
   and its location on the system, hostname is the host name of the Digital
   Library and VisualInfo system administration gateway, -p 6021 specifies
   the port number, -t specifies that the text search component is installed,
   and -l en US specifies the locale.
4. Click OK.

You should update the system's CLASSPATH environment variable, to use
the system administration client as the tool for Text search administration.

CLASSPATH should include:

  %cmbroot%\lib\frnntmgw.jar;%cmbroot\lib\swingall.jar




                                   Chapter 3. Installing and configuring the IBM EIP   47
3.3.2 Installing and configuring EIP on the client machine
                  This section describes how to install and configure the EIP components on
                  the client. See Figure 30.
                  1. Insert the Enterprise Information Portal CD in the CD drive.
                  2. Click Start—>Run on the Windows taskbar.
                  3. In the Run window, type:
                      D:\WIN\ENU\Setup.exe
                      Where D is your CD drive,WIN is the directory for windows installation files
                      and ENU is the three-character abbreviation for your workstation’s locale.
                  4. Click OK and follow the instructions in the installation program.




Figure 30. Component selection

                  5. When your are prompted with the Component selection Dialogbox, select
                     the necessary components:
                      a. Under Component, select Client.




48    IBM Enterprise Information Portal - A Primer
   b. Under Subcomponent, select Enterprise Portal client and the
      necessary viewers.
   c. Under Component, select Runtimes.
   d. Under Subcomponent, select all necessary runtimes
   e. Click Next to continue the installation program.
6. Generate a new network table for the DL/VI runtimes.See Figure 31.




Figure 31. Network Table Generation for DL/VI

7. When you finish the installation program, reboot your workstation.
8. Ensure that the variables in cmbcs.ini are set to “remote”

Configuring your RMI client

After you install the EIP client, you must configure your RMI client to be able
to talk to the RMI server.The cmbclient.ini file is a file that is installed with the
administration program and with every client that locates the RMI server. If
your configuration includes an RMI server, you must set cmbclient.ini on the
workstation where the administration program or client is installed.



                                        Chapter 3. Installing and configuring the IBM EIP   49
                 To set the cmbclient.ini file:
                 1. From the EIP installation directory, open cmbclient.ini in a text editor.
                 2. Delete the number sign ( #) next to the key words RemoteHost and
                    RemotePort. The number sign indicates a comment in the file
                 3. Type your RMI server host name and port number as follows:
                     RemoteHost=ITSO007
                     RemotePort=1919
                     Where ITSO007 is the RMI server host name and 1919 is the RMI server port
                     number.


3.4 Final tasks to be completed
                 Before you run the client applications discussed in this book you should
                 complete the following tasks.

                 EIP provides the administration program to assist you in administering
                 federated searches. This section describes concepts and procedures for
                 using the administration program and other tasks that should be performed
                 before running the client applications.

                 This chapter gives an overview of each task. For more detailed instructions
                 please refer to the “ IBM Enterprise Information Portal for Multiplatforms,
                 User’s and Administrator’s guide”.

                 Starting the EIP Administration program
                 To start and log into the EIP administration program:
                 1. Click Start -> Programs -> IBM Enterprise Information Portal for
                    Multiplatforms -> Administration from the Windows taskbar.
                 2. In the EIP Administration window enter a valid EIP user ID and password.
                    The default user ID is ccadmin and the default password is password.
                 3. Select the EIP database you want to access.
                 4. Click OK.

3.4.1 Defining content servers and running server inventory
                 Once you have a list of the content servers that store the items that need to
                 be returned, you can use the EIP administration program to define the
                 content servers and list all the native entities and attributes in each content
                 server.



50   IBM Enterprise Information Portal - A Primer
You define a content server in the administration program using the following
steps (see Figure 32):
1. From the administration panel, select Servers group.
2. Right click on Servers group -> New -> select the type of content
   server you are going to add.




Figure 32. Defining a content server

3. In the New server dialog box, specify the name of the server (see
   Figure 33).
4. You can also specify additional information in the Initialization parameters
   tab.




Figure 33. Initialization parameters tab



                                           Chapter 3. Installing and configuring the IBM EIP   51
                 5. Test the connection to the server by clicking on Test connection button.
                 6. Click OK to save.

                 After you define the content servers, you can run the server inventory
                 program to list their native entities and attributes. Each type of content server
                 has its own set of native attributes and native entities. Native attributes are
                 the labels used for metadata in content servers, for example, key fields are
                 native attributes in IBM DB2 Digital Library and EDMSuite VisualInfo content
                 servers. Native entities are content server objects that contain native
                 attributes.

                 For example, Digital Library and VisualInfo index classes are native entities
                 comprised of Digital Library and VisualInfo key fields. As an administrator,
                 you must understand the native attributes and entities of all necessary
                 content servers, so you can map the appropriate native attributes to a
                 federated attribute that are used for searching.

                 For a detailed list of content server entities and attributes please refer to the
                 “ IBM Enterprise Information Portal for Multiplatforms, User’s and
                 Administrator’s guide”.

                 To run the server inventory:
                 1. Select the content server from the Servers group.
                 2. Right click on the Content server and select Refresh server Inventory.

3.4.2 Creating federated entities
                 You must create a federated entity to associate with the search template (see
                 Figure 34). A federated entity is a EIP object that contains federated
                 attributes. You should create a federated entity that describes the information
                 the federated attributes contain. For example, create a federated entity
                 named RES_Members_EIP.

                 To create the Federated entity:
                 1. Select Federated entities group in the Administration panel.
                 2. Right click on Federated entities and select New.
                 3. Specify the name of the Federated entity and description.
                 4. Add all the Federated attributes for this entity.
                 5. Define the mapping for all the attributes.
                 6. Click OK to save.




52   IBM Enterprise Information Portal - A Primer
            Figure 34. Federated entity definition


3.4.3 Creating and mapping federated attributes
            A federated attribute is a EIP metadata category that is mapped to native
            attributes in one or more content servers. You can map a federated attribute
            only to native attribute with the same properties, such as the ability to be
            queried or updated.

            To create a federated attribute for an entity (see Figure 35):
            1. Select the Federated entity or create a new entity.
            2. From the Federated entity dialog box, click Add to add a federated
               attribute.
            3. Select whether you want to add a new federated attribute or existing
               attribute.
            4. Specify the Name, type and other options.
            5. Click on OK.




                                                     Chapter 3. Installing and configuring the IBM EIP   53
                 Figure 35. Federated attribute definition

                 To map the Federated attributes in the Federated Entity (see Figure 36):
                 1. From the Federated attribute dialog box, select the Federated entity and
                    click on the Map Federated attribute button.
                 2. From the Federated entity Mapping dialog box, select the Federated
                    entity, the content server, Native entity, and the Native attribute.
                 3. click on Add.
                 4. Repeat step 2 and 3 until you have mapped all the Federated attributes.
                 5. Click OK.




54   IBM Enterprise Information Portal - A Primer
Figure 36. Federated attribute mapping


3.4.4 Creating federated text indexes
                  If you are using IBM DB2 Digital Library and EDMSuite VisualInfo servers
                  with the text search server, you can create a federated text index and map it
                  to the Digital Library and VisualInfo text index on the Digital Library and
                  VisualInfo text servers.

                  When you create the federated text index, you can enable it for combined
                  searching, that is, for searching both native text indexes and native attributes.
                  When enabling a federated text index for combined searches, you also map
                  that index to a federated entity and map the native attributes mapped by that
                  federated entity and its federated attributes to the native text indexes on the
                  text servers.




                                                      Chapter 3. Installing and configuring the IBM EIP   55
3.4.5 Creating search templates
                 After you have created the necessary objects, you can create a search
                 template. Creating a search template involves associating the appropriate
                 EIP objects and defining search criteria. Each search criterion is mapped to a
                 federated attribute. You can create the search templates using the
                 Administration program, which users will use to find necessary information.

                 The scope of this book does not cover the Search Templates. If you want to
                 know more details on Search templates, please refer to “IBM Enterprise
                 Information Portal for Multiplatforms, Users and Administrators Guide”.




56   IBM Enterprise Information Portal - A Primer
Chapter 4. Java client for Content Manager using WebSphere

                  This chapter discusses how to build a Java client application to search the
                  Content Manager datastore. Our application is written as Java servlets, so we
                  need an application server to execute the servlets. We used the IBM
                  WebSphere application server for this purpose.

                  Using this client application, we can do three types of searches: a parametric
                  search, a text search, and a combined search which executes a parametric
                  search and a text search at the same time and produces as a result, the
                  combined set of the two searches.


4.1 Getting ready for developing the application
                  This section is a test case for developing the application.

                  We briefly describe how we installed and configured the application server,
                  configured the Java environment, and loaded the data into the servers.

                  The system environment needs to be configured so that we can compile and
                  execute a Java program using the Java APIs of EIP.

                  Finally, to search a document, we should have some documents stored in the
                  servers before we try to find a document. We call this process of storing data
                  in the Content Manager server loading, and there are some sample loading
                  programs provided with the EIP development toolkits. We used one of them.

                  Note: The installation and customization of IBM WebSphere Application
                  Server is described in the Appendix B.

4.1.1 Configuring IBM WebSphere Application Server
                  After you install the IBM WebSphere Application Server on your machine,
                  perform these configuration steps before running a Java servlet using the EIP
                  APIs.
                  1. Click Start - Programs - IBM WebSphere - Application Server -
                     Administration.
                  2. Log into the WebSphere Administration.
                  3. In the left pane, click Setup - Java Engine.
                  4. In the right pane, click the Paths tab.
                  5. On the Paths page:



© Copyright IBM Corp. 2000                                                                    57
                     a. Next to Use System Classpath, type No.
                     b. In the Application Server Classpath field, append the following text to
                        the end of the field. Substitute the root where you installed Enterprise
                        Portal for c:\cmbroot.
                        c:\cmbroot\lib\cmb30.jar;c:\cmbroot\lib\cmbcm30.jar;c:\cmbroot\lib\c
                        mbdd30.jar;c:\cmbroot\lib\cmbddc30.jar;c:\cmbroot\lib\cmbdes30.jar;c
                        :\cmbroot\lib\cmbdesc30.jar;c:\cmbroot\lib\cmbdl30.jar;c:\cmbroot\li
                        b\cmbdlc30.jar;c:\cmbroot\lib\cmbfed30.jar;c:\cmbroot\lib\cmbfedc30.
                        jar;c:\cmbroot\lib\cmbip30.jar;c:\cmbroot\lib\cmbipc30.jar;c:\cmbroo
                        t\lib\cmbjdbc30.jar;c:\cmbroot\lib\cmbjdbcc30.jar;c:\cmbroot\lib\cmb
                        od30.jar;c:\cmbroot\lib\cmbodc30.jar;c:\cmbroot\lib\cmbservlets30.ja
                        r;c:\cmbroot\lib\cmbv430.jar;c:\cmbroot\lib\cmbv4c30.jar;c:\cmbroot\
                        lib\swingall.jar;c:\sqllib\java\db2java.zip;c:\cmbroot\lib\ics.jar
                     c. Click Save.
                 6. In the left pane, click Setup - Sessions Tracking.
                 7. In the right pane, click the Enable tab.
                 8. On the Enable page:
                     a. Next to Enable URL Rewriting, click Yes.
                     b. Next to Enable Cookies, click Yes.
                     c. Click Save.
                 9. In the right pane, click the Persistence tab.
                 10.On the Persistence page, next to Persistence, click No and then click
                    Save.
                 11.You can leave the default values on the Server Execution Analysis page.
                 12.Define the initialization parameters for the thin client. Skip this step if you
                    are satisfied with the default initialization parameters.

                 This procedure is described in the file named %CMBROOT%\DOC\
                 thinClientInstall.html, where %CMBROOT% is the directory where the EIP
                 is installed.

4.1.2 Environment variables for compiling a Java program
                 Java APIs are applied to a Java program by importing some packages which
                 include API code. Currently there are four packages in the EIP client:
                  • com.ibm.mm.sdk.server
                     This package accesses and manipulates datastore information.
                  • com.ibm.mm.sdk.client



58   IBM Enterprise Information Portal - A Primer
                 This package is implemented for communication with the server package,
                 network control, and data transformation between the server and clients.
             • com.ibm.mm.sdk.common
                 This package is needed by the server package and the client package.
             • com.ibm.mm.sdk.cs
                 This package connects the client and server dynamically across the
                 network.

            All programs in our application are server programs, so we imported
            com.ibm.mm.sdk.common and com.ibm.mm.sdk.server.

            Note: A program cannot import the server package and the client package at
            the same time. A server program must use the server package, a client
            program must use the client package.

            The following libraries are to be set in the environment variable CLASSPATH
            to enable the Java compiler to find the packages imported and APIs used.
             •   cmbcm30.jar
             •   cmbdl30.jar
             •   cmbdlc30.jar
             •   cmbdd30.jar
             •   cmbddc30.jar
             •   cmbip30.jar
             •   cmbipc30.jar
             •   cmbod30.jar
             •   cmbv430.jar
             •   cmbv4c30.jar
             •   cmbfed30.jar
             •   cmbfedc30.jar
             •   cmbjdbc30.jar
             •   cmbjdcc30.jar
             •   cmbdes30.jar
             •   cmbdesc30.jar

            These libraries are all located in the directory %CMBROOT%\Lib, where
            %CMBROOT% is the directory where the EIP is installed.

4.1.3 Loading the sample data into the Content Manager server
            To get the result of searches, there must be some data loaded in the Content
            Manager server and the text server. We used the sample loader program
            provided with the EIP to load some data.



                                     Chapter 4. Java client for Content Manager using WebSphere   59
                 4.1.3.1 Generating index classes
                 To run the sample loader program, the first thing to do is to define the index
                 classes to be used. The loader program uses two index classes, one for the
                 Content Manager server and the other for the text server. The names of these
                 two index classes are:
                  • DLSAMPLE for the Content Manager server, which is generated when the
                    Content Manager server is installed
                  • TMINDEX for the text server, which is generated before running the
                    sample loader program

                 Because we already have the DLSAMPLE index class in the Content
                 Manager server, we only have to create the TMINDEX text index.

                 To create the TMINDEX text index:
                 1. Run the System Administration Client.
                 2. To start the system administration client, from the Windows task bar, click
                    Start - Programs - IBM DB2 Digital Library and EDMSuite VisualInfo -
                    System Admin Client. Login to the Content Manager server.
                 3. On the server selection list, select the text server.
                 4. Double-click on Search Servers, TM and Indexes (see Figure 37).




60   IBM Enterprise Information Portal - A Primer
Figure 37. Text Server Administration using the System Administration Client

                   5. Right-click on Indexes, and select New.
                   6. Create an index named TMINDEX. (See Figure 38)
                   7. Click OK.
                   8. You can now see the index you created by clicking the Indexes in the left
                      panel. (See Figure 39)




                                                 Chapter 4. Java client for Content Manager using WebSphere   61
Figure 38. Creating Text Index using the System Administration Client




62     IBM Enterprise Information Portal - A Primer
Figure 39. After Creating the Text Index TMINDEX

                  4.1.3.2 Running the sample loader program
                  Some sample programs are provided with the EIP client. They are written in
                  C++, Java, and Active X.You will find these programs at
                  %CMBROOT%\Samples directory.

                  Sample Java programs for the Content Manager server can be found at
                  %CMBROOT%\Samples\java\dl. To load data into our Content Manager
                  server and text server, we used a sample program in the directory named
                  LoadSampleTSQBICDL.java . It is a program to load sample data to the
                  Content Manager server, text server, and image server. Since we didn’t have
                  any image server, we commented out the code for loading data to the image
                  server.

                  To load sample data into the servers:
                  1. Unzip the sample data.
                      Two types of files are needed to run this program: one ia a file listing all
                      the files to be loaded, and the other is the actual data files. The listing file



                                               Chapter 4. Java client for Content Manager using WebSphere   63
                      is in the same directory as the sample program, and named
                      sampleQBIC.dat . Actual data files are zipped in the file named
                      samples.jar. Use a utility to unzip the file.
                 2. Open the sample program LoadSampleTSQBICDL.java in an text editor and
                    comment out the code for image loading.
                      In the program, there are some comments that can be used when there is
                      no text server or image server. The comments to prevent loading images
                      to the image server are:
                      /**** no image search by comment out following line ****/
                      /**** end of comment out for no image search ***********/
                      So if there is no text or image server, comment them out. An example is:
                      /**** no image search by comment out following line ****
                                 DKSearchEngineInfoDL aSrchEx2 = new DKSearchEngineInfoDL();
                                 aSrchEx2.setSearchEngine(searchEngineQBIC);
                                 aSrchEx2.setSearchIndex(searchIndexQBIC);
                                 aSrchEx2.setSearchInfo(searchInfo);
                                 xdo.setExtension("DKSearchEngineInfoDL",
                      (dkExtension)aSrchEx2);
                      **** end of comment out for no image search ***********/
                 3. Compile the program.
                      Compile the program with javac. An example is:
                      javac LoadSampleTSQBICDL.java
                 4. Run the program.
                      Run the program with proper arguments. Five arguments are needed to
                      run the program. They are:
                  •   Input data file name
                  •   Output log file name
                  •   User ID for the Content Manager server
                  •   Password for the user
                  •   The Content Manager library server name
                      So, an example command for running the loader program is:
                      java LoadSampleTSQBICDL sampleQBIC.dat qbic.log frnadmin password
                      libsrvrn
                      After running this program, some html files and image files which are
                      referenced in the html files are stored in the Content Manager server. Also
                      a text file is stored for each html file, which is used to make text search
                      index in the text search server.




64   IBM Enterprise Information Portal - A Primer
4.2 The client application
                   In this section, we will show you how our Java servlets work by showing the
                   web browser screens. There are three ways to search with this application: a
                   parametric search, a text search, and a combined search. We show you how
                   to do each of these searches using our application.

4.2.1 The input screen
                   In the first screen of our application, there are two criteria for search condition
                   inputs. One is the criteria for the parametric search (see Figure 40), which is
                   placed on the upper half of the input screen, and the other is for the text
                   search (see Figure 41).




Figure 40. Input area for parametric search




                                              Chapter 4. Java client for Content Manager using WebSphere   65
Figure 41. Input area for Text search

                   If you input the conditions for parametric search and text search at the same
                   time, a combined search is performed.

                   The URL for running our client application is:
                   http://our_host_name/servlet/MSInput

                   Where ‘MS’ stands for Multi-Search.

4.2.2 A parametric search
                   4.2.2.1 The input for the parametric search
                   When you want to find the documents that have a specific value as their
                   specific attributes, you can get the result by doing a parametric search (see
                   Figure 42).




66     IBM Enterprise Information Portal - A Primer
To enter the conditions for a parametric search:
1. Choose the index class to search within, and click Get Attributes button.
2. Select the attribute, and operator to search with and the value of the
   attribute. You can enter up to three conditions for a parametric search, with
   up to two concatenating conditions.
3. Set other values to decide the result list form.
   Other input values are as followings:
   a. Thumbnail ID field means the part number of the thumbnail object in
      the document. When specified, the object which has the same part
      number with the value will be shown at the result screen. The
      thumbnail ID will be decided when the index class is designed, and
      assigned when data are loaded into the Content Manager server. In our
      loader program, we loaded the thumbnail image on the part numbered
      5, so in the example screen, we set the thumbnail ID field to 5.
   b. Filter field means whether we limit the result set as the set of
      document, folder, or both. The default is both.
   c. Maximum Results field indicates how many results are to be retrieved.
      Blank in this field means all results will be retrieved from the Content
      Manager server.
4. Click Start Search button to see the result list.




                         Chapter 4. Java client for Content Manager using WebSphere   67
Figure 42. An example of parametric search input

                  4.2.2.2 The result list of the parametric search
                  In the result list screen of the parametric search, the number of documents
                  found is shown at the top of the result list table. Each cell of table shows one
                  document retrieved. This screen should be customer-specific, and we
                  assumed that there is an attribute named DLSAMPLE_Subject which
                  indicates the subject of a document. So the DLSAMPLE_Subject attribute is
                  retrieved and shown on the screen.

                  An example of a parametric search result list screen is shown in Figure 43.

                  When you find the document you are looking for in the result list, click the
                  thumbnail (if any) or the subject, and the detailed information of the document
                  will be displayed.




68    IBM Enterprise Information Portal - A Primer
Figure 43. An example of parametric search result

                  4.2.2.3 The content of a document
                  A document has attributes and parts. That is, to show the detailed content of
                  a document, we should show both the metadata of the document and the
                  parts relating to that document (see Figure 44).




                                                Chapter 4. Java client for Content Manager using WebSphere   69
Figure 44. An example of a document content

                  As you can see, the content screen consists of two parts, metadata and an
                  html file. Because we loaded an html file and several image files referred to in
                  the html file to the Content Manager server, we can show the content on the
                  Web browser.

4.2.3 A text search
                  4.2.3.1 The input for a text search
                  When you want to find documents that have specific words or phrases, you
                  can do a text search (see Figure 45).

                  To enter the conditions for text search in our application:
                  1. Search Index means the text index to be searched. Select one from the
                     list.




70    IBM Enterprise Information Portal - A Primer
                   2. Enter Text to be Searched . In our application, you can use several words
                      with ‘&’ and ‘|’ signs, ‘&’ for ANDing and ‘|’ for ORing the results. Search
                      words and ‘&’, ‘|’ signs should be separated with a space.
                   3. If you want to find documents which do NOT have certain words, you can
                      use the NOT condition by checking on the NOT check box.
                   4. You can also limit the number of results by assigning a value in Maximum
                      Return field. A blank in this field means all documents which meet the
                      search criteria will be retrieved.
                   5. Click Start Search to start your query.




Figure 45. An example of a text search input

                   4.2.3.2 The result list of a text search
                   When you run a text search, the text search server will execute the query and
                   return a list of matching documents(see Figure 46). All the text documents
                   are stored in the Content Manager server, and the text server stores the index




                                               Chapter 4. Java client for Content Manager using WebSphere   71
                   for those documents. So the result list of a text search contains the
                   information about the result of searching in the index.




Figure 46. An example of the text search result list

                   In the result list, DKDLItemId is the primary ID of the document in the
                   Content Manager server of which this text object is included as a part, and
                   the DKPartNo field indicates the part number of this text object in the
                   document.

                   DKRepType shows the type of this text object. FRN$NULL is the default
                   value of this field, which means no specific type was declared for this object
                   when it was loaded in the Content Manager server.

                   DKRank is an integer value which means how relevant this object is related
                   to the search condition. Usually the search result list is sorted by this value.




72     IBM Enterprise Information Portal - A Primer
                   DKMatches means how many times the given search word was found in the
                   object.

                   By clicking on the link at the end of each row, you can see the content of each
                   text object.

                   4.2.3.3 The content of a text file
                   This screen shows the text object which was used to make the text index, and
                   stored in the Content Manager server (see Figure 47). Again, the content is
                   stored in the Content Manager server and only the index for the content is
                   stored in the text server. So to retrieve the actual content, the Content
                   Manager server has to be accessed.




Figure 47. An example of the content of a text object




                                                  Chapter 4. Java client for Content Manager using WebSphere   73
4.2.4 A combined search
                  4.2.4.1 The input for a combined search
                  To do a combined search, you should specify both the input for a parametric
                  search and the input for a text search. Please refer to 4.2.2.1, “The input for
                  the parametric search” on page 66 for how to enter the conditions for
                  parametric search, and 4.2.3.1, “The input for a text search” on page 70 for a
                  text search. Specifying the two conditions at the same time will retrieve a
                  result list combining the two result lists.

                  One thing you should remember here is that the result is actually made by
                  combining the results of the two queries. So, if you specify a small number in
                  any of the maximum return fields, say 1, you may not get the right result for
                  your query, as the retrieved result list is limited by the maximum number given
                  and may not contain the document you are looking for. Therefore we put
                  blanks for both of the maximum return fields, see Figure 48.




Figure 48. An example of a combined search input




74    IBM Enterprise Information Portal - A Primer
                   4.2.4.2 The result list of a combined search
                   The result list of a combined search looks very similar to that of a parametric
                   search (see Figure 49). In fact, the only difference is that there is a Rank
                   value in a combined search. The Rank value has the same meaning as the
                   result list of a text search.

                   Clicking the thumbnail image, the Rank value, or the subject string will display
                   the content of the document stored in the Content Manager server.




Figure 49. An example of a combined search result list

                   4.2.4.3 The contents of a document
                   The contents of a document in a combined search is shown in the same
                   manner as in a parametric search, as Figure 44.




                                                 Chapter 4. Java client for Content Manager using WebSphere   75
4.3 The Java servlet programs
                 This section discusses how we developed the programs described in the
                 previous section.These programs were developed in Java language using the
                 EIP APIs. Important classes in EIP APIs for searching in the Content
                 Manager server are covered. Also the way to register a servlet in the IBM
                 WebSphere application server is described.

4.3.1 The running environment
                 This application is developed as Java servlets, which are executed by an
                 application server, in our case, IBM WebSphere Application Server.

                 In our configuration, there are three machines used (See Figure 50). Server A
                 is the Content Manager server, which has NT server 4.0 as its operating
                 system, and runs a library server, an object server, and a text server. Server
                 B is an application server, which has also NT server 4.0 as its operating
                 system, and runs a Web server, in our case Microsoft Internet Information
                 Server 4.0, and the IBM WebSphere Application Server as the application
                 server. Also in Server B, the IBM Enterprise Information Portal for
                 Multiplatform(EIP) is installed, which enables us to connect to the Content
                 Manager in the Server A. The third computer is the client machine, which has
                 NT workstation 4.0 as its operating system, and runs the Web browser,
                 Netscape Communicator 4.5 and Internet Explorer 4.0 in our configuration, to
                 run our application.

                 The programs which compose our application are placed in the servlet
                 directory of Server B.




                     Server A                 Server B              Client
                                          Web Server              Web Browser
                   Library Server
                   Object Server          Application Server
                   Text Server            EIP toolkit


                 Figure 50. The running environment of our application


4.3.2 The servlets flow
                 This application consists of five servlets; MSInput, MSList, MSContent,
                 MSMeta, and MSText. The prefix MS means Multi-Search. The functions of
                 each servlet are:



76   IBM Enterprise Information Portal - A Primer
 • MSInput: In the servlet MSInput, the input page is generated. If the user
   has selected the index class to be searched, the attributes in the selected
   index class are retrieved from the Content Manager server and be
   displayed in the page.
 • MSList: In the servlet MSList, the query is generated and executed to get
   the result list. This servlet checks the input to find out whether the query is
   parametric, text, or combined, and generates the query object by it. After
   creating the query object, it is executed to get a result list.
   It also generates links to the next pages, which are different by the query
   type.
 • MSContent: In the servlet MSContent, the document which is found as a
   result of executing query and all its parts, is retrieved from the Content
   Manager server and stored in the temporary internet directory, so that it
   can be shown on the client’s Web browser. It also calls the servlet to show
   the metadata of this document.
 • MSMeta: In the servlet MSMeta, all the meta data of the given document
   is shown on the client’s Web browser.
 • MSText: In the servlet MSText, the text part which was used to make the
   text index is retrieved from the Content Manager server and shown on the
   client’s Web browser.

The flow of these servlets is shown in Figure 51.


                         MSInput



                         MSList

 parametric search                     text search
 combined search

          MSContent                   MSText



          MSMeta

Figure 51. The flows among the Java servlets




                             Chapter 4. Java client for Content Manager using WebSphere   77
4.3.3 Condition/Input - MSInput
                 MSInput servlet is a program which generates the input page for this
                 application. It connects to the Content Manager server and shows all the
                 index classes currently in the Content Manager server. It also finds out what
                 attributes are in a particular index class if an index class has been selected.
                 For a text search, it connects to and accesses the text server and gets the
                 names of all the existing text indexes.

                 In the page generated by this servlet, you can enter the condition to search in
                 the Content Manager server.

                 4.3.3.1 Main Logic of this program (MSInput)
                 1. Connect to the Content Manager server and text server.
                 2. Find out all the index classes which are created in the Content Manager
                    server, and show them on the screen.
                 3. If the call for this servlet has a parameter indicating an index class, find out
                    all the attributes the index class has and show them on the screen.
                 4. Find out all the text index which are created in the text server and show
                    them on the screen.
                 5. Make spaces for the users to enter their condition.

                 4.3.3.2 Used classes and methods (MSInput)
                 Servlet input and output
                 The main routine of a servlet is to be placed in the method named service,
                 which has two parameters, HttpServletRequest and HttpServletResponse.
                 Through the HttpServletRequest object you can get the parameters that have
                 been used to call this servlet, and you can generate your output to the client’s
                 web browser through the HttpServletResponse object.

                 The typical code to get a parameter named from the HttpServletRequest
                 object is:
                 values =req.getParameterValues("indexClass");
                 if (values != null && values[0] != null && (values[0].length() != 0)){
                    indexClass = values[0];
                 }else {
                    indexClass =null;
                 }

                 Where req is an object of which type is HttpServletRequest.




78   IBM Enterprise Information Portal - A Primer
To generate an output line to the client’s Web browser, you should first
generate an ServletOutputStream object with the given HttpServletResponse
object. The example code is:
res.setContentType("text/html");
ServletOutputStream pw = res.getOutputStream();

To send a string to the client’s Web browser, you can use the
ServletOutputStream in the same way to output to the System.out. The
example code is:
pw.println("<HTML>");
pw.println("<!DOCTYPE HTML PUBLIC \"-//W3C/DTD HTML 3.2 Final//EN\">");

Connecting to the Content Manager server
There are classes in the Java package in the EIP toolkit that can be used to
access each Content Manager server. We used DKDatastoreDL class to
connect to our Content Manager server. After creating an object typed
DKDatastoreDL, you can connect to the Content Manager server with
parameters indicating the library server’s name, a user name, and the
password for the user. The example code is:
DKDatastoreDL dsDL = new DKDatastoreDL();
dsDL.connect(libsrv, userid, passwd, "");

Where libsrv is a String object which has the name of the library server to
access, userid is a String object indicating the name of user, and passwd is a
String object indicating the user’s password.

Listing all the existing index classes in a Content Manager server
By calling the method listEntities() from the DKDatastoreDL object, you can
get the list of all existing index classes. This method returns a sequential
collection, so you can create an iterator from this collection and get each
definition to a DKIndexClassDefDL object. The example code is:
DKSequentialCollection pCol = null;
dkIterator pIter = null;
DKIndexClassDefDL icDef = null;

pCol = (DKSequentialCollection) dsDL.listEntities();
pIter = pCol.createIterator();
while (pIter.more()) {
   icDef = (DKIndexClassDefDL) pIter.next();
   ... do something ...
}




                         Chapter 4. Java client for Content Manager using WebSphere   79
                 Listing all the attributes of a particular index class
                 By calling the method listEntityAttrs() of DKDatastoreDL object with a
                 parameter indicating the name of an index class, you can get the list of the
                 attributes of the index class. The result is a sequential collection and by
                 creating a iterator you can access each attribute to a DKAttrDefDL object.
                 The example code is:
                 pCol = (DKSequentialCollection) dsDL.listEntityAttrs( indexClass );
                 pIter = pCol.createIterator();
                 DKAttrDefDL attrDef = null;

                 while ( pIter.more() ) {
                    attrDef = (DKAttrDefDL) pIter.next();
                    ... do something ...
                 }

                 Connecting to the text server
                 Connecting to the text server is very similar to connecting to the Content
                 Manager server described earlier. First you make an object of
                 DKDatastoreTS class, which is an object for a text search server, and call a
                 method connect() to connect to the text server. The example code is:
                 DKDatastoreTS dsTS = new DKDatastoreTS();
                 dsTS.connect(srchSrv, "",' ');

                 Where srchSrv is a String object indicating the name of a text server.

                 Listing all the existing text indexes
                 Listing all the existing text indexes is very similar to listing all the existing
                 index classes in a Content Manager server. The only difference is that to list
                 all the existing text indexes you must call the method listEntities() from a
                 DKDatastoreTS object, not DKDatastoreDL object.
                 pCol = (DKSequentialCollection) dsTS.listEntities();
                 pIter = pCol.createIterator();

                 while (pIter.more()) {
                    pIndx = (DKSearchIndexDefTS) pIter.next();
                    ... do something ...
                 }

                 Disconnecting from the servers
                 To disconnect from any server, you can use the method disconnect() of the
                 datastore object you used. The example code is:
                 dsDL.disconnect();
                 dsTS.disconnect();




80   IBM Enterprise Information Portal - A Primer
Where dsDL is a DKDatastoreDL object, and dsTS is a DKDatastoreTS object.

4.3.3.3 Source code (MSInput)
The following is the complete source code of MSInput.java.

import com.ibm.mm.sdk.common.*;
import com.ibm.mm.sdk.server.*;

import   javax.servlet.*;
import   javax.servlet.http.*;
import   java.io.*;
import   java.util.*;
import   java.text.*;
import   java.net.*;

/*
 * MSInput class
 * - servlet for the input page of multi-type search
 * - extends HttpServlet
 * - implements DKConstantDL
*/
public class MSInput extends HttpServlet implements DKConstantDL
{
  // set max class size as needed for your application
  public final int MAX_CLASS_SIZE = 2;

  // set ResourceBundle name
 public final String BASENAME = "samples";
 static ResourceBundle rb = null;

 // connection information for content server and text server
 private String libsrv = "libsrvrn";
 private String srchSrv = "TM";
 private String userid = "frnadmin";
 private String passwd = "password";

 // initialization
 public void init(ServletConfig config) throws ServletException
 {
   super.init(config);
   /* get the ResourceBundle for localization */
   try{
     rb = ResourceBundle.getBundle(BASENAME);
   }
   catch(Throwable e) {
     e.printStackTrace();
   }
 }

/**
    * @param req Class instance of HttpServletRequest.
    * @param res Class instance of HttpServletResponse.
    * @exception IOException When opening, reading from,
    * or writing to the registration file.
    */
 public void service(HttpServletRequest req, HttpServletResponse res)
      throws IOException {
   String indexClass = null;

      res.setContentType("text/html");
      ServletOutputStream pw = res.getOutputStream();



                                 Chapter 4. Java client for Content Manager using WebSphere   81
                     try {
                         // get query string name-value pairs
                         // into a String array for easy access
                         String[] values;

                         // get parameter for indexClass
                         values =req.getParameterValues("indexClass");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           indexClass = values[0];
                         }else {
                           indexClass =null;
                         }

                         try {
                            DKDatastoreDL dsDL = new DKDatastoreDL();
                 //****** connect to the libsrv
                            dsDL.connect(libsrv, userid, passwd, "");
                 //****** processing
                            // print header
                            pw.println("<HTML>");
                            pw.println("<!DOCTYPE HTML PUBLIC \"-//W3C/DTD HTML 3.2 Final//EN\">");
                            pw.println("<head>");
                            pw.println("<title>IBM Digital Library Internet Connection</title>");
                            pw.println("<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html;
                 charset=iso-8859-1\">");
                            pw.println("<SCRIPT language=\"JavaScript\">");
                            pw.println("function getAttrFunc()");
                            pw.println("{");
                            pw.println("if ( document.srchForm.indexClass.selectedIndex > 0) {");
                            pw.println("document.getAttr.indexClass.value =
                 document.srchForm.indexClass[document.srchForm.indexClass.selectedIndex].value;");
                            pw.println("document.getAttr.submit();");
                            pw.println("}");
                            pw.println("else {");
                            pw.println("alert('Select an Index Class First!');");
                            pw.println("}");
                            pw.println("}");
                            pw.println("</SCRIPT>");
                            pw.println("</head>");

                            pw.println("<BODY bgcolor=\"#CCCCCC\">");
                            pw.println("<BASEFONT SIZE=\"4\">");
                            pw.println("<FORM NAME=\"getAttr\" METHOD=POST ACTION=\"/servlet/MSInput\">");
                            pw.println("<INPUT TYPE=\"hidden\" NAME=\"indexClass\">");
                            pw.println("</FORM>");
                            pw.println("<FORM NAME=\"srchForm\" METHOD=POST ACTION=\"/servlet/MSList\">");
                            pw.println("<CENTER>");
                            pw.println("<!Header>");
                            pw.println("<h2> Multi-Search using Java servlet </h2>");
                            pw.println("</CENTER>");
                            pw.println("<br>");
                            pw.println("<TABLE border=1 width=\"100%\" cellpadding=2 cellspacing=0>");
                            pw.println("   <TR align=center>");
                            pw.println("      <TD nowrap colspan=5> <strong>Parametric Search Condition
                 </strong></TD>");
                            pw.println("   </TR>");
                            pw.println("   <TR align=center valign=top>");
                            pw.println("   <TD nowrap rowspan=3> <strong>Index Class</strong>");
                            pw.println("<br>");
                            pw.println("   <SELECT NAME=\"indexClass\" SIZE=5>");
                            pw.println("   <OPTION value=\"\">");

                             DKSequentialCollection pCol = null;




82   IBM Enterprise Information Portal - A Primer
          dkIterator pIter = null;
          DKIndexClassDefDL icDef = null;
          String strIndexClass = null;

           // ***** parametric search criteria
           // list index classes
           pCol = (DKSequentialCollection) dsDL.listEntities();
           pIter = pCol.createIterator();
           while (pIter.more()) {
              icDef = (DKIndexClassDefDL) pIter.next();
              strIndexClass = icDef.getName();
              if ( strIndexClass.startsWith("FRN$") == false ) {
                 if ( (indexClass != null) && (indexClass.equals(strIndexClass)) )
                    pw.println("   <OPTION value=\""+strIndexClass+"\" SELECTED>"
+strIndexClass + "</OPTION>");
                 else
                    pw.println("   <OPTION value=\""+strIndexClass+"\">"+strIndexClass
+"</OPTION>");
              }
           }
           pw.println("   </SELECT><br><br>");
           pw.println("   <INPUT TYPE=\"button\" name=\"getAttrBtn\" value=\"Get
Attributes\" " +"onClick=\"javascript:getAttrFunc()\">");
           pw.println("   </TD>");

          // lists of attributes in given index class
          for (short i = 1; i <= 3; i++) {
             pw.println("   <TD align=center nowrap> <strong>Attribute</strong>");
             pw.println("   <br>");
             pw.println("<SELECT NAME=\"attrName"+i+"\" SIZE=1 >");
             pw.println("<OPTION value=>");

             // get the attributes lists
             if ( indexClass != null ) {
                pCol = (DKSequentialCollection) dsDL.listEntityAttrs( indexClass );
                pIter = pCol.createIterator();

                 DKAttrDefDL attrDef = null;
                 String attrName = null;
                 while ( pIter.more() ) {
                    attrDef = (DKAttrDefDL) pIter.next();
                    attrName = attrDef.getName();
                    pw.println("<OPTION value=\""+attrName+"\">"+attrName+"</OPTION>");
                 }
             }

             pw.println("</SELECT>");
             pw.println("</TD>");
             pw.println("<TD align=center nowrap> <strong>Operator</strong>");
             pw.println("<br>");
             // list of operators
             pw.println("<SELECT NAME=\"attrOp"+i+"\" SIZE=1 >");
             pw.println("<OPTION SELECTED value=\"\"> ");
             pw.println("<OPTION value=\" == \"> &#61 ");
             pw.println("<OPTION value=\" > \"> &#62 ");
             pw.println("<OPTION value=\" < \"> &#60 ");
             pw.println("<OPTION value=\" <> \"> &#60&#62 ");
             pw.println("<OPTION value=\" >= \"> &#62&#61 ");
             pw.println("<OPTION value=\" <= \"> &#60&#61");
             pw.println("</SELECT>");
             pw.println("</TD>");
             pw.println("<TD align=center nowrap> <strong>Value</strong>");
             pw.println("<br>");




                            Chapter 4. Java client for Content Manager using WebSphere   83
                               // searching value
                               pw.println("<INPUT NAME=\"attrVal"+i+"\" TYPE=\"text\" VALUE=\"\"
                 SIZE=\"12\">");
                               pw.println("</TD>");
                               pw.println("<TD align=center nowrap> <strong>Logical</strong>");
                               pw.println("<br>");
                               pw.println("<SELECT NAME=\"attrCond"+i+"\" SIZE=1>");
                               pw.println("<OPTION SELECTED value=\"\"> ");
                               if (i != 3) {
                                  pw.println("<OPTION value=\" AND \"> AND");
                                  pw.println("<OPTION value=\" OR \"> OR");
                               }
                               pw.println("</SELECT>");
                               pw.println("</TD>");
                               pw.println("</TR>");
                            }

                             // thumbnail, filter, maximum result information
                             pw.println("<TR>");
                             pw.println("<TD colspan=2>&nbsp;</TD>");
                             pw.println("<TD align=center nowrap> <strong>Thumbnail ID</strong>");
                               pw.println("<br>");
                               pw.println("<SELECT NAME=\"thumbId\" SIZE=1>");
                               pw.println("<OPTION SELECTED> ");
                               pw.println("<OPTION > 1");
                               pw.println("<OPTION > 2 ");
                               pw.println("<OPTION > 3 ");
                               pw.println("<OPTION > 4 ");
                               pw.println("<OPTION > 5 ");
                               pw.println("</SELECT>");
                             pw.println("</TD>");
                             pw.println("<TD align=center nowrap> <strong>Filter</strong>");
                               pw.println("<br>");
                               pw.println("<SELECT NAME=\"typeFilter\" SIZE=1>");
                               pw.println("<OPTION SELECTED> ");
                               pw.println("<OPTION value=\"DOC\"> Document ");
                               pw.println("<OPTION value=\"FOLDER\"> Folder ");
                               pw.println("<OPTION value=\"FOLDERDOC\"> FolderDocument");
                               pw.println("</SELECT>");
                             pw.println("</TD>");
                             pw.println("<TD align=center nowrap> <strong>Maximum Return</strong>");
                               pw.println("<br>");
                               pw.println("<SELECT NAME=\"maxRes\" SIZE=1>");
                               pw.println("<OPTION SELECTED> 1 ");
                               pw.println("<OPTION> 5 ");
                               pw.println("<OPTION> 10 ");
                               pw.println("<OPTION> 20 ");
                               pw.println("<OPTION> 60 ");
                               pw.println("<OPTION> 70 ");
                               pw.println("<OPTION> ");
                               pw.println("</SELECT>");
                             pw.println("</TD>");
                             pw.println("</TR>");
                             pw.println("</TABLE>");
                             pw.println("<br><br>");

                             //***** text search criteria
                             // connect to the text search server
                             DKDatastoreTS dsTS = new DKDatastoreTS();
                             DKSearchIndexDefTS pIndx = null;
                             String srchIndexName = null;
                             dsTS.connect(srchSrv, "",' ');




84   IBM Enterprise Information Portal - A Primer
           pw.println("<TABLE border=1 width=\"100%\" cellpadding=2 cellspacing=0>");
           pw.println("<TR align=center>");
           pw.println("<TD nowrap colspan=4> <strong>Text Search
Condition</strong></TD>");
           pw.println("</TR>");
           pw.println("<TR align=center valign=top>");
           pw.println("<TD nowrap> <strong>Search Index</strong>");
           pw.println("<SELECT NAME=\"textIndex\" SIZE=\"1\" WIDTH=\"20\" >");
           pw.println("   <OPTION value=\"\"></OPTION>");

           // text index names
           pCol = (DKSequentialCollection) dsTS.listEntities();
           pIter = pCol.createIterator();
           while (pIter.more()) {
              pIndx = (DKSearchIndexDefTS) pIter.next();
              srchIndexName = pIndx.getName();
              pw.println("   <OPTION value=\""+srchIndexName+"\">"+srchIndexName
+"</OPTION>");
           }
           pw.println("</SELECT>");
           pw.println("</TD>");

           /*
           pw.println("<TD nowrap rowspan=1> <strong>Map to DL Index Class</strong>");
           pw.println("<SELECT NAME=\"tmIndexClass\" SIZE=1>");
           pw.println("<OPTION value=\"\">");
           // list index classes
           pCol = (DKSequentialCollection) dsDL.listEntities();
           pIter = pCol.createIterator();
           while (pIter.more()) {
              icDef = (DKIndexClassDefDL) pIter.next();
              strIndexClass = icDef.getName();
              if ( strIndexClass.startsWith("FRN$") == false ) {
                 if ( (indexClass != null) && (indexClass.equals(strIndexClass)) )
                    pw.println("   <OPTION value=\""+strIndexClass+"\" SELECTED>"
+strIndexClass +"</OPTION>");
                 else
                    pw.println("   <OPTION value=\""+strIndexClass+"\">"+strIndexClass
+"</OPTION>");
              }
           }
           pw.println("</SELECT>");
           pw.println("</TD>");
           */
           pw.println("<TD align=center rowspan=3><A NAME=\"#TextAnchor\">");
           pw.println("<strong>Text to be searched, can be <br>");
           pw.println("WORD, PHRASE, or SENTENCE</strong><br>");
           pw.println("<TEXTAREA align=center NAME=\"TMQ\" ROWS=2 COLS=30></TEXTAREA>");
           pw.println("</TD>");

           // attributes to be used in text search
           pw.println("<TD align=center> ");
           pw.println("<INPUT TYPE=\"checkbox\" NAME=\"notMatch\"> <strong>NOT Match
</strong>");
           pw.println("</TD>");
           pw.println("</TR>");
           pw.println("<TR align=center valign=top>");
           pw.println("<TD nowrap> <strong>Time Limit</strong>");
          pw.println("<INPUT NAME=\"timeLimit\" TYPE=\"text\" VALUE=\"\" SIZE=\"12\">");
           pw.println("</TD>");
           pw.println("<TD nowrap> <strong>Maximum Return</strong>");
           pw.println("<SELECT NAME=\"tmMaxResult\" SIZE=1>");
           pw.println("<OPTION SELECTED> 1 ");




                            Chapter 4. Java client for Content Manager using WebSphere   85
                             pw.println("<OPTION> 5 ");
                             pw.println("<OPTION> 10 ");
                             pw.println("<OPTION> 20 ");
                             pw.println("<OPTION> 60 ");
                             pw.println("<OPTION> 70 ");
                             pw.println("<OPTION> ");
                             pw.println("</SELECT>");
                             pw.println("</TD>");
                             pw.println("</TR>");
                             pw.println("</TABLE>");

                              // buttons
                              pw.println("<br>");
                              pw.println("<TABLE cellpadding=10>");
                              pw.println("<TR>");
                              pw.println("<TD>");
                             pw.println("<INPUT TYPE=\"submit\" NAME=\"startQry\" VALUE=\" Start Search \">
                 ");
                             pw.println("</TD>");
                             pw.println("<TD><INPUT TYPE=\"button\" NAME=\"clearAll\" VALUE=\"Clear\" "
                                        +"onClick=\"javascript:location.href='/servlet/MSInput'\"></TD>");
                             pw.println("</TR>");
                             pw.println("</TABLE>");
                             pw.println("</FORM>");
                             pw.println("<hr noshape>");

                             pw.println("</body>");
                             pw.println("</html>");

                 //****** disconnect from the libsrv
                            dsTS.disconnect();
                            dsDL.disconnect();
                         }
                         catch (Exception exc) {
                            pw.print("Exception Message " + exc.getMessage() + "<br>");
                            exc.printStackTrace();
                            pw.flush();
                         }
                         pw.flush();

                         }
                       catch(Throwable e)
                         {
                           e.printStackTrace();
                           pw.flush();
                         }

                   } // end of doPost()

                 } // end of class MSInput


4.3.4 Servlet for listing the query result — MSList
                 The MSList servlet is where the actual query is executed. The value entered
                 by the user determines which type of query should be executed, and make a
                 query object to run the query. After executing the query, it shows the result on
                 the screen with a link to other servlet like MSContent or MSText to display the
                 content of the retrieved documents.




86   IBM Enterprise Information Portal - A Primer
4.3.4.1 Main logic of this program (MSList)
1. Get parameters to find out which type of query it should run.
   If at least one of the attribute values were entered, it is a parametric
   search.
   If there is a string entered as the searchable words, it is a text search.
   If both of the values are entered, it is a combined search.
2. Connect to the appropriate servers.
   If it is a parametric search, connect to the Content Manager server.
   If it is a text search, connect to the text server.
   If it is a combined search, connect to both of the servers.
3. Make the query strings using the input by the user.
4. Run the query to get the result set.
5. Show the result on the screen.

4.3.4.2 Used classes and methods (MSList)
Connecting to the Content Manager server and the text server is as described
in the previous section. See 4.3.3.2, “Used classes and methods (MSInput)”
on page 78.

Creating and running a parametric search object
To create a parametric search, a search string should be generated first. A
typical search string for a parametric search is:
String cmd = “SEARCH=(INDEX_CLASS=DLSAMPLE,MAX_RESULTS=5,”;
cmd +=
“COND=(DLSAMPLE_Date=’1996’));OPTION=(CONTENT=YES;TYPE_QUERY=DYNAMIC";)”

In MSList.java, we get the values from the parameter passed, so it is
necessary to parse the parameter to find out the proper query string for the
input.

For further information about the parametric search string, refer to the OO
and Internet Application Programming Reference, SC26-9837.

Once you make this search string, you can create an object for a parametric
search. DKParametricQuery is the class for doing a parametric search. To
create a parametric query object, createQuery() method of DKDatastoreDL
can be used. The example code is:
   DKParametricQuery pq = null;




                          Chapter 4. Java client for Content Manager using WebSphere   87
                     pq = (DKParametricQuery) dsDL.createQuery(pcmd, DK_PARAMETRIC_QL_TYPE,
                     parms);

                 Where dsDL is a DKDatastoreDL object, whose connect() method has been
                 executed before calling this method.

                 After you create this query object, you can run the query. In our program, we
                 used execute() method of a DKParametricQuery object. The example code to
                 is:
                 pq.execute(parms);

                 After your query has executed, you get the result set from it by calling the
                 method result() of the query object.
                 DKResults rs = (DKResults) pq.result();

                 DKResult class is a collection class, so you can create an iterator to see the
                 information about the document found by the query.
                 dkIterator pIter = rs.createIterator();
                 while (pIter.more()) {
                    item = (DKDDO) pIter.next();
                    ...do something..
                 }

                 Creating and running a text search object
                 To create a text search, a search string should be generated first. A typical
                 search string for a text search is:
                 String tcmd = "SEARCH=(COND=(‘UNIX’));OPTION=(SEARCH_INDEX=TMINDEX;MAX_RESULTS=5);”

                 In MSList.java, we get the values from the parameter passed, so it is
                 necessary to parse the parameter to find the proper query string for the input.
                 We parsed the search words to find out if there is character like & or |, which
                 indicate logical AND and logical OR, repectively. Also we parsed the string to
                 convert the search condition to see if there is an input condition for NOT.

                 For further information about the text search string, refer to the OO and
                 Internet Application Programming Reference , SC26-9837.

                 Once you make this search string, you can create an object for a text search.
                 DKTextQuery is the class for performing a text search. To create a text query
                 object, createQuery() method of DKDatastoreTS can be used. The example
                 code is:
                 DKTextQuery tq=null;
                 tq = (DKTextQuery) dsTS.createQuery(tcmd, DK_TEXT_QL_TYPE, parms);




88   IBM Enterprise Information Portal - A Primer
Where dsTS is a DKDatastoreTS object, whose connect() method has been
executed before calling this method.

After you create this query object, you can run the query. In our program, we
used execute() method of a DKTextQuery object. The example code is:
tq.execute(parms);

After your query is executed, you can get the result set from it by calling the
method result() of the query object.
DKResults rs = (DKResults) tq.result();

DKResult class is a collection class, so you can create an iterator to see the
information about the document found by the query.
dkIterator pIter = rs.createIterator();
while (pIter.more()) {
   item = (DKDDO) pIter.next();
   ...do something..
}

Where rs is a DKResult object.

Creating and running a combined search object
To create a combined search object, each search object to be combined
should be created first. Details to create a parametric search or a text search
were described earlier in this section.

Once you have created the search objects to combined, you can create a
combined search object. DKCombinedQueryDL is the class for doing a
combined search. The example code to create and run a combined query is:
DKCombinedQueryDL query = new DKCombinedQueryDL();
DKNVPair[] parms = new DKNVPair[3];
parms[0] = new DKNVPair(DK_PARM_QUERY, pq);
parms[1] = new DKNVPair(DK_TEXT_QUERY, tq);
parms[2] = new DKNVPair(DK_PARM_END, null);
query.execute(parms);

Where pq is a DKParametricQuery object and tq is a DKTextQuery object.
DK_PARM_END is used to indicate that there is no further query object to be
combined.

An array of DKNVPair is used to limit the result set. In the previous topics on
parametric search or text search, we did not use this feature. Using this
feature, we can limit the result of a query as the result of a query executed
earlier.


                         Chapter 4. Java client for Content Manager using WebSphere   89
                 After executing a combined query, the way to get the result set is the same as
                 the way already described for a parametric search or a text search. After the
                 query is executed, you can get the result set from it by calling the method
                 result() of the query object.
                 DKResults rs = (DKResults) tq.result();

                 DKResult class is a collection class, so you can create an iterator to see the
                 information about the document found by executing the query.
                 dkIterator pIter = rs.createIterator();
                 while (pIter.more()) {
                    item = (DKDDO) pIter.next();
                    ...do something..
                 }

                 Where rs is a DKResult object.

                 4.3.4.3 Source code (MSList)
                 The following is the complete source code of MSList.java.
                 import com.ibm.mm.sdk.common.*;
                 import com.ibm.mm.sdk.server.*;

                 import   javax.servlet.*;
                 import   javax.servlet.http.*;
                 import   java.io.*;
                 import   java.util.*;
                 import   java.text.*;
                 import   java.net.*;

                 /*
                  * MSList class
                  * - makes a query string with the inputs from MSInput servlet
                  *   and shows the result of executing the query
                  * - extends HttpServlet
                  * - implements DKConstantDL
                  */
                 public class MSList extends HttpServlet implements DKConstantDL
                 {
                   // set max class size as needed for your application
                   public final int MAX_CLASS_SIZE = 2;

                    // set ResourceBundle name
                   public final String BASENAME = "samples";
                   static ResourceBundle rb = null;

                   // connection informations
                   private String libsrv = "libsrvrn";
                   private String srchSrv = "TM";
                   private String userid = "frnadmin";
                   private String passwd = "password";

                   ServletOutputStream pw = null;

                   // initialization
                   public void init(ServletConfig config) throws ServletException




90   IBM Enterprise Information Portal - A Primer
 {
      super.init(config);
      /* get the ResourceBundle for localization */
      try{
        rb = ResourceBundle.getBundle(BASENAME);
      }
      catch(Throwable e) {
        e.printStackTrace();
      }
 }

/**
    * @param req Class instance of HttpServletRequest.
    * @param res Class instance of HttpServletResponse.
    * @exception IOException When opening, reading from,
    * or writing to the registration file.
    */
 public void service(HttpServletRequest req, HttpServletResponse res)
      throws IOException {

      // for parametric search
      String indexClass = null;
      String[] attrName = new String[3];
      String[] attrOp = new String[3];
      String[] attrVal = new String[3];
      String[] attrCond = new String[3];
      int thumbId = 0;
      String typeFilter = null;
      String maxRes = null;

      // for   text search
      String   textIndex = null;
      String   tmIndexClass = null;
      String   TMQ = null;
      String   notMatch = null;
      String   pMatch = null;
      String   freeText = null;
      String   timeLimit = null;
      String   tmMaxResult = null;

      // search types
      boolean pSearch = true; // parametric search is default
      boolean tSearch = false;

      res.setContentType("text/html");
      pw = res.getOutputStream();
      try {

          // get query string name-value pairs
          // into a String array for easy access
          String[] values;

          // get values for parametric search
          values =req.getParameterValues("indexClass");
          if (values != null && values[0] != null && (values[0].length() != 0)){
            indexClass = values[0];
          }else {
            indexClass =null;
          }

          for (short i = 0; i< 3; i++ ) {
             values =req.getParameterValues("attrName"+(i+1));
             if (values != null && values[0] != null && (values[0].length() != 0)){




                                Chapter 4. Java client for Content Manager using WebSphere   91
                               attrName[i] = values[0];
                             }else {
                               attrName[i] =null;
                             }

                             values =req.getParameterValues("attrOp"+(i+1));
                             if (values != null && values[0] != null && (values[0].length() != 0)){
                               attrOp[i] = values[0];
                             }else {
                               attrOp[i] =null;
                             }

                             values =req.getParameterValues("attrVal"+(i+1));
                             if (values != null && values[0] != null && (values[0].length() != 0)){
                               attrVal[i] = values[0];
                             }else {
                               attrVal[i] =null;
                             }

                             values =req.getParameterValues("attrCond"+(i+1));
                             if (values != null && values[0] != null && (values[0].length() != 0)){
                               attrCond[i] = values[0];
                             }else {
                               attrCond[i] =null;
                             }
                         }

                         values =req.getParameterValues("thumbId");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           thumbId = Integer.valueOf(values[0]).intValue();
                         }else {
                           thumbId = 0;
                         }

                         values =req.getParameterValues("typeFilter");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           typeFilter = values[0];
                         }else {
                           typeFilter = null;
                         }

                         values =req.getParameterValues("maxRes");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           maxRes = values[0];
                         }else {
                           maxRes = null;
                         }

                         // for text search
                         values =req.getParameterValues("textIndex");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           textIndex = values[0];
                         }else {
                           textIndex = null;
                         }

                         /*
                         values =req.getParameterValues("tmIndexClass");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           tmIndexClass = values[0];
                         }else {
                           tmIndexClass = null;
                         }




92   IBM Enterprise Information Portal - A Primer
        */

        values =req.getParameterValues("TMQ");
        if (values != null && values[0] != null && (values[0].length() != 0)){
          TMQ = values[0];
        }else {
          TMQ = null;
        }

        values =req.getParameterValues("notMatch");
        if (values != null && values[0] != null && (values[0].length() != 0)){
          notMatch = values[0];
        }else {
          notMatch = null;
        }

        values =req.getParameterValues("timeLimit");
        if (values != null && values[0] != null && (values[0].length() != 0)){
          timeLimit = values[0];
        }else {
          timeLimit = null;
        }

        values =req.getParameterValues("tmMaxResult");
        if (values != null && values[0] != null && (values[0].length() != 0)){
          tmMaxResult = values[0];
        }else {
          tmMaxResult = null;
        }

        // if there is input for text to be searched, text search will be executed
        if ( TMQ == null )
           tSearch = false;
        else
           tSearch = true;

       // if there is any input for attribute values, parametric search will be executed
       if ( (attrVal[0] != null) || (attrVal[1] != null) || (attrVal[2] != null) )
          pSearch = true;
       else
          pSearch = false;

        try {
//****** connect to the libsrv and the text server
           DKDatastoreDL dsDL = new DKDatastoreDL();
           DKDatastoreTS dsTS = new DKDatastoreTS();

           if ( pSearch )
              dsDL.connect(libsrv, userid, passwd, "");
           if ( tSearch )
              dsTS.connect(srchSrv, "", "",
"LIBACCESS=("+libsrv+","+userid+","+passwd+")");
//****** processing
           // header
           pw.println("<HTML>");
           pw.println("<!DOCTYPE HTML PUBLIC \"-//W3C/DTD HTML 3.2 Final//EN\">");
           pw.println("<head>");
           pw.println("<title>IBM Digital Library Internet Connection</title>");
           pw.println("<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html;
charset=iso-8859-1\">");
           pw.println("</head>");

             pw.println("<BODY bgcolor=\"#CCCCCC\">");




                              Chapter 4. Java client for Content Manager using WebSphere   93
                             pw.println("<BASEFONT SIZE=\"4\">");

                             //***** parametric search
                             String pcmd = null;
                             DKParametricQuery pq = null;
                             DKNVPair parms[] = null;

                             if ( pSearch ) {
                                // make a query string for parametric search
                                pcmd = "SEARCH=(INDEX_CLASS="+indexClass;
                                if ( maxRes != null )
                                   pcmd += ",MAX_RESULTS="+maxRes;
                                pcmd += ",COND=(";
                                for (short i = 0; i< 3; i++ ) {
                                   if ( attrVal[i] != null ) {
                                      if ( (i > 0) && (attrOp[i-1] != null) )
                                         pcmd += attrOp[i-1];
                                      else if ( i> 0 )
                                         pcmd += " AND ";
                                      pcmd += "("+attrName[i]+attrOp[i]+"'"+attrVal[i]+"'"+")";
                                   }
                                }
                                pcmd += "));";
                                pcmd += "OPTION=(CONTENT=YES;TYPE_QUERY=DYNAMIC";
                                if ( typeFilter != null )
                                   pcmd += ";TYPE_FILTER="+typeFilter;
                                pcmd += ")";

                                 // create a query object with the given query string
                                 //pw.println("<H3>Parametric Query : "+pcmd+"</H3>");
                                 pq = (DKParametricQuery) dsDL.createQuery(pcmd, DK_PARAMETRIC_QL_TYPE,
                 parms);
                             }

                             //***** text search
                             String tcmd = null;
                             DKTextQuery tq = null;

                            if ( tSearch ) {
                               // make a query string for text search
                               String newTMQ = new String("");
                               int prevIdx = 0;
                               // check if there is any '|' or '&'
                               for (int idx = TMQ.indexOf(" ", 0); idx >= 0; prevIdx=idx+1,
                 idx=TMQ.indexOf(" ", idx+1)) {
                                  String tmpStr = TMQ.substring(prevIdx, idx);
                                  if ( tmpStr.equals("&") || tmpStr.equals("|") )
                                     newTMQ += " "+tmpStr+" ";
                                  else
                                     newTMQ += "'"+tmpStr+"'";
                               }
                               newTMQ += "'"+TMQ.substring(prevIdx)+"'";

                                 tcmd = "SEARCH=(COND=(";
                                 if ( notMatch != null )
                                    newTMQ= convNot( newTMQ );
                                 tcmd += newTMQ+"));";
                                 tcmd += "OPTION=(SEARCH_INDEX="+textIndex;
                                 if ( tmMaxResult != null )
                                    tcmd += ";MAX_RESULTS="+tmMaxResult;
                                 if ( timeLimit != null )
                                    tcmd += ";TIME_LIMIT="+timeLimit;
                                 tcmd += ")";




94   IBM Enterprise Information Portal - A Primer
              // create a query object with the given query string
              //pw.println("<H3>Text Query : "+tcmd+"</H3>");
              tq = (DKTextQuery) dsTS.createQuery(tcmd, DK_TEXT_QL_TYPE, parms);
          }

          // parametric search only
          if ( (pSearch) && (!tSearch) ) {
             pw.println("<CENTER>");
             pw.println("<!Header>");
             pw.println("<h2> Search Result Sets </h2>");
             pw.println("</CENTER>");
             pw.println("<br>");

              // result using parametric query object
              getParmResult(pq, thumbId);
          }
          // text query only
          else if ( (!pSearch) && (tSearch) ) {
             pw.println("<CENTER>");
             pw.println("<!Header>");
             pw.println("<h2> Text Search Results </h2>");
             pw.println("</CENTER>");
             pw.println("<br>");

              // result using text query object
              getTextResult(tq);
          }
          // combined search
          else if ( (pSearch) && (tSearch) ) {
             pw.println("<CENTER>");
             pw.println("<!Header>");
             pw.println("<h2> Search Result Sets </h2>");
             pw.println("</CENTER>");
             pw.println("<br>");

              // result using combined query object
              getCombResult(pq, tq, thumbId);
          }
          // when there is no valid input for search
          else {
             pw.println("<CENTER>");
             pw.println("<H3>Your input was not valid. Please try again.</H3>");
             pw.println("</CENTER>");
             pw.println("<br>");
          }

          pw.println("</BODY>");
          pw.println("</HTML>");

//****** disconnect from the libsrv and the text server
           if ( tSearch )
              dsTS.disconnect();
           if ( pSearch )
              dsDL.disconnect();
        }
        catch (Exception exc) {
           pw.print("Exception Message " + exc.getMessage() + "<br>");
           exc.printStackTrace();
           pw.flush();
        }
        pw.flush();




                            Chapter 4. Java client for Content Manager using WebSphere   95
                       }
                     catch(Throwable e)
                       {
                         e.printStackTrace();
                         pw.flush();
                       }

                   } // end of doPost()

                   /*
                    * public void getParmResult(DKParametricQuery query, int thumbId)
                    * - execute the parametric query with the given query object
                    * - shows the result on the screen
                    * - Input TypeDescription
                    *   ----------------------------------------------------------------------
                    *   queryDKParametricQueryquery object to be executed
                    *   thumbIdintthe part number of the thumbnail
                    *                                    0 if there is no input for thumbnail
                    */
                   public void getParmResult(DKParametricQuery query, int thumbId)
                   {
                   try {
                      try {
                         DKNVPair[] parms = null;
                         DKDDO item= null;
                         // execute the query
                         query.execute(parms);
                         DKResults rs = (DKResults) query.result();
                         pw.println("<CENTER>");
                         pw.println("<table border=1 width=\"80%\">");
                         dkIterator pIter = rs.createIterator();
                         short ind = 0;
                         pw.println("<tr height=15 valign=center><td colspan=3 align=center><H4>Total
                 Number of Hits : "+rs.cardinality()+"</H4></td>");
                         while (pIter.more()) {
                            item = (DKDDO) pIter.next();

                             if ( item != null ) {
                                String pid = item.getPid().pidString();
                               // replace some characters that this pid string can be delivered through the
                 cgi calls
                                // --- that is, a blank and # cannot be delivered in the cgi calls
                                pid = pid.replace(' ','+');
                                pid = pid.replace('#','^');
                                String filename = pid.substring(pid.length() -16);

                               if ( ind % 3 == 0 )
                                  pw.println("</tr><tr>");
                                  pw.println("<td align=center><a
                 href=\"/servlet/MSContent?pid="+pid+"\">");
                                  //pw.println("thumbId : "+thumbId+"<br>");
                                  // shows the thumbnail
                                  if (thumbId != 0) {
                                     item.retrieve();
                                     // find the thumbnail part from the part collection
                                     DKParts pPart = (DKParts) item.getDataByName("DKParts");
                                     if ( pPart != null ) {
                                        DKBlobDL blob;
                                        dkIterator iter = pPart.createIterator();
                                        short tid = 1;
                                        while (iter.more()) {
                                           blob = (DKBlobDL) iter.next();
                                           if ((blob != null) && (tid == thumbId)) {




96   IBM Enterprise Information Portal - A Primer
                            blob.retrieve();
                            // we assume that the thumbnail is in gif format

blob.getContentToClientFile("C:\\InetPub\\WWWRoot\\RESMult\\temp\\"+pid+".gif", 1);
                             pw.println("<img border=\"0\"
src=\"/RESMult/temp/"+pid+".gif\"><br>");
                          }
                          tid++;
                       }
                    }
                 }
                 // print the subject attributes
                 pw.println(item.getDataByName("DLSEARCH_Subject")+"</a></td>");
                 ind ++;
              }
           }
           pw.println("</tr>");
           pw.println("</table></CENTER>");
      }
      catch (Exception exc) {
         pw.println("Exception Message " + exc.getMessage() + "<br>");
         exc.printStackTrace();
         pw.flush();
      }
    }
    catch(Throwable e)
      {
        e.printStackTrace();
        //pw.flush();
      }

  }

   /*
    * public void getTextResult(DKTextQuery query)
    * - executes the query for text search and shows the result on the screen
    * - InputTypeDescription
    *   -----------------------------------------------------------------------
    *   queryDKTextQuerythe query object to be executed
    */
   public void getTextResult(DKTextQuery query)
   {
   try{
     try {
        DKNVPair parms[] = null;
        DKDDO item= null;
        String pid= null;
        // execute the query
        query.execute(parms);
        DKResults rs = (DKResults) query.result();
        pw.println("<CENTER>");
        pw.println("<table border=1 width=\"80%\">");
        dkIterator pIter = rs.createIterator();
        short ind = 0;
        pw.println("<tr height=15 valign=center><td colspan=7 align=center><H4>Total
Number of Hits : "+rs.cardinality()+"</H4></td>");
        while (pIter.more()) {
           item = (DKDDO) pIter.next();

          if ( item != null ) {
             pw.println("</tr><tr>");
             // shows all the attributes resulted by the text query
             short na = item.dataCount();




                            Chapter 4. Java client for Content Manager using WebSphere   97
                                pw.println("<!-- dataCount " + na + " -->");
                                if ( ind == 0 ) {
                                   for (short j = 1; j <= na; j++)
                                      pw.println("<td align=center>"+item.getDataName(j) + "</td>");
                                   pw.println("<td>Content</td>");
                                   pw.println("</tr><tr>");
                                   ind++;
                                }
                                for (short k = 1; k <= na; k++) {
                                   pw.println("<td align=center>"+item.getData(k) + "</td>");
                                }
                                // get item id for DL objects and replace # to ^ to deliver it through cgi
                 call
                               pid = (String) item.getDataByName("DKDLItemId");
                               pid = pid.replace('#','^');
                               pw.println("<td><a href=\"/servlet/MSText?pid="+pid+"\">Content</a></td>");
                            }
                          }
                          pw.println("</tr>");
                          pw.println("</table></CENTER>");
                        }
                        catch (Exception exc) {
                           pw.println("Exception Message " + exc.getMessage() + "<br>");
                           exc.printStackTrace();
                           pw.flush();
                        }
                     }
                     catch(Throwable e)
                       {
                         e.printStackTrace();
                         //pw.flush();
                       }

                    }

                   /*
                    * public void getCombResult(DKParametricQuery pq, DKTextQuery tq, int thumbId)
                    * - makes the combined query string with the given two query string and executes it
                    *   to show the results on the screen
                    * - InputTypeDescription
                    *   -------------------------------------------------------------------------
                    *   pqDKParametricQuerythe parametric query object
                    *   tq DKTextQuerythe text query object
                    *   thumbIdintthe part number for the thumbnail
                    */
                   public void getCombResult(DKParametricQuery pq, DKTextQuery tq, int thumbId)
                   {
                   try {
                      try {
                         DKCombinedQueryDL query = new DKCombinedQueryDL();
                         DKNVPair[] parms = new DKNVPair[3];
                         parms[0] = new DKNVPair(DK_PARM_QUERY, pq);
                         parms[1] = new DKNVPair(DK_TEXT_QUERY, tq);
                         parms[2] = new DKNVPair(DK_PARM_END, null);
                         DKDDO item= null;
                         // execute the query
                         query.execute(parms);
                         DKResults rs = (DKResults) query.result();
                         pw.println("<CENTER>");
                         pw.println("<table border=1 width=\"80%\">");
                         dkIterator pIter = rs.createIterator();
                         short ind = 0;




98   IBM Enterprise Information Portal - A Primer
        pw.println("<tr height=15 valign=center><td colspan=3 align=center><H4>Total
Number of Hits : "+rs.cardinality()+"</H4></td>");
        while (pIter.more()) {
           item = (DKDDO) pIter.next();

          if ( item != null ) {
             String pid = item.getPid().pidString();
             String filename = pid.substring(pid.length() -16);
             pid = pid.replace(' ','+');
             pid = pid.replace('#','^');

             if ( ind % 3 == 0 )
                pw.println("</tr><tr>");
             pw.println("<td align=center>");
             pw.println("<a href=\"/servlet/MSContent?pid="+pid+"\">");
             // show the thumbnail object
             if (thumbId != 0) {
                item.retrieve();
                DKParts pPart = (DKParts) item.getDataByName("DKParts");
                if ( pPart != null ) {
                   DKBlobDL blob;
                   dkIterator iter = pPart.createIterator();
                   short tid = 1;
                   while (iter.more()) {
                      blob = (DKBlobDL) iter.next();
                      if ((blob != null) && (tid == thumbId)) {
                         blob.retrieve();

blob.getContentToClientFile("C:\\InetPub\\WWWRoot\\RESMult\\temp\\"+filename+".gif", 1);
                          pw.println("<img border=\"0\"
src=\"/RESMult/temp/"+filename+".gif\"><br>");
                       }
                       tid++;
                    }
                 }
              }
              pw.println("Rank : " + item.getDataByName("DKRank")+"<br>");
              pw.println(item.getDataByName("DLSEARCH_Subject")+"</a></td>");
              ind ++;
           }
        }
        pw.println("</tr>");
        pw.println("</table></CENTER>");
     }
     catch (Exception exc) {
        pw.println("Exception Message " + exc.getMessage() + "<br>");
        exc.printStackTrace();
        pw.flush();
     }
  }
  catch(Throwable e)
  {
     e.printStackTrace();
     //pw.flush();
  }

 }

 /*
  * private String convNot(String oldStr)
  * - convert the given string with NOT option
  * - InputTypeDescription
  *   -----------------------------------------------------




                            Chapter 4. Java client for Content Manager using WebSphere   99
                   *   oldStrStringstring to be converted
                   *
                   * - Return valueDescription
                   *   ------------------------------------------------------
                   *   Stringconverted string
                   */
                  private String convNot(String oldStr)
                  {
                     String newStr = new String(" NOT ");

                      for (short i = 0; i< oldStr.length(); i++) {
                         String sub = oldStr.substring(i, i+1);
                         if ( sub.equals("&") )
                            newStr += "| NOT ";
                         else if (sub.equals("|"))
                            newStr += "& NOT ";
                         else
                            newStr += sub;
                      }

                      return newStr;
                  }

                } // end of class MSList


4.3.5 Servlet for showing content of a document — MSContent
                The MSContent servlet is used to retrieve the part objects which are stored
                with a document and show them on the client’s Web browser. Because the
                part objects are a html file and image files used in the html file, the retrieved
                objects are easily displayed on a Web browser.

                It is called by MSList servlet when a parametric or combined search is used.
                All part objects are retrieved and stored in a temporary directory which can
                be accessed by the browser.

                4.3.5.1 Main logic of this program (MSContent)
                1. Retrieve the document using the item ID passed from MSList from the
                   Content Manager server.
                2. Retrieve the notepart from the part collection (of which there are two
                   parts) and find the original names of all the other parts.
                3. Retrieve all the parts except the notepart from the part collection and save
                   them in a temporary directory which can be accessed by the browser.
                4. Make one frame to show the retrieved files, and another frame to show the
                   metadata with a call to MSMeta servlet.




100   IBM Enterprise Information Portal - A Primer
4.3.5.2 Used classes and methods (MSContent)
Finding a document with PID
PID is a string identifing one document in the Content Manager server. It has
information about the index class, and includes the document and the key
value to differentiate the document from other documents.

In the servlet MSList , documents are found as the result of a query, and the
documents are represented as DKDDO objects. To get the PID from a
DKDDO object, the following code can be used:
String pid = ddo.getPid().pidString();

Where ddo is the DKDDO object of which pid is retrieved.

When you get the PID from this statement, there are several blank characters
and # characters that cannot be passed by CGI (common gateway interface)
calls, which is a common way to pass parameters between two Web
documents. So we substitute the blank character to ‘+’, which will be removed
after passing the parameter, and ‘#’ to ‘^’, which is not used to generate a PID
in the Content Manager server.

Once the PID is known, it is easy to find the document for the PID. First,
generate a DKPid object with the given PID, and a DKDDO object with the
generated DKPid object. By calling the retrieve() method of DKDDO object,
you can access the document. The example code is:
DKPid objPid = new DKPid(pid);
DKDDO ddo = new DKDDO(dsDL, objPid);
ddo.retrieve();

Where pid is a String object which has the PID value and dsDL is a
DKDatastoreDL object whose connect() method is already executed.

Retrieving parts from a document
After you retrieve the document, you can access the part objects; that is, the
objects which are stored related to the document. A part can be found with
two values: a PID for the document the part is included, and the part number
for it. So there can be only one part with the same part number in a
document.

All parts are retrieved as a sequential collection, using DKPart class. Finding
the DKPart object leads us to create an iterator for parts, which lets us access
every part object related in the object. The example code to retrieve parts is:
DKParts pCol = (DKParts) ddo.getDataByName("DKParts");
if (pCol != null) {
   DKBlobDL blob;


                        Chapter 4. Java client for Content Manager using WebSphere   101
                    dkIterator iter = pCol.createIterator();
                    int partId = 0;
                    while (iter.more()) {
                       blob = (DKBlobDL) iter.next();
                       if (blob != null) {
                          blob.retrieve();
                          ... do something ...
                       }
                    }
                }

                Where ddo is a DKDDO object which was retrieved earlier.

                Using Notepart
                In this application, a part whose part number is 2 has special meaning. It is
                not an actual part we loaded to the Content Manager server, but it is a file
                generated when the document was created and all the other parts were
                loaded.

                As we already mentioned, a part object is identified using the PID of the
                document it is included and the part number. So there is no way to find the
                original file name of a part object. But sometimes the original file name for a
                part should be known, as is the case in our application. In this application, the
                main part object is the html part, and in the html part the name of referencing
                image files are hard-coded, so we cannot change them. So when we want to
                save a retrieved part, we want to use their original names. That’s why we
                used the notepart object in this application.

                Notepart is a part which contains the original file names of all the other part
                objects. In our application, we put the part number 2 for the notepart object.
                An example of a notepart object is:
                tivoli.dat:1
                tivoli.htm:3
                tivoli.gif:4
                tivolit.gif:5
                tivoli.txt:10

                Every line indicates one part loaded, and it consists of two parts: the file
                name and the part number. So by accessing the notepart, we can find out the
                original names of each part object.

                4.3.5.3 Source code (MSContent)
                The following is the complete source code of MSContent.java.
                import com.ibm.mm.sdk.common.*;
                import com.ibm.mm.sdk.server.*;




102   IBM Enterprise Information Portal - A Primer
import   javax.servlet.*;
import   javax.servlet.http.*;
import   java.io.*;
import   java.util.*;
import   java.text.*;
import   java.net.*;

/*
 * MSContent class
 * - shows the content of the document found at the previous query in MSList
 * - retrieves all parts and save it in temporary directory
 * - calls another servlet to show the meta data for this document
 * - extends HttpServlet
 * - implements DKConstantDL
 */
public class MSContent extends HttpServlet implements DKConstantDL
{
  // set max class size as needed for your application
  public final int MAX_CLASS_SIZE = 2;

  // set ResourceBundle name
 public final String BASENAME = "samples";
 static ResourceBundle rb = null;

 // connection informations
 private String libsrv = "libsrvrn";
 private String srchSrv = "TM";
 private String userid = "frnadmin";
 private String passwd = "password";

 ServletOutputStream pw = null;

 // initialization
 public void init(ServletConfig config) throws ServletException
 {
   super.init(config);
   /* get the ResourceBundle for localization */
   try{
     rb = ResourceBundle.getBundle(BASENAME);
   }
   catch(Throwable e) {
     e.printStackTrace();
   }
 }

/**
    * @param req Class instance of HttpServletRequest.
    * @param res Class instance of HttpServletResponse.
    * @exception IOException When opening, reading from,
    * or writing to the registration file.
    */
 public void service(HttpServletRequest req, HttpServletResponse res)
      throws IOException {
   String pid = null;
   boolean found= false;

      res.setContentType("text/html");
      pw = res.getOutputStream();
      try {

          // get query string name-value pairs
          // into a String array for easy access




                            Chapter 4. Java client for Content Manager using WebSphere   103
                         String[] values;

                         // get values for pid to retrieve a document
                         values =req.getParameterValues("pid");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           pid = values[0];
                         }else {
                           pid =null;
                         }
                         // for we changed # to ^ to deliver this string through the cgi call,
                         // we should re-change ^ to # to get the original string
                         pid= pid.replace('^','#');

                        try {
                //****** connect to the libsrv
                           DKDatastoreDL dsDL = new DKDatastoreDL();

                           dsDL.connect(libsrv, userid, passwd, "");
                //****** processing
                           // headers
                           pw.println("<HTML>");
                           pw.println("<!DOCTYPE HTML PUBLIC \"-//W3C/DTD HTML 3.2 Final//EN\">");
                           pw.println("<head>");
                           pw.println("<title>IBM Digital Library Internet Connection</title>");
                           pw.println("<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html;
                charset=iso-8859-1\">");
                           pw.println("</head>");

                            // notepart file name
                            // notepart file is a file used to record the part number and original file
                           // name pairs. so if we want to find out the original file names of all parts,
                            // we should refer to the notepart.
                            String filename = null;
                            String np = new String("c:\\InetPub\\wwwroot\\RESMult\\Temp\\notepart.txt");

                            DKPid objPid = new DKPid(pid);
                            DKDDO ddo = new DKDDO(dsDL, objPid);
                            ddo.retrieve();

                            // finding notepart - notepart id is 2
                            short data_id = ddo.dataId("DKParts");
                            DKParts pCol = (DKParts) ddo.getData(data_id);
                            if (pCol != null) {
                               DKBlobDL blob;
                               dkIterator iter = pCol.createIterator();
                               while (iter.more()) {
                                  blob = (DKBlobDL) iter.next();
                                  if (blob != null) {
                                     // if it is notepart
                                     if ( blob.getPartId() == 2 ) {
                                        blob.retrieve();
                                        blob.getContentToClientFile(np,1);
                                     }
                                  }
                               }
                            }

                            // read the notepart into the memory and find each file name-part id pair
                            FileInputStream fis = new FileInputStream(np);
                            DataInputStream dis = new DataInputStream(fis);
                            String[] fNames = new String[100];
                            String buffer = null;
                            int tmpPart = 0;




104   IBM Enterprise Information Portal - A Primer
          while (dis.available() > 0) {
             buffer = dis.readLine();
             int idx = buffer.indexOf(":");
             tmpPart = Integer.valueOf(buffer.substring(idx+1)).intValue();
             fNames[tmpPart] = new String(buffer.substring(0, idx));
          }
          dis.close();
          fis.close();

           // retrieve all parts except notepart(we already have it) and
           // save the files in the temporary directory
           DKParts pCol2 = (DKParts) ddo.getData(data_id);
           if (pCol2 != null) {
              DKBlobDL blob2;
              dkIterator iter2 = pCol2.createIterator();
              int partId = 0;
              while (iter2.more()) {
                 blob2 = (DKBlobDL) iter2.next();
                 if (blob2 != null) {
                    blob2.retrieve();
                    partId = blob2.getPartId();
                    if (partId != 2) {// if it is not an notepart
                       //pw.println("part number is = "+partId+"<br>");
                       //pw.println("file name is = "+fNames[partId]+"<br>");
                       blob2.getContentToClientFile(
"C:\\InetPub\\WWWRoot\\RESMult\\Temp\\"+fNames[partId], 1);
                    }
                    // part id 3 is html file - it is to be shown on the screen
                    if ( partId == 3)
                       found = true;
                 }
              }
           }
           if (found)
              filename= fNames[3];

          pw.println("<FRAMESET ROWS=\"*\" COLS=\"30%,*\" BORDER=\"1\">");
          // replace the invalid characters again to pass to another servlet
          pid = pid.replace(' ','+');
          pid= pid.replace('#','^');
          pw.println("<FRAME NAME=\"INFO\" src=\"/servlet/MSMeta?pid="+ pid +"\">");
          pw.println("<FRAME NAME=\"HTML_CON\" src=\"/RESMult/temp/"+ filename +"\">");
          pw.println("</FRAMESET>");
          pw.println("</HTML>");

//****** disconnect from the libsrv
           dsDL.disconnect();
        }
        catch (Exception exc) {
           pw.print("Exception Message " + exc.getMessage() + "<br>");
           exc.printStackTrace();
           pw.flush();
        }
        pw.flush();

      }
    catch(Throwable e)
      {
        e.printStackTrace();
        pw.flush();
      }




                          Chapter 4. Java client for Content Manager using WebSphere   105
                  } // end of doPost()

                } // end of class MSContent


4.3.6 Servlet for showing metadata of a document — MSMeta
                The MSMeta servlet shows all the attributes and their value which are stored
                as a document and displays them in the client’s Web browser. So first, you
                need to find the document by the given PID and list all the attributes and their
                values.

                This servlet is called by MSContent servlet where the part objects for the
                document are retrieved and shown.

                4.3.6.1 Main logic of this program (MSMeta)
                1. Retrieve the document using the item ID passed from MSContent to the
                   Content Manager server.
                2. Find all the attributes assigned to this document and show them on the
                   screen.

                4.3.6.2 Used classes and methods (MSMeta)
                Finding a document with a PID

                The way to find a document using the given PID was covered in the previous
                section.

                Listing all the attributes of a document
                To list all the attributes of a document, you need to find how many attributes
                the document has. Method dataCount() in class DKDDO returns the number
                of attributes in the document object.

                All the attributes have an ID whose type is short. It is called a data ID, and
                every attribute in a document is identified by this data ID. Data ID for an
                attributes is assigned when a index class is created, so all attributes of the
                same name have the same data ID in an index class.

                The fact that all attributes are identified by the data ID means that you can get
                the name and value of an attribute using the data ID. A data ID is
                automatically assigned as a short number, starting from 1 and increased by 1.
                So you can access all the attributes if you know the number of all attributes.

                After getting the number of all the attributes, all you have to do is make a loop
                executing getDataName() method to find out the name of the attribute with
                the given data ID, and getData() method to find out the value of the attribute.
                The example code is:



106   IBM Enterprise Information Portal - A Primer
short na = ddo.dataCount();
for (short i = 1; i<= na; i++ ) {
   Object obj = ddo.getDataName(i);
  System.out.println("Attribute Name : "+ obj.toString() + "\tValue : "+ddo.getData(i));
}

Where ddo is a DKDDO object which is already retrieved.

4.3.6.3 Source Code (MSMeta)
The following is the complete source code of MSMeta.java.
import com.ibm.mm.sdk.common.*;
import com.ibm.mm.sdk.server.*;

import   javax.servlet.*;
import   javax.servlet.http.*;
import   java.io.*;
import   java.util.*;
import   java.text.*;
import   java.net.*;

/*
 * MSMeta class
 * - shows meta datas for the given document
 * - extends HttpServlet
 * - implements DKConstantDL
 */
public class MSMeta extends HttpServlet implements DKConstantDL
{
  // set max class size as needed for your application
  public final int MAX_CLASS_SIZE = 2;

   // set ResourceBundle name
  public final String BASENAME = "samples";
  static ResourceBundle rb = null;

  // connecting information
  private String libsrv = "libsrvrn";
  private String srchSrv = "TM";
  private String userid = "frnadmin";
  private String passwd = "password";

  ServletOutputStream pw = null;

  // initialization
  public void init(ServletConfig config) throws ServletException
  {
    super.init(config);
    /* get the ResourceBundle for localization */
    try{
      rb = ResourceBundle.getBundle(BASENAME);
    }
    catch(Throwable e) {
      e.printStackTrace();
    }
  }

  /**
     *   @param req   Class instance of HttpServletRequest.
     *   @param res   Class instance of HttpServletResponse.
     *   @exception   IOException When opening, reading from,
     *   or writing   to the registration file.



                              Chapter 4. Java client for Content Manager using WebSphere   107
                     */
                  public void service(HttpServletRequest req, HttpServletResponse res)
                       throws IOException {
                    String pid = null;
                    boolean found= false;

                     res.setContentType("text/html");
                     pw = res.getOutputStream();
                     try {

                         // get query string name-value pairs
                         // into a String array for easy access
                         String[] values;

                         // get values for pid to retrieve a document
                         values =req.getParameterValues("pid");
                         if (values != null && values[0] != null && (values[0].length() != 0)){
                           pid = values[0];
                         }else {
                           pid =null;
                         }
                         // replace ^ to #, for we changed # to ^ to deliver it through cgi call
                         pid = pid.replace('^','#');

                        try {
                //****** connect to the libsrv
                           DKDatastoreDL dsDL = new DKDatastoreDL();
                           dsDL.connect(libsrv, userid, passwd, "");
                //****** processing
                           // header
                           pw.println("<HTML>");
                           pw.println("<!DOCTYPE HTML PUBLIC \"-//W3C/DTD HTML 3.2 Final//EN\">");
                           pw.println("<head>");
                           pw.println("<title>IBM Digital Library Internet Connection</title>");
                           pw.println("<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html;
                charset=iso-8859-1\">");
                           pw.println("</head>");

                             // retrieve the document
                             DKPid objPid = new DKPid(pid);
                             DKDDO ddo = new DKDDO(dsDL, objPid);
                             ddo.retrieve();

                             pw.println("<BODY bgcolor=\"#FFFFFF\">");
                             pw.println("<CENTER>");
                             pw.println("<H3>Meta Data</H3>");
                             pw.println("<table border=\"1\">");

                             // shows all attributes' name and value
                             short na = ddo.dataCount();
                             for (short i = 1; i<= na; i++ ) {
                                Object obj = ddo.getDataName(i);
                                if ( (obj.toString()).indexOf("DKParts") < 0) {
                                   pw.println("<tr><td align=center bgcolor=\"#CCCCCC\">"+ obj.toString()
                +"</td>");
                                     pw.println("<td align=center>"+ddo.getData(i)+"</td></tr>");
                                 }
                             }

                             pw.println("</table>");

                             pw.println("</CENTER>");
                             pw.println("</BODY>");




108   IBM Enterprise Information Portal - A Primer
                      pw.println("</HTML>");

            //****** disconnect from the libsrv
                       dsDL.disconnect();
                    }
                    catch (Exception exc) {
                       pw.print("Exception Message " + exc.getMessage() + "<br>");
                       exc.printStackTrace();
                       pw.flush();
                    }
                    pw.flush();

                  }
                catch(Throwable e)
                  {
                    e.printStackTrace();
                    pw.flush();
                  }

             } // end of doPost()

            } // end of class MSMeta


4.3.7 Servlet for showing text object of a document — MSText
            The MSText servlet shows the text part object used to create the text index.
            The text objects are stored in the Content Manager server, and the indexing
            information is stored in the text server. So as a result of text query, you can
            get the primary item ID and part number for the object which was used as the
            indexing sources.

            As we already mentioned, a part object can be identified using the item ID of
            the document which has the part object and the part number of it. So with the
            information retrieved by executing the text query, you can get the real object
            used to make the index information.

            This servlet is called by MSList servlet when a text search has been
            executed.

            4.3.7.1 Main logic of this program (MSText)
            1. Retrieve the document using the item ID passed from MSList from the
               Content Manager server.
            2. Search the part objects stored with the document, and retrieve the part
               object whose PID equals the PID of the text object.

            4.3.7.2 Used classes and methods (MSText)
            Finding a document with a primary PID

            The PID consists of an item ID, a datastore name, and some other
            information. A primary PID means the item ID, it does not have other
            information such as the datastore name in which the document is stored.


                                       Chapter 4. Java client for Content Manager using WebSphere   109
                You cannot use the primary ID in the same manner as the whole PID string.
                To set the primary ID on a DKPid object, a method named setPrimaryId() is
                used. Once you set the primary ID, you can do the same thing as you did with
                the DKPid object created using the whole PID string. The example code is:
                // retrieve the document
                DKPid objPid = new DKPid();
                objPid.setPrimaryId(pid);
                DKDDO ddo = new DKDDO(dsDL, objPid);
                ddo.retrieve();

                Where pid is a String object which has a primary ID as its value.

                Retrieving a part object from a document
                Retrieving a part object from a document can be done in the same manner as
                retrieving all part objects from a document, with only one difference.. you can
                figure out the part number from the part object, and retrieve it using the
                method getPartId() of DKPart class. The example code is:
                // get the text part - part ID is 1
                short data_id = ddo.dataId("DKParts");
                DKParts pCol = (DKParts) ddo.getData(data_id);
                byte[] dataStr=null;
                if (pCol != null) {
                   DKBlobDL blob;
                   dkIterator iter = pCol.createIterator();
                   while (iter.more()) {
                      blob = (DKBlobDL) iter.next();
                      if (blob != null) {
                         if ( blob.getPartId() == 1 ) {
                            ... do something ...
                         }
                      }
                   }
                }

                Where ddo is a DKDDO object which is already retrieved, and the part
                number for retrieved part is 1.

                4.3.7.3 Source code (MSMeta)
                The following is the complete source code of MSMeta.java.
                import com.ibm.mm.sdk.common.*;
                import com.ibm.mm.sdk.server.*;

                import   javax.servlet.*;
                import   javax.servlet.http.*;
                import   java.io.*;
                import   java.util.*;




110   IBM Enterprise Information Portal - A Primer
import java.text.*;
import java.net.*;

/*
 * MSText class
 * - shows the text part content on the screen
 * - extends HttpServlet
 * - implements DKConstantFed
 */
public class MSText extends HttpServlet implements DKConstantFed
{
  // set max class size as needed for your application
  public final int MAX_CLASS_SIZE = 2;

  // set ResourceBundle name
 public final String BASENAME = "samples";
 static ResourceBundle rb = null;

 // connecting information
 private String libsrv = "libsrvrn";
 private String srchSrv = "TM";
 private String userid = "frnadmin";
 private String passwd = "password";

 ServletOutputStream pw = null;

 // initialization
 public void init(ServletConfig config) throws ServletException
 {
   super.init(config);
   /* get the ResourceBundle for localization */
   try{
     rb = ResourceBundle.getBundle(BASENAME);
   }
   catch(Throwable e) {
     e.printStackTrace();
   }
 }

 /**
    * @param req Class instance of HttpServletRequest.
    * @param res Class instance of HttpServletResponse.
    * @exception IOException When opening, reading from,
    * or writing to the registration file.
    */
 public void service(HttpServletRequest req, HttpServletResponse res)
      throws IOException {
   String pid = null;
   boolean found= false;

   res.setContentType("text/html");
   pw = res.getOutputStream();
   try {

       // get query string name-value pairs
       // into a String array for easy access
       String[] values;

       // get values for pid for the document to be retrieved
       values =req.getParameterValues("pid");
       if (values != null && values[0] != null && (values[0].length() != 0)){
         pid = values[0];
       }else {




                          Chapter 4. Java client for Content Manager using WebSphere   111
                           pid =null;
                         }
                         // for we replace # with ^ to deliver this string through cgi call,
                         // re-change ^ to # to get the original string.
                         pid = pid.replace('^','#');

                        try {
                //****** connect to the libsrv
                           DKDatastoreDL dsDL = new DKDatastoreDL();
                           dsDL.connect(libsrv, userid, passwd, "");
                //****** processing
                           pw.println("<HTML>");
                           pw.println("<!DOCTYPE HTML PUBLIC \"-//W3C/DTD HTML 3.2 Final//EN\">");
                           pw.println("<head>");
                           pw.println("<title>IBM Digital Library Internet Connection</title>");
                           pw.println("<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/txt\">");
                           pw.println("</head>");

                            // retrieve the document
                            DKPid objPid = new DKPid();
                            objPid.setPrimaryId(pid);
                            DKDDO ddo = new DKDDO(dsDL, objPid);
                            ddo.retrieve();

                            // get the text part - part id is 1
                            short data_id = ddo.dataId("DKParts");
                            DKParts pCol = (DKParts) ddo.getData(data_id);
                            byte[] dataStr=null;
                            if (pCol != null) {
                               DKBlobDL blob;
                               dkIterator iter = pCol.createIterator();
                               while (iter.more()) {
                                  blob = (DKBlobDL) iter.next();
                                  if (blob != null) {
                                     if ( blob.getPartId() == 1 ) {
                                        // after finding the text part, retrieve it and get the content
                                        // to write it on the output stream
                                        blob.retrieve();
                                        dataStr= blob.getContent();
                                        // because the text part is in txt mode and output is in http,
                                        // put <pre> tags to show the content in text-like mode.
                                        pw.println("<pre>");
                                        pw.write(dataStr);
                                        pw.println("</pre>");
                                        found = true;
                                     }
                                  }
                               }
                            }

                            pw.println("<body>");
                            pw.println("</body>");
                            pw.println("</HTML>");

                //****** disconnect from the libsrv
                           dsDL.disconnect();
                        }
                        catch (Exception exc) {
                           pw.print("Exception Message " + exc.getMessage() + "<br>");
                           exc.printStackTrace();
                           pw.flush();
                        }
                        pw.flush();




112   IBM Enterprise Information Portal - A Primer
                 }
               catch(Throwable e)
                 {
                   e.printStackTrace();
                   pw.flush();
                 }

             } // end of doPost()

            } // end of class MSText


4.3.8 Compilation and configuration of a servlet
            In this section we describe the compilation and configuration of a servlet.

            4.3.8.1 Compiling a servlet
            To run a servlet, the first thing you should do after you write your Java
            program is to compile the program using a Java compiler. We used the
            compiler which is a part of the Java Development Toolkit (JDK). The version
            of JDK we used is JDK 1.1.7. You can download the JDK from the Sun
            Microsystems web site:
            http://java.sun.com

            To compile a Java program, the following command can be used:
            javac MSInput.java

            Where MSInput.java is the name of program we developed. Remember the
            file name without the extension should be the same as one with the public
            class name, which has the main method. In our application, we don’t have
            any main method in any class. All the classes are extended the HttpServlets
            class, but internally main methods are inherited from the ancestor class. So
            the file name should be the same as the class name which inherits the
            HttpServlets class. The class name is case-sensitive.

            4.3.8.2 Configuring a program as a servlet
            Copying a servlet to the servlet’s directory
            After compiling this program, the compiled class should be moved to the
            servlet directory, or any directory which the IBM WebSphere Application
            Server can read. An example to do this is:
            copy MSInput.class c:\WebSphere\AppServer\servlets\

            Where c:\websphere\AppServer\ is the directory which was used to install
            the IBM WebSphere application server. This directory is the default directory
            where the servlets can be placed.




                                       Chapter 4. Java client for Content Manager using WebSphere   113
                Registering a servlet in the IBM WebSphere Application server
                You must register this servlet in the WebSphere server before you use it, or
                the WebSphere application server will not recognize your request. Refer to
                your WebSphere documentation or Appendix B, “Installing and configuring
                IBM WebSphere V.2.02” on page 169 to find out how to add a servlet to your
                application server.

                Figure 52 is an example of the screen which shows where to add a servlet
                named MSInput to the WebSphere application server.

                After entering the servlet name and class name of the new servlet, you can
                verify that it is a valid servlet that can be used in the WebSphere application
                server, by clicking the TEST button. If the class cannot pass the validation
                test, it cannot be used as a servlet of IBM WebSphere Application Server.

                Click ADD button to add the servlet in the application server.




114   IBM Enterprise Information Portal - A Primer
Figure 52. Adding a servlet in the IBM WebSphere Application server




                                              Chapter 4. Java client for Content Manager using WebSphere   115
116   IBM Enterprise Information Portal - A Primer
Chapter 5. Lotus Notes client for content servers using EIP

                  This chapter discuses the design and development of a Lotus Notes based
                  client application for the content servers using the EIP Java APIs. This
                  chapter also discusses the federated search, a search that runs
                  simultaneously against connected content servers. Prior to running the
                  application discussed here, you should have installed the EIP database and
                  the federated runtimes in the respective systems.


5.1 Preparing for development
                  To develop the Lotus Notes based client application, your system should meet
                  the prerequisite hardware and software requirements, see Table 6.
                  Table 6. Development system hardware and software requirements

                    Category                    Required hardware / software

                    Processor                   400 Mhz Intel Pentium II

                    RAM                         64 MB

                    Storage                     2 GB

                    Display and Adapter         1024x768x256

                    Operating system            Windows 95, Windows 98, or Windows NT 4.0 with service
                                                pack 4 or greater

                    Network support             Microsoft Networking Services

                  Apart from the above listed system hardware and software, you need the
                  following software installed on your system:
                    • Lotus Domino Release 5.0 (both the designer and user client)
                    • Java Development Kit Version 1.1.7
                    • EIP runtimes and the RMI client settings.

                  For installing the Lotus Domino and the JDK, please refer to the respective
                  installation documentation. For installing EIP Runtimes and configuring RMI
                  client on your system please refer to Chapter 3, “Installing and configuring the
                  IBM EIP” on page 37.

                  Make sure everything is installed properly, up and running. To verify your RMI
                  client settings, we suggest that you install the EIP client application and test
                  the connection.



© Copyright IBM Corp. 2000                                                                        117
5.2 Setting up the Windows development environment
                The EIP CD includes a set of Java Packages, which you can use for your
                development. These JAR files are installed when you install the EIP on your
                system. The Java APIs can be imported into your Java programs to use all
                the APIs available in the respective packages. These APIs are broadly
                categorized into four major packages.
                  • com.ibm.mm.sdk.server
                      This has classes which access and manipulate datastore information.
                  • com.ibm.mm.sdk.client
                      This package is implemented for communication with the server package,
                      network control, and data transformation between the server and clients.
                  • com.ibm.mm.sdk.common
                      This package is needed by the server package and the client package.
                  • com.ibm.mm.sdk.cs
                      This package connects the client and server dynamically across the
                      network.

                Since we are using the RMI client, all of our Java programs will import the
                com.ibm.mm.sdk.client and com.ibm.mm.sdk.common packages.

                Note: A program cannot import the server package and client package at the
                same time. It must be a server program using the server package, or a client
                program using the client package.

                Set these libraries in the environment variable CLASSPATH, to enable the
                Java compiler to find the packages imported.
                  •   cmbcm30.jar
                  •   cmbdl30.jar
                  •   cmbdlc30.jar
                  •   cmbdd30.jar
                  •   cmbddc30.jar
                  •   cmbip30.jar
                  •   cmbipc30.jar
                  •   cmbod30.jar
                  •   cmbv430.jar
                  •   cmbv4c30.jar
                  •   cmbfed30.jar
                  •   cmbfedc30.jar
                  •   cmbjdbc30.jar


118   IBM Enterprise Information Portal - A Primer
            • cmbjdcc30.jar
            • cmbdes30.jar
            • cmbdesc30.jar

           These libraries are all located in the directory %CMBROOT%\Lib, where
           %CMBROOT% is the directory where the EIP is installed.

           Since all of our programs are client based, that is it talks to the server
           component in the RMI server, only the files which ends with *c30.jar files are
           referred. If you are writing applications which will run at the server end, you
           need to specify the files which does not end with *c30.jar.

           For example, for the federated search, we will import cmbfedc30.jar if our
           application will run on the RMI client, or we will import cmbfed30.jar if our
           application will run on the RMI server or on a local configuration.


5.3 Setting up the Lotus Domino development environment
           This section describes the components of the Domino Development
           environment, and the setup of the environment for running your client
           applications.

           Domino applications: Domino applications let people share, collect, track,
           and organize information, using Lotus Notes® or the Web. Domino
           applications can cover a wide range of business solutions, including:
            • Workflow - Applications that route information.
            • Tracking - Applications that monitor processes, projects, performance, or
              tasks.
            • Collaboration - Applications that create a forum for discussion and
              collaboration.
            • Data Integration - Applications that integrate with relational databases and
              transactional systems.
            • Personalization - Applications that produce dynamic content based on, for
              example, user name, user profile, access rights, or time of day.
            • Globalization - Applications that use Domino Global Workbench to
              produce global sites.

           Every Domino application starts with a Domino Database. All Domino
           applications contain one or more Domino databases.




                                     Chapter 5. Lotus Notes client for content servers using EIP   119
                Domino Databases: A Domino database is the container for the data, logic,
                and design elements in your application. Design elements are building blocks
                you use to create your application. Design elements include: Forms, Views,
                Agents, shared resources and more.

                Programming in Domino: Formula, Lotus Script, Java, and Java Script code
                provide an integral programming interface to Domino Designer. You can
                attach code to various objects depending on the need. For example, if you
                create a computed field in a form, you would attach a formula to compute the
                value of the field. Or you could attach Java Script code to the onFocus event
                of a field; this code would execute whenever a user places focus on the field.
                Or you might decide to create a formula, Lotus Script, or Java agent to
                automatically update all the documents in a database at scheduled times.

                Domino also provides a programming interface for Java applications and
                applets. These applications and applets can operate locally by accessing
                installed Domino software or remotely by connecting to a Domino server
                using IIOP protocols.

                Using Domino APIs: In our Domino based client application, we will use the
                Java APIs provided by the Enterprise Information Portal, as well as the
                Domino Java Classes to communicate with Lotus Notes.

                You can call into the object interface from a Java program by importing the
                lotus.domino package. The program can be coded as an application, a
                Domino agent, an applet, or a servlet. Compilation must be on a machine with
                Domino Designer Release 5 installed.

                Note: The lotus.domino package has the same content as the Release 4.6
                lotus.notes package plus new classes, methods, and other enhancements.

                Designer requirements: All the Java programs written in this chapter,
                imports the lotus.domino package for using the Domino APIs.

                Compilation of a Java program using the lotus.domino package requires
                installation of Domino Designer Release 5.

                Ensure that the notes.ini file of the Designer machine contains the following
                line:
                ALLOW_NOTES_PACKAGE_APPLETS=1

                For stand-alone applications, include domino\java\NCSO.jar and Notes.jar
                from the Notes directory in the CLASSPATH environment variable. For
                example:



120   IBM Enterprise Information Portal - A Primer
set CLASSPATH=.;c:\notes\domino\java\NCSO.jar;c:\notes\Notes.jar

Notes.jar contains the high-level lotus.domino package, the
lotus.domino.local package for local calls, and the old lotus.notes package.
NCSO.jar contains the high-level lotus.domino package and the
lotus.domino.corba package for remote calls. Strictly, you do not need
NCSO.jar if you are not compiling remote calls and you do not need
Notes.jar if you are not compiling local calls or old calls.

Your class code must import the high-level lotus.domino package:
import lotus.domino.*;

Important: You should copy the cmbclient.ini from the EIP home directory to
the Notes home directory.For example: if you have installed the EIP in
C:\CMBROOT and the Lotus Notes in C:\Notes, the cmbclient.ini which will
be in C:\CMBROOT directory has to be copied to the C:\Notes directory
before you run any Notes based client applications that uses the EIP APIs.
Even if you have specified the C:\CMBROOT in the PATH environment
variable, still you will get a Notes error. Notes does search in its home
directory. So copy the cmbclient.ini to the Notes home directory.

Lotus Domino Designer: Designer is an integrated application development
environment which lets developers and web site designers create, manage,
and deploy secure, interactive applications for the Domino Server.

When you open a design element such as a page or a form (see Figure 53),
you will be in the work area for that design element. In addition to items in the
Designer Workspace, the Programmer's pane appears.

You can select your own choice of the programming language from the Run
option in the Programmer’s panel based on the attributes of the selected
object.




                          Chapter 5. Lotus Notes client for content servers using EIP   121
Figure 53. The different panes in Lotus Domino Designer



5.4 Writing an Agent using Java in Lotus Domino
                  The scope of this section only covers how to write an agent using Java code
                  in a Lotus Domino Agent (see Figure 54). Please refer to the Domino
                  Designer’s Help topics for more details.




122     IBM Enterprise Information Portal - A Primer
Figure 54. Creating an agent which uses Java code

                  A Domino agent using Java extends the AgentBase class, which extends the
                  NotesThread class. The class that contains the agent code must be public.
                  The entry point to the functional code must be public void NotesMain() .

                  For foreground agents, System.out and System.err output goes to the Java
                  debug console. For locally scheduled agents, System.out and System.err
                  output goes to the Domino log.

                  System.exit must not be used to terminate a program using the NotesThread
                  class (and by extension the AgentBase class). In an agent, System.exit
                  throws SecurityException.

                  The lotus.domino classes allow you to access named databases, views,
                  documents, and other back-end objects.




                                                Chapter 5. Lotus Notes client for content servers using EIP   123
                The Session class is the root of the Domino back-end Objects containment
                hierarchy, providing access to the other Domino objects, and represents the
                Domino environment of the current program.

                From an Agent, use the AgentBase.getSession() function to get the handle
                for the current Domino session.

                In an Agent you can include Java code in two ways (Refer Figure 54). One
                way is to write the direct Java code in the Programmer’s pane itself. By
                selecting the “Java” option from the Run menu you will be able to write the
                Java code. The other way of including Java code, is to compile the Java code
                in an external environment and then import it along with other files into a
                Domino agent. This can be done by selecting the “Imported Java” option from
                the Run menu.

5.4.1 How to write inline Java in an Agent
                To create a new Agent in your current Database,which will use Java as the
                language for coding, follow these steps:
                1. Select Create - Agent.
                2. Specify a name, options, scheduling, and Add Search as needed.
                3. Select Java from the Run menu.
                4. Write your Java after the remark line, Your code goes here, or click Edit
                   Project to add resource, class, or .jar files to the current agent.
                5. Note: Any changes made to the .java files in the current agent exist only in
                   the agent. If you want to update the original files, you must export the
                   agent to the directory containing the files you want to update.
                6. (Optional) Click New Class to add a new class. A horizontal bar
                   separates each class. The name of a class appears on the bar above the
                   class to which it refers.
                7. Click on Compile below the Script area. You can choose to compile the
                   current class or the entire agent.
                8. (Optional) Click Export to export Java to a project directory.
                9. Save the Agent.

5.4.2 How to import Java in an Agent
                To create a new Agent in your current Database,which will use pre-compiled
                Java classes, follow these steps:
                1. Select Create - Agent.



124   IBM Enterprise Information Portal - A Primer
                   2. Specify a name, options, scheduling, and Add Search as needed.
                   3. Select Imported Java from the Run menu.
                   4. Click Import Class Files. (see Figure 55)




Figure 55. Importing Java files

                   5. Under the Available Java Files column in Figure 55, select the filing
                      system and base directory for the files you want to import. If you are
                      importing from a named package, the base directory must be above the
                      directory containing the class files.
                   6. (Optional) Select the appropriate check box for Show File Types. The
                      default file type is All.
                   7. Select the files you want to import from the file list and click Add/Replace
                      Files. To import all of the files in the base directory and all of its
                      subdirectories, click Add/Replace All. To remove a file, or group of files
                      from the Current Agent Files column, select the file(s) and click Delete.



                                             Chapter 5. Lotus Notes client for content servers using EIP   125
                8. Put the files in the proper order in the Current Agent Files column by
                   clicking Reorder Up or Reorder Down to move files up or down, or by
                   dragging files into place. You may move files one at a time, or in groups.
                9. Enter the base class in the Base class box or select it from the list.
                10.(Opt ional) Click Refresh, or Refresh all to reload files in the Current
                   Agent Files column.
                11.Click OK to import files.
                12.(Optional) Click Reimport Class Files to import additional files, or
                   reimport an existing file.

                All the Java code used in the client application discussed in this book are
                compiled externally and then imported to the respective agents.


5.5 Passing parameters to the Java Agent
                To pass parameters or values to the Java code from the Notes environment,
                as well as to the Notes environment from the Java code, you can adopt many
                ways. Three different options are discussed here. It’s up to you to decide
                which way to pass parameters. There are many other ways to pass
                parameters other than the options discussed here.

5.5.1 Option 1: Passing values using the user profile
                This is one of the easiest ways to pass parameters to and from the Java code.
                Before calling the Java agent, set the values of the fields in the current user’s
                profile document and you can retrieve the values from Java by getting the
                handle to the current user profile.

                You can set or retrieve the User profile document fields using formulas, Lotus
                script, or Java.

                Here are some examples:
                  • Set / Retrieve the user profile fields using formulas:
                @SetProfileField("$UserProfile"; "Field01”;”Param Value”; @UserName) ;
                @GetProfileField("$UserProfile"; "Field01”; @UserName) ;
                  • Set / Retrieve the user profile fields using Lotus script:
                Set db = session.CurrentDatabase
                Set doc = db.GetProfileDocument("$UserProfile",session.UserName)
                Print doc.Field01(0)
                doc.Field01 = “Param value”
                Call doc.save(False,False)



126   IBM Enterprise Information Portal - A Primer
             • Set / Retrieve the user profile fields using Java APIs:
            Session sess = getSession();
            AgentContext ac = sess.getAgentContext();
            Database db = ac.getCurrentDatabase();
            Document pdoc = db.getProfileDocument("$UserProfile",sess.getUserName());
            String input = pdoc.getItemValueString("Field01");
            pdoc.replace Item Value("Field01",”Paramvalue”) ;
            pdoc.save(False,False);


5.5.2 Option 2: Passing values using the environment variables
            This method is not advisable to use in the Domino server, but you can use it
            in the workstations depending on your need. Before calling the Java agent,
            set the values of the environment variables and you can retrieve the values
            from the Java by getting the handle to the current session.

            You can set or retrieve the environmental variables using formulas, Lotus
            script, or Java.

            Here are some examples:

            . Set / Retrieve the environmental variables using formulas:
            @Environment("Field01”; “Param value”) ;
            @SetEnvironment(“Field01”;”Param value”);
            @Environment(“Field01”) ;

            . Set / Retrieve the environmental variables using Lotus script:
            Dim sess as New NotesSession
            Call sess.SetEnvironmentVar(“Field02”,”Param value”)
            value = sess.GetEnvironmentString("Field01")

            . Set / Retrieve the environmental variables using Java APIs:
            Session sess = getSession();
            String value = sess.getEnvironmentString(“Field01”);
            sess.setEnvironmentVar("Field01", "Param value");


5.5.3 Option 3: Passing values using the in-memory document
            The in-memory document is a representation of the current document in the
            memory. This document representation gives you read-only access to the
            document in which the Agent was invoked.

            If the agent was invoked from a view through the UI, then the in-memory
            document is the document highlighted in the view.



                                      Chapter 5. Lotus Notes client for content servers using EIP   127
                The in-memory document can be accessed using the getDocumentContext
                property of the AgentContext class defined in the lotus.domino package.

                Here is an example:
                Session session = getSession();
                AgentContext agentContext = session.getAgentContext();
                Document doc = agentContext.getDocumentContext();
                if (doc != null) {
                System.out.println("Value of 'Subject' in document is " +
                doc.getItemValueString(“Subject”));
                }

                Once you get the handle for the in-memory document, all the field values of
                the current UI document will be available to the Java code. Since this is a
                read-only document you cannot pass values from Java code to the Notes
                environment.

                Option 3 is not optimal and may or may not affect your application
                performance. Follow the Lotus Domino design guidelines to build your
                applications. The application discussed in this book uses option 1 and 2 to
                demonstrate the functionalities. It is upto the user to select the options based
                on performance and other issues.


5.6 The Lotus Notes client application
                The Lotus Notes based client application is designed and developed using
                the native framework and using Java (see Figure 56). This client application
                will give you an idea of how to develop EIP client applications in Lotus Notes
                and how to integrate these products.




128   IBM Enterprise Information Portal - A Primer
Figure 56. Sample Notes application

                  This application is only a basis. You should not consider it as a fully
                  developed application. Lotus Domino allows you to develop applications
                  adopting various architectures. One of them is discussed in this chapter. You
                  should further apply your architectural and programming skills to fully develop
                  a Lotus Notes based client application which will integrate with EIP.

                  The purpose of the application is to demonstrate how you can design and
                  develop Lotus Notes based applications, which need to be integrated with
                  different content servers using the EIP. The application discusses how to use
                  the EIP Java APIs in Notes and how to communicate with the EIP federated
                  layer.

                  Figure 56 shows the Notes user interface of the client application discussed
                  here. It uses the frameset to show the various components in different
                  frames. It has a Login frame, Search criteria frame and a Result frame. These
                  frames are discussed separately in the following sections.


                                            Chapter 5. Lotus Notes client for content servers using EIP   129
                The functionality of the client application is as follows:

                The user will enter the Login name, password and the federated database
                name and will click on the Federated Login button (Figure 57).




                Figure 57. Before Login

                The application will verify the login name by connecting to the EIP database.
                Once the login is successful, you see a message saying that you have logged
                into the system successfully as in Figure 58.




130   IBM Enterprise Information Portal - A Primer
Figure 58. After a successful login

The application also retrieves and displays all the federated entities defined in
the EIP database. The user selects any one of the federated entities and the
application fills up the fields in the Search criteria form with the federated
attributes and operators for that selected entity.

The user composes the query expression using the Search criteria form
(Figure 59) and submits the request to the EIP through the APIs. The EIP
performs a federated search in all the available content servers and displays
the results in the results frame.




                               Chapter 5. Lotus Notes client for content servers using EIP   131
Figure 59. Composing the query expression

                  Note: This application uses the Federated entities and the attributes so that
                  you can build a dynamic query expression with any combination of “AND” and
                  “OR”. This doesn’t use the Search templates which are defined in the EIP
                  database. If you specifically want to use the Search templates, you can use
                  the APIs to get the search templates instead of the federated entities.

5.6.1 Designing the Login form
                  The next section discusses the different forms used in the client application,
                  and the possibilities for designing your application interface.

                  The client application uses three major forms:
                      The Login and Federated entity selection interface
                      The Search Criteria entry interface
                      The form used for Parameter definition

                  The design of these forms and their various action buttons are also
                  discussed.




132     IBM Enterprise Information Portal - A Primer
Details of the Login form
This form is used to enter the Login name, password and the EIP database
name to login to the EIP federated database. This form also provides the
interface to select the federated entity after the user has logged in. The Login
form is displayed in the Login frame (see Figure 60).

Since this form is not saved for any reason, we created a SaveOptions field
and assigned a default value to 0 so that it will not prompt with the famous Do
you want to save? dialog box when we exit the application. We also created
a LoginFlag field to trace whether the user has successfully logged in or not.

There are two sections in this form. The first section has the interface for the
Login and the second section has the interface for the Federated entity
selection. At any point in time, only one of these sections should be visible to
the user.

Since the second section has to be displayed only after a successful login, we
place a condition for the display of the second section based on a successful
login. The first section is visible to the user if the user has not logged in and it
is hidden after a successful login. The second section is visible to the user if
the user has successfully logged in and it is hidden if the user has not logged
in or the user has logged off.




                           Chapter 5. Lotus Notes client for content servers using EIP   133
Figure 60. Designing the Login form

                  Place these conditions in the “Hide when” formula for the sections (see Figure
                  61).

                  For the first section the “Hide when” formula is:
                  @If(@GetProfileField("$UserProfile";"LoginFlag";@UserName) ="1")

                  For the second section the “Hide when” formula will be :
                  @If(@GetProfileField("$UserProfile";"LoginFlag";@UserName) !="1")

                  We access the User profile, because we also have the same “LoginFlag” field
                  in the User Profile form to access across the frames.




134     IBM Enterprise Information Portal - A Primer
We also have a “FederetedEntity” field, which is a combo box, to provide the
user with a set of available federated entities defined in the EIP database.
Once the user has successfully logged in, the Login Java agent populates the
user profile with a Federated entity list. The Login Java agent is discussed
later in this chapter.




Figure 61. Hide when formula for the first section of the Login form

The list has to be brought into the combo box field to display the available
entities. For the “FederatedEntity” field, you should select the “Refresh
choices on document refresh” in the options section of the Field properties.
To make this possible we will write a formula in the choices option of the
FederatedEntity field as follows:
@Explode(@GetProfileField("$UserProfile";"FederatedEntityList";@UserName);
";")

This will explode the list and the combobox will display the options.

You have to create the two text fields, “Login_Name”, “Login_Database” and
the password field “Login_Password” and place it as shown in Figure 60

The Login form also contains three action buttons namely Federated Login
to login into the EIP database using the entered field values, Logout to log
out and to reset the user interface, and the Get attributes to populate the
search form with the attributes of the selected Federated entity.




                                Chapter 5. Lotus Notes client for content servers using EIP   135
                5.6.1.1 Federated Login action button
                The functionality of the Federated Login button is to validate the data entered
                by the user, update the current user’s profile with the data entered by the user
                in the login form, and to call the FSLogin agent to start the Java code. After
                the execution of the Java code, the action button checks whether the Login is
                successful or not. If the Login is not successful it displays a message to the
                user, and exits.

                If the Login is successful, it again updates the user profile document with the
                Federated entity list which is passed by the Java code, and refreshes the
                Login form to display the second section. When the Login form gets
                refreshed, the FederatedEntity field also gets refreshed with the new set of
                choices from the User profile.

                The code for the Federated Login action button is written using Lotus script.
                To access the current User profile, use the GetProfileDocument function of
                the NotesDatabase class. Remember you should pass the User name as a
                parameter.
                'Get the user profile
                Set updoc = db.GetProfileDocument("$UserProfile", sess.UserName)

                To update a field in the User profile you can directly assign the value to the
                Field names. And call the Save method to save the modified fields.
                'Update the user profile fields and save
                Set doc = uidoc.Document
                updoc.Login_Name = doc.Login_Name(0)
                updoc.Login_Password = doc.Login_Password(0)
                updoc.Login_Database = doc.Login_Database(0)
                Call updoc.Save(True, False)

                To run an agent, use the GetAgent function of the NotesDatabase class to get
                the handle for the agent and then use the Run function to run the agent code.
                We have added parenthesis to the name of agent, since it is a hidden agent.
                'Call the Java Agent
                Set JAgent = db.GetAgent("(FSLogin)")
                Call JAgent.Run()

                Then, after the Java code completes its execution, we should get the
                federated entity list from the environment variable (the environment variable
                is updated by the Java code) and update the User profile.
                ‘After a successful login,update the user profile
                updoc.LoginFlag = "1"
                updoc.FederatedEntityList = sess.GetEnvironmentString("FEList")



136   IBM Enterprise Information Portal - A Primer
Call updoc.Save(True, False)

Finally, it refreshes the current document to show the second section after a
successful login.

5.6.1.2 Full source code of the Federated Login action button
Dim   ws As New NotesUIWorkspace
Dim   sess As New NotesSession
Dim   db As NotesDatabase
Dim   uidoc As NotesUIDocument
Dim   doc As NotesDocument
Dim   updoc As NotesDocument
Dim   JAgent As NotesAgent

Set uidoc = ws.CurrentDocument
Set db = sess.CurrentDatabase

' Validate the input
If(ValidateFields() <> 1) Then
Exit Sub
End If
'Get the user profile
Set updoc = db.GetProfileDocument("$UserProfile", sess.UserName)
Set doc = uidoc.Document

updoc.Login_Name = doc.Login_Name(0)
updoc.Login_Password = doc.Login_Password(0)
updoc.Login_Database = doc.Login_Database(0)
Call updoc.Save(True, False)

'Call the Java Agent to Login to the Federated Datastore
Set JAgent = db.GetAgent("(FSLogin)")
Call JAgent.Run()
'Test whether the Login is successful
If sess.GetEnvironmentString("LoginFlag") <> "1" Then
'Login Failed
Messagebox "Login Failed ! Verify the Login name, Password and Database ame
!", MB_OK + MB_ICONSTOP, "EIPFS Message"
Exit Sub
End If
'The user has successfully logged in
doc.LoginFlag = "1"
updoc.LoginFlag = "1"
updoc.FederatedEntityList = sess.GetEnvironmentString("FEList")
Call updoc.Save(True, False)




                          Chapter 5. Lotus Notes client for content servers using EIP   137
                'Reset the Environmental variables
                Call sess.SetEnvironmentVar("LoginFlag","")
                Call sess.SetEnvironmentVar("FEList","")
                Call uidoc.Refresh

                5.6.1.3 Get Attributes action button
                The functionality of the Get Attributes button is to validate the data entered by
                the user, update the current user’s profile with the selected Federated entity
                and to call the FSGetFedEntity agent to start the Java code. After the
                execution of the Java code, the action button composes a new Search criteria
                form in the Criteria frame.

                When the search criteria form is composed it uses the values in the user
                profile to display various options.

                The code for the Get Attributes action button is also written in Lotus script. It
                accesses the current user profile and updates with the currently selected
                Federated entity and calls the FSGetFedEntity agent. Also, it updates the
                user profile with the list of attributes and operators which is passed by the
                Java code, for the selected federated entity.
                ‘update the user profile to the pass the selected Fed entity to Java
                updoc.FederatedEntity = doc.FederatedEntity(0)
                Call updoc.Save(True, False)

                'Call the Java Agent to get the list of attributes and operators
                Set JAgent = db.GetAgent("(FSGetFedEntity)")
                Call JAgent.Run()

                'Set the user profile fields
                updoc.SCName = sess.GetEnvironmentString("SCName")
                updoc.SCOper = sess.GetEnvironmentString("SCOper")
                Call updoc.Save(True, False)
                And finally you need to compose the Search criteria form in the Criteria
                Frame to display to new set of attributes and operators for the selected
                Federated entity.
                'Show the new set of attributes and operators
                Dim ws As New NotesUIWorkspace

                Call ws.SetTargetFrame("FS_Frame_Middle_Right") // The criteria Frame
                Call ws.ComposeDocument( "", "", "$FSearch" )

                5.6.1.4 Full source code of the Get Attributes action button
                Dim ws As New NotesUIWorkspace
                Dim sess As New NotesSession
                Dim db As NotesDatabase



138   IBM Enterprise Information Portal - A Primer
           Dim   uidoc As NotesUIDocument
           Dim   doc As NotesDocument
           Dim   updoc As NotesDocument
           Dim   JAgent As NotesAgent

           Set uidoc = ws.CurrentDocument
           Set db = sess.CurrentDatabase

           'Get the user profile
           Set updoc = db.GetProfileDocument("$UserProfile", sess.UserName)
           Set doc = uidoc.Document

           If Trim(doc.FederatedEntity(0)) = "" Then
           Messagebox "Please select the Federated entity !", MB_OK + MB_ICONSTOP,
           "EIPFS Message"
           Exit Sub
           End If

           updoc.FederatedEntity = doc.FederatedEntity(0)
           Call updoc.Save(True, False)

           'Call the Java Agent to show the Search Template
           Set JAgent = db.GetAgent("(FSGetFedEntity)")
           Call JAgent.Run()

           'Set the user profile fields
           updoc.SCName = sess.GetEnvironmentString("SCName")
           updoc.SCOper = sess.GetEnvironmentString("SCOper")
           Call updoc.Save(True, False)

           'Reset the Environmental variables
           Call sess.SetEnvironmentVar("SCName","")
           Call sess.SetEnvironmentVar("SCOper","")

           'Show the new Search Template
           Call ws.SetTargetFrame("FS_Frame_Middle_Right")
           Call ws.ComposeDocument( "", "", "$FSearch" )


5.6.2 Designing the Search form
           This form will be used by the user to enter the search criteria, the search
           expression which will be used to search all the content servers. This form will
           be displayed in the Criteria frame (see Figure 62).




                                     Chapter 5. Lotus Notes client for content servers using EIP   139
Figure 62. Designing Search form

                  Since this form is not saved for any reason, we created a “SaveOptions” field
                  and assigned a default value to “0”, so that it does not prompt us with the
                  famous “Do you want to save?” dialog box when we exit the application. We
                  also created a “SearchCriteria” field to hold the final search expression
                  composed by the user using the fields, operators, and action buttons
                  provided in the interface.

                  This form also has two sections. The first section has the interface for
                  composing the Search expression and the second section has just a
                  message that the user needs to login and select the federated entity in order
                  to display the search criteria interface to the user. At any point of time only
                  one of these sections should be visible to the user.




140     IBM Enterprise Information Portal - A Primer
Since the first section is not displayed until the user has successfully logged
in and selected a federated entity, we place a condition for the display of the
first section based on a successful login. The first section is not visible to the
user if the user has not logged in, and it is initially hidden. The second section
is visible to the user initially, giving a message to the user that he/she needs
to login and select the federated entity. It will be hidden if the user has
successfully logged in and selected a federated entity for the search criteria
entry.

Place these conditions in the “Hide when” formula for the sections.

For the first section the “Hide when” formula is:
@If(@GetProfileField("$UserProfile";"LoginFlag";@UserName) !="1")

For the second section the “Hide when” formula is:
@If(@GetProfileField("$UserProfile";"LoginFlag";@UserName) ="1")

We access the User profile for checking the successful login by the user
which is captured in the “LoginFlag” field by the Login form.

In the search criteria interface, we have “SC_Display”, a computed display
field that displays the currently composed search expression. It gets updated
when ever the user clicks on one of the seven Hotspot buttons.

We have three more fields, FSC_Name, FSC_Operator, FSC_Value in the
criteria composing section. The FSC_Name holds all the attributes of the
currently selected Federated entity. The FSC_Name will update its choices
from the SCName field in the current user’s profile, which will be updated by
the Java code. The formula for its choices are:
@Explode(@GetProfileField("$UserProfile";"SCName";@UserName))

FSC_Operator holds the set of operators based on the selection of the
attributes in FSC_Name. The set of operators can differ based on the type of
the attribute. If it is a text attribute, then the IN, NOT IN operators apply. If it is
a date attribute, then BETWEEN operator applies. We leave it to you to
design this field. To update the operator choices based on the FSC_Name,
you should select the “Refresh choices on document refresh” in the options
section of the field properties. The formula for its choices are:
@If(@Member(FSC_Name;@Explode(@GetProfileField("$UserProfile";"SCName";@Us
erName);";")) != 0 ;
@Do(@Explode(@Subset(@Subset(@Explode(@GetProfileField("$UserProfile";"SCO
per";@UserName);";");@Member(FSC_Name;@Explode(@GetProfileField("$UserProf
ile";"SCName";@UserName);";")));-1);"#"));"")



                            Chapter 5. Lotus Notes client for content servers using EIP   141
                This formula extracts the subset of operators from the SCOper field, based on
                the position of the selected FSC_Name in the SCName field.

                FSC_Value is a normal Text field, where the user will enter the values for the
                selected expression in the FSC_Name and FSC_Operator field.

                There are six Hotspot buttons defined in the interface. The functionality of
                each button is given here.

                AND Button: To add a AND operator to the composed expression.
                'Add "AND" to the search criteria
                doc.SearchCriteria = doc.SearchCriteria(0) + " AND "
                Call uidoc.Refresh
                    OR Button: To add a OR operator to the composed expression.
                    ( : To add a left paranthesis to the composed expression.
                    ) : To add a right paranthesis to the composed expression.
                    Clear: To clear the composed expression.
                    Add criteria : To add the selected field, operator and value to the
                    composed search expression.
                doc.SearchCriteria = doc.SearchCriteria(0) + " " + Trim(doc.FSC_Name(0)) +
                " " + Trim(doc.FSC_Operator(0)) + " '" + Trim(doc.FSC_Value(0)) + "'"

                The Search criteria form also has a action button named “Search”, to invoke
                the search agent and to display the results.

                5.6.2.1 Search action button
                The functionality of the Search button is to validate the Search criteria
                entered by the user, update the current user’s profile with the composed
                search expression, and to call the FSSearch agent to start the Java code.
                After the execution of the Java code, the action button displays the number of
                hits in the result set and refreshes the result view in the Result frame.

                The code for the Search action button is also written in Lotus script. It
                accesses the current user profile and updates with the composed search
                expression and calls the FSSearch agent. After the search is completed it
                displays the user with the number of Hits in the result set.
                ‘update the user profile to the pass the selected Fed entity to Java
                updoc.QueryString = doc.SearchCriteria(0)
                Call updoc.Save(True, False)

                'Call the Java Agent to show the Search Template
                Set JAgent = db.GetAgent("(FSSearch)")


142   IBM Enterprise Information Portal - A Primer
Call JAgent.Run()

Messagebox "No. of Hits for the Search = " +
sess.GetEnvironmentString("SHitCount"), MB_OK + MB_ICONQUESTION, "EIPFS
Message"

Finally, you need to refresh the result view in the Result frame.
'Show the new result set
Dim ws As New NotesUIWorkspace

Call ws.SetTargetFrame("FS_Frame_Bottom")
Call ws.ViewRefresh

5.6.2.2 Source code for the Search action button
Dim   ws As New NotesUIWorkspace
Dim   sess As New NotesSession
Dim   db As NotesDatabase
Dim   uidoc As NotesUIDocument
Dim   doc As NotesDocument
Dim   updoc As NotesDocument
Dim   JAgent As NotesAgent

Set uidoc = ws.CurrentDocument
Set db = sess.CurrentDatabase

'Get the user profile
Set updoc = db.GetProfileDocument("$UserProfile", sess.UserName)
Set doc = uidoc.Document

If Trim(doc.SearchCriteria(0)) = "" Then
Messagebox "Please enter the Search criteria !", MB_OK + MB_ICONSTOP,
"EIPFS Message"
Exit Sub
End If

updoc.QueryString = doc.SearchCriteria(0)
Call updoc.Save(True, False)

'Call the Java Agent to show the Search Template
Set JAgent = db.GetAgent("(FSSearch)")
Call JAgent.Run()

Messagebox "No. of Hits for the Search = " +
sess.GetEnvironmentString("SHitCount"), MB_OK + MB_ICONQUESTION, "EIPFS
Message"




                          Chapter 5. Lotus Notes client for content servers using EIP   143
                'Reset the Environmental variables
                Call sess.SetEnvironmentVar("SHitCount","")

                'Refresh the search view
                Call ws.SetTargetFrame("FS_Frame_Bottom")
                Call ws.ViewRefresh


5.6.3 Designing the User Profile form
                This form is used by the application to pass parameters to the Java code from
                the Lotus Notes environment. This is an intermediate form used by the
                application in between Java and Lotus Notes (see Figure 63).

                In this form, we have eight text fields and one password field. The
                FederatedEntityList , SCName and SCOper fields are multivalue fields. The
                values can be separated by either a comma or a colon. The Login_Name,
                Login_Password, and the Login_Database fields holds the Login name,
                password and EIP database name respectively. The LoginFlag is used to
                verify whether the user has logged into the EIP database or not. The
                FederatedEntityList field contains all the federated entities defined in the EIP
                database. The FederatedEntity field holds the currently selected entity. The
                SCName field contains all the attributes of the currently selected federated
                entity. The SCOper field holds the respective set of operators for the
                attributes. This form will be used internally by the application.




144   IBM Enterprise Information Portal - A Primer
Figure 63. Designing the User Profile form


5.6.4 Federated Datastore and the EIP Java APIs
                   Before we continue with our development, let us discuss the Federated
                   Datastore and its related concepts, as well as the EIP Java APIs for
                   Federated Datastore which we use in our development.

                   5.6.4.1 Federated Datastore
                   A Federated Datastore is a virtual datastore which combines several
                   heterogeneous datastores into a consistent and unified conceptual view. This
                   view, or federated schema, is established via schema mapping of the
                   underlying datastores. The users interact with a Federated Datastore using
                   the federated schema, without needing to know what individual datastore
                   participates in this Federated Datastore.

                   The Federated Datastore coordinates query evaluation, data-access, and
                   transaction processing of the participating datastores. Specifically the
                   federated schema, a multiple-search query can be formulated, executed, and



                                             Chapter 5. Lotus Notes client for content servers using EIP   145
                coordinated to produce results in the form of a datastore-neutral dynamic
                data object. The EIP database is what we call the Federated Datastore.

                The execute and evaluate methods of DKDatastoreFed takes query strings
                expressed in federated query language. DKFederatedQuery object accepts
                queries in this syntax.

                5.6.4.2 Federated searching and query processing
                Federated searching is a query issued from Enterprise Information Portal that
                searches for data in one or more content servers. Federated search classes
                are specific implementations of dkDatastore , dkDatastoreDe f, and other
                related classes that support federated searches. The specific federated
                classes work together with other common classes, such as query, collections,
                and data object classes, and they are part of the EIP framework.

                There several ways you can run a federated search. You can create a
                federated query string and pass it to a federated query object,
                DKFederatedQuery, and then invoke the execute or evaluate method on that
                object to trigger the query processing.

                Alternatively, you can pass the query string to the execute or evaluate method
                in the EIP database to process the query directly. The query string is parsed
                into a federated query canonical form, which is essentially a datastore neutral
                representation of the query.

                Each datastore runs a query after it has been submitted. Results are returned
                to the federated query results processor module, which can do the following:
                  • Convert native entities an attributes into federated entities and attributes
                    according to the mapping information.
                  • Filter the results to include only the requested data.
                  • Merge the results from several content servers into a federated collection.

                The end result is a federated collection. The user can create a federated
                iterator to iterate over the collection members. Each call to the next method in
                the federated iterator returns a DKDDO object, which is a datastore neutral
                dynamic data object.

                The federated collection provides the facility to separate the query results
                according to the content server.

                For more details please refer IBM Enterprise Information Portal for
                Multiplatforms, OO and Internet Application Programming Guide, SC26-9838.




146   IBM Enterprise Information Portal - A Primer
5.6.4.3 Connecting to the Federated Datastore
The DKDatastoreFed object represents and manages a connection to the
Federated Datastore. It also provides the transaction support and runs the
server commands. Using the connect function you can specify the EIP
Database name, Login name, and the password to establish a connection
with the Federated Datastore.

5.6.4.4 Establishing a connection
Federated Datastore provides methods for connecting to, and disconnecting
from it. The following example shows how to connect to a EIP federated
database named “cmbdb, using the user ID ccadmin and password
password. Normally, you would create a datastore, connect to it, work with it,
then disconnect from it. For example:
DKDatastoreFed dsFed = new DKDatastoreFed();
dsFed.connect(eipdb,userid,pw,"");
System.out.println("Fed. datastore connected :" + eipdb + " userid : "
+userid);
userName = dsFed.userName();
dsName = dsFed.datastoreName();
System.out.println("user : " + userName + " dsName : " + dsName);
dsFed.disconnect();

5.6.4.5 Connecting and disconnecting in the client side
The following is a Java sample that runs on the client. This sample uses the
EIP Federated Datastore as an example. One thing to consider is the remote
exception. Since the client classes communicate with server classes, some
exceptions may be triggered by network communication errors. Therefore, the
application program needs to catch the remote exception in the client
package also.

Connect using the EIP database name, user ID, and password. You can
connect to the Federated Datastore by creating a DKDatastoreFed object.
This example connects to the EIP database CMBDB using the user ID
CCADMIN and the password PASSWORD, then disconnects from the
Federated Datastore.

import com.ibm.mm.sdk.common.*;
import com.ibm.mm.sdk.client.*;
import java.io.*;
public class TConnectFed implements DKConstantFed
{
// Main method
public static void main(String argv[])
{


                         Chapter 5. Lotus Notes client for content servers using EIP   147
                try {
                DKDatastoreFed dsFed = new DKDatastoreFed();
                dsFed.connect("cmbdb","ccadmin","password","");
                dsFed.disconnect();
                }
                catch (DKException exc) {
                System.out.println("Exception name " + exc.name());
                System.out.println("Exception message " + exc.getMessage());
                exc.printStackTrace();
                }
                catch (java.rmi.RemoteException exc) {
                System.out.println("Exception message " + exc.getMessage());
                exc.printStackTrace();
                }
                }
                }

                5.6.4.6 Using DDOs
                DKDDO can be regarded as a container of attributes. An attribute, also called
                data item, has a name, value, and properties. Each attribute is identified by a
                data ID, which is a number starting from one up to the total number of
                attributes in the DDO. Because the number, name, value, and property of an
                attribute can vary, DKDDO provides flexible mechanisms to represent data
                originating from a variety of datastores and formats.

                For example, items from different index classes in Digital Library and
                VisualInfo, or rows from different tables in a relational database. In Digital
                Library and VisualInfo, a DDO represents an item, which could be a
                document or a folder. The DKDDO itself can have properties that apply to the
                whole DKDDO, instead of to only one particular attribute.

                You need to associate a DKDDO with a datastore to be able to call the add,
                retrieve, update and delete methods to send its attributes into the datastore
                and retrieve them. This is done by calling the proper DKDDO constructor or
                by calling setDatastore method.

                Persistent object identifier (PID)
                Each DDO must have a persistent object identifier (PID). It contains
                information about the datastore name, datastore type, ID, and object type.
                The ID identifies the location of the DDO’s persistent data in the datastore.
                For example, in a Digital Library and VisualInfo datastore, this ID is the item
                ID. The item ID is one of the most important parameters for the retrieve,
                update, and delete methods.




148   IBM Enterprise Information Portal - A Primer
            5.6.4.7 Federated query syntax
            The syntax of federated query syntax is similar to a Digital Library and
            VisualInfo parametric query syntax.
            PARAMETRIC_SEARCH=([ENTITY=entity_name,]
            [MAX_RESULTS=maximum_results,][COND=(conditional_expression)][; ...]);
            [OPTION=([CONTENT=yes_no])]

            [and
            TEXT_SEARCH=(COND=(text_search_expression));
            [OPTION=([SEARCH_INDEX={search_index_name | (index_list) };]
            [MAX_RESULTS=maximum_results;] [TIME_LIMIT=time_limit])]]

            [and
            IMAGE_SEARCH=(COND=(image_search_expression));
            [OPTION=([SEARCH_INDEX={search_index_name | (index_list) };]
            [MAX_RESULTS=maximum_results;][TIME_LIMIT=time_limit])]]

            5.6.4.8 Catching exceptions
            A DKException, once caught, allows you to see any error messages, error
            codes, and error states that occurred while running. If an error is caught
            below the DKException name, an error is issued along with the location of
            where the exception was thrown. The error ID and exception ID are also
            given.
            try {
            DKDatastoreFed dsFed = new DKDatastoreFed();
            dsFed.connect("cmbdb","ccadmin","password","");
            dsFed.disconnect();
            }


5.6.5 Creating the Java Agents
            When you use the EIP Federated Java APIs in your Java class file, your class
            should implement the DKConstantFed so that the APIs can use the constants
            defined for Federated Datastore.

            The procedures for creating the Java Agents are described in:
             • Creating the “Creating the FSLogin Agent” on page 150
             • Creating the “Creating the FSGetFedEntity Agent” on page 155
             • Creating the “Creating the FSSearch Agent” on page 158




                                      Chapter 5. Lotus Notes client for content servers using EIP   149
                  5.6.5.1 Creating the FSLogin Agent
                  To create the FSLogin agent:
                  1. In the Designer client select Create - Agent (see Figure 64)




Figure 64. Designing the FSLogin Agent

                  2. Specify FSLogin as the name of the agent.
                  3. Select Manually from agent List so that the agent will be hidden to the
                     users.
                  4. Select Run once in the Which documents should it act option.
                  5. Select Imported Java from the Run option, since we will be compiling our
                     code externally.
                  6. Click on Import Class Files to get the Define Java agent files dialog box
                     (see Figure 65).




150     IBM Enterprise Information Portal - A Primer
                   7. Select the base directory and select the Login.class and the necessary .jar
                      files, and add it to the current list.
                   8. Select the Login.class as the Base class and reorder the files so that it will
                      be in the order of execution.
                   9. Click OK.
                   10.Click File - Save.




Figure 65. Defining the Java agent files

                   The Login.java described
                   The main functionality of the Login class is to Login into the Federated
                   Datastore using the user supplied name, password and database name and
                   get all the available federated entities defined in the Federated Datastore.
                   Also, it informs the Notes environment about the status of the login process
                   and passing the federated entity list to the Notes environment.




                                             Chapter 5. Lotus Notes client for content servers using EIP   151
                The API packages
                The Login.java file imports the following packages to enable your program to
                access the EIP and Notes Java APIs.
                import com.ibm.mm.sdk.common.*;
                import com.ibm.mm.sdk.client.*;
                import lotus.domino.*;


                We are importing the com.ibm.mm.sdk.client package, since we are running
                our application in the client side. If you run your application in the server or
                standalone configuration, you should import com.ibm.mm.sdk.server
                package. For both client and server, you should import the
                com.ibm.mm.sdk.common package.

                Login class: extending AgentBase
                Remember, your class should extend the AgentBase class, so that it can run
                through the Notes agent. Also, the class should implement the
                DKConstantFed interface. Finally, it should have a NotesMain function which
                is a public interface.
                public class Login extends AgentBase implements DKConstantFed
                {
                  public void NotesMain(){ ......} }


                Accessing the Notes session from the Java code
                You can access the current Notes session in Java code, using the getSession
                function. This will write a handle to the current Notes session through which
                you can access its properties.
                Session JNsess = getSession();

                Accessing the current user’s profile
                The getProfileDocument function of the Database class provides you the
                access to the current user’s profile. The Database handle can be retrieved
                from the AgentContext. The getAgentContext function of the Session returns
                the handle of the AgentContext.
                ‘Accessing the User’s profile
                AgentContext ac = JNsess.getAgentContext();
                Database db = ac.getCurrentDatabase();

                Document pdoc= db.getProfileDocument("$UserProfile",JNsess.getUserName());




152   IBM Enterprise Information Portal - A Primer
Connecting to the Federated Datastore
To connect to the Federated Datastore, we create a DKDatastoreFed object,
and using the data entered by the user, we try to login to the Federated
Datastore.
DKDatastoreFed dsFed = new DKDatastoreFed();
// Connect to the Federated Datastore [LOGIN]
dsFed.connect( pdoc.getItemValueString("Login_Database"),
pdoc.getItemValueString("Login_Name"),pdoc.getItemValueString("Login_Passw
ord"), "");

The getItemValueString function of the Document class will retrieve the value
stored in the specified field. In this case, the Login name, password, and the
database name are retrieved from the user profile and are passed as
parameters to the connect function.

If the supplied values are incorrect, the connect function will bring up an
exception of which you can make use.

Listing all the federated entities defined in the datastore
By calling the method listEntityNames() from the DKDatastoreFed object, you
will get all existing federated entities defined in the Federated Datastore. This
method returns you an array of strings. You can form a string list out of this
array and pass it to the Notes.
// Get all the available Federated Entities
String entNames[] = dsFed.listEntityNames();
for (short i = 0; i < entNames.length; i++)
FEList += ";" + entNames[i];

Disconnecting from the datastore
To disconnect from the Federated Datastore, use the disconnect() function of
the DKDatastoreFed object.
// Disconnect from the Federated Datastore
dsFed.disconnect();

Passing the values to the Notes environment
To pass the entitylist and the Login status, we use the environment variables
to pass the values to Notes.

Note: You can also directly update the current user profile from Java. This is
to demonstrate the various ways to pass parameters to the Notes.
JNsess.setEnvironmentVar("FEList", FEList);
JNsess.setEnvironmentVar("LoginFlag", "1");




                          Chapter 5. Lotus Notes client for content servers using EIP   153
                Full source code of Login.java
                import com.ibm.mm.sdk.common.*;
                import com.ibm.mm.sdk.client.*;

                import java.io.*;
                import lotus.domino.*;

                public class Login extends AgentBase implements DKConstantFed
                {
                  public void NotesMain()
                  {
                    try
                    {
                        Session JNsess = getSession();
                AgentContext ac = JNsess.getAgentContext();
                        Database db = ac.getCurrentDatabase();

                // Set Default Value for LoginFlag
                JNsess.setEnvironmentVar("LoginFlag", "");

                Document pdoc =
                db.getProfileDocument("$UserProfile",JNsess.getUserName());
                String FEList = "";

                try
                {
                // Create federated datastore instance
                DKDatastoreFed dsFed = new DKDatastoreFed();

                // Connect to the Federated Datastore [LOGIN]
                dsFed.connect( pdoc.getItemValueString("Login_Database"),
                pdoc.getItemValueString("Login_Name"),pdoc.getItemValueString("Login_Passw
                ord"), "");

                // Get all the available Federated Entities
                String entNames[] = dsFed.listEntityNames();
                for (short i = 0; i < entNames.length; i++)
                FEList += ";" + entNames[i];

                // Disconnect from the Federated Datastore
                dsFed.disconnect();
                JNsess.setEnvironmentVar("FEList", FEList);
                JNsess.setEnvironmentVar("LoginFlag", "1");
                }
                catch (DKException exc)
                {
                System.out.println(": Exception name : " + exc.name());


154   IBM Enterprise Information Portal - A Primer
System.out.println(": Exception message : " + exc.getMessage());
exc.printStackTrace();
}
catch (Exception exc)
{
System.out.println(": Exception message : " + exc.getMessage());
exc.printStackTrace();
}
}
catch (Exception e)
{
e.printStackTrace();
}
}
}

5.6.5.2 Creating the FSGetFedEntity Agent
To create the FSGetFedEntity agent:
1. In the Designer client select Create-Agent.
2. Specify FSGetFedEntity as the name of the agent.
3. Select Manually from agent List so that the agent will be hidden to the
   users.
4. Select Run once in the Which documents should it act option.
5. Select Imported Java from the Run option, since we will be compiling our
   code externally.
6. Click on Import Class Files to get the Define Java agent files dialog
   box.
7. Select the base directory and select the GetFedEntity.class and the
   necessary .jar files, and add it to the current list.
8. Select the GetFedEntity.class as the Base class and reorder the files so
   that it will be in the order of execution.
9. Click OK.
10.Click File-Save.

The GetFedEntity.java described
The main functionality of the GetFedEntity class is to Login into the federated
datastore using the user supplied name, password, and database name and
get all the federated attributes for the selected federated entity defined in the
Federated Datastore. Also, it passes the Attribute list to the Notes
environment.



                          Chapter 5. Lotus Notes client for content servers using EIP   155
                The API packages
                The GetFedEntity.java file imports the following packages to enable your
                program to access the EIP and Notes Java APIs.
                import com.ibm.mm.sdk.common.*;
                import com.ibm.mm.sdk.client.*;
                import lotus.domino.*;


                GetFedEntity class: extending AgentBase
                The GetFedEntity class extends the AgentBase class, so that it can run
                through the Notes agent. Also the class implements the DKConstantFed
                interface.
                public class GetFedEntity extends AgentBase implements DKConstantFed
                {
                  public void NotesMain(){ ..... } }

                Retrieving the selected federated entity from Lotus Notes
                The getProfileDocument() function of the Database class provides the access
                to the current user’s profile. The Database handle can be retrieved from the
                AgentContext . The getAgentContext function of the Session returns the
                handle of the AgentContext .
                ‘Accessing the User’s profile
                Session JNsess = getSession();
                AgentContext ac = JNsess.getAgentContext();
                Database db = ac.getCurrentDatabase();

                Document pdoc= db.getProfileDocument("$UserProfile",JNsess.getUserName());
                String FedEntity = pdoc.getItemValueString("FederatedEntity");

                The getItemValueString function of the Document class retrieves the value
                stored in the specified field. In this case, it retrieves the value stored in the
                FederatedEntity field of the user profile and stores it in a string.

                Listing all the federated attributes of the selected federated entity
                By calling the method listEntityAttrNames() from the DKDatastoreFed object,
                you will get all the federated attributes of the given federated entity. This
                method returns you an array of strings. You can form a string list out of this
                array and pass it to the Notes.
                // Get all attributes of the selected Search Template
                if (FedEntity != null)
                {
                        // Get all the available Federated Entities
                        String entAtts[] = dsFed.listEntityAttrNames(FedEntity);
                        for (short i = 0; i < entAtts.length; i++)



156   IBM Enterprise Information Portal - A Primer
              AttnameString += ";" + entAtts[i];
}

Disconnecting from the datastore
To disconnect from the Federated Datastore, use the disconnect() function of
the DKDatastoreFed object.
// Disconnect from the Federated Datastore
dsFed.disconnect();

Passing the values to the Notes environment
To pass the entity attribute list, we will use the environmental variables to
pass the values to the Notes.
JNsess.setEnvironmentVar("SCName", AttnameString);

Full source code of GetFedEntity.java
import com.ibm.mm.sdk.common.*;
import com.ibm.mm.sdk.client.*;

import java.io.*;
import lotus.domino.*;

public class GetFedEntity extends AgentBase implements DKConstantFed
{
  public void NotesMain()
  {
    try
    {
        Session JNsess = getSession();
AgentContext ac = JNsess.getAgentContext();
        Database db = ac.getCurrentDatabase();

Document pdoc =
db.getProfileDocument("$UserProfile",JNsess.getUserName());

String FedEntity = pdoc.getItemValueString("FederatedEntity");
String AttnameString = "";
String AttoperString = "";

try
{
// Create federated datastore instance
DKDatastoreFed dsFed = new DKDatastoreFed();

// Connect to the Federated Datastore




                          Chapter 5. Lotus Notes client for content servers using EIP   157
                dsFed.connect( pdoc.getItemValueString("Login_Database"),
                pdoc.getItemValueString("Login_Name"),pdoc.getItemValueString("Login_Passw
                ord"), "");

                // Get all attributes of the selected Search Template
                if (FedEntity != null)
                {
                // Get all the available Federated Entities
                String entAtts[] = dsFed.listEntityAttrNames(FedEntity);
                for (short i = 0; i < entAtts.length; i++)
                {
                AttnameString += ";" + entAtts[i];
                AttoperString += ";==#<>#LIKE#NOT LIKE#IN#NOT IN#>#<";
                }

                }
                // Disconnect from the Federated Datastore
                dsFed.disconnect();
                JNsess.setEnvironmentVar("SCName", AttnameString);
                JNsess.setEnvironmentVar("SCOper", AttoperString);
                }
                catch (DKException exc)
                {
                System.out.println(": Exception name : " + exc.name());
                System.out.println(": Exception message : " + exc.getMessage());
                exc.printStackTrace();
                }
                catch (Exception exc)
                {
                System.out.println(": Exception message : " + exc.getMessage());
                exc.printStackTrace();
                }
                }
                catch (Exception e)
                {
                e.printStackTrace();
                }
                }
                }

                5.6.5.3 Creating the FSSearch Agent
                To create the FSSearch agent:
                1. In the Designer client, select Create-Agent.
                2. Specify FSSearch as the name of the agent.




158   IBM Enterprise Information Portal - A Primer
3. Select Manually from agent List so that the agent will be hidden to the
   users.
4. Select Run once in the Which documents should it act option.
5. Select Imported Java from the Run option, since we will be compiling our
   code externally.
6. Click on Import Class Files to get the Define Java agent files dialog
   box.
7. Select the base directory and select the FedSearch.class and the
   necessary .jar files and add it to the current list.
   Note: If you are searching in different content servers, you should also
   add their respective client .jar files in order to run the code. For example, if
   you are searching in Digital Library and in OnDemand, you should add
   both cmbdlc30.jar and cmbodc30.jar files into the Notes agent.
8. Select the FedSearch.class as the Base class and reorder the files so that
   it will be in the order of execution.
9. Click OK.
10.Click File-Save.

The FedSearch.java described
The main functionality of the FedSearch class is to Login to the Federated
Datastore using the user supplied name, password and database name, and
using the Search expression composed by the user, issue a federated search
on all defined content servers and get the result back to the Notes
environment. The result set is passed to Lotus Notes as a set of documents
with all the field names and values.

The API packages
The FedSearch.java file imports the following packages to enable your
program to access the EIP and Notes Java APIs.
import com.ibm.mm.sdk.common.*;
import com.ibm.mm.sdk.client.*;
import lotus.domino.*;


FedSearch class: extending AgentBase
Since we are running the FedSearch.class through an agent, the FedSearch
class should extend the AgentBase class. Also, the class implements the
DKConstantFed interface.
public class FedSearch extends AgentBase implements DKConstantFed
{



                           Chapter 5. Lotus Notes client for content servers using EIP   159
                   public void NotesMain(){ ..... } }

                To get the federated entity and search expression from Lotus Notes
                The getProfileDocument() function of the Database class provides the access
                to the current user’s profile. The database handle can be retrieved from the
                AgentContext. The getAgentContext function of the Session returns the
                handle of the AgentContext.
                ‘Accessing the User’s profile
                Session JNsess = getSession();
                AgentContext ac = JNsess.getAgentContext();
                Database db = ac.getCurrentDatabase();

                Document pdoc= db.getProfileDocument("$UserProfile",JNsess.getUserName());

                String FedEntity = pdoc.getItemValueString("FederatedEntity");
                String QueryString = pdoc.getItemValueString("QueryString");

                The getItemValueString function of the Document class retrieves the value
                stored in the specified field. In this case, it retrieves the value stored in the
                Federated Entity and the Search Criteria composed by the user from the user
                profile and stores it in the respective strings.

                Creating the federated query string
                Now we should create the Federated query from the user composed
                expression, which is passed as a parameter to the execute function of the
                DKDatastoreFed object. We use the FedEntity as well as the QueryString for
                this purpose.
                // Create the Federated query string
                FedQueryString = "PARAMETRIC_SEARCH = (ENTITY = " + FedEntity + ",
                MAX_RESULTS = 50,";
                FedQueryString += "COND = (" + QueryString + ")); OPTION = (CONTENT =
                ATTRONLY)";

                Executing the query
                We will use the execute() function of the DKDatastoreFed object to execute
                the Federated query. This function will return a result set cursor.
                // Execute the query
                dkResultSetCursor rsc =
                dsFed.execute(FedQueryString,DK_CM_FEDERATED_QL_TYPE, null);

                hitCount = rsc.cardinality();

                The cardinality() function of the result set cursor returns the number of search
                results.



160   IBM Enterprise Information Portal - A Primer
Passing the search result to the Notes environment
We use the DKDDO object to retrieve each result, and then pass all the
values by creating a new Notes document and dumping all the contents of the
DKDDO object into it.
// Create the DKDDO object
DKDDO ddo;
while (rsc.isValid() && !(rsc.isEnd()))
{
ddo = rsc.fetchNext();
if (ddo != null)
CreateSearchResult(ddo,db);
}

We are passing the DKDDO object and the database object to the function
CreateSearchResult . In the CreateSearchResult function we will create a new
Notes document and fields for every DKDDO data item and its value.
Object a = null;
if (ddo != null)
{
Document doc = db.createDocument(); // Create the Notes document
doc.appendItemValue("Form", "$SearchResult");
for (short i = 1; i <= ddo.dataCount(); i++)
{
a = ddo.getData(i);
// Populate the Fields
doc.appendItemValue("Field"+i+"0", ddo.getDataName(i));
if (a != null)
doc.appendItemValue("Field"+i+"1", a.toString());
}
doc.appendItemValue("ItemId", ddo.getPid().pidString());
doc.save(); // Save the Notes Document
}

Disconnecting from the datastore
To disconnect from the Federated Datastore, use the disconnect() function of
the DKDatastoreFed object.
// Disconnect from the Federated Datastore
dsFed.disconnect();

Passing the values to the Notes environment
To pass the search hit count, we will use the environmental variables to pass
the values to the Notes.
// Since hitCount is a integer you should convert it into a string
JNsess.setEnvironmentVar("SHitCount", String.valueOf(hitCount));



                         Chapter 5. Lotus Notes client for content servers using EIP   161
                Full source code of FedSearch.java
                import com.ibm.mm.sdk.common.*;
                import com.ibm.mm.sdk.client.*;

                import java.io.*;
                import lotus.domino.*;

                public class FedSearch extends AgentBase implements DKConstantFed
                {
                  public void NotesMain()
                  {
                    try
                    {
                        Session JNsess = getSession();
                AgentContext ac = JNsess.getAgentContext();
                        Database db = ac.getCurrentDatabase();

                Document pdoc =
                db.getProfileDocument("$UserProfile",JNsess.getUserName());

                String FedEntity = pdoc.getItemValueString("FederatedEntity");
                String QueryString = pdoc.getItemValueString("QueryString");
                String FedQueryString = "";
                int hitCount = 0;

                try
                {
                // Create federated datastore instance
                DKDatastoreFed dsFed = new DKDatastoreFed();

                // Connect to the Federated Datastore
                dsFed.connect( pdoc.getItemValueString("Login_Database"),
                pdoc.getItemValueString("Login_Name"),pdoc.getItemValueString("Login_Passw
                ord"), "");

                if (FedEntity != null && QueryString != null)
                {

                // Formulate the query string
                FedQueryString = "PARAMETRIC_SEARCH = (ENTITY = " + FedEntity + ",
                MAX_RESULTS = 50,";
                FedQueryString += "COND = (" + QueryString + ")); OPTION = (CONTENT =
                ATTRONLY)";

                // Execute the query
                dkResultSetCursor rsc = dsFed.execute(FedQueryString,
                DK_CM_FEDERATED_QL_TYPE, null);


162   IBM Enterprise Information Portal - A Primer
// Get the result set cursor
if (rsc == null)
hitCount = 0;
else
{
hitCount = rsc.cardinality();
DKDDO ddo;

while (rsc.isValid() && !(rsc.isEnd()))
{
ddo = rsc.fetchNext();
if (ddo != null)
CreateSearchResult(ddo,db);
}
}
}
// Disconnect from the Federated Datastore
dsFed.disconnect();
JNsess.setEnvironmentVar("SHitCount", String.valueOf(hitCount));
}
catch (DKException exc)
{
JNsess.setEnvironmentVar("Error : @ : ", exc.name() + " # " +
exc.getMessage());
System.out.println(": Exception name : " + exc.name());
System.out.println(": Exception message : " + exc.getMessage());
exc.printStackTrace();
}
catch (Exception exc)
{
JNsess.setEnvironmentVar("Error : @ : ", exc.getMessage());
System.out.println(": Exception message : " + exc.getMessage());
exc.printStackTrace();
}
}
catch (Exception e)
{
e.printStackTrace();
}
}

public static void CreateSearchResult(DKDDO ddo,Database db) throws
DKException, Exception
{
Object a = null;
if (ddo != null)


                        Chapter 5. Lotus Notes client for content servers using EIP   163
                {
                Document doc = db.createDocument(); // Create the Notes document
                doc.appendItemValue("Form", "$SearchResult");

                for (short i = 1; i <= ddo.dataCount(); i++)
                {
                a = ddo.getData(i);

                // Populate the Fields
                doc.appendItemValue("Field"+i+"0", ddo.getDataName(i));
                if (a != null)
                doc.appendItemValue("Field"+i+"1", a.toString());
                }
                doc.appendItemValue("ItemId", ddo.getPid().pidString());
                doc.save(); // Save the Notes Document
                }
                }
                }


5.6.6 Placing the components in a frameset
                Lotus Domino Designer Release 5 allows you to define frames and framesets
                in the client environment.

                A frameset is a collection of frames and can add structure to your Web site or
                Notes database. A frame is one section, or pane, of the larger frameset
                window and is independently scrollable.

                A frame can contain a form, folder, page, document, view, navigator, or
                frameset. The frame can also contain a Web page and is associated with a
                specific URL. Framesets let you create links and relationships between
                frames. For example, you can leave one page displayed, as users scroll or
                link to other pages or databases.

                Designers can set a frameset to launch automatically when a database, form,
                or page opens.

                Placing the elements in a frameset:
                1. Open Designer and choose Create - Design - Frameset. The Create New
                   Frameset dialog box appears.
                2. At the Number of frames drop-down box, select 4 frames. You can make
                   adjustments later.
                3. Select the First arrangement option.
                4. The frameset with the chosen layout appears (see Figure 66).



164   IBM Enterprise Information Portal - A Primer
Figure 66. Designing a frameset

                  Adding content to each frame (see Figure 67 ):




                  Figure 67. Defining the content for a frame




                                                 Chapter 5. Lotus Notes client for content servers using EIP   165
                1. Select a frame in the frameset.
                2. Choose Frame - Frame Properties. The Frame Properties box appears.
                3. At the Basics tab, provide a name for the frame.
                4. Choose, Named element in the Type field.
                5. Choose the type of Named element: for example, Form.
                6. Specify the name of the Named element in the value field.

                Specifying the database launch option
                To specify the database launch option, see Figure 68.




                Figure 68. Database launch option

                1. From the Designer client, select the Database.
                2. Select File-Database-Properties.
                3. Select the Launch Tab.
                4. Select Open designated Frameset in Launch option.
                5. Select the name of the Frameset in the Name field.




166   IBM Enterprise Information Portal - A Primer
Appendix A. Environment: hardware and software configurations

                  In this appendix we provide details on hardware and software configurations.


A.1 NT servers:
                  Hardware:
                    •   Pentium II processor - 300PL
                    •   128 MB memory
                    •   5 GB hard drive, divided into two partitions, both formatted NTFS
                    •   10/100 Mbps Ethernet PCI Adapter

                  Software:
                    •   Windows NT V4.0 Server w/ Service Pack 5
                    •   Internet Explorer V4.0
                    •   Microsoft Web and FTP Server from Option Pack
                    •   VideoCharger V2.0, plus Service Level 4


A.2 AIX servers
                  Hardware:
                    •   430 Model 260
                    •   Multiple Processor, PCI bus
                    •   2 SCSI disk drives, 9 GB each
                    •   500 MB memory
                    •   L2 cache
                    •   One Controller- Wide/Fast-20 SCSI
                    •   10/100 Mbps Ethernet PCI Adapter
                    •   Token Ring Adapter

                  Software
                    •   AIX V4.3.2
                    •   Java Runtime Environment V1.1.6.4
                    •   Netscape Communicator V4.0.8.0
                    •   DCE V2.2.0.2
                    •   Multi Media File Manager V2.2.
                    •   C Set ++ for AIX Application V3.6.4.0




© Copyright IBM Corp. 2000                                                                  167
A.3 Digital library servers
                Hardware:
                  •   Pentium II processor - 300PL
                  •   128 MB memory (second object server has 64 MB memory)
                  •   5 GB hard drive, divided into two logical partitions, both formatted NTFS
                  •   10/100 Mpbs Ethernet PCI Adapter

                Software:
                  •   Windows NT V4.0 Server w/ Service Level 5
                  •   Internet Explorer V4.0
                  •   Microsoft Web and FTP Server (from option pac IIS install)
                  •   War FTP daemon beta 1.70, release 4 (from www.tucows.com)
                  •   Microsoft Visual C++ Compiler V5.0
                  •   IBM UDB V5.2, Enterprise Edition
                  •   Digital Library V2.4, CSD1
                         The library server, object server, system administration client, gateway,
                         and client are installed on one machine.


A.4 Clients
                Hardware:
                  •   Pentium II processor - 300PL
                  •   64 - 128 MB memory
                  •   5 GB hard drive, divided into one or two logical partitions, formatted NTFS
                  •   10/100 Mpbs Ethernet PCI Adapter

                Software:
                  • Windows NT V4.0 Workstation or server with Service Level 5
                  • Internet Explorer V4.0


A.5 Miscellaneous
                Token ring network.




168   IBM Enterprise Information Portal - A Primer
Appendix B. Installing and configuring IBM WebSphere V.2.02

                  IBM WebSphere Application Server lets you achieve your “write once, use
                  anywhere” goal for servlet development. The product consists of a
                  Java-based servlet engine that is independent of your Web server and its
                  underlying operating system. The WebSphere Application Server offers a
                  choice of server plug-ins that are compatible with the most popular server
                  application programming interfaces (APIs). The supported Web servers are:
                    •   IBM HTTP Server
                    •   Apache Server
                    •   Domino
                    •   Lotus Domino Go Webserver
                    •   Netscape Enterprise Server
                    •   Netscape FastTrack Server
                    •   Microsoft Internet Information Server

                  WebSphere also has support for dynamic page content called Java Server
                  Pages (JSP). JSP technology lets you produce dynamic Web pages with
                  server-side scripting. The result is to separate your presentation logic (for
                  example, the HTML code that defines your Web site structure and
                  appearance) from your business logic (for example, the Java code that
                  accesses a database for information to display on the Web site). For flexibility,
                  JSP files can include any combination of inline Java, <SERVLET> tags,
                  NCSA tags, and JavaBeans.


B.1 IBM WebSphere Application Server components
                  The following components comprise IBM WebSphere Application Server.

                  Base servlet engine
                  A Java-based servlet engine to support your “write once, use everywhere”
                  servlet development goal.

                  Web server plug-ins
                  Plug-ins are provided (where applicable) for:
                  IBM HTTP Server V1.3.3
                  Apache Server V1.3.2
                  Domino V5.0 (not available on Solaris)
                  Lotus Domino Go Webserver V4.6.2.5
                  Netscape FastTrack Server V3.01
                  Netscape Enterprise Server V3.01 and V3.51




© Copyright IBM Corp. 2000                                                                     169
                Microsoft Internet Information Server V3.x and V4.0 on AIX, Solaris, and
                           Windows NT

                Note: WebSphere Application Server offers the choice to run as part of the
                Web server (“in process”) or in stand-alone mode (“out of process”), except
                for an Apache server and IBM HTTP Server, which supports only stand-alone
                operation. We recommend that you use stand-alone mode with all Web
                servers.

                Application Server Manager
                An easy-to-use graphical interface for configuring, managing, and monitoring
                servlets running on Application Server.

                Java Server Pages (JSP)
                Dynamic Web pages using server-side scripting and tagging to separate
                presentation logic (such as HTML) from business logic, making it easier to
                develop applications.

                Samples
                Sample servlets and Web site applications demonstrating both simple and
                advanced techniques

                Documentation
                On-line and printable documentation to get you started quickly and help you
                master the use of advanced server features.


B.2 Preparing to install the IBM WebSphere Application Server
                This section discusses the memory and software requirements, as well as
                additional tasks to complete before installing the application server.

B.2.1 Prerequisites for IBM WebSphere installation on Windows NT
                  • Memory and disk space requirements
                      - A minimum of 128 MB RAM, however 256 MB is recommended. The
                        Application Server installation CD includes Application Server, IBM
                        HTTP Server, and a Java Development Kit (JDK).
                  • Operating system
                      - Microsoft NT V4.0 with Service Pack 3
                  • Web server
                      - Application Server requires one of these servers:




170   IBM Enterprise Information Portal - A Primer
                    • IBM HTTP Server V1.3.3 for Windows NT (available during
                      Application Server install)
                    • Apache Server V1.3.2 for Windows NT
                - Domino V5.0 for Windows NT
                - Lotus Domino Go Webserver V4.6.2.5 for Windows NT
                - Microsoft Internet Information Server V3.x and V4.0 for Windows NT
                - Netscape Enterprise Server V3.01 and V3.51 for Windows NT
                  (recommend V3.5.1)
             • Netscape FastTrack Server V3.01 for Windows NT
             • Java Development Kit (JDK)
                - JDK 1.1.6 ships with Application Server and is recommended.
             • Java servlet API
                - Application Server includes the JSDK V2.0 or higher .class files, which
                  you will need if you want to develop servlets.
             • Web browser
               The Application Server Manager is the user interface for managing
               servlets. To run the Manager, you need an applet viewer or a browser that
               supports JDK1.1, for example:
                - Netscape Navigator 4.06 or 4.0.7, which include integrated JDK 1.1
                  support
                - Microsoft Internet Explorer 4.01 with the fix pack, or higher
                - Sun HotJava 1.1 or higher

B.2.2 Additional tasks to complete before installation
            Before installing the IBM WebSphere, you should backup all your files (from
            your previous application server installation, if you have installed any) that are
            not backed up by the installation program automatically.

            You should have installed the Web server you plan to use. The Web server
            must be installed prior to installing the Application Server. You should stop
            the Web server if it is running before the installation.

            Note that during the Application Server installation, if you specify to use IBM
            HTTP Server or Apache Server, you are prompted to confirm the location of
            the Web server httpd.conf file.




                                    Appendix B. Installing and configuring IBM WebSphere V.2.02   171
                If you have information in your CLASSPATH from a previous version of
                Application Server, delete the information before installing this version.
                Otherwise, you may encounter a version mismatch message and be unable to
                view your new Application Server administrative interface, the IBM
                WebSphere Application Server Manager.


B.3 Installing the IBM WebSphere Application Server on Windows NT
                1. Insert the Application Server installation CD.
                2. Go to the subdirectory named for the Windows NT operating system.
                3. Run the setup executable (setup.exe) see Figure 69.




                Figure 69. Application server components

                4. Select the necessary application server components from the prompted
                   dialog box.
                5. In the next dialog box, you should select the Java Development Kit or the
                   Runtime environment from the list. You can also specify the JDK/JRE path
                   if it is not listed.



172   IBM Enterprise Information Portal - A Primer
            6. Next the installation procedure will prompt you with the Application server
               plug-ins dialog box (see Figure 70). Choose whichever plug-ins you want
               to install.




            Figure 70. Application server plug-ins

            7. Now the installation program will install all the selected components and
               the application files in the specified installation directory.


B.4 Starting and stopping Application Server
            In this section we discss Starting and stopping Application Server.

B.4.1 Starting the server
            The server starts automatically when you start your Web server. The
            Application Server Manager, which you use a Web browser to access,
            provides an interface for viewing and changing Application Server settings
            and performance.




                                        Appendix B. Installing and configuring IBM WebSphere V.2.02   173
B.4.2 Stopping the server
                If running Application Server as part of the Web server, Application Server
                stops automatically when you shut down your Web server.

                If running in stand alone mode, Application Server does not shut down
                automatically. Remember that the Application Server must run out of process
                with the Apache Server or IBM HTTP Server. By default, it runs out of process
                with any Web server, and this is recommended.

                When running Application Server out of process on Windows NT, after
                shutting down the Web server, shut down the WebSphere Servlet Service to
                stop Application Server. Select the WebSphere Servlet Service from
                Start—>Settings —> Control Panel —> Services and push the Stop button.


B.5 Customizing configuration settings
                This section describes how to start and use the Application Server Manager,
                a graphical interface, to customize the basic setup parameters for servlet
                activity and Application Server components.

B.5.1 Starting the Application Server Manager
                To start the Application Server Manager, enter this URL from your Web
                browser:
                http://your.server.name:9527/

                Where your.server.name is the fully qualified name of your host.

                Note: If you start the Application Server Manager in a browser on the same
                machine on which you installed Application Server, use:
                http://localhost:9527/

                for better performance.

                The Manager starts and displays the login page.

                To log in to the Manager for the first time, use admin as the login user ID and
                password. Click OK. To run the Manager, you need an applet viewer or
                browser that supports Java Development Kit (JDK) 1.1.6.




174   IBM Enterprise Information Portal - A Primer
B.5.2 Using the Application Server Manager
           The navigation area on the left-hand side of the Application Server Manager
           enables you to:
            •   Customize settings for a variety of Application Server components
            •   Configure servlets and set up aliasing and filtering
            •   Establish and maintain security
            •   Collect and monitor Application Server, connection, and servlet data

           B.5.2.1 Customizing basic properties
           Before using Application Server to manage servlets, configure basic setup
           parameters for servlet activity and the properties of the Application Server
           components. In the Manager navigation area, click Setup to display pages for
           a variety of items whose settings you can customize:

           Administration page:
           Change the user ID and password for logging in to the Manager, and specify
           a new port number for the Manager

           Connection Management page:
           Set up connection pools for reducing resources spent on maintaining
           connections to data servers, such as IBM DB2 relational databases

           Directory Management page:
           Specify settings for a directory server, which lets you manage security data
           from a location central to your Web server, operating system, Application
           Server, and other software products

           Java Engine page:
           Specify Java compiler settings and indicate whether to run Application Server
           as part of the Web server for faster performance, or in stand alone mode for
           greater security

           Session Tracking page:
           Specify settings for maintaining state information about user sessions (series
           of related user requests from the same browser)

           User Profile page:
           Specify settings for maintaining persistent information about your Web site
           visitors




                                   Appendix B. Installing and configuring IBM WebSphere V.2.02   175
                . Virtual Hosts page:
                Specify alternate paths for servlets, allowing your Web server to serve
                different documents depending on the domain specified by the client during a
                servlet request

B.5.3 Configuring servlets, aliases, and filtering
                Servlets placed in the <as_root>\servlets directory are automatically loaded
                and reloaded (if updated) when requested. You can also use the WebSphere
                Application Server Manager to manage servlets more directly by defining
                initialization parameters and creating servlet aliases and filters.

                To manage servlets, click Servlets in the Manager navigation area and
                choose a page:

                . Configuration page:
                Define configuration information and initialization parameters for individual
                servlets, such as the associated class file, whether the servlet loads at
                startup, and whether the Web server loads the servlet from a remote location.
                You can also register new servlets by clicking on the Add button.

                . Aliases page:
                Specify a path-mapping rule allowing users to enter a shortcut URL to invoke
                a specific servlet.

                . Filtering page:
                Associate servlets with MIME-types so that each time a response with a
                specific MIME-type is generated, a particular servlet is invoked.

B.5.4 Logging off
                To log off instantly, click Log Off in the Manager navigation area, returning to
                the Manager login screen.




176   IBM Enterprise Information Portal - A Primer
Appendix C. Special notices

                  This publication is intended to help professionals to install, configure, and test
                  the IBM Enterprise Information Portal product. The information in this
                  publication is not intended as the specification of any programming interfaces
                  that are provided by the IBM Enterprise Information Portal product set. See
                  the PUBLICATIONS section of the IBM Programming Announcement for the
                  IBM Enterprise Information Portal Version 6.1 for more information about
                  what publications are considered to be product documentation.

                  References in this publication to IBM products, programs or services do not
                  imply that IBM intends to make these available in all countries in which IBM
                  operates. Any reference to an IBM product, program, or service is not
                  intended to state or imply that only IBM's product, program, or service may be
                  used. Any functionally equivalent program that does not infringe any of IBM's
                  intellectual property rights may be used instead of the IBM product, program
                  or service.

                  Information in this book was developed in conjunction with use of the
                  equipment specified, and is limited in application to those specific hardware
                  and software products and levels.

                  IBM may have patents or pending patent applications covering subject matter
                  in this document. The furnishing of this document does not give you any
                  license to these patents. You can send license inquiries, in writing, to the IBM
                  Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY
                  10504-1785.

                  Licensees of this program who wish to have information about it for the
                  purpose of enabling: (i) the exchange of information between independently
                  created programs and other programs (including this one) and (ii) the mutual
                  use of the information which has been exchanged, should contact IBM
                  Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA.

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

                  The information contained in this document has not been submitted to any
                  formal IBM test and is distributed AS IS. The use of this information or the
                  implementation of any of these techniques is a customer responsibility and
                  depends on the customer's ability to evaluate and integrate them into the
                  customer's operational environment. While each item may have been
                  reviewed by IBM for accuracy in a specific situation, there is no guarantee
                  that the same or similar results will be obtained elsewhere. Customers


© Copyright IBM Corp. 2000                                                                      177
                attempting to adapt these techniques to their own environments do so at their
                own risk.

                Any pointers in this publication to external Web sites are provided for
                convenience only and do not in any manner serve as an endorsement of
                these Web sites.

                The following terms are trademarks of the International Business Machines
                Corporation in the United States and/or other countries:
                IBM  â                                 Redbooks
                AIX                                    Redbooks Logo
                AS/400                                 RS/6000
                CICS                                   SP
                DB2                                    S/390
                DB2 Universal Database                 VideoCharger
                EDMSuite                               VisualAge
                ImagePlus                              VisualInfo
                MVS/ESA                                WebSphere
                Net.Data                               Lotus
                Netfinity                              Lotus Notes
                OS/390
                PC 300
                QBIC

                The following terms are trademarks of other companies:

                Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything.
                Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet
                Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli
                Systems Inc., an IBM company, in the United States, other countries, or both.
                In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli
                A/S.

                C-bus is a trademark of Corollary, Inc. in the United States and/or other
                countries.

                Java and all Java-based trademarks and logos are trademarks or registered
                trademarks of Sun Microsystems, Inc. in the United States and/or other
                countries.

                Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
                Microsoft Corporation in the United States and/or other countries.

                PC Direct is a trademark of Ziff Communications Company in the United
                States and/or other countries and is used by IBM Corporation under license.



178   IBM Enterprise Information Portal - A Primer
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel
Corporation in the United States and/or other countries.

UNIX is a registered trademark in the United States and other countries
licensed exclusively through The Open Group.

SET, SET Secure Electronic Transaction, and the SET Logo are trademarks
owned by SET Secure Electronic Transaction LLC.

Other company, product, and service names may be trademarks or service
marks of others.




                                                Appendix C. Special notices   179
180   IBM Enterprise Information Portal - A Primer
Appendix D. Related publications

                  The publications listed in this section are considered particularly suitable for a
                  more detailed discussion of the topics covered in this redbook.


D.1 IBM Redbooks
                  For information on ordering these ITSO publications see “How to Get IBM
                  Redbooks” on page 183.
                    • Getting Started with Digital Library V1.0, SG24-2243-00
                    • Image and Workflow Library: Capacity Planning and Performance Tuning
                      for VisualInfo and Digital Library Servers, SG24-4974-01
                    • Image and Workflow Library: SmartGuide to EDMSuite System Managed
                      Storage, SG24-5159-00
                    • Java Thin Client Systems: With VisualAge Generator -- In IBM WebSphere
                      Application Server, SG24-5468-00
                    • Developing an e-business Application for the IBM WebSphere Application
                      Server, SG24-5423-00
                    • IBM WebSphere and VisualAge for Java Database Integration with DB2,
                      Oracle, and SQL Server, SG24-5471-00
                    • Linux for WebSphere and DB2 Servers , SG24-5850-00
                    • Getting Started with Data Warehouse and Business Intelligence,
                      SG24-5415-00
                    • WebSphere Application Servers: Standard and Advanced Editions,
                      SG24-5460-00
                    • e-business Application Solutions Using Java: Volume I , SG24-5342-00
                    • Windows NT Backup and Recovery with ADSM, SG24-2231-00
                    • DB2 Meets Windows NT, SG24-4893-00
                    • World Wide Web Access to DB2, SG24-4716-00




© Copyright IBM Corp. 2000                                                                      181
D.2 IBM Redbooks collections
                Redbooks are also available on the following CD-ROMs. Click the CD-ROMs
                button at ibm.com/redbooks for information about all the CD-ROMs offered,
                updates and formats.
                CD-ROM Title                                                       Collection Kit
                                                                                   Number
                IBM System/390 Redbooks Collection                                 SK2T-2177
                IBM Networking Redbooks Collection                                 SK2T-6022
                IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038
                IBM Lotus Redbooks Collection                                      SK2T-8039
                Tivoli Redbooks Collection                                         SK2T-8044
                IBM AS/400 Redbooks Collection                                     SK2T-2849
                IBM Netfinity Hardware and Software Redbooks Collection            SK2T-8046
                IBM RS/6000 Redbooks Collection                                    SK2T-8043
                IBM Application Development Redbooks Collection                    SK2T-8037
                IBM Enterprise Storage and Systems Management Solutions            SK3T-3694



D.3 Referenced Web sites
                This Web site is also relevant as a further information source:
                  • http://java.sun.com/         Sun Java page




182   IBM Enterprise Information Portal - A Primer
How to Get IBM Redbooks

This section explains how both customers and IBM employees can find out about IBM Redbooks,
redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided.
 • Redbooks Web Site ibm.com/redbooks
   Search for, view, download, or order hardcopy/CD-ROM Redbooks from the Redbooks Web site.
   Also read redpieces and download additional materials (code samples or diskette/CD-ROM images)
   from this Redbooks site.
   Redpieces are Redbooks in progress; not all Redbooks become redpieces and sometimes just a few
   chapters will be published this way. The intent is to get the information out much quicker than the
   formal publishing process allows.
 • E-mail Orders
   Send orders by e-mail including information from the IBM Redbooks fax order form to:
                                      e-mail address
   In United States or Canada         pubscan@us.ibm.com
   Outside North America              Contact information is in the “How to Order” section at this site:
                                      http://www.elink.ibmlink.ibm.com/pbl/pbl
 • Telephone Orders
   United States (toll free)          1-800-879-2755
   Canada (toll free)                 1-800-IBM-4YOU
   Outside North America              Country coordinator phone number is in the “How to Order”
                                      section at this site:
                                      http://www.elink.ibmlink.ibm.com/pbl/pbl
 • Fax Orders
   United States (toll free)          1-800-445-9269
   Canada                             1-403-267-4455
   Outside North America              Fax phone number is in the “How to Order” section at this site:
                                      http://www.elink.ibmlink.ibm.com/pbl/pbl

This information was current at the time of publication, but is continually subject to change. The latest
information may be found at the Redbooks Web site.


    IBM Intranet for Employees
 IBM employees may register for information on workshops, residencies, and Redbooks by accessing
 the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button.
 Look in the Materials repository for workshops, presentations, papers, and Web pages developed
 and written by the ITSO technical professionals; click the Additional Materials button. Employees
 may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements.




© Copyright IBM Corp. 2000                                                                            183
IBM Redbooks fax order form

Please send me the following:
Title                                                         Order Number               Quantity




First name                                   Last name


Company


Address


City                                         Postal code               Country


Telephone number                            Telefax number             VAT number


   Invoice to customer number


   Credit card number



Credit card expiration date                  Card issued to            Signature

We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.




184       IBM Enterprise Information Portal - A Primer
Glossary

This glossary defines terms and abbreviations that     associated. In WebSphere Studio, a file that is
are used in this book. If you do not find the term     marked as belonging to a site. Associated files
you are looking for, refer to the IBM Dictionary of    display as non-dimmed icons in the File View.
Computing, New York: McGraw-Hill, 1994.
                                                       attribute. A specification of an element of a class.
                                                       For example, a customer bean could have a name
A                                                      attribute and an address attribute.

abstract class. A class that provides common
behavior across a set of subclasses but is not         B
itself designed to have instances. An abstract
class represents a concept; classes derived from it    base class. A class from which other classes or
represent implementations of the concept. See          beans are derived. A base class may itself be
also base class.                                       derived from another base class. See also
                                                       abstract class.
access modifier. A keyword that controls access
to a class, method, or attribute. The access modifi-   bean. A definition or instance of a JavaBeans
ers in Java are public, private, protected, and        component. See also JavaBeans.
package, the default.
                                                       BeanInfo. (1) A companion class for a bean that
accessor methods. Methods that an object pro-          defines a set of methods that can be accessed to
vides to define the interface to its instance vari-    retrieve information on the bean’s properties,
ables. The accessor method to return the value of      events, and methods. (2) In the VisualAge for
an instance variable is called a get method or get-    Java IDE, a page in the Class Browser that pro-
ter method, and the mutator method to assign a         vides bean information.
value to an instance variable is called a set
method or setter method.                               beans palette. In the Visual Composition Editor, a
                                                       pane that contains beans that you can select and
applet. A Java program designed to run within a        manipulate to create programs. You can add your
Web browser. Contrast with application.                own categories and beans to the beans palette.

application. In Java programming, a self-con-          break point. A point in a computer program where
tained, stand-alone Java program that includes a       the execution will be halted.
main() method. Contrast with applet.
                                                       browser. (1) In VisualAge for Java, a window that
application programming interface (API). A             provides information about program elements.
software interface that enables applications to        There are browsers for projects, packages,
communicate with each other. An API is the set of      classes, methods, and interfaces. (2) An Inter-
programming language constructs or statements          net-based tool that lets user browse Web sites.
that can be coded in an application program to
obtain the specific functions and services provided
by an underlying operating system or service pro-      C
gram.
                                                       category. In the Visual Composition Editor, a
argument. A data element, or value, included as a      selectable grouping of beans on the palette.
parameter in a method call. Arguments provide          Selecting a category displays the beans belonging
additional information that the called method can      to that category. See also beans palette.
use to perform the requested operation.
                                                       child. In WebSphere Studio, a file that is refer-
                                                       enced by another file.




© Copyright IBM Corp. 2000                                                                            185
class. A template that defines properties, opera-         console. In VisualAge for Java, the window that
tions, and behavior for all instances of that tem-        acts as the standard input (System.in) and standard
plate.                                                    output (System.out) device for programs running in
                                                          the VisualAge for Java IDE.
class hierarchy. The relationships among classes
that share a single inheritance. All Java classes         construction from parts. A software development
inherit from the Object class.                            technology in which applications are assembled
                                                          from existing and reusable software components,
class library. A collection of classes.                   known as parts. In VisualAge for Java, parts are
                                                          called beans.
class method. See method.
                                                          constructor. A special class method that has the
CLASSPATH. (1) In VisualAge for Java the lists of         same name as the class and is used to construct
pathnames which will be searched for dynamically          and possibly initialize objects of its class type.
loaded classes, BeanInfo information and external
source for debugging. (2) In your deployment envi-        container. A component that can hold other com-
ronment, the environment variable that specifies the      ponents. In Java, examples of containers include
directories in which to look for class and resource       Applets, Frames, and Dialogs. In the Visual Compo-
files.                                                    sition Editor, containers can be graphically repre-
                                                          sented and generated.
client/server. The model of interaction in distrib-
uted data processing where a program at one loca-         current edition. The edition of a program element
tion sends a request to a program at another              that is currently in the workspace. See also open
location and awaits a response. The requesting            edition.
program is called a client, and the answering pro-
gram is called a server.                                  custom link. In WebSphere Studio, a relationship
                                                          between files that you identify and WebSphere Stu-
Class Browser. In the VisualAge for Java IDE, a           dio does not automatically recognize.
tool used to browse the classes loaded in the work-
space.
                                                          D
component model. An architecture and an API
that allows developers to define reusable segments        DNS. See “domain name server.”
of code that can be combined to create a program.
VisualAge for Java uses the JavaBeans component           demarshal. To deconstruct an object so that it can
model.                                                    be written as a stream of bytes. Synonym for flatten
                                                          and serialize.
composite bean. A bean that is composed of other
beans. A composite bean can contain visual beans,         deserialize. To construct an object from a de-mar-
nonvisual beans, or both. See also bean, nonvisual        shaled state. Synonym for marshal and resurrect.
bean, and visual bean.
                                                          domain. A domain name server (DNS) or Internet
concrete class. A non-abstract subclass of an             protocol (IP) address, for example, soft-
abstract class that is a specialization of the abstract   ware.ibm.com or 123.45.67.8.
class.
                                                          domain name server. A system for translating
connection. In the Visual Composition Editor, a           domain names such as www.software.ibm.com into
visual link between two components that represents        numeric Internet protocol addresses such as
the relationship between the components. Each             123.45.67.8.
connection has a source, a target, and other prop-
erties. See also event-to-method connection,              double-byte character set (DBCS). A set of char-
parameter connections, and property-to-property           acters in which each character is represented by 2
connection.                                               bytes. Languages such as Japanese, Chinese, and
                                                          Korean, which contain more symbols than can be


186     IBM Enterprise Information Portal - A Primer
represented by 256 code points, require dou-              File View. In WebSphere Studio, graphical repre-
ble-byte character sets. Compare with single-byte         sentation of all the files in your site arranged in fold-
character set.                                            ers.

dynamic information. Information that is created          flatten. Synonymous with demarshal.
at the time the user requests it. Dynamic informa-
tion changes over time so that each time users view       Folder. In WebSphere Studio, a group of related
it, they see different content.                           files.

                                                          free-form surface. The open area of the Visual
E                                                         Composition Editor where you can work with visual
                                                          and nonvisual beans. You add, remove, and con-
edition. A specific “cut” of a program element. Visu-     nect beans on the free-form surface.
alAge for Java supports multiple editions of pro-
gram elements. See also current edition, open
edition, and versioned edition.                           G
encapsulation. The hiding of a software object’s          generated link. In WebSphere Studio, a link that is
internal representation. The object provides an           created by WebSphere Studio based on the param-
interface that queries and manipulates the data           eters of a code file.
without exposing its underlying structure.
                                                          graphical user interface (GUI). A type of interface
event. An action by a user program, or a specifica-       that enables users to communicate with a program
tion of a notification that may trigger specific behav-   by manipulating graphical features, rather than by
ior. In JDK 1.1, events notify the relevant listener      entering commands. Typically, a GUI includes a
classes to take appropriate actions.                      combination of graphics, pointing devices, menu
                                                          bars and other menus, overlapping windows, and
event-to-method connection. A connection from             icons.
an event generated by a bean to a method of a
bean. When the connected event occurs, the
method is executed. See also connection.                  H
                                                          HTML. See “hypertext markup language.”
F
                                                          HTTP. See “hypertext transfer protocol.”
federated search. A search that runs against dis-
parate content servers                                    home page. See “start page.”

FTP. See “file transfer protocol.”                        hyperlinks. Areas on a Web page that, when
                                                          clicked, connect you to other areas on the page or
factory. A nonvisual bean capable of dynamically          other Web pages.
creating new instances of a specified bean.
                                                          Hypertext Markup Language (HTML). The basic
feature. (1) A component of VisualAge for Java that       language that is used to build hypertext documents
is installed separately using the QuickStart. (2) A       on the World Wide Web. It is used in basic, plain
method, field, or event that is available from a          ASCII-text documents, but when those documents
bean’s interface and to which other beans can con-        are interpreted, or rendered, by a Web browser
nect.                                                     such as Netscape, the document can display for-
                                                          matted text, color, a variety of fonts, graphical
field. See attribute                                      images, special effects, hypertext jumps to other
                                                          Internet locations, and information forms.
file transfer protocol. An international standard for
transferring files from one computer to another
across a network.


                                                                                                              187
Hypertext Transfer Protocol (HTTP). The protocol         Internet. The collection of interconnected networks
for moving hypertext files across the Internet.          that use TCP/IP and evolved from the ARPANET of
Requires an HTTP client program on one end, and          the late 1960s and early 1970s.
an HTTP server program on the other end. HTTP is
the most important protocol used in the World Wide       Internet Protocol (IP). The protocol that provides
Web.                                                     basic Internet functions.

                                                         Internet protocol address. A numeric address that
I                                                        uniquely identifies every computer connected to a
                                                         network. For example, 123.45.67.8
IDE. See Integrated Development Environment.
                                                         intranet. A private network, inside a company or
IP. See “Internet protocol address.”                     organization, that uses the same kinds of software
                                                         that you would find on the public Internet. Many of
IP number. An Internet address that is a unique          the tools used on the Internet are being used in pri-
number consisting of four parts separated by dots,       vate networks; for example, many companies have
sometimes called a dotted quad (for example:             Web servers that are available only to employees.
198.204.112.1). Every Internet computer has an IP
number, and most computers also have one or
more domain names that are mappings for the dot-         J
ted quad.
                                                         JDBC. In JDK 1.1, the specification that defines an
Import Wizard. A WebSphere Studio feature that           API that enables programs to access databases
copies an existing Web site into the WebSphere           that comply with this standard.
Studio environment.
                                                         Java. A programming language invented by Sun
inheritance. (1) A mechanism by which an object          Microsystems that is specifically designed for writ-
class can use the attributes, relationships, and         ing programs that can be safely downloaded to your
methods defined in classes related to it (its base       computer through the Internet and immediately run
classes). (2) An object-oriented programming tech-       without fear of viruses or other harm to your com-
nique that allows you to use existing classes as         puter or files.
bases for creating other classes.
                                                         Java archive (JAR). A platform-independent file
inside link. In WebSphere Studio, a file within a        format that groups many files into one. JAR files are
WebSphere Studio site that links to other files in the   used for compression, reduced download time, and
site.                                                    security.

instance. Synonym for object, a particular instantia-    JavaBeans. The specification that defines the plat-
tion of a data type.                                     form-neutral component model used to represent
                                                         parts. Instances of JavaBeans (often called beans)
integrated development environment (IDE). In             may have methods, properties, and events.
VisualAge for Java, the set of windows that provide
the user with access to development tools. The pri-      JavaServer Pages. A server side scripting tech-
mary windows are Workbench, Class Browser, Log,          nology that allows for dynamic generation of the
Console, Debugger, and Repository Explorer.              response on the server.

interchange file. A file that you can export from        JSP. See "JavaServer Pages."
VisualAge for Java that contains information about
selected projects or packages. This file can then be
imported into any VisualAge for Java session.            K
interface. A named set of method declarations that       keyword. A predefined word reserved for Java, for
is implemented by a class. The Interface page in         example, return, that may not be used as an identi-
the Workbench lists all interfaces in the workspace.     fier.


188     IBM Enterprise Information Portal - A Primer
L                                                      mutator methods. Methods that an object provides
                                                       to define the interface to its instance variables. The
library server. See server - library.                  accessor method to return the value of an instance
                                                       variable is called a get method or getter method,
listener. In JDK 1.1, a class that receives and han-   and the mutator method to assign a value to an
dles events.                                           instance variable is called a set method or setter
                                                       method.
local area network (LAN). A computer network
located on a user’s establishment within a limited
geographical area. A LAN typically consists of one
                                                       N
or more server machines providing services to a
number of client workstations.                         named package. In the VisualAge for Java IDE, a
                                                       package that has been explicitly named and cre-
log. In VisualAge for Java, the window that displays   ated.
messages and warnings during development.
                                                       nesting. In WebSphere Studio, the number of
                                                       folder levels beneath other folders. One level of
M                                                      folders gives you a “nesting” of one. If that folder
                                                       contains other folders, you have a nesting of two
MIME type (Multi-purpose Internet Mail Exten-          and so on.
sions). An international standard for categorizing
types of Web files such as text and images.            nonvisual bean. In the Visual Composition Editor,
                                                       a bean that has no visual representation at run
MVC. See Model View Controller.                        time. A nonvisual bean typically represents some
                                                       real-world object that exists in the business environ-
marshal. Synonymous with deserialize.                  ment. Compare with model. Contrast with view and
                                                       visual bean.
message. A communication from one object to
another that requests the receiving object to exe-
cute a method. A method call consists of a method
                                                       O
name that indicates the requested method and the
arguments to be used in executing the method. The      ODBC driver. An ODBC driver is a dynamic link
method call always returns some object to the          library that implements ODBC function calls and
requesting object as the result of performing the      interacts with a data source.
method. Synonym for method call.
                                                       object server. See server - object.
method. A fragment of Java code within a class
that can be invoked and passed a set of parameters     object. (1) A computer representation of something
to perform a specific task.                            that a user can work with to perform a task. An
                                                       object can appear as text or an icon. (2) A collection
method call. Synonymous with message.                  of data and methods that operate on that data,
                                                       which together represent a logical entity in the sys-
model. A nonvisual bean that represents the state      tem. In object-oriented programming, objects are
and behavior of an object, such as a customer or an    grouped into classes that share common data defi-
account. Contrast with view.                           nitions and methods. Each object in the class is
                                                       said to be an instance of the class. (3) An instance
Model View Controller. An application architecture     of an object class consisting of attributes, a data
which separates the components of the application:     structure, and operational methods. It can represent
the model represents the business logic or data; the   a person, place, thing, event, or concept. Each
view represents the user interface and the control-    instance has the same properties, attributes, and
ler manages user input, or, in some cases the appli-   methods as other instances of the object class,
cation flow.                                           although it has unique values assigned to its
                                                       attributes.




                                                                                                        189
object class. A template for defining the attributes      parent class. The class from which another bean
and methods of an object. An object class can con-        or class inherits data, methods, or both.
tain other object classes. An individual representa-
tion of an object class is called an object.              part. An existing, reusable software component. In
                                                          VisualAge for Java, all parts created with the Visual
object-oriented programming (OOP). A program-             Composition Editor conform to the JavaBeans com-
ming approach based on the concepts of data               ponent model and are referred to as beans. See
abstraction and inheritance. Unlike procedural pro-       also nonvisual bean and visual bean.
gramming techniques, object-oriented program-
ming concentrates on those data objects that              primitive bean. A basic building block of other
constitute the problem and how they are manipu-           beans. A primitive bean can be relatively complex in
lated, not on how something is accomplished.              terms of the function it provides.

Open Database Connectivity (ODBC). A                      private. In Java, an access modifier associated
Microsoft-developed C database API that allows            with a class member. It allows only the class itself to
access to database management systems calling             access the member.
callable SQL, which does not require the use of an
SQL preprocessor. In addition, ODBC provides an           process. A collection of code, data, and other sys-
architecture that allows users to add modules (data-      tem resources, including at least one thread of exe-
base drivers) that link the application to their choice   cution, that performs a data processing task.
of database management systems at run time.
Applications no longer need to be directly linked to      program. In VisualAge for Java, a term that refers
the modules of all the database management sys-           to both Java applets and applications.
tems that are supported.
                                                          program element. In VisualAge for Java, a term
open edition. An edition of a program element that        referring to any of the entities under source control.
can still be modified; that is, the edition has not       Program elements are projects, packages, classes,
been versioned. An open edition may reside in the         interfaces, or methods.
workspace as well as in the repository.
                                                          project. In VisualAge for Java, the topmost kind of
operation. A method or service that can be                program element. A project contains Java pack-
requested of an object.                                   ages.

outside link. In WebSphere Studio, a link to a file       promotion. Within a JavaBean, to make features of
that is located outside the current Web site.             a contained bean available to be used for making
                                                          connections. For example, a bean consisting of
                                                          three push buttons on a panel. If this bean is placed
P                                                         in a frame, the features of the push buttons would
                                                          have to be promoted to make them available from
package. A program element that contains related          within the frame.
classes and interfaces.
                                                          property. An initial setting or characteristic of a
palette. See beans palette.                               bean; for example, a name, font, text, or positional
                                                          characteristic.
parameter connection. A connection that satisfies
a parameter of an action or method by supplying           property sheet. In the Visual Composition Editor, a
either a property’s value or the return value of an       set of name-value pairs that specify the initial
action, method, or script. The parameter is always        appearance and other bean characteristics.
the source of the connection. See also connection.
                                                          property-to-property connection. A connection
parent. In WebSphere Studio, a file that contains a       from a property of one bean to a property of another
reference to another file.                                bean. See also connection.




190     IBM Enterprise Information Portal - A Primer
protected. In Java, an access modifier associated         Resources folder. In WebSphere Studio, the
with a class member. It allows the class itself, sub-     folder that physically holds a site’s folders and files.
classes, and all classes in the same package to
access the member.                                        resurrect. Synonymous with deserialize.

protocol. (1) The set of all messages to which an         RMI compiler. The compiler that generates stub
object will respond. (2) Specification of the structure   and skeleton files that facilitate RMI communica-
and meaning (the semantics) of messages that are          tion. This compiler can be automatically invoked
exchanged between a client and a server. (3) Com-         from the Tools menu item.
puter rules that provide uniform specifications so
that computer hardware and operating systems can          RMI registry. A server program that allows remote
communicate.                                              clients to get a reference to a server bean.

prototype. A method declaration or definition that
includes the name of the method, the return type          S
and the types of its arguments. Contrast with signa-
ture.                                                     Scrapbook. In VisualAge for Java, the window
                                                          from which you can write and test fragments of
publishing. In WebSphere Studio, the process of           code, without having to define an encompassing
copying your site’s files to Web servers.                 class or method.

Publishing View . In WebSphere Studio, a graphi-          serialize. Synonymous with demarshal.
cal representation of the stages (for example Test
or Production) where you define the layout of your        servlet. A Java program designed to run within a
Web servers and identify the files you want in your       Java-enabled Web server.
Web site.
                                                          server - library. The library server manages cata-
                                                          log information and provides pointers to the objects
R                                                         held in the object server.

Relations View. In WebSphere Studio, a graphical          server - object. The object server contains the
representation of each file in your site and the links    actual digitized content files of a digital library, such
between those files.                                      as a video clip.

Remote Method Invocation (RMI). In JDK 1.1, the           signature. The part of a method declaration con-
API that enables you to write distributed Java pro-       sisting of the name of the method and the number
grams, allowing methods of remote Java objects to         and types of its arguments. Contrast with prototype.
be accessed from other Java virtual machines.
                                                          single-byte character set. A set of characters in
repository. In VisualAge for Java, the storage area,      which each character is represented by a 1- byte
separate from the workspace, that contains all edi-       code.
tions (both open and versioned) of all program ele-
ments that have ever been in the workspace,               SmartGuide. In IBM software products, an inter-
including the current editions that are in the work-      face that guides you through performing common
space. You can add editions of program elements to        tasks.
the workspace from the repository.
                                                          source link. In WebSphere Studio, a link you cre-
Repository Explorer. In VisualAge for Java, the           ate to identify the source file of a publishable file.
window from which you can view and compare edi-
tions of program elements that are in the repository.     Start page. The first page a user sees when brows-
                                                          ing a Web site, also known as the “home page.”
resource file. A file that is referred to from your
Java program. Examples include graphics and               static information. Web files that do not change on
audio files.                                              every access.


                                                                                                              191
sticky. In the Visual Composition Editor, the mode        program logic; it must be connected such that it
that enables an application developer to add multi-       receives run-time identity from a bean elsewhere in
ple beans of the same class (for example, three           the application.
push buttons) without going back and forth between
the beans palette and the free-form surface.              versioned edition. An edition that has been ver-
                                                          sioned and can no longer be modified.
superclass. See abstract class and base class.
                                                          versioning. The act of making an open edition a
                                                          versioned edition; that is, making the edition
T                                                         read-only.

tear-off property. A property that a developer has        view. (1) A visual bean, such as a window, push
exposed as a variable to work with as though it           button, or entry field. (2) A visual representation that
were a stand-alone bean.                                  can display and change the underlying model
                                                          objects of an application. Views are both the end
thread. A unit of execution within a process.             result of developing an application and the basic
                                                          unit of composition of user interfaces. Compare
type. In VisualAge for Java, a generic term for a         with visual bean. Contrast with model.
class or interface.
                                                          visual bean. In the Visual Composition Editor, a
                                                          bean that is visible to the end user in the graphical
U                                                         user interface. Compare with view. Contrast with
                                                          nonvisual bean.
URL . See “uniform resource locator.”
                                                          visual programming tool. A tool that provides a
Unicode. A character coding system designed to            means for specifying programs graphically. Applica-
support the interchange, processing, and display of       tion programmers write applications by manipulat-
the written texts of the diverse languages of the         ing graphical representations of components.
modern world. Unicode characters are typically
encoded using 16-bit integral unsigned numbers.           Visual Composition Editor. In VisualAge for Java,
                                                          the tool where you can create graphical user inter-
uniform resource locator (URL). A standard iden-          faces from prefabricated beans and define relation-
tifier for a resource on the World Wide Web, used         ships (connections) between both visual and
by Web browsers to initiate a connection. The URL         nonvisual beans. The Visual Composition Editor is
includes the communications protocol to use, the          a page in the class browser.
name of the server, and path information identifying
the objects to be retrieved on the server.
                                                          W
user interface (UI). (1) The hardware, or software,
or both that enables a user to interact with a com-       Web application. A software system that is
puter. (2) The term user interface typically refers to    designed to automate a business process and is
the visual presentation and its underlying software       delivered on intranets or the Internet.
with which a user interacts.
                                                          Workbench. In VisualAge for Java, the main win-
                                                          dow from which you can manage the workspace,
V                                                         create and modify code, and open browsers and
                                                          other tools.
variable. (1) A storage place within an object for a
data feature. The data feature is an object, such as      workspace. The work area that contains all the
number or date, stored as an attribute of the con-        code you are currently working on (that is, current
taining object. (2) A bean that receives an identity at   editions). The workspace also contains the stan-
run time. A variable by itself contains no data or        dard Java class libraries and other class libraries.




192     IBM Enterprise Information Portal - A Primer
List of abbreviations

EIP                          Enterprise Information
                             Portal
ERP                          Enterprise Resource
                             Planning
IBM                          International Business
                             Machines Corporation
ITSO                         International Technical
                             Support Organization
IT                           Information Technology
ROI                          Return on Investment
SAP™                         Systems, Applications,
                             and Products in Data
                             Processing




© Copyright IBM Corp. 2000                             193
194   IBM Enterprise Information Portal - A Primer
Index
                                                     Criteria frame 139
A
AgentBase 152, 159                                   D
AgentBase class 123                                  Data Integration 119
AgentBase.getSession() 124                           Data Management 1
AgentContext 156                                     Data Mart 1
                                                     Data Warehouse 1, 8
                                                     DB2 20, 22
B                                                    DB2 database 22
Business Intelligence 1
                                                     DB2 environment variables 15
                                                     DB2 INCLUDE directory 14
C                                                    DB2 Knowledge Portal 2
C++ 39                                               DB2 UDB 9, 11, 12, 43
Catching exceptions 149                              DB2 UDB Software Developer’s Kit (SDK) 5.2 12
ccadmin 50, 147                                      DB2ADMIN 11, 12
CGI 101                                              Designer Workspace 121
CLASSPATH 47, 59, 118                                Digital Library 2, 37, 47, 148, 159
Classpath 58                                         Digital Library Administrator 10
Client/Server Configuration 20, 22, 23               Digital Library and VisualInfo toolkit 40
cmbclient.ini 49, 50                                 DKAttrDefDL 80
cmbcs.ini 46, 49                                     DKCombinedQueryDL 89
cmbdb 147                                            DKConstantFed 149, 152, 159
cmbdlc30.jar 159                                     dkDatastore 146
cmbfed30.jar 119                                     dkDatastoreDe 146
cmbfedc30.jar 119                                    DKDatastoreDL 79, 80, 81, 87, 101
cmbodc30.jar 159                                     DKDatastoreDL object 88
cmbregist 46                                         DKDatastoreFed 147, 153, 156, 157, 160, 161
cmbregist.bat 46                                     DKDatastoreTS 80, 81, 88
CMBROOT 45, 46, 47, 58, 63, 119, 121                 DKDDO 101, 102, 106, 107, 110, 146, 148, 161
Code page 10                                         DKDLItemId 72
Collaboration 119                                    DKException 149
Collaborative Portal 3                               DKFederatedQuery 146
com.ibm.mm.sdk.client 58, 118, 152                   DKMatches 73
com.ibm.mm.sdk.common 59, 118, 152                   DKNVPair 89
com.ibm.mm.sdk.cs 59, 118                            DKParametricQuery 87, 88, 89
com.ibm.mm.sdk.server 58, 118, 152                   DKPart 101
combined search 57, 75, 87                           DKPartNo 72
Content Connect 2                                    DKPid 110
Content Management 1                                 DKRank 72
Content Manager xi, 8, 9, 11, 17, 19, 20, 23, 57,    DKRepType 72
59, 63, 64, 70                                       DKResult 88, 89, 90
Content Manager installation 9                       DKTextQuery 88, 89
Content Manager server 71, 73, 75, 76, 78, 79, 80,   DLSAMPLE 60
87, 100, 109                                         DLSAMPLE_Subject 68
Content server runtimes 38                           Domino 169
Cookies 58                                           Domino APIs 120
Corporate Portal 2                                   Domino Database 119 , 120



© Copyright IBM Corp. 2000                                                                     195
Domino Designer 120                         G
Domino Extended Search 2                    Get Attributes 138
Domino Server 121                           GetAgent 136
Domino.Doc 37, 38                           getAgentContext 152, 156, 160
Domino.Doc toolkit 40                       getData() 106
                                            getDataName() 106
                                            GetFedEntity.class 155
E                                           GetFedEntity.java 155, 156, 157
EDMSuite VisualInfo 2, 19, 27, 30, 31, 55
EIP 1, 2, 3, 7                              getItemValueString 153, 156, 160
EIP administration program 37               getPartId() 110
EIP API 76                                  getProfileDocument 152
EIP benefits 3                              getProfileDocument() 156, 160
EIP client 38                               getSession 152
EIP database 37, 43, 117, 131               Globalization 119
EIP federated layer 129                     Grand Portal 2
EIP Java API 117, 129
EIP prerequisites 41                        H
EIP runtimes 38, 117                        Host name 23
Environment variables 16                    HttpServletRequest 78
ERP 4                                       HttpServletResponse 78, 79
Expertise Portal 3

                                            I
F                                           IBM DB2 21
FedEntity 160                               IBM DB2 Digital Library 19, 27, 30, 31, 55
Federated access toolkit 40                 IBM HTTP Server 169
Federated attributes 53, 54                 IBM WebSphere Application Server 76, 113, 114,
Federated Datastore 145, 147                169
Federated entity 52, 53, 54, 133            Image server 64
Federated entity selection 132              ImagePlus for OS/390 37
Federated Login 135                         INCLUDE 14
Federated Query 149                         Index class 60, 78, 101
Federated Search 37                         Initialization parameters 51
Federated searching 146                     Install DB2 11
FederatedEntity 156                         Install Visual C++ 12
FederatedEntityList 144                     Internet Connection Server 10
FedSearch.class 159                         Internet Explorer 76
FedSearch.java 159, 162                     istEntityNames() 153
Filter 67
FRNADMIN 30, 33
frnninst.log 27                             J
                                            Java xi, 39, 122, 124
FSC_Name 141
                                            Java API 57, 145, 149
FSC_Operator 141
                                            Java client 57
FSC_Value 141
                                            Java Development Kit 117
FSGetFedEntity 138, 155
                                            Java servlets 76
FSSearch 142
                                            JDK 113
                                            JSP 169




196
K                                              Net.Data 2, 42
Knowledge Portal 3                             NetFusion 2
                                               Netscape Communicator 76
                                               Netscape Enterprise Server 169
L                                              Netscape FastTrack Server 169
LIB 14
                                               Netscape Navigator 32
Library Server 9, 10, 14, 21, 22, 23, 27, 29
                                               Network table 17, 20, 21, 23, 49
Library Server Administrator 14
                                               Notepart 102
libsrv 79
                                               Notes database 164
LIBSRVRN 27
                                               Notes Java API 159
License 29
                                               notes.ini 120
listEntityAttrNames() 156
                                               Notes.jar 121
listEntityAttrs() 80
                                               NotesMain 152
Llibrary Server 17
                                               NotesThread class 123
Local configuration 38
Login.java 151
Login_Database 144                             O
Login_Name 144                                 Object Server 9, 10, 14, 21, 22, 23, 28
Login_Password 144                             Object Server Database 22
LoginFlag 134, 144                             OBJSRVRN 28
Lotus 2                                        OnDemand 37, 42, 159
Lotus Domino 117, 119, 122                     OnDemand toolkit 40
Lotus Domino Designer 121, 164                 Oracle 20
Lotus Domino Go Webserver 169                  Oracle NT 9
Lotus Notes xi, 117 , 119, 144
Lotus Notes client application 39, 128
                                               P
                                               Parameter definition 132
M                                              Parametric search 57, 66, 68, 74, 75, 87
Maximum Results 67                             PATH 14
Maximum Return 71                              Persistence 58
Media archiver 23                              Personalization 119
Media Object Server feature 23                 PID 101, 148
Metadata 69                                    Port number 23
Microsoft Internet Explorer 32                 Prerequisites installation 9
Microsoft Internet Information Server 169      Public Portal 3
Microsoft Visual C++ 9, 12
MQ Series Workflow 2
MSContent 76, 77, 86, 100, 102, 106
                                               Q
                                               Query processing 146
MSInput 76, 77, 78, 81
MSInput.java 113
MSList 76, 77, 86, 87, 90 , 100, 101           R
MSMeta 76, 77, 100, 106, 107, 110              Rank value 75
MSText 76, 77, 86, 109                         RemoteHost 50
                                               RemotePort 50
                                               RMI 37, 38, 39, 45, 46, 49, 50, 117, 118
N
Native attributes 52
Native entities 52                             S
NCSO.jar 121                                   SaveOptions 133
                                               SCName 144


                                                                                          197
SCOper fields 144                                     W
Search Criteria entry 132                             Web 6
Search form 139                                       Web browser 70, 100
Search Index 70                                       WebSphere xi, 2, 57
Search template 52, 56                                Windows NT 9, 10, 17, 23, 29 , 43
Server name 23                                        Workflow 119
ServletOutputStream 79
Set Visual C++ environment variables 14
setDatastore 148                                      Y
                                                      Yahoo 1
setPrimaryId() 110
Software requirements 9
Starting and stopping the servers 9
Starting the System Administration Program 9
System Administration 24, 29, 30 , 31, 32, 33, 35
System Administration Client 17, 19, 24, 29, 35, 60
System Administration Client Properties 19
System Administration Gateway 24, 29
System Administration Program 29
System Administration window 31
System configuration 9
System.err 123
System.exit 123
System.out 123


T
TCP/IP 10, 24
Test connection 52
Text indexes 80
Text search 18, 57, 71, 74, 87
Text Search Server 47
Text server 60, 78, 80
Thumbnail ID 67
TMINDEX 60, 61
Tracking 119


U
Unicode 22
US_ENGLISH 10, 22
User ID 79


V
VideoCharger 23
Visual C++ 11, 14, 15
Visual Cafe 2
VisualInfo 37, 47, 148




198
IBM Redbooks review
Your feedback is valued by the Redbook authors. In particular we are interested in situations where a
Redbook "made the difference" in a task or problem you encountered. Using one of the following
methods, please review the Redbook, addressing value, subject matter, structure, depth and
quality as appropriate.
 • Use the online Contact us review redbook form found at ibm.com/redbooks
 • Fax this form to: USA International Access Code + 1 914 432 8264
 • Send your comments in an Internet note to redbook@us.ibm.com



 Document Number                     SG24-5749-00
 Redbook Title                       IBM Enterprise Information Portal - A Primer

 Review




 What other subjects would you
 like to see IBM Redbooks
 address?


 Please rate your overall            O Very Good     O Good      O Average      O Poor
 satisfaction:

 Please identify yourself as         O Customer     O Business Partner       O Solution Developer
 belonging to one of the             O IBM, Lotus or Tivoli Employee
 following groups:                   O None of the above

 Your email address:
 The data you provide here may
 be used to provide you with         O Please do not use the information collected here for future
 information from IBM or our         marketing or promotional contacts or other communications beyond
 business partners about our         the scope of this transaction.
 products, services or activities.

 Questions about IBM’s privacy       The following link explains how we protect your personal information.
 policy?                             ibm.com/privacy/yourprivacy/




© Copyright IBM Corp. 2000                                                                             199
                                             90<->249 pages
                                              0.17”<->0.473”
                                                (0.2”spine)
IBM Enterprise Information Portal A Primer
                                                                                                              ®




IBM Enterprise
Information Portal
A Primer
Introduction to the    The IBM Enterprise Information Portal (EIP) is a federated
IBM Enterprise         search gateway that provides a rich development
                                                                                        INTERNATIONAL
Information Portal     environment for the composition of mass customized               TECHNICAL
(EIP)                  applications or views.                                           SUPPORT
                                                                                        ORGANIZATION
                       This IBM Redbook describes one example of a Content
EIP installation and
                       Manager installation, based on the Windows NT platform for
configuration
                       a Web enabled system configuration. We outline the steps for
                       installing and configuring the necessary Content Manager         BUILDING TECHNICAL
Java and Notes         components and prerequisites for this example, based on our      INFORMATION BASED ON
sample code                                                                             PRACTICAL EXPERIENCE
                       configuration.

                       This redbook also discusses how to build a Java client           IBM Redbooks are developed by
                       application to search the Content Manager datastore. Our         the IBM International Technical
                       application is written as Java servlets, using the IBM           Support Organization. Experts
                                                                                        from IBM, Customers and
                       WebSphere application server. With this client application, we
                                                                                        Partners from around the world
                       can perform three types of searches: a parametric search, a      create timely technical
                       text search, and a combined search which executes a              information based on realistic
                       parametric search and a text search at the same time and         scenarios. Specific
                       produces, as a result, the combined set of the two searches.     recommendations are provided
                                                                                        to help you implement IT
                                                                                        solutions more effectively in
                       We also discuss the design and development of a Lotus Notes      your environment.
                       based client application for the content servers using the EIP
                       Java APIs.

                                                                                        For more information:
                                                                                        ibm.com/redbooks

                         SG24-5749-00                    ISBN 0738418889

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:36
posted:10/10/2011
language:English
pages:218