Database choice

The app-manager, business-manager, client, client-direct and site-business components require a local database to be configured.

Currently only MySQL, Oracle (10g) and HSQL database use is available pre-configured.

Warning

If an unavailable db vendor is used then another Spring profile in the src/main/resources/META-INF/spring/ctx/data/appCtx.database.xml file is required (e.g. see app-manager’s appCtx.database.xml) and the pom.xml (derived from sample.pom.xml) to include the vendor-specific JDBC driver.
A corresponding build arg -Dspring.profiles.active= specific to the new vendor will be needed at build time and run time.
The ability to modify appCtx.database.xml locally to accommodate alternative database vendors is not yet implemented as the file is under version control. Until such time any local modifications to this file may in the future result in version control conflicts.

For each potential database system you intend to use in a deployment environment, substitute the following where applicable :

<deploy.env> = dev (see [1])
<deploy.db_vendor> = (embedded|mysql|oracle10g|<your db vendor, e.g. postgres>)

pom.xml

Whereas the HSQL driver is built into sample.pom.xml files out of necessity, if you’re using MySQL, Oracle, or your preferred db, then pom.xml files must contain references to your database driver, e.g.

<dependency>
  <groupId>com.oracle</groupId>
  <artifactId>ojdbc6</artifactId>
  <version>11.2.0.2.0</version>
</dependency>

<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>5.1.15</version>
</dependency>

src/properties/database/dev.database.<deploy.db_vendor>.properties

(Using client-direct as an example …)
[ T ] Copy src/properties/database/sample.database.spring.properties to src/properties/database/dev.database.<deploy.db_vendor>.properties e.g. dev.database.mysql.properties.

Adjust your JDBC connectivity settings to your local environment.

Example settings (for MySQL) :

For app-manager, business-manager, site-business components.

app_manager.database.driverClassName=com.mysql.jdbc.Driver
app_manager.database.url=jdbc:mysql://localhost:4003/app_manager
business_manager.database.url=jdbc:mysql://127.0.0.1:4003/business_manager

Note

Historically ?autoDeserialize=true was appended for MySQL but this has been removed (since mid-2018) as data is manually (de)serialised.

For client and client-direct components.

client_direct.database.url=jdbc:mysql://localhost:4003/client_direct?useUnicode=true&characterEncoding=UTF-8&characterSetResults=utf8&connectionCollation=utf8_general_ci

Note

In the case of an embedded <deploy.db_vendor> being active in a deployed environment a corresponding dev.database.embedded.properties file does not need to be created as all database connectivity and activity is managed internally.
Note also that all content written to an embedded database is destroyed when the application is stopped.

Internationalisation

The client and client-direct web interfaces are for the most part internationalised but only using online translations of English to Spanish and Chinese (Traditional) rather than accurate translation services. Some untranslated messages originating from the business logic, particularly error messages, will appear in the web interface.

Language bundles are in src/main/resources/bundle/.

Bundles are referenced in the src/main/resources/META-INF/spring/ctx/appCtx.view.xml messageSource bean definition.

FAQ

  1. How do I modify site-specific messages?
    At the moment only client has this feature, whereby any entries in src/main/resources/bundle/site*.properties can be changed to anything site-specific.
  2. How do I add a new language bundle, e.g. Italian?
    The appropriate new language bundle files will need to be copied from existing examples, e.g. create index_it.properties based on index.properties, and appCtx.view.xml updated to include the new bundle reference. (Note however the potential for version control conflicts)

JASYPT

The JASYPT_PWD environment variable needs to be assigned in situations where;

  1. integration testing involves property file use, and,
  2. application runtime.

For example:

  • Bash environment : export JASYPT_PWD=<encrypting password>
  • Eclipse : Run -> Run Configurations -> Environment tab.

This is whether the properties file value-encoding facilities of Jasypt are used or not - in the latter case set ‘<encrypting password>’ to be an empty string.

Note

Keep in mind that it is better to restrict access rights on any files which may contain the JASYPT password.

Footnotes

[1]This was originally intended to be one of (dev|test|live), depending on the particular deployment environment, however only dev has ever been utilised (and may itself be removed at some point).
In business-manager the value is hardcoded. In app-manager, client, and client-direct it needs to be specified.