From the IBM WebSphere Developer Technical Journal.

Introduction

Beginning with Version 6.1, the IBM® WebSphere® Application Server administrative console is based on the Integrated Solutions Console, which provides a single, common interface framework for system administration. By using this common framework, other products (IBM and non-IBM) are provided with a platform in which their administrative user interfaces can be deployed as additional modules. Administration functions sharing this platform will have a common look and feel and consistent behavior.

The main benefits of using the Integrated Solutions Console are:

• Enables consistent user interaction for administering products.
• Modules are developed using the Java EE standard for Web applications and JSR168 standard for portlet application development.
• Deployment is simple, as all the needed information is contained in XML files.
• Standards-based architecture and the common framework reduce the time required to implement solutions.
• Using a common interface for administration reduces time and expense required for training administrative personnel.

Console modules are Web applications that are accessed not from a URL, but from the Integrated Solutions Console itself. Developing console modules requires Java EE and portlet development skills, plus some HTML skills to understand how contents in a page are created and how forms work. This article will step through the creation of a console module, illustrating the tools and techniques along the way that can simplify the process.

Setting up the environment

In explaining how to develop console modules, we will use the Application Server Toolkit, which is a component part of WebSphere Application Server V6.1. This tool, which in previous versions of WebSphere Application Server was provided mostly for application packaging, has had its capabilities increased with the inclusion of Java Development Tools, with which it is now possible to develop Java classes, JSP pages, Web services, and so on.

As an aid for creating the layout and security XML descriptors, you will need to install the Integrated Solutions Console Portal Application Archive (PAA) Visual Designer Plug-in in this environment. To install the plug-in file once you have it downloaded, you only need to unpack its contents inside the eclipse folder in the Application Server Toolkit installation directory.

Back to top

Console module development

The construction of a new module for your Integrated Solutions Console needs the creation of a Portlet JSR168 project. This project will be the container for one or more portlets which will be later placed inside the pages of your console module. Once you have created and placed your portlets, you need to define each role's access to the functionalities provided by your module.

Project creation

There are two APIs for portlet development. One is IBM's own API and the other is the one compliant with the JSR168 standard. Both are similar, although the latter one is still being developed and does not provide all the functionalities available with IBM's API. However, IBM is committed to JSR168 and has deprecated its own API.

In any case, console modules need to be created using the JSR168 API which is, by the way, the only API supported by the Application Server Toolkit development environment.

1. From the Application Server Toolkit development environment, select File => New and then Portlet Project in the wizard list (Figure 1). Press Next.

   
   
   Figure 1. Select Portlet Project wizard
   
   
   

2. In the Portlet Project page (Figure 2), specify the name for your project, such as ISCDemo. As it is a Portlet project and not a Dynamic Web project, you do not need to have an Enterprise Application (nor its corresponding EAR file) created.

   
   
   Figure 2. Specify project name
   
   
   

3. By default, a portlet will also be created with the same name in your project (Figure 3). Press Next.

   
   
   Figure 3. Specify portlet name
   
   
   

Portlets to a Web-based environment are like windows to a graphical operating system. As such, they have different states (normal, maximized, minimized), but they also have what are known as modes. Modes are different ways of displaying information. The most common modes are view, edit, and help: View is used to display information, while Edit is used for setting up the parameters that will later determine the portlet behaviour, and Help is used to provide information that might be useful for the user.

4. In the next wizard step, specify which of these modes to implement in your portlet. By default, only the View mode will be selected. Provide your sample portlet with the Edit and Help modes as well.

   
   
   Figure 4. Specify modes to implement in portlet
   
   
   

5. You must also provide the name for the class that will implement the control in your portlet and the package where it will be placed (Figure 5). (The Application Server Toolkit will not create a Java bean for the Model part, but the Rational® Application Developer wizard for portlets will create it. Either way makes no difference here, as we will not be using it in this article.)

   
   
   Figure 5. Name portlet class
   
   
   

6. Finally, you need to specify the languages that will be supported by your module. Include the languages needed by selecting the Add button in the Locale-specific information section, provide the requested information, and then press OK. (We will not use this feature in our example.) Languages and modes may be specified in the module development phase or later, during development, by modifying the portlet deployment descriptor in your project.

