GateIn Cookbook

4 (1 reviews total)
By Ken Finnigan , Luca Stancapiano , Piergiorgio Lucidi
  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Getting Started

About this book

Enterprises have websites constructed in different web frameworks and the need for them to work together cohesively. GateIn will provide the solution to effectively integrate them into a single website. GateIn is an open source website framework that does more than a web framework by letting you use your preferred one.

This GateIn Cookbook provides solutions whether you're planning to develop a new GateIn portal, migrate a portal, or only need to answer a specific query. It is filled with bite-sized recipes for quick and easy problem resolution. From the beginning to the end it will guide you through the process of configuring and securing a portal, managing content and resources, and developing applications as you go.

Beginning with installation and configuration, the book swiftly moves on to discussing content, users, and security. The second half covers all aspects of developing on a portal, such as portlets, gadgets, migration, and integration.

The goal of the book is to show GateIn as an open source website framework piece by piece. Starting with simple recipes, you will see each step analyzed with code examples and images, before progressing to more advanced recipes.

This GateIn Cookbook will help you with a quick approach to building portals.

Publication date:
November 2012


Chapter 1. Getting Started

In this chapter we will cover:

  • Installing GateIn from binary package

  • Building and installing GateIn from the source code

  • Configuring the content storage

  • Configuring GateIn to send e-mails

  • Running GateIn on your machine

  • Setting up the development environment



This first chapter will discuss how to install a GateIn instance on your local environment. We will see that there are two main ways to achieve this task.

We will then look at how to configure a different content store for data so that you can use your preferred DBMS and your file system. Then we will see how to set up the GateIn mail sender to allow you to use the SMTP server available in your network.

At the end of the chapter, you will understand what the architecture of GateIn is and how to configure and run a portal instance on your machine.

GateIn is a portal framework dedicated to implementing highly customizable portal solutions with a powerful set of components based on well-known and adopted open source technologies and standards based on the Java web technologies.


Installing GateIn from a binary package

GateIn is released through different bundles that differ for the included application server. These bundles are dedicated to the following application servers—JBoss AS 5.x, JBoss AS 6.x, JBoss AS 7.x, Tomcat 6.x, Tomcat 7.x, and Jetty 6.x.

In this recipe, we will see which are the required packages you need to download before starting a GateIn instance.

Getting ready

A pre-requisite for running GateIn is the availability of the Java Development Kit (JDK), which must be updated to the latest revision of version 1.6. Depending on your operating system, please be sure to correctly add the JDK binaries' path to the classpath of your machine. In order to verify the Java version actually installed on your machine, you can run the following command line:

java –version

It will return an output similar to the following:

java version "1.6.0_29"
Java(TM) SE Runtime Environment (build 1.6.0_29-b11-402-10M3527)
Java HotSpot(TM) 64-Bit Server VM (build 20.4-b02-402, mixed mode)

If you don't find in the output the string Server VM, but you find the string Client VM in the place of Server VM, this means that the JDK is not installed on your machine. In this case, you can download the JDK 1.6 for your operating system at

How to do it...

  1. As introduced before, GateIn can be installed using different packages, so now you can download your preferred bundle depending on which application server you need to use for your installation.

  2. Typically, the right application server can be chosen by thinking about what you need for your software architecture. Let's assume that you need to deploy GateIn together with other standard Java EE applications that need explicit support for middleware components such as DataSource, Enterprise Java Bean (EJB), Java Message Service (JMS), or an Enterprise Service Bus (ESB). You would then probably want to use the JBoss AS bundle. JBoss AS is completely focused on middleware support having the availability of a total J2EE-compliant application server. Otherwise, if you only need to use a standard servlet container, you can choose to download the Tomcat bundle.

  3. Once you have chosen the right bundle for yourself, you are ready to download it from .

  4. After downloading the GateIn package, you can extract it in your preferred directory in your file system.

How it works

You have just installed GateIn from binary package.

There's more...

The difference between the various bundles is related to application server-specific configuration files and directories, with some added artifacts. For example, the JBoss 6.x directory structure consists of the following folders:

  • bin

  • client

  • common

  • docs

  • lib

  • server

