eXo Platform 3.5

## Chapter 1. Configuration

This chapter provides you with the basic knowledge of configurations in GateIn 3.2 via 2 main topics:

- Database Configuration

  Instructions on how to configure the database for the JCR and the default identity store.

- Email Service Configuration

  Instructions on how to configure the email sending services.

- Configuration of Custom Data Validators

  Instructions on how to configure custom data validators.

After reading this chapter, you can extend more functions for your product and customize to your desires.

## 1.1. Database Configuration

GateIn 3.2 has two different database dependencies. One is the identity service configuration, which depends on Hibernate. The other is the 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 so that GateIn 3.2 works properly.

The database configuration in GateIn can be divided into 2 main topics:

- Configure the database for JCR

- Configure the database for the default identity store

Configure the database for JCR

To configure the database used by JCR, edit the file: `$PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties`.

For Tomcat, the file is located at `$PLATFORM_TOMCAT_HOME/gatein/conf/configuration.properties`.

Next, edit the values of driver, url, username and password with the values for your JDBC connection. To learn more, 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 example, `gatein-sample-portal.ear` defines "sample-portal" as the container name and the default portal defines "portal" as the container name.

In case of HSQL, the databases are created automatically. For any other databases, you need to create a database named "jdbcjcr_portal" (and "jdbcjcr_sample-portal" if you have `gatein-sample-portal.ear` in `$PLATFORM_JBOSS_HOME/server/default/deploy`). Note that some databases do not accept '-' in the database name, so you may have to remove `$PLATFORM_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 `$PLATFORM_JBOSS_HOME/server/default/lib` (or `$PLATFORM_TOMCAT_HOME/lib`, if you are running on Tomcat).

MySQL example:

Configure the JCR to store data in MySQL and assume that you created a user named "gateinuser" with a password "gateinpassword". Next, create a database mygateindb_portal (remember that portal is required), and assign the rights to create tables to the users.

Add the MySQL's JDBC driver to the classpath, and finally edit `gatein.ear/portal.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

Configure the database for the default identity store

By default, users are stored in a database. To change the database where users are stored, you need to edit the file:

For Jboss: `$PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties`

For Tomcat: `$PLATFORM_TOMCAT_HOME/gatein/conf/configuration.properties`

You will find the same type 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.password

`See also`

- Email Service Configuration

## 1.2. Email Service Configuration

GateIn 3.2 includes an email sending service that needs to be configured before it can function properly. This service, for instance, is used to send emails to users who forgot their password or username.

Configure the outgoing email account

The email service can use any SMTP account configured in `$PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties` (or `$PLATFORM_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 with username and password.

In corporate environments, if you want to use your corporate SMTP gateway over SSL, like in the default configuration, 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.

`See also`

- Database Configuration

## 1.3. Configuration of custom data validators

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 username formats in the user account and user registration 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 in the GateIn configuration directory. By default, this directory is found at `$PLF-3.5-JBOSS_HOME/server/default/conf/gatein/` if you are using JBoss Application Server or `$PLF-3.5-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 case, which is the user name validation during account creation.

### 1.3.1. Validator configuration

A configuration is created by adding an entry to the `configuration.properties` file 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`: The minimum length of the validated field.

- `gatein.validators.{configuration}.length.max`: The maximum length of the validated field.

- `gatein.validators.{configuration}.regexp`: The regular expression to which values of the validated field must conform.

- `gatein.validators.{configuration}.format.message`: The information message to display when the value does not conform to the specified regular expression.

### 1.3.2. Configuration of Username Validator

By default, the username will be validated as follows:

- The length must be between 3 and 30 characters.

- Only lowercase letters, numbers, underscores (_) and period (.) can be used.

- No consecutive underscores (_) or period (.) can be used.

- Must start with a lowercase letter.

- Must end with a letter or number.

### Note

Some components that leverage GateIn depend on usernames being all lowercase. Therefore, you are strongly recommended to use a lowercase username only.

If you want to make sure that your users use an email address as their username, you could use the following configuration:

    # 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

When the username field does not conform to this rule, the account is not created and there will be a warning message.

        The field "User Name" must match the format "Username must be a valid email address".

In case you do not define `gatein.validators.username.format.message`, the value of `gatein.validators.username.regexp` will be used in the warning message and you will see

        The field "User Name" must match the format "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-za-z]{2,4}$".

when the username does not match the validation pattern.

### 1.3.3. Developer information

The user-configurable validator is implemented by the `org.exoplatform.webui.form.validator.UserConfigurableValidator` class.

To use a specific validator configuration to validate a given field value, add the validator to the field where `configurationName` is a `String` representing the name of the configuration used:

    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=This value 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, `configurationName` as follows:

    addValidator(UserConfigurableValidator.class, configurationName, localizationKey);

where `localizationKey` is defined in a resource bundle.

Copyright © 2009-2012. All rights reserved. eXo Platform SAS