7. When all the information has been provided, click Finish to start creating the project.

Portlet development

Portlet development is based on the Model View Controller (MVC) paradigm. Applications following this paradigm consist of three related parts.

• The Model part represents the logical structure of the information in an application.
• The View part is the representation of the user interface.
• The Controller part is the one in charge to connect Model and View.

The practical implementation of this paradigm would happen, then, through the creation of a Java bean that encapsulates the model data, several JSPs that provide the View interface, and one Java class controlling the operation of the application.

As for the Java class, a portlet works in a similar way to a servlet; instead of having doGet() and doPost() methods, we will have doView(), doEdit() and doHelp() methods. Each of these methods will be called when the portlet needs to be displayed in the corresponding mode. The wizard creates these methods for you depending on the available modes that you selected for your portlet.

Notice that the wizard created an additional method called processAction. This method will be responsible for processing the data received in the portlet when, for example, a form is submitted.

Java bean

In the Java bean, keep just the model information. In this example, we are storing a string. Create a new class in your project, add a String instance variable, and generate getters and setters for that variable. The source code for your Java bean, then, will look similar this:

package isc.demo;
public class ISCDemoPortletBean {
	String text=null;
	public String getText() {
		return text;
	}
	public void setText(String text) {
		this.text = text;
	}
}

JSP pages

You need at least one JSP for every mode you need to provide to your portlet. In our example, you will be creating three JSPs:

1. Select your project and then in the context menu, select New => JSP.

2. Name your JSP files, for example: ISCDemoPortletView.jsp, ISCDemoPortletEdit.jsp and ISCDemoPortletHelp.jsp. You can use any other name for your pages, but this type of naming convention makes it easier to remember its function.

3. When you create JSPs for portlets, they are created as fragments. This means that a complete HTML output will not be created. A JSP fragment has no <HTML>, <HEAD>, or <BODY> tags. You just provide the contents.

   For every JSP created, include the header below. You are describing the contents, referencing your classes, and including both the portlet class and tags libraries.

   <%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1" session="false" buffer="none"%> <%@ page import="javax.portlet.*,isc.demo.*" %> <%@ taglib uri="http://java.sun.com/portlet" prefix="portletAPI" %> <portletAPI:defineObjects/>

   
   

   We have added the <portletAPI:defineObjects/> tag, which will define some useful objects you will be using in your code, such as renderRequest.

4. The View mode JSP page will display the content of two attributes stored in the session and will also recover and display the content of the string in our model bean. Your code should look similar to this:

   <H3>View Mode</H3> <TABLE> <TR><TD>Portlet Mode:</TD><TD><%= request.getAttribute("Mode") %></TD></TR> <TR><TD>Window State:</TD><TD><%= request.getAttribute("State") %></TD></TR> <% ISCDemoPortletBean bean= (ISCDemoPortletBean) renderRequest.getPortletSession().getAttribute(ISCDemoPortlet.BEAN); if (bean!=null) { String value= bean.getText(); if (value!=null) { %> <TR><TD>Configuration value:</TD><TD><%= value %></TD></TR> <% } } %> </TABLE>

   
   

5. For the Edit mode JSP, include an HTML FORM. In this form, you will include a single text field. This field will be stored in the model bean when the form is submitted. The only thing different in a FORM when placed inside a portlet is that you need to specify the ACTION attribute using the portletAPI:actionURL tag. This way, when the FORM is submitted, the processAction method in your control Java class will be invoked.

6. Copy the contents of the View mode JSP in your Edit mode JSP. Just change the <H3> title and add an HTML Form. Your finished page will look similar to this:

   <H3>Edit Mode</H3> <TABLE> <TR><TD>Portlet Mode:</TD><TD><%= request.getAttribute("Mode") %></TD></TR> <TR><TD>Window State:</TD><TD><%= request.getAttribute("State") %></TD></TR> </TABLE> <% ISCDemoPortletBean bean= (ISCDemoPortletBean) renderRequest.getPortletSession().getAttribute(ISCDemoPortlet.BEAN); if (bean!=null) { String value= bean.getText(); %> <FORM ACTION="<portletAPI:actionURL/>" METHOD="POST"> <LABEL for="<%=ISCDemoPortlet.TEXT%>">Configuration value: </LABEL><BR> <INPUT name="<%=ISCDemoPortlet.TEXT%>" value="<%=value%>" type="text"/><BR> <INPUT name="<%=ISCDemoPortlet.SUBMIT%>" value="Save" type="submit"/> </FORM> <% } %>

   
   

