Download pulse

Of bundles and components

Aside of the web frameworks core – the container – pulse is organised in bundles and components. Components add new functionalities to pulse in providing additional controllers, joblets (scheduled tasks) and persistent business objects. A bundle – as the name suggests – group the functionalities from one or more components as a part of your website, thus making it available to be used.

:
To put it in a nutshell: components provide capabilities and bundles expose and configure them. Components provide – bundles expose.

How components are organised

All components of pulse consist of three parts:

  • the component's JAR in WEB-INF/lib providing the Java classes
  • the compontent configuration and XSL files in WEB-INF/components in a separate sub-directory with the component's name
  • the public resources such as images, JavaScripts in resources/components in a separate sub-directory with the component's name

Per convention all component names start with a lower case letter as opposed to bundles which start with a capital letter.

Each component is defined within its component.xml. 

<?xml version="1.0" encoding="utf-8"?>
<conf:component xmlns:conf="http://pulse.torweg.org/container">
    <!-- all JPA entities provided by this component -->
    <jpa-entities>
        <entity class="org.torweg.pulse.component.cms.model.CMSContent"/>
        <entity class="org.torweg.pulse.component.cms.model.Page"/>
    </jpa-entities>
    <!-- all packages of this components which are enabled for JAXB, 
        i.e. they contain a "jaxb.index" -->
    <jaxb-endorsed>
        <package>org.torweg.pulse.component.cms</package>
        <package>org.torweg.pulse.component.cms.model</package>
    </jaxb-endorsed>
</conf:component>

The above sample show the component.xml of the CMS component. It defines the JPA entities of the component and its JAXB enabled packages.

''
As long as you do not intend to write your own components you will never have to edit a component.xml.

Inside the xsl sub-folder you can find all the layout templates required for the current component. The main entry point, when adapting a layout will always be main.xsl.

Within resources/components you can find all icons required by the components. Sometimes there are also additional JavaScript files used to enhance the UI provided by the default layout included of the component.

Configuring a bundle

The configurations for each bundle reside in WEB-INF/bundles within a directory with the bundle's name. Per convention bundle names always start with a capital letter.

Bundles expose the capabilities of one or more components to the extend you wish to use them in your pulse installation. 

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
    <!-- classes with "web methods" -->
    <controllers>
...        
    </controllers>

    <!-- mapping contents to their administrative controllers -->
    <content-mappings>
...
    </content-mappings>
    <!-- automated jobs of the bundle -->
    <joblets>
...
    </joblets>
</bundle>

The above shows a skeleton bundle configuration to be found in the bundle.xml of each individual bundle. Let's go through each of the three sections in a bit more detail:

  • controllers: lists all controllers exposed by the current bundle
    <controller class="org.torweg.pulse.component.core.site.search.SearchSiteSuggestions"/>
<controller class="org.torweg.pulse.component.core.RuleBasedRedirector" alwaysRun="pre"/>
<controller class="org.torweg.pulse.component.core.site.ThemesController" alwaysRun="post"/>
    The above sample shows all variations of controller exposition. The SearchSiteSuggestions are configured as a default controller acting only if one of its web methods is request, i.e. methods annotated with an @Action annotation.
    The RuleBasedRedirector is configured as a so-called always-run-controller, i.e. controller which are processed on each request regardless of any @Action annotated web method being requested. During the always-run execution, all methods annotated with the @AnyAction annotation are executed.
    The alwaysRun attribute specifies how the always-run execution shall take place: "pre" causes these methods to be executed prior to any requested method within the same bundle, whereas "post" executes the methods after the requested web method or not all, if the web methods issued a StopEvent.
  • content-mappings: maps different content types (i.e. subclasses of Content) to their administrative counterparts. You should stick to the defaults provided by the distribution here.
  • joblets: defines the automated jobs of the bundle, i.e. timer based tasks (much like Unix cronjobs) running in the applications context 
    <!-- cleans old search suggestions and failures from Hibernate -->
<joblet class="org.torweg.pulse.component.core.site.search.SearchSiteJoblet">
    <!-- run every day at 1:30am -->
    <cron-expression>0 30 1 * * ?</cron-expression>
</joblet>
    Each joblet is configured with a cron-expression defining the execution intervals. For more information on cron-expressions see the Quartz scheduler documentation.

Just like components, bundles also have room for additional XSL files in WEB-INF/bundles/{bundlename}/xsl and additional resources in resources/bundles/{bundlename}.

Configurations of Controllers and Joblets

Each configurable controller exposed or joblet scheduled by a bundle has its configurations residing directly next to bundle.xml. The configurations are named after the full qualified class name of the resource configured. More information on the configurations and the controllers/Joblets configured can be found in our JavaDoc.