Java Server APIs

The essential interfaces and classes in the backend API:

API framework overview

See also full API Javadoc.

App framework

  • Main interface for apps. Apps are started and managed by

  • Describes an app.

  • Represents a view open in a tab within an app.

  • Describes a subapp.

  • Provides functionality used by an app to interact with the Magnolia shell.

    • sendLocalMessage(Message message). Sends a message to the current user.

    • sendUserMessage(String user, Message message). Sends a message to a named user.

    • broadcastMessage(Message message). Sends a message to all users.

  • Provides functionality used by a sub app to interact with the Magnolia shell.

  • Extends the BaseApp with the ability to open a choose dialog.

  • info.magnolia.ui.contentapp.browser.BrowserSubApp. Base implementation of a content subApp.

  • info.magnolia.ui.contentapp.browser.BrowserSubAppDescriptor. Describes a browser subapp.

  • info.magnolia.ui.contentapp.detail.DetailSubApp. Base implementation of an item subApp.

  • info.magnolia.ui.contentapp.detail.DetailSubAppDescriptor. Descriptor for Item subApps. Holds the form definition to build a form and needed fields to create a new node.

UI framework

The UI Framework is a collection of components for building the user interface in apps.

UI context

  • info.magnolia.ui.api.context.UiContext. Represents a UI context and allows components, views and presenters to interact with the context that contains them.


  • info.magnolia.ui.contentapp.configuration.WorkbenchDefinition. Defines a workbench. Contains all elements that define a workbench configuration.

  • info.magnolia.ui.contentapp.configuration.ContentViewDefinition. Displays content in the workbench.

  • info.magnolia.ui.contentapp.browser.TreePresenter. Responsible for creating, configuring and updating a tree of items according to the workbench definition.

  • info.magnolia.ui.contentapp.browser.ListPresenter. Responsible for creating, configuring and updating a list of items according to the workbench definition.

  • info.magnolia.ui.contentapp.browser.ThumbnailPresenter. Responsible for creating, configuring and updating a thumbnail grid of items according to the workbench definition.

  • info.magnolia.ui.contentapp.configuration.column.ColumnDefinition. Defines a column in the workbench.


  • info.magnolia.ui.api.action.Action. An action is executed in response to user interaction with the UI. For instance clicking on an item in a menu.

  • info.magnolia.ui.api.action.ActionDefinition. Action definitions are used to configure actions in many parts of the UI. The definition holds a name which is used to identify the action within a certain scope, for instance within a sub app.

Action bar

  • info.magnolia.ui.actionbar.definition.ActionbarDefinition. The definition for an action bar, made of sections and groups of actions.


  • info.magnolia.ui.editor.FormDefinition. Defines a form.

  • info.magnolia.ui.framework.layout.TabDefinition. Defines a tab within a form. Holds a list of fields contained in this tab.

  • info.magnolia.ui.field.FieldDefinition. Defines a field within a dialog.

  • info.magnolia.ui.field.FieldFactory. Responsible for creating Vaadin fields based on their FieldDefinition.

  • info.magnolia.ui.field.FieldValidatorDefinition. Defines a validator for field values.

Location and navigation

  • info.magnolia.ui.api.location.Location. Represents a location within the application, such as the open view and the selected item.

  • info.magnolia.ui.api.location.LocationController. Manages the user’s location in the application and controls location changes.


  • Decouples the presenters and the Vaadin application. Provides methods to show messages and configuration dialogs.


  • info.magnolia.ui.api.message.Message. Models a message.

  • info.magnolia.ui.framework.message.MessagesManager. Manages user messages.


  • info.magnolia.event.EventBus. Fires events to a set of registered handlers.

  • info.magnolia.ui.api.event.ContentChangedEvent. Event fired when content is changed in a workspace. Holds an itemId of an item that is related to the changes made. If the change was a deletion the itemId is the parent of the deleted item. If something was added the itemId is for the new item.


