eXo Platform 3.5

## Chapter 2. Get Started

This chapter will provide you the basic knowledge of eXo Platform 3.5 through the following topics:

- Glossary

- Set up Maven settings

- eXo Architecture Primer

## Glossary

This section gives you explanations of some technical terms which are used throughout the documentation.

Container templates

Templates which are used to contain the UI components in a specific layout and display them on the portal page.

ConversationState

An object which stores all information about the state of the current user. This object also stores acquired attributes of an Identity which is a set of principals to identify a user.

Data container

An object which implements the physical data storage. It enables different types of backend (such as RDB, FS files) to be used as a storage for the JCR data. With the main Data Container, other storages for persisted Property Values can be configured and used. The eXo JCR persistent data container can work in two configuration modes.

- Multi-database: A database for each workspace (used in the standalone eXo JCR service mode).

- Single-database: All workspaces persisted in one database (used in the embedded eXo JCR service mode; for example in eXo portal).

The data container uses the JDBC driver to communicate with the actual database software. For example, any JDBC-enabled data storage can be used with the eXo JCR implementation.

Database Creator (DBCreator)

A service that is responsible for executing the DDL (Data Definition Language) script in runtime. A DDL script may contain templates for database name, username, and password which will be replaced by real values at execution time.

Drives

Customized workspaces which include:

- a configured path where the user will start when browsing the drive.

- a set of views with limitations to available actions, such as editing or creating contents while being in the drive.

- a set of permissions to limit the access (and view) of the drive to a restricted number of people.

- a set of options to describe the behavior of the drive when users browse it.

eXo Cache

One which all applications on the top of eXo JCR need. This can rely on an org.exoplatform.services.cache.ExoCache instance managed by org.exoplatform.services.cache.CacheService.

eXoContainer

An object which behaves like a class loader that is responsible for loading services/components. The eXoContainer class is inherited by all the containers, including RootContainer, PortalContainer, and StandaloneContainer. It itself inherits from a PicoContainer framework which allows eXo to apply the IoC Inversion of Control principles.

External Plugin

One which allows adding configuration for services and components easily.

Folksonomy

A system of classification which is derived from the practice and a method of collaboratively creating and managing tags to annotate and categorize content. This practice is also known as collaborative tagging social classification social indexing and social tagging. For more details, see: http://en.wikipedia.org.

Gadgets

Web-based software components which are based on HTML, CSS, and JavaScript. They allow developers to easily write useful web applications that work anywhere on the web without modification. For more details, see: opensocial.org.

Groovy template

A template which is widely used in eXo UI framework. It leverages the usage of Groovy language, a scripting language for Java. The template file consists of HTML code and Groovy code blocks.

JCR WebDav

A service that allows accessing a JCR repository via WebDav.

JobSchedulerService

One which defines a job to execute a given number of times during a given period. It is a service that is in charge of unattended background executions commonly known for historical reasons as batch processing.

JodConverter (Java OpenDocument Converter)

A tool which converts documents into different office formats and vice versa.

JCR Item

One which may be a node or a property.

ListenerService

An event mechanism which allows triggering and listening to events under specific conditions inside eXo Platform. This mechanism is used in several places in eXo Platform, such as login/logout time, creating/updating users, and groups.

LockManager

One which stores lock objects, so it can give a lock object or can release it. Also, LockManager is responsible for removing Locks that live too long.

Namespace

The name of a node or property which may have a prefix delimited by a single ':' colon character. This name indicates the namespace of the item (Source: JSR-170) and is used to avoid the naming conflict.

Navigation node

A node which looks like a label of the link to page on the Navigation bar. By clicking a node, the page content is displayed. A node maps a URI and a portal page for the portal's navigation system.

Navigation

One which looks like a menu which is to help users visualize the site structure and to provide hyperlinks to other parts on a Portal. Thus, a bar which contains navigations is called the Navigation bar.

Node type

One which defines child nodes and properties which a node may (or must) have. Every node type has attributes, such as name, supertypes, mixin status, orderable child nodes status, property definitions, child node definitions and primary item name (Source: JSR-170).

Node

An element in the tree structure that makes up a repository. Each node may have zero or more child nodes and zero or more child properties. There is a single root node per workspace which has no parent. All other nodes have only one parent.

Organization listener

One which provides a mechanism to receive notifications via an organization listener, including UserEventListener, GroupEventListener and MembershipEventListener.

- UserEventListener is called when a user is created, deleted or modified.

- GroupEventListener is called when a group is created, deleted or modified.

- MembershipEventListener is called when a membership is created or removed.

Organization management

A portlet that manages users groups and memberships. This portlet is often managed by administrators to set up permission for users and groups.

OrganizationService

A service that allows accessing the Organization model. This model is composed of users, groups, and memberships. It is the basis of eXo's personalization and authorizations and is used for all over the platform.

