Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

You should have a good understanding of Lotus Quickr services for WebSphere® Portal V8.1, Java™ Platform, Enterprise Edition (Java EE) development, the IBM Lotus Web Content Management API, and the Struts v1.2 to follow this article.

Introduction

Lotus Quickr services for WebSphere Portal (henceforth called as Lotus Quickr in this article) provides collaborative services that make it possible to create, manage, update, search, query, and delete Lotus Quickr content. These services are based on the Representational State Transfer (REST) architecture and support the Atom Syndication Format and the Atom Publishing Protocol (APP). This support allows Lotus Quickr to expose its content as Atom feeds.

This article shows you how to write a new Atom feed to fetch the content of a component in Lotus Quickr and deploying it to Lotus Quickr. This feed allows users to specify a criterion for filtering the content using query parameters. This article gives you a glimpse of what is possible with this technology. While the sample code for this application is provided in the Downloads section of this article, it is up to you to customize the feed further.

Back to top

Before you start

For creating a new Atom feed, you need administrative access to the Lotus Quickr server. Lotus Quickr comes with many Atom feeds. The section that follows describes how to write a custom feed for Lotus Quickr and how to deploy the same. The entire application is a few hundred line of code, but we ask you to code only the important components; the rest are provided. The steps are as follows:

1. Extend the Struts action class to handle the HTTP request
2. Implement a NewFeedWCMResolver.java file, which processes the request and creates the Atom document
3. Modify the Struts configuration to register the new action
4. Package the code and deploy it to Lotus Quickr

Back to top

Setting up

This article assumes that you use the IBM Rational® Application Developer V7 for developing the Web application, but you are free to use any application to edit and deploy the Web application. Nothing in this exercise is tool-specific. You also need to have Lotus Quickr 8.1 installed and the WebSphere Portal therein to be configured with Rational Application Developer V7 as the WebSphere Portal V6.0 runtime environment.

Back to top

Configuring the project and import files

The first step toward writing the new Atom feed is setting up the project. You need to create a Web project that can later be exported as an EAR file. This section shows you the configuration of the IBM Rational® Application Developer project. Follow these steps:

1. Start Rational Application Developer.
2. Select File - New - Other, and then locate and select Dynamic Web Project on the Select a wizard step. Click Next.

   NOTE: Select the Show All Wizards option if you do not see the Portal section.

3. For the Dynamic Web Project step, enter the following information and click Next.
   
   
   • In the Project name field, enter NewAtomFeed.
   • In the Target Rutime field, select WebSphere Portal v6.0.
   • In the Configurations field, select <custom>.
   • Select the Add project to an EAR option.
   • In the EAR Project name field, enter NewAtomFeedEAR.
4. For the Project Facets step, select the following two project facets:
   
   
   • Dynamic Web module (version 2.4)
   • Java (version 1.4)

   NOTE: Ensure that the versions of these project facets are exactly as mentioned here.

5. Click Finish to save the changes.
6. If you see a message that says "This type of project associated with the web perspective," click Yes.

You should see the two projects shown in figure 1, created in your current workspace.

Back to top

Setting up your enterprise application EAR file

After you create the Rational Application Developer project, your next step is to set it up completely before you start writing your code. Lotus Quickr comes with a Web application called ilwwcm-atompublishing.war that contains Atom content feeds that are ready to use without modification. You create a copy of this Web application to automatically bring in most of the configurations. You have to modify the Struts configuration and the deployment descriptor of the EAR file to complete the setup.

Follow these steps:

1. Right-click the NewAtomFeed project in the Project Explorer tab, and select Import - Import.
2. In the Import page that displays, select General - File System and then click Next.
3. In the Import page that displays, select the ilwwcm-atompublishing.war folder. Following is the path to the ilwwcm-atompublishing.war folder inside the Lotus Quickr installation’s root directory:
   <quickr_root>/wp_profile/installedApps/<node_name>
/wcm.ear/ilwwcm-atompublishing.war
4. In the field Select a folder to import into, enter "NewAtomFeed/Webcontent" as shown in figure 2. Click OK to continue.
   
   

   NOTE: Click Yes to All if the Overwrite paes display.

   
   
   Figure 2. Import ilwwcm-atompublishing.war file in WebContent folder
   
   
   
