eXo Platform 3.0 Developers Guide

A container is always required in order to access a service, because the eXo Kernel relies on dependency injection. This means that the life-cycle of a service (instantiating, opening and closing streams, disposing, etc.) is handled by a dependency provider (i.e. the eXo Container) rather than the consumer. The consumer only needs a reference to an implementation of the requested service, which is provided in the configuration.xml file that comes with every service. You can read more about dependency injection here http://en.wikipedia.org/wiki/Dependency_injection.

eXo has two several kinds of container, the RootContainer and the PortalContainer. The RootContainer holds the lower level components. It is automatically started before the PortalContainer. You will rarely interact directly with it except to activate your own extension (more on this further). The PortalContainer is created at the startup of the portal web application (portal.war). All services started by this container will run embedded in the portal. It also gives access to the 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.

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. Important characteristics of services are:

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

To declare a service, you must add an xml configuration file in a specific your classpath. 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>	

3.2.3.4. Value-param

You can use the value param to pass values to methods inside the service.

<component>
  <key>org.exoplatform.portal.config.UserACL</key>
  <type>org.exoplatform.portal.config.UserACL</type>
  <init-params>
    <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>

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

package org.exoplatform.portal.config;
public class UserACL {

public UserACL(InitParams params) {
UserACLMetaData md = new UserACLMetaData();
ValueParam accessControlWorkspaceParam = params.getValueParam("access.control.workspace");
if(accessControlWorkspaceParam != null) md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue());
...

	Note
	In this case, the UserACL service has the same <key> and <type>. This corresponds to the special case of a single implementation service. The developer may decide not to create an interface if there will not be more than one implementation of the service.

<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 extensibility. For this, they use a plugin mechanism based on method injection. 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 parameter.

Plugins allow 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.

Let's have a look at the configuration of the TaxonomyPlugin of the TaxonomyService:

<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 the components that hosts the extension point.The configuration is injected by the container using a method that is 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> corresponds to the structure of the TaxonomyPlugin object.

The kernel startup follows a well defined sequence to load configuration. The objects are initialized in the container only after the whole loading sequence is done. Hence, by placing your configuration in an upper location of the sequence, you can override a component declaration by your own. 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.

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

	Note
	$exo.conf.dir is a system property, that points to a path in filesystem. It is passed to the JVM in the startup script like with Dexo.conf.dir=gatein $PORTAL is the name of the portal container. By default, there is only one and it is called 'portal'

eXo Platform comes with a preconfigured PortalContainer named "portal". This portal container configuration ties together the core and extended services stack. It is started from portal.war and naturally maps to the /portal uri.

The gatein extensions mechanism lets you very easily extend the /portal context. This capacity is fundamental as it shields you from any changes we may want to do in portal.war. You do not need to fear of upgrades anymore as your extension war will be clearly separated from the portal war.

To achieve this magical extensibility, the PortalContainer turns on two advanced features :

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

First, you will want eXo to load the WEB-INF/conf/configuration.xml of your extension. For this, declare it as a PortalConfigOwner in web.xml :

<web-app>
  <display-name>my-portal</display-name>
  <listener>
   <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
  </listener>
<!-- ... -->
</web-app>

Then you need to register your extension by appending it to the list of dependencies that already contribute to the portal container. This is done by an xml configuration liek 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>

We define a PortalContainerDefinitionChange$AddDependencies plugin to the PortalContainerConfig. The plugin declares a list of dependencies that are webapps. The apply.default=true indicates that your extension is acutally extending portal.war.

A content repository consists of one or more workspaces, each of which contains a tree of items.

To access a repository's content at a component level :

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

Every node can only have one primary node type. The primary node type defines the 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 (i.e., more child nodes, properties and their respective names and types).

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

