Full text


Computer Practie

Jahia Ltd

45, rue de la Gare

Web Application Developer Guide


Serge Huber

Jahia Ltd

1.0 english









Disclaimers, Terms and Conditions



, T





Copyright 2003 by Jahia Ltd. (http://www.jahia.org). All rights reserved.



This is protected software (Jahia). The Jahia software is furnished under license and may only be used or copied in accordance with the terms of such license. Check the Jahia license (www.jahia.org/license) to know your rights.


The names JAHIA Ltd., JAHIA Solutions Sàrl, Jahia and any of its possible derivatives may not be used to endorse or promote products derived from this software without prior written permission of JAHIA Ltd. To obtain written permission to use these names and/or derivatives, please contact license@jahia.org.


This product includes software developed by the Apache Software Foundation (http:// www.apache.org/).

Windows and Windows NT are registered trademarks of the Microsoft Corporation. For more information on these products and/or licenses, please refer to their websites (http:// www.microsoft.com).

Java is a trademark of Sun Microsystems, Inc. For more information on these products and/or licenses, please refer to their website (http://www.sun.com).

Other trademarks and registered trademarks are the property of their respective owners. 4. DISCLAIMER OF WARRANTY.






Disclaimers, Terms and Conditions



Any action derived from or related to this agreement will be governed by the Swiss Law and shall be of the competence of the judicial authorities of the Canton of Vaud, Switzerland. 7. TERMINATION.

This agreement is effective until terminated. END OF TERMS AND CONDITIONS



License agreement




INSTALLING THE JAHIA SOFTWARE INDICATES YOUR ACCEPTANCE OF THE FOL-LOWING TERMS AND CONDITIONS. IF YOU DO NOT AGREE WITH THESE TERMS AND CONDITIONS, DO NOT INSTALL THE JAHIA SOFTWARE ON YOUR COMPUTER. The contents of this file, or the files included with this file, are subject to the current version of the Jahia Community Source License for the Jahia Portal Server (the "License"); You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.jahia.org. See the License for the rights, obligations and limitations governing use of the contents of the file.

The Original and Upgraded Code is Jahia Portal Server. The developer of the Original and Upgraded Code is Jahia Ltd. Jahia Ltd owns the copyrights in the portions it created. All Rights Reserved.



Contents at a Glance









Chapter 1

Introduction to Portlet Development ... 2

Chapter 2

Compile and Deploy your First Portlet ... 7

Chapter 3

Porting existing applications to Jahia, or simply writing advanced

applications with Jahia ... 13

Chapter 4

Working with Jahia.org’s Example Portlets... 26

Chapter 5

Portlets Summary ... 39








Chapter 1

Introduction to Portlet Development ... 2

What is this all about? ... 2

What is a Portal? ... 2

Portal Features ... 2

Portlet Definitions ... 3

Pros and cons of portlet types ... 3

Prerequisites ... 4

Mixing Portlets and Content ... 4

Support for standardized Java web applications and Frameworks ... 5

Support of existing Web Application Frameworks ... 5

Application generation tools ... 5

Portlet standards ... 6

The Java Portlet API standard (JSR 168) ... 6

WSRP (Web Services for Remote Portlets) Standard ... 6

Chapter 2

Compile and Deploy your First Portlet ... 7

Hello Web Application ... 7

Introduction ... 7

Requirements ... 7

Servlet code ... 7

Web application deployment descriptor file ... 8

Compiling the web application ... 8

Packaging the web application ... 9

Running the application ... 9

Looking under the hood ... 11

URL generation ... 11

Web application entry point ... 12

Chapter 3

Porting existing applications to Jahia, or simply writing advanced

applications with Jahia ... 13

Introduction ... 13

Key Basic things to remember for porting to Jahia ... 13

Portal content size ... 14




Request/response processing ... 14

Transforming action URLs to use encodeURL ... 16

Single sign-on ... 17

Web application role mappings ... 18

Single entry point into web application ... 19

Special request attributes set by Jahia ... 19

Session Attributes ... 20

Cache management ... 20

Javascript issues ... 23

CSS (Cascading Style Sheets) and Web Applications ... 24

HTTP Redirects from web applications ... 24

Chapter 4

Working with Jahia.org’s Example Portlets... 26

Web application Installation ... 26

Installation a web application in Jahia ... 26

Importing an existing web application from Jahia’s public CVS ... 27

Compiling a Jahia.org web application ... 28

Database configuration ... 29

OJB Database Configuration ... 29

Understanding the Deployed File System ... 30

Web application Deployment ... 33

Automatic deployment of web applications ... 34

Deployment descriptors overview ... 34

Creating WAR and EAR files ... 36

Re-deploying web applications ... 36

Developing WebApps with an IDE (example with Jbuilder 8 EE) ... 36

Chapter 5

Portlets Summary ... 39

Wrapping it up ... 39

References ... 39



List of figures





Part I

Figure 2-1 Directory structure of the “Hello” web application... 7

Figure 3-1 Overview of request/response processing for a web application. Grey boxes represent J2EE container systems... 15

Figure 3-2 Class loader hierarchy in Tomcat... 16

Figure 3-3 Jahia Web application role mapping popup... 18

Figure 3-4 Cache processing during a request to a web application ... 21

Figure 4-1 : Overview of the file system structure for a standard Jahia installation .. 31

Figure 4-2 : Jahia’s file system overview ... 32



List of tables





Part I

Table 1-1 : Possibilities of the different types of portlets ... 3

Table 3-1 : Jahia-specific request attributes ... 19

Table 3-2 : Cache modes and effects ... 22

Table 3-3 : Special cache control request attribute ... 22








Chapter 1 • Introduction to Portlet Development

- DR AFT -W ebapps / Portlets d evelo p me nt











1.1. W







This manual presents different sections that details the specifics about writing portlet web applications for Jahia. We also cover some of Jahia’s internal in the process when they are relevant to understanding why and how a certain subsystem works. We start with a short introduction on the context of portal and portlets.

1.2. W







A portal is a feature-rich Web site. It provides a single point of access to enterprise data and applications, presenting a unified and personalized view of that information to employees, customers, and business partners.

Portals allow you to have multiple Web applications within a single Web interface. In addition to regular Web content that appears in a portal, portals provide the ability to display portlets— self-contained applications or content—all in a single Web interface.

1.2.1 Portal Features

Portals offer unified sets of features that concern both the end-user as well as the application developer. This section describes some of these features.

Personalization and Authorization

Because Jahia Portal comes with robust authentication and personalization features, admin-istrators can determine what content a visitor can interact with and how that information will appear to the specific visitor. Visitors themselves can leverage Jahia Portal's personalization features to select their own content and create their own look and feel. A major component of the Portal development process is to create the elements that make such authorization and personalization possible.

Group Portals

Portals are designed either for single users or for groups. With group portals you can set up delegated administration for portals and restrict portal access to specific users. You can cre-ate multiple group portals within a portal Web Application. The group portals can share portal resources, such as layouts and portlets, but can be configured differently to satisfy the needs of each group separately. Because users are designated individually as members of a group, the group portal uses a static form of personalization.

Unified User Profile

In Jahia Portal, users are represented by user profiles. A user profile employs a user's ID to access such properties for that user as age or e-mail address. A Unified User Profile incorpo-rates user data from external data sources in addition to or instead of LDAP servers, such as a legacy system or database, so that the user can access data from many different sources



Chapter 1 • Introduction to Portlet Development

- DR AFT -W ebapps / Portlets d evelo p me nt

through a single profile. During portal development, you will create this profile so that your Portal application can retrieve data from multiple external sources.

Other Useful Features

Jahia Portal also provides these other features that facilitate portal development: A layout paradigm for dynamic, interactive, personalized content

Content modules called portlets, laid out in rectangular grids The ability to personalize portlets at many levels

Delegated administration

1.3. P




The term “portlet” is extremely used throughout the industry of web applications. A portlet can be anything from a portion of static HTML code to a piece of Java code. In order to clarify the notion, we will quickly present the definitions we use in this manual.


A small HTML fragment element, usually in the form of a box on a page, which could be gen-erated by different subsystems, such as a JSR 168 portlet application, a servlet that is included from the main page, or a JSP.

JSR-168 Portlet API

The Java Community Process has recently released the first version of the specification for the Portlet API. This is a standardized API to dispatch to portlet classes that generates HTML fragments. Jahia is currently working on integrating this standard, and we will update this doc-ument once this integration is complete.

Web applications

Jahia supports the use of standard J2EE web applications as the basis for developing port-lets. This manual will therefore mostly cover this technique of building portport-lets.


It is also possible to build portlets simply by including JSP code in a JSP template within Jahia’s context. This manual does not cover this type of development, but the template guide does, so if you are interested in this type of portlets, we strongly suggest you refer to that guide.


JSP may be messy to use as portlets if they are used in Jahia’s web application context, unless there is a lot of available taglibs to use. Implementing portlet taglibs is another way of integrating HTML fragments. Notable projects that offer this type of functionality are Struts Tiles, Java Server Faces, etc.... Again this is not the subject of this manual but is part of the template manual.

1.3.1 Pros and cons of portlet types

There are some pros and cons for the various types of portlets. Basically we will cover in detail the limitations of using web applications in this manual, but we will quickly present here the other types, because depending on your needs you might be interested in one or another type of portlet.

Table 1-1 : Possibilities of the different types of portlets

Portlet type Standard spec Can work in standalone

Java programming


In Jahia context Access to Jahia Content API

JSR-168 Portlet API yes no yes no no



Chapter 1 • Introduction to Portlet Development

- DR AFT -W ebapps / Portlets d evelo p me nt

1.4. P


It is assumed in this manual that the reader is familiar with the following technologies:

- Java programming language.

- Java Servlet API especially HTTP Servlets.

- Apache Tomcat


- JavaScript, JSP files and Taglibs

- Familiarity with Jahia’s content model

- Nobel prize in Quantum Physics

In the examples, the Tomcat servlet container platform will be used. We recommend the reader to become familiar with this product.

1.5. M







Jahia offers the possibility to mix portlets and content on the same HTML page since it offer the possibility to treat portlets as content from a template designer’s point of view. In order to embed web applications in a Jahia template, he has the following possibilities:

• Embed it at a fixed place, or in a container list, as in the illustration below :

• Use the layout manager (MyYahoo-like home page), that offers powerful

posi-tioning possibilities such as column and row spans, moving of portlets, as

illus-JSP yes no not necessarily yes yes

Taglibs yes yes to use no, to

develop yes

yes yes

Table 1-1 : Possibilities of the different types of portlets

Portlet type Standard spec Can work in standalone

Java programming




Chapter 1 • Introduction to Portlet Development

- DR AFT -W ebapps / Portlets d evelo p me nt trated below :

1.6. S











Jahia is able to use standard J2EE web applications as portlets, provided a few modifications we present in the next chapters. Because of this capability, it means a lot of existing technol-ogies and tools can be leveraged, since the Servlet API norm is now quite established and recognized as the de-facto standard for developing web applications.

1.6.1 Support of existing Web Application Frameworks

Because of the possibility to use standard web applications, this also means that most exist-ing web application buildexist-ing frameworks may be used to develop portlets. Examples of such technologies include:

• Struts, http://jakarta.apache.org/struts

• Java Server Faces, http://java.sun.com/j2ee/javaserverfaces/

• Webwork, http://www.opensymphony.com/webwork/

• Tapestry, http://jakarta.apache.org/tapestry/index.html

• JSTL Taglibs, http://java.sun.com/products/jsp/taglibraries/index.jsp

There are some limitations as to the portability across J2EE servlet containers when using such frameworks, but with Tomcat most of these frameworks should work as expected.

1.6.2 Application generation tools

There are also tools that may be used to quickly generate simple web applications. Often these should be used to quick-start an application development, but will need some modifying to properly integrate in the portal. Nevertheless, it might be interesting to use these tools if a great number of applications need to be developed. Also note that although these tools are cited here, there is no support offered for the use of these tools when integrating with Jahia, but hey, it might work :)

• Codecharge, www.codecharge.com



Chapter 1 • Introduction to Portlet Development

- DR AFT -W ebapps / Portlets d evelo p me nt

1.7. P



For a long time there was no standardization effort in the field of portlet APIs. One of the many reasons was that portal vendors saw no incentive in standardizing one of the few ways left of “locking-in” developers. Fortunately with the commodotization of portals, this lock-in strategy started falling apart and new standards have recently been completed and are avail-able or under implementation on most portals.

1.7.1 The Java Portlet API standard (JSR 168)

Specified by: Java Community Process http://jcp.org/en/jsr/detail?id=168

The Java Portlet API standard is an API mostly similar to the Servlet API, except that it spec-ifies ways to build Java web applications that generate HTML fragments instead of complete pages. Because of this requirement and to allow for optimizations in the dispatching process, a request coming into a page is split into two sub request: an action request and a render request. The render request is basically the new sub-request that may be call more than once, while the action request will only be called once.

Jahia will also introduce support for this API by integrating with the reference implementation of the API available here: http://jakarta.apache.org/pluto/index.html

1.7.2 WSRP (Web Services for Remote Portlets) Standard

Specified by: Oasis Consortium


The Java Portlet API standard is a great new addition to the J2EE platform, but it has one main drawback: it is Java-specific. One of the interesting ideas with portlets is to have the possibility to have an XML-standard to dispatch to portlets, which could be written in any lan-guage, available on other informations systems remotely, and aggregate the portlet onto our local portal. The idea here is to use the SOAP (Simple Object Access Protocol) XML standard to allow dispatching to remote portlets. These portlets may very will have been written in a dif-ferent programming language, such as C/C++, or run on a difdif-ferent platform than the portal. One of the main drawbacks of this standard is that remote XML calls are usually quite slow, so the integration of system through such technologies should be reserved to applications that do not need to be accessed often.

This standard will also be integrated into Jahia, but only after the Java Portlet API integration is complete, and will offer new possibilities.



Chapter 2 • Compile and Deploy your First Portlet

- DR AFT -W ebapps / Portlets d evelo p me nt














2.1. H






Goal: Build and deploy a minimal web application from scratch

2.1.1 Introduction

Jahia allows the usage of standard J2EE web application as “portlets”, meaning that with some basic rules and modifications we can adapt existing web applications to work under Jahia.

For this example, we will develop a small “hello” application that asks a user for it’s name and then display a message saying “Hello Name”.

The directory structure of our sample application is presented in

Figure 2-1 Directory struc-ture of the “Hello” web application

The top-level directory name “hello_webapp” is not really important, and you can name it something else if you want, but the other two directory names are very important, and should not be changed, not even capitalized in a different way or else the application will no longer work correctly (this is a format defined by the J2EE web application standard).

2.1.2 Requirements

In order to develop, compile and run the following example, you will need the following installed on your computer:

• Recent Jahia package (version 4 or more recent), available at http://


• Sun JDK 1.4 or more recent, available at http://java.sun.com • A text editor to edit the *.java files

It is also assumed that you are reasonably familiar with all of the above software and that it is properly configured (i.e.: you have a JAVA_HOME environment variable pointing to your JDK installation)

2.1.3 Servlet code

Here is the code for the servlet that will contain all the code for the sample application. Note that this is not a recommend way to build an application, but it does have the merit of simplic-ity so for the moment we will not expand on it.

1 : // File : WEB-INF/classes/HelloServlet.java 2 : import java.io.IOException;



Chapter 2 • Compile and Deploy your First Portlet

- DR AFT -W ebapps / Portlets d evelo p me nt 3 : import java.io.PrintWriter; 4 : 5 : import javax.servlet.ServletException; 6 : import javax.servlet.http.HttpServlet; 7 : import javax.servlet.http.HttpServletRequest; 8 : import javax.servlet.http.HttpServletResponse; 9 :

10 : public class HelloServlet extends HttpServlet { 11 :

12 : protected void service (HttpServletRequest request, 13 : HttpServletResponse response) 14 : throws ServletException,

15 : IOException { 16 :

17 : PrintWriter writer = response.getWriter(); 18 : String name = request.getParameter("name"); 19 :

20 : response.setContentType("text/html"); 21 : if (name == null) {

22 : writer.println("<form method=\"post\" action=\"" +

23 : response.encodeURL( request.getContextPath() + "/hello" ) + 24 : "\">");

25 : writer.println("Enter your name: <input name='name'>"); 26 : writer.println("<br/><input type='submit' value='Submit'>"); 27 : writer.println("</form>"); 28 : } else { 29 : writer.println("Hello <b>" + name + "</b>"); 30 : } 31 : } 32 : }

Before explaining all the details of the above source code, we will first describe the steps to compile, deploy and run the above application.

2.1.4 Web application deployment descriptor file

J2EE web applications use a deployment descriptor XML file called web.xml, that basically contains information such as the name of the application, the servlets present in the applica-tion, the URLs that correspond to servlet, user role mappings, etc. For this applicaapplica-tion, again we will use a minimal web.xml file, which we will describe in more details after we have run the application for the first time.

1 : <?xml version="1.0"?>

2 : <!--$Id: web.xml,v 1.1 2003/11/11 13:32:15 shuber Exp $ -->

3 : <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 4 : "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> 5 : <web-app> 6 : <display-name>Hello</display-name> 7 : 8 : <servlet> 9 : <servlet-name>hello</servlet-name> 10 : <servlet-class>HelloServlet</servlet-class> 11 : </servlet> 12 : 13 : <servlet-mapping> 14 : <servlet-name>hello</servlet-name> 15 : <url-pattern>/hello</url-pattern> 16 : </servlet-mapping> 17 : </web-app>

The location of the web.xml file must be (again this is imposed by the J2EE web application specification):


2.1.5 Compiling the web application

Before it can be deployed and run, the application’s source code must be compiled. The serv-let we present has a dependency on the Servserv-let API’s libraries, so we will need to include the



Chapter 2 • Compile and Deploy your First Portlet

- DR AFT -W ebapps / Portlets d evelo p me nt

servlet API library provided by Tomcat in our class path in order to compile the source code successfully. In Tomcat 4.1 this file is located in:


whereas in Tomcat 5 it is located in TOMCAT_HOME/common/lib/servlet-api.jar

TOMCAT_HOME is the directory where TOMCAT is installed. If you are using a packaged version of Jahia, this directory will usually be equivalent to:


To compile the “Hello” application, you must have a Java compiler available on your path and then you may type from the WEB-INF/classes directory:

javac -classpath TOMCAT_HOME/common/lib/servlet.jar HelloServlet.java

Of course in your are using Tomcat 5 or another J2EE web application container you will need another path to the Servlet API jar file.

2.1.6 Packaging the web application

The standard way to package J2EE web applications is to build a WAR (Web Application Archive file). For our sample application, we can execute the following command from the hello_webapp directory:

jar cvf hello.war .

Note: the point at the end of the command is important, it means we want to build an archive from the current directory.

2.1.7 Running the application

In order to run the application you will need to deploy it into the J2EE web application con-tainer, and then use Jahia’s administration interface to make it available to users.

The easiest way to deploy the application in Jahia’s standard package is to use the built-in Tomcat. You can copy the hello.war file into the following directory:


If all goes well, the file should disappear from the directory, which means it has been properly deployed in Jahia. If you have problems with the deployment, you should check in the site administration (Administration -> Manage portlets -> Component management options -> Automatic deployment mode) that the automatic deployment mode is activated for the site. You can also replace the above “myjahiasite” with another site name, meaning that the web application will only be deployed for that site.

1. Click on “Add a portlet”

2. From the “Content” drop-down, select Webapps and enter a title such as “Hello Web Appli-cation”



Chapter 2 • Compile and Deploy your First Portlet

- DR AFT -W ebapps / Portlets d evelo p me nt 3. Click “OK”

4. Click “Add a webapp”

5. In the drop-down, select the “Hello” web application and click “OK”

6. If all goes well you should see the following screen:

7. Enter your name in the form and click on “Submit”, and you should see a response that says “Hello your_name”



Chapter 2 • Compile and Deploy your First Portlet

- DR AFT -W ebapps / Portlets d evelo p me nt

2.2. L





Now that we have presented the steps required to develop, compile, package, deploy and run a simple application, we will go into more details, as to the important parts of each step, and explain how they interact with Jahia.

2.2.1 URL generation

or why do we use response.encodeURL at line 23 in the “hello” web app source code ? In general, web application have a lot of freedom on how to generate URL, whether they point to application actions (such as HTML form submission), external resources or just anchors on a page. As usual, lots of freedom means lots of ways to confuse and complicate things. The biggest problem specific to portals such as Jahia is that action URLs (form POST URLs for example), must generally point back to the portal, otherwise we will loose the context of the application’s execution.

A typical non-portal application could be generating URLs such as these: http://localhost:8080/hello/Hello



If the HTML generated by a web application contains such links in <A> tags, this means that when the user clicks one of these links, he will directly access the web application, completely bypassing Jahia’s processing. This has two effects:

no longer in Jahia’s processing context

no way to navigate back to Jahia (except for a browser’s back button, but this is not what you user to have to do)

So what is needed for web application to correctly integrate with a Jahia portal, is to rewrite their URLs to be Jahia-compliant. Fortunately Jahia intercepts an existing Servlet API response method called encodeURL to offer a service for rewriting URLs. If we look at the original JavaDoc definition for this method here is what we get:


public java.lang.String encodeURL(java.lang.String url)

Encodes the specified URL by including the session ID in it, or, if encoding is not needed, returns the URL unchanged. The implementation of this method includes the logic to determine whether the session ID needs to be encoded in the URL. For example, if the browser supports cookies, or session tracking is turned off, URL encoding is unnecessary.

For robust session tracking, all URLs emitted by a servlet should be run through this method. Otherwise, URL rewriting cannot be used with browsers which do not support cookies.


url - the url to be encoded.

Returns: the encoded URL if encoding is needed; the unchanged URL otherwise

Integrating the session ID in URLs is an important thing to do in web applications because it ensures that the application will function in environment that do not support cookies.

Jahia modifies the semantic of this method to something like the following:

Encodes the specified URL by wrapping it into a Jahia URL. This ensures that Jahia will get receives the request first, and then it will dispatch the result back to the

application, by unwrapping it first. The application will see a regular request come in, so it can process it as it was a standalone web application.

If we look at the what goes on behind the scenes in a response.encodeURL call we have something like this:



Chapter 2 • Compile and Deploy your First Portlet

- DR AFT -W ebapps / Portlets d evelo p me nt

The above sequence diagram illustrates the way Jahia “intercepts” calls to the request and response objects. We will present more details on all the intercepted methods in the next chapter.

2.2.2 Web application entry point

Standard J2EE web application do not define a single entry point, but simply declare URL mappings such as in the following web.xml extract:

1 : <servlet-mapping>

2 : <servlet-name>hello</servlet-name> 3 : <url-pattern>/hello</url-pattern> 4 : </servlet-mapping>

Basically this will map the servlet called “hello” onto an URL that looks like this: http://localhost:8080/hello/hello

where the first hello is the name of the web application’s context, which happens to be the same as the URL pattern defined in the web.xml. Another mapping that will also use the map-ping is the following:


A pattern matching is always a “part of URL” matching system, so the above URL will also call the “hello” servlet.

Although applications may have multiple entry points, Jahia only supports a single entry point to a web application. In order to resolve the entry point, it uses the definitions in the web.xml deployment descriptor file, and tries to resolve an entry point based on the following sequence:

1. Is there a default servlet defined for mapping “/” ? If yes, use that as the entry point

2. If no default servlet, let’s look at <welcome-file> entries. If there is at least one define, use the first one as the application’s entry point.

3. If there is no default servlet mapping or no welcome file, use the first declared servlet as the entry point.

For most applications, the <welcome-file> method is the recommended way of declaring an entry point to Jahia. Basically you could have a <welcome-file> section that looks like the fol-lowing:

1 : <welcome-file-list>

2 : <welcome-file>index.jsp</welcome-file> 3 : </welcome-file-list>

And the index.jsp file could simply contain: 1 : <%@ page language="java" %>

2 : <jsp:forward page="/hello" />

This way you can precisely control your entry point, including calculating it based on same variables or anything you can come up with, such as a dispatching system to have entry points vary on some parameters such as the current user agent.



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt




















3.1. I


or what on earth is this section all about ?

Since Jahia offers an web application model that is quite close to the standard J2EE web application specification, porting an existing application is a process that is facilitated, but not without it’s guidelines. Most of the guidelines presented in this section will be quite generic and not specific to Jahia, but some of the most advanced ones are. At the same time these guidelines of course also apply to new applications

For the moment this section will not cover porting or writing new applications that are JSR-168 compliant portlet applications, but once the support for this standard will be integrated in Jahia we will expand this section with relevant information about this new standard.

Note that JSR-168 portlet application are more different from standard J2EE web apps than Jahia’s web app model, so porting to the JSR-168 will require more modifications, but as the benefit of making the application a “real” (as in standard portlet).

This document assumes that you have read and are familiar with the concepts presented in Chapter 2.

3.2. K












In order for your web application to be transformed into a Jahia "portlet" web application, you should follow these basic rules:

reduce content size for display within a portal

the developer must understand that web applications are enclosed in contexts that have special limitations.

call response.encodeURL on all action URLs generated by the portlet access login information through request.getRemoteUser or

request.getUser-Principal (Jahia maps the info through the use of Servlet API 2.3 wrappers for HttpRequest and HttpResponse objects)

convert the application to use only one entry point, preferably as a JSP <wel-come-file> in the web.xml deployment descriptor

We will now present in more detail the above points as well as other important issues to cor-rectly integrate your existing web application into Jahia.



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

3.2.1 Portal content size

or why can’t I use up the whole page for my application ?

The first thing you can look at in your application is whether it will behave correctly in an HTML page consisting of multiple portlets, all displayed at once on the page. If you are trying to port an application that has always assumed it would be displayed alone on a page, you might run into some issues by trying to convert if it hasn’t been properly designed for flexible view display.

One good pointer is to make the application’s HTML “resizeable”, meaning that the applica-tion doesn’t assume a size in pixels, but can easily be resized to display each in full width of the page or in half or third width of an HTML page.

3.2.2 Web application contexts

or why can’t I access Jahia classes directly from my web application ?

In order to better understand how our web application integrates with Jahia, we will first start with a mile-high view of the structure of the whole J2EE web application container:

The first thing that we can note from this diagram is that all web applications are at the same level, including Jahia itself. Jahia is not a privileged application compared to another in any-way. It just has defined a way to communicate with other applications, by asking them to build content for a page display.

3.2.3 Request/response processing

In order to better understand how the request and response processing is performed in a web application used by Jahia, we present here an overview of the communication system between Jahia and the application.

HTTP Connector

Servlet API

Hello Classloader Jahia Classloader InfoNews Classloader

Servlet Container Services : -Session Management -Deployment

-Dispatching to web applications -Resource sharing

Hello Web App Jahia InfoNews

Communication via



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt Figure 3-1 Overview of request/response process-ing for a web application. Grey boxes represent J2EE container systems

As we can see in Figure 3-1, Jahia uses the server’s servlet dispatcher to call the web appli-cation. Before doing that it inserts “wrappers” around the request and response objects. These wrapper classes are specific to the Servlet API 2.3 and up, and they allow the defini-tion of interceptor classes (classes that may intercept method calls on request and response objects), which is how Jahia manages to route different services to sub web applications, as well as post-process the output of the web applications before it is sent back to the client browser.

Contexts and class loaders

One important limitation of having separate web applications as “portlets” in a Jahia system is that each application is being executed in it’s own separate servlet context. A context con-tains notably:

class loaders for application specific classes and libraries

session attributes (the session is unique for each client browser, but the attributes are local to a context and cannot be accessed from another web application’s context)

servlet configurations

The notion context is very important, notably in environment where security is an issue. For example if we have two web application deployed in the same server in a hosting environ-ment, they should not be able to interfere with each other if the server administrator does not want to allow it. Typically this means that cross-context dispatching will be forbidden. Jahia actually requires cross-context to be allowed, because it is itself a web application that wants to dispatch to other web application.

The separate class loader limitation is very important. Basically it allows different web appli-cations to use different versions of the same libraries without any conflicts. If we look at Tom-cat’s implementation and usage of class loaders, we can see that they are organized as a tree hierarchy, such as below:

HTTP Connector

Servlet Dispatcher


Servlet Dispatcher

Hello Web App Request Response



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

Figure 3-2 Class loader hierarchy in Tomcat

The rules for class lookup are a bit particular, but here is a detailed order of lookup for a sam-ple web application:

1. /WEB-INF/classes of your web application 2. /WEB-INF/lib/*.jar of your web application 3. Bootstrap classes of your JVM

4. System class loader classes (described above) 5. TOMCAT_HOME/common/classes

6. TOMCAT_HOME/common/endorsed/*.jar 7. TOMCAT_HOME/common/lib/*.jar 8. TOMCAT_HOME/shared/classes 9. TOMCAT_HOME/shared/lib/*.jar Basically the rule for lookup is the following:

1. Look in the current web application for a class

2. Then from the “shared” class loader, always first look in parent for a class, then in the current node.

The reason we go into so much detail about class loaders is to correctly explain the fact that web application are not allowed to access Jahia classes directly, and this means they will have limited ways of communicating with Jahia, and especially they will not be able to access classes such as JahiaData or ParamBean since these classes are only present in Jahia’s class loader. One way around this limitation would be to copy Jahia’s classes into the “shared” class loader, but this might cause other conflicts with common classes between the web application and Jahia (usually this occurs with very common classes such as XML pars-ers, XSL transformpars-ers, logging classes, database drivpars-ers, etc....). Also, as this procedure is risky, it is not supported by Jahia’s developers.

3.2.4 Transforming action URLs to use encodeURL

As presented in Chapter 2, the use of response.encodeURL() method is central to porting an existing application to Jahia.

The immediate question that comes to mind when working with existing code is:

“How do I know which URLs I should encode and which are the ones I can leave as they are?”

The easiest way to answer this, although not necessarily the most accurate would be: “You should encode every URL generated by the application except for image URLs and in general access to static data (such as data files, etc.).”

The most important URLs to convert are <form> action URL such as the following:

Bootstrap System Common

Catalina Shared



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

1 : <form method="post" action="<%=request.getContextPath() + “/hello” %>"> 2 : Enter your name: <input name=”name”>

3 : <br/>

4 : <input type=”submit” value=”Submit”> 5 : </form>

The problem with the above code is that although it will work fine in a standalone web appli-cation, Jahia is no longer involved in the processing of the request, and we will loose all con-text information of the current Jahia user. Basically we want a way for the action URL to be modified so that we stay in a Jahia context. Jahia offers a URL modification services that is embedded in the call to the response.encodeURL() method, and that will perform the neces-sary URL transformations necesneces-sary to stay in the portal context. So the modified code that is portal-aware will look like this:

1 : <form method="post" action="<%=response.encodeURL( request.getContextPath() + "/ hello" ) %>">

2 : Enter your name: <input name=”name”> 3 : <br/>

4 : <input type=”submit” value=”Submit”> 5 : </form>

Note that the above modification is in no way Jahia-specific in terms of implementation and will work seamlessly in standalone mode too. Actually the call to encodeURL is usually rec-ommended if you want your application to support session tracking with clients that do not support or accept cookies. So in effect although this modification must be done everywhere an action URL is used, it will only improve your application and not make it specific to Jahia, but at the same time making it portal aware.

You will also need to perform the encoding of URLs on HTML <a> tags if they are used to per-form actions to a servlet. If they are links to external sites (such as in the case of a bookmark application for example), then they do not need to be encoded.

It is also recommended not to encode URLs that do not need to be, such as usually <img> tags that access a static image (for dynamically images this is a different story), because it will make unnecessary requests to Jahia’s portal, for resources that could very well be accessed directly.

3.2.5 Single sign-on

or how can I make sure the user must enter his password only once for all portlets ? As soon as you have multiple web applications running on a single servlet container, you will want to offer services to allow the user to login only once and be recognized in all applica-tions. There are even cases where this must be done across servers and in such cases solu-tions such as Liberty Alliance (http://www.projectliberty.org/) become interesting.

In Jahia portals, the goal is mostly to integrate with Jahia’s authentication system and be able to re-use authentication information, so that the user only needs to login once in the portal. Basically, by using the request and response wrapper object presented in Chapter 2, Jahia maps authentication through the following method calls:

• request.getRemoteUser()

• request.getUserPrincipal()

• request.isUserInRole()

It is assumed in this section that are familiar with the regular usage of these methods in stan-dard J2EE web applications. If you are not, it is strongly recommended you refer to the J2EE specification and/or to guides on how to use these methods for user and role usage. Also it is also recommended that you become familiar with the deployment of web applications that use the methods in a standalone environment, which will greatly help when porting or writing the application for Jahia.

We will now present the new semantics of the above method calls as they are defined for an application running under Jahia’s context. For the original semantic of these methods we point you to the original Servlet API specification.


When running under Jahia, returns the login name for the current user. For example if the user that logged in Jahia is called “root”, this method will return a String containing “root”. Note that there is no guarantee that this name is unique when Jahia uses multiple sites, and



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

that you may encounter multiple users with the same name, but that are coming from different sites. In order to get around this, you can use the context data sent by Jahia such as the cur-rent site, which the application may use to guarantee unicity of user information. We will details these context parameters further in this document.


When running under Jahia, returns an Object that implements java.security.Principal interface and that represents the currently logged in user in the Jahia portal. Again as with the getRem-oteUser() call, the getName() method on the Principal interface will not return a name unique to a Jahia installation but only to a site, so it is recommended to use this in conjunction with the sitekey that is available in special request parameters set by Jahia and described further in this document.

HttpServletRequest.isUserInRole(String roleName)

When running in Jahia, tests if the current logged in user is part of the role roleName. Usually in web applications you will want to use roles instead of users in order to allow users to com-bine roles and/or have separate responsibilities for groups of users. Role mappings are defined when instantiating an “portlet” web application on a page. The next section presents in details how role mapping works with Jahia.

3.2.6 Web application role mappings

or how can I define and manage user roles in my web application ?

In the servlet specification, web applications have the possibility to declare and use roles to regroup users. Users may be part of multiple roles at a same time. The web application is not in charge of mapping users to roles, that is the responsibility of the J2EE servlet container. The application can then interrogate the servlet container to know whether a user is present in a role through the Servlet API call:

HttpServletRequest.isUserInRole(String roleName)

In the case of a web application running inside a Jahia portal, the mappings from user to roles will be performed by Jahia, and the above servlet API call will be intercepted to use Jahia’s role mapping system. Figure 3-3 presents a screenshot of the HTML GUI interface for map-ping roles to users and/or groups. Mapmap-pings roles to groups is a powerful way of mapmap-ping groups of users to a role. So in this example the “manager” role has been assigned to all members of the Jahia “administrators” group on the current site.

Figure 3-3 Jahia Web appli-cation role mapping popup

As we can see in Figure 3-3, Jahia allows for graphical configuration of roles declared in web applications.



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

Defining roles in a web application

A web application defines the roles it uses by using the <security-role> tag in the web.xml deployment descriptor file such as in the example below:


<role-name>editor</role-name> </security-role>

In the current version of Jahia, only <security-role> tags are used for role definitions, and <security-role-ref> references are ignored, so it is recommended that all the roles are prop-erly defined with the <security-role> tag.

When the web application is deployed, Jahia will read from the deployment descriptor the roles that were defined and will internally create groups for each web application that the user can manipulate using the GUI presented in Figure 3-3.

An application can then test the presence of the current user in a certain role using code such as below:


3.2.7 Single entry point into web application

or how do I know what servlet Jahia will call upon first access ?

Jahia supports only one entry point per web application, so it is important to know how to define this entry point so that you can route requests to the proper controller servlet in your new or existing application. We have already covered this topic in the previous chapter, under section 2.2.2

3.2.8 Special request attributes set by Jahia

or how can I get information about Jahia’s current context from my web application ? Jahia inserts attributes into the request object that can be very interesting to applications developers. Note that the use of these attributes will make the application Jahia specific, whereas most of the other interceptors are not. The table below describes the name, type, possible values of the attributes set by Jahia and that may be accessed by web applications through the request.getAttribute(String attributeName) Servlet API call:

Table 3-1 : Jahia-specific request attributes

Attribute name Type Value Description

"org.portletapi.portal" String “true” Always set to value “true” in Jahia. This is the recommended way to determine whether it is running in standalone or within a Jahia Portal

"org.portletapi.userlist" Vector of String objects

List of user names Contains a list of user names that correspond to all the users that are in any role of the application. Useful to present a list of users for application-specific user assignments. Be warned though that it usually is a better idea to use roles for this but it may not always be possible.

"org.portletapi.contextid" String == fieldID The contextid is a String that is useful to have an identifier to separate different instances of the same application. Jahia allows the same application to be instantiated multiple times on the same page. The contextID will be an identifier that will change among these instances, so that instance specific data may be stored in the application. In the current implementa-tions of Jahia, the contextID is equivalent to the fieldID that contains the application.

"org.portletapi.fullscreen" String “true” / “false” Not yet fully implemented. This attribute tells the application whether it is running in full screen mode or not. Basically if this attribute is true, the application may take over the whole screen, including HTML headers, etc.



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

3.2.9 Session Attributes

or how can I access Jahia’s session attributes if at all possible ?

By default, Jahia does not share it’s session attributes with application session attributes. This means that if you set an attribute in Jahia’s session (through a scriptlet or tag in a tem-plate) using a call similar to this:

request.getSession().setAttribute(“name”, “value”);

You will not be able to access it from your application through the following call: request.getSession().getAttribute(“name”);

This limitation exists for security reasons, as application should be as separates as possible in order to avoid namespace conflicts, as well as attribute corruption, etc. But it is possible to deactivate this limitation by using a special setting in the jahia.properties configuration file. webapps.dispatcher.inheritJahiaSessionAttributes = true

The default setting is false, and settings this parameter to true will authorize web applications to access Jahia’s session attributes.

If you need to communicate in the other direction, from a web application to Jahia, it is not possible to use session attributes. You need to do this using request attributes.

3.2.10 Cache management

or why isn’t my application being called for each request that I make on a page ?

Jahia is an application that makes heavy use of data extracted out of a database. Unfortu-nately, a database back-end, while usually very scalable, is an expensive system in terms of performance. This is why database back-ends are often paired with in-memory caches to improve overall speed. This is possible because in a CMS and Portal server such as Jahia, read operations are much more frequent that write operations, so the benefit of caches becomes immediate.

Basically Jahia has 3 caches that are important to application developers:

1. Front-end HTML page cache : used to store the full HTML generated by a request, so that subsequent requests for the same content will be served very quickly. This cache is the ultimate cache because it allows for extremely fast response times if it is not too often bypassed (unfortunately this is rarely the case for dynamic web applications).

2. Web application output cache : used to store the output of a single web appli-cation’ HTML fragment. The idea here is that when we have a page with more "org.jahia.sitekey" String jParams.getSiteKey () The unique String identifier for the current site. You should use

this in conjunction with the request.getRemoteUser() call in order to make sure you have a unique user on a Jahia installa-tion. For more information about the getRemoteUser limitation check 3.2.5

"org.jahia.siteurl" String jParams.getSiteURL () A String object that contains the siteURL parameter entered that usually corresponds to the domain name for the site, i.e.: www.jahia.org, www.jahia.com, etc....

"org.jahia.siteid" String Integer.toString (jParams.getSiteID ())

A String object that contains an integer value that corresponds to the database identifier for the site.

"org.jahia.pageid", String Integer.toString (jParams.getPageID ())

A String object that contains an integer value for the page num-ber that the application is being displayed on.


String jParams.getOperation-Mode ()

The current operation mode of the page. Possible values for this attribute in Jahia 4 are: “normal” (also called Live in our templates), “edit” (content edition mode), “debug” (not used, but still accepted in page URLs), “preview” (preview modifica-tions to a page before it gets published in live mode), “com-pare” (a special mode to compare two versions of the content on the page)

Table 3-1 : Jahia-specific request attributes



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

to all the applications on each request when only one is really concerned by the current incoming request. This cache makes sure that we only really dis-patch to the current target application, and that all others simply display what-ever they were displaying previously. Of course this might cause problems if we have applications that must be refreshed regularly such as news tickers or instant messaging, but Jahia offers a way for applications to control this cache. 3. Web application request cache : used to cache the last requests that were sent to the application. This is mostly to make sure we remember the last applica-tion entry point used in cache the applicaapplica-tion request cache has been flushed. So basically the first entry point is automatically generated by Jahia based on the declarations in the web.xml (see the “Entry Point” section in this manual), and then subsequent GET requests are stored in this case in case we need to regenerate a call to the application. POST requests are never stored in this case in order to reduce the problems of submitting the same request twice. This implies that the same GET request may be posted multiple times to a web application, and that it should work despite that.

Web applications running in a Jahia portal must be designed to work well with the various cache layers. It is important for application developers to understand how these caches work, because it will have important effects on the way the application is dispatched to.

In the flow diagram on Figure 3-4 we present the processing for a request to a web applica-tion, in regards to how the different caches are accessed. This graph gives a detailed inside look as to how the caches are used.

Figure 3-4 Cache processing during a request to a web application

In the above flow design, Jahia tries to use caches as early as possible to always keep total request time to an absolute minimum.

Incoming page request

Are we bypassing the HTML cache ?

Is the page available in the HTML cache ?

Send HTML cache for page to client browser No Yes

Outgoing page response

Are we processing a

webapp action request ? cache for the webapp ?Is there an output Get webapp output from cache

Store page output in HTML cache ?

Template-based Page aggregation Store page output in HTML cache No No Yes Yes No Yes Is there a cached request for the webapp ?


Build entry point request for webapp Store request in request

cache for webapp No Dispatch to webapp Yes Store webapp output in cache ? Yes Store output in webapp output cache Yes


HTML Cache Webapp Output Cache Webapp Request Cache Legend :



Chapter 3 • Porting existing applications to Jahia, or simply writing advanced applications with Jahia

- DR AFT -W ebapps / Portlets d evelo p me nt

Cache control through URL parameters

Jahia offers a mechanism for controlling the front-end caches (HTML and web application output cache) simply through URL parameters. By default the front-end caches are activated. The name of the URL parameter is a “path” parameter called “cache”. So in effect here are different URLs that illustrates possible values for the parameter:

http://localhost:8080/jahia/Jahia/pid/1 (means the cache is on) http://localhost:8080/jahia/Jahia/pid/1/cache/offonce

http://localhost:8080/jahia/Jahia/pid/1/cache/off http://localhost:8080/jahia/Jahia/pid/1/cache/bypass

The different modes not only control the loading from the cache but also the URL generation on the page. Depending on the cache mode the URLs will be generated with a special cache mode or not.

The different modes are summarized in Table 3-2 :, and describe the mode that was specified in the URL parameter, whether Jahia will try to read from the cache, whether Jahia will update the cache, and finally the mode for the URL generation, which will basically be the next cache mode for the page.

Warning : the /cache/off mode will generate all URLs on the page with /cache/off again, so this is not recommended when developing templates or generating your own URLs, because from that point on all navigation will be done in cache off-mode and be much slower. This mode is mostly reserved for development purposes, in order to check the functionality without cache.

In this chapter we will not expand on this mechanism of cache control because the web appli-cations are not able to control URL generation for a page, but this was presented for refer-ence as it also helps explain how the cache works, and how it may be controlled for a page, notably for debugging and testing purposes.

Cache expiration control mechanism

Jahia offers a way for web applications to control the expiration of the web application output cache. Actually this will also control the expiration of the HTML cache, but this is transpar-ently done by Jahia, so all you need to know is how to control the output cache. However, the web application request cache expiration can not be controlled by application, but it should not need to.

Using a special request attribute name, an application can set an expiration delay in millisec-onds for it’s output cache to expire. This can be very useful for applications that need to be refreshed often, such as news syndication services, tickers, and so on.

In Table 3-1 : Jahia-specific request attributes, we present the details of this mechanism for

controlling the cache output. Again this is specific to Jahia so it will have no effect in standal-one mode or on other portals.

Table 3-2 : Cache modes and effects

Mode HTML Cache Read HTML Cache Write URL mode

on yes yes on

offonce no yes on

off no no off

bypass no no on

Table 3-3 : Special cache control request attribute

Attribute name Type Description

"org.jahia.portletapi.CacheExpirationDelay" Long Specifies in milliseconds the delay after which the web appli-cation output cache will expire. -1 means the cache will never expire, whereas 0 means the cache will never be stored.





Related subjects :