Friday, October 16, 2015

Using IBM WCM 8.0 Query API - sample code

For our project we needed to make use of IBM Web Content Manager as a 'lightweight' document store, or Library, so users can search for their documents using search criteria. To allow us to do this we create a prof of concept using the Query API.

For the purpose of this blog I'm assuming you have a good understanding of how to create WCM ContentItems, Authoring Templates and the like, and that you're familiar with the terminology. You must also have a licensed Portal 8.0 with WCM 8.0 installation to play with.

Accessing WCM content

IBM Web Content Manager 8.0 has different means of accessing WCM Content:
  • Via the WCM REST API (out-of-the-box): WCM comes with a REST API that gives you access to most of the concepts, including content items, site areas and the like. For WCM 8.0 though, no facility is available to access or search by Categories.
  • Using the Java API: The Java API allows a lot more flexibility, including searching by categories. It is also a lot faster than the 'chatty' REST service. It includes Workspace 'findxxx' methods, or for more advanced cases, a Query API.
  • Using a WCM Content Viewer Portlet with Presentation template: This solution works fine for 'normal' content on the site. We wanted a completely custom UI though, and also surface the items in other standalone applications.


Content (library) requirements for the POC

We created some sample content in WCM to showcase the following:
  1. Search for content by keywords, or
  2. Search for content by categories, or
  3. Search for content by name(s), then
  4. Search for or limit results based on custom elements (e.g. text element)

Demo portlet

To make it easy to play with, we created a JSR286 Portlet with a simple JSP, deployed as a WAR directly on a Portal 8.0 environment (same virtual portal/portal as the WCM Library).

