2.1.1. Portal extension mechanism

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 in a .jar archive.

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:

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.