Accessing Quickr Document Libraries using IBM WebSphere Portlet Factory

Transcription

1 Accessing Quickr Document Libraries using IBM WebSphere Portlet Factory August 27, 2010 Copyright International Business Machines Corporation All rights reserved. Abstract This sample shows how to use the Quickr Document Access builder to access a Lotus Quickr document library using IBM WebSphere Portlet Factory Version (hereafter called Portlet Factory.) This sample includes a feature set and two project archives. The feature set can be added to Portlet Factory and used in a project to provide access to a Quickr document library. The project archives can be imported into Portlet Factory to see how the feature set was developed and how it can be used. Prerequisites You should have a basic familiarity with Portlet Factory and be able to create and run Portlet Factory models. Familiarity with Quickr Documents and access to a Quickr server is required for any practical use of the feature set, but t for inspecting the project archives.

2 Table of Contents The Builder Quickr Document Access...1 Overview of the Quickr Document Service API...1 A Builder to Handle the Complexity...1 XML Schemas...1 Service Operations...3 Library Operations...3 View Operations...3 Property Sheet Operations...3 Document Type Operations...3 Folder Operations...4 Document Operations...4 Draft Operations...5 Comment Operations...5 Unsupported Data Types...5 Using the Quickr Document Access Builder...6 Connection Example...7 Kwn Issues...8 The Feature Set Sample Quickr Documents Extension...9 Installing the Feature Set...9 Provider Model...9 Consumer Model...10 Configuration Model...10 Precedence of Configuration Settings...10 Running the Provider Model...10 The Service Project Archive QuickrDocumentService...11 Importing the Project Archive...11 Viewing the Builder Models...11 Service Models...12 Configuration...12 Settings...12 DocumentService...12 Implementation...13 Java Infrastructure...13 Anatomy of a Service Operation...13 Builder Files...13 Packaging the Feature Set...13 The Portlet Project Archive QuickrDocumentPortlet...14 Importing the Project Archive...14 Portlet Models...14 Portlet...16 Configuration Example...17 Resources...18 Trademarks...18 August 27, 2010 i

3 The Builder Quickr Document Access Overview of the Quickr Document Service API The Quickr Document Service API allows other programs to integrate with IBM Lotus Quickr. Application programmers can use the API to add Quickr features to existing programs or enhance existing Quickr features. In addition, new content can be created and existing content modified with the API. Feed reader programs can use the Atom syndication format to subscribe to various views of Lotus Quickr data to keep informed of updates and new content. A Builder to Handle the Complexity The Quickr Document Service API provides extensive functionality. In order to access this functionality however, an application developer must understand the complexities of the API and the resource model. The Quickr Document Access builder exposes a simpler programming and resource model -- a full set of Portlet Factory service operations that provide access to Quickr document libraries. By using this builder, Portlet Factory developers can more easily access the extensive functionality of the Quickr Document Service API. Figure 1. Picking the Quickr Document Access Builder XML Schemas The Quickr Document Access builder defines two schemas document-service-inputs.xsd for the inputs to the service operations and document-service.xsd for the results of the service operations. These schemas are used instead of the Atom-based format used by Quickr for a couple of reasons. 1. Atom is weakly typed the type of a given entity is defined by an attribute of a child element instead of by the type of the entity element. 2. Other important entity information is contained in attributes. This style is harder to use with Portlet Factory. Detailed schema documentation and sample XML documents are available in this folder: WEB-INF/deploy/product_documentation/quickr August 27,