The demo code listed at the end of the blog demonstrates the following usage of the WCM Query API and Workspace.
  1. Use a WCM Workspace for a specific logged in user;
  2. Limit search results to a given WCM Library;
  3. Search for Content (Items) by category(ies), keyword(s) or name(s) - these are built-in fields or profile abilities of ContentItems;
  4. Filter the results on a custom Element (a text element) value (the Query API doesn't seem to support searching on Element in Documents directly).


Getting the project to work in your environment

Content

Before creating the portlet, be sure to have some WCM ContentItems with keywords, categories and the like available in a WCM Library where the user has access.

WAR

You will need to create a WAR with a JSR286 Portlet, with the appropriate Portal WCM jar (ilwwcm-api.jar), which should come with your Portal installation and be available in RAD or eclipse with Portal 8 Development stubs. So, your project should either have the correct maven dependencies or the Portal 8 libraries attached.

Once set up, you can copy the code into your portlet java class and your own JSP, deploy it and test.

References


Code listing

You can get the code as Gist here as well.
package sample.wcm.query.portlet;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.PortletRequestDispatcher;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.ResourceRequest;
import javax.portlet.ResourceResponse;
import org.apache.commons.lang.StringUtils;
import com.ibm.workplace.wcm.api.Category;
import com.ibm.workplace.wcm.api.Content;
import com.ibm.workplace.wcm.api.ContentComponent;
import com.ibm.workplace.wcm.api.DocumentId;
import com.ibm.workplace.wcm.api.DocumentLibrary;
import com.ibm.workplace.wcm.api.FileComponent;
import com.ibm.workplace.wcm.api.ImageComponent;
import com.ibm.workplace.wcm.api.Repository;
import com.ibm.workplace.wcm.api.TextComponent;
import com.ibm.workplace.wcm.api.WCM_API;
import com.ibm.workplace.wcm.api.Workspace;
import com.ibm.workplace.wcm.api.exceptions.ComponentNotFoundException;
import com.ibm.workplace.wcm.api.exceptions.OperationFailedException;
import com.ibm.workplace.wcm.api.exceptions.QueryServiceException;
import com.ibm.workplace.wcm.api.exceptions.ServiceNotAvailableException;
import com.ibm.workplace.wcm.api.query.Disjunction;
import com.ibm.workplace.wcm.api.query.ProfileSelectors;
import com.ibm.workplace.wcm.api.query.ResultIterator;
import com.ibm.workplace.wcm.api.query.Selectors;
/**
* A portlet that demos accessing content items with the Query API and doing filtering on Elements.
* @author RBester
*
*/
public class WcmQueryExamplePortlet extends GenericPortlet {
private static final String DOCUMENT_LIBRARY = "java-api-test-library";
private static final String NATIONAL_ID_ELEMENT_NAME = "nationalID";
@Override
public void serveResource(ResourceRequest request, ResourceResponse response) throws PortletException, IOException {
super.serveResource(request, response);
// comma-delimited list of content item names, category names, keywords and a custom element.
String contentNames = request.getParameter("contentNames");
String categoryNames = request.getParameter("categoryNames");
String keywords = request.getParameter("keywords");
String nationalIds = request.getParameter("nationalIds");
//Retrieve the workspace
Workspace workspace = null;
Repository repository = WCM_API.getRepository();
try {
// Use the logged-in user credentials to log in to the workspace
workspace = repository.getWorkspace(request.getUserPrincipal());
workspace.login();
// use a specific WCM library that is available on the Virtual portal
DocumentLibrary library = workspace.getDocumentLibrary(DOCUMENT_LIBRARY);
com.ibm.workplace.wcm.api.query.Query query = workspace.getQueryService().createQuery();
/*
* Select all content items for a specific library, with either categories, keywords or names as requested.
* Use a Disjunction (OR) compound selector to add the relevant Selectors to (categories OR keywords OR names)
*/
Disjunction or = addOrClauses(workspace, library, categoryNames, keywords, contentNames);
// limit to the library and Content, with the specified OR clause.
query.addSelector(Selectors.libraryEquals(library));
query.addSelector(Selectors.typeIn(Content.class));
query.addSelector(or);
// We're interested in the objects themselves (Document) and not the IDs (DocumentId)
query.returnObjects();
/*
* Filter the results on the provided custom element (TextElement) value.
* We need to filter, as there isn't a facility in the Query API to search on Document Elements.
*/
ResultIterator resultIterator = workspace.getQueryService().execute(query);
List<Content> content = packageContentInList(resultIterator);
// apply filter
content = filterByNationalId(content, nationalIds);
// print the results as HTML by traversing the Content Elements (previously known as ContentComponent and still that name in the API)
response.getWriter().write(generateDocumentList(content));
} catch (ServiceNotAvailableException e) {
e.printStackTrace();
} catch (OperationFailedException e) {
e.printStackTrace();
} catch (QueryServiceException e) {
e.printStackTrace();
} finally {
if (workspace != null) {
workspace.logout();
}
if (repository != null) {
repository.endWorkspace();
}
}
}
private Disjunction addOrClauses(Workspace workspace, DocumentLibrary library, String categoryNames, String keywords, String contentNames) {
Disjunction or = new Disjunction();
addCategoriesSelectors(workspace, library, or, categoryNames);
addKeywordSelectors(or, keywords);
addNamesSelectors(or, contentNames);
return or;
}
private void addCategoriesSelectors(Workspace workspace, DocumentLibrary library, Disjunction or, String categoryNames) {
if (StringUtils.isEmpty(categoryNames)) {
return;
}
try {
List<DocumentId> categories = findCategories(workspace, library, categoryNames);
or.add(ProfileSelectors.categoriesContains(categories));
} catch (QueryServiceException e) {
e.printStackTrace();
}
}
private void addKeywordSelectors(Disjunction or, String keywords) {
if (StringUtils.isEmpty(keywords)) {
return;
}
or.add(ProfileSelectors.keywordsContain(splitKeywords(keywords)));
}
private void addNamesSelectors(Disjunction or, String itemNames) {
if (StringUtils.isEmpty(itemNames)) {
return;
}
or.add(Selectors.nameIn(splitKeywords(itemNames)));
}
/*
* Loops through the content items and interrogates the ContentComponent (Element). If it's a TextElement (which it should be),
* the text should match our search criteria.
*/
private List<Content> filterByNationalId(List<Content> contentItems, String nationalIds) {
if (StringUtils.isEmpty(nationalIds)) {
return contentItems;
}
List<Content> toReturn = new ArrayList<Content>();
for (Content contentItem: contentItems) {
try {
ContentComponent contentComponent = contentItem.getComponent(NATIONAL_ID_ELEMENT_NAME);
if (containsContentText(nationalIds, contentComponent)) {
toReturn.add(contentItem);
}
} catch (ComponentNotFoundException e) {
System.out.println("component not found: " + e.getMessage());
}
}
return toReturn;
}
/*
* Match TextComponent's text with a comma-delimited list of search terms
*/
private boolean containsContentText(String textToScan, ContentComponent contentComponent) {
if (contentComponent instanceof com.ibm.workplace.wcm.api.TextComponent) {
String componentText = ((com.ibm.workplace.wcm.api.TextComponent) contentComponent).getText();
return textToScan.contains(componentText);
}
return false;
}
/*
* Casts and adds results to a List for convenience.
*/
private List<Content> packageContentInList(ResultIterator resultIterator) {
List<Content> toReturn = new ArrayList<Content>();
Object nextItem;
while(resultIterator.hasNext()) {
nextItem = resultIterator.next();
if (nextItem instanceof Content) {
toReturn.add((Content)resultIterator.next());
}
}
return toReturn;
}
/*
* Generate HTML to be printed
*/
private String generateDocumentList(List<Content> content) {
StringBuilder documentHtml = new StringBuilder();
for (Content contentItem : content) {
documentHtml.append(getContentDescription(contentItem));
}
return documentHtml.toString();
}
/*
* Tokenize the keywords/search terms
*/
private List<String> splitKeywords(String keywords) {
String [] splitKeywords = keywords.split(",");
return Arrays.asList(splitKeywords);
}
/*
* To search by categories, we need to first fetch all the categories' IDs, then use those in the query.
* Typically one could cache the categories so this lookup isn't needed all the time.
*/
private List<DocumentId> findCategories(Workspace workspace, DocumentLibrary library, String categories) throws QueryServiceException {
String[] categoriesSplit = categories.split(",");
com.ibm.workplace.wcm.api.query.Query query = workspace.getQueryService().createQuery();
query.addSelector(Selectors.typeIn(new Class[] {Category.class}));
query.addSelector(Selectors.libraryEquals(library));
query.addSelector(Selectors.nameIn(categoriesSplit));
query.returnIds();
ResultIterator resultIterator = workspace.getQueryService().execute(query);
List<DocumentId> toReturn = new ArrayList<DocumentId>();
while (resultIterator.hasNext()) {
toReturn.add((DocumentId) resultIterator.next());
}
return toReturn;
}
/*
* Returns html for ContentItem with text, an ImageComponent/Element and a FileComponent (e.g. pdf).
*/
private String getContentDescription(Content content){
String result = "";
try {
String[] componentNames = content.getComponentNames();
for(int i = 0; componentNames != null && i < componentNames.length; i++){
ContentComponent contentComponent = content.getComponent(componentNames[i]);
if(contentComponent instanceof TextComponent){
result += componentNames[i] + ": " + ((TextComponent)contentComponent).getText() + "<br>";
} else if(contentComponent instanceof ImageComponent){
result += componentNames[i] + ": <a href='" + ((ImageComponent)contentComponent).getResourceURL() + "'>Image</a><br>";
} else if(contentComponent instanceof FileComponent){
result += componentNames[i] + ": <a href='" + ((FileComponent)contentComponent).getResourceURL() + "'>File</a><br>";
}
}
result += "<br>";
} catch(ComponentNotFoundException e){
e.printStackTrace();
}
return result;
}
@Override
protected void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException {
PortletRequestDispatcher dispatcher = getPortletConfig().getPortletContext().getRequestDispatcher("/WEB-INF/jsp/WcmQueryUtilitiesPortlet.jsp");
dispatcher.forward(request, response);
}
}
view raw WcmQueryExamplePortlet.java hosted with ❤ by GitHub
<%@ page contentType="text/html" pageEncoding="UTF-8" language="java"%>
<%@ taglib prefix="portlet" uri="http://java.sun.com/portlet_2_0"%>
<portlet:defineObjects/>
<form method="post" action='<portlet:resourceURL />'>
Content name(s): <input type="text" name="contentNames">
Category(ies): <input type="text" name="categoryNames">
Keyword(s): <input type="text" name="keywords">
National IDs(s): <input type="text" name="nationalIds">
<input type="submit" value="submit">
</form>
view raw WcmQueryExamplePortlet.jsp hosted with ❤ by GitHub



Posted by at

5 comments:

Subscribe to: Post Comments (Atom)