	Note
	include sample JCR data

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.

The configuration of the "classic" portal can be found in the directory /src/main/webapp/WEB-INF/conf/sample-ext/portal/portal/classic of your extension webapp.

The portal.xml file describes the layout and portlets common to all the pages of the portal.

<?xml version="1.0" encoding="ISO-8859-1"?>
<portal-config
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0"
    xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0">
  <portal-name>classic</portal-name>
  <locale>en</locale>
  <access-permissions>Everyone</access-permissions>
  <edit-permission>*:/platform/administrators</edit-permission>
  <properties>
    <entry key="sessionAlive">onDemand</entry>
  </properties>
    
     <portal-layout>
      <portlet-application>
      <portlet>
        <application-ref>web</application-ref>
        <portlet-ref>BannerPortlet</portlet-ref>
        <preferences>
          <preference>
            <name>template</name>
            <value>par:/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</value>
            <read-only>false</read-only>
          </preference>
        </preferences>
      </portlet>
      <access-permissions>Everyone</access-permissions>
        <show-info-bar>false</show-info-bar>
      </portlet-application>

      <portlet-application>
      <portlet>
       ...
      </portlet>
      </portlet-application>
        
      <portlet-application>
      <portlet>
        ...
      </portlet>
      </portlet-application>
      
      <page-body> </page-body>
      
     <portlet-application>
       <portlet>
         ...
       </portlet>
     </portlet-application>
  </portal-layout>
</portal-config>

As you can see, each portlet can be configured with a set of preferences, which will be further detailed.

The pages.xml file is used to describe the content of the pages of your portal. In other words, what will be inside the <page-body> tag of the portal.xml file above. Here is an example of the classic portal pages.xml.

<page>
    <name>homepage</name>
    <title>Home Page</title>
    <access-permissions>Everyone</access-permissions>
    <edit-permission>*:/platform/administrators</edit-permission>
    <container id="ClassicBody" template="system:/groovy/portal/webui/container/UITableColumnContainer.gtmpl">
      <access-permissions>Everyone</access-permissions>
      <container id="ClassicLeft" template="system:/groovy/portal/webui/container/UIContainer.gtmpl">
        <access-permissions>Everyone</access-permissions>
        <portlet-application>
          <portlet>
            <application-ref>presentation</application-ref>
            <portlet-ref>SingleContentViewer</portlet-ref>
            <preferences>
              <preference>
                <name>repository</name>
                <value>repository</value>
                <read-only>false</read-only>
              </preference>
              ...
              <preference>
                <name>ShowTitle</name>
                <value>false</value>
                <read-only>false</read-only>
              </preference>
            </preferences>
          </portlet>
          <title>Introduce</title>
          <access-permissions>Everyone</access-permissions>
          <show-info-bar>false</show-info-bar>
          <show-application-state>false</show-application-state>
          <show-application-mode>false</show-application-mode>
        </portlet-application>
      </container>
    </container>
  </page>

	Note
	This section is meant to help you organize the layout and structure of your portal. Review the "Working with applications" chapter to learn more about portlet configuration within the pages.xml file.

The navigation.xml is used to associate the links in your navigation (called page-node) with your portal pages.

If the pattern #{} is used then the label of the link will be loaded from the portal resource bundle (link to the ref guide about resource bundles

<?xml version="1.0" encoding="UTF-8"?>
<node-navigation>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<priority>1</priority>
<page-nodes>
<node>
<uri>home</uri>
<name>home</name>
<label>#{portal.classic.home}</label>
<page-reference>portal::classic::homepage</page-reference>
</node>
<node>
<uri>webexplorer</uri>
<name>webexplorer</name>
<label>#{portal.classic.webexplorer}</label>
<page-reference>portal::classic::webexplorer</page-reference>
</node>
</page-nodes>
</node-navigation>

This navigation tree can have multiple views inside portliest, such as breadcrumbs that render the current view node, the site map or the menu portlets.

