GateIn Reference Guide

GateIn 3.0 has two different database dependencies. One is the identity service configuration, which depends on the Hibernate. The other database dependency is Java content repository (JCR) service, which depends on the native JDBC API and it 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.0 assumes the default encoding for your database is latin1 . You will need to change this parameter for your database in order 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=

In that case, the name of the database is "jdbcjcr_${name}", ${name} should be 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 kept gatein-sample-portal.ear in $JBOSS_HOME/server/default/deploy. Note that some database wont accept '-' in a database name and you will have to delete $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 during the first startup they will be automatically created.

Also add the JDBC driver into the classpath, for instance 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 him the rights to create tables.

Then we need to add the MySQL JDBC connector in the classpath and finally edit gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration with:

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 database. To change the database 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 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

GateIn 3.0 has a service to send e-mails that requires to be configured before it can work properly. This service is used to send e-mails to users who forgot their username or password for instance.

The e-mail service can use any SMTP account that needs to be 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 be easily used (Just use a full gmail address as username and fill-in the password.

The default portal will be accessed if the user doesn't specify another portal. For example: http://hostname:port/portal/. The default portal also be used at startup to determine if the database is empty.

The example configuration file below is found at: "02portal.war:/WEB-INF/conf/portal/portal-configuration.xml".

<component>

    <key>org.exoplatform.portal.config.UserPortalConfigService</key>

    <type>org.exoplatform.portal.config.UserPortalConfigService</type>

    <component-plugins>           

     <component-plugin>

       <name>new.portal.config.user.listener</name>

       <set-method>initListener</set-method>

       <type>org.exoplatform.portal.config.NewPortalConfigListener</type>

       <description>this listener init the portal configuration</description>

       <init-params>

         <value-param>

           <name>default.portal</name>

           <description>The default portal for checking db is empty or not</description>

           <value>classic</value>

         </value-param> 

         ..........

       </init-params>

     </component-plugin>

    </component-plugins> 

  </component>

In this example the classic portal has been set as the default. Note that the definition should be as a initial parameter of the NewPortalConfigListener component-plugin.

The main configuration file is idm-configuration:

<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
               xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
 
   <component>
        <key>org.exoplatform.services.organization.idm.PicketLinkIDMService</key>
      <type>org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl</type>
      <init-params>
         <value-param>
            <name>config</name>
            <value>war:/conf/organization/idm-config.xml</value>
         </value-param>
         <value-param>
            <name>portalRealm</name>
            <value>realm${container.name.suffix}</value>
         </value-param>
       </init-params>
   </component>
 
 
   <component>
      <key>org.exoplatform.services.organization.OrganizationService</key>
      <type>org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl</type>
      <init-params>
      <object-param>
        <name>configuration</name>
        <object type="org.exoplatform.services.organization.idm.Config">
          <field name="useParentIdAsGroupType">
            <boolean>true</boolean>
          </field>
 
          <field name="forceMembershipOfMappedTypes">
            <boolean>true</boolean>
          </field>
 
          <field name="pathSeparator">
            <string>.</string>
          </field>
 
          <field name="rootGroupName">
            <string>GTN_ROOT_GROUP</string>
          </field>
 
          <field name="groupTypeMappings">
            <map type="java.util.HashMap">
              <entry>
                <key><string>/</string></key>
                <value><string>root_type</string></value>
              </entry>
 
              <!-- Sample mapping -->
              <!--
              <entry>
                <key><string>/platform/*</string></key>
                <value><string>platform_type</string></value>
              </entry>
              <entry>
                <key><string>/organization/*</string></key>
                <value><string>organization_type</string></value>
              </entry>
              -->
 
            </map>
          </field>
 
          <field name="associationMembershipType">
            <string>member</string>
          </field>
 
          <field name="ignoreMappedMembershipType">
            <boolean>false</boolean>
          </field>
        </object>
      </object-param>
    </init-params>
 
 
   </component>
 
</configuration>

The org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl service has following options: config (value-param) PicketLink IDM configuration file hibernate.properties (properties-param) A list of hibernate properties used to create SessionFactory that will be injected to JBoss Identity IDM configuration registry. hibernate.annotations A list of annotated classes that will be added to hibernate configuration. hibernate.mappings A list of xml files that will be added to hibernate configuration as mapping files. jndiName (value-param) If the 'config' parameter is not provided this parameter will be used to perform JNDI lookup for IdentitySessionFactory portalRealm (value-param) The name of a realm that should be used to obtain proper IdentitySession. The default is 'PortalRealm'.

The org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl key is a main entrypoint implementing org.exoplatform.services.organization.OrganizationService and is dependant on org.exoplatform.services.organization.idm.PicketLinkIDMService org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl service has following options defined as fields of object-param type org.exoplatform.services.organization.idm.Config: defaultGroupType The name of the PicketLink IDM GroupType that will be used to store groups. The default is 'GTN_GROUP_TYPE'. rootGroupName The name of the PicketLink IDM Group that will be used as a root parent. The default is 'GTN_ROOT_GROUP' passwordAsAttribute This parameter specifies if a password should be stored using PicketLink IDM Credential object or as a plain attribute. The default is false. useParentIdAsGroupType This parameter stores the parent ID path as a group type in PicketLink IDM for any IDs not mapped with a specific type in 'groupTypeMappings'. If this option is set to false and no mappings are provided under 'groupTypeMappings' only one group with a given name can exist in the GateIn 3.0 group tree. pathSeparator When 'userParentIdAsGroupType is set to true, this value will be used to replace all "/" characters in IDs. The "/" character is not allowed to be used in group type name in PicketLink IDM. associationMembershipType If this option is used then each Membership created with MembrshipType that is equal to the value specified here will be stored in PicketLink IDM as simple Group-User association. groupTypeMappings This parameter maps groups added with the GateIn 3.0 API as a child of a given group ID and stores them with a given group type name in PicketLink IDM. If the parent ID ends with "/*" then all child groups will have the mapped group type. Otherwise only direct (first level) children will use this type. This can be leveraged by LDAP if LDAP DN is configured in PicketLink IDM to only store a specific group type. This will then store the given branch in the GateIn 3.0 group tree while all other groups will remain in the database. forceMembershipOfMappedTypes Groups stored in PicketLink IDM with a type mapped in 'groupTypeMappings' will automatically be a member under the mapped parent. Group relationships linked by PicketLink IDM group association will not be necessary. This parameter can be set to false if all groups are added via GateIn 3.0 APIs. This may be useful with LDAP configuration as, when set to true, it will make every entry added to LDAP appear in GateIn 3.0. This is not true for entries added via the GateIn 3.0 management UI, however. ignoreMappedMembershipType If "associationMembershipType" option is used and this option is set to true then Membership with MembershipType configured to be stored as PicketLink IDM association will not be stored as PicketLink IDM Role. Additionally JBossIDMOrganizationServiceImpl uses those defaults to perform identity management operations GateIn 3.0 User interface properties fields are persisted in JBoss Identity IDM using those attributes names: firstName, lastName, email, createdDate, lastLoginTime, organizationId, password (if password is configured to be stored as attribute) GateIn 3.0 Group interface properties fields are persisted in JBoss Identity IDM using those attributes names: label, description GateIn 3.0 MembershipType interface properties fields are persisted in JBoss Identity IDM using those RoleType properties: description, owner, create_date, modified_date

A sample PicketLink IDM configuration file is shown below. To understand all the options present in it please refer to the PicketLink IDM Reference Guide

<jboss-identity xmlns="urn:jboss:identity:idm:config:v1_0_beta"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_alpha identity-config.xsd">
    <realms>
        <realm>
            <id>PortalRealm</id>
            <repository-id-ref>PortalRepository</repository-id-ref>
            <identity-type-mappings>
                <user-mapping>USER</user-mapping>
            </identity-type-mappings>
        </realm>
    </realms>
    <repositories>
        <repository>
            <id>PortalRepository</id>
            <class>org.jboss.identity.idm.impl.repository.WrapperIdentityStoreRepository</class>
            <external-config/>
            <default-identity-store-id>HibernateStore</default-identity-store-id>
            <default-attribute-store-id>HibernateStore</default-attribute-store-id>
        </repository>
    </repositories>
    <stores>
        <attribute-stores/>
        <identity-stores>
            <identity-store>
                <id>HibernateStore</id>
                <class>org.jboss.identity.idm.impl.store.hibernate.HibernateIdentityStoreImpl</class>
                <external-config/>
                <supported-relationship-types>
                    <relationship-type>JBOSS_IDENTITY_MEMBERSHIP</relationship-type>
                    <relationship-type>JBOSS_IDENTITY_ROLE</relationship-type>
                </supported-relationship-types>
                <supported-identity-object-types>
                    <identity-object-type>
                        <name>USER</name>
                        <relationships/>
                        <credentials>
                            <credential-type>PASSWORD</credential-type>
                        </credentials>
                        <attributes/>
                        <options/>
                    </identity-object-type>
                </supported-identity-object-types>
                <options>
                    <option>
                        <name>hibernateSessionFactoryRegistryName</name>
                        <value>hibernateSessionFactory</value>
                    </option>
                    <option>
                        <name>allowNotDefinedIdentityObjectTypes</name>
                        <value>true</value>
                    </option>
                    <option>
                        <name>populateRelationshipTypes</name>
                        <value>true</value>
                    </option>
                    <option>
                        <name>populateIdentityObjectTypes</name>
                        <value>true</value>
                    </option>
                    <option>
                        <name>allowNotDefinedAttributes</name>
                        <value>true</value>
                    </option>
                    <option>
                        <name>isRealmAware</name>
                        <value>true</value>
                    </option>
                </options>
            </identity-store>
        </identity-stores>
    </stores>
</jboss-identity>

Three types of navigation are available to portal users:

These navigations are configured with standard XML syntax in the file; "02portal.war:/WEB-INF/conf/portal/portal-configuration.xml".

<component>

  <key>org.exoplatform.portal.config.UserPortalConfigService</key>

  <type>org.exoplatform.portal.config.UserPortalConfigService</type>

  <component-plugins>           

   <component-plugin>

     <name>new.portal.config.user.listener</name>

     <set-method>initListener</set-method>

     <type>org.exoplatform.portal.config.NewPortalConfigListener</type>

     <description>this listener init the portal configuration</description>

     <init-params>

       <value-param>

         <name>default.portal</name>

         <description>The default portal for checking db is empty or not</description>

         <value>classic</value>

       </value-param> 

       <object-param>

         <name>portal.configuration</name>

         <description>description</description>

         <object type="org.exoplatform.portal.config.NewPortalConfig">

           <field  name="predefinedOwner">

             <collection type="java.util.HashSet">                

               <value><string>classic</string></value>

               <value><string>webos</string></value>

             </collection>

           </field>

           <field  name="ownerType"><string>portal</string></field>

           <field  name="templateLocation"><string>war:/conf/portal</string></field> 

         </object>

       </object-param> 

       <object-param>

         <name>group.configuration</name>

         <description>description</description>

         <object type="org.exoplatform.portal.config.NewPortalConfig">

           <field  name="predefinedOwner">

             <collection type="java.util.HashSet">            

              <value><string>platform/administrators</string></value>    

              <value><string>platform/users</string></value>

              <value><string>platform/guests</string></value>

              <value><string>organization/management/executive-board</string></value>               

             </collection>

           </field>

           <field  name="ownerType"><string>group</string></field>

           <field  name="templateLocation"><string>war:/conf/portal</string></field> 

         </object>

       </object-param>       

       <object-param>

         <name>user.configuration</name>

         <description>description</description>

         <object type="org.exoplatform.portal.config.NewPortalConfig">

           <field  name="predefinedOwner">

             <collection type="java.util.HashSet">                

               <value><string>root</string></value>

               <value><string>john</string></value>

               <value><string>mary</string></value>

               <value><string>demo</string></value>

             </collection>

           </field>

           <field  name="ownerType"><string>user</string></field>

           <field  name="templateLocation"><string>war:/conf/portal</string></field> 

         </object>

       </object-param>

     </init-params>

   </component-plugin>

</component-plugins>

This XML file defines, for the three navigations, which sets of portals, groups or users will have XML files inside the apprpriate war. Those files will be used to create an initial navigation the first time the portal is launched. That information will then be stored in the JCR and is then modifiable from the portal UI.

The portal navigation incorporates the pages that can be accessed when the user is not logged in (if the applicable permissions allow public access). For example; several portal navigations are used when a company has multiple trademarks and each trade has its own website.

The classic portal is configured by four XML files in the 02portal.war:/WEB-INF/conf/portal/portal/classic directory:

Group navigations are dynamically added to the user navigation at login. This allows users to see all the pages assigned to any groups they belong to in the menu.

The group navigation menu is configured by three XML files (navigation.xml, pages.xml and portlet-preferences.xml). The syntax used in these files is the same as those covered in Section 2.5.2, “Portal Navigation”.

They are located in the portal/WEB-INF/conf/portal/group/group-name-path/ directory (For example; portal/WEB-INF/conf/portal/group/platform/administrators/).

The user navigation is the set of nodes and pages that are owned by a user. They are part of the user dashboard.

Three files configure the user navigation (navigation.xml, pages.xml and portlet-preferences.xml). They are located in the directory "portal/WEB-INF/conf/portal/users/{userName}".

This directory also contains a gadgets.xml file (which was formerly called widgets.xml). This file defines the gadgets located in the user workspace.

The user workspace is located at the left hand side of the page and access is restricted to some privileged users, see Section 2.7, “Predefined User Configuration”

<?xml version="1.0" encoding="ISO-8859-1"?>

<widgets>

  <owner-type>user</owner-type>

  <owner-id>root</owner-id>

 

  <container id="Information">

    <name>Information</name>

    <description>Information's Description</description>

    <application>

      <instance-id>user#root:/GateInWidgetWeb/WelcomeWidget/WelcomeWidget1</instance-id>

      <application-type>GateInWidget</application-type>

    </application>

      

    <application>

      <instance-id>user#root:/GateInWidgetWeb/StickerWidget/StickerWidget</instance-id>

      <application-type>GateInWidget</application-type> 

    </application>

    

    <application>

      <instance-id>user#root:/GateInWidgetWeb/InfoWidget/InfoWidget1</instance-id>

      <application-type>GateInWidget</application-type>

    </application>

  </container>

  

  <container id="Calendar">

    <name>Calendar</name>

    <description>Calendar's Description</description>

    <application>

      <instance-id>user#root:/GateInWidgetWeb/CalendarWidget/CalendarWidget</instance-id>

      <application-type>GateInWidget</application-type> 

    </application>

  </container> 

 

</widgets>

Token service is used in authentication.

The token system prevents user account information being sent in clear text mode for inbound requests. This increases authentication security.

Token service allows adminitrators to create, delete, retrieve and clean tokens as required. The service also defines the validity period of any given token. The token becomes invalid once this period has expired, . The life-time definition must be configured.

All token services used in GateIn 3.0's authentication must be a subclass of an abstract class AbstractTokenService. The following example shows how the token-service manipulates its tokens.

        public Token getToken(String id) throws PathNotFoundException, RepositoryException;

        public Token deleteToken(String id) throws PathNotFoundException, RepositoryException;

        public String[] getAllTokens();

        public long getNumberTokens() throws Exception;

        public String createToken(Credentials credentials) throws IllegalArgumentException,NullPointerException;

        public Credentials validateToken(String tokenKey, boolean remove) throws NullPointerException;

Token services configuration includes specifying the validity period time of token in the configuration file. The token service is configured as a portal component.

In the example below, CookieTokenService is a subclass of AbstractTokenService so it has a property which specifies the validity period of the token.

The token service will initiate this validity property by looking for an init-param named "service.configuration".

This property must have three values.

<component>
  <key>org.exoplatform.web.security.security.CookieTokenService</key>
  <type>org.exoplatform.web.security.security.CookieTokenService</type>
  <init-params>
  	<values-param>
      <name>tokenTimeout</name>          
      <value>jcr-token</value>
      <value>7</value>
      <value>DAY</value>
    </values-param>    	
  </init-params>
</component>

	Service name
	Amount of time
	Unit of time

In this case, the service's name is "jcr-token" and the token's expiration time is a week.

GateIn 3.0 supports four timing units:

To specify the initial Organization configuration, the content of 02portal.war:/WEB-INF/conf/organization/organization-configuration.xml should be edited. This file uses the portal XML configuration schema. It lists several configuration plugins.

The plugin of type org.exoplatform.services.organization.OrganizationDatabaseInitializer specifies the list of users, groups and membership types to be created.

The initialization parameter "checkDatabaseAlgorithm" determines how the creation is triggered.

The value "entry" means that each user, group and membership listed in the configuration file is checked each time GateIn 3.0 is started. If the entry doesn't exist, it is created. The value "empty" sets the configuration file to be processed only if the database is empty.

The predefined membership types are specified in the "membershipType" field of the "OrganizationConfig" plugin parameter.

<field name="membershipType">

  <collection type="java.util.ArrayList">

    <value>

      <object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">

        <field name="type">

          <string>member</string>

        </field>

        <field name="description">

          <string>member membership type</string>

        </field>

      </object>

    </value>

    <value>

      <object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">

        <field name="type">

          <string>owner</string>

        </field>

        <field name="description">

          <string>owner membership type</string>

        </field>

      </object>

     </value>

     <value>

       <object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">

         <field name="type">

           <string>validator</string>

         </field>

         <field name="description">

           <string>validator membership type</string>

         </field>

       </object>

     </value>

   </collection>

</field>

The predefined groups are specified in the "group" field of the "OrganizationConfig" plugin parameter.

<field name="group">

  <collection type="java.util.ArrayList">

    <value>

      <object type="org.exoplatform.services.organization.OrganizationConfig$Group">

        <field name="name">

          <string>portal</string>

        </field>

        <field name="parentId">

          <string></string>

        </field>

        <field name="type">

          <string>hierachy</string>

        </field>

        <field name="description">

          <string>the /portal group</string>

        </field>

      </object>

    </value>

    <value>

      <object type="org.exoplatform.services.organization.OrganizationConfig$Group">

        <field name="name">

          <string>community</string>

        </field>

        <field name="parentId">

          <string>/portal</string>

        </field>

        <field name="type">

          <string>hierachy</string>

        </field>

        <field name="description">

          <string>the /portal/community group</string>

        </field>

      </object>

    </value>

    ...

  </collection>

</field>

The predefined users are specified in the "membershipType" field of the "OrganizationConfig" plugin parameter.

<field name="user">

  <collection type="java.util.ArrayList">

    <value>

      <object type="org.exoplatform.services.organization.OrganizationConfig$User">

        <field name="userName"><string>root</string></field>

        <field name="password"><string>exo</string></field>

        <field name="firstName"><string>root</string></field>

        <field name="lastName"><string>root</string></field>

        <field name="email"><string>exoadmin@localhost</string></field>

        <field name="groups"><string>member:/admin,member:/user,owner:/portal/admin</string></field>

      </object>

    </value>

    <value>

      <object type="org.exoplatform.services.organization.OrganizationConfig$User">

        <field name="userName"><string>exo</string></field>

        <field name="password"><string>exo</string></field>

        <field name="firstName"><string>site</string></field>

        <field name="lastName"><string>site</string></field>

        <field name="email"><string>exo@localhost</string></field>

        <field name="groups"><string>member:/user</string></field>

      </object>

    </value>

    ...

  </collection>

</field>

The plugin of type org.exoplatform.services.organization.impl.NewUserEventListener specifies which groups should join all newly created users. It notably specifies the groups and memberships to be used. It also specifies a list of users that should be excepted.

<component-plugin>

  <name>new.user.event.listener</name>

  <set-method>addListenerPlugin</set-method>

  <type>org.exoplatform.services.organization.impl.NewUserEventListener</type>

  <description>this listener assign group and membership to a new created user</description>

  <init-params>

    <object-param>

      <name>configuration</name>

      <description>description</description>

      <object type="org.exoplatform.services.organization.impl.NewUserConfig">

        <field  name="group">

          <collection type="java.util.ArrayList">

            <value>

              <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup">

                <field name="groupId"><string>/user</string></field>

                <field name="membership"><string>member</string></field>

              </object>

            </value>               

          </collection>

        </field>

        <field  name="ignoredUser">

          <collection type="java.util.HashSet">

            <value><string>exo</string></value>

            <value><string>root</string></value>

            <value><string>company</string></value>

            <value><string>community</string></value>

          </collection>

        </field>

      </object>

    </object-param>

  </init-params>

</component-plugin>

The permission configuration for the portal is defined in the file 02portal.war:/WEB-INF/conf/portal/portal-configuration.xml . The component UserACL is described there along with other portal component configurations.

It defines 5 permissions types:

<component>

  <key>org.exoplatform.portal.config.UserACL</key>

  <type>org.exoplatform.portal.config.UserACL</type>   

  <init-params>      

    <value-param>

      <name>super.user</name>

      <description>administrator</description>

      <value>root</value>     

    </value-param>

      

    <value-param>

      <name>portal.creator.groups</name>

      <description>groups with membership type have permission to manage portal</description>

      <value>*:/platform/administrators,*:/organization/management/executive-board</value>     

    </value-param>

      

    <value-param>

      <name>navigation.creator.membership.type</name>

      <description>specific membership type have full permission with group navigation</description>

      <value>manager</value>     

    </value-param>

    <value-param>

      <name>guests.group</name>

      <description>guests group</description>

      <value>/platform/guests</value>     

    </value-param>     

    <value-param>

      <name>access.control.workspace</name>

      <description>groups with memberships that have the right to access the User Control Workspace</description>

      <value>*:/platform/administrators,*:/organization/management/executive-board</value>     

    </value-param>           

  </init-params>   

</component>

<external-component-plugins>

    <target-component>org.exoplatform.portal.config.UserACL</target-component>

    <component-plugin>

      <name>addPortalACLPlugin</name>

      <set-method>addPortalACLPlugin</set-method>

      <type>org.exoplatform.portal.config.PortalACLPlugin</type>

      <description>setting some permission for portal</description>

      <init-params>     

        <values-param>

          <name>access.control.workspace.roles</name>

          <value>*:/platform/administrators</value>

          <value>*:/organization/management/executive-board</value>       

        </values-param>

        <values-param>

          <name>portal.creation.roles</name>

          <value>*:/platform/administrators</value>

          <value>*:/organization/management/executive-board</value>      

        </values-param>

      </init-params>

    </component-plugin>

  </external-component-plugins>

Data-injector is a utility to initialize enterprise data for GateIn 3.0. It is packed as a .jar.

OrganizationInitializer is the service that allows creating a large organization with many groups and users. It also creates portal navigation and page(s) for each group and each user.

Service configuration file

<configuration>
  <component>
  <key>org.exoplatform.portal.initializer.organization.OrganizationInitializer</key>
  <type>org.exoplatform.portal.initializer.organization.OrganizationInitializer</type>
    <init-params>
      <value-param>
        <name>auto.create.group.page.navigation</name>
        <description>true or false</description>
        <value>true</value>
      </value-param>
       
      <value-param>
        <name>auto.create.user.page.navigation</name>
        <description>number of pages per user</description>
        <value>10</value>
      </value-param>
      
      <object-param>
        <name>organization</name>
        <description>description</description>
        <object type="org.exoplatform.portal.initializer.organization.OrganizationConfig">
          <field name="groups">
            <collection type="java.util.ArrayList">
              <value>
                <object type="org.exoplatform.portal.initializer.organization.OrganizationConfig$GroupsConfig">
                  <field name="group">
                    <object type="org.exoplatform.services.organization.OrganizationConfig$Group">
                      <field name="name"><string>province</string></field>
                      <field name="parentId"><string>/africa/tanzania</string></field>
                      <field name="description"><string>Tanzania's province</string></field>
                      <field name="label"><string>Province</string></field>
                    </object>                
                  </field> 
                  <field name="from"><string>1</string></field>
                  <field name="to"><string>10</string></field>
                </object>
              </value>
            </collection>
          </field>
          <field name="users">
            <collection type="java.util.ArrayList"> 
              <value>
                <object type="org.exoplatform.portal.initializer.organization.OrganizationConfig$UsersConfig">
                  <field name="user">
                    <object type="org.exoplatform.services.organization.OrganizationConfig$User">
                      <field name="userName"><string>user</string></field>
                      <field name="password"><string>GateInPlatform</string></field>
                      <field name="firstName"><string>First-Name</string></field>
                      <field name="lastName"><string>Last-Name</string></field>
                      <field name="email"><string>exo@localhost</string></field>
                      <field name="groups"><string>member:/africa</string></field>
                    </object>
                  </field>
                  <field name="from"><string>0</string></field>
                  <field name="to"><string>9</string></field>
                </object>
              </value>
            </collection>
          </field>
        </object>
      </object-param>
    </init-params>
  </component>  
</configuration>

The " auto.create.group.page.navigation" parameter value is true or false. If this value is set to true it automatically creates portal navigations and pages for each group. If false it does not.

The "auto.create.user.page.navigation" parameter value is the number of pages that are automatically created for each user.

GateIn 3.0 provides support for skinning the entire portal User Interface (UI) including your own portlets. Skins are designed to help you pack and reuse common graphic resources.

Skins can be switched dynamically at runtime.

When you switch, the whole portal will be repainted and the new styles will be applied to the UI.

The complete skinning of a page can be decomposed into four parts:

The main portal skin stylesheet (/DefaultSkin/skin/Stylesheet.css)is shown below as an example:

@import url(/eXoResources/skin/PortletThemes/Stylesheet.css) ;
@import url(DefaultSkin/portal/webui/component/UIPortalApplicationSkin.css) ;
@import url(DefaultSkin/webui/component/Stylesheet.css) ;

A GateIn 3.0 skin contains css styles for the portal's components but also shares components that may be reused in portlets. When GateIn 3.0 generates a portal page markup, it inserts stylesheet links in the page's head tag.

In the snipped code below you can see two types of links:

<head>
...   
<link id="CoreSkin" rel="stylesheet" type="text/css" href="/eXoResources/skin/Stylesheet.css" />
<link id="web_FooterPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css" />
<link id="web_NavigationPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UINavigationPortlet/DefaultStylesheet.css" />
<link id="web_HomePagePortlet" rel="stylesheet" type="text/css" href= "/portal/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css" />
<link id="web_BannerPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UIBannerPortlet/DefaultStylesheet.css" />
...
</head>

	Portal skin stylesheet (id="CoreSkin").
	Portlets skins stylesheets (all others). Each portlet within the page may contribute its own style(s)

The default skin of portal is called Default. To change this value add a skin tag in the portal.xml that defines your portal:

<portal-config>

  <portal-name>classic</portal-name>

  <locale>en</locale>

  <access-permissions>Everyone</access-permissions>

  <edit-permission>*:/platform/administrators</edit-permission>

  <skin>MySkin</skin>

  <creator>root</creator>

...

Window styles are the CSS applied to window decoration. When an administrator choose a new application to add on a page he can decide which style of decoration would go around the window if any.

The code below illustrates the inclusion of all CSS resoucres for a new theme from the example file GateInResourcesCp060508/skin/MyPortalSkin/PortletThemes/Stylesheet.css.

/*---- MyTheme ----*/
.MyTheme .WindowBarCenter .WindowPortletInfo {
  margin-right: 80px; /* orientation=lt */
  margin-left: 80px; /* orientation=rt */
}
.MyTheme .WindowBarCenter .ControlIcon {
  float: right;/* orientation=lt */
  float: left;/* orientation=rt */
  width: 24px; 
  height: 17px;
  cursor: pointer;
  background-image: url('background/MyTheme.png');
}
.MyTheme .ArrowDownIcon {
  background-position: center 20px;
}
.MyTheme .OverArrowDownIcon {
  background-position: center 116px;
}
.MyTheme .MinimizedIcon {
  background-position: center 44px;
}
.MyTheme .OverMinimizedIcon {
  background-position: center 140px;
}
.MyTheme .MaximizedIcon {
  background-position: center 68px;
}
.MyTheme .OverMaximizedIcon {
  background-position: center 164px;
}
.MyTheme .RestoreIcon {
  background-position: center 92px;
}
.MyTheme .OverRestoreIcon {
  background-position: center 188px;
}
.MyTheme .NormalIcon {
  background-position: center 92px;
}
.MyTheme .OverNormalIcon {
  background-position: center 188px;
}
.UIPageDesktop .MyTheme .ResizeArea {
  float: right;/* orientation=lt */
  float: left;/* orientation=rt */
  width: 18px; height: 18px;
  cursor: nw-resize;
  background: url('background/ResizeArea18x18.gif') no-repeat left top; /* orientation=lt */
  background: url('background/ResizeArea18x18-rt.gif') no-repeat right top; /* orientation=rt */
}
.MyTheme .Information {
  height: 18px; line-height: 18px;
  vertical-align: middle; font-size: 10px;
  padding-left: 5px;/* orientation=lt */
  padding-right: 5px;/* orientation=rt */
  margin-right: 18px;/* orientation=lt */
  margin-left: 18px;/* orientation=rt */
}
.MyTheme .WindowBarCenter .WindowPortletIcon {
  background-position: left top; /* orientation=lt */
  background-position: right top; /* orientation=rt */
  padding-left: 20px; /* orientation=lt */
  padding-right: 20px; /* orientation=rt */
  height: 16px;
  line-height: 16px;
}
.MyTheme .WindowBarCenter .PortletName {
  font-weight: bold;
  color: #333333;
  overflow: hidden;
  white-space: nowrap;
  width: 100%;
}
.MyTheme .WindowBarLeft {
  padding-left: 12px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: left -148px;
}
.MyTheme .WindowBarRight {
  padding-right: 11px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: right -119px;
}
.MyTheme .WindowBarCenter {
  background-image: url('background/MyTheme.png');
  background-repeat: repeat-x;
  background-position: left -90px;
}
.MyTheme .WindowBarCenter .FixHeight {
  height: 21px;
  padding-top: 8px;
}
.MyTheme .MiddleDecoratorLeft {
  padding-left: 12px;
  background: url('background/MyTheme.png') repeat-y left;
}
.MyTheme .MiddleDecoratorRight {
  padding-right: 11px;
  background: url('background/MyTheme.png') repeat-y right;
}
.MyTheme .MiddleDecoratorCenter {
  background: #ffffff;
}
.MyTheme .BottomDecoratorLeft {
  MyTheme: 12px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: left -60px;
}
.MyTheme .BottomDecoratorRight {
  padding-right: 11px;
  background-image: url('background/MyTheme.png');
  background-repeat: no-repeat;
  background-position: right -30px;
}
.MyTheme .BottomDecoratorCenter {
  background-image: url('background/MyTheme.png');
  background-repeat: repeat-x;
  background-position: left top;
}
.MyTheme .BottomDecoratorCenter .FixHeight {
  height: 30px;
}

Portlets often require additionnal styles that may not be defined by the portal skin. GateIn 3.0 allows portlets to define additional stylesheets for each portlet and will append the corresponding link tags to the head.

The link ID will be of the form {portletAppName}{PortletName}. For example: ContentPortlet in content.war, will give id="contentContentPortlet"

To define a new CSS file to include whenever a portlet is added, the following snippet need to be added in gatein-resources.xml

<portlet-skin>
  <application-name>portletAppName</application-name>
  <portlet-name>PortletName</portlet-name>
  <skin-name>Default</skin-name>
  <css-path>/skin/DefaultStylesheet.css</css-path>
</portlet-skin>

<portlet-skin>
  <application-name>portletAppName</application-name>
  <portlet-name>PortletName</portlet-name>
  <skin-name>OtherSkin</skin-name>
  <css-path>/skin/OtherSkinStylesheet.css</css-path>
</portlet-skin>

The portal framework will include the CSS file corresponding to the skin in used.

In this tutorial, the SSO server is installed in a Tomcat installation. Tomcat can be obtained from http://tomcat.apache.org.

All the packages required for setup can be found in a zip file located at: http://repository.jboss.org/maven2/org/gatein/sso/sso-packaging. In this document we will call $SSO_HOME the directory where the file is extracted.

Users are advised to not run any portal extensions that could override the data when manipulating the gatein.ear file directly.

Remove $JBOSS_HOME/server/default/deploy/gatein-sample-extension.ear and $JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear which are packaged by default with GateIn 3.0.

First, set up the server to authenticate against the portal login module. In this example the CAS server will be installed on Tomcat.

To utilize the Central Authentication Service, GateIn 3.0 needs to redirect all user authentication to the CAS server.

Information about where the CAS is hosted must be properly configured within the GateIn 3.0 instance. The required configuration is done by modifying three files:

Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form.

This section details setting up the JOSSO server to authenticate against the GateIn 3.0 login module.

In this example the JOSSO server will be installed on Tomcat.

The next part of the process is to redirect all user authentication to the JOSSO server.

Information about where the JOSSO server is hosted must be properly configured within the GateIn 3.0 instance. The required configuration is done by modifying four files:

From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form.

This section details setting up the OpenSSO server to authenticate against the Enterprise Portal Platform login module.

In this example the JOSSO server will be installed on Tomcat.

The next part of the process is to redirect all user authentication to the OpenSSO server.

Information about where the OpenSSO server is hosted must be properly configured within the Enterprise Portal Platform instance. The required configuration is done by modifying three files:

From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form.

A service component is defined in configuration.xml by using <component> element.

There is only one required information when defining a service - the service implementation class, specified using <type>

Every component has a <key> that identifies it. If not explicitly set, a key defaults to the value of <type>. If key can be loaded as a class, a Class object is used as a key, otherwise a String is used.

The usual approach is to specify an interface as a key.

<?xml version="1.0" encoding="ISO-8859-1"?>

<configuration

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd

                          http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"

      xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">

   <component>

      <key>org.exoplatform.services.database.HibernateService</key>

      <type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>



      ...



   </component>

</configuration>

      

GateIn Kernel supports non-component objects that can be configured, instantiated, and injected into registered components, using method calls. The mechanism is called 'plugins', and allows portal extensions to add additional configurations to core services.

External plugin is defined by using <external-component-plugins> wrapper element which contains one or more <component-plugin> definitions. <external-component-plugins> uses <target-component> to specify a target service component that will receive injected objects.

Every <component-plugin> defines an implementation type, and a method on target component to use for injection (<set-method>).

A plugin implementation class has to implement org.exoplatform.container.component. ComponentPlugin interface.

In the following example PortalContainerDefinitionPlugin implements ComponentPlugin:

<?xml version="1.0" encoding="UTF-8"?>

<configuration

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd

                          http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"

      xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">



   <external-component-plugins>

      <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>

      <component-plugin>

         <!-- The name of the plugin -->

         <name>Add PortalContainer Definitions</name>



         <!-- The name of the method to call on the PortalContainerConfig

              in order to register the PortalContainerDefinitions -->

         <set-method>registerPlugin</set-method>



         <!-- The fully qualified name of the PortalContainerDefinitionPlugin -->

         <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>



         ...



      </component-plugin>

   </external-component-plugins>

</configuration>

         

It is possible to break configuration.xml file into many smaller files, that are then included into a 'master' configuration file. The included files are complete configuration xml documents by themselves - they are not fragments of text.

An example configuration.xml that 'outsources' its content into several files:

<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd

                          http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"

      xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">



   <import>war:/conf/sample-ext/jcr/jcr-configuration.xml</import>

   <import>war:/conf/sample-ext/portal/portal-configuration.xml</import>



</configuration>

         

We see a special URL being used to reference another configuration file. URL schema 'war:' means, that the path that follows is resolved relative to current PortalContainer's servlet context resource path, starting at WEB-INF as a root.

Also, thanks to extension mechanism, the servlet context used for resource loading is a unified servlet context (as explaned in a later section).

To have include path resolved relative to current classpath (context classloader), use 'jar:' URL schema.

Configuration files may contain a special variable reference ${container.name.suffix}. This variable resolves to the name of the current portal container, prefixed by underscore (_). This facilitates reuse of configuration files in situations where portal specific unique names need to be assigned to some resources (i.e. JNDI names, Database / DataSource names, JCR repository names, etc ...).

This variable is only defined when there is a current PortalContainer available - only for PortalContainer scoped services.

A good example for this is HibernateService:

<?xml version="1.0" encoding="ISO-8859-1"?>

<configuration

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd

                       http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"

   xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">



   <component>

      <key>org.exoplatform.services.database.HibernateService</key>

      <jmx-name>database:type=HibernateService</jmx-name>

      <type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>

      <init-params>

         <properties-param>

            <name>hibernate.properties</name>

            <description>Default Hibernate Service</description>

            <property name="hibernate.show_sql" value="false" />

            <property name="hibernate.cglib.use_reflection_optimizer" value="true" />

            <property name="hibernate.connection.url"

                            value="jdbc:hsqldb:file:../temp/data/exodb${container.name.suffix}" />

            <property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver" />

            <property name="hibernate.connection.autocommit" value="true" />

            <property name="hibernate.connection.username" value="sa" />

            <property name="hibernate.connection.password" value="" />

            <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect" />

            <property name="hibernate.c3p0.min_size" value="5" />

            <property name="hibernate.c3p0.max_size" value="20" />

            <property name="hibernate.c3p0.timeout" value="1800" />

            <property name="hibernate.c3p0.max_statements" value="50" />

         </properties-param>

      </init-params>

   </component>

</configuration>