Path constraint

One which restricts the result node to a scope specified by a path expression. The following path constraints must be supported exact child nodes descendants and descendants or self (Source: JSR-170).

Permission

A permission settings control which actions users can or cannot perform within the portal and are set by the portal administrators. Permission types specify what a user can do within the portal.

Portal Page

A page which consists of one or more various portlets. Their layouts are defined by container templates. To display a portal page, this page must be mapped to a navigation node.

Portal skins

Graphic styles which display an attractive user interface. Each skin has its own characteristics with different backgrounds, icons, color, and more.

PortalContainer

A type of container which is created at the startup of the portal web application in the init method of the PortalController servlet.

Portlet

A web-based application that provides a specific piece of content to be included as part of a portal page. In other words, portlets are pluggable user interface components that provide a presentation layer to information systems. There are two following types of portlet:

- Functional Portlets support all functions within the portal. They are integrated into the portal that can be accessed through toolbar links.

- Interface Portlets constitute the interface of a portal. eXo Portal consists of some Interface Portlets, such as Banner Portlet, Footer Portlet, Homepage Portlet, Console Portlet, Breadcrumb Portlet and more.

Property constraint

One which may be specified by a query on the result nodes by way of property constraints (Source: JSR-170).

Property

An element in the tree structure that makes up a repository. Each property has only one parent node and has no child node.

Repository

One which holds references to one or more workspaces.

eXo REST framework

One which is used to make eXo services (for example, the components deployed inside eXo Container) simply and transparently accessible via HTTP in a RESTful manner. In other words, those services should be viewed as a set of REST Resources-endpoints of the HTTP request-response chain. Those services are called ResourceContainers.

RootContainer

A base container which plays an important role during the startup. However, it is recommended that it should not be used directly.

RTL Framework (Right To Left Framework)

A framework which handles the text orientation depending on the current locale settings. It consists of four components, including Groovy template, Stylesheet, Images, and Client java.

StandaloneContainer

One which is a context independent eXo Container. It is also used for unit tests.

Taxonomy

One which is used to sort documents to ease searches when browsing documents online.

Tree structure

One structure which is defined as a hierarchical structure with a set of linked nodes and properties.

Type constraint

One which specifies the common primary node type of the returned nodes plus possibly additional mixin types that they also must have. Type constraints are inheritance-sensitive in which specifying a constraint of node type x will include all nodes explicitly declared to be type x and all nodes of subtypes of x (Source: JSR-170).

Web Content

A textual, visual or aural content that is encountered as part of the user experiences on a website. It may include other things, such as texts images, sounds, videos, and animations.

Workspace

A container of single rooted tree which includes items.

## Set up Maven settings

Before setting up a complete project/extension, you need to have knowledge of how to install a Maven project.

Requirements

- JDK (Java Development Kit) 6.0

- SVN 1.6+

- Maven 2.2.1+

- Tomcat 6.0.32 or JBoss EAP 5.1.1

Install and configure Maven

You need to add a system environment variable MAVEN_OPTS (it could be in a .profile startup script on Linux/MacOS operating systems or in the global environment variables panel on Windows).

- Windows:

    set MAVEN_OPTS=-Xshare:auto -Xms128M -Xmx1G -XX:MaxPermSize=256M

- Linux/MacOS:

    export MAVEN_OPTS="-Xshare:auto -Xms128M -Xmx1G -XX:MaxPermSize=256M"

Maven settings

1. Save the settings.xml file to the HOME/.m2/settings.xml path.

2. Edit and change the local-properties profile, including:

- exo.projects.directory.dependencies contains the application servers, and Openfire.

- each exo.projects.app.AS-NAME.version contains the name and version of the application servers.

### Note

If the settings.xml file has been existing, you can merge them. You will need the followings:

- The local-properties profile, which defines properties, is used to build application server distributions of our products.

- The repository to download our dependencies.

In Linux environments, the ulimit limits the system-wide resource used. When running eXo Platform, you may get the error message about "Too many open files" because the ulimit had limited the opened files. By default, the number of open files is limited to "1024". You should execute the command "ulimit n 8196" as root before starting the server to avoid this issue.

### Note

`See also`

Create your extension project

[Create a custom look and feel|#DEV.CreateYourOwnPortal.CreateCustomLookAndFeel

## eXo Architecture Primer

This section aims at helping readers further understand about the eXo architecture, including Kernel, GateIn extensions and Java Content Repository via concepts, services, configuration, and more. In this section, the sub-topics will be covered:

Kernel

- Containers

- Services

- Service configuration

- Plugins

- Configuration loading sequence

GateIn extensions

- Default Portal Container

- Register Extension

Java Content Repository

- Repositories and workspaces

- Tree structure: working with nodes and properties

### Kernel

All eXo Platform 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 the dependency injection. The container is responsible for loading services/components.

This part introduces concepts of Container and Services with an overview before configuring basic services.

#### Containers

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

    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)

