synon2hbm - Manual.

synon2hbm Manual

This is a work in progress, and currently very, very incomplete...

Configuration
Dependencies
Customizing generated classes
- Files
- Fields

When starting a new project, where you want to use synon2hbm, we recommend starting with a copy of synon2hbmDemo. You don't have to organize your project as synon2hbmDemo, of course, but in the following, we assume that things are organized as in synon2hbmDemo.

/src/java: This is where most of your java source files goes.
/src/types: Customized classes for Synon types. This is also manually written (or maintained) source code, but it influences what is generated.
synon2hbm generates two classes for each field declared in Synon. For a Synon field called CustomerName it will generate GeneratedCustomerName.java and CustomerName.java. CustomerName extends GeneratedCustomerName, but dosn't add anything to it. If you want to customize CustomerName, move it from /gen/src to /src/types, and add whatever methods you need.
The next time you run synon2hbm, it will see your modified class, and only generate GeneratedCustomerName.
Other classes which should be available to synon2hbm sould also go here. If you can't use the hibernate mappings generated by synon2hbm, this is also where you should put the Hibernate mappings (.hbm.xml files) and UserTypes you write.
/src/test: JUnit tests.
/gen/java: Generated code (java files and hibernate mappings).
/build-resources: Configuration files and other artifacts for synon2hbm to use.
A few configuration files are directly under /build-resources so that programs looking for their configuration files in the classpath can find them. The rest is in subdirectories under /build-resources.
/build-resources/conf: Configuration files.
/build-resources/hbmFragments: Hibernate mapping fragments (or Velocity macros to generate Hibernate mapping fragments) which synon2hbm will include in the hibernate mappings it generates.
synon2hbm does not automatically map associations. Although they in theory could be generated to match the relations declared in Synon (OWNED-BY, REFERS-TO and EXTENDED-BY), it is our expirience that that is normally not exactly what is needed. So for maximum flexibility you must manually specify how each relation shuld be mapped. However, templates are provided, so in most cases that is very easy.

Configuration Files

/build-resources/generatorContext.xml: A Spring ApplicationConext configuration - the primary configuration file for synon2hbm.
/build-resources/jdbc.properties: JDBC properties. Here you specify the location of the Synon model and a username and password to use to connect to it.
/build-resources/log4j.properties: log4j configuration. Normally you don't have to change this, but if you need debug logging for synon2hbm or Hibernate, this is the place to specify it.
/build-resources/conf/generator.properties: synon2hbm configuration. Most configuration data for synon2hbm is in /build-resources/generatorContext.xml, but some simple settings was moved to this property file to make them accessible for the build script also.
/build-resources/hbmFragments: Hibernate mapping fragments (or Velocity macros to generate Hibernate mapping fragments) for associations.
build.xml: The build-script. Use the one from synon2hbmDemo, but modify it to (at least) reflect the name of your project.

Synon User Defined Field Types

In Synon there are a number of predefined field types, but it is also possible to define new types.

If synon2hbm encounters fields of such user-defined types it will not generate Java classes for them but log a warning like this:
Skipping DET field DVN Geboortedatum

Later the POJO generation vil fail with a stacktrace similar to this:

[hibernatetool] org.hibernate.MappingException: 
Could not determine type for: nl.iza.reveng.hibernate.DVNGeboortedatumUserType, for columns: [org.hibernate.mapping.Column(BWADDE)]
[hibernatetool]         at org.hibernate.mapping.SimpleValue.getType(SimpleValue.java:265)
[hibernatetool]         at org.hibernate.tool.hbm2x.Cfg2JavaTool.getRawTypeName(Cfg2JavaTool.java:587)
...(rest of stacktrace omitted)

In this case the field named DVNGeboortedatum was declared as a DET field in Synon.

To resolve this, you must define the field type in build-resources/generatorContext.xml.
In the above example DET was actually a date-field, so DET was added in the list of types defined in <property name="dateTypes"> So: before the list of dateTypes was:


	<property name="dateTypes">
	<set>
	<value>DTÆ</value>
	</set>
	</property>

and the working version is:


	<property name="dateTypes">
	<set>
	<value>DTÆ</value>
	<value>DET</value>
	</set>
	</property>

Dependencies

Since we depend very heavily on Spring, we strive to limit dependencies to whatever is supplied with Spring.
Therefore the /lib directory is more or less a copy of the /lib directory from the spring-framework-with-dependencies download bundle available from the Spring SourceForge project download site (we did remove some of the .jars we don't use, though) plus:

spring.jar (in /lib/spring)
hibernate-tools.jar (in/lib/hibernate-tools)
JDBC drivers from jtOpen (in /lib/jtopen)

Customizing generated classes

Files

In the generator configuration in generatorContext.xml you can set the following attributes to control how file-classes are generated:

fileSuperclasses

A <map> in which you - for each file - may specify a class to be used as a superclass for the class generated for that file. Here's an example:

<property name="fileSuperclasses"><map>
	<entry key="SomeFile" value="AbstractSomeFile"/>
	<entry key="AnotherFile" value="AbstractOtherFile"/>
</map></property>

fieldSettings

Another <map>, where the key is a file name, and the entries are maps which specify settings for fields in that file. In this "secondary" <map/gt; the key is a fieldname (the database field name - not the name normally used in *:2E), and the value is one of these:

ignore: Do not generate Hibernate mapping for this field. Use this if you dont't want the field included in the Hibernate mapping at all, or if you wish to hand-code the mapping (you may write part of the hibernate mapping file manually, and have synon2hbm include your xml in the generated hibernate mapping file.
version: Map the field as a version field. Note that *:2E does not have any support for version fields, so you must manually code all the create-object and change-object functions in *:2E so that they initializes and updates the version number.
identity: Map the field as an identity field. Note, that identity fields are not directly supported by *:2E. However, we have some files, which was created with identity fields using SQL, and "imported" into *:2E as "Assimilated physical" files, and therefore support for identity fields was also added to synon2hbm.

Here's an example:

<property name="fieldSettings"><map>
	<entry key="SomeFile"><map>
		<!-- Price fields are manually mapped to a Pricelist component -->
		<entry key="AUBVQT" value="ignore"/>
		<entry key="AUAVN9" value="ignore"/>
		<entry key="AUAUN9" value="ignore"/>
		<entry key="AUZQN9" value="ignore"/>
	</map></entry>
	<entry key="YetAnotherFile"><map>
		<entry key="APKAID" value="identity"/>
		<entry key="APVER" value="version"/>
	</map></entry>
</map></property>

Fields

For each *:2E field synon2hbm generates three of four classes. For a field called "Field X" it will generate:

FieldXUserType.java: A Hibernate UserType which Hibernate uses to convert between database values and GeneratedFieldX objects.
This class is always generated.
GeneratedFieldX.java: This class contains most of the generated code. For status (STS) fields it declares constants matching each status condition value defined on the field in *:2E.
This class is always generated.
FieldXCondition.java: This is only generated for status (STS) fields. It declares all the conditions defined for the field in *:2E.
FieldX.java: This class is only generated if it dosn't already exist in the classpath. When it is generated it is just an almost empty (it has some constructors) class, which extends GeneratedFieldX. This means, that if you need to add methods to a field, this is where you should do it. Move the .java file out of the generator output folder (but make sure it is still available on the classpath, when you run the generator again), and modify it as needed.
The next time you run the generator, changes made in *:2E will be reflected in your FieldX because GeneratedFieldX.java is regenerated, but FieldX.java will not be touched, and therefore your modifications will be preserved.