The Tomcat 6.x bundle is based on a different structure:

  • bin

  • conf

  • gatein

  • lib

  • logs

  • temp

  • webapps

  • work

The Tomcat bundle also has a further execution script compared to the JBoss bundle, but we will see how to run a GateIn instance for all the different application servers later in the chapter, in another recipe.

See also

  • The Building and installing GateIn from the source code recipe

  • The Running GateIn on your machine recipe


Building and installing GateIn from the source code

Another way to install GateIn is by getting the source code from the JBoss SVN repository and then compiling it to generate the build artifacts as you found in the binary package.

The goal of building GateIn from the source code is to have the possibility to freely customize it. Another useful reason for building from source is that you simply want to contribute to the project and test your fixes before applying the patch on the issue tracker.


Notice that this book is based on GateIn 3.2.0, which has its source code based on the SVN repository. From GateIn 3.3.x the source code is based on a GitHub repository. For more information about how to build from GitHub, please see

Getting ready

Let's first see if you have installed in your machine the following needed components:

  • Java Development Kit (JDK) 1.6

  • Subversion client (SVN)

  • Apache Maven 3.x

Let's check your environment for the see following required tools:

  1. You can test and install JDK 1.6 following the Getting ready section of the Installing GateIn from a binary package recipe.

  2. To test if the SVN client is installed in your machine run the following command line:

    svn --version

    If the SVN client is correctly installed you should see output similar to the following:

    svn, version 1.6.17 (r1128011)
       compiled Aug 25 2011, 17:31:03
    Copyright (C) 2000-2009 CollabNet.
    Subversion is open source software, see

    If the svn command is not found in the scope of your operating system, then you can install it by following the instructions available on the official website, depending on your operating system, at

  3. Once the SVN client is installed, the next step is to test if Apache Maven is installed on your machine, by running the following command line:

    mvn --version

    After running the command, you should see an output similar to the following:

    Apache Maven 3.0.4 (r1232337; 2012-01-17 09:44:56+0100)
    Maven home: /Users/piergiorgiolucidi/tools/apache-maven-3.0.4
    Java version: 1.6.0_29, vendor: Apple Inc.
    Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
    Default locale: it_IT, platform encoding: MacRoman
    OS name: "mac os x", version: "10.6.8", arch: "x86_64", family: "mac"

    If the mvn command is not found in your machine then it could mean either of the following two things:

    • You have to configure the PATH environment variable

    • You have to install Apache Maven from scratch

    We are going to assume that maven is not installed. In this way, we will describe both the cases:

    • Download the Apache Maven binary at .

    • Extract the binary package and follow the specific instructions that are described in the web page according to your operating system.

      Notice that you have to set two environment variables to allow Maven to work correctly, so please be sure to set the PATH and M2 variables before continuing. For instance, for a Linux-based operating system, you should have a snippet in your profile configuration file similar to the following:

      export M2_HOME="/Users/piergiorgiolucidi/tools/apache-maven-3.0.4"
      export M2=$M2_HOME/bin
      export MAVEN_OPTS="-Xms512m -Xmx1024m -Xss1024k -XX:MaxPermSize=256m -XX:NewSize=256m"
      export PATH=$M2:$PATH
  4. Finally, check if you have installed the latest stable release of Apache Maven before continuing the recipe.

How to do it...

Now we are ready to check out the source code. For this book, we will consider the current latest stable version of GateIn Portal, which is version 3.2.0.

  1. Check out the code on your machine by executing the following comman line:

    svn checkout gatein-portal-3.2.0
  2. Once you have finished the download, you will find a new subfolder gatein-portal-3.2.0 in the folder where you have executed the command that contains all the source code of the project.

  3. Now we are ready to build the project using Apache Maven. For this step, we have some parameters to set:

    • Which type of bundle you have

    • Whether the build process must download the application server distribution

    • The path of the root folder of your application server distributions (if you have an existing distribution package)

    • The name of the folder related to the application server distribution to use for building

  4. Let's assume that you want to build GateIn with the Tomcat 6 bundle and, considering that the Tomcat distribution is stored in the /Applications/Apache Tomcat/apache-tomcat-6.0.32 folder, you have to execute the following command line from the root folder of the project that contains the main pom.xml file:

    mvn clean install -DskipTests -Ppkg-tomcat Tomcat

    Upon completion, you should see the following output:

    [INFO] -------------------------------------------
    [INFO] -------------------------------------------

    The binary artifacts will be available on your machine inside the /gatein-portal-3.2.0/packaging/tomcat/pkg/tc6/target/tomcat6 folder.

