RDBMS Persistence

Resoa persistence enables the auto-generation of a database schema out of a Java service model. Write / Read transactions of bean instances are resolved on the fly due to the resoa.persistence.xml declaration. Currently we support MYSQL and POSTGRESQL, other database might be integrated by adding a dedicated JavaToSQL type mapping.

Java type to SQL type mapping

As there does not exist a clear standard for this mapping, Resoa persistence looks for a <databasename>.typemap.xml file on classpath root. Per default the resoa.persistence jar contains a mysql.typemap.xml and a postgresql.typemap.xml file. For overwriting this mapping add a database specific typemap file into a folder config under your JRE runtime root. Some generic rules about mapping:

  • Simple bean properties are directly mapped to a SQL type
  • Column name is the java property name in lower case. If it is reserverd SQL key word, ‘_’ is prepended.
  • Arrays are marshalled to JSON string during runtime, so use TEXT or VARCHAR within your database. Resoa currently supports java.util.List and java.util.Set, avoid using java.util.Map properties within your service model. Be aware of fixed length issues in your SQL database, this might cause errors during Java to JSON serialization.
  • Enums need a TEXT or VARCHAR column type as well. Again, be aware of fixed length issues, this might cause errors curing Java to JSON serialization.
  • Resoa creates only one table for inherited types. If the persistor recognizes an inheritance structure within your service model, it adds a SQL schema column ‘java_class’ (java.lang.String) to the table. Please do not use this name as property name within your service model!

Define service domain specific type mappings within your resoa.persistence.xml file

There might be service specific requirements which should overwrite the default mapping (i.e. for fixing any VARCHAR length issues). You can define a domain specific mapping within the resoa.persistence.xml. An example:

<PersistenceConfig xmlns="http://www.resoa.org/persistence/model" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
	<!-- -- -- -- -- -- -- -- -- -- -- -- -- --->
	<!-- put your Persistent declaration here -->
	<!-- -- -- -- -- -- -- -- -- -- -- -- -- --->
	<!-- Add database specific type mappings -->
	<SQLTypeMap database="mysql" version="5+" defaultLengthCHAR="80" >
	<Map fieldName="id" sqlType="VARCHAR" length="36"/>
	<Map fieldName="code" sqlType="VARCHAR" length="16"/>
	<Map fieldName="_name" sqlType="VARCHAR" length="50"/>

Scheme/Table Creation/Update Strategy

When adding a service domain to the persistor, the schema structure in the database is generated or updated. Principles:

  • The database scheme name deviates from the service domain name. If the schema does not exist, a new schema is created.
  • Every simple bean property is maps to a table column. Inherited types use one common table, a column named ‘java_class’ stores the java class name.
  • A n:m relation table is required if a relation property is of the type java.util.List or java.util.Set and this relation is declared within resoa.persistence.xml.
  • A foreign key column is added to the reference type table, if a property is of type java.util.List or java.util.Set and it is NOT declared within the resoa.peristence.xml.
  • 1:1 relations result in a foreign key column within the “relation from” table.

Definition of datasources

Resoa peristence needs datasource handles for performing transactions to your database. ResoaGateways look for JNDI defined datasources during startup. You also can define them within the GridInfo.xml file. There is no need to declare a datasource for every schema, just create a valid handle for a connection with read/write and schema generation permission.