Lotus® Quickr services for IBM® WebSphere® Portal provides a rich REST interface to its ATOM Syndication and ATOM Publishing services.
Lotus® Quickr's ATOM Syndication support allows you to retrieve ATOM feeds from various Lotus Quickr resources, including Document Libraries, Folders, Documents, and Drafts. The ATOM Publishing support allows you to manipulate Lotus Quickr resources via HTTP GET, PUT, POST and DELETE. For example, you can manipulate metadata for document libraries, folders, and documents; upload documents; retrieve documents; and delete documents. For a comprehensive guide to all of Lotus Quickr's REST services, refer to the Lotus Content Quickr Services Wiki.
This article and accompanying sample application demonstrates how you can use IBM® WebSphere® Portlet Factory's REST Service Call builder -- introduced in Portlet Factory 6.0.2 -- to rapidly develop a web application that interacts with Lotus Quickr's REST services.
Shown in the image below, the sample application allows you to explore the contents of a Lotus Quickr Document Library and upload new documents.
The sample application is constructed in a provider/consumer manner. We'll begin by looking at the provider model.
This model provides two main services that use the REST Service Call builder: getFeed and uploadDoc
The getFeed Service Operation calls the REST Service Call builder (named Feed) to retrieve the feed of a Document Library or Folder. Since Lotus Quickr Feeds are retrieved by an HTTP GET, the builder's HTTP Request Type input is set to GET. The builder's URL input is taken from a variable at runtime. Initially the variable contains the feed url to the Document Library you entered on the login page. As you navigate by clicking on folders, the variable is set to the feed url of the selected folder.
Lotus Quickr allows you to control the number of entrys returned in the feed with the pagesize query string parameter. In this example, the builder's Parameters input sets pagesize to 200. Though the pagesize is hardcoded here for illustrative purposes, the pagesize parameter would be an excellent candidate for profiling.
The REST Service Call builder's Username and Password inputs are set to the username and password entered on the login page.
The uploadDoc Service Operation allows for posting a new document to a document library or folder. Since Lotus Quickr's ATOM Publishing support allows for uploading a document via an HTTP POST to a document library or folder feed, another REST Service Call builder (named PostNewDoc) is used. Accordingly, the Http Request Type input is set to POST.
When POST is selected, the REST Service Call builder allows you to specify a value for the Body Content Data Type input. When InputStream is selected for this input, the builder creates a separate input object type variable -- named builderCallNameInputStream , where builderCallName is the name chosen for the REST Service Call builder -- that you can set to the desired InputStream. In this example the getInputStream method is used to convert the uploaded file to an InputStream. Then, the InputStream is assigned to the builderCallnameInputStream variable. Conveniently, the REST Service Call builder handles streaming the InputStream to the Lotus Quickr repository.
The consumer model is responsible for rendering a UI and calling the services in the provider model.
The consumer model's login page, shown below, prompts you to enter the URL of a Lotus Quickr Document Library feed, a username, and password. To learn how to get the feed for a Document Library, see the section "Getting the URL for a Lotus Quickr Document Library" below.
Much like a file system explorer, the FeedContents page renders the contents of the root level of the Document Library and the contents of folders. When an a folder or document is selected, the openItem method of the QuickrUtil LJO decides what action to take: if the clicked item is a folder, the getFeed service operation is called and the contents of the folder are rendered. If the clicked item is a document, openItem sends a redirect to Lotus Quickr so the file can be streamed to the browser.
QuickrUtil also contains various utility methods for parsing the XML elements. For example, the element contains an attribute specifying whether an element represents a folder or document. The getImage method uses Portlet Factory's IXml interface to parse the this XML and returns the URL to a either a folder icon or document icon. This method is used by the Image builder to determine the icon -- either a folder or document -- to show next to each item.
The File Upload builder is used to place a file upload control on the page and stream the file from the browser to the application server. The uploadFile Action List calls the provider model's uploadDoc service, passing the filename of the uploaded file.
The Breadcrumbs builder is used to provide details on your current location in the library and backwards navigation. For example, the next image shows that the user first selected the Insurance folder, then the Life subfolder of the Annual Open Enrollment document library. The user can navigate backwards by clicking the links of the breadcrumbs builder.
Getting the URL for a Lotus Quickr Document Library
The quickest way to get the feed URL to your document library is to use Lotus Quickr's Service Document, a REST API that will return a list of all of the Document Libraries to which the username and password has access. This is explained in the IBM Lotus Quickr Developer's Guide.
Use a web browser to browse to
Search the service document for your document library. The href attribute of the collection element specifies the url of the library feed. The following is an example of a collection element:
Ideas to Consider
- The provider model could easily be modified to expose the list of libraries the user has access to from Lotus Quickr's Service document. Then, the consumer model could present this list and allow the user to choose a document library to explore. Similar to the methods in QuickrUtil, a simple utility method would be needed to parse the specific feed url from the XML. The advantage of this approach is that the user would not have to deal with complex feed URL's.
- Expose additional Lotus Quickr services, such as deleting documents and folders; updating metadata for libraries, folders, and documents; etc.
- Spiff up the User Interface with Portlet Factory's rich set of UI builders. For example, like one of the popular photo sharing websites, allow the user to edit metadata in place. Or, much like one of the major movie rental websites, hovering over the title of a library or folder could present a balloon with additional metadata.
Notes on running the sample and prerequisites
Portlet Factory 126.96.36.199 is required.
Lotus Quickr services for WebSphere Portal is required. (Lotus Quickr services for Lotus Domino will not work with this sample)
Import the attached zip file into your project using the Import WebSphere Portlet Factory Archive command.
File Upload support must be enabled. Set bowstreet.upload.enabled to true in WEB-INF\config\override.properties.
Also, update the bowstreet.upload.maxFileSizeK to the maximum file size that can be uploaded.