How it works...

As you have seen, the GateIn packaging process relies upon Apache Maven to execute the build process of the project. However, Maven allows you to manage the entire lifecycle process of the project and its own children modules by starting a command from a parent Project Object Model (POM).

In this recipe, we have invoked two Maven phases to execute the build process of the project—the clean phase and the install phase.

The clean phase will remove all the compiled artifacts created by prior builds to initialize the build state of the project. Typically, the final result of the clean goal is that the target folder will be removed for each submodule of the project.

The install phase will start the complete Maven lifecycle executing all the phases up to install. The details of this execution process are as follows:

  1. Validate

  2. Compile

  3. Test

  4. Package

  5. Integration-test

  6. Verify

  7. Install

Each phase is responsible for specific goals that need to be processed before the next phase.

The parameter skipTests used in the previous Maven command allows skipping the execution of tests from the lifecycle process. This means that when Maven is executing, the entire process will skip the execution of the test phase for each module.

So if you want to contribute to the project or you are customizing the product for your needs, you will probably want to remove this parameter. This is because if you want to be sure that your own implementation correctly works with all the other modules included in GateIn, you probably want to execute all the tests included in the project.

See also

  • The Installing GateIn from a binary package recipe

  • The Running GateIn on your machine recipe

  • The Setting up the development environment recipe


Configuring the content storage

By default, GateIn is configured to use the Hypersonic SQL database and a relative folder in the bundle to manage the content storage. This type of setting is only useful for running a product demo without specifying any parameter, but this is not the suggested way to set up the platform for a production environment.

For production system environments, you should configure GateIn for using external DBMS and using a file system with good I/O performance to prevent bottlenecks during reading and writing operations on contents and search indexes.

We are going to configure the components that manage content storage in GateIn:

  • exoJCR: This is an open-source implementation of the Java Content Repository (JCR) specification provided by the eXo Community. It is used internally by GateIn to manage all the content data related to portals, pages, portlets, and metadata.

  • PicketLink IDM: This is an open-source project that can be embedded in any standard Java EE application and allows managing user identities by storing the information in a database. It also supports many ways to negotiate credentials and Single Sign On (SSO) mechanisms.

Let's first configure exoJCR, which is the component responsible for the content storage in the portal. This component consists of two physical storage elements:

  • Database

  • File system

Finally, we will see how to configure a JBoss identity that is based only on a separate database instance.

Getting ready

Locate the configuration file in the shared class loader according to your application server. Assuming that you are using Tomcat, the configuration file is located here:


If you are using JBoss AS 6 you will find it at the following location:


If you want to use JBoss AS 7, you have to edit the configuration file here:


How to do it...