Context is an abstraction layer representing the environment of the current process which can be a request process, a scheduled task or a command execution in the workflow. The context provides access to the most important components such as hierarchy managers jcr session, current user, context attributes and parameters, response object and so on. The context is initialized at the beginning of each process. Context attributes will have a different meaning based on the environment. In case of a request, the attributes are request attributes and request parameters. Magnolia implements context using a thread-local class.

  • info.magnolia.context.MgnlContext. This static helper class is the programmer’s entry point to work with the current context.

    • getInstance() Returns the current context.

    • getUser() Returns the current user.

    • getJCRSession(String workspacename). Returns a JCR session to the provided workspace.

    • getAttribute(name) Returns a named context attribute. In case of a request, this can be a request parameter, request attribute or session attribute.

    • getWebContext() Returns the Web context if the current thread is processing a request.

    • getAggregationState().

  • info.magnolia.context.WebContext. Context interface specialized for servlet requests; knows about HttpServletRequest and HttpServletResponse. Should be used as little as possible as it makes the calling code dependent on the servlet API. Use MgnlContext instead if possible.

    • getRequest() Returns the current servlet request object.

    • getResponse() Returns the current servlet response object.

  • info.magnolia.cms.core.AggregationState. Contains information about the current request and rendering process. It is initialized by the ContentTypeFilter.

    • getOriginalURI() Original URI is the URI as requested by the client.

    • getCurrentURI() URI as mapped by Magnolia at a given point in processing. This value is for instance changed by the i18n filter, virtual URI mapping etc.

    • getMainContentNode() The content with which we start the rendering process. In general this is the page node.

    • getCurrentContentNode() The content that is processed at the moment. First this is typically the page, then a component and so on.

Rendering and templating

  • info.magnolia.rendering.engine.RenderingEngine. Entry point for the rendering.

    • render(javax.jcr.Node content, OutputProvider out). Renders the content with its assigned template.

    • render(javax.jcr.Node content, RenderableDefinition definition, Map<String,Object> contextObjects, OutputProvider out). Uses a specific RenderableDefinition to render the content and exposes the given context objects to the template script.

  • info.magnolia.rendering.template.RenderableDefinition. Abstract rendering definition used for templates and components.

    • getName(). Name of the template definition.

    • getRenderType(). Defines the renderer to use (for instance, FreeMarker).

  • info.magnolia.rendering.template.TemplateDefinition. A RenderableDefinition which supports editing in the page editor and can define their areas.

    • getDialog()

  • info.magnolia.rendering.template.AreaDefinition

  • info.magnolia.rendering.model.RenderingModel. The model used in the rendering process. It is instantiated for each rendering and ties the current content and rendering definition together. Concrete classes provide helper methods used in the template script. The execute method is executed before the rendering starts, a useful place to execute any business logic. The model is available in the template script under the named model.

    • getParent(). Parent model most often used for page rendering.

    • getNode(). The content node tied to this model.

    • getContent(). Map representation of the content node tied to this model.

    • getDefinition(). The renderable (template, area or component) tied to this model.

    • execute(). Called after all properties were set.

  • info.magnolia.rendering.renderer.Renderer. Responsible for generating the actual response from request data and a template. You can bind a specific implementation to a template type.

    • render(RenderingContext ctx, Map<String,Object> contextObjects). Called by RenderingEngine after it has setup the RenderingContext.

  • info.magnolia.rendering.context.RenderingContext. Provides all information needed in the rendering process.

  • info.magnolia.jcr.util.ContentMap. Map based representation of JCR content. This class is used in template scripts to allow notations like content.<property name>. It first tries to read a property with name (key) and, if not present, checks for the presence of a child node. Special property names map to JCR methods:

    • @name

    • @id

    • @path

    • @level

    • @nodeType

  • Templating functions

  • info.magnolia.templating.functions.TemplatingFunctions. An object that exposes methods useful for templates. The object is exposed to template scripts as cmsfn.

    • children(javax.jcr.Node content)

    • parent(javax.jcr.Node content)

    • isEditMode()

    • isPublicInstance()

    • language()

  • info.magnolia.cms.util.LinkUtil. Utility methods for link transformations and handling.

    • createLink(javax.jcr.Node node)

    • createAbsoluteLink(javax.jcr.Node node)

    • makePathRelative(String url, String absolutePath)

  • Site configuration Java bean. Default site configuration merged with the user-defined site.

    • getI18n()

    • getTheme()

    • getVariations()


  • info.magnolia.commands.CommandsManager

  • info.magnolia.commands.chain.Command

Filter chain

  • info.magnolia.cms.filters.MgnlFilter. Interface for filters managed by Magnolia, exposing support for the bypass mechanism.

  • info.magnolia.cms.filters.AbstractMgnlFilter. A Magnolia filter configured in the config repository. This filter is bypassable.

Module management

  • info.magnolia.module.ModuleRegistry. Holds instances and definitions of modules.

  • info.magnolia.module.ModuleVersionHandler. Provides deltas to be applied to install/update/uninstall modules. A module that needs to handle its own install/updates should provide an implementation of this interface.

  • info.magnolia.module.ModuleLifecycle. Manages the lifecycle of an installed instance of a Magnolia Module. Implementing this interface is optional.


Magnolia relies on the Apache Jackrabbit JCR API to manage its data, with security handled by JCR.

See the JCR API page for more details.


DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.