5. On the page that displays, keep the default values and click Finish to save your changes.
6. Select Windows - Preferences, and then on the Preferences window that displays, select Java - Compiler. Change the Compiler compliance level field value to 1.4 as shown in figure 3.
   
   
   
   Figure 3. Setting Java compiler level preferences
   
   
   
7. On the Project Explorer tab, right-click the NewAtomFeed project and select Properties to add class libraries to the build path.
8. In the Properties wizard, select the Java Build Path option and select the Libraries tab as shown in figure 4.
   
   
   
   Figure 4. Java Build Path wizard
   
   
   
9. Click Add External JARs to add the following JAR files as shown in figure 5:
   
   • <quickr_root>/PortalServer/wcm/shared/app/ilwwcm-commons-properties.jar
   • <quickr_root>/PortalServer/wcm/shared/app/ilwwcm-commons-utils.jar
   • <<quickr_root>/PortalServer/wcm/shared/app/ilwwcm-nls-filter.jar
   • <quickr_root>/PortalServer/wcm/shared/app/ilwwcm-server.jar
   
   
   Figure 5. Java Build Path wizard for the NewAtomFeed project
   
   
   
10. Click OK to save your changes.
11. Open the Deployment Descriptor to open the application.xml or open the application.xml file explicitly for the project NewAtomFeedEAR. See figure 6.
    
    
    
    Figure 6. Project explorer view of NewAtomFeedEAR
    
    
    
12. Go to the Module view.
13. Select the NewAtomFeed module to populate the Context root field. In the Context root field enter "/lotus/customfeed" as shown in figure 7.
    
    
    
    Figure 7. Context root setting of NewAtomFeed module
    
    
    
14. Then, go to the Security view by clicking the Security tab at the bottom.
15. In the Security Roles section, add one security role with the name All Role and the description All Authenticated users in the enterprise. Alternatively, you could go to the source view by clicking the Source tab and manually adding a security role by using the XML fragment shown in listing 1. Click Finish to continue.

<security-role >
	<description>All Authenticated users in the enterprise.</description>
	<role-name>All Role</role-name>
</security-role>

16. Save the application.xml file.
17. Optionally, you can delete the ilwwcm-atompublishing.jar file from the Web application library folder whose path is shown here: <RAD_Workspace _root>/NewAtomFeed/WebContent/WEB-INF/lib/ilwwcm-atompublishing.war

    NOTE: This step is optional. You can choose to keep the JAR file in the Web application.

Back to top

Creating your own classes for the new feed

The Web application that you imported into your project in the previous section uses the Struts framework. Therefore, you extend the Struts framework to create your new feed. You need to create a servlet that handles all requests to Atom feeds for this new Web application. Then you create your own action class, which extends the base Struts action class org.apache.struts.action.Action.

Your new action class uses a resolver class that processes the request and builds the Atom feed. You also need a utility class for creating appropriate URLs in your feed.

Follow these steps:

1. Select Windows - Open Perspective - Web to go to the Web perspective.
2. Create a new package by right-clicking Java Resources: src in the NewAtomFeed project, on the Project Explorer tab, and then selecting New - Package.
3. In the Name field, enter "com.ibm.test.wcm.app.atom.servlet". Click Finish.
4. Create a new class by right-clicking the package com.ibm.test.wcm.app.atom.servlet and then select New - Class.
5. In the New Java Class wizard, do the following:
   
   
   • Enter AuthServlet in the Name field.
   • Enter org.apache.struts.action.ActionServlet in the Superclass field.
   • Select the Constructors from superclass and Inherit abstract methods fields See figure 8.
   
   
   Figure 8. AuthServlet Class settings
   
   
   
6. Click Finish to create the class.
7. Create a new package by right-clicking Java Resources: src in the NewAtomFeed project and then selecting New - Package.
8. Enter com.ibm.test.wcm.app.atom.util in the Name field and click Finish.
9. Create a new class by right-clicking on the package com.ibm.test.wcm.app.atom.util and then selecting New - Class.
10. In the New Java Class wizard, do the following:
    
    
    • Enter AtomURLBuilder in the Name field.
    • Enter java.lang.Object in the Superclass field.
    • Select the Constructors from superclass and Inherit abstract methods fields See figure 9.
    
    
    Figure 9. AtomURLBuilder class settings
    
    
    
