Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
945 lines (835 sloc) 81.4 KB

Configuring Hermes

Introduction

This document acts as a configuration reference for Hermes. The configurations of Hermes are specified by various XML-based configuration files. By modifying these files, administrators or developers can configure all the settings such as the location of the message database and log file locations.

The intended audience of this document includes system administrators, application developers and plugin developers of the Hermes system. It assumes the audience has some background knowledge of the following:

  • Java Standard Edition
  • XML
  • AS2
  • ebXML Messaging Services
  • Public Key Infrastructure
  • Application server compliant to Servlet 2.x specification
  • Databases

Overview on loading property files

Hermes has employed a module-group-component architecture where you can define your own module for each application. You can then assign a property file for each component and the Hermes Core System will load them.

There are two loading mechanisms, one for the core system and one for the plugins. The two are almost identical except for their initial definitions.

Let's take a look at how the core system modules are loaded.

/_static/images/2-overview-1.jpeg

For the core system, Hermes will look for the existence of a file named :file:`sys.properties` from the classpath which contains the location of the module-group definition file. E.g.,

:file:`sys.module.group=doc-processor.module-group.xml`

From there, the system will look for the specified XML file and load up the modules specified within. The modules could be System Modules, which contain infrastructure components such as logging and database access, or they could be Active Modules, which perform business functions such as sending messages.

<module id="piazza.corvus" name="Piazza Corvus" version="1.0">
  <component id="logger" name="System Logger">
    <class>hk.hku.cecid.piazza.commons.util.LoggerLog4j</class>
    <parameter name="config"
               value="hk/hku/cecid/piazza/corvus/core/conf/corvus.log.properties.xml" />
    <parameter name="category" value="hk.hku.cecid.piazza" />
  </component>
...
</module>

For the plugins, instead of looking for a file named :file:`sys.properties`, Hermes will look for a file named :file:`plugin.xml` instead.

/_static/images/2-overview-2.jpeg

From within, a parameter with the value module-group-descriptor will define the location of the module-group definition.

<?xml version="1.0" encoding="UTF-8"?>
<plugin
  id="hk.hku.cecid.edi.as2"
  name="Corvus AS2 Plugin"
  version="1.0.1"
  provider-name="hk.hku.cecid"
  class="hk.hku.cecid.edi.as2.AS2Processor"
>
  <parameters>
    <parameter name="module-group-descriptor"
               value="hk/hku/cecid/edi/as2/conf/as2.module-group.xml"/>
  </parameters>
...
</plugin>

Hermes core system properties

You can modify the following information either through the web admin interface or by manipulating the XML configuration files directly.

The configuration files are stored in :file:`{<WEBAPPS_LOCATION>}/corvus/WEB-INF/classes/hk/hku/cecid/piazza/corvus/core/conf` (where :file:`{<WEBAPPS_LOCATION>}` is the web application repository of the application server).

Properties Configuration file
  1. Hermes location
  2. Plugin location for Hermes
  3. SSL trust store information
  4. HTTP/HTTPS proxy server
  5. Encoding settings for core system
  6. Connection timeout settings
:file:`corvus.properties.xml`
  1. Log file location and level of logging
:file:`corvus.log.properties.xml`

Hermes location

You can change the location of Hermes by modifying this element:

<corvus>
  <home>/corvus</home>
  ...
</corvus>
XPath Expected information
/corvus/home The location in which Hermes is installed. Note that the specified path is an absolute path.

Plugin location for Hermes

You can change the plugin location of Hermes by modifying this element:

<corvus>
  ...
  <plugin>
    ...
    <registry>/corvus/plugins</registry>
    <descriptor>plugin.xml</descriptor>
    ...
  </plugin>
  ...
</corvus>
XPath Expected information
/corvus/plugin/registry The location in which Hermes plugins are installed. By default, it should be the plugins directory under the home directory where Hermes is installed. Note that the specified path is an absolute path.
/corvus/plugin/descriptor The name of the XML file which Hermes will use when loading the module-group-component.

SSL trust store information

<corvus>
  ...
    <environment>
      <properties>
          ...
        <javax.net.ssl.trustStore>/j2sdk1.4.2_04/jre/lib/security/cacerts
        </javax.net.ssl.trustStore>
        <javax.net.ssl.trustStorePassword>password
        </javax.net.ssl.trustStorePassword>
        ...
      </properties>
    <environment>
