Download pulse

The main configuration – pulse.xml

The central configuration of the system is located in WEB-INF/conf/pulse.xml. Let’s go through the configuration from bottom to top:

Reload interval:

<!-- Configure the pulse container for automatic reloading.
     The reload interval is given in milliseconds. An interval
     of 0 (zero) milliseconds turns off automatic reloading. -->
<reload-interval>10000</reload-interval>

The reload interval is given in milliseconds and defines the interval in which pulse checks for updated configuration and template files.

HTTP ports, TLS and server salt

<!-- if tls-available is 'true', you can set the weakest allowed security setting by
     adding weakest-level="NONE|KEEP|ALWAYS" -->
<security tls-available="false" secure-port="443" default-port="80" weakest-level="NONE"
    server-salt="changeMeOnInstall"/>

The <security/> element defines whether TLS/SSL is available for the installation and the ports for HTTP and HTTPS. The optional "weakest-level" attribute allows to set the weakest connection security level:

  • NONE: allow changing back to HTTP even if previous request have been on HTTPS (default)
  • KEEP: once switched to an HTTPS connection, do not fall back to plain HTTPS
  • ALWAYS: force HTTPS for all requests

For more information on the security level take a look at the @Action annotation JavaDoc. The "server-salt" sets a server-wide salt to be used in hash functions (e.g. the different digest methods in StringUtils).

Versioning prefix (to allow far future expiration headers):

<versioning-prefix>__v</versioning-prefix>

The versioning prefix is used to prefix paths inside the webapp with a version specific path element. This makes it easy to force clients to update files even though far future expiration headers are used. See also WEB-INF/web.xml for the configuration of the filter and WEB-INF/xsl/globals.xsl to see how the prefix is used for path building ($path.webapp).

Service request implementation and execution framework:

<service-request class="org.torweg.pulse.service.request.ServiceRequestImpl"/>
<invoker class="org.torweg.pulse.invocation.BundleInvoker"/>

The next two settings <service-request/> and <invoker/> set up the internal implementations for the request and execution framework. Usually you will not want to make any changes here unless you are an absolute expert.

The geo-location provider:

<geo-location-provider class="org.torweg.pulse.util.geolocation.GeoIPLocationProvider"/>

Different tasks in pulse require geo-locations. The provider for geo-loactions is set up in <geo-location-provider/>. Pulse is delivered with two implementations:

Other implementations can be easily added by implementing the org.torweg.pulse.util.geolocation.IGeoLocationProvider interface.

The CAPTCHA adapter:

<captcha-adapter class="org.torweg.pulse.util.captcha.ReCaptchaAdapter"/>

Integrates pulse with reCAPTCHA.

FOP configuration location to enable pulse for XSL-FO:

<!-- 
    fop-directory, specifies location of fop.conf.xml
    also this is being used as base-path & font-base-path
    required [false]
-->
<fop-directory>WEB-INF/fop</fop-directory>

Pulse contains Apache FOP to render PDF documents. This setting gives the location for the Apache FOP configuration file fop.conf.xml and is also being used as the Apache FOP base-path and font-base-path. Pulse is delivered with a sensibly preconfigured version of Apache FOP. To learn more on how you can customise Apache FOP take a look on the FOP website: http://xmlgraphics.apache.org/fop/1.0/configuration.html

The mail queue of the container:

<mail-queue>
    <protocol>smtp</protocol>
    <server port="25">localhost</server>
    <!--
    <user>mail-user</user>
    <password>pass</password>
    <temporary-directory>/tmp</temporary-directory>
    -->
</mail-queue>

Pulse has its own internal mail queue which is responsible for sending e-mails. The settings above define the necessary parameters for the mail queue to actually connect with the sending MTA. Currently supported protocols for sending are SMTP and IMAP.

The virtual file system:

<virtual-file-system>
    <provider realm="public" class="org.torweg.pulse.vfs.providers.SingleFileSystemProvider">
        <!-- relative paths will be resolved against the webapp root -->
        <base-path uri="WEB-INF/vfs-public"/>
        <http-base-path uri="/site/vfs-public"/>
    </provider>
    <provider realm="private" class="org.torweg.pulse.vfs.providers.SingleFileSystemProvider">
        <base-path uri="WEB-INF/vfs-private"/>
        <http-base-path uri="/site/vfs-private"/>
    </provider>
</virtual-file-system>

The above section configures the virtual files system of pulse (VFS). The current VFS needs two realms to be configured: public and private. At this time there exists only one VFS provider (SingleFileSystemProvider). Other providers might be added in the future. Each realm must know its base-path in the file system and its base path for HTTP based access. Note that if you change the http-base-path you will also have to adjust the mount points of the VFSServlet in WEB-INF/web.xml. For more information on the VFS take a look at the JavaDoc.