4 Here's an example of a "document" <entry> response from the Quickr Document Service API. Example 1. Atom-based document <entry> received from Quickr. <entry xml:lang="en" xmlns:snx=" xmlns:td="urn:ibm.com/td"> <id>urn:lsid:ibm.com:td:e4abf60040b7ce06977bdf48833d85d2</id> <link href="document/e4abf60040b7ce06977bdf48833d85d2/entry" rel="self"></link> <link href=" rel="alternate"></link> <link href="document/e4abf60040b7ce06977bdf48833d85d2/entry" rel="edit"></link> <link href="document/e4abf60040b7ce06977bdf48833d85d2/media" rel="enclosure" type="unkwn/unkwn" title="ather Sample File" hreflang="en" length="132"></link> <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"></category> <author> <uri>uid%3dcosmokramer%2cdc%3dibm%2cdc%3dcom</uri> <name>cosmo Kramer</name> < >cosmo_kramer@us.ibm.com</ > </author> <title type="text">ather Sample File</title> <published> t20:26:46.812z</published> <updated> t20:26:46.812z</updated> <td:locked>false</td:locked> <td:path>/complete.log</td:path> <td:label>complete.log</td:label> <td:uuid>e4abf60040b7ce06977bdf48833d85d2</td:uuid> <td:created> t20:26:46.812z</td:created> <td:modified> t20:26:46.812z</td:modified> <td:documenttype>4f91cf0040b5bd4f8f2fdf48833d85d2</td:documenttype> <td:modifier> <td:uri>uid%3dgeorgecostanza%2cdc%3dibm%2cdc%3dcom</td:uri> <td:name>george Costanza</td:name> <td: >george_costanza@us.ibm.com</td: > </td:modifier> <summary type="text">sample file used for testing.</summary> <content type="unkwn/unkwn" xml:lang="en" src="document/e4abf60040b7ce06977bdf48833d85d2/media"></content> </entry> For comparison, here's the same entry after being transformed to a <document> element. Example 2. XML <document> element. <document> <id>e4abf60040b7ce06977bdf48833d85d2</id> <title>ather Sample File</title> <description>sample file used for testing.</description> <product-link> <created> <date> t20:26:46.812z</date> <person> <name>cosmo Kramer</name> < >cosmo_kramer@us.ibm.com</ > <presence>uid%3dcosmokramer%2cdc%3dibm%2cdc%3dcom</presence> </person> </created> <modified> <date> t20:26:46.812z</date> <person> <name>george Costanza</name> < >george_costanza@us.ibm.com</ > <presence>uid%3dgeorgecostanza%2cdc%3dibm%2cdc%3dcom</presence> </person> </modified> <location>/complete.log</location> <media> <file-name>complete.log</file-name> <size>132</size> <href> </media> <document-type-ref> <id>4f91cf0040b5bd4f8f2fdf48833d85d2</id> <title>document Type 1</title> <approval>0</approval> </document-type-ref> </document> August 27,

5 Service Operations The service operations created by the Quickr Document Access builder include basic CRUD operations for each supported data type. Not all applications using the Quickr Document Access builder will support all of these data types. And some applications will be limited to read-only access to the document library. For these reasons, some of the Quickr Document Access builder's service operations are optional, and can be disabled using the builder UI. Disabling unneeded service operations produces a smaller, simpler application. Table 1. Library Operations Service Operation Description Input/Result Type Optional getlibraries getlibrary getlibrarycontents getlibrarycontentsbypage getlibrarycontentsdataretriever getlibrarycontentsrowcount Get an XML document containing the document libraries available to the current user. This can take an extended amount of time and is t paged or sorted. Get an XML document containing the values for the specified document library. Get an XML document containing the folders and documents within the specified document library. Get an XML document containing a page of folders and documents within the specified document library. Get a data retriever for the folders and documents within the specified document library. Get the total number of folders and documents within the specified document library. input: <get-libraries> result: <libraries> input: <get-library> result: <library> input: <get-library-contents> result: <rowset> input: <get-library-contents-by-page> result: <rowset> input: <get-library-contents-data-retriever> result: object input: <get-library-contents-row-count> result: int modifylibrary Modify the metadata for the specified library. input: <modify-library> result: <library> Table 2. View Operations Service Operation Description Input/Result Type Optional getviews getview getviewcontents Get an XML document containing the views in the specified document library available to the current user. Get an XML document containing the values for the specified view. Get an XML document containing the documents in the specified view. input: <get-views> result: <views> input: <get-view> result: <view> input: <get-view-contents> result: <documents> Table 3. Property Sheet Operations Service Operation Description Input/Result Type Optional getpropertysheets getpropertysheet Get an XML document containing all property sheets available in the specified document library. Get an XML document containing the values of the specified property sheet. input: <get-property-sheets> result: <property-sheets> input: <get-property-sheet> result: <property-sheet> addpropertysheet Add a property sheet with the given values. input: <add-property-sheet> result: <property-sheet> modifypropertysheet Modify the specified property sheet using the given values. input: <modify-property-sheet> result: <property-sheet> removepropertysheet Remove the specified property sheet. input: <remove-property-sheet> Table 4. Document Type Operations Service Operation Description Input/Result Type Optional getdocumenttypes getdocumenttype getdocumenttypemetadata Get an XML document containing all document types available in the specified document library. Get an XML document containing the values of the specified document type. Get an XML document containing the metadata for the specified document type. input: <get-document-types> result: <document-types> input: <get-document-type> result: <document-type> input: <get-document-type-metadata> result: <metadata> adddocumenttype Add a document type with the given values. input: <add-document-type> result: <document-type> modifydocumenttype Modify the specified document type using the given values. input: <modify-document-type> result: <document-type> removedocumenttype Remove the specified document type. input: <remove-document-type> August 27,