7. In our example, you are using the same code for your Help mode JSP that you used for your View mode JSP. Just copy the contents in the new file and change the title provided in the <H3> tag.

Java class

Your Java class will extend javax.portlet.GenericPortlet and three processes that need to be implemented, one for each mode. These methods are very similar to the doGet and doPost methods in a servlet. They will be called by the server each time any of its corresponding modes have to be rendered.

Since the three methods are very similar, we will only illustrate the creation of doView.

1. Create a new method called doView. Recover the PortletMode and WindowState values using request accesors and place them as session attributes to make them available from the JSPs.

2. Next, you need to know which JSP is going to provide the contents for your portlet. Create a new PortletRequestDispatcher from the PortletContext providing the name and path of the JSP:

   PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher("/jsp/html/ISCDemoPortletView.jsp"); rd.include(request,response);

   
   

   The path for your JSP is related with the contextroot option you use in the deployment phase. We are using "/" here as our contextroot. If you specify ISCDemo, then, when creating the PortletRequestDispatcher, the path to your page would be /ISCDemo/jsp/html/ISCDemoPortletView.jsp.

   Your method should look similar to this:

   /** * Serve up the <code>view</code> mode. * * @see javax.portlet.GenericPortlet#doView(javax.portlet.RenderRequest, javax.portlet.RenderResponse) */ public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException { System.out.println(">>ISCDemoPortlet.doView"); ISCDemoPortletBean bean= getBean(request); if (bean!=null) { System.out.println("\tISCDemoPortlet.doView.bean: "+bean); } PortletMode mode = request.getPortletMode(); request.setAttribute("Mode",mode.toString()); WindowState state = request.getWindowState(); request.setAttribute("State",state.toString()); response.setContentType(request.getResponseContentType()); PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher("/jsp/html/ISCDemoPortletView.jsp"); rd.include(request,response); System.out.println("<<ISCDemoPortlet.doView"); }

   
   

3. Once you have your doView, doEdit and doHelp methods, you need one more to process all the events received by your portlet.

   Create a new method and name it processAction. Inside this method, you need to distinguish among different events. Check if there is a parameter called "submit" in your request to find out if the event has been generated by your form. Once you are sure that it is your form action event, recover the input form value and place it in the model bean. This method will look similar to this:

   public void processAction(ActionRequest request, ActionResponse response) throws PortletException, java.io.IOException { System.out.println(">>ISCDemoPortlet.processAction"); if( request.getParameter(SUBMIT) != null ) { System.out.println("ISCDemoPortlet.processAction.TEXT: "+request.getParameter(TEXT)); try { getBean(request).setText(request.getParameter(TEXT)); System.out.println("ISCDemoPortlet.processAction.prefs.Bean.TEXT: "+getBean(request).getText()); } catch(Exception ex ) { System.out.println("ISCDemoPortlet.processAction.Exception: "); ex.printStackTrace(); } } System.out.println("<<ISCDemoPortlet.processAction"); }

   
   

4. You will also be using an accessory method to recover your model bean. This method will check if an instance of this bean has not yet been created and will place a reference to the bean as a session attribute:

   public ISCDemoPortletBean getBean(PortletRequest request) { PortletSession session = request.getPortletSession(); if( session == null ) { System.out.println("ISCDemoPortlet.getBean. Session is null"); return null; } ISCDemoPortletBean bean = (ISCDemoPortletBean)session.getAttribute(BEAN); if(bean == null) { System.out.println("ISCDemoPortlet.getBean. Bean is null"); bean= new ISCDemoPortletBean(); session.setAttribute(BEAN,bean); } System.out.println("ISCDemoPortlet.getBean. Bean: "+bean); return(bean); }

   
   

Layout definition

Once you have created your new portlet, the next step consists of creating the layout of pages in your module.

