Integration into a specific application server / web container involves several aspects of GateIn configuration, operation, and features availability.
JBoss AS7 is a very compact, modular, and extensible application server, based on concurrent, and isolated classloading layer called JBoss Modules, and on fully parallel kernel called Modular Service Container (MSC). On top of these there is a standalone server with a notion of subsystems, and centralized configuration management.
Most notable features of AS7 are parallel deployment of application archives, and finegrained class isolation. The result is a combination of great performance, and multitenant coexistence of different applications without cross-influences between them.
GateIn integrates into JBoss AS7 via a custom subsystem. The main JBoss AS7 configuration file where subsystems are configured is located at $JBOSS_HOME/standalone/configuration/standalone.xml.
GateIn subsystem is activated with the following xml snippet:
<subsystem xmlns="urn:jboss:domain:gatein:1.0">
<portlet-war-dependencies>
<dependency name="org.gatein.wci"/>
<dependency name="org.gatein.pc"/>
<dependency name="javax.portlet.api"/>
</portlet-war-dependencies>
</subsystem>
The <portlet-war-dependencies> element specifies a list of libraries (available as modules under $JBOSS_HOME/modules directory) that are automatically available to all your portlet applications. The listed modules are required, and should not be removed. It's possible to add additional modules, which might allow you to deploy some existing portlet applications without repackaging them.
JBoss AS7 provides mechanisms for configuring which modules are visible to a specific deployment archive. One mechanism involves adding additional attribute to deployment archive's MANIFEST.MF - Dependencies attribute in MANIFEST.MF. Another one involves adding a JBoss AS7 specific descriptor file jboss-deployment-structure.xml to your deployment archive. You can read more about it in JBoss AS7 Developer Guide - Class Loading in AS7.
When gatein subsystem is active it takes care of boot-time GateIn initialization. Boottime initialization expects to find gatein.ear deployment archive at $JBOSS_HOME/gatein/gatein.ear, and it looks for any additional deployment archives in $JBOSS_HOME/gatein/extensions. These additional deployment archives can have any names, but have to be either one of .ear, .war, or .jar.
Archives placed in $JBOSS_HOME/gatein/extensions are not hot-deployable. They are treated as extensions of default gatein.ear - meaning that this is a place for archives that integrate with GateIn configuration management system as they install additional GateIn kernel services, override default services configuration, or add/override default portal resources. All GateIn custom skins, custom portals, and custom extensions should be deployed to this directory.
GateIn's Extension mechanism is described in Developer's Guide - Portal Containers and Extensions, and in Reference Guide - Foundations.
JBoss AS7 supports two different running modes. It can run as a standalone server (a standalone mode), or it can run as part of a server domain (a domain mode).
The difference between the two modes is in configuration management. Domain mode provides central configuration management for multiple servers, while in standalone mode every server maintains its own local configuration. There is no difference in available server features between the two modes, and advanced setups like clustering with session replication, and single sign-on can be configured in both standalone, and domain mode.
GateIn 3.5 only supports standalone mode.
There are several locations in JBoss AS7 where GateIn adds code or configuration:
$JBOSS_HOME/gatein
... contains gatein.ear deployment archive, which contains all the portal resources packaged as multiple web application archives. The libraries are available as modules under $JBOSS_HOME/modules, and are not part of the deployment archive. When implementing your portal by starting from scratch and replacing significant parts of the default portal with your own functionality, you can make changes directly in this directory to completely redefine many aspects of the portal.
$JBOSS_HOME/gatein/extensions
... contains custom extensions, custom portals, and custom skins. Initially this directory is empty. When building your portal as a customization of existing default portal, or when adding additional custom portals or custom skins, you would create your own portal extension archives and place them in this directory.
$JBOSS_HOME/modules
... contains classes packaged as isolated modules. It contains both modules that come with JBoss AS7, and additional modules added by GateIn. Developers can add their own modules here. Libraries that are to be shared between different application archives should be packaged as jboss modules, and placed here.
$JBOSS_HOME/standalone/configuration/gatein
... contains gatein configurations - i.e. the master configuration.properties file.
$JBOSS_HOME/standalone/data/gatein
... contains JCR Lucene indexes.
$JBOSS_HOME/standalone/deployments
... a directory used by JBoss AS7 deployment scanner to auto-detect and hot-deploy application archives. Your portlet applications, web applications, and Java EE applications can be placed here in order to be deployed. You should not place in this directory custom portal extensions, custom portals, or custom skins. Those archives deeply integrate with GateIn kernel, and are not hot-deployable. They should be placed in $JBOSS_HOME/gatein/extensions in order to be deployed as part of GateIn boot-time initialization.
$JBOSS_HOME/standalone/configuration/standalone.xml
This is a master JBoss AS7 configuration file. It contains gatein subsystem configuration, configuration of datasources, configuration of security realms required by deployed portals, and configuration for all the other JBoss AS7 subsystems.
There are a few GateIn services that are only available with JBoss AS7:
SSO
Clustered mode
WSRP
TODO