</corvus>
XPath Expected information
/corvus/environment/properties/javax.net.ssl.trustStore The location of the Java keystore which is used for establishing SSL connections. The keystore should contain the certificates of trusted certificate authorities. To maintain the keystore, the reader should use the :program:`keytool` provided by :program:`JDK`. For more information, the reader may reference http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html.
/corvus/environment/properties/javax.net.ssl.trustStorePassword The password used to access the keystore specified above.

HTTP/HTTPS proxy server

<corvus>
  ...
    <environment>
      <properties>
        <http.proxyHost>proxy.csis.hku.hk</http.proxyHost>
        <http.proxyPort>8282</http.proxyPort>
        <https.proxyHost>proxy.csis.hku.hk</https.proxyHost>
        <https.proxyPort>8282</https.proxyPort>
        ...
      </properties>
    <environment>
</corvus>
XPath Expected information
/corvus/environment/properties/http.proxyHost The hostname or IP address of the proxy host that Hermes will establish HTTP connections with for outgoing messages.
/corvus/environment/properties/http.proxyPort The TCP port of the proxy server specified above.
/corvus/environment/properties/https.proxyHost The hostname or IP address of the proxy host that Hermes will establish HTTPS connections with for outgoing messages.
/corvus/environment/properties/https.proxyPort The TCP port of the proxy server specified above.

Encoding settings for core system

<corvus>
  ...
    <encoding>
      <servlet-request>UTF-8</servlet-request>
      <servlet-response>text/html;UTF-8</servlet-response>
    </encoding>
  ...
</corvus>
XPath Expected information
/corvus/encoding/servlet-request The encoding of incoming HTTP or HTTPS requests. UTF-8 is the recommended value because it can handle most written languages.
/corvus/encoding/servlet-response The encoding of outgoing HTTP or HTTP responses.

Connection timeout settings

<corvus>
    ...
  <properties>
    ...
    <sun.net.client.defaultConnectTimeout>30000</sun.net.client.defaultConnectTimeout>
    <sun.net.client.defaultReadTimeout>300000</sun.net.client.defaultReadTimeout>
    ...
  </properties>
  ...
</corvus>
XPath Expected information
/corvus/properies/sun.net.client.defaultConnectTimeout It specifies the timeout (in milliseconds) for establishing HTTP or HTTPS connections for outgoing messages. 30 seconds is the recommended value.
/corvus/properies/sun.net.client.defaultReadTimeout It specifies the timeout (in milliseconds) for reading from input streams when a HTTP or HTTPS connection is established. 300 seconds is the recommended value.

Log file location and level of logging

To change the settings of the log written by the core system, you will need to modify the XML file named :file:`corvus.log.properties.xml`. Configuring the logging module is the same as configuring Apache Log4j. Note that for configuring the logs of plugins, you need to edit another configuration file.

<log4j:configuration debug="null" threshold="null" xmlns:log4j="http://jakarta.apache.org/log4j/">
<appender name="corvus" class="org.apache.log4j.RollingFileAppender">
  <param name="File" value="/corvus/corvus.log"/>
  <param name="Encoding" value="UTF-8"/>
  <param name="MaxFileSize" value="100KB"/>
  <param name="MaxBackupIndex" value="1"/>
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} [%-12.12t] &lt;%-5p&gt; &lt;%m&gt;%n"/>
  </layout>
</appender>
<category additivity="true" name="hk.hku.cecid.piazza">
  <priority value="debug"/>
  <appender-ref ref="corvus"/>
</category>
</log4j:configuration>
XPath Expected information
/log4j:configurationcategory/priority The log level of core system logging. The available levels are debug, info, warn, error and fatal. If you set the value as debug, all logs will be printed.
/log4j:configurationcategory/appender-ref@ref The name of the appender element to be used for logging. The appender element specifies how to generate log files. In the above example, the appender named corvus is used. The settings of the appender are specified by the referenced appender element.
/log4j:configurationappender@class The appender specified by the appender configuration element. Apache Log4j provides a series of appenders, such as RollingFileAppender and DailyRollingFileAppender.
/log4j:configurationappender@name The name of the appender configuration element. :file:`/log4j:configurationcategory/appender-ref@ref` should reference the appender configuration element by this name.