	Note
	For top nodes, the URI and the navigation node name must have the same value. For the other nodes, the URI is composed like <uri>contentmanagement/fileexplorer</uri> where 'contentmanagement' is the name of the parent node and 'fileexplorer' the name of the node (<name>fileexplorer</name>).

You can easily set the visibility of select pages and navigation to certain groups and users. Simply create pages.xml and navigation.xml files in folders named after the group and user to which you want to give permission:

The checkbox allows to say if the nodetype should be considered as a DocumentType. File Explorer considers such nodes as user content and applies the following behavior :

Templates are written using Groovy Templates and will require some experience with JCR API and HTML notions.

Dialogs are groovy templates that generate forms by mixing static HTML fragments and groovy calls to the components responsible for building the UI at runtime. The result is a simple but powerful syntax.

By placing interceptors in your template, you will be able to execute a groovy script just before and just after the node-save. Pre node-save interceptors are mostly used to validate input values and their overall meaning while the post node-save interceptor can be used to do some manipulation or reference for the newly created node such as binding it with a forum discussion or wiki space.

To place interceptors, use the following fragment :

<% uicomponent.addInterceptor("ecm-explorer/interceptor/PreNodeSaveInterceptor.groovy", "prev");%>

Interceptor groovy scripts are managed in the 'Manage Script' section in the ECM admin portlet. They must implement the CmsScript interface. Pre node-save are passed input values within the context :

public class PreNodeSaveInterceptor implements CmsScript {

  public PreNodeSaveInterceptor() {
  }

  public void execute(Object context) {
    Map inputValues = (Map) context;
    Set keys = inputValues.keySet();
    for(String key : keys) {
      JcrInputProperty prop = (JcrInputProperty) inputValues.get(key);
      println("   --> "+prop.getJcrPath());
    }
  }

  public void setParams(String[] params) {}

}

Whereas post node-save one are passed the path of the saved node in the context:

<% uicomponent.addInterceptor("ecm-explorer/interceptor/PostNodeSaveInterceptor.groovy", "post");%>

public class PostNodeSaveInterceptor implements CmsScript {

  public PostNodeSaveInterceptor() {
  }

  public void execute(Object context) {
    String path = (String) context;

    println("Post node save interceptor, created node: "+path);
  }

