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.
In this recipe, we will see which are the required packages you need to download before starting a GateIn instance.
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 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 .
After downloading the GateIn package, you can extract it in your preferred directory in your file system.
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:
binclientcommondocslibserver
The Tomcat 6.x bundle is based on a different structure:
binconfgateinliblogstempwebappswork
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.
Note
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.
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:
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:
svn --versionIf 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:
mvn --versionAfter 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:
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 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
PATHandM2variables 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.0Once 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)
The name of the folder related to the application server distribution to use for building
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 mainpom.xmlfile:mvn clean install -DskipTests -Ppkg-tomcat -Dexo.projects.directory.dependencies=/Applications/Apache Tomcat -Dexo.projects.app.tomcat.version=apache-tomcat-6.0.32Upon completion, you should see the following output:
[INFO] ------------------------------------------- [INFO] BUILD SUCCESS [INFO] -------------------------------------------
The binary artifacts will be available on your machine inside the
/gatein-portal-3.2.0/packaging/tomcat/pkg/tc6/target/tomcat6folder.
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:
Validate
Compile
Test
Package
Integration-test
Verify
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.
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.
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:
<TOMCAT6_HOME>/gatein/conf/configuration.properties
If you are using JBoss AS 6 you will find it at the following location:
<JBOSS6_HOME>/server/default/conf/gatein/configuration.properties
If you want to use JBoss AS 7, you have to edit the configuration file here:
<JBOSS7_HOME>/standalone/configuration/gatein/configuration.properties
Carry out the following steps to configure the content storage:
Locate the following properties inside the configuration file:
gatein.jcr.datasource.drivergatein.jcr.datasource.urlgatein.jcr.datasource.usernamegatein.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.jdbcDrivergatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name}gatein.jcr.datasource.username=sagatein.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
gatein.db.data.dir, used for the value of the parametergatein.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.OracleDrivergatein.jcr.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInJcrgatein.jcr.datasource.username=<ORACLE USERNAME>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.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:
<TOMCAT6_HOME>/libFor JBoss 6 AS you can use this one:
<JBOSS6_HOME>/server/default/libFor JBoss 7 AS the following directory is available here:
<JBOSS7_HOME>/standalone/libNow 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:
gatein.data.dir=../gatein/datagatein.jcr.data.dir=${gatein.data.dir}/jcrgatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/valuesgatein.jcr.index.data.dir=${gatein.jcr.data.dir}/lucene
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.
The built-in properties' values for the database JDBC connection of the identity management are the following:
gatein.idm.datasource.driver=org.hsqldb.jdbcDrivergatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name}gatein.idm.datasource.username=sagatein.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.OracleDrivergatein.idm.datasource.url=jdbc:oracle:thin:@<HOST>:<PORT>:gateInIdmgatein.idm.datasource.username=<ORACLE USERNAME>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.
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
JDBC URL
Username
Password
Note
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.
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 gatein.jcr.storage.data.dir property.
Note
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.driver=com.mysql.jdbc.Driver
gatein.jcr.datasource.url=jdbc:mysql://<HOST>:<PORT>/gateInJcr
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.driver=com.mysql.jdbc.Driver
gatein.idm.datasource.url=jdbc:mysql://<HOST>:<PORT>/gateInIdm
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.
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.
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.
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.
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.
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
gatein.sh, for Windowsgatein.bat, provided in the binary folder<TOMCAT_HOME>/binFor JBoss AS 6 you can use the standard
run.shscript available in this folder<JBOSS6_HOME>/binJBoss AS 7 requires using the script
standalone.shstored here<JBOSS7_HOME/bin>
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
binfolder:./gatein.sh startOnce the command above executes, you can take a look at the log file with the following command:
tail –f ../logs/catalina.outNow you can start using the portal, pointing your browser at
http://localhost:8080/portal.If the first deployment of GateIn finishes without errors we expect to see in the browser the following homepage of the default portal:
In order to stop the GateIn instance use the following command line:
./gatein.sh stop
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.
We will take a look at how to start GateIn with different versions of JBoss application servers.
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.
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.
Set up your development environment following these steps:
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 Confirm Selected Features window, select all the items and click on the Next 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.
Wait for the installation process of JBoss tools to complete. Once the installation is finished, restart Eclipse.
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.
Browse the Maven category and select Existing Maven Projects and press the Next button.
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.
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
