A container is always required to access a service, because the eXo Kernel relies on the dependency injection. This means that the lifecycle 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 the dependency injection, visit here.

eXo Platform provides two types of containers: 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 Platform service.

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);

  }

}

Then, invoking becomes as easy as:

OrganizationService orgService = ExoUtils.getService(OrganizationService.class)

Containers are used to gain access to services. The followings are important characteristics of services:

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

To declare a service, you must add the .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 /conf/portal/configuration.xml file in your jar.

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

<configuration xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" 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">

</configuration>

<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>    

<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>

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);

  }

}

<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>

package org.exoplatform.services.ldap.impl;


public class LDAPServiceImpl implements LDAPService {

  // ...

  public LDAPServiceImpl(InitParams params) {

    LDAPConnectionConfig config = (LDAPConnectionConfig) params.getObjectParam("ldap.config").getObject();

    ...

  }

  // ...

}

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";

  // ...

}

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 the structured configuration outside the original declaration of the component. This is the main way to customize eXo Platform to your needs.

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

<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>

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.

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.

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

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:

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

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:

<web-app>

  <display-name>my-portal</display-name>

    <listener>

      <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>

    </listener>

  <!-- ... -->

</web-app>

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

<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>

A PortalContainerDefinitionChangePlugin plugin is defined 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:

<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>

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

To access the repository's content from a service:

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);

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

String path = "/"; // put your node path here

Node node = (Node) session.getItem(path);

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

RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class);

Repository repository = repositoryService.getRepository("repositoryName");

// 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();

Context ctx = new InitialContext();

Repository repository =(Repository) ctx.lookup("repositoryName");

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

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


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

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:

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 are stored in properties, which may hold simple values, such as numbers, 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 Section 6.2.3. Node Read Methods in the JCR Specification document.