#### Services

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

- 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 where the term "component" is often used instead of service.

For example, in the /lib folder, you can find services for the following databases, caching, and 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

#### Service configuration

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.

##### Kernel XML Schema

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

    <configuration xmlns="http://www.exoplatform.org/xml/ns/kernel_1_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_1.xsd http://www.exoplatform.org/xml/ns/kernel_1_1.xsd">

    </configuration>

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.

##### Components

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

For example, open the /webapps/exo-wcm-core/WEB-INF/conf/wcm-core/core-services-configuration.xml. You will see the following code:

        <component>

            <key>org.exoplatform.services.cms.CmsService</key>

            <type>org.exoplatform.services.cms.impl.CmsServiceImpl</type>

        </component>

Each component has a key which matches with 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.

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

###### Value-param

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

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

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

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

      }

    }

###### Object-param

For the object-param component, you can look at the LDAP 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>

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

    package org.exoplatform.services.ldap.impl;

    public class LDAPServiceImpl implements LDAPService {

      // ...

      public LDAPServiceImpl(InitParams params) {

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

        ...

      }

      // ...

    }

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.

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

      // ...

    }

###### Rest of parameter types

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

#### 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 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 org.exoplatform.services. cms.categories.impl.TaxonomyPlugin type.

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

#### Configuration loading sequence

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

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

Configurations for the RootContainer are loaded first, and then for 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 which points to the folder containing external configuration files 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 "portal" is unique.

### GateIn extensions

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. That is, you can inherit resources and configurations from existing web archives, then simply add extra resources and configurations to your extension, and override ones which need to be changed by including modified copies.

### Note

Starter is a web application which has been added to create and start all the portal containers once all the other web applications have already been started. Generally, each web application of a portal container defines several things, such as skins, JavaScripts, Google gadgets and configuration files, at its startup, so the loading order is important. For example, at startup of the web application 1, skins or configuration files or JavaScripts are defined that could depend on another JavaScript from the 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.

If you ship servlets or servlet filters as part of your portal extension, and these servlets/servlet filters need to access specific resources of a portal during the process of the servlets or filters request, make sure that these servlets/filters are associated with the current portal container. The proper way to do that is making your servlet extend the 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 servlets or servlet filters which looks for resources in associated web applications in the order specified by dependencies configuration.

As similar to filters, make sure that your filter class extends org.exoplatform.container.web.AbstractFilter. Both AbstractHttpServlet and AbstractFilter have the method named getContainer(), which returns the current PortalContainer.

#### Default Portal Container

eXo Platform comes with a pre-configured PortalContainer named "portal". The configuration of this portal container ties the core and the 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. With this feature, you only need to make your desired modifications on your extension, but NOT on the portal.war. As a result, your upgrades will become simple as your extension.war is totally independent of the portal.war.

This extensibility is achieved via 2 advanced features of the PortalContainer:

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

- A unified ServletContext: any web resources contained in your extension.war will be accessible from /portal/ uri.

For more details on how to make a simple extension for a "portal" container, see the Register Extension section.

#### Register Extension

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.

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:

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

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

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

### Java Content Repository

All data of eXo Platform are stored in a Java Content Repository (JCR). JCR is the Java specification (JSR-170) for a type of Object Database tailored to the storage, searching, and retrieval of hierarchical data. It is useful for the content management systems, which require storage of objects associated with metadata. The JCR also provides versioning, transactions, observations of changes in data, and import or export of data in XML. The data in JCR are 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.

#### Repositories and workspaces

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

Access the repository's content from a service

1. Get the session object.

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

i. Obtain the javax.jcr.Repository object via one of the following ways:

The first way

Call the getRepository() method of RepositoryService.

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

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

The second way

Call the getCurrentRepository() method, especially when you plan to use a single repository which covers more than 90% of usecases.

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

The third way

Using JNDI as specified in JSR-170.

    Context ctx = new InitialContext();

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

ii. Log in the server to get a Session object by either of two ways:

The first way

Create a Credential object, for example:

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

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

The second way

Log in the server without using a Credential object.

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

This way is only applied when you run an implementation of eXo Platform. The eXo Platform 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.

### Note

There are some JCR Session common considerations as follows:

Because javax.jcr.Session is not a safe object of thread, it is recommended that you should not share it between threads.

Do not use the 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 mixings.

2. Retrieve your node content of the session object.

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

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

#### Tree structure: working with nodes and properties

Every node can only have one primary node type. The primary node type defines names, types and other characteristics of the properties, and the number of its allowed child nodes. 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 from an existing node.

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