  public void setParams(String[] params) {}

In the next code sample, each argument is composed of a set of keys and values. The order of the arguments are not important and only the key matters. That example builds a field which has the id "hiddenInput4", which will generate a date which will not be visible. In other words the value of the field will be automatically set to the current date value and no visible field will be printed on the form.

String[] hiddenField4 = ["jcrPath=/node/jcrcontent/jcr:lastModified", "visible=false"];
uicomponent.addCalendarField("hiddenInput4", hiddenField4);

Once the form is saved, that date value will be saved in under the relative JCR path ./exo:image/jcr:lastModified

In many cases, when creating a Node instance out of a form, one must still tell the CMS service about the structure of that node. In other words, the template creator must tell what nodetype is a child of the newly created node or if that current node has any mixin type attributed.

By defining these arguments, the node and its children are created with the correct nodetype and mixintype.

See the following example :

String[] hiddenField = ["jcrPath=/node/jcrcontent", "nodetype=nt:resource", "mixintype=exo:rss-enable", "visible=false"] ;
 uicomponent.addHiddenField("hiddenInput", hiddenField) ; 

In the previous sample, the value was automatically created and set according to the current date. However, it is also possible to set a default value for a field.

Furthermore, as no widget is specified then a text widget is used. The widget will still not be visible.

String[] hiddenField = ["jcrPath=/node/jcrcontent/jcr:mimeType", "image/jpeg"] ;
uicomponent.addHiddenField("hiddenInput", hiddenField) ;

It is possible to create widgets that are non editable (and then only used to print some information). Furthermore, it is possible to tell that a widget should be visible only if its value is not null, in other words when the form is used to edit an already existing node.

String nameArgs[] = ["jcrPath=/node", "mixintype=mix:votable", "visible=if-not-null"];
uicomponent.addMixinField("name", nameArgs ) 

The "What You See Is What You Get" widget is one of the most powerful one. It prints an advanced javascript text editor with many functionalities including the ability to dynamically upload images or flash assets into a JCR workspace and then to reference them from the created HTML text.

String[] fieldSummary = ["jcrPath=/node/exo:summary", "options=basic"] ;
uicomponent.addWYSIWYGField("summary", fieldSummary) ;

The "options" argument is used to tell the component which toolbar should be used.

By default there are two options for the toolbar:

There is also a simple textarea widget:

String [] descriptionArgs = ["jcrPath=/node/exo:title", "validate=empty"];
uicomponent.addTextAreaField("description", descriptionArgs) ;

We also provide a selectbox widget with a simple default mechanism where we can print all the available static options, separated with comma, in the "options" argument of the directive. The argument with no key (here "text/html") is the selected option of the list.

String[] mimetype = ["jcrPath=/node/jcrcontent/jcr:mimeType", "text/html", "options=text/html,text/plain"] ;
uicomponent.addSelectBoxField("mimetype", mimetype) ;

As usual, the value will be stored at the relative path defined by the jcrPath directive argument.

For more example on how to create WCM templates, take a look at the reference guide.

It is important to understand the distinction between Gadgets and Portlets. Portlets are user interface components that provide fragments of markup code from the server-side, while gadgets generate dynamic web content on the client-side. With Gadgets, small applications can be built relatively quickly, and mashed up on the client-side using lightweight Web Oriented Architecture (WOA) technologies, like REST or RSS.

More information about developing gadgets and portlets can be found in the GateIn Reference Guide:

eXo Platform facilitates easy gadget development, via its powerful, web-based IDE. You can learn more about the basic principles of Gadget development at http://code.google.com/apis/gadgets/docs/gs.html.

A Portlet Bridge allows you to create a JSR-168 compliant portlet with very little change to your existing web application.

For example, the JSF Bridge allows you to transparently deploy your existing JSF Applications as a Portlet Application or Web Application.

http://wiki.apache.org/myfaces/PortletBridge

The JBoss implementation of the Portlet Bridge has enhancements to support other web frameworks such as RichFaces and Seam.

http://jboss.org/portletbridge/docs.html

When logging into the portal, users gain access to many systems through portlets using a single identity. However, in many cases the portal infrastructure must be integrated with other SSO enabled systems. There are many different Identity Management solutions available. The GateIn documentation gives detailed configuration for different SSO implementation: http://docs.jboss.com/gatein/portal/3.1.0-FINAL/reference-guide/en-US/html_single/index.html#chap-Reference_Guide-SSO_Single_Sign_On.

Central Authentication Service (CAS) is a Web Single Sign-On (WebSSO), developped by JA-SIG as an open-source project. CAS allows users working on different applications to log-in only once be recognized and authentified by all applications. Details about CAS can be found here http://www.ja-sig.org/products/cas/.

The CAS integration consists of two parts; the first part consists of installing or configuring a CAS server, the second part consists of setting up the portal to use the CAS server.

Read the GateIn documentation for more CAS configuration: http://docs.jboss.com/gatein/portal/3.1.0-FINAL/reference-guide/en-US/html_single/index.html#sect-Reference_Guide-Single_Sign_On-CAS_Central_Authentication_Service.

eXo Portal 3.0 supports Kerberos authentication on a Microsoft Active Directory. You will need to configure both your Active Directory server and the application server.

In this example, we suppose that the complete name of the machine on which Tomcat server runs is ubu.exoua-int, and that it runs on the Linux host (Ubuntu 7.04). This machine must be in a Windows domain.

Our implementation makes it possible to use SPNEGO or NTLM. The client will get two authentication headers 'Negotiate' and 'NTLM' and will use whichever is supported by the browser. In Firefox it is possible to manage authentication types, but it isn't in IE, therefore SPNEGO will be used.

Reference guide for configuring Kerberos SSO: NEED LINK

To specify the initial Organization configuration, the content of yourextension.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 is used to specify a list of membership types, a list of groups, and a list of users to be created.

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>
   </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 exo.platform.services.organization package has five main components: user, user profile, group, membership type and membership. There is an additional component that serves as an entry point into Organization API - OrganizationService component, that provides handling functionality for the five components. For more details, take a look at the GateIn documentation .