6 Table 5. Folder Operations Service Operation Description Input/Result Type Optional getfolder getfoldercontents getfoldercontentsbypage getfoldercontentsdataretriever getfoldercontentsrowcount addfolder Get an XML document containing the values for the specified folder. Get an XML document containing the folders and documents within the specified folder. Get an XML document containing a page of folders and documents within the specified folder. Get a data retriever for the folders and documents within the specified folder. Get the total number of folders and documents within the specified folder. Add a folder with the given title and description to the specified folder. input: <get-folder> result: <folder> input: <get-folder-contents> result: <rowset> input: <get-folder-contents-by-page> result: <rowset> input: <get-folder-contents-data-retriever> result: object input: <get-folder-contents-row-count> result: int input: <add-folder> result: <folder> modifyfolder Modify the values for the specified folder. input: <modify-folder> result: <folder> removefolder Remove the specified folder. input: <remove-folder> copyfolder Copy the specified folder to the destination folder. input: <copy-folder> movefolder Move the specified folder to the destination folder. input: <move-folder> Table 6. Document Operations Service Operation Description Input/Result Type Optional getalldocuments getcheckedoutdocuments getdocument getdocumentmedia adddocument modifydocument Get an XML document containing all documents available to the current user in the specified document library. Get an XML document containing the checked out documents for the current user in the specified document library. Get an XML document containing the values for the specified document. Get an object containing the media of the specified document. Add a document (or draft) with the given values to the specified folder. If the document type for this document specifies that an approval process is required, the document will be saved as a draft, regardless of the "isdraft" input value. Modify the specified document using the given values. If the document type for this document specifies that an approval process is required, the document will be saved as a draft, regardless of the "is-draft" input value. input: <get-all-documents> result: <documents> input: <get-checked-out-documents> result: <documents> input: <get-document> result: <document> input: <get-document-media> result: object input: <add-document> result: <document> or <draft> input: <modify-document> result: <document> or <draft> removedocument Remove the specified document. input: <remove-document> removedocumentmedia Remove the specified document's media. input: <remove-document-media> checkoutdocument Check out the specified document. input: <check-out-document> checkindocument Check in the specified document. input: <check-in-document> lockdocument Lock the specified document. input: <lock-document> unlockdocument Unlock the specified document. input: <unlock-document> copydocument Copy the specified document to the destination folder. input: <copy-document> movedocument Move the specified document to the destination folder. input: <move-document> August 27,

