Level: Intermediate Eitan Shapiro (EITANS@il.ibm.com), Software Engineer, IBM
22 Jan 2008 This article presents the IBM Lotus Quickr Search REST service and an example of its use. Learn about an IBM Lotus Sametime plug-in that lets you search for content on the Lotus Quickr server and share it during a conversation through IBM Lotus Sametime Connect or by sending IBM Lotus Notes email.
IBM Lotus Quickr makes it easy for users to share business content because it is built on open interfaces that let customers and business partners develop their own applications based on their own needs. This article helps you become familiar with both the layout of the search service and the request-response patterns used so that you can start developing your own applications. For information on other published interfaces that interact with Lotus Quickr content, refer to the IBM Lotus Quickr Developers Guide. For an introduction to Lotus Quickr REST services, refer to the companion developerWorks article, "Introducing IBM Lotus Quickr REST services."
Prerequisites
You should have a good understanding of Java and Web 2.0 programming to get the most out of this article. To use the sample code, you need a basic understanding of IBM Lotus Sametime Software Development Kit (SDK) and the Apache Abdera client toolkit. NOTE: The sample code works only after you install the iFix for the Lotus Quickr Search REST servlet (iFix L025578).
For information about the Lotus Sametime SDK, see the developerWorks article, "Extending IBM Lotus Sametime Connect V7.5." For information about the Apache Abdera client toolkit, see the developerWorks article, "Getting to know the Atom Publishing Protocol, Part 3: Introducing the Apache Abdera project."
You can download the Lotus Sametime SDK from the developerWorks Lotus Toolkits page.
Overview
The goal of the Lotus Quickr Search REST service is to enable you to build collaborative solutions with as little effort as possible. The service is designed around open standards and Web 2.0 technologies, allowing you to build applications with a basic understanding of existing Web technologies, such as HTTP and XML. Specifically, REST-style URLs are used to search the server content. The service is based on the Atom Syndication Format as described in RFC 4287 and uses OpenSearch response elements to extend the syndication formats of Atom with the extra metadata needed to return search results.
Lotus Sametime plug-in for searching/sharing Lotus Quickr content
In this example, we implement two extension points for Lotus Sametime Connect. The first one allows users to open the search window from the Contacts panel, and the second one allows them to open the same search window from a chat window. The two scenarios are handled by the same code; however, in the second scenario, we detect the chat window and add an option to select a search result and share it by clicking the Share button. Listing 1 shows part of the plugin.xml file, which includes the extensions and definitions, such as the implementation class name.
Listing 1. Lotus Sametime plug-in extension points
<plugin>
<extension
point="org.eclipse.ui.viewActions">
<viewContribution
id="com.ibm.lotus.search.feed.viewactions"
targetID="com.ibm.collaboration.realtime.imhub">
<action ... here specify what class handle and more .../>
</viewContribution>
</extension>
<extension
point="com.ibm.collaboration.realtime.chatwindow.chatAction">
<chatAction ... here specify what class handle and more .../>
</extension>
</plugin>
|
The plug-in features the following operations:
- Getting the list of scopes
- Searching any one of the available scopes
- Showing icon, title, owner, updated date, and description for each search result
- Sending search results through IBM Lotus Notes
- Sharing search results through Lotus Sametime Connect
- Opening the search results in a browser as an Atom feed
The structure of the plug-in is very simple. The SearchApplication class is instantiated by the two implementations of the different extension points. This search application is the main entry point into the code. It holds several other class instances that assist in achieving the required functionality. All three of them can be found under the package com.ibm.lotus.search.feed.application.
- SearchTable class is responsible for displaying the search results and supporting the different operations, such as drag and drop into Lotus Notes, double-click to open the search result in a browser, or hover to see more details about the item.
- ScopesList class is responsible for displaying the scopes in a list and allowing the user to select the relevant one for the current search.
- DetailedDialog class is responsible for receiving from the user the details required for connecting to the remote Lotus Quickr server.
In our example, the open source Apache Abdera client is used to parse the Atom feeds in the SearchFeedParser class. Figure 1 shows a high-level view of the plug-in architecture.
Figure 1. High-level architecture of the plug-in
Getting the list of scopes
You must first retrieve the list of scopes so that you can display them in the Scopes window and enable users to select the specific scope they want to search. To retrieve the scopes feed, you need to know the server name along with a user ID and password to connect to the server. Because the URL format is published in the documentation, you can build it yourself for a given server. For this server, the URL appears as follows:
http://quickr.bookswisdom.com/searchfeed/myserver/scopes
Use a GET request to this URL to retrieve the list of scopes. The response contains an Atom with two entries (see listing 2) that describes two scopes, My Places and My Favorites. The All Sources scope, which searches across the server content, is a virtual scope with an empty string ID, and as such, it is not published on the feed.
Listing 2. Feed with available scopes from the Lotus Quickr server
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xhtml="http://www.w3.org/1999/xhtml"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
<atom:title>Available Scopes</atom:title>
<atom:link href=
"http://bookswisdom/searchfeed/myserver/scopes" rel="self"
type="application/atom+xml"/>
<atom:author>
<atom:name>Enterprise Search API Web Service.</atom:name>
</atom:author>
<atom:id>[http://bookswisdom/searchfeed/myserver/scopes]</atom:id>
<atom:updated>2007-12-20T21:07:36.250+00:00</atom:updated>
<atom:entry>
<atom:title>My Favorites</atom:title>
<atom:summary>Search content from your favorite Places</atom:summary>
<atom:id>DYNAMIC_SCOPE.MyFavoritesScopeBrowseFactory</atom:id>
<opensearch:image>/lotus/themes/html/QPG/icons/scope_search_favorites.gif
</opensearch:image>
</atom:entry>
<atom:entry>
<atom:title>My Places</atom:title>
<atom:summary>Search content from your Places.</atom:summary>
<atom:id>DYNAMIC_SCOPE.TSScopeBrowseFactory</atom:id>
<opensearch:image>/lotus/themes/html/QPG/icons/scope_search_teamspaces.gif
</opensearch:image>
</atom:entry>
</atom:feed>
|
The summary element can be used as hover text, and the image element is the icon for the scope. The most important element is the ID, which should be used when building the search request as one of the URL query parameters. Listing 3 shows the portion of code that processes this response in the sample. The code uses a class that represents a search result or a scope and is called SearchEntryData. This class reads the information from the Abdera feed object.
Listing 3. Partial code to process the response
public class SearchFeedParser implements FeedParser {
private Stream feed;
private Abdera abdera;
public SearchFeedParser(Stream feed) {
this.feed = feed;
AbderaConfiguration config = new AbderaConfiguration();
config.addExtensionFactory(new OpenSearchExtensionFactory());
abdera = new Abdera(config);
}
public List getEntries() throws ParseException, HttpException,
MalformedURLException, IRISyntaxException, IOException {
List entriesList = new ArrayList();
try {
Parser parser = abdera.getParser();
Document doc = parser.parse(feed.getContent(), feed.getFullUri());
Feed f = (Feed) doc.getRoot();
List entries = f.getEntries();
Iterator it = entries.iterator();
while (it.hasNext()) {
entriesList.add(
new SearchEntryData((Entry) it.next(), feed.getSource()));
}
} finally {
feed.release();
}
return entriesList;
}
}
|
The small window in figure 2 shows the list of available scopes from which the user can choose. The All Sources scope is used as the default scope.
Figure 2. Plug-in showing the list of scopes retrieved from the server
Searching against a specific scope
Now that you have a selected scope and its ID, the next step is to build the URL with the search query that the user entered in the search box and to send the search request to the Lotus Quickr server. Here again, to perform the search, you need to know the server name along with a user ID and password to connect to the server. Because the URL format is published in the documentation, you can build it yourself for a given server. For this server, the URL appears as follows:
http://quickr.bookswisdom.com/searchfeed/myserver/search?scope= &query=test
A GET request to this URL is used to retrieve the list of search results. The response contains an Atom with two entries (see listing 4), which describes two scopes, My Places and My Favorites. The All Sources scope, which searches across the server content, is a virtual scope with an empty string ID, and as such, it is not published on the feed.
Listing 4. Feed with search results for the query test
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xhtml="http://www.w3.org/1999/xhtml"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
<atom:title>Search results for query test on all sources</atom:title>
<atom:link href="http://bookswisdom/searchfeed/myserver/search?scope=&query=test"
rel="self" type="application/atom+xml"/>
<atom:author><atom:name>Enterprise Search API Web Service.
</atom:name></atom:author>
<atom:id>http://maggie:10038/searchfeed/myserver/search?scope=
&query=test</atom:id>
<atom:category term="all sources" label="all sources"/>
<atom:updated>2007-12-20T22:06:23.438+00:00</atom:updated>
<opensearch:totalResults>3</opensearch:totalResults>
<opensearch:Query role="request" searchTerms="a*"/>
<opensearch:startIndex>0</opensearch:startIndex>
<opensearch:itemsPerPage>3</opensearch:itemsPerPage>
<atom:entry><atom:title>CAIDesign.ppt</atom:title>
<atom:author>
<atom:uri>uid=quikradm,o=default organization</atom:uri>
<atom:name>aa bb</atom:name>
<atom:email>quikradm@gmail.com</atom:email>
</atom:author>
<atom:link href="/lotus/poc/?uri=dm%3a18b90c0047dded508e259f15926dda5e&
pageHint=6_GQJU461028VI602DJC28AV00O7"
type="application/vnd.ms-powerpoint" hreflang="en"/>
<atom:category term="ContentSourceType/clb:clbDocument"
scheme="com.ibm.wplc.taxonomy://feature_taxonomy"
label="Document"/>
<opensearch:relevance>41.0</opensearch:relevance>
<atom:updated>2007-12-11T16:06:59.703+00:00</atom:updated>
<atom:id>/lotus/poc/?uri=dm%3a18b90c0047dded508e259f15926dda5e&
pageHint=6_GQJU461028VI602DJC28AV00O7</atom:id>
<atom:summary type="html"><ul class="property-list"><li><
span dir="ltr">Place:
someplace over the rainbow</span> - <span dir="ltr">Library:
<a class="action-links"
href="/lotus/poc/?uri=dm%3acb5bd40047ddb13cbd8cffdc14da9f2b"
>Library</span></a></li></ul></atom:summary>
<opensearch:image>/lotus/themes/html/QPG/icons/scope_search_docs.gif
</opensearch:image>
</atom:entry>
... more entries goes here ...
</atom:feed>
|
Figure 3 shows the list of search results for the issued query. The user can choose an item to share with his coworkers, or he can double-click it and go to the document page on the server.
Figure 3. Plug-in showing the search results for the query test
Sharing search results with coworkers
After you issue a search query, get back the list of results, and pick the relevant item from the list, you can share this item with others. Two options are available for sharing. The first option is to send the link through email by dragging the item from the search window into a Lotus Notes email. The other option is to select an item from the search window and click the Share button, which posts the selected item in the chat window. The second option is available only if the search window was opened from a chat window. Listing 5 shows the portion of code that adds the drag and drop capability to the search results table in the sample.
Listing 5. Partial code to add drag and drop functionality to the search results table
public DndSearchResult(final Control dragControl, final List entries) {
// Allow data to be copied or moved from the drag source
int operations = DND.DROP_MOVE | DND.DROP_COPY;
DragSource source = new DragSource(dragControl, operations);
Transfer[] types = new Transfer[] { RTFTransfer.getInstance()};
source.setTransfer(types);
source.addDragListener(new DragSourceListener() {
// ... here we implement the DragSourceListener methods
and handle RTFTransfer and FileTransfer
});
}
|
Figure 4 illustrates how a search result can be dragged and dropped from the plug-in search window to a Lotus Notes email. Figure 5 shows how a search result can be shared from the plug-in search window and sent to the chat window.
Figure 4. Dropped search result Quickr Developers Guide.zip into a Lotus Notes email
Figure 5. Selecting and sharing search result Quickr Developers Guide.zip through chat window
Getting feed for a search query
After searching and sharing content items from the Lotus Quickr server, you can also register your search query through a feed reader. The plug-in search application already has a special button for that purpose. Clicking the button opens your default Internet browser and presents the search results as an Atom feed. You can copy the link from the browser and add it to any other feed reader application you choose as shown in figure 6.
Figure 6. Open the search results as a feed in a browser
Conclusion
Lotus Quickr Search REST service offers a simple way to search and share content. Because the operations are done through REST, you can use your programming language of choice and your associated tooling support to quickly generate code for interacting with the remote server. This article demonstrates how to use the service to perform basic search operations, and it explains the basic pattern for each request and response message.
Download | Name | Size | Download method |
|---|
| com.ibm.lotus.search.feed_7.5.1.jar | 4329KB | HTTP |
Resources Learn
Get products and technologies
Discuss
About the author  | | | Eitan Shapiro holds a BSc degree in Information Systems Engineering from the Technion, Haifa, Israel. He joined IBM in 2005, and he is the team lead and chief programmer of the Lotus Quickr Search Technologies Team. |
Rate this page
| 