/log4j:configurationappender/param[@name='File']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is File)

The path of the core system log from this appender.

/log4j:configurationappender/param[@name='Encoding']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is Encoding)

The encoding to be used for the log file.

/log4j:configurationappender/param[@name='MaxFileSize']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is MaxFileSize)

If the size of a log file has grown to exceed this limit, a new log file will be written and the old log file will be backed up. An index will be appended to the name of the old log file. (e.g. :file:`corvus.log.1`).

/log4j:configurationappender/param[@name='MaxBackupIndex']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is MaxBackupIndex)

The maximum number of log files that will be backed up. For example, if it is set to 10, the maximum number of backed up log files will be 10 and their filenames will be :file:`{xxx}.log.1`, :file:`{xxx}.log.2`, ..., :file:`{xxx}.log.10`.
/log4j:configurationappender/layout/param[@name='ConversionPattern']/@value The pattern used when writing the log file.

Hermes plugin properties

AS2 plugin

In the directory :file:`{<HERMES_2_PLUGINS_LOCATION>}/corvus-as2/conf/hk/hku/cecid/edi/as2/conf`, there are some configuration files for Hermes's AS2 plugin. Which configuration file you should edit depends on the property:

Properties Configuration file
Log file location and level of logging :file:`as2.log.properties.xml`
Connection to message database :file:`as2.module.core.xml`
Location of keystore for signing outgoing messages
Location of message repository

Log file location and level of logging

To change the location of the log file, you will need to modify the XML file named :file:`as2.log.properties.xml`.

<log4j:configuration debug="null" threshold="null" xmlns:log4j="http://jakarta.apache.org/log4j:configuration">
<appender name="as2" class="org.apache.log4j.RollingFileAppender">
  <param name="File" value="/as2.log"/>
  <param name="Encoding" value="UTF-8"/>
  <param name="MaxFileSize" value="100KB"/>
  <param name="MaxBackupIndex" value="1"/>
  <layout class="org.apache.log4j.PatternLayout">
  <param name="ConversionPattern"
        value="%d{yyyy-MM-dd HH:mm:ss} [%-12.12t] &lt;%-5p&gt; &lt;%m&gt;%n"/>
  </layout>
</appender>
<category additivity="true" name="hk.hku.cecid.edi.as2">
  <priority value="debug"/>
  <appender-ref ref="as2"/>
</category>
</log4j:configuration>
XPath Expected information
/log4j:configuration/category/priority The log level of the AS2 plugin logging. The available levels are debug, info, warn, error and fatal. If you set the value as debug, all logs will be printed.
/log4j:configuration/category/appender-ref@ref The name of the appender element to be used for logging. The appender element specifies how to generate log files. In the above example, the appender named as2 is used. The settings of the appender are specified by the referenced appender element.
/log4j:configuration/appender@class The appender specified by this appender configuration element. Apache Log4j provides a series of appenders, such as RollingFileAppender and DailyRollingFileAppender.
/log4j:configuration/appender@name The name of this appender configuration element. :file:`/log4j:configuration/category/appender-ref@ref` should reference the appender configuration element by this name.

/log4j:configuration/appender/param[@name='File']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is File)

The path of the AS2 log of this appender.

/log4j:configuration/appender/param[@name='Encoding']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is Encoding)

The encoding to be used for the log file.

/log4j:configuration/appender/param[@name='MaxFileSize']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is MaxFileSize)

If the size of a log file has grown to exceed this limit, another new log file will be written and the old log file will be backed up. An index will be appended to the name of the old log file (e.g. :file:`as2.log.1`).