7 Table 7. Draft Operations Service Operation Description Input/Result Type Optional getworkingdrafts getsubmitteddrafts getreviewdrafts getdraft getdraftmedia Get an XML document containing the working drafts for the current user in the specified document library. Get an XML document containing the submitted drafts for the current user in the specified document library. Get an XML document containing the review drafts for the current user in the specified document library. Get an XML document containing the values for the specified draft. Get an object containing the media of the specified draft. input: <get-working-drafts> result: <drafts> input: <get-submitted-drafts> result: <drafts> input: <get-review-drafts> result: <drafts> input: <get-draft> result: <draft> input: <get-draft-media> result: object modifydraft Modify the specified draft using the given values. input: <modify-draft> result: <draft> removedraft Remove the specified draft. input: <remove-draft> removedraftmedia Remove the specified draft's media. input: <remove-draft-media> submitdraft Submit the specified draft for approval. input: <submit-draft> approvedraft Approve the specified draft. input: <approve-draft> rejectdraft Reject the specified draft. input: <reject-draft> Table 8. Comment Operations Service Operation Description Input/Result Type Optional getcomments getcomment addcomment Get an XML document containing the contents of the specified document or draft. Get an XML document containing the values for the specified comment. Add a comment with the given content to the specified document or draft. input: <get-comments> result: <comments> input: <get-comment> result: <comment> input: <add-comment> result: <comment> modifycomment Modify the values for the specified comment. input: <modify-comment> result: <comment> removecomment Remove the specified comment. input: <remove-comment> Unsupported Data Types The Quickr Document Service API defines a couple of data types which are t supported by the Quickr Document Access builder. The Sync data type defines a replication request. The functionality provided by this type was t deemed to be necessary for the Quickr Document Access builder. The Query type defines a dynamic query for document-related content. This type was deemed to be overly complex, and may be added to a future version of the Quickr Document Access builder. August 27,

8 Using the Quickr Document Access Builder Figure 2. Input Values for the Quickr Document Access Builder The Quickr Document Access builder defines three groups of inputs. The Enabled Operations group defines which of the optional service operations will be available to a Service Consumer. The Connection Settings and Testing Support groups define the design-time settings used during development and testing. Table 9. Enabled Operations Builder Inputs Builder Input Affected Service Operations Libraries Views Property Sheets Document Types Folders Documents and Drafts Comments Workflow Non-Paged Contents updatelibraries getviews, getview addpropertysheet, modifypropertysheet, removepropertysheet adddocumenttype, modifydocumenttype, removedocumenttype addfolder, modifyfolder, removefolder, copyfolder, movefolder adddocument, modifydocument, removedocument, removedocumentmedia, checkoutdocument, checkindocument, lockdocument, unlockdocument, copydocument, movedocument, modifydraft, removedraft, removedraftmedia addcomment, modifycomment, removecomment getworkingdrafts, getsubmitteddrafts, getreviewdrafts, submitdarft, approvedraft, rejectdraft getlibrarycontents, getlibrarycontentsrowcount, getfoldercontents, getfoldercontentsrowcount August 27,