11. Click Finish to create the class.
12. Create a new package by right-clicking Java Resources: src in the NewAtomFeed project and then selecting New - Package.
13. Enter com.ibm.test.wcm.app.atom.actions in the Name field and click Finish.
14. Create a new class by right-clicking the package com.ibm.test.wcm.app.atom.actions and then selecting New - Class.
15. In the New Java Class wizard, do the following:
    
    
    • Enter NewFeedAction in the Name field.
    • Enter org.apache.struts.action.Action in the Superclass field.
    • Select the Constructors from superclass and Inherit abstract methods fields as shown in figure 10.
    
    
    Figure 10. NewFeedAction class settings
    
    
    
16. Click Finish to create the class.
17. Create a new package by right-clicking Java Resources: src in the NewAtomFeed project and then selecting New - Package.
18. Enter com.ibm.test.wcm.app.atom.resolver in the Name field and click Finish.
19. Create a new class by right-clicking the package com.ibm.test.wcm.app.atom.resolver and then selecting New - Class.
20. In the New Java Class wizard, do the following:
    
    
    • Enter NewFeedWCMResolver in the Name field.
    • Enter java.lang.Object in the Superclass field.
    • Select the Constructors from superclass and Inherit abstract methods fields as shown in figure 11.
    
    
    Figure 11. NewFeedWCMResolver class settings
    
    
    
21. Click Finish to create the class.

Back to top

Completing the code

Now that the Web application is set up, you can start to code the internal classes of the Atom feed. You have already created four Java classes for this purpose.

The servlet class is the starting point for the Atom feed request processing. The purpose of the AuthServlet class, as its name suggests, is to ensure that the user is authenticated before the request is redirected to the action class. The servlet class also ensures that when the request reaches the action class it is over a protected servlet path (/myatom).

The AuthServlet class is the common authentication servlet for all Atom feeds created under the NewAtomFeed Web application. The AuthServlet class extends the org.apache.struts.action.ActionServlet class, and it overrides the process() method. The process() method is the method used for performing the standard request processing and generating the corresponding response. See listing 2.