/log4j:configuration/appender/param[@name='MaxBackupIndex]/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is MaxBackupIndex)

The maximum number of log files that will be backed up. For example, if it is set to 10, the maximum number of backed up log files will be 10 and their filenames will be :file:`{xxx}.log.1`, :file:`{xxx}.log.2`, ..., :file:`{xxx}.log.10`.
/log4j:configuration/appender/layout/ param[@name='ConversionPattern']/@value The pattern used when writing the log file.

Connection to message database

<module>
...
<component id="daofactory" name="AS2 DAO Factory">
  <class>
  hk.hku.cecid.piazza.commons.dao.ds.SimpleDSDAOFactory
  </class>
  <parameter name="driver" value="org.postgresql.Driver" />
  <parameter name="url"
             value="jdbc:postgresql://localhost:5432/as2" />
  <parameter name="username" value="corvus" />
  <parameter name="password" value="corvus" />
  <parameter name="pooling" value="true" />
  <parameter name="maxActive" value="20" />
  <parameter name="maxIdle" value="10" />
  <parameter name="maxWait" value="-1" />
  <parameter name="config"
             value="hk/hku/cecid/edi/as2/conf/as2.dao.xml" />
</component>
...
</module>
XPath Expected information
/module/component[@id='daofactory']/class

The Java class to use when establishing a database connection. You can select:

  • hk.hku.cecid.piazza.commons.dao.ds.SimpleDSDAOFactory, if you want AS2 to manage the database connection pool
  • hk.hku.cecid.piazza.commons.dao.ds.DataSourceDAOFactory, if you want the application server to manage the database connection pool, which is accessible through the Java Naming and Directory Interface (JNDI) name.
Belows are fields you need to fill in if you are using SimpleDSDAOFactory
/module/component[@id='daofactory']/ parameter[@name='driver']/@value The JDBC driver that should be used. The driver for Postgres is provided by default. The driver should be placed in the directory :file:`{<TOMCAT_HOME>}/webapps/corvus/WEB-INF/lib`, where we suppose the web application repository is configured as :file:`{<TOMCAT_HOME>}/webapps`.
/module/component[@id='daofactory']/ parameter[@name='url']/@value The URL for establishing the database connection. Please refer to the documentation of the JDBC driver for the syntax. For PostgreSQL, the syntax is :file:`jdbc:postgresql://{<IP or hostname of the database>}/{<message database name for AS2>}`
/module/component[@id='daofactory']/ parameter[@name='username']/@value The username to connect to the database.
/module/component[@id='daofactory']/ parameter[@name='password']/@value The password for the username specified.
/module/component[@id='daofactory']/ parameter[@name='pooling']/@value The boolean value (true/false) specifying if connection pooling should be used.
/module/component[@id='daofactory']/ parameter[@name='maxActive']/@value The maximum number of active threads.
/module/component[@id='daofactory']/ parameter[@name='maxIdle']/@value The maximum number of threads that can remains idle.
/module/component[@id='daofactory']/ parameter[@name='maxWait']/@value The maximum amount of time (milliseconds) that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
/module/component[@id='daofactory']/ parameter[@name='config']/@value Additional configuration files that will be used by the plugin. You should just leave it as is.
Belows are fields you need to fill in if you are using DataSourceDAOFactory
datasource The JNDI name of the data source for connecting to the message database, e.g. java:/comp/env/jdbc/as2db

Location of keystore for signing outgoing messages

<module id="as2.core" name="Corvus AS2" version="1.0">
...
<component id="keystore-manager" name="AS2 Key Store Manager">
  <class>hk.hku.cecid.piazza.commons.security.KeyStoreManager</class>
  <parameter name="keystore-location" value="corvus.p12"/>
  <parameter name="keystore-password" value="password"/>
  <parameter name="key-alias" value="corvus"/>
  <parameter name="key-password" value="password"/>
  <parameter name="keystore-type" value="PKCS12"/>
  <parameter name="keystore-provider"
             value="org.bouncycastle.jce.provider.BouncyCastleProvider"/>
</component>
...
</module>
XPath Expected information
/module/component[@id='keystore-manager']/parameter[@name='keystore-location']/@value The path of the keystore for signing outgoing messages.
/module/component[@id='keystore-manager']/parameter[@name='keystore-password']/@value The password for accessing the keystore.
/module/component[@id='keystore-manager]/parameter[@name='key-alias']/@value The alias of the private key for a digital signature.
/module/component[@id='keystore-manager]/parameter[@name='key-password']/@value The password protecting the private key for a digital signature.
/module/component[@id='keystore-manager]/parameter[@name='keystore-type']/@value The keystore format. It is either PKCS12 or JKS.

Location of the message repository

Outgoing Repository:

<module id="as2.core" name="Corvus AS2" version="1.0">
...
<component id="outgoing-payload-repository" name="AS2 Outgoing Payload Repository">
<class>
hk.hku.cecid.edi.as2.module.PayloadRepository
</class>
  <parameter name="location" value="/as2-outgoing-repository" />
  <parameter name="type-edi" value="application/EDIFACT" />
  <parameter name="type-x12" value="application/EDI-X12" />
  <parameter name="type-eco" value="application/edi-consent" />
  <parameter name="type-xml" value="application/XML" />
</component>
...
</module>
XPath Expected information
/module/component[id='outgoing-payload-repository']/class The Java class responsible for handling outgoing payload. You should just leave it as is.
/module/component[id='outgoing-payload-repository']/ parameter[@name='location']/@value The directory that will store the outgoing payload. E.g., :file:`c:\program files\hermes2\repository\as2-outgoing-repository`
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-edi']/@value You should leave these fields as is.
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-x12']/@value
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-eco']/@value
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-xml']/@value
<module id="as2.core" name="Corvus AS2" version="1.0">
...
<component id="incoming-payload-repository" name="AS2 Incoming Payload Repository">
  <class>
    hk.hku.cecid.edi.as2.module.PayloadRepository
  </class>
  <parameter name="location" value="/as2-incoming-repository" />
  <parameter name="type-edi" value="application/EDIFACT" />
  <parameter name="type-x12" value="application/EDI-X12" />
  <parameter name="type-eco" value="application/edi-consent" />
  <parameter name="type-xml" value="application/XML" />
</component>
...
</module>
XPath Expected information
/module/component[id='incoming-payload-repository']/class The Java class responsible for handling incoming payloads. You should just leave it as is.
/module/component[id='outgoing-payload-repository']/ parameter[@name='location']/@value The directory that will store the outgoing payload. E.g., :file:`c:/program files/hermes2/repository/as2-incoming-repository`
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-edi']/@value You should leave these fields as is.
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-x12']/@value
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-eco']/@value
/module/component[id='outgoing-payload-repository']/ parameter[@name='type-xml']/@value

Original Message Repository (a temporary message repository used when Hermes is composing or receiving AS2 messages):

<module id="as2.core" name="Corvus AS2" version="1.0">
...
<component id="original-message-repository" name="AS2 Original Message Repository">
  <class>
    hk.hku.cecid.edi.as2.module.MessageRepository
  </class>
  <parameter name="location" value="/as2-message-repository" />
  <parameter name="is-disabled" value="false" />
</component>
...
</module>
XPath Expected information
/module/component[id='original-payload-repository']/class The Java class responsible for handling original messages. You should just leave it as is.
/module/component[id='original-payload-repository']/ parameter[@name='location']/@value The directory that will store outgoing payloads. E.g., :file:`c:/program files/hermes2/repository/as2-message-repository`
/module/component[id='original-payload-repository']/ parameter[@name='is-disabled']/@value This flag indicates if the original message should be stored locally.

ebMS plugin

In the directory :file:`{<HERMES_2_PLUGINS_LOCATION>}/corvus-ebms/conf/hk/hku/cecid/ebms/spa/conf`, there are some configuration files for Hermes's ebMS plugin. The configuration file you should edit depends on the property:

Properties Configuration file
Log file location and level of logging :file:`log4j.properties.xml`
Connections to message database :file:`ebms.module.xml`
Location of keystore for signing outgoing messages
Location of keystore for S/MIME decryption (incoming messages)

Log file location and level of logging

To change the location of the log file, you will need to modify the XML file named :file:`log4j.properties.xml`

<log4j:configuration debug="null" threshold="null" xmlns:log4j="http://jakarta.apache.org/log4j/">
  <appender name="ebms" class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="/ebms.log"/>
    <param name="Encoding" value="UTF-8"/>
    <param name="MaxFileSize" value="100KB"/>
    <param name="MaxBackupIndex" value="1"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern"
          value="%d{yyyy-MM-dd HH:mm:ss} [%-12.12t] &lt;%-5p&gt; &lt;%m&gt;%n"/>
    </layout>
  </appender>
  <category additivity="true" name="hk.hku.cecid.ebms">
    <priority value="debug"/>
    <appender-ref ref="ebms"/>
  </category>
</log4j:configuration>
XPath Expected information
/log4j:configuration/category/priority The log level of the ebMS plugin logging. The available levels are debug, info, warn, error and fatal. If you set the value as debug, all logs will be printed.
/log4j:configuration/category/appender-ref@ref The name of the appender element to be used for logging. The appender element specifies how to generate log files. In the above example, the appender named RollingFileAppender is used. The settings of the appender are specified by the referenced appender element.
/log4j:configuration/appender@class The appender specified by this appender configuration element. Apache Log4j provides a series of appenders, such RollingFileAppender and DailyRollingFileAppender.
/log4j:configuration/appender@name The name of this appender configuration element. :file:`/category/appender-ref@ref` should reference the appender configuration element by this name.

/log4j:configuration/appender/param[@name='File']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is File)

The path of the ebMS log of this appender.

/log4j:configuration/appender/param[@name='Encoding']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is Encoding)

The encoding to be used for the log file.

/log4j:configuration/appender/param[@name='MaxFileSize']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is MaxFileSize)

If the size of a log file has grown to exceed this limit, another log file will be written and the old log file will be backed up. An index will be appended to the name of the old log file (e.g. :file:`ebms.log.1`).

/log4j:configuration/appender/param[@name='MaxBackupIndex']/@value

(i.e. The value attribute of the param element under the appender element, whose name attribute is MaxBackupIndex)

The maximum number of log files that will be backed up. For example, if it is set to 10, the maximum number of backed up log files will be 10 and their filenames will be :file:`{xxx}.log.1`, :file:`{xxx}.log.2`, ..., :file:`{xxx}.log.10`.
/log4j:configuration/appender/layout/ ``param[@name='ConversionPattern']/@value The pattern used when writing the log file.

Connection to message database

<module>
...
<component id="daofactory" name="System DAO Factory">
  <class>
  hk.hku.cecid.piazza.commons.dao.ds.SimpleDSDAOFactory
  </class>
  <parameter name="driver" value="org.postgresql.Driver" />
  <parameter name="url" value="jdbc:postgresql://localhost:5432/ebms" />
  <parameter name="username" value="corvus" />
  <parameter name="password" value="corvus" />
  <parameter name="pooling" value="true" />
  <parameter name="maxActive" value="30" />
  <parameter name="maxIdle" value="10" />
  <parameter name="maxWait" value="-1" />
  <parameter name="testOnBorrow" value="true" />
  <parameter name="testOnReturn" value="false" />
  <parameter name="testWhileIdle" value="false" />
  <parameter name="validationQuery" value="SELECT now()" />
  <parameter name="config">hk/hku/cecid/ebms/spa/conf/ebms.dao.xml</parameter>
</component>
...
</module>
XPath Expected information
/module/component[@id='daofactory']/class

The Java class to use when establishing a database connection. You can select:

  • hk.hku.cecid.piazza.commons.dao.ds.SimpleDSDAOFactory, if you want ebMS to manage the database connection pool.
  • hk.hku.cecid.piazza.commons.dao.ds.DataSourceDAOFactory, if you want the application server to manage the database connection pool, which is accessible through the Java Naming and Directory Interface (JNDI) name.
Belows are fields you need to fill in if you are using SimpleDSDAOFactory
/module/component[@id='daofactory']/ parameter[@name='driver']/@value The JDBC driver that should be used. The driver for Postgres is provided by default. The driver should be placed in the directory :file:`{<TOMCAT_HOME>}/webapps/corvus/WEB-INF/lib`, where we suppose the web application repository is configured as :file:`{<TOMCAT_HOME>}/webapps`.
/module/component[@id='daofactory']/ parameter[@name='url']/@value The URL for establishing the database connection. Please refer to the documentation of the JDBC driver for the syntax. For PostgreSQL, the syntax is :file:`jdbc:postgresql://{<IP or hostname of the database>}/{<message database name for AS2>}`
/module/component[@id='daofactory']/ parameter[@name='username']/@value The username to connect to the database.
/module/component[@id='daofactory']/ parameter[@name='password']/@value The password for the username specified.
/module/component[@id='daofactory']/ parameter[@name='pooling']/@value The boolean value (true/false) specifying if connection pooling should be used.
/module/component[@id='daofactory']/ parameter[@name='maxActive']/@value The maximum number of active threads.
/module/component[@id='daofactory']/ parameter[@name='maxIdle']/@value The maximum number of threads that can remains idle.
/module/component[@id='daofactory']/ parameter[@name='maxWait']/@value The maximum amount of time (milliseconds) that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
/module/component[@id='daofactory']/ parameter[@name='testOnBorrow']/@value Parameter used by system during testing, please keep it unchanged
/module/component[@id='daofactory']/ parameter[@name='testOnReturn']/@value Parameter used by system during testing, please keep it unchanged
/module/component[@id='daofactory']/ parameter[@name='tesWhileIdle']/@value Parameter used by system during testing, please keep it unchanged
/module/component[@id='daofactory']/ parameter[@name='validateQuery']/@value Parameter used by system during testing, please keep it unchanged
/module/component[@id='daofactory']/ parameter[@name='config']/@value Additional configuration files that will be used by the plugin. You should just leave it as is.
Belows are fields you need to fill in if you are using DataSourceDAOFactory
datasource The JNDI name of the data source for connecting to the message database, e.g. java:/comp/env/jdbc/ebmsdb

Location of keystore for signing outgoing messages

<module id="ebms.main" name="Ebms Plugin" version="1.0">
...
<component id="keystore-manager-for-signature" name="Key Store Manager for Digital Signature">
  <class>hk.hku.cecid.piazza.commons.security.KeyStoreManager</class>
  <parameter name="keystore-location" value="corvus.p12"/>
  <parameter name="keystore-password" value="password"/>
  <parameter name="key-alias" value="corvus"/>
  <parameter name="key-password" value="password"/>
  <parameter name="keystore-type" value="PKCS12"/>
  <parameter name="keystore-provider"
             value="org.bouncycastle.jce.provider.BouncyCastleProvider"/>
  </component>
...
</module>
XPath Expected information
/module/component[@id='keystore-manager-for-signature']/ parameter[@name='keystore-location']/@value The path of the keystore for signing outgoing messages.
/module/component[@id='keystore-manager-for-signature']/ parameter[@name='keystore-password']/@value The password for accessing the keystore.
/module/component[@id='keystore-manager-for-signature']/ parameter[@name='key-alias']/@value The alias of the private key for digital signature.
/module/component[@id='keystore-manager-for-signature']/ parameter[@name='key-password']/@value The password protecting the private key for digital signature.
/module/component[@id='keystore-manager-for-signature']/ parameter[@name='keystore-type']/@value The keystore format. It is either PKCS12 or JKS.

Location of keystore for S/MIME decryption (incoming messages)

<module id="ebms.main" name="Ebms Plugin" version="1.0">
...
  <component id="keystore-manager-for-decryption" name="Key Store Manager for Decryption (ebMS over SMTP)">
    <class>hk.hku.cecid.piazza.commons.security.KeyStoreManager</class>
    <parameter name="keystore-location" value="corvus.p12"/>
    <parameter name="keystore-password" value="password"/>
    <parameter name="key-alias" value="corvus"/>
    <parameter name="key-password" value="password"/>
    <parameter name="keystore-type" value="PKCS12"/>
    <parameter name="keystore-provider" value="org.bouncycastle.jce.provider.BouncyCastleProvider"/>
  </component>
...
</module>
XPath Expected information
/module/component[@id='keystore-manager-for-decryption']/ parameter[@name='keystore-location']/@value The path of the keystore for decrypting incoming messages with S/MIME encryption.
/module/component[@id='keystore-manager-for-decryption']/ parameter[@name='keystore-password']/@value The password for accessing the keystore
/module/component[@id='keystore-manager-for-decryption']/ parameter[@name='key-alias']/@value The alias of the private key for the decryption.
/module/component[@id='keystore-manager-for-decryption']/ parameter[@name='key-password']/@value The password protecting the private key for digital signatures.
/module/component[@id='keystore-manager-for-decryption']/ parameter[@name='keystore-type']/@value The keystore format. It is either PKCS12 or JKS.

See also