9 Table 10. Connection Settings Builder Inputs Builder Input Description Base Service URI Library ID Single Sign On User Name Password The base URI for the Quickr Document Service API. This is the first part of the URI used to access the Quickr server's Document Service API, and typically ends with a "dm" token. The ID of the Quickr document library to display. This ID is assigned by Quickr, and can be obtained by using a web browser to request <base-service-uri>/atom/introspection. A flag that indicates whether Portal Server is configured for single sign on with Quickr. If this input is selected, all requests to the Quickr Document Service API will be authenticated using the Portal Server LTPA token for the current user, so the User Name and Password inputs will be igred. The user name to be used for Basic Authentication with the Quickr Server. When using Basic Authentication, all requests to the Quickr Document Service API will be authenticated using the specified user name and password, even if the specified user is different than the current Portal Server user. The password to be used for Basic Authentication with the Quickr Server. When using Basic Authentication, all requests to the Quickr Document Service API will be authenticated using the specified user name and password, even if the specified user is different than the current Portal Server user. Table 11. Testing Support Builder Inputs Builder Input Description Add Testing Support Add Logging Enable testing support for the Quickr Document Access builder. This generates test pages for inputs and results of all the service operations, along with an index page for accessing the other pages. Enable service call logging for the Quickr Document Access builder. Information is written to the application server console and to the WebSphere Portlet Factory log file. Logged information can help in debugging problems with the service. Note: The inputs in tables 10 and 11 are design-time settings, and should be blank for a production application. Connection Example When using the Quickr Document Access builder to build a portlet, it is typically necessary to specify connection information in the builder. This developer-specific connection information is used while the portlet is being developed, and is then removed before the production portlet is deployed. Connection information for the deployed portlet is specified using the Configure mode. Here's an example of connecting to Quickr on Lotus Greenhouse. ( Greenhouse is a public website where you can test drive Lotus Collaboration products. In this example, we assume that John Doe from Acme Corp. has signed up for a Greenhouse account ( john_doe@acme.com, password: passw0rd!) John has created an "Acme Corp." document library, which has an ID of " abcdef abcdef". (Display the "Edit Library Properties" page in the Quickr product UI to determine the ID of a document library.) To connect to the "Acme Corp." document library during portlet development, John would specify the following settings in the Quickr Document Access builder: Note: The account mentioned above is fictitious. You will need to sign-up for and use your own Greenhouse account if you want to be able to access Quickr on Greenhouse. August 27,

10 Kwn Issues Error Handling. When the Quickr Document Service API encounters a problem with a request, it will return a 400- series or 500-series value for the HTTP response code and an error message in the response content. Unfortunately, Portlet Factory does t retain these values so that they can be used by an Error Handler Method. The Quickr Document Access builder includes an error handling infrastructure that attempts to use the response code and error message; but for w this aspect of the error handling is t fully functional. JSR-109 Web Services. Some versions of Eclipse scan your projects on startup, and add an entry named "JSR-109 Web Services" to the Project Explorer if any WSDL files are found. The Quickr Document Access builder includes a WSDL file used to describe the Quickr Web Services, so you may see the entry in your Project Explorer. It doesn't cause any problems, but can be removed from the Project Explorer. To remove it, choose Customize View from the Project Explorer menu, select the Content tab, and remove the check mark from JSR-109 Web Services Index. August 27,

11 The Feature Set Sample Quickr Documents Extension A feature set includes optional functionality in a project. This allows the generated application to include only the additional features required. The Sample Quickr Documents Extension adds functionality for accessing Quickr document libraries. This includes the Quickr Document Access builder, the Configuration model, and all of the supporting models and files required by the builder. Installing the Feature Set The feature set can be installed manually, or by using the Import WebSphere Portlet Factory Feature Set plugin. This plugin automates the process of installing a feature set in Portlet Factory. See this link for more information on the plugin. To install the feature set manually, make sure Portlet Factory Designer is closed. Copy the feature set package file to the WPF package location (e.g....\designer\featuresets\web-app_6.1.5\packages.) Start Portlet Factory Designer and verify that the Sample Quickr Documents Extension feature set is available in the Preferences dialog. Figure 3. Default Project Features Provider Model Once the feature set has been installed, it must be added as a feature of a new or existing project. For a new project, this can be done on the Feature Set page of the Create Project wizard. For an existing project, this can be done on the WebSphere Portlet Factory Project Properties, Feature Info page of the Project Properties dialog. The Quickr Document Access builder contains a Service Definition and several Service Operations. Therefore any model containing the Quickr Document Access builder is considered to be a Provider Model. The inputs specified in the builder determine which service operations are available to the Consumer Model. The Provider Model will also need to import the Configuration model if the portlet will use a Portlet Customizer to configure the connection settings. August 27,

12 Consumer Model Once the Provider Model has been created, a Consumer Model should be created. The Consumer Model will contain a Service Consumer builder whose Provider Model input specifies the Quickr Provider Model. This follows the classic Provider-Consumer pattern recommended for Portlet Factory applications. Once the Service Consumer is in place, the Quickr service operations will be available to the portlet model(s). Configuration Model The Configuration model is installed as part of the Sample Quickr Documents Extension feature set. This model defines the connection settings for the Quickr server. Its variables are profiled using the Configuration profile set. The model is meant to be imported into the portlet model(s) and used with a Portlet Customizer, so that the model's variables can be set via the portlet's configuration UI. In order to make the configuration variables available to the Quickr Document Access builder, the Configuration model must be imported into the Provider model. It is important to te that 1) the Imported Model builder must precede the Quickr Document Access builder in the Provider Model, and 2) the Import Once setting must be turned on in the Imported Model builder. Precedence of Configuration Settings The configuration settings are typically specified during portlet configuration, by using the Configuration model. These settings can also be specified as input values to the Quickr Document Access builder, or as inputs to the individual service operations. The order of precedence is: 1. Service operation inputs 2. Portlet configuration values 3. Builder inputs The recommended practice for a deployed portlet is to use portlet configuration. This allows the users and/or administrators of the portlet to specify the configuration values. The other two options are mainly used during development. The service operation inputs can be used during portlet development, possibly with a stub service data model. Service operation inputs might also be used for a portlet that allows for dynamic access to multiple Quickr document libraries, but this use case wouldn't be typical. If the service operation inputs are t meant to be used, then null or blank values should be specified for these inputs. The builder input values are convenient when developing a portlet that uses the Quickr Document Access builder. The builder inputs can specify a Quickr test server that is used while the portlet is being developed. For a deployed portlet however, the input values should be blank, to avoid interference with the desired configuration settings. Running the Provider Model After the Quickr Document Access builder inputs have been specified, with the Testing Support input checked, you can run the Provider Model to test the various service operations. This is done by opening the Provider Model and using the Run, Run command. The test index page will be displayed, from which a service operation can be selected. An input page for the selected service operation will be displayed. Entering the appropriate values on this page and pressing the Submit button will execute the service operation using the specified input values. The results of the service operation will be displayed, and the Back button can be used to return to the test index page. August 27,

