Portal URL

Portal URLs can become complicated as more pages are implemented. However, there are ways to set simpler alternate URLs, which make things a bit easier. It is important to note that portlets by themselves do not have a URL, and hence cannot be invoked directly. Portlets are part of a page and have an independent identity only from a browser perspective. Hence, they don't have their own URLs. Only portals and portal pages can be directly invoked; hence they can be invoked directly from browsers.

Each portal server can consist of several portals. Each one of these portals has its own URL. Similarly, each portal has several pages and each page has its own URL. To access a portal directly, we can use the portal name in the URL, which will then look like this: http(s)://server:port/portal/<portal name> .

Specifying only /portal takes us to the default portal. Similarly, to access a page on a given portal on the server, the URL we use is /portal/<portal name>/<page name> .

A Content Management System(CMS) serves content transparently like a portlet, hence doesn't impact the URL. We will discuss CMSs in more detail in Chapter 8.

Portlet modes

A portlet mode is a pointer to the type of function it will perform. There are three modes: VIEW, EDIT, and HELP. The mode indicates to a portlet the type of function it should perform and the associated content it should generate. When a portlet is invoked, the portlet is informed of the mode by the container. A portlet can have different modes depending on the function it needs to perform. There are three modes defined by the portlet specification, but a portal can extend them.

Let us look at these three modes in a bit more detail:

Window states

Window states relate to the space allocated for a given portlet on a page. As each portlet generates its markup, it is important to manage the real-estate of the aggregated final portal page effectively. Window states play a major role in this. Portal window states can be compared with the state of windows in a Microsoft Windows environment. A window in Windows can be minimized, maximized, or can be set as normal. Portal window states behave the same way. When the portlet is invoked, just like the portlet mode, the window state is also provided to the portlet. The portlet, based on the state provided, decides the best way to effectively organize the content in the portlet that will eventually be served as a fragment. Again, a portlet can change the state programmatically.

The three states defined by the specification are:

Portlet development environment

Portlet development, like web application development, requires a set of tools that help write code, build and successfully deploy our solution. The choice of the tools is very subjective, but typically, most of the developers prefer to use some kind of Integrated Development Environment(IDE) that encompasses all of their needs. However, if we want to stay agnostic of the IDE, command line developments can be a good option. At the least, the following set of tools is required to successfully create and deploy portlets:

Portlet package structure

Before we start with the code, let us build a context and briefly look at the overall structure of a deployable portlet archive.

Portlet archives are packaged asWAR(Web Archive) files, similar to archives in JEE applications. The content of our "Hello World" example as a WAR file will appear somewhat like this:

The directory structure is a standard structure for JEE projects. The structure can be created either manually or by using an IDE.

As you can see, the package consists of executable CLASS files, library JAR files and various deployment descriptors. For the purpose of simplicity, the example doesn't illustrate all of the scenarios, but a portlet WAR file can also consist of static content, resource bundles, JSPs, servlets, and so on.

The deployment descriptors illustrated in the figure are a combination of ones that are required by the JSR-286 specification, and others that are provided by JBoss to facilitate added features, easier configuration, and deployment on a JBoss portal platform. The JBoss-specific configurations provide significant value when deployed on a JBoss application server platform.

Writing the code

Now, let us look at the following code for our "Hello World" portlet:

package org.jboss.portlet.hello;
import java.io.IOException;
import java.io.PrintWriter;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletConfig;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.UnavailableException;
public class HelloWorld extends GenericPortlet {
public void init(PortletConfig portletConfig) throws UnavailableException, PortletException {
super.init(portletConfig);
}
public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException {
// set return content type
response.setContentType("text/html");
PrintWriter writer = response.getWriter();
writer.println("<p>Hello World of Portals!</p>");
writer.close();
}
}

Let us parse through the code to understand it better.

