Java packages policy

 cz.muni.fi.web2platform
 |
 + core             Platform core
 |   + db
 |   + listeners
 |   + ...
 |
 + connectors       General classes ready to be used by connectors
 |   + utils        Helper classes for connectors
 |   + storage      Every connector should use its own package
 |   + calendar
 |   + ...
 |
 + common           Classes shared by connectors and platform core

Namespaces policy

• All WSDL-defined services accessed by client applications use the namespace http://www.fi.muni.cz/web2platform
• ConnectorCall service
  • namespace of call and callResponse XML elements:
    http://www.fi.muni.cz/web2platform
  • namespace of all connector-specific XML elements:
    http://www.fi.muni.cz/web2platform/connectors/{$connectorName}
  • package of all WSDL-generated classes (both JAX-WS and JAXB)
    cz.muni.fi.web2platform.connectors.{lower-case($connectorName)}
• UserData service (both private and public interface)
  • namespaces of XML elements (if not taken from other parts of W2P):
    http://www.fi.muni.cz/web2platform/core/UserData{Public, Secure}
  • package of JAX-WS-generated classes:
    cz.muni.fi.web2platform.core
  • packages of JAXB-generated classes:
    cz.muni.fi.web2platform.core.userdata{public, secure}

General notes

The "UserData" component needs to store some small amount of data. We decided to employ a relational database for this purpose. The component is designed so that it is (as much as possible) not bound to any specific database engine.

The Apache Derby database, running in the embedded mode, was chosen as the default solution. There are four main reasons for this decision:

• This database engine is already present in the Servicemix distribution so there are no extra downloads or installations necessary (Servicemix 3.3.2 contains Derby 10.5.3.0_1).
• The embedded mode imposes no requirements on the administration (the database engine is started and configured automatically during the first access and stopped together with the Servicemix container).
• The embedded mode provides some extra safety which is important because of the sensitive nature of the data stored - the data can be accessed by only one JVM at a time so there is no possibility of accessing the data from outside the Servicemix (provided Servicemix is running).
• It is possible to encrypt the database data, which again adds some extra safety.

We use a siplified single-user model, i.e. the platform accesses the database using just a single user account with full access rights.

Configuration needed

To use Derby in embedded mode it is necessary to add the following to the SERVICEMIX_HOME/conf/jndi.xml file as a child of the beans/util:map element:

<!-- Make the DataSource accessible via this JNDI entry key. Do not change! -->
<entry key="java:comp/env/jdbc/Web2PlatformDb">

  <!-- We access the embedded Derby using its native connection pooling mechanism -->
  <bean class="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource40">

    <!-- The database name. You can change this although there should be no need to do it. -->
    <property name="databaseName" value="Web2PlatformDb"/>

    <!-- Create the database during the first access.
         Do not change this unless you know what you are doing! -->
    <property name="createDatabase" value="create"/>

    <!-- User login. You can (and should) change this in the production environment -->
    <property name="user" value="web2platform"/>

    <!-- User password. You can (and should) change this in the production environment -->
    <property name="password" value="dbUserPassword"/>

    <!-- Turn on the database encryption. You can (and should) change the bootPassword
         in the production environment -->
    <property name="connectionAttributes" value="dataEncryption=true;encryptionAlgorithm=AES/CBC/NoPadding;bootPassword=dbPassword"/>

  </bean>
</entry>

This way a pre-configured DataSource instance is instantiated automatically and made accessible through JNDI.

When you want to use some other database engine, you have to:

• provide the DataSource configuration similar to the above
• provide a database-engine-specific implementation of the cz.muni.fi.web2platform.core.db.DbManager interface (the AbstractDbManager class should save you a lot of work)
• change the DbManagerFactory.getDbManager() method implementation. If it shows out that using other database engine is important, we will change this method to be more general and use some configuration so that you will need just to change the configuration.

Derby-related design notes

• The createDatabase DataSource property can be used even if the database already exists. In that case it just throws an SQLWarning with an SQLState value of "01J01".
• There is nothing like create table if not exists in Derby so it is necessary to check the table existence (or the SQLWarning mentioned above) first.
• Tables are created and the database configured (user accounts created etc.) during the first access
• We use the Derby's builtin user authentication mechanism.
• It is not possible to combine two or more SQL statements in Statement.execute* methods. More specifically, it is not possible to use an unescaped semi-colon character there. This is good because it prevents some variants of the SQL injection attack.

General notes

Almost all operations provided by the Web 2.0 Platform have to be invoked by a known, i.e. registered user. We therefore need some kind of authentication. The good news is, that servicemix-http component is ready for authentication out-of-the-box and that it uses a flexible JAAS framework. The bad news is, that the pre-configured authentication mechanism reads authentication data from property files and that the whole Servicemix container is considered a single JAAS domain. All deployables are therefore sharing a single JAAS configuration.

JAAS is very flexible and platform adopters can configure it to authenticate users using LDAP, WinNT, Kerberos and many other common services. As a pre-built solution, we have developed a simple JAAS Login Module capable of authenticating users using the 'Users' database table (see the ERD above). Passwords are not stored in a plain text there, we use an MD5 hash instead.

Configuration needed

To enable the pre-built authentication mechanism described above, it is necessary to do two things:

• Copy the web2platform-jaas-1.0-SNAPSHOT.jar archive containing the JAAS Login Module to the SERVICEMIX_HOME/lib directory (you can find it in the web2platform/core/web2platform-core-jaas/target directory after building the project)
• Add the following entry to the beginning of the JAAS configuration for the servicemix-domain in the SERVICEMIX_HOME/conf/login.properties file:

  cz.muni.fi.web2platform.core.JAASLoginModule sufficient;
  

General notes

Connectors are registered automatically by listening to SA deployment events.

Configuration needed

To enable automatic connector registration, copy the web2platform-core-listeners-1.0-SNAPSHOT.jar archive containing the service assembly life cycle listener to the SERVICEMIX_HOME/lib directory (you can find it in the web2platform/core/web2platform-core-listeners/target directory after building the project) and add the following snippet to the SERVICEMIX_HOME/conf/servicemix.xml file as a child of the beans/sm:container element:

<sm:listeners>
  <bean class="cz.muni.fi.web2platform.core.listeners.ServiceAssemblyListenerImpl" />
</sm:listeners>