Carry out the following steps to configure the content storage:

  1. Locate the following properties inside the configuration file:

    • gatein.jcr.datasource.driver

    • gatein.jcr.datasource.url

    • gatein.jcr.datasource.username

    • gatein.jcr.datasource.password

    The default database settings of the JCR component of GateIn are based on these standard JDBC parameters:

    • gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver

    • gatein.jcr.datasource.url=jdbc:hsqldb:file:${}/data/jdbcjcr_${name}

    • gatein.jcr.datasource.username=sa

    • gatein.jcr.datasource.password=

    The above parameters will configure your HSQL database in a folder in your file system. As you can see, the parameter named, used for the value of the parameter gatein.jcr.datasource.url, allows you to set a specific folder that will contain all the content storage dedicated to the GateIn instance.

    These parameters allow you to set the typical settings for a JDBC connection, so for example, if you need to configure Oracle DBMS for the JCR database, you should have a similar configuration to the following:

    • gatein.jcr.datasource.driver=oracle.jdbc.OracleDriver

    • gatein.jcr.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInJcr

    • gatein.jcr.datasource.username=<ORACLE USERNAME>

    • gatein.jcr.datasource.password=<ORACLE USER PASSWORD>

  2. You or your DBA must create the database schema and the user above in your DBMS instance before running GateIn. The user credentials used by GateIn must have all the necessary permissions to manage tables and rows in the database instance. Notice that the default encoding for the database needed by GateIn is latin1, so be sure to set this parameter in your DBMS configuration.

  3. Remember to copy the database JDBC driver (packaged as a JAR) to the library folder of your application server. In this way, GateIn can correctly use the existing database instance.

    For Tomcat, you can copy the JDBC driver in this folder:


    For JBoss 6 AS you can use this one:


    For JBoss 7 AS the following directory is available here:

  4. Now that we have configured the database for the JCR component, we can continue configuring the JCR file system location. This section allows you to set a specific file system dedicated to store all the binaries and search indexes files managed by GateIn. The default properties' values relating to the file system configuration are as follows:





    Using these parameters, you can change the default location of the content binaries of GateIn. Here, you can change the default configuration for contents and search indexes as needed for your architecture.

  5. Configure another database schema dedicated to the identity manager.

  6. The built-in properties' values for the database JDBC connection of the identity management are the following:

    • gatein.idm.datasource.driver=org.hsqldb.jdbcDriver

    • gatein.idm.datasource.url=jdbc:hsqldb:file:${}/data/jdbcidm_${name}

    • gatein.idm.datasource.username=sa

    • gatein.idm.datasource.password=

    As seen above for the JCR database settings, a potential configuration for an Oracle database dedicated to the identity manager could be the following:

    • gatein.idm.datasource.driver= oracle.jdbc.OracleDriver

    • gatein.idm.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInIdm

    • gatein.idm.datasource.username=<ORACLE USERNAME>

    • gatein.idm.datasource.password=<ORACLE USER PASSWORD>

How it works...

In the previous steps, we have configured the content storage of GateIn that will be used to create all the needed data structures (tables in the database and folders in the file system) for managing portal contents.

When the application server runs for the first time, GateIn will automatically create all the needed data structures in the database and inside the file system.

The database connection used in GateIn is a standard JDBC connection that requires the usual parameters for configuration:

  • JDBC driver class


  • Username

  • Password


The driver class is the Java class of the DBMS driver that allows remote access to the database instance for managing JDBC connections.

The value for the JDBC URL must follow your specific DBMS conventions to locate the database instance remotely via JDBC.

The username and password are related to a specific users credentials that GateIn must use to access and manipulate contents in the database.

There's more...

You also have the possibility to configure contents and indexes to increase performance during searching or creating contents. This is done by changing locations to machines with better hardware for both of the components.

A typical approach is to dedicate the local file system storage to the Apache Lucene indexes ( and a high-performance storage location for contents, setting a different value for the property.


Apache Lucene is an open-source text-search engine library used in many Enterprise products to create and manage content indexes. It supports execution of queries based on the Lucene Query Language, which is a very powerful query language that can search contents by ranking, phrase, and exact match. Lucene is licensed under Apache Software License Version 2.0.

For more information about Lucene, you can visit the project website at

MySQL example configuration

In order to configure MySQL for the database storage of GateIn, you should edit the configuration file in a similar way for JCR, following the related conventions:



gatein.jcr.datasource.username=<MYSQL USERNAME>

gatein.jcr.datasource.password=<MYSQL USER PASSWORD>

For the identity manager you should have the following:



gatein.idm.datasource.username=<MYSQL USERNAME>

gatein.idm.datasource.password=<MYSQL USER PASSWORD>

Finally, remember to copy the MySQL JDBC driver library into the application server library folder in order to make the driver class available to GateIn.

See also

  • The Configuring GateIn to send e-mails recipe

  • The Running GateIn on your machine recipe


Configuring GateIn to send e-mails

GateIn includes notification features that send e-mails to users when a specific action is performed on the portal, for instance the forgot password feature. There is another snippet to change in the configuration file to enable GateIn to send e-mails.

These are the usual properties required to configure an SMTP server in your local network.

Getting ready

Locate the configuration file as described in the previous recipe.

How to do it...

Carry out the following steps in order to configure GateIn to send e-mails:

  1. Locate in the e-mail section of the configuration file the following snippet:

    # Email
  2. Change the default configuration to allow GateIn, using your specific SMTP server settings for sending outgoing e-mails. As you can see, by default GateIn is configured to work on a Gmail account.

How it works...

GateIn can send outgoing e-mails using its internal MailService, which needs to be configured using the usual parameters for setting up an SMTP connection:

  • Username

  • Password

  • Host

  • Port

  • EnableTls

  • Auth

  • Socket factory port

  • Socket factory class

Username and password are the values that identify the e-mail account that you want to use in GateIn.

Host and port are used to set your SMTP server endpoint address.

EnableTls and Auth are used to set the needed authentication mechanism to process any operation.

Socket factory parameters are specifically used for instancing secure connections on your SMTP server. In this case, be sure to have correctly installed any security library needed to process the SSL specific request.

See also

  • The Configuring the content storage recipe

  • The Running GateIn on your machine recipe


Running GateIn on your machine

Let's assume that you have correctly configured GateIn as shown in the previous recipes or are using the default settings found in the standard binary package. Now we are going to run GateIn for the first time.

Getting ready

Locate the bin folder of your application server; this is the location where the start/stop script is stored in your machine. Here are the details for the scripts in different application servers:

  • If you are using Tomcat then you have a specific script, for Windows gatein.bat, provided in the binary folder <TOMCAT_HOME>/bin

  • For JBoss AS 6 you can use the standard script available in this folder <JBOSS6_HOME>/bin

  • JBoss AS 7 requires using the script stored here <JBOSS7_HOME/bin>

How to do it...

Supposing that we are using Linux as the operating system, we would follow these steps:

  1. To start GateIn using Tomcat use the following command line from the current bin folder:

    ./ start
  2. Once the command above executes, you can take a look at the log file with the following command:

    tail –f ../logs/catalina.out

    Now you can start using the portal, pointing your browser at http://localhost:8080/portal.

  3. If the first deployment of GateIn finishes without errors we expect to see in the browser the following homepage of the default portal:

  4. In order to stop the GateIn instance use the following command line:

    ./ stop

How it works...

GateIn is distributed as a standard Java EE application that needs to be deployed in an application server.

In this recipe, we have seen how to start and stop a Tomcat instance by using a specific script file provided by GateIn developers.

For each specific application server you must follow the correct procedure to use the dedicated script file to start and stop the portal instance.

There's more…

We will take a look at how to start GateIn with different versions of JBoss application servers.

Starting GateIn with JBoss AS 6 instance

If you are using GateIn with JBoss AS 6, you have to use the following command line:

nohup ./ & 

Then you can access the log file in the following way:

tail –f nohup.out

To stop the instance you can use the following command line:

./ -S

Starting GateIn with JBoss AS 7 instance

Otherwise, if you are using JBoss AS 7 use the following command line:

nohup ./ &

The log file can be viewed in this way:

tail –f nohup.out

To stop the JBoss 7 instance run the following command:

./ –connect command=:shutdown

See also

  • The Configuring the content storage recipe

  • The Configuring GateIn to send e-mails recipe


Setting up the development environment

GateIn is developed using the Apache Maven lifecycle process and this guarantees that the project can be used with any standard development environment.

In this recipe, we will learn how to import the GateIn project in Eclipse IDE (you can use any other IDE that supports Maven). You will also see how to install JBoss tools in Eclipse to add support for developing standard portlets and all Java EE components provided by JBoss.

Getting ready

  1. Download Eclipse IDE for Java EE Developers at .

  2. Install Eclipse on your machine, launching the executable and following the installation instructions.

How to do it...

Set up your development environment following these steps:

  1. Launch Eclipse and create a new workspace dedicated to GateIn.

  2. Click on Help | Eclipse Marketplace.

  3. Search jboss tools and click on the Go button.

  4. Locate the JBoss Tools version required for your specific Eclipse version and click on the Install button.

  5. In the Confirm Selected Features window, select all the items and click on the Next button.

  6. In the Install Details window, click on the Next button.

  7. In the Review Licenses window, read and accept the terms of the license agreements and click on the Finish button.

  8. Wait for the installation process of JBoss tools to complete. Once the installation is finished, restart Eclipse.

  9. After the restart, you should see the overview of what you can do with JBoss tools with a similar tab in your Eclipse environment:

  10. Right-click on the Package Explorer tab and select Import.

  11. Browse the Maven category and select Existing Maven Projects and press the Next button.

  12. Insert as Root Directory the GateIn source root folder that you have created in the previous recipe.

  13. Click on the Next button and then click on Finish.

  14. Be sure at the end of the import process to update the project configuration of all the Maven modules— in the Package Explorer window select all the modules, right-click, then select Maven | Update Project Configuration and finally click on OK.

How it works...

The source code of GateIn is based on Maven, but by default, Eclipse IDE does not support it. The JBoss tools package includes the m2eclipse plugin that allows managing Maven projects inside Eclipse IDE. So in order to develop your own solutions make sure to use an IDE that supports Maven.

We have configured Eclipse to manage JBoss middleware and Maven projects and then we have imported the GateIn source code to let you contribute to the product or create your own customizations.

The following are all the example modules available in the GateIn source code:

  • GateIn Portal Sample

    • GateIn Portal Sample Extension

    • Sample Configuration

    • Sample Ear

    • Sample War

    • Sample Jar

    • GateIn Portal Sample Portal

    • GateIn Portal examples—Portlets

    • API Sample Portlet

    • JSF Sample Portlet

    • JSP Sample Portlet

    • Standard Sample Portlet

    • Struts Sample Portlet

    • Resource Serving Sample Portlet

    • GateIn Skin Sample

See also

  • The Building and installing GateIn from the source code recipe

About the Authors

  • Ken Finnigan

    Ken Finnigan is a Senior Software Engineer at Red Hat, technical lead of the JBoss Portlet Bridge project, a member of the GateIn development team, and the founder of the Arquillian Portal Extension. As a consultant and engineer he has over 15 years development experience with enterprises throughout the world using technologies that include Java EE frameworks (JSF, CDI, EJB3, Hibernate, and Seam), Java testing frameworks (Arquillian, JUnit, and TestNG), Maven, Ant, and a variety of others. In his spare time, he is a committer for Apache DeltaSpike, ShrinkWrap, and Arquillian. He is also the author of GateIn Cookbook, Packt Publishing.

    Browse publications by this author
  • Luca Stancapiano

    Luca Stancapiano has been working in the IT industry since 2000. He specializes in Java EE and JBoss, and has collaborated with Apache, Alfresco, Atliassian, EXo, and JBoss communities on several open source products for many years. He lives in Italy and collaborates with leading consulting companies for design and implementation of applications for both government and private companies dealing with information, finance, and transport. Abroad, he is known for his interventions at the Daily Telegraph in portals. He brings projects such as Wildfly, Alfresco ECM, Activiti, JGroups, Arquillian, Exo Portal, Solr, Infinispan, JBoss Portal ,Gatein, Jira, and Confluence, and manages Vige, an open source community specializing in open government and smart cities. He is one of the authors of the Gatein Cookbook, showing Gatein's portal and how to develop portlets with it, published in 2012 by Packt.

    Browse publications by this author
  • Piergiorgio Lucidi

    Piergiorgio Lucidi is an open source ECM Specialist at Sourcesense. Sourcesense is a European open source systems integrator providing consultancy, support, and services around key open source technologies. He works as Software Engineer, and he has 8 years of experience in the areas of Enterprise Content Management (ECM), system integrations, web, and mobile applications. He is an expert in integrating ECM solutions in web and portal applications. He contributes as PMC member, Project Leader, and Committer at the Apache Software Foundation for the project Apache ManifoldCF; he also contributes on ECM connectors such as CMIS, Alfresco, and ElasticSearch. He is a Project Leader and Committer of the JBoss Community, and he contributes to some of the projects of the JBoss Portal platform. He is a Speaker at conferences dedicated to ECM, Java, Spring Framework, and open source products and technologies. He is an Author, Technical Reviewer, and Affiliate Partner at Packt Publishing, for whom he wrote the technical book Alfresco 3 Web Services. As Technical Reviewer, he contributed to both Alfresco 3 Cookbook and Alfresco Share. As Affiliate Partner, he writes and publishes book reviews on his website Open4Dev (

    Browse publications by this author

Latest Reviews

(1 reviews total)
Book Title
Access this book, plus 7,500 other titles for FREE
Access now