protected void process(HttpServletRequest p_request, HttpServletResponse p_response) 
        throws IOException, ServletException 
    { 
        try 
        { 
                // check if user is authenticated 
  
                // if user is authenticated check if servlet path 
  
// if user is authenticated and servlet path is protected servlet path, 
// then redirect request so that it can 
// be processed by struts Action 
                
    } 

The action class is the one that is registered with the Struts configuration and therefore called when a request is received after it is redirected by the AuthServlet. The overridden method execute(), which is inherited from the super-class org.apache.struts.action.Action, is called for processing the request.

In the execute() method, you first determine the method of request. Only Get and Head requests are considered valid, according to the APP specification. If the incoming request is either Get or Head, then the header in the response object is set and then forwards this request to the get() method. The get() method then processes this request. See listing 3.

public ActionForward execute(ActionMapping mapping, ActionForm aform, 
HttpServletRequest request, HttpServletResponse response) throws Exception
{
    ActionForward forward = null;
    response.setHeader("Server", "Teamspace Web Content 1.0");
    String httpMethod = request.getMethod();
    if(httpMethod.equalsIgnoreCase("GET"))
    {
	m_isHead = false;
	forward = get(mapping, aform, request, response);
    } else
    if(httpMethod.equalsIgnoreCase("HEAD"))
    {
	m_isHead = true;
	forward = get(mapping, aform, request, response);
    } else
    {
	response.setStatus(405);
	response.setHeader("Allow", "GET, HEAD");
	return null;
    }
    return forward;
}

In the get() method, you first extract all the useful information from the request that is passed as query parameters. Then you create an instance of the Lotus Web Content Management repository for the authenticated user. In the sample code, shown in listing 4, you also use a utility class com.ibm.test.wcm.app.atom.util.AtomURLBuilder that has methods that help you build URLs that point back to the Lotus Quickr server. All this data (that is, query parameters, Lotus Web Content Management repository instance, and AtomURLBuilder instance) is then passed to the getFeed() method of the NewFeedWCMResolver class where the Atom document is built. The Atom document that is returned by the NewFeedWCMResolver class is then sent back as a response to the browser. See listing 4.

public ActionForward get(ActionMapping actionMapping, ActionForm actionForm, 
HttpServletRequest request, HttpServletResponse response) throws Exception
{
	/*
	*	..... fetch query parameters data ....
	*/

	/*
	*	..... create instance of WCM repository .... 
	*/
	
	/*
	*	..... create instance of AtomURLBuilder  utility .... 
	*/

	/*
	*	..... pass all the data captured from query params and the instaces of 
	*	WCM repository and AtomURLBuilder  utility to  getFeed method of 
*	NewFeedWCMResolver class  .... 
	*/
	
	/*
	*	..... send the atom document as response back to the browser 
	*/
}

The getFeed() method of NewFeedWCMResolver class first fires a query on Lotus Web Content Management to fetch the content of the selected component type from all the teamplaces in which the authenticated user is a member. The Atom document is built starting with the headers section and then followed by the entries. The filtering is done while the entries are added to the Atom document. This Atom document is then returned to the NewFeedAction class. See listing 5.

NOTE: While creating the atom field, you need to be cautious about the values (data) that you populate in the feed. Some characters such as an empty space " " are not accepted by some elements of the Atom feed. Refer the Resources section for more information on the Atom Publishing Protocol.

public Feed getFeed(Workspace p_workspace, AtomURLBuilder p_urlBuilder, 
Locale locale, String p_atName, String p_optionAttr, 
String p_optionVal, HttpServletRequest p_request) throws AuthorizationException, 
InvalidIdException, AtomException
{
	/*
	*	..... query WCM for fetching content of the selected 
	component type for the authenticated user ....
	*/

	/*
	*	..... add header elements to the Atom document  .... 
	*/
	
	/*
	*	..... add header elements to the Atom document  .... 
	*/

	/*
	*	..... pass all the data captured from query params and the instaces of 
	*	..... WCM repository and AtomURLBuilder  utility to  getFeed method of 
	NewFeedWCMResolver class .... 
	*/
	
	/*
	*	..... return the atom document back to the NewFeedAction class 
	*/
}

NOTE: The source code for the four classes is provided as a file in the Downloads section of this article. The files names are as follows:

• AuthServlet.java
• NewFeedAction.java
• NewFeedWCMResolver.java
• AtomURLBuilder.java

Back to top

Registering the new servlet class with the Web deployment descriptor

The new servlet class needs to be registered with the Web deployment descriptor. Because you have created your Web application from an existing Web application, the appropriate entry for this servlet already exists in the Web deployment descriptor. You change only the class attribute to point it to the new servlet class AuthServlet.

Follow these steps:

1. Open the Web Deployment Descriptor to open the web.xml or open the web.xml file explicitly for the project NewAtomFeed.
2. Go to the Servlets view.
3. Select the WCM Atom Publishing servlet.
4. Click the Browse button next to the Servlet class field to change the value of this attribute. See figure 12.
   
   
   
   Figure 12. Servlets view of web.xml file
   
   
   
5. In the Select Servlet or JSP wizard, do the following:
   
   
   • Enter AuthServlet in the Choose a servlet field.
   • Select the servlet class AuthServlet in package com.ibm.test.wcm.app.atom.servlet to change the Servlet Class attribute of this servlet.
6. Save the web.xml file.

Back to top

Registering the new action class with the Struts configuration

The new action class that you created needs to be registered with the Struts configuration. The Struts configuration is defined in the struts-config-atom.xml file. A mapping of the action class with the URL path is registered with the Struts configuration so that all requests with a matching path are sent to the mapped action class for processing.

Follow these steps:

1. Open the struts-config-atom.xml file in the NewAtomFeed project.
2. Remove all three action mappings from the action-mappings element. Add a new action mapping for the new feed as shown in listing 6.

<action path="/newfeed/*" 
type="com.ibm.test.wcm.app.atom.actions.NewFeedAction" />

3. Save the struts-config-atom.xml file.

Back to top

Deploying the new Atom feed EAR file

Now that the application is ready for deployment, you must do a full build and then export the application as an EAR file. After that is done, use the WebSphere Application Server console to deploy the exported EAR file to the WebSphere_Portal application server. Remember that you must start the deployed application explicitly before you can use it. Similarly, if you redeploy the EAR file for any reason, you must restart the application for the changes to take effect.

Follow these steps:

1. Right-click the NewAtomFeedEAR project and select Export - EAR file.
2. Select the NewAtomFeedEAR project in the EAR application, and enter the EAR destination path in the Destination field in the Export wizard. See figure 13.
   
   
   
   Figure 13. Exporting the application as ear file
   
   
   
3. Click Finish to export the project as NewAtomFeed.ear in the selected path.
4. Log in to the WebSphere Application Server administration console.
5. Select Application - Enterprise Applications as shown in figure 14.
   
   
   
   Figure 14. WebSphere Application Server admin console
   
   
   
6. The page Preparing for the application installation displays; this page is where you can install the newly created EAR file. Click Next.
7. A new page, shown in figure 15, displays where you can set the default bindings and mappings. Do the following:
   
   
   • Select the Generate Default Bindings field
   • Select the Override existing bindings field
   • Select the Use default virtual host name for Web modules field
   • Click Next to continue.
   
   
   Figure 15. Default binding settings
   
   
   
8. The page for Step 1, Select installation options, displays. Don’t make any changes to the default settings. Click Next to continue.
9. The page for Step 2, Map modules to servers, displays. Do the following as shown in figure 16:
   
   
   • Select the second field, WebSphere: cell=ykare, node=<node_name>,server=Websphere_Portal, in the Clusters and Servers section.
   • Select the check box under the Select heading.
   • Click Apply.
   • Click Next to continue.
   
   
   Figure 16. Mapping module to server
   
   
   
10. The page for Step 3, Map virtual hosts for Web modules, of the wizard displays. Keep the default values and click Next to continue.
11. The page for Step 4, Map security roles to users/groups, of the wizard displays. Do the following as shown in figure 17:
    
    
    • Select the All authenticated? check box for All Role.
    • Click Next to continue.
    
    
    Figure 17. Mapping Security roles to user/groups
    
    
    
12. The summary page of the installation wizard displays. Click Finish.
13. The installation summary page displays. Click the Save to Master Configuration link as shown in figure 18.
    
    
    
    Figure 18. Installation summary page
    
    
    
14. Click the Save button. This action takes you back to the Enterprise Application view.
15. Start the application that you installed in the previous step.

Back to top

Using your new Atom feed

You now have a finished deployment for the new Atom feed. You can test it using the following URL:

The sample URL for the announcement personalize feed is as follows:

• <host>: Host name or IP
• <port>: Port number (default value 10038)
• <authoring_template_name>: Name of the authoring template for the component
• <element_name>: Element name by which filtering should be done. This element should be of type OptionSelection.
• <element_value>: Value by which filtering should happen.

Back to top

Conclusion

This article discussed how to create a new Atom feed to fetch Lotus Quickr content. You used the existing ilwwcm-atompublishing.war file to create a new project for your new feed. Then you configured the application to support the new feed by modifying the application.xml and the struts-config-atom.xml files. Next you implemented the two Java classes, NewFeedAction.java and NewFeedWCMResolver.java. Last, you learned how to deploy the application and then test it.

Back to top

Downloads

Information about download methods

Resources

• Participate in the discussion forum.
  
  
• Read the developerWorks® article, "Introducing IBM Lotus Quickr REST services."
  
  
• Read the developerWorks article, " Working with components in IBM Lotus Quickr, part 1: Creating a news component."
  
  
• Read the developerWorks article, " Working with components in IBM Lotus Quickr, part 2: Creating a personalized view of the announcement component."
  
  
• Read the developerWorks article, " Getting to know the Atom Publishing Protocol, Part 3: Introducing the Apache Abdera project."
  
  
• Read the Lotus Quickr documentation, "IBM Lotus Quickr Developer's Guide."
  
  
• Refer to the Lotus Quickr product documentation.
  
  
• Refer to the Lotus Quickr product page.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Introduction
• Before you start
• Setting up
• Configuring the project and import files
• Setting up your enterprise application EAR file
• Creating your own classes for the new feed
• Completing the code
• Registering the new servlet class with the Web deployment descriptor
• Registering the new action class with the Struts configuration
• Deploying the new Atom feed EAR file
• Using your new Atom feed
• Conclusion
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Quickr
• Demo: Lotus Quickr
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Quickr

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers