Recently I’ve completed my first JBoss portlet development project. I’ve faced many challenges during the development, since this is my first portlet project. But I managed to complete the project successfully. This blog is like a documentation of my experience and learning in JBoss portlet development.

Platform used : JBoss 4.2.2 / JBoss portal 2.6.4

JDK : JDK 1.5.0

IDE Used : Eclipse

First thing first… Getting started with portlet development:

Portals are now widely used in enterprise systems. Portals, with their customization features, single point access to multiple data sources, dash-board kind of look, are attracting more business users. When I say portal, I am referring the application which hosts multiple portlets. Confused, huh?! For example take a look at the IGoogle home page. This IGoogle is a Portal, where as the small small windows (application) you see there are Portlets. The Portal is a container for the portlets.

Now coming to the point, I’ve developed my portlet for JBoss portal platform. JBoss portal is a community developed, open source platform which fully supports the JSR168 specification for portlets. I’ve started with the Hello World portlet sample from the JBoss tutorial page. The folder structure is something similar to the below image:

As you see, portlets are also packaged into WAR file with some more XML configuration files along with the default web.xml file. These configuration files might be different for different vendors. The portlet.xml is a JSR168 portlet descriptor, which is common between different portal platforms and helloword-object.xml and portlet-instances.xml are JBoss specific configuration files. Check out the Portlet Primer for more information on Configuring these XML file.

As JBoss portal requires the abovepackage structure, I’ve used an Ant Script to build my portlet. All the source codes should go inside a JAR file, which is placed inside the lib folder. The configuration XML files also should be included in the WAR file. This WAR file may contain other web resources like servlets, images, style, etc.

Once you built the WAR file, you should place the WAR file in [JBoss HOME]\server\default\deploy folder. You can copy the WAR file, when the server is running. This is called as Hot-deployment. JBoss server will detect the changes made and deploys your portlet. After the deployment, you can navigate to JBoss portal page http://localhost:9090/portal to see you portlet in action.

Tips and Learning on portlet development:

Below are some of the issues that I’ve faced and solution I found through googling and tech forums. I’ve mentioned the source of the information, where ever possible.

• Changing JBoss portal server’s port:
  By default JBoss uses port number 8080. For some reasons, if you want to change this port, you can do so by changing the server.xml file. Open this file from the location [JBoss HOME]\server\default\deploy\jboss-web.deployer\server.xml and change the port number in the Connector tag, as below:
  <Connector port="8080" address="${jboss.bind.address}" maxThreads="250" maxHttpHeaderSize="8192" emptySessionPath="true" protocol="HTTP/1.1" enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" />




• Small mistakes make big problems:
  Sometimes a very silly mistake may cause you headache. I experience this in this project. Take a look at the below code:
  Properties props = null;
  try
  {
    InputStream is = ClassLoader.getSystemResourceAsStream("/WEB-INF/query.properties");
    props.load(is);
  }catch (IOException e) {
    //Exception
  }

  While executing the above code, I was getting the exception for a long time. Since, I was using the JBoss portal command line console, the exception messages were also not clear. For a long time, i was thinking that I gave the queries.properties file address wrongly. Then I noticed the actual problem. On the top of the code, I had initialized the props to null and inside the catch block, I was trying to load this properties file. Then changed the code to Properties props = new Propertie(); and it worked like a charm.




• Calling a servlet from a portlet:
  In some cases you might want to call a servlet from the portlet to do your task. In my case, I needed a servlet to export the details to an excel file. Since, portal framework does not support sending the data in binary format (PDF, XLS), a servlet is necessary to send excel data. To call a servlet, do the below steps:
  1. Package your servlet as you usually do and place an entry and servlet mapping for this servlet in web.xml file.
  2. Now call you servlet from a JSP file by prefixing the portlet name along with the servlet name (Usually we specify only the servlet name when calling the servlet. But for portlets, you have to prefix the portlet application name also).Take a look at my form’s action property.
     
<form name=”SomeForm” method=”POST” Action= <%= request.getContextPath() + “/servletNameHere” %> >





• Exporting to excel file from portlet:
  As I’ve already mentioned, portal does not support sending binary content to client. So, in order to export a binary file, like Excel, you need to call a servlet and pass the information to the servlet.

  There are two ways in which you can call a servlet from the portlet. Using a Request Dispatcher and directly calling the servlet from JSP. But for exporting to excel, you should not use RequestDispatcher, since the call is still handled by the portlet container, the excel file will be sent as a plain HTML format. To avoid this, call the servlet directly from the JSP (see the previous tip) and send the excel file to client.