h1. Overview of architecture {anchor:id=DEV.eXoArchitecturePremer.Overview}

h1. Kernel {anchor:id=DEV.eXoArchitecturePremer.Kernel}

All eXo services are built around the eXo kernel, or the service management layer, which manages the configuration and the execution of all components.
The main kernel object is the eXo Container, a micro-container that glues services together through dependency injection. The container is responsible for loading services/components.

This chapter will introduce the concepts of Container and Services, and will give you an overview before configuring basic services.

h2. Containers {anchor:id=DEV.eXoArchitecturePremer.Containers}

A container is always required to access a service, because the eXo kernel relies on dependency injection. This means that the life cycle of a service (for example, instantiating, opening and closing streams, disposing) is handled by a dependency provider, such as the eXo Container, rather than the consumer. The consumer only needs a reference to an implementation of the requested service. The implementation is configured in an *.xml* configuration file that comes with every service. To learn more about dependency injection, visit [here|http://en.wikipedia.org/wiki/Dependency_injection].

eXo has two types of container: {{RootContainer}} and {{PortalContainer}}. 

The RootContainer holds the low level components. It is automatically started before the PortalContainer. You will rarely interact directly with the RootContainer except when you activate your own extension.
The PortalContainer is created for each portal (one or several portals). All services started by this container will run as embedded in the portal. It also gives access to components of its parent RootContainer.


In your code, if you need to invoke a service of a container, you can use the {{ExoContainerContext}} helper from any location. The code below shows you a utility method that you can use to invoke any eXo service.

{code:language=java}

public class ExoUtils {

  /**
   * Get a service from the portal container
   * @param type : component type
   * @return the concrete instance retrieved in the container using the type as key
   */
  public <T>T getService(Class<T> type) {
    return (T)ExoContainerContext.getCurrentContainer().getComponentInstanceOfType(type);
  }
  
}
{code}
Then, invoking becomes as easy as:
{code:language=java}
  OrganizationService orgService = ExoUtils.getService(OrganizationService.class)
{code}

h2. Services {anchor:id=DEV.eXoArchitecturePremer.Services}

Containers are used to gain access to services. Important characteristics of services are:

* Because of the Dependency Injection concept, the interface and implementation for a service are usually separate.
* Each service has to be implemented as a singleton, which means it is created only once per portal container in a single instance.
* A component equals a service. A service must not be a large application. A service can be a little component that reads or transforms a document, in which case the term component is often used instead of service.

For example, in the lib/folder, you can find services for databases, caching, ldap:

* exo.core.component.database-x.y.z.jar
* exo.kernel.component.cache-x.y.z.jar
* exo.core.component.organization.ldap-x.y.z.jar

h2. Service configuration {anchor:id=DEV.eXoArchitecturePremer.ServiceConfiguration}

To declare a service, you must add an *.xml* configuration file to a specific place. This file can be in the jar file, in a webapp or in the external configuration directory. If you write a new component for the eXo Container, you should always provide a default configuration in your jar file. This default configuration must be in the file /conf/portal/configuration.xml in your jar.  

A configuration file can specify several services, so there can be several services in one jar file.

h3. Kernel XML Schema {anchor:id=DEV.eXoArchitecturePremer.KernalXMLSchema}

Containers configuration files must comply with the kernel configuration grammar. Thus, all configurations will contain an XSD declaration like this:

{code:language=xml}
<configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd">
</configuration>
{code}

The {{kernel_1_1.xsd}} file mentioned in the example above can be found inside {{exo.kernel.container-x.y.z.jar!org/exoplatform/container/configuration/}} along with other versions.

h3. Components {anchor:id=DEV.eXoArchitecturePremer.Components}

The service registration within the container is done with the {{<component>}} element.

For example, open the {{exo-ecms-core-services-x.y.z.jar}} file. Next, open {{/conf/portal/configuration.xml}}, you will see:

{code:language=xml}
  <component>
    <type>org.exoplatform.services.deployment.ContentInitializerService</type>
  </component>
  <component>
    <key>org.exoplatform.services.cms.CmsService</key>
    <type>org.exoplatform.services.cms.impl.CmsServiceImpl</type>
  </component>	
{code}

Each component has a {{key}} which matches the qualified Java interface name ({{org.exoplatform.services.cms.CmsService}}). 

The specific implementation class of the component ({{CmsServiceImpl}}) is defined in the {{<type>}} tag.

If a service does not have a separate interface, the {{<type>}} will be used as the key in the container. This is the case of{{ContentInitializerService}}. 


h3. Parameters {anchor:id=DEV.eXoArchitecturePremer.Parameters}

You can provide initial parameters for your service by defining them in the configuration file. The followings are different parameters:

* value-param
* properties-param
* object-param
* collection
* map
* native-array


h4. Value-param {anchor:id=DEV.eXoArchitecturePremer.Value-param}

You can use the value-param to pass a single value to the service.

{code:language=xml}
<component>
    <key>org.exoplatform.services.resources.LocaleConfigService</key>
    <type>org.exoplatform.services.resources.impl.LocaleConfigServiceImpl</type>
      <init-params>
        <value-param>
          <name>locale.config.file</name>
          <value>war:/conf/common/locales-config.xml</value>
        </value-param>
      </init-params>
  </component>
{code}

The LocaleConfigService service accesses to the value of value-param in its constructor.

{code:language=java}
package org.exoplatform.services.resources.impl;
public class LocaleConfigServiceImpl implements LocaleConfigService
{
public LocaleConfigServiceImpl(InitParams params, ConfigurationManager cmanager) throws Exception
   {
      configs_ = new HashMap<String, LocaleConfig>(10);
      String confResource = params.getValueParam("locale.config.file").getValue();
      InputStream is = cmanager.getInputStream(confResource);
      parseConfiguration(is);
   }
{code}


h4. Object-param {anchor:id=DEV.eXoArchitecturePremer.Object-param}

For the object-param component, you can look at the LDAP service:

{code:language=xml}
<component>
  <key>org.exoplatform.services.ldap.LDAPService</key>
  <type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
  <init-params>
    <object-param>
      <name>ldap.config</name>
      <description>Default ldap config</description>
      <object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
        <field name="providerURL"><string>ldaps://10.0.0.3:636</string></field>
        <field name="rootdn"><string>CN=Administrator,CN=Users,DC=exoplatform,DC=org</string></field>
        <field name="password"><string>exo</string></field>
        <field name="version"><string>3</string></field>
        <field name="minConnection"><int>5</int></field>
        <field name="maxConnection"><int>10</int></field>
        <field name="referralMode"><string>ignore</string></field>
        <field name="serverName"><string>active.directory</string></field>
      </object>
    </object-param>
  </init-params>
</component>
{code}

An object-param is used to create an object (which is actually a Java Bean) passed as a parameter to the service. This object-param is defined by a name, a description and exactly one object. The object tag defines the type of the object, while the field tags define parameters for that object.

You can see how the service accesses the object in the code below:

{code:language=java}
package org.exoplatform.services.ldap.impl;

public class LDAPServiceImpl implements LDAPService {
// ...
public LDAPServiceImpl(InitParams params) {
  LDAPConnectionConfig config = (LDAPConnectionConfig) params.getObjectParam("ldap.config").getObject();
// ...
{code}

The passed object is LDAPConnectionConfig, which is a classic Java Bean. It contains all fields defined in the configuration files and also the appropriate getters and setters (not listed here). You also can provide default values. The container creates a new instance of your Java Bean and calls all setters whose values are configured in the configuration file.

{code:language=java}
package org.exoplatform.services.ldap.impl;

public class LDAPConnectionConfig {
  private String providerURL = "ldap://127.0.0.1:389";
  private String rootdn;
  private String password;
  private String version;
  private String authenticationType = "simple";
  private String serverName = "default";
  private int minConnection;
  private int maxConnection;
  private String referralMode = "follow";
  // ...
{code}

h4. Rest of parameter types {anchor:id=DEV.eXoArchitecturePremer.RestOfParameterTypes}

Other possible parameter types are Collection, Map and Native Array. See the exhaustive reference in the kernel reference guide.

h2. Plugins {anchor:id=DEV.eXoArchitecturePremer.Plugins}

Some components may want to offer some extensibilities. For this, they use a plugin mechanism based on the injection method. To offer an extension point for plugins, a component needs to provide a public method that takes an instance of {{org.exoplatform.container.xml.ComponentPlugin}} as a parameter.

Plugins enable you to provide structured configuration from outside the original declaration of the component. This is the main way you will use to customize eXo Platform for your needs.

You can have a look at the configuration of the {{TaxonomyPlugin}} of the {{TaxonomyService}} as below:

{code:language=xml}
<external-component-plugins>
  <target-component>org.exoplatform.services.cms.taxonomy.TaxonomyService</target-component>
  <component-plugin>
    <name>predefinedTaxonomyPlugin</name>
    <set-method>addTaxonomyPlugin</set-method>
    <type>org.exoplatform.services.cms.taxonomy.impl.TaxonomyPlugin</type>
    <init-params><!-- ... --></init-params>
  </component-plugin>
</external-component-plugins>
{code}

The {{<target-component>}} defines components that host the extension point. The configuration is injected by the container using the method defined in {{<set-method>}} ({{addTaxonomyPlugin()}}. The method accepts exactly one argument of the type{{org.exoplatform.services.cms.categories.impl.TaxonomyPlugin}}.

The content of <init-params> is interpreted by the TaxonomyPlugin object.

h2. Configuration loading sequence {anchor:id=ADM.eXoArchitecturePremer.ConfigureLoadingSequence}

The kernel startup follows a well-defined sequence to load configuration files. The objects are initialized in the container only after the whole loading sequence is done. Hence, by placing your configuration in the upper location of the sequence, you can override a component declaration by yourself. You will typically do this when you want to provide your own implementation of a component, or declare custom init-params.

{note}
{{external-component-plugins}} declarations are additive, so it is NOT possible to override them.
{note}

The loading sequence involves loading successively configurations for the RootContainer then from the PortalContainers:

# Services default RootContainer configurations from JAR files {{/conf/configuration.xml}}.
# External RootContainer configuration will be found at {{$exo.conf.dir/configuration.xml}}.
# Services default PortalContainer configurations from JAR files {{/conf/$PORTAL/configuration.xml}}.
# Web applications configurations from WAR files {{/WEB-INF/conf/configuration.xml}}.
# External configuration for services of the portal will be found at {{$exo.conf.dir/portal/$PORTAL/configuration.xml}}.

{note}
* $exo.conf.dir is a system property that points to the external configuration file on the file system. It is passed to the JVM in the startup script like {{-Dexo.conf.dir=gatein}}.

* $PORTAL is the name of the portal container. By default, the name is unique that is called 'portal'.
{note}

h1. GateIn extensions {anchor:id=DEV.eXoArchitecturePremer.GateInExtensions}

GateIn extensions are special *.war* files that are recognized by eXo Platform and contribute to custom configurations to the PortalContainer. To create your own portal, you will have to create a GateIn extension.

The extension mechanism makes possible to extend or even override portal resources in almost plug-and-play way. You simply add a *.war* archive with your custom resources to the war folder and edit the configuration of the PortalContainerConfig service. Customizing a portal does not involve unpacking and repacking the original portal *.war* archives. Instead, you need to create your own *.war* archive with your own configurations, and modify resources. The content of your custom *.war* archive overrides the resources in the original archives.

The most elegant way to reuse configuration for different coexisting portals is by way of extension mechanism - by inheriting resources and configuration from existing web archives, and just adding extra resources to it, and overriding those that need to be changed by including modified copies.

{note}
Starter is a web application that has been added to create and start all the portals, such as portal containers, at the same time once all the other web applications have already been started. In fact, all other web applications can potentially defined several things at startup, such as skins, javascripts, google gadgets and configuration files. The loading order is important as we can define skins or configuration files or a javascript again from a web application 1. This could depend on another Javascript from a web application 2. Thus, if the web application 2 is loaded after the web application 1, you will get errors in the merged Javascript file.
{note}

If you ship servlets or servlet filters as part of your portal extension, and if you need to access specific resources of portal at any time during processing of the servlet or filter request, you need to make sure the servlet/filter is associated with the current container. The proper way to do that is to make your servlet extend org.exoplatform.container.web.AbstractHttpServlet class. This will not only properly initialize the current PortalContainer for you, but  also  set  the  current  thread's  context  classloader  to  one  that  looks  for  resources in associated web applications in the order specified by Dependencies configuration (as explained in the Extension mechanism section).

Similarly for filters,  make  sure  your filter class extends org.exoplatform.container.web.AbstractFilter. Both AbstractHttpServlet and AbstractFilter have the method getContainer(), which returns the current PortalContainer.


h2. Default Portal Container {anchor:id=DEV.eXoArchitecturePremer.defaultPortalContainer}

eXo Platform comes with a pre-configured PortalContainer named "portal". This portal container configuration ties the core and extended services stack. The default Portal Container is started from {{portal.war}} and naturally maps to the {{/portal}} url.

The GateIn extension mechanism lets you extend the portal context easily. This feature is fundamental as it shields you from any changes we may want to do in *portal.war*. You do not need to be afraid of upgrades anymore as your *extension.war* will be clearly separated from the *portal.war*.

To achieve this extensibility, the PortalContainer activates two advanced features: 

* a unified classloader: any classpath resource, such as property files, will be accessible as if it was inside the *portal.war*.

{note}
This is valid only for resources but not for java classes.
{note}

* a unified servlet context: any web resource contained in your *extension.war* will be accessible from /portal/ uri.

The next part explains what to do to make a simple extension for "portal" container.

h2. Register Extension {anchor:id=DEV.eXoArchitecturePremer.RegisterExtension}

The webapps are loaded in the order defined in the list of dependencies of the {{PortalContainerDefinition}}. You then need to deploy the *starter.war*; otherwise, the webapps will be loaded in the default application server's order', such as the loading order of the Application Server.

If you need to customize your portal by adding a new extension and/or a new portal, you need to define the related {{PortalContainerDefinitions}} and to deploy the starter. Otherwise, you do not need to define any {{PortalContainerDefinition}} or deploy the starter.

First, you need to tell eXo Platform to load {{WEB-INF/conf/configuration.xml}} of your extension, you need to declare it as a {{PortalContainerConfigOwner}}. Next, open the file {{WEB-INF/web.xml}} of your extension and add a listener:

{code:language=xml}
<web-app>
  <display-name>my-portal</display-name>
  <listener>
   <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
  </listener>
<!-- ... -->
</web-app>
{code}

You need to register your extension in the portal container. This is done by the *.xml* configuration file like this: 

{code:language=xml}

<external-component-plugins>
  <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
  <component-plugin>
    <name>Change PortalContainer Definitions</name>
    <set-method>registerChangePlugin</set-method>
    <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    <init-params>
      <object-param>
        <name>change</name>
        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
          <field name="dependencies">
            <collection type="java.util.ArrayList">
              <value>
                <string>my-portal</string>
              </value>
              <value>
                <string>my-portal-resources</string>
              </value>              
            </collection>
          </field>
        </object>
      </object-param> 
      <value-param>
        <name>apply.default</name>
        <value>true</value>
      </value-param>       
    </init-params>
  </component-plugin>
</external-component-plugins>
{code}


We define a {{PortalContainerDefinitionChangePlugin}} plugin to the {{PortalContainerConfig}}. The plugin declares a list of dependencies that are webapps. The {{apply.default=true}} indicates that your extension is actually extending *portal.war*. You  need to package your extension into a *.war* file and put it to the tomcat webapps folder, then restart the server.

In your portal, if you want to add your own property file to support localization for your keys, you can do as follows:

- Put your property file into folder /WEB-INF/classes/locale/portal of your extension project.

- Add an external plugin declaration to the *.xml* configuration file.	  

{code}
<external-component-plugins>
                <!-- The full qualified name of the ResourceBundleService -->
                <target-component>org.exoplatform.services.resources.ResourceBundleService</target-component>
                <component-plugin>
                        <!-- The name of the plugin -->
                        <name>Sample ResourceBundle Plugin</name>
                        <!-- The name of the method to call on the ResourceBundleService in order to register the ResourceBundles -->
                        <set-method>addResourceBundle</set-method>
                        <!-- The full qualified name of the BaseResourceBundlePlugin -->
                        <type>org.exoplatform.services.resources.impl.BaseResourceBundlePlugin</type>
                        <init-params>
                                <!--values-param>
                                        <name>classpath.resources</name>
                                        <description>The resources that start with the following package name should be load from file system</description>
                                        <value>locale.portlet</value>
                                </values-param-->
                                <values-param>
                                        <name>init.resources</name>
                                        <description>Store the following resources into the db for the first launch </description>
                                        <value>locale.portal.sample</value>
                                </values-param>
                                <values-param>
                                        <name>portal.resource.names</name>
                                        <description>The properties files of the portal , those file will be merged
                                                into one ResoruceBundle properties </description>
                                        <value>locale.portal.sample</value>
                                </values-param>
                        </init-params>
                </component-plugin>
        </external-component-plugins>
{code}

h1. Java Content Repository {anchor:id=DEV.eXoArchitecturePremer.JavaContentRepository}

All data in eXo Platform is stored in a Java Content Repository (JCR). JCR is a Java specification ([JSR-170|http://jcp.org/aboutJava/communityprocess/final/jsr170/index.html] ) for a type of Object Database tailored to the storage, searching, and retrieval of hierarchical data. It is useful to content management systems, which require storage of objects associated with metadata. A JCR also provides versioning, transactions, observations of changes in data, and import or export of data in XML. The data in JCR is stored hierarchically in a tree of nodes with associated properties.

Also, the JCR is primarily used as an internal storage engine. Accordingly, eXo Content lets you manipulate JCR data directly in several places. 


h2. Repositories and workspaces {anchor:id=DEV.eXoArchitecturePremer.Repositories&Workspaces}

A content repository consists of one or more workspaces. Each workspace contains a tree of items.

To access a repository's content from a service:

{code:language=java}
import javax.jcr.Session;

import org.exoplatform.services.jcr.RepositoryService;
import org.exoplatform.services.jcr.core.ManageableRepository;
import org.exoplatform.services.jcr.ext.common.SessionProvider;
import org.exoplatform.services.wcm.utils.WCMCoreUtils;

// For example
RepositoryService repositoryService = WCMCoreUtils.getService(RepositoryService.class);
ManageableRepository manageableRepository = repositoryService.getRepository(repository);
SessionProvider sessionProvider = WCMCoreUtils.getSessionProvider();
Session session = sessionProvider.getSession(workspace, manageableRepository);
{code}

You can use the session object to retrieve your node content.

{code}
String path = "/"; // put your node path here
Node node = (Node) session.getItem(path);
{code}

A javax.jcr.Repository object can be obtained via one of the following ways:

-- Using the eXo Container "native" mechanism. All Repositories are kept with a single RepositoryService component. So it can be obtained from eXo Container as below:

{code}
RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class);
  Repository repository = repositoryService.getRepository("repositoryName");
{code}

-- Using the eXo Container "native" mechanism with a thread local saved "current" repository (especially if you plan to use a single repository which covers more than 90% of usecases)

{code}
// set current repository at initial time
  RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class);
  repositoryService.setCurrentRepositoryName("repositoryName");
  ....
  // retrieve and use this  repository
  Repository repository = repositoryService.getCurrentRepository();
{code}

-- Using JNDI as specified in JSR-170.

{code}
Context ctx = new InitialContext();
Repository repository =(Repository) ctx.lookup("repositoryName"
{code}

Next, you need to log in the server to get a Session object by either of two ways:

-- Creating a Credential object, for example:

Credentials credentials = new SimpleCredentials("exo", "exo".toCharArray());

Session jcrSession = repository.login(credentials, "production");

-- Logging in by using:

Session jcrSession = repository.login("production");

This way is only applied when you run an implementation of eXo Platform embedded in the portal.

In embedded cases, the implementation will directly leverage the organization and security services that rely on LDAP or DB storage and JAAS login modules. Single-Sign-On products can now also be used as eXo Platform v.2 which supports them.

*JCR Session common considerations*

-- javax.jcr.Session is not a safe object of thread. So, you should never try to share it between threads.
-- Do not use System session from the user-related code because a system session has unlimited rights. Call ManageableRepository.getSystemSession() from the process-related code only.
-- Call Session.logout() explicitly to release resources assigned to the session.
-- When designing your application, you should take care of the Session policy inside your application. Two strategies are possible: Stateless (Session per business request) and Stateful (Session per User) or some mixes.

h2. Tree structure: working with nodes and properties {anchor:id=DEV.eXoArchitecturePremer.WorkingWithNodes&Properties}

Every node can only have one primary node type. The primary node type defines names, types and other characteristics of the properties and child nodes that a node is allowed (or required) to have. Every node has a special property called jcr:primaryType that records the name of its primary node type. A node may also have one or more mixin types. These are node type definitions that can mandate extra characteristics (for example, more child nodes, properties and their respective names and types).

Data is stored in properties, which may hold simple values, such as numbers and strings or binary data of arbitrary length. 

The JCR API provides methods to define node types and node properties, create or delete nodes, and add or delete properties to an existing node.

You can refer to "Chapter 6.2.3 Node Read Methods" in the JCR Specification document.