JBoss.orgCommunity Documentation
GateIn 3.2 has two different database dependencies. One is the identity service configuration, which depends on Hibernate. The other is Java content repository (JCR) service, which depends on JDBC API, and can integrate with any existing datasource implementation.
When you change the database configuration for the first time, GateIn will automatically generate the proper schema (assuming that the database user has the appropriate permissions).
GateIn 3.2 assumes the default encoding for your database is
latin1. You may need to change this parameter for
your database in order for GateIn 3.2 to work properly.
To configure the database used by JCR you will need to edit the file:
$JBOSS_HOME/server/default/conf/gatein/configuration.properties
For Tomcat, the file is located at
$TOMCAT_HOME/gatein/conf/configuration.properties
And edit the values of driver, url, username and password with the values for your JDBC connection (please, refer to your database JDBC driver documentation).
gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver
gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name}
gatein.jcr.datasource.username=sa
gatein.jcr.datasource.password=
By default, the name of the database is "jdbcjcr_${name}" - ${name} should be a part of the database name, as it is dynamically replaced by the name of the portal container extension (for instance, gatein-sample-portal.ear defines "sample-portal" as container name and the default portal defines "portal" as container name).
In the case of HSQL the databases are created automatically. For any other database you will need to create a database named jdbcjcr_portal (and "jdbcjcr_sample-portal" if you have gatein-sample-portal.ear in $JBOSS_HOME/server/default/deploy - note that some databases don't accept '-' in the database name, so you may have to remove $JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear)
Make sure the user has rights to create tables on jdbcjcr_portal, and to update them as they will be automatically created during the first startup .
Also add your database's JDBC driver into the classpath - you can put it in $JBOSS_HOME/server/default/lib (or $TOMCAT_HOME/lib, if you are running on Tomcat)
MySQL example:
Let's configure our JCR to store data in MySQL. Let's pretend we have a user named "gateinuser" with a password "gateinpassword". We would create a database "mygateindb_portal" (remember that _portal is required), and assign our user the rights to create tables.
Then we need to add MySQL's JDBC driver to the classpath, and finally edit gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration to contain the following:
gatein.jcr.datasource.driver=com.mysql.jdbc.Driver
gatein.jcr.datasource.url=jdbc:mysql://localhost:3306/mygateindb${container.name.suffix}
gatein.jcr.datasource.username=gateinuser
gatein.jcr.datasource.password=gateinpassword
By default, users are stored in a database. To change the database in which to store users, you will need to edit the file:
$JBOSS_HOME/server/default/conf/gatein/configuration.properties
For Tomcat, the file is located at
$TOMCAT_HOME/gatein/conf/configuration.properties
You will find the same kind of configuration as in jcr-configuration.xml:
gatein.idm.datasource.driver=org.hsqldb.jdbcDriver
gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name}
gatein.idm.datasource.username=sa
gatein.idm.datasource.passwordGateIn 3.2 includes an e-mail sending service that needs to be configured before it can function properly. This service, for instance, is used to send e-mails to users who forgot their password or username.
The e-mail service can use any SMTP account configured in $JBOSS_HOME/server/default/conf/gatein/configuration.properties (or $TOMCAT_HOME/gatein/conf/configuration.properties if you are using Tomcat).
The relevant section looks like:
# 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
It is preconfigured for GMail, so that any GMail account can easily be used (simply use the full GMail address as username, and fill-in the password.
In corporate environments you will want to use your corporate SMTP gateway. When using it over SSL, like in default configuration, you may need to configure a certificate truststore, containing your SMTP server's public certificate. Depending on the key sizes, you may then also need to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your Java Runtime Environment.
GateIn 3.2 default run on HTTP mode. However, for security purpose, you can config GateIn to run on HTTPS mode. This section show you how to config GateIn with HTTPS mode.
If you haven't your own X.509 certificate, you can make a simple certificate using keytool command:
keytool -genkey -alias serverkeys -keyalg RSA -keystore server.keystore -storepass 123456 -keypass 123456 -dname "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY"
Now, your key is stored in server.keystore
You need to import your key into the Sun JDK keystore (This is required to help running gadget features)
keytool -importkeystore -srckeystore server.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts
Edit server.xml from jboss/server/<NAME>/deploy/jbossweb.sar folder. Comment lines:
<Connector protocol="HTTP/1.1" port="8080" address="${jboss.bind.address}"
connectionTimeout="20000" redirectPort="8443" />Uncomment lines and change keystoreFile and keystorePass to values of your key:
<Connector protocol="HTTP/1.1" SSLEnabled="true"
port="8443" address="${jboss.bind.address}"
scheme="https" secure="true" clientAuth="false"
keystoreFile="$JAVA_HOME/jre/lib/security/cacerts"
keystorePass="123456" sslProtocol = "TLS" />
Edit server.xml from tomcat/conf folder. Comment lines:
<Connector port="8080" protocol="HTTP/1.1" maxThreads="150" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8" emptySessionPath="true"/>
Uncomment lines and add keystoreFile and keystorePass values:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="$JAVA_HOME/jre/lib/security/cacerts" keystorePass="123456" />
Restart GateIn. If your configuration is correct, you can access to GateIn via address: https://<ServerAddress>:8443/portal
GateIn 3.2 includes a user-configurable validator that can be applied to input fields of different bundled portlets. Currently, this validator is only used to configure the validation of user name formats in the user account, user registration and group membership portlets, though the architecture allows for configurable validation to be used in different contexts if needed.
The validator can be configured via properties in the
configuration.properties
file found in the GateIn configuration directory. By default, this directory is found at
$JBOSS_HOME/server/default/conf/gatein/
if you are using JBoss Application Server or
$TOMCAT_HOME/gatein/conf/
if you are using Tomcat.
The architecture supports several configurations that can be activated and associated to specific instances of the user-configurable validator when they are created and assigned to fields in portlets. We will only concern ourselves with the currently supported use cases, which are creation/modification of a user name during registration/modification of a user and group membership assignments.
A configuration is created by adding an entry in
configuration.properties
using the
gatein.validators.
prefix followed by the name of the configuration, a period '.' and the name of the validation aspect you want
to configure. The user-configurable validator currently supports four different aspects per configuration, as
follows, where
{configuration}
refers to the configuration name:
gatein.validators.{configuration}.length.min: minimal length of the validated
field
gatein.validators.{configuration}.length.max: maximal length of the validated
field
gatein.validators.{configuration}.regexp: regular expression to which values of
the validated field must conform
gatein.validators.{configuration}.format.message: information message to display
when the value of the validated field doesn't conform to the
specified regular expression
Only two configurations are currently supported by GateIn, one, named
username, to configure validation of user names when they are created/modified and the
other, named
groupmembership,
to configure validation of user names in the context of group memberships.
For example, if you want to make sure that your users use an email address as their user name, you could use the following configuration:
Example 2.1.
# validators
gatein.validators.username.regexp=^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-za-z]{2,4}$
gatein.validators.username.format.message=Username must be a valid email address.
If you don't change the configuration of the validator, user names will be validated as follows:
Length must be between 3 and 30 characters.
Only lowercase letters, numbers, undescores (_) and period (.) can be used.
No consecutive undescores (_) or period (.) can be used.
Must start with a letter.
Must end with a letter or number.
Some components that leverage GateIn depend on user names being all lowercase. We therefore strongly recommend that you also only accept lowercase user names.
The user-configurable validator is implemented by the
org.exoplatform.webui.form.validator.UserConfigurableValidator
class. Please refer to its documentation for more details.
To use a specific validator configuration to validate a given field value, add the validator to the field as
follows, where
configurationName
is a
String
representing the name of the configuration to use:
addValidator(UserConfigurableValidator.class, configurationName))
The validator instance can then be configured by adding the relevant information in configuration.properties, for example:
# validators
gatein.validators.configurationName.length.min=5
gatein.validators.configurationName.length.max=10
gatein.validators.configurationName.regexp=^u\d{4,9}$
gatein.validators.configurationName.format.message=Username must start with ''u'' and be followed by 4 to 9 digits.
Alternatively, a resource key can also be passed to the
addValidator
method to specify which localized message should be used in case a validation error occurs, for example as
follows:
configurationName
addValidator(UserConfigurableValidator.class, UserConfigurableValidator.GROUPMEMBERSHIP,
UserConfigurableValidator.GROUP_MEMBERSHIP_LOCALIZATION_KEY);