1. Open the ISC Module Configuration folder in your project (Figure 8). You will see that there are two files inside: ibm-portal-security.xml and ibm-portal-topology.xml, which are the XML descriptors needed for describing access control and page layout. Open either of these to access the ISC module configuration wizard.

   
   
   Figure 8. XML descriptor files
   
   
   

2. This wizard has three tabs. In the first (default) tab, General Information (Figure 10), specify the name for the application in the Application title field, then select Lead Application. If the application was a child of another application, or if there were no other related applications, you would have selected a different configuration option.

   
   
   Figure 9. ISC module configuration wizard, General Information
   
   
   

   In this first sample you will create just a lead application and only specify the application title, an application identifier, and its version. This application identifier will be useful for chaining child applications or referencing it as a prerequisite for other applications.

3. To describe your page structure, select the Layout tab (Figure 10).

   
   
   Figure 9. ISC module configuration wizard, General Information
   
   
   

   In this tab, you will add the content for your module. There will always be an About Page where you could add a portlet introducing your module. This page is not necessary here.

4. Add new content by opening the context menu when the mouse cursor is hovering over the column on the left (Figure 11). There are different elements which might be added.

   
   
   Figure 11. Add elements
   
   
   
   • Pages are where you will place portlets you have created.
   • URLs are useful for creating links to Web pages from the administrative console.
   • Labels let you create more complex structures for your module. You will use labels for grouping pages, URLs, or new labels.
   
   
   Figure 12. Labels for grouping
   
   
   

5. The Properties option in the context menu will show you the properties for every item. From the Properties view you might change the title of your page or its visibility.

   
   
   Figure 13. Properties option
   
   
   

6. As you create your content structure, an outline of this content layout will be created and its elements displayed in a window in your development environment (Figure 14).

   
   
   Figure 14. Content outline
   
   
   

7. When the page structure is finished, you can add the contents. Before adding any portlets, you will define how the content layout will appear by using row and column containers. If row containers are used, portlets are placed one upon the other, whereas column containers set them one next to the other. Each page you create has a default row container.

   
   
   Figure 15. Page structure containers
   
   
   

   Add new containers by selecting the container where you want to place them, then select the Row Container or Column Container option from the context menu. Use this same method to add portlets to an existing container. (If you miss the container orientation, you can change it later from its Properties view.)

   
   
   Figure 16. Modify containers
   
   
   

8. When adding a portlet to your page, you will be presented with the Available portlets dialog. Select the desired portlet (Figure 18), enter a title for the portlet window, and press OK.

   
   
   Figure 17. Insert portlet
   
   
   

   In Figure 18, we have added several copies of the same portlet in each container. We have specified a different title depending on its position on the layout (R for rows and C for columns).

   
   
   Figure 18. Sample structure with portlets
   
   
   

   The page outline that you have been defining should look like Figure 19.

   
   
   Figure 19. Page outline
   
   
   

Security definition

Next, you will define which access to different elements of our module a user will have depending on his role. It is important to notice that portlets in a page will only be displayed if the user has access not only to that portlet, but also to the structure of labels and pages where it has been placed.

1. Open the Security tab inside the ISC Module Configuration (Figure 20).

   
   
   Figure 20. Security tab
   
   
   

2. Since access will depend on the user role, the first thing you need to do is specify the role. Press Add under Application Roles.

3. You can define any role you need. Specify predefined roles in WebSphere Application Server so that your module will be visible by administrators, monitors, and so on (Figure 22).

   
   
   Figure 21. Define administrator role
   
   
   

4. The next step is to provide the portal roles for every element to which a user in that application role should have access. The only available roles are User or Privileged User. There is no difference in these roles for pages or labels, but for portlets, a User has access to the View and Edit modes, while the Privileged User additionally has access to the Edit mode.

   For our example, add all the objects selected in Figure 23. In this version of the plug-in, you cannot select multiple elements and so you will have to add them one at a time. For every portlet object, select Privileged User as role type under Portal Role Details.

   
   
   Figure 22. Create portal roles
   
   
   

5. Once we have added all the objects, the security configuration page for the administrator role will have a look similar to the one in the figure.

   
   
   Figure 23. Security confirmation page for administrator role
   
   
   

   If you had other roles to be defined, selecting them in the left column would display the objects with portal access in the right column.