public class HelloWorld extends GenericPortlet {

JSR-168 requires every portlet to implement the javax.portlet.Portlet interface. The Portlet interface is used by the container to invoke the portlets in the container. The GenericPortlet class is the default implementation of the Portlet interface, and provides an abstract class that portlets can then extend, and override its methods for various functions. The method processAction , for example, is used to handle requests, and the init and destroy methods are used to manage the life cycle of the portlet. However, the GenericPortlet class is significant for its implementation of the javax.portlet.Portlet render method, which sets the title of the portlet and invokes the doDispatch method, which in turn delegates the processing to one of the portlet mode methods, based on the mode indicated by the request.

public void init(PortletConfig portletConfig) throws UnavailableException, PortletException {
super.init(portletConfig);
}

This is an optional method, but it is good practice to use it, and a convenient way to initialize the portlet with any configuration information. In this case, we are not using a special configuration; instead, we default to the parent implementation.

public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException {

For our example, we have used only the View mode for our portlet. Hence, we need to implement only the doView method of the GenericServlet class. When the portlet is invoked, the render method invokes this doView method through the doDispatch method.

// set return content type
response.setContentType("text/html");
PrintWriter writer = response.getWriter();
writer.println("<p>Hello World of Portals!</p>");

Now that we have dispatched the request to the appropriate view mode, it is time to implement functionality in the portlet and send a response back.

As our response needs to be served to a browser, we first set the response type, text/html in this case. We then invoke the PrintWriter to output our message Hello World of Portals! in our portlet window.

This code generates the portlet fragment that will be aggregated with other fragments and content to generate the final page. Hence, it is important that the content that gets generated has tags that are valid inside an HTML <body> tag.

With this simple piece of code implementing our portlet functionality, we are now ready to tell our portlet container about the portlet.

Application descriptors

The application descriptors are XML-based configuration file options that, among other things, indicate the properties and behavior of the portlet to the container.

The portlet specification, JSR-286, mandates some of these options, while the rest are specific configurations mandated by the portal server — JBoss portal in our case. There is also a standard J2EE web deployment descriptor.

The following screenshot shows the descriptors as part of the deployable WAR file that we saw earlier:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns=http://java.sun.com/xml/ns/portlet/portlet-
app_2_0.xsd
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet /portlet-app_2_0.xsd http://java. sun.com/xml/ns/portlet/portlet- app_2_0.xsd"
version="2.0">
<portlet>
<portlet-name>SayHelloPortlet</portlet-name>
<portlet-class>org.test.portlet.hello.SayHelloPortlet</portlet- class>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
</supports>
<portlet-info>
<title>Say Hello Portlet</title>
</portlet-info>
</portlet>
</portlet-app>

<portlet-name>SayHelloPortlet</portlet-name>

<portlet-class>org.test.portlet.hello.SayHelloPortlet</portlet-class>

<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
</supports>

<portlet-info>
<title>Say Hello Portlet</title>
</portlet-info>

<?xml version="1.0" standalone="yes"?>
<deployments>
<deployment>
<instance>
<instance-id>SayHelloPortletInstance</instance-id>
<portlet-ref>SayHelloPortlet</portlet-ref>
</instance>
</deployment>
</deployments>

sayhello-object.xml

The *-object.xml defines the structure and configuration of a portlet instance that has been created earlier. We can use this file to create and configure windows and pages, their behavior, and their structure. We have decided to call our file, sayhello-object.xml:

<?xml version="1.0" encoding="UTF-8"?>
<deployments>
<deployment>
<if-exists>overwrite</if-exists>
<parent-ref>default.default</parent-ref>
<window>
<window-name>SayHelloPortletWindow</window-name>
<content>
<content-type>portlet</content-type>
<content-uri>SayHelloPortletInstance</content-uri>
</content>
<region>center</region>
<height>1</height>
</window>
</deployment>
</deployments>

The descriptor allows for multiple deployments of portlets with distinct individual behaviors.

<if-exists>overwrite</if-exists>

This is used to manage copies of the object that may have already been instantiated. When we set the value to overwrite , we are telling the container to destroy any existing object and create a new one. If we set the value to the other allowed option, keep , the container retains any existing copy and creates a new instance. The decision to overwrite or keep an existing copy is purely a design call, and is based on the capacity of the server, performance requirements, and the complexity of the portlet.

<parent-ref>default.default</parent-ref>

This line basically indicates the location of our portlet, and stands for portal instance.portal page . In our case, by giving a value of default.default , we have decided to keep it simple and add the SayHelloPortlet to the default page of the default instance. We could very easily add the portlet to a new page that can be created using the approach outlined earlier in the chapter. In this case, the reference would change to default.newPage

<window-name>SayHelloPortletWindow</window-name>

This line assigns an arbitrary but unique window name to the portlet window.

<instance-ref>SayHelloPortletInstance</instance-ref>

This line references the portlet instance created in the portlet-instance.xml file. Again, the value of this element should be the same as the <instance-id> element in portlet-instance.xml

<region>center</region>
<height>1</height>

These lines specify the location and dimension of the portlet window. There are various configuration options for these elements, but in our case, we are indicating that the portlet should appear in the center of the page layout as described by identifier in the layout descriptor, and should be second portlet from the top as indicated by height 1 . Height "0" is the first portlet from the top in a column. We will see later how the location and the order can be changed using the admin console.

The inter-relationship of these descriptors is as follows:

The <portlet-name> in portlet.xml is used to create an instance using <instance-id> in portlet-instances.xml . The properties of this instance is defined in *-object.xml .

Building the application

Now that we have our code and descriptors in place, let us start building our deployable artifact, and plan for its eventual deployment on the server.

The source code associated with this chapter provides the necessary build scripts to compile and create deployable artifacts. There are multiple ways of creating the WAR file — the build script uses one such technique. We will create our portlet source file under the src/main directory, and place our deployment descriptors under src/resource/sayhelloportlet-war . The libraries required for building will go under the lib directory.

The script will first compile the source, create a JAR file of the compiled binaries, and copy this JAR file to the src/resource/sayhelloportlet-war/WEB-INF/lib directory. It will then package the contents of the src/resource/sayhelloportlet-war directory into a WAR file.

The screen output will look like the following screenshot:

Although we have packaged the portlet classes as a library, it is not necessary to do so. As with a J2EE application, the CLASS file tree can be copied as it is, below the WEB-INF/classes directory.

Deploying the application

We are now ready to deploy the WAR file to the portal server. We can deploy the file in a couple of ways:

An exploded deployment has significant value when we need more control over the content. However, for our purposes, we will use the WAR file deployment option.

To deploy the WAR file, all we need to do is drop the file into the deploy directory of the JBoss application server (AS or EAP). This can be done as a hot deploy, while the server is running.

For bundle installs, the deploy directory is $JBOSS_PORTAL_HOME/server/default/deploy .

The output on the console, indicating deployment activity after we drop the WAR file, is as follows:

 03:27:42,810 INFO [TomcatDeployer] deploy, ctxPath=/sayhelloportlet, warUrl=.../tmp/deploy/tmp26738sayhelloportlet-exp.war/

Accessing the page and portal URL

Once we have successfully deployed the application, we can then go to the default URL for JBoss server: http://localhost:8080/portal .

The default URL and page corresponds to our default.default location setting earlier in the descriptor.

We can now see our portal, displayed in the center of the page, in View mode:

Minor changes to content can be done directly on the tree without redeploying the whole archive. To trigger a redeploy, we just need to update the timestamp on the web.xml file by touching it. A web.xml file with a timestamp later than the last deployment will trigger the JBoss portal to deploy the application again. It is worth noting here that this time the deployment takes place in an exploded format as there is no WAR file involved.