13 The Service Project Archive QuickrDocumentService This project is used for developing the Quickr Document Access builder and the Sample Quickr Document Extension feature set. Importing the Project Archive Create a new Portlet Factory project using the File, New, WebSphere Portlet Factory Project command. Some of the project's properties will need to be modified, so select the project in the Project Explorer and use the Project, Properties command. 1) Specify that the project requires Java 5.0, by selecting the Project Facets page and changing the Java facet to ) If Ant is t available locally, download it. Add ant.jar as an external jar to the service project, as shown below. Now download the QuickrDocumentService.zip file and import it into the new project using the File, Import, WebSphere Portlet Factory Archive command. The project should build with errors. Viewing the Builder Models Some of the models included in the Quickr Document Access builder are located with the factory models. This is done to keep them hidden when using the Sample Quickr Documents Extensions feature set. For this project, you may want these models to be visible. If so, choose Customize View from the Project Explorer menu, select the Filters tab, and remove the check mark from models/factory directory. August 27,

14 Table 10. QuickrDocumentService project archive contents File name Description build_pkg.xml QuickrDocuments.bdef Configuration.model Settings.model DocumentService.model Implementation.model document.service.configuration.pset document.service.settings.pset deploy/product_documentation/ quickr/help/* deploy/product_documentation/ quickr/sample xml/* deploy/product_documentation/ quickr/schema/* document-service.xsd document-service-inputs.xsd DocumentService.wsdl PkgManifest.java QuickrDocuments*.java PageBasedDataRetriever.java PortletFactoryUtil.java DocumentService*.java *Exception.java QuickrDocumentService*.java Quickr*Util.java Quickr*DataRetriever.java The ant script used to build the feature set package. The builder definition file for the Quickr Document Access builder. Configuration settings for connecting to the Quickr server. Design-time settings for connecting to the Quickr server. The service delegate for the Quickr Document Service. The implementation of the Quickr Document Service. Configuration values for the Quickr Document Access builder. Settings for the Quickr Document Access builder. On-line help files for the Quickr Document Access builder. Sample XML documents for service operation inputs and outputs. Detailed documentation on the input and output schemas. XML schema defining output types for the service operations. XML schema defining input types for the service operations. WSDL file describing Quickr web services. Java file called by Ant to build the feature set package. Implementation of the Quickr Document Access builder. Generic data retriever for data from a page-based service. Utility methods related to method and variable usage in WPF. Generic document service functionality. Exceptions that are returned from the document service. Quickr extensions to generic document service functionality. Utility methods to generate service URIs and transform XML. Quickr extensions to the generic data retriever functionality. Service Models Configuration. This model defines the connection settings for the Quickr server. Its variables are profiled using the Configuration profile set. The model is meant to be imported into the portlet model(s) and used with a Portlet Customizer, so that the model's variables will be set via the portlet's configuration UI. This model must also be imported into the Provider model (before the Quickr Document Access builder,) so that the portlet configuration settings will be available to the builder. Settings. This model defines the design-time settings for connecting to the Quickr server. These settings will only be used if the configuration model settings have t been set. It is located with the "factory" models, because it is considered to be a private model. DocumentService. This model is the service delegate for the Quickr Document Service. It defines the available service operations, and determines the service implementation to be used. This model contains the: 1. Implementation model. 2. Configuration and settings models. 3. Input and output schemas. 4. Service Operations. It is located with the "factory" models, because it is considered to be a private model. August 27,

15 Implementation. This model implements the Quickr Document Service API. It contains the: 1. LJO for the Quickr Document Service. 2. REST Service Calls to the Quickr server. 3. Web Service Calls to the Quickr server. 4. Request variables for the service calls. It is located with the "factory" models, because it is considered to be a private model. Java Infrastructure Each service operation in the builder's DocumentService model specifies a Java method as the "Action to Call". All of these Java methods are declared as abstract methods of the DocumentService class, and are implemented in the QuickrDocumentService class. This pattern allows the DocumentService model and class to potentially be reused for other document service builders. The QuickrDocumentService class implements the business logic for accessing Quickr document libraries. Several types of common logic have been implemented as separate classes, including URI construction, XML transformation, and Portlet Factory variable and method access. See the Java source for more detailed information on the functionality of these classes. Anatomy of a Service Operation There are several steps that occur each time a service operation is executed. The process begins by using the input parameters and configuration settings to construct a service URI, set the request parameters, and construct any required request content. Once these steps have been completed, the appropriate service call can be invoked. The service call is made using a REST Service Call builder or a Web Service Call builder, depending on which type of call is defined by the Quickr Document Service API. If the service call results in an error, an exception will be thrown by the Java infrastructure. If the service call succeeds, the Atom-based response from Quickr will be transformed to the appropriate result type in the document-service schema. Builder Files The QuickrDocuments.bdef file defines the properties of the Quickr Document Access builder, including which Java classes are used to implement the builder and the details of each input value and input group. Most of the Java code for the builder is boilerplate, but there is some custom logic for handling the builder UI and hiding objects that are private to the builder. See the Java source for more detailed information on the functionality of these classes. Packaging the Feature Set The Ant scripts used to package the feature set need access to a Java compiler. If a Java 5.0 SDK is t available locally, download one, and then add "tools.jar" to the Ant classpath, as shown below. To invoke the packaging process, right-click on the file Web Content/build_pkg.xml and select Run As, Ant build. The results of the package process are displayed in the console. See Creating a Feature Set in the Portlet Factory wiki for more information about how to package a feature set. August 27,

16 The Portlet Project Archive QuickrDocumentPortlet This project is used for developing a simple portlet, to show how the Quickr Document Access builder and the Sample Quickr Document Extension feature set are to be used. Importing the Project Archive Create a new Portlet Factory project using the File, New, WebSphere Portlet Factory Project command. A few of the project's properties will need to be modified, so select the project in the Project Explorer and use the Project, Properties command. First, to specify that the project requires Java 5.0, select the Project Facets page and change the Java facet to 5.0. Then, to specify that the project uses the Sample Quickr Document Extension and Dojo features, select the WebSphere Portlet Factory Project Properties, Feature Info page. Expand Integration Extensions, and select the Sample Quickr Document Extension checkbox. Expand Dojo Ajax, and select the Dojo Extension 1.x checkbox. To enable the upload of files, locate the following section in the.../web-inf/config/cluster.properties file. Set the value of bowstreet.upload.enabled to true and modify the file size if the default in insufficient. # [ bowstreet.upload ] # File Upload Settings # This determines whether file upload is active for this server. bowstreet.upload.enabled= # This sets the directory where uploaded files will be stored upon successful upload. #bowstreet.upload.destinationpath=${bowstreet.rootdirectory}/upload # This determines the maximum file size that can be uploaded at one time in KiloBytes. bowstreet.upload.maxfilesizek=500 Now download the QuickrDocumentPortlet.zip file and import it into the new project using the File, Import, WebSphere Portlet Factory Archive command. The project should build with errors. Portlet Models BrowseContent. This is the main portlet model. It implements the main table, and uses the Service Consumer to make calls to the Quickr server. It also supports the following functionality: 1. A simple paging model - each page is limited to five entries. 2. Breadcrumbs show the current folder location. 3. The Dojo progress indicator shows that an action is being processed (some requests can take a while). 4. Folder contents are displayed by clicking on the folder icon. 5. The Library Options menu provides access to library/folder operations. This menu is always displayed. 6. The Document Options menu provides access to document operations. This menu is displayed when a document is selected. The BrowseContent model acts as a container for other models. Communication between models is event driven. CommonUI. This model contains common functionality used by the other portlet models. The Service Consumer builder provides access to a Quickr document library. The Command LJO exposes several common helper methods. This model also includes event declarations and shared variables. DynamicMenu. This model implements the 'Document Options' menu. It includes the handler for the UpdateDynMenu event, which is fired when a document is selected in the table. When a document is selected in the table, the Document Options menu is displayed. AddFile. This model handles the file upload to the current folder. It provides a browse option to select a file for upload. It launches on a new page clicking OK or Cancel will return to the main page. Folders. This model handles the functionality for adding a new folder and modifying the properties of an existing folder. It launches on a new page clicking OK or Cancel will return to the main page. August 27,

17 ReplaceFile. This model handles the functionality for replacing an existing file in the library or editing the properties of an existing file. It also displays additional information when hovering over a file name. It launches on a new page clicking OK or Cancel will return to the main page. CommentsMenu. This model handles the display of the comments for a given document, along with adding and deleting comments. The comments page gets included on a page in the BrowseContent model, and replaces the main portlet page completely. The Comments page includes a 'Back' link to allow the user return to the main portlet page. Provider. This model includes the Quickr Document Access builder and the Configuration model. It is important to te that the Imported Model builder for the Configuration model must precede the Quickr Document Access builder, in order for the Quickr service layer to have proper access to the variables in the Configuration model. DocLibConfigure. This model includes the Portlet Customizer builder and other support for configuring the portlet. If the portlet has t been properly configured, the main portlet page will display a message. On the configure page, the list of document libraries is hidden until the "Get Libraries" button is pressed. Pressing this button fetches the list of libraries from the Quickr server, and displays the populated drop down. August 27,

18 Portlet The portlet provided with this sample is an example of what can be built using the Quickr Document Access builder. It provides the following Quickr functionality: Folders. Display folder contents, add a new folder, edit folder properties, delete a folder. Documents. Upload a new document, replace an existing document, download a document, edit document properties, delete a document, display the comments for a document. Comments. Add a new comment, delete a comment. This portlet does t provide all of the functionality available in the builder. For example, the portlet does t display property sheets or document types. It does t display the contents of views or support drafts. Using the project provided, this portlet could be modified to provide more of the functionality available in the builder. August 27,

19 Configuration Example Before the portlet can display a Quickr document library, an administrator must provide the appropriate connection settings. These connection settings are specified on the portlet's Configure page, where the administrator provides a URL to the Quickr server, authentication information, and the document library to be displayed. Here's an example of connecting to Quickr on Lotus Greenhouse. ( Greenhouse is a public website where you can test drive Lotus Collaboration products. In this example, we assume that John Doe from Acme Corp. has signed up for a Greenhouse account ( john_doe@acme.com, password: passw0rd!), and has created a document library named "Acme Corp.". To configure the portlet for connecting to the "Acme Corp." document library, John would specify the following settings on the portlet's configure page. Note that pressing the "Get Libraries" button will use the values from the other fields to access the Quickr server, so these values must be specified before pressing the button. After pressing the "Get Libraries" button, the drop down list of available libraries will be displayed. Specifying these values will work, but will connect to the Quickr server as "John Doe" for all users of the portlet. In most deployment scenarios, the Portal server and Quickr server are configured for Single Sign On (SSO), allowing a user who has logged into Portal to be automatically authenticated with Quickr. So if the servers are configured for SSO, the administrator should specify this on the portlet's Configure page, instead of User Name and Password. Note: As an alternate configuration design, the administrator could specify the Base Service URI, SSO, and the document library on the portlet's Configure page. Then if the SSO setting is false, each user would specify their own user name and password on the portlet's Personalize page. This alternate design is t included in the sample. August 27,

20 Resources WebSphere Portlet Factory product documentation WebSphere Portlet Factory support WebSphere Portlet Factory Best Practices forum Quickr REST services for documents Quickr Web services for documents Trademarks IBM, Lotus, Quickr, WebSphere, and Portlet Factory are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corp. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. August 27,