6. Repeat the same steps and create another application role, name it monitor, and define portal roles as shown in Figure 24. For this role, specify User as role type under Portal Role Details.

   
   
   Figure 24. Security confirmation page
   
   
   

Back to top

Module packaging and deployment

At this point, you have completed the development of the module for the administrative console. The next step is to deploy it. It is important to know that modules for the administrative console are not installed in the same manner as other Web applications.

1. Find your portlet project and select Export as a WAR file. You do not need an Enterprise Application and its corresponding EAR file. The WAR file should be created in the directory where the console resides: <WAS_DIR>\systemApps\isclite.ear.

2. Start a wsadmin session and execute these commands:

   $AdminApp update isclite modulefile { -operation add -contents c:/IBM/WebSphere/AppServer/systemApps/isclite.ear/ISCDemo.war -contenturi ISCDemo.war -custom paavalidation=true -usedefaultbindings -contextroot / -MapWebModToVH {{.*.* admin_host}}} $AdminConfig save

   
   

3. Login to the administration console as the administrator to see the deployed module.

4. On the welcome page, you will see an entry with the name of your application, and a new menu entry at the bottom of the console (Figure 25).

   
   
   Figure 25. Colsole menu entry for new deployed module
   
   
   

5. Although you created several pages, you only gave users access to one of them, which is why you only see the Page 1.1.1 entry. Inside this page, you can see the portlet with the layout you prepared. Since you specified Privileged User for the administrator, you will see the pencil icon on the portlet menu, indicating you can modify some properties.

   
   
   Figure 26. Portlets within deployed application
   
   
   

6. Click on the pencil to enter in Edit mode (Figure 27).

7. Enter a Configuration value, to be stored in your model bean, then click Save to submit it for processing. (We are not persisting this value in our example, so changes will be lost when we log out.)

   
   
   Figure 27. Portlet edit mode for Privileged User
   
   
   

8. Click the arrow in the top bar. You have returned from View mode, but now the value you entered is displayed (Figure 28).

   
   
   Figure 28. Portlet view mode for Privileged User
   
   
   

9. Finally, log out and sign on as a user with Monitor role.

10. You will see one portlet only. The pencil for Edit mode is not available, since you specified User for role type.

    
    
    Figure 29. Portlet view mode for User
    
    
    

Back to top

Removing a module

If we need to unisnstall the module from the administration console, start a wsadmin session and run these commands:

$AdminApp update isclite modulefile {-operation delete -contenturi ISCDemo.war}
$AdminConfig save

In this example, we specified ISCDemo.war as the name of the WAR that contains our module.

If you need to install a new version of the module, you must first uninstall the existing version from the administration console using these same commands. The folder that was created by the system with the name of the WAR file inside (<WAS_DIR>\systemApps\isclite.ear) should also be deleted. If the folder is not deleted, you will not be able to copy your modified WAR file.

Keep in mind that if changes are introduced to the module related to security or page layout, then you need to logout from the console and login again so that the console will show the updates.

Back to top

Conclusion

This article explained how creating a module for the Integrated Solution Console is not very different from Web application development when you use the PAA Visual Designer Plug-in, which creates all the descriptors needed. This article also described the procedure for deploying a console module, which is different from a typical Web application.

Back to top

Download

Information about download methods

Resources

Learn

• WebSphere Application Server V6.1 Information Center
  
  
• Rational Application Developer V6 Programming Guide
  
  

Get products and technologies

• Download IBM Integrated Solutions Console PAA Visual Designer Plug-in, Version 6.1
  
  
• Rational Application Developer V6 Portlet Application Development and Portal Tools
  
  

About the author

Genaro Nieto is currently working as a Senior IT Specialist in the IBM Software Group's SMB & Channel Technical Sales organization. He is helping customers from SPGIT by providing them with enablement and technical support for Websphere products. His main focus is on WebSphere Application Server, WebSphere Portal Server, WebSphere Process Server, and Websphere Integration Developer. Before joining the Software Group, he spent six years in Services and three years in the Consulting group. Mr. Nieto holds a degree in Communications Engineering and another in Business Management. He lives in the Barcelona (Spain) area, and spends his spare time with his family, friends, or with his mountain bike.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Console module development
• Module packaging and deployment
• Removing a module
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers