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.
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.
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:
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 http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u31-download-1501634.html.
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.
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.
Once you have chosen the right bundle for yourself, you are ready to download it from http://www.jboss.org/gatein/downloads .
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:
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.
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 https://github.com/gatein/gatein-portal.
Java Development Kit (JDK) 1.6
Subversion client (SVN)
Apache Maven 3.x
Let's check your environment for the see following required tools:
You can test and install JDK 1.6 following the Getting ready section of the Installing GateIn from a binary package recipe.
To test if the SVN client is installed in your machine run the following command line:
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 http://subversion.apache.org/
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 http://subversion.apache.org/packages.html.
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:
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"
Download the Apache Maven binary at http://maven.apache.org/download.html .
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
M2variables 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
Finally, check if you have installed the latest stable release of Apache Maven before continuing the recipe.
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.
Check out the code on your machine by executing the following comman line:
svn checkout http://anonsvn.jboss.org/repos/gatein/portal/tags/3.2.0-GA/ gatein-portal-3.2.0
Once you have finished the download, you will find a new subfolder
gatein-portal-3.2.0in the folder where you have executed the command that contains all the source code of the project.
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)
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.32folder, you have to execute the following command line from the root folder of the project that contains the main
mvn clean install -DskipTests -Ppkg-tomcat -Dexo.projects.directory.dependencies=/Applications/Apache Tomcat -Dexo.projects.app.tomcat.version=apache-tomcat-6.0.32
Upon completion, you should see the following output:
[INFO] ------------------------------------------- [INFO] BUILD SUCCESS [INFO] -------------------------------------------
The binary artifacts will be available on your machine inside the
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.
Each phase is responsible for specific goals that need to be processed before the next phase.
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.
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.
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:
Locate the following properties inside the configuration file:
The default database settings of the JCR component of GateIn are based on these standard JDBC parameters:
The above parameters will configure your HSQL database in a folder in your file system. As you can see, the parameter named
gatein.db.data.dir, 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.password=<ORACLE USER PASSWORD>
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.
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:
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.
Configure another database schema dedicated to the identity manager.
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.password=<ORACLE USER PASSWORD>
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.
The database connection used in GateIn is a standard JDBC connection that requires the usual parameters for configuration:
JDBC driver class
The username and password are related to a specific users credentials that GateIn must use to access and manipulate contents in the database.
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 (
gatein.jcr.index.data.dir) and a high-performance storage location for contents, setting a different value for the
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 http://lucene.apache.org/.
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.password=<MYSQL USER PASSWORD>
For the identity manager you should have the following:
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.
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.
Carry out the following steps in order to configure GateIn to send e-mails:
Locate in the e-mail section of the configuration file the following snippet:
# Email gatein.email.smtp.username= gatein.email.smtp.password= gatein.email.smtp.host=smtp.gmail.com gatein.email.smtp.port=465 gatein.email.smtp.starttls.enable=true gatein.email.smtp.auth=true gatein.email.smtp.socketFactory.port=465 gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
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.
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.
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.
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
gatein.sh, for Windows
gatein.bat, provided in the binary folder
For JBoss AS 6 you can use the standard
run.shscript available in this folder
JBoss AS 7 requires using the script
Supposing that we are using Linux as the operating system, we would follow these steps:
To start GateIn using Tomcat use the following command line from the current
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
In order to stop the GateIn instance use the following command line:
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.
We will take a look at how to start GateIn with different versions of JBoss application servers.
nohup ./run.sh &
tail –f nohup.out
To stop the instance you can use the following command line:
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.
Download Eclipse IDE for Java EE Developers at http://www.eclipse.org/downloads/ .
Install Eclipse on your machine, launching the executable and following the installation instructions.
Launch Eclipse and create a new workspace dedicated to GateIn.
Click on Help | Eclipse Marketplace.
Search jboss tools and click on the Go button.
Locate the JBoss Tools version required for your specific Eclipse version and click on the Install button.
In the Install Details window, click on the Next button.
In the Review Licenses window, read and accept the terms of the license agreements and click on the Finish button.
After the restart, you should see the overview of what you can do with JBoss tools with a similar tab in your Eclipse environment:
Right-click on the Package Explorer tab and select Import.
Insert as Root Directory the GateIn source root folder that you have created in the previous recipe.
Click on the Next button and then click on Finish.
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.
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.
The following are all the example modules available in the GateIn source code:
GateIn Portal Sample
GateIn Portal Sample Extension
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