CCM NG:

- Some (general) documentation about the module system
    - Removed obsolete profiles from testing documentation


git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@3612 8810af33-2d31-482b-a856-94f89814c4df

ccm-core/src/main/java/org/libreccm/modules/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2015 LibreCCM Foundation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301  USA
+ */
+
+/**
+ * This package contains the basic classes for the module system of LibreCCM
+ */
+package org.libreccm.modules;

src/site/apt/module-system.apt

@@ -10,7 +10,47 @@ The module system of LibreCCM
 
     The functionality of LibreCCM is organised in modules which can bundled to
     serve specific needs. The bundling is done by special modules which packaged
-    as WAR files. A module itself is packaged as JAR file. 
+    as WAR files. A module itself is packaged as JAR file. The module system 
+    provides several features like automatic database migrations. 
 
-    The module system provides several features like automatic database 
+    We are not using OSGi here because OSGi would add another layer of 
-    migrations.
+    complexity. Also OSGi does to integrate well with some of the Java EE 
+    technologies.
+
+    The module system is build around the classes in the 
+    {{{file:///home/jensp/pwi/libreccm/ccm/ccm_ng/target/staging/ccm-core/apidocs/index.html?org/libreccm/modules/package-summary.html}org.libreccm.modules}} package.
+
+    When the LibreCCM application is started by the Application Server two 
+    things will happen. First the 
+    {{{file:///home/jensp/pwi/libreccm/ccm/ccm_ng/target/staging/ccm-core/apidocs/index.html?org/libreccm/modules/CcmIntegrator.html}CcmIntegrator}}
+    is executed. The integrator checks for new or updated modules and executes
+    DB migrations if necessary. We are using the 
+    {{{http://www.flyway.org}Flyway}} framework for this. We have
+    to execute these migrations before the Application Server starts the JPA
+    Persistence Unit and the JPA provider validates the database structure.
+    Unfortunately the JPA specification does not provide a hook for doing
+    such things. Therefore we have to use a Hibernate specific API for that.
+
+    Secondly the 
+    {{{file:///home/jensp/pwi/libreccm/ccm/ccm_ng/target/staging/ccm-core/apidocs/index.html?org/libreccm/modules/CcmModuleContextListener.html}CcmModuleContextListener}}
+    is called when the <<<ServletContext>>> is initialised. The 
+    <<<CcmModuleContextListener>>> is an ordinary <<<ServletContextListener>>>.
+    We use the new annotations (<<<@WebListener>>>) to register the listener.
+    The <<<CcmModuleContextListener>>> checks for new modules and executes
+    the <<<install>>> method of these modules. After that for each module
+    the <<<init>>> method of the module is called. When the application is
+    shutdown the <<<shutdown>>> method of each module is called. If the module
+    is marked for uninstall the <<<uninstall>>> method of the module is called 
+    also. 
+
+    The <<<CcmIntegrator>>> is also called on shutdown and checks for modules
+    marked to be deinstalled. If there are such modules the database for the
+    module is cleaned by Flyway.
+
+    The database tables for each module live in their own schema (namespace) in
+    the the database. This makes it easier to manage them using Flyway. Each 
+    schema contains a <<<schema_version>>> table which is used by Flyway to 
+    keep track of the migrations applied to the schema. Because MySQL and its 
+    descendents like MariaDB implement schemas wrong (as databases) we can't 
+    support MySQL as database for now. This kind of implementation causes
+    all sort of silly problems.

src/site/apt/testing.apt

@@ -40,15 +40,9 @@ Testing LibreCCM
 
     At the moment the following profiles are provided:
 
-    [wildfly8-embedded] Uses an embedded Wildfly 8 server and the integrated H2
-    database-
-
     [wildfly8-remote-h2-mem] Uses a remote Wildfly 8 application server and
     a in memory H2 database
 
-    [wildfly8-remote-mysql] Uses a remote Wildfly 8 application server and
-    a MySQL or MariaDB database.
-
     [wildfly8-remote-pgsql] Uses a remote Wildfly 8 application server and
     a PostgreSQL database.
 
@@ -62,11 +56,6 @@ Testing LibreCCM
     [wildfly8-remote-oracle] Will use a remote Wildfly 8 server and a Oracle 
     database.
     
-    [tomee17-embedded] Will use a embedded TomEE application server, version 1.7
-    
-    [tomee17-remote-mysql] Will use a remote TomEE application server and a
-    MySQL/MariaDB database.
-    
     [tomee17-remote-pgsql] Will use a remote TomEE application server and a 
     PostgreSQL database.
 
@@ -97,8 +86,6 @@ Testing LibreCCM
     [java:/comp/env/jdbc/org/libreccm/ccm-core/h2-mem] A in memory database 
     using the H2 database which is part of Wildfly.
 
-    [java:/comp/env/jdbc/org/libreccm/ccm-core/mysql] MySQL database
-
     [java:/comp/env/jdbc/org/libreccm/ccm-core/pgsql] PostgresSQL database
 
     Please note that the database is recreated after each test. Therefore