Version 5
Created by jmesnil on Sep 6, 2016 6:53 AM. Last modified by jmesnil on Sep 7, 2016 5:04 AM.

    User Story

     

    Be able to use a JBDC store for messaging persistence.

     

    Issue Metadata

     

    * EAP issue: https://issues.jboss.org/browse/EAP7-591

    * Related issues: N/A

    * Dev Contacts: Jeff Mesnil, Artemis (TBD)

    * QE Contacts: TBD

    * Affected projects or components: Artemis, messaging-activemq subsystem

     

    Hard Requirements

     

    Artemis 1.3 provide a JDBC persistence store in addition to its file-system store.

    Artemis can be configured to store any persistence information in this database.

     

    Using a DB to persist information provides a simpler solution to share information than the file-system store (which only works with specify shared file systems). On the other side, it introduces performance degradation.

     

    Note that paging is currently not working with the JDBC store (as documented in http://activemq.apache.org/artemis/docs/1.3.0/persistence.html). Pages are stored in local files and not inside the DB.

    Only a few databases are supported by Artemis 1.3.0 (PostGreSQL 9.4.x, MySQL 5.7.x, and Apache Derby 10.11.1.1).

     

    For EAP7, the requirements are:

     

    • Store any persistent information for Artemis in a database accessed using the JDBC API
    • Must be made compatible with any DB (including Oracle 12c)

     

    Non Requirements

     

    • There is no management operations provided by the messaging-activemq subsystem to manage the JDBC tables.
    • There is no management operations provided by the messaging-activemq subsystem to export/import the tables

     

    Design Details

     

    Artemis can be configured to use JDBC persistence by configuring the following properties:

     

    • jdbc-connection-url - the JDBC connection URL
    • jdbc-driver-class-name - the name of the JDBC driver
    • bindings-table-name - the name of the JDBC table to store bindings
    • message-table-name - the name of the JDBC table to store persistent messages
    • large-message-table-name - the name of the JDBC table to store large messages

     

    Artemis internally store a list of SQL commands to manipulate those tables that depends on the DB (represented by https://github.com/apache/activemq-artemis/blob/master/artemis-jdbc-store/src/main/java/org/apache/activemq/artemis/jdbc/store/sql/SQLProvider.java and its subclasses).

    Artemis provides implementation for PostgreSQL, MySQL and Derby plus a generic one (https://github.com/apache/activemq-artemis/blob/master/artemis-jdbc-store/src/main/java/org/apache/activemq/artemis/jdbc/store/sql/GenericSQLProvider.java).

     

    From WildFly perspective, the jdbc-connection-url and jdbc-driver-class-name properties are not a good fit as they rely on the driver classes being in Artemis class loader so that it can instantiate it.

    WildFly provides a JDBC DataSource through its datasource subsystem and we should leverage it to keep any JDBC configuration in a single configuration place.

    Artemis should be modified to use a DataSource to communicate with the database as an alternative to the existing URL/class name properties.

     

    Since Java EE7 provides a default JDBC DataSource, the user would not need to provide any value for it to be able to use JDBC persistence out of the box for Artemis.

     

    To be able to support additional DBs than those supported by Artemis, we need a mechanism to provide additional subclasses of SQLProvider.java.

     

    Artemis could be modified to accept a SQLProvider object in its store configuration and leave it up to WildFly to provide it.

     

    When the user configure the JDBC persistence store for a messaging-activemq's server he would have to specify the SQLProvider class name and the module that contains it. The subsystem will then instantiate the class and pass it to Artemis to use it.

     

    Note that JDBC store is not compatible with HA. Artemis does not provide a way to lock a JDBC store and allow access to only a live server (and not to any backup servers).

     

    Configuration examples

     

    These example are not definitive and only provide a preview of what the final configuration will be.

     

    Out of the box JDBC persistence would be configured by a single CLI command (or equivalent XML element):

     

      /subsystem=messaging-activemq/server=default/store=jdbc:add()

     

    This would rely on default values for all configuration:

     

    • default Java EE7 DataSource (looked up at "java:comp/DefaultDataSource") and its corresponding SQLProvider (based on H2)
    • default values for the table names

     

    A Complete configuration to use an external database (such as Oracle 12c) would be configured by a more complex CLI command:

     

      /subsystem=datasources/data-source=myDB:add("jndi-name"="java:jboss/datasources/myDS"...) => configure datasource to access the external DB

      /subsystem=messaging-activemq/server=default/store=jdbc:add(datasource="java:jboss/datasources/myDS", sql-provider={class => "com.foo.myDBProvider", module => "com.foo"}, bindings-table-name="foo", message-table-name="bar", large-message-table-name="baz")

     

    Artemis Requirements

     

    • Artemis would have to be modified to accept a DataSource object as an alternative to the (URL/driver class name) tuple to connect to the JDBC store
    • Artemis would have to be modified to take an instance of its SQLProvider to execute commands on the DB.

     

    WildFly Requirements

     

    The messaging-activemq subsystem will have to be modified to support the configuration of the jdbc persistence store.

     

    The subsystem will have to ensure that configuration of file store and JDBC store are mutually exclusive and warn the users if that's not the case.

     

    Work Decomposition

     

    Work can be decomposed by first modifying Artemis and then WildFly's messaging-activemq subsystem.

     

    Artemis requires modification to its configuration API to be able to use DataSource and SQLProvider instances instead of (URL/Class name) tuple and hard-coded providers. This does not require any modification to the actual code that persist data in the DB.

    Artemis will also have to provide paging support for JDBC store.

    Once a version of Artemis is released with these modification, WildFly's messaging-activemq can be updated to leverage it.

     

    QE

     

    QE has already tests to check Artemis behaviour when using a shared file store. These tests could also be run with WildFly using the new JDBC persistent store to ensure that there is no issue with it.

     

    Special attention should be paid if different WildFly servers connect to the same DB to store their messages (if that's not already taken into account by Artemis).