The wsag4j implementation provides mechanisms to persist agreement instances. By default agreements only exist as long as the wsag4j instance is running. To persist the agreements, you have to change the wsag4j engine configuration to use the corresponding persistence layer implementation and the persistence-enabled agreement factory.
The default implementations are the
and
classes.
The GenericAgreementFactory provides the functionality to create new agreements, list all agreements, etc. DatabaseWSAG4JPersistence instances are used to provide a database-driven persistence. All agreements are wrapped by some kind of container, which allows the engine to store and retrieve all required information.
To use the persistence functions, you first have to provide the database configuration, described in the next section, and after that have to change the engine configuration.
To use the persistence capability you have to provide a valid database configuration. This is done by adding a persistence.xml file inside the META-INF folder. This configuration file is used by the Java Persistence API (JPA) to build the database connection, configure the cache behaviour, etc. The default server distributions already contains an database configuration. It can be found in inside the war archive (META-INF/classes/META-INF/persistence.xml).
The following snipplet shows the default productive configuration of the wsag4j system. Each persistence unit is identified by a unique name (wsag4j_file). The provider element specifies the persistence provider to be used. In wsag4j OpenJPA is used; alternatives are Eclipselink or Hibernate.
For each entity class, which should be accessible by the database subsystem, a class element must be specified, which contains the whole package and class name. Following a snipplet, which illustrates a valid database configuration.
<persistence-unit name="wsag4j_file" transaction-type="RESOURCE_LOCAL"> <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> <class>org.ogf.graap.wsag.wsrf.persistence.AgreementEprContainer</class> <class>org.ogf.graap.wsag.server.persistence.impl.PersistentAgreementContainer</class> <properties> <property name="javax.persistence.jdbc.url" value="jdbc:hsqldb:file:$PATH_AND_FILENAME$"/> <property name="javax.persistence.jdbc.driver" value="org.hsqldb.jdbcDriver"/> <property name="javax.persistence.jdbc.user" value="sa"/> <property name="javax.persistence.jdbc.password" value=""/> <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(SchemaAction='refresh')" /> <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/> <property name="openjpa.RuntimeUnenhancedClasses" value="supported"/> </properties> </persistence-unit>
The displayed configuration can be used for the default (webservice-enabled) package of wsag4j. If you want to extend or use only the core server module, you have to remove the org.ogf.graap.wsag.wsrf.persistence.AgreementEprContainer class entry.
Since the default persistence unit uses an file-based database, you have to specify a location for the database-file storage. For this change the $PATH_AND_FILENAME$ marker to your needs. By default (as delivered in the default distribution) this is /tmp/wsag4j-testdb.
All JPA- and database-specific configurations are handles by the properties element. The first four configurations are JPA2-specific and valid for all supported persistence providers. The later configurations are specific to the used OpenJPA and need to be replaced, if you want to switch to another persistence provider:
Driver-specific JDBC connection URL. By default a HSQLDB is used, which can be run in a file-based or memory-only mode. Since the agreements should be persisted, you have to replace $PATH_AND_FILENAME$ with a valid relative or absolute path and filename, which is OS-dependent.
If you want to use another database, for instance a PostgreSQL, you have to change the JDBC url to the correct once.
Fully qualified name of the driver class. This depends on the JDBC-driver and the databasem, which should be accessed.
Name of the database user. In case of HSQLDB this setting can be used to restrict the access to the file-based database.
Password of the database user. In case of HSQLDB this setting can be used to restrict the access to the file-based database.
Defines the synchronisation behaviour of OpenJPA. By default OpenJPA does not modify a once created database schema (on the DB-side). For the persistence of agreements we use buildSchema(SchemaAction='refresh'). This enables OpenJPA to modify the DB-side schema, if it detects any change in the entity classes. More information can be found in the OpenJPA: Mapping chapter of the documentation.
OpenJPA allows the configuration of separate log-levels for different parts of the JPA. BY default it is set to DefaultLevel=WARN, Tool=INFO. An overview of all possible parts and configuration can be found in the OpenJPA: Log chapter of the documentation.
OpenJPA allows the usage of enhanced and unenhanced classes. Enhanced classes are extended with further logic, for instance to prevent unnecessary list iterations, to enable lazy-loading. The enhancement is done by the runtime, an Ant task or whatever. By default OpenJPA allows only enhanced classed to be used. In some cases it is useful to allow unenhanced classes; for this set this property to supported. More informations can be found in the Omitting the OpenJPA enhancer section of the documentation.
To allow the engine to use different kinds of storage, for instance for testing you want to use an In-memory database, the persistence layer allows the configuration of three different persistence units. Each of the different persistence unit configurations just changes the place, where the data is stored:
To change the default persistence unit in use (wsag4j_file) you can use the setPersistenceMode() method of the org.ogf.graap.wsag.server.persistence.util.EmfRegistry class or set the wsag4j.persistence.mode system property. To access the correct persistence unit you should use one of the three static constants defined in the EmfRegistry: PERSISTENCE_MODE_MEM, PERSISTENCE_MODE_FILE or PERSISTENCE_MODE_TEST. Then you can change the used persistence unit at the beginning of your unit tests or during the startup of your application server/the deployment of the wsag4j instance. If non of the three settings is in some kind provided, the EmfRegistry always selects the wsag4j_file configuration.
The following snipplet gives you an example of a valid configuration (in the wsag4j engine configuration):
<wsag4j-config:Factory> <wsag4j-config:FactoryImplementation> <wsag4j-config:ImplementationClass>org.ogf.graap.wsag.server.engine.GenericAgreementFactory </wsag4j-config:ImplementationClass> </wsag4j-config:FactoryImplementation> <wsag4j-config:PersistenceImplementation> <wsag4j-config:ImplementationClass>org.ogf.graap.wsag.server.persistence.impl.DatabaseWSAG4JPersistence </wsag4j-config:ImplementationClass> </wsag4j-config:PersistenceImplementation> </wsag4j-config:Factory>
The ImplementationClass should be set to the (default) value GenericAgreementFactory, the ImplementationClass has to be changed from SimpleWSAG4JPersistence to DatabaseWSAG4JPersistence.
By using the DatabaseWSAG4JPersistence database-enabled persistence implementation, wsag4j persists all agreements in the configured (relational) database. Each agreement is wrapped in some kind of container, which allows the storage and the retrieval of all required information. See the next section for further details about the implementation.
The persistence-related functions were implemented inside the org.ogf.graap.wsag.server.persistence.impl package. All information, which need to be stored, are capsuled by the class DatabasePersitentAgreement and the entity class PersistentAgreementContainer. Detailed information about the internal implementation can be found in the Javadoc documentation of the package.