The virtual file system’s in memory cache:

<cache vfs-cache-enabled="true">
    <max-file-size kBytes="350"/>
    <!-- 50 MB -->
    <max-cache-size kBytes="51200"/>
    <max-inactive timespan="3m"/>
</cache>

To speed up the delivery of common (and small files) the VFS has an in memory cache.
The max-file-size defines the upper file size limit for virtual files to be cached. The max-cache-size gives the maximum amount of RAM to be used by the cache. And the max-inactive setting gives the maximum timespan a cached file may be idle before being purged from the cache.

The Hibernate configuration:

The next section of the pulse.xml contains the container's Hibernate configuration setting up the JPA2 environment. It basically consists of two parts, where the first part configures Hibernate and the second part adds the containers core entities to the session factory.

The structure is equivalent to a stand-alone Hibernate configuration, so you can find very detailed information on all the available options at the Hibernate website.

  1. The Hibernate properties:
       <hibernate-configuration>
            <session-factory>
    
    ...            
                <!--  -->
                <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
                <property name="connection.url"
                    >jdbc:mysql://localhost:3306/pulsehp?autoReconnect=true&amp;characterEncoding=UTF-8</property>
                <property name="connection.username">root</property>
                <property name="connection.password">pass</property>
                <!--  -->
                <!-- use c3p0 -->
                <property name="connection.provider_class"
                    >org.hibernate.connection.C3P0ConnectionProvider</property>
                <property name="hibernate.c3p0.min_size">0</property>
                <property name="hibernate.c3p0.max_size">30</property>
                <property name="hibernate.c3p0.timeout">3000</property>
                <property name="hibernate.c3p0.max_statements">500</property>
                <property name="hibernate.c3p0.idle_test_period">10</property>
                <!-- SQL dialect -->
                <property name="hibernate.dialect"
                    >org.torweg.pulse.util.MySQL5InnoDBDialectUTF8</property>
                <!-- Echo all executed SQL to stdout -->
                <property name="show_sql">false</property>
                <!-- Drop and re-create the database schema on startup -->
                <property name="hbm2ddl.auto">update</property>
                
    ...
    
                <!-- hibernate search -->
                <property name="hibernate.search.index.directory_provider"
                    >org.hibernate.search.store.FSDirectoryProvider</property>
                <property name="hibernate.search.default.indexBase"
                    >WEB-INF/hibernate-search</property>
    
    ...
    
    	</session-factory>
    
    </hibernate-configuration>
    
    The default configuration sets up pulse with a locale MySQL database with a webapp specific connection pool using c3p0 (maximum size of 30 connections) using the included MySQL dialect of pulse (which forces InnoDB usage and UTF-8 charset with a collation of utf8_bin which is strongly recommended for MySQL). It also configures Hibernate Search to store its Lucene indexes for the site-wide full-text search inside the webapp at WEB-INF/hibernate-search.
    In depth information on how you can setup Hibernate can be found in the Hibernate configuration manual.
  2. The JPA entities of the container:
       <hibernate-configuration>
            <session-factory>
    
    ...            
    
               <!--
                    core entity mappings
                    =========================================================
                -->
                <!-- Bundle -->
                <mapping class="org.torweg.pulse.bundle.Bundle"/>           
                
    ...            
    
                
            </session-factory>
    
    </hibernate-configuration>
          
    You will not want to make any changes here.

The JAXB enabled packages of the container:

<jaxb-endorsed>
    <package>org.torweg.pulse.accesscontrol</package>

...

    <package>org.torweg.pulse.vfs</package>
    <package>org.torweg.pulse.vfs.filebrowser</package>
    <package>org.torweg.pulse.webdav.util</package>
</jaxb-endorsed>

This part of the configuration enumerates the JAXB enabled packages of the container.
Unless you start to contribute to the pulse container, you will never have to change anything here.

The joblet scheduler:

<joblet-scheduler-configuration>
    <scheduler-factory>
        <property name="org.quartz.threadPool.class">org.quartz.simpl.SimpleThreadPool</property>
        <property name="org.quartz.threadPool.threadCount">5</property>
    </scheduler-factory>
</joblet-scheduler-configuration>

This sets up the the pulse joblet scheduler which is built upon the Quartz Scheduler. Basically this is an embedded configuration for the scheduler which should be sensible for most installations. For more information on configuring the scheduler take a look at the Quartz documentation.