Getting Started

The Service Domain Conception of Resoa

Resoa persistence bases on the resoa.services project and its service domain conception. Summery:

  • A resoa servive domain is represented by a JAR file, containing the interfaces¬†and implementation classes of your domain. The domain name is defined by the JAR¬†file name, the JAR must have a resoa.xml file within the META-INF folder.
  • Resoa persistence creates a database schema for every service domain. Multi-domain persistence is not yet supported.

How to declare Java types as persistent ?

Create a resoa.persistence.xml within your  domain Jar META-INF folder with the root entity PersistenceConfig. An example:


<PersistenceConfig xmlns="http://www.resoa.org/persistence/model" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
	<!-- Declare the Student type as persistent -->
	<Persistent className="org.resoa.test.xsd.Student" encrypted="false" compressed="true" autoKeyGenerator="org.resoa.persistence.autokey.UUID">
		<!-- declare the relations, which should be resolved during object persistence -->
		<Relation fieldName="mainCourse" type="CREATE"/> <!-- the course will be created, if not yet exists. No updates of existing records -->
		<Relation fieldName="studies" /> <!-- default relation type is CREATE_UPDATE -->
		<Relation fieldName="user" type="LINK_INSIST" /><!-- LINK-INSIST defines a consistency, the user must exists, otherwise the student store will throw an exception -->
	</Persistent>
	<!-- declare the linked type Course as persistent -->
	<Persistent className="org.resoa.test.xsd.Course" encrypted="true" compressed="true" > <!-- course key is defined by XSD Type/Annotation ID -->
		<Relation fieldName="teacher" type="CREATE" />
	</Persistent>
	<!-- declare the linked type teacher as persistent -->
	<Persistent className="org.resoa.test.xsd.Teacher" primaryKeyField="autoID" autoKeyGenerator="org.resoa.persistence.autokey.UUID" />
	</Persistent>
	<!-- declare the linked type User as persistent -->
	<Persistent className="org.resoa.test.xsd.sub.TestUser" encrypted="true" primaryKeyMethod="getUserid"/>
</PersistenceConfig> 

This file declares the bean org.resoa.test.xsd.Student as persistent. The relations of the bean Student to ‘mainCourse‘ and ‘studies‘ should become resolved, the related type (org.resoa.test.xsd.Course) is declared as persistent as well. Don’t forget about defining a key property for every persistent type.

Can I declare persistence by annotations as well?

As Resoa recommends using code generators for creating service object models, adding annotations to a Java classes depend on the generator functionality. In general we believe, declaring the persistence within a XML does not cause so many efforts. Anyway, fields with annotations @Id, @XmlId or @PrimaryKey are identified as primary key fields without XML declaration. If you use these annotations, it is enough to specify the root type as persistent, relation types are automatically persistent, if a primary key field can be identified.

Setting up Resoa Persistence

org.resoa.persistence.Persistor provides an implementation of the org.resoa.grid.ResoaPersistence interface. ResoaGateways create an instance of the persistor during initialization, you easily can use within your services by calling myGateway.getPersistence(). If you like to work without ResoaGateways, call the constructor with following arguments:

  • ResoaDomainExplorer: Check the Resoa service documentation for more information about Resoa Service domains. The DomainExplorer examines all Jar’s on the environment path for Resoa Service implementations.
  • ResoaGateway:¬†ResoaGateways provide access to your services by several nodes within a ‘grid’. Resoa persistence supports the grid persistence independently from the storage backend. Check the grid persistence chapter for more information about. If you don’t need support for grid persistence, pass NULL here.
  • CacheManager: You might¬†provide a custom org.resoa.peristence.CacheManager implementation i.e. for¬†ehcache support. By default, Resoa persistence uses a memory based caching.

If you like to enable a service domain for persistence, call  peristor.addPersistenceDomain. Arguments are the DomainDescriptor for your service domain (check ResoaDomainExplorer for retrieving instances) and the XML declaration instance of resoa.persistence. If you provide null here, the instance of PeristenceConfig will be generated out of the META-INF folder of the service domain jar.

Configuration of persistent domains

Detailed configuration of domain persistence is done within the GridInfo.xml. ResoaGateways look for this file within the gateway root folder, for local persistor instances invoke setGridInfo before adding domains. Beside the Resoa grid configuration you might specify the domain database transition (BTREE or SQL) and JDBC datasources.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GridInfo xmlns="http://www.resoa.org/topology"  xmlns:stack="http://www.resoa.org/stack/config" persistenceFactory="org.resoa.persistence.PersistenceFactory">
	<!-- Persistence domain configuration --> 
	<!-- define the database transition for a persistent domain --> 
	<PersistenceDomainConfigs domain="org.foo" dbTransition="org.resoa.persistence.rdbms.SQLTransition" dbType="mysql" />
	<!-- for grid persistence you might specify the database for the resoa transaction (default is BTREE) --> 
	<PersistenceDomainConfigs domain="resoa.persistence" dbTransition="org.resoa.persistence.rdbms.SQLTransition" dbType="postgresql" sqlSchemaName="resoa_transactionlog" /> 
	<!-- Datasource configuration -->
	<!-- Root datasource for MySQL (used for database and schema generation -->
	<DataSources className= "com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource" dbType = "mysql">
		<Set name="ServerName" value="localhost" />
		<Set name="PortNumber" value="3306" /> 
		<Set name="User" value="resoa_node" />
		<Set name="Password" value="anysecret" /> 
		<Set name="UseUnicode" value ="false" />
		</DataSources> 
		<!-- Root datasource for postgresql, here we use apache dbcp pooling -->
		<DataSources className= "org.apache.commons.dbcp2.BasicDataSource" dbType = "postgresql">
		<Set name="DriverClassName" value="org.postgresql.Driver" />
		<Set name="Url" value="jdbc:postgresql://127.0.0.1:5432/postgres" />
		<Set name="Username" value="resoa_node" />
		<Set name="Password" value="anysecret" /> 
		<Set name="MaxTotal" value="80" />
	</DataSources>
</GridInfo>

Working with Resoa Persistence

Here are some Java code examples

public void example (User user, ResoaResponse response, ResoaGateway gateway) {
// Use the Persistor instance for all storage operations
try {
	// Read from storage
	User dbUser = gateway.getPersistence().read("anyID", User.class);
	// Store an object instance
	gateway.getPersistence().store(user);
	// Delete from storage
	gateway.getPersistence().delete("anyID", User.class);
	// Store an instance only, if the key does not exist yet
	gateway.getPersistence().createNew(user);
} catch (PersistenceException e) {
	// handle errors here
}}