2.1.1. Portal extension mechanism

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

Technically, the eXo Kernel provides an extensibility mechanism that extends the portal container configurations. This extensibility mechanism allows more services and resources to be loaded at start-up. In other words, thanks to the extensibility mechanism, you can extend the portal resources in an almost plug-and-play fashion - simply by dropping in a .war archive with the resources, and configuring its position on the portal's classpath.

Note

With this way, customization of the portal does not involve unpacking and repacking the original portal's .war archives. Instead, you can override a portal resource by including it in your extension in the same path as that of portal.war.
In case many extensions include a same resource, they override each other too. So, take care that only the last loaded one will take effect.

See the following diagram for how the portal extensions work:

Tip

In this diagram, configuration.xml is packaged in a jar archive. This structure is applied by many add-ons, because the jar often contains also service classes and other resources. If the jar is supposed to contain only configuration.xml, you can include configuration.xml in the war instead, to make the package simpler. See details below.

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 webapp portal.war is the base that can be overridden by other extensions.

The 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 portal.war.
Note
This is valid only for resources but not for Java classes.
A unified ServletContext: Any web resources contained in your custom-extension.war will be accessible from /portal/ uri.

When you are extending an existing portal container, the name of the portal in the extension's configuration should be the same as that of the existing portal container. By using this approach, the configuration (and many other aspects) of an existing portal container can be customized, for example, Groovy templates of portlets, porlet skins, CSS and Images, navigations and pages or localizations.

Servlets and Servlet Filters in a portal extension

If you ship servlets or servlet filters as part of your portal extension, and these servlets/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 look for resources in associated web applications in the order specified by dependencies configuration.

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

New extension mechanism as of Platform 4.3

Before Platform 4.3, you have to place configuration.xml (that declares your extension) in a jar archive, at:

your.jar!/conf/configuration.xml

As of Platform 4.3 (eXo Kernel 2.5), you have one more option to place that file in the .war itself, at:

your.war!/META-INF/exo-conf/configuration.xml

The benefit is you can remove the jar if it does only one thing: to configure the extension.

References

To deeply understand the extension mechanism, you should read the Kernel reference about services, containers and configuration: