http://www.nabble.com/Fornax-Platform-f17564.html
http://www.fornax-platform.org/cp/display/fornax/Hibernate+(CHB)
http://fornax-platform.org/tracker/secure/Dashboard.jspa
|
This is the Fornax Hibernate Cartridge documentation. The meaning of ’”cartridge’” in context of this document is defined as a bundle of artefacts (here: typical openArchitectureWare- Templates and Extensions, etc. and Java Classes). These artefacts are bundled to answer a well-defined purpose and can be used for Model Driven Software Development.
The challenge is to write a documentation, which is easy to understand on the one hand and gives enough detailed information on the other hand.
we are very happy about any fair comment. What is good or bad? What is described too detailed, or is there anything what has to be described not in that document?
There are many possibilities to contact us.
|
|
We are very happy about any feedback!
This chapter describes the installation of the Fornax Hibernate Cartridge. There are three different ways to run the Hibernate Cartridge:
The installation is shown in the next sections.
This chapter shows the installation of the Hibernate Cartridge if you want to use it in combination with ant .
Precondition: Apache ant is installed on your system. Open a shell and type:
ant -version
|
Ant should prompt its version. If no ant is installed please follow the installation instructions in the manual at: http://ant.apache.org/
In this case the installation is quite easy. First you should download the actual release from http://sourceforge.net/project/showfiles.php?group_id=166970&package_id=216043
To install the example extract the archive and then change to the fornax-cartridges-uml2-hibernate-parent-1.8.0 folder. Open a shell and call:
ant install
|
The build script will setup the environment. Now your working directory should look like this (Snippet of the relevant parts):
The istallation is complete!
To run the cartrige just call:
ant generate
|
The build.xml has to be extended by at last this properties and targets (An example build script is shipped within the release archive):
You can also modify the provided build.xml provided with the release. The lib.path has to point to
the provided lib folder of the release. The generate target calls a workflow.oaw. The workflow.oaw is
the openArchitectureWare build script what is calling the Fornax Hibernate Cartridge. You can simple
copy the example workflow.oaw from the release distribution (It is placed inside the example folder).
Copy both, the workflow.oaw and the workflow.properties into the src/main/resources
folder.
The further configuration is described in section 3.
We encourage to use the Fornax Hibernate Cartridge in combination with Eclipse. This section describes the installation of Eclipse and the Fornax Hibernate Cartridge. This chapter describes the setup of a development environment based on Eclipse 3.4.x or higher. The setup consists of two parts. The first part is the installation of Eclipse. Then the creation of the project structure is explained.
itemis AG provides an Eclipse 3.4.x distribution with openArchitectureWare 4.3.0. The distribution comprises the current version of Eclipse with the actual openArchitectureWare release and some other useful plugins.
Inside Eclipse:
Note: Don’t forget to remove the eclipse default source folder ’src’ first. Otherwise it is not possible to add the required source folders.
First of all you have to download the Fornax Hibernate Cartridge 1.8.0 release. It is hosted by
SourceForge.net and can be found on the Sourceforge Fornax Project page
http://sourceforge.net/project/showfiles.php?group_id=166970&package_id=216043
Download: fornax-cartridges-uml2-hibernate-parent-1.8.0-release.* ( * = zip or tar.gz) The distribution contains following artefacts:
Unzip the release. Add the jars within the lib folder to your classpath. Copy the Persistence_Profile.mdzip
model and the Persistence.profile.uml into the /src/main/recources folder of your Eclipse
project.
The hibernateCartridge.properties must be also placed in this folder. In some cases the it is
necessary to import also the generator project to avoid Eclipse warnings. The generator project is also
provided with the release.
The setup of the Eclipse environment is complete. At last you must configure your UML2 Modeling tool. This is described in section 2.4 on page 13.
This section shows the minimal configuration of the wrapping workflow calling the hibernate.oaw. If you want to integrate the cartridge into an existing workflow, your workflow has to be extended at last by the following components:
<workflow>
<property file="./workflow.properties"/> <component class="org.openarchitectureware.util.featureconfig.text.TextConfigurationReader"> <configFile value="${feature.model}" /> </component> <bean class="org.openarchitectureware.uml2.Setup" standardUML2Setup="true" /> <component class="org.openarchitectureware.emf.XmiReader"> <modelFile value="${model.file}"/> <outputSlot value="model"/> </component> <cartridge file="org/fornax/cartridges/uml2/hibernate/hibernate.oaw" inheritAll="true"/> </workflow> |
An example workflow can be found in the distribution zip inside the example folder. Further configuration is described in section 3.
This section describes the the setup of the UML2 Modelling Tool. The UML2 Modelling-Tool must support UML2 profiles. This manual and the examples shown will use Magic Draw. A profile consists of Stereotypes, Tagged Values and the dependencies between them. All Stereotypes used for the Hibernate Cartridge are defined in the Persistence profile. So you have to add the profile to your Magic Draw model.
The Persistence profile should now appear in the containment tree (see figure 2.1).
The configuration consists of two general parts. The first part is to define global generator properties, like file encoding, locations to generate the sources, etc. This is done by a general workflow.properties. An example of that workflow.properties can also be found in the distribution zip, located in the example folder (refer: 3.1.1).
The second part of the configuration is to customize the Hibernate specific properties. This properties can be customized by editing the hibernateCartridge.properties (refer: 3.1.2).
The general generation properties are defined in the workflow.properties. This file can
also be found in the release zip, located in the properties folder. The property files must
also be declared in the workflow. Check that the property files are declared in the workflow
file:
<property file="workflow.properties"/>
And optional:
<property file="hibernateCartridge.properties"/>
Inside the Hibernate Cartridge definition there is some stuff defined. Lets take a closer look on this.
First there are three outlets defined:
#The outlet to use to store code artefacts
outlet.src.dir =${basedir}/src/generated/java # The outlet to use to store non-code artefacts (configurations, sql-files and so on) outlet.res.dir =${basedir}/src/generated/resources #The outlet to use to store code artefacts. At this the # generator will checking whether the artifact to generate # already exists.If yes the generation of this artifact will # be skipped. outlet.src.once.dir = ${basedir}/src/main/java |
These are the locations, where the generated artefacts are placed. These three places should be defined in the workflow.properties. The last two important property is the model.file and property. It has to point to your model and to the hibernateCartridge.properties.
#The modelfile
model.file =./your-model.uml #The propertie file hibernate.properties.file = ’hibernateCartridge.properties’ |
The default values the Fornax Hibernate Cartridge handle with, are defined in the hibernateCartridgeDefaults.properties, placed in the Generator jar. Snippet of hibernateCartridgeDefault.properties see 7.3.2 on page 118
The values of the properties are Strings. They are used to generate the needed hibernate configuration files. This default will work with the HSQLDB 1.8.0.7 in an in memory configuration. If any of this values have to be customized, simply add the customized value in the workflow.properties.
Note that the hibernateCartride.properties is not used by the example workflow. Default values are
assumed instead (defined in the
org.fornax.cartridges.uml2.hibernate.hibernateCartridgeDefaults.properties inside the in the
fornax-hibernate-generator-1.8.0.jar). If you want to customize more of the Hibernate Properties, it is
recomented, to define this in the separate hibernateCartridge.properties.
At last the different features preProcessing mappings pojo and schemaExport can be separately enabled or disabled. To configure the features edit the hibernateConfig.txt. Snipped of the hibernateConfig.txt:
You can change the log-level by adding a log4j.xml in your project root. Add the entry:
<category
additivity="false" name="org.openarchitectureware"> <level value="debug"/> <appender-ref ref="ConsoleAppender"/> </category> |
The Fornax Hibernate Cartridge provides some customizing facilities. But in some cases, they are not sufficient and some Sourcecode or Templates have to be added or extended. There are some Extension Points defined, which allow the elimination of common problems. Extension Points are Template Definitions which are designed to extend the Templates by using aspect oriented programming (AOP) 1.
If some other Extension Points are recognized/ needed, please let us know!
AROUND org::fornax::cartridges::uml2::javabasic::templates::Entity::
import FOR uml::Class |
ARROUND org::fornax::cartridges::uml2::javabasic::templates::Entity::
classAnnotations FOR uml::Class |
The section shows the internal dependencies and the structure of the Fornax Hibernate Cartridge.
The workflow used by the Hibernate Cartridge is called hibernate.oaw. It consists of eight parts, which are executed in the shown order.
The individual components in detail:
The different features are indepented of each other and can be configured by the feature configuration model described in hibernateConfig.txt. Snipped of the feature configuration model see 7.3.1 on page 118
The Fornax Hibernate Cartridge comprises several copmonents. Some of them are optional. The
optional components are called features and can be configured by a simple text file:
hibernateConfig.txt (snipped 7.3.1).
Configuring the features is quite easy.
The preProcessor is an optional feature. By default it is disabled. You can enable it with the feature preProcessing. By default the preProcessor transformes every <<uml::Class>> into a <<Persistence::Entity>>. You can enable the preProcessor to run the Fornax Hibernate Cartridge with your existing domain model without changing it (you don’t have to apply the Persistence profile to your model).
Another usecase is to write some transformations. This allows the Fornax Hibernate Cartridge to
handle any input model. Therefore you must write your own advice. Overwirte the following
extension:
org::fornax::cartridges::uml2::hibernate::extensions::PreProcessing::start
for uml::Model.
The Version 1.8.0 of the Fornax Hibernate Cartridge provided some model-modifications. The purpose of them is to complete the model with default settings, to relieve the designer and let him concentrate on the important aspects. This modifications are always done on the current instantiated meta model instance. So no changes on the saved model were done!
This chapter explains, what are this model-modifications, when they fire (are executed), and what they do.
The first model-modification is the: nameUnnamedAssociationEnds(Model m) transformation, located in the Modeltransformation template. This modification is called for a model instance and checks it for unnamed association ends. If an unnamed association end is found, it is named with the type.
Example:
In this example both association ends are unnamed. The model modification thread this association, as it were named like in the following figure.
|
|
The second model-modification is the: createDefaultKeys(Entity e) transformation, located in the Modeltransformation template.
It is no more necessary to model the primary key as Key explicit. If no Key is modelled, the model modification completes the Entity with a Key for every new Generation. This model modification checks every Entity for an property of type Key. If no Key is found, a default key is is added. The default key is named id of type long.
Example:
The Hibernate Cartridge completes the left Entity with an Key so that it looks like the right.
|
|
Often the Fornax Hibernate Cartridge is only one of more cartridges to generate the whole application. In this scenario, you may want to derive more then java beans from an entity. E.g. you want to generate a persistent java bean placed in a pojo subpackage and a Data Access Object (DAO) for each entity. This maybe should be placed into a dao subpackage. Figure 4.3 illustrate this scenario.
The Fornax Hibernate Cartridge provides a posibility to realize this behavior. The pojo.package property defines an optional sub-package. In the example above the property is set to pojo. Leave this property empty if the generated artefacts should be placed into the modeled package.
This behavior is realized by overwriting the getFQNPackageName extension of the Fornax Java Basic Cartridge. The Extension Naming.ext contains an aspect doing this. If you need to determine the path or the full qualified name of the pojos in the subpackage, you have to import this extensions. The extension file contains a definition:
String getFQNPackageName(Persistence::Entity this)
|
that will determine the adapted fqn for entities.
The Checks are not an optional feature. They are performed every generation run. No configuration facilities are given. The model is checked. If any check fail, error massages will be prompted and the generation process will be stopped.
The FieldsAreNaturalKeys is an optional feature. If enabled the properties of an <<Entity>> without <<NaturalKey>> are handeled as <<NaturalKey>> (definition of <<NaturalKey>> see 5.7). If an <<Entity>> has at least one property declared as <<NaturalKey>> nothing is done.
Generation of the mappings can be enabled with the feature mappings. A lot of configuration facilities are given. Therefore look at the:
The most important configuration facilities are:
fileHeaderDoc = generated by Fornax Hibernate Cartridge
#hibernate.cfg.xml properties hibernate.dialect = org.hibernate.dialect.HSQLDialect hibernate.connection.driver_class = org.hsqldb.jdbcDriver hibernate.connection.url= jdbc:hsqldb:mem:test hibernate.connection.user= sa hibernate.connection.password= hibernate.connection.poolSize = 1 hibernate.currentSessionContextClass = thread hibernate.cacheProviderClass =org.hibernate.cache.NoCacheProvider hibernate.showSql = true hibernate.hbm2ddlAuto = create #hibernate O/R mapping properties hibernate.generatorClass = increment hibernate.access = property hibernate.auto-import = true |
The implementation of the domain objects is done with POJOs. The POJO-generation is done by the Fornax Java Basic Cartridge. Please refer the Java Basic Wiki for more detailed informations. Link to Wiki: ’ http://www.fornax-platform.org/cp/display/fornax/JavaBasic+%28CJB%29’. The generation of the POJOs is optional. You can configure it by customize the pojo feature within the hibernateConfig.txt.
The most important configuration facilities are:
The SchemaExporter can be enabled by the feature schemaExport. The schema export is done by invoking the Hibernate internal schema export tool. (org.hibernate.tool.hbm2ddl.SchemaExport)
The Fornax Hibernate Cartridge Domain Specific Language (DSL) comprises:
This chapter describes how to model a persistence model correctly. Every section explains another model element.
Note: Some elements of the profile are removed with the version 1.8.0 of the Fornax Hibernate Cartridge. Please refer the Fornax Wiki-Version side for more detailled information
(http://www.fornax-platform.org/cp/display/fornax/Versions).
Persistent classes are classes in an application that implement the entities of the business problem (e.g. Customer and Order in an E-commerce application). Not all instances of a persistent class are considered to be in the persistent state - an instance may instead be transient or detached.
Every class marked as Entity is treated as a persistent entity. Every attribute and every association to other entities or value types is made persistent. Every entity must have a name. The name must follow the common Java naming convention. Also it has to be placed into a package.
A Embedded Value is a contained object that is persisted as a value type, not an entity reference. Please refer the hibernate online documentation for more information: http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-component.
Every Embedded must be referred by an Entity. Every embedded must have a name. The name must follow the common Java naming convention. Also it has to be placed into a package.
An entity can own attributes. Every attribute is saved into the database.
—
Note: The multiplicity of a property affects two things.
Property or Collection:
Generation of the not-null constraint:
Entities can own attributes. Attributes have a name and a type. The name must follow the common Java naming convention. All UML2 basic types are supported. In addition to that the common Hibernate used Java-Types are supported (BigInteger, Timestamp, etc.). How to use them is described in 5.22 Data types. One attribute of each Entity can be declared as Primary Key. This primary key is described by the Stereotype key and explained in 5.6 Primary-Key Key. How to customize attributes see 5.5
A <<CollectionElement>> is an abstract base stereotype which are used for mapping collections. Fields or to-many associations can use the tagged values defined in this element.
Attributes and to-many associations can be stored in collections. Therefore Hibernate provides some more configuration facilities.
An entity can own attributes. Every attribute is saved into the database. A <<Field>> provides some more customize facilities. Please refer the hibernate online documentation for more information: http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-property.
Note: By assigning the stereotype <<Field>> to a property, the handling of the nullable constraint changed. The generated nullabe constraint corresponds to the tagged value nullable .
Entities can own attributes. Attributes have a name and a type. The name must follow the common Java naming conventions. All UML2 basic types are supported. In addition to that the common Hibernate used Java-Types are supported (BigInteger, Timestamp, etc.). How to use them is described in 5.22 Data types. One attribute of each Entity can be declared as Primary Key. This primary key is described by the Stereotype key and explained in 5.6 Primary Key Key.
Adding attributes to an Entity is like add attributes to a class. There are two ways to model attributes. The fast and easy way is to add a ’normal’ attribute (see figure ??: attribute: simple_attribute). All mapping properties will be generated with default values. But of cause, if you want to customize e.g. the columnName of the database table the Fornax Hibernate Cartridge provides a mechanism to do this. If any customizing is wanted, you must apply the Stereotype Field to the attribute (see figure ?? attribute: customizable_attribute). Then you can affect the generated O/R-mapping properties.
The Hibernate Cartridge is able to customize the primary key of an entity. Therefore the stereotype
<<Key>> is used. Please refer the hibernate online documentation for more information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-id.
Every Entity persisted by Hibernate needs a Primary Key. Therefore the Fornax Hibernate Cartridge provides the Stereotype <<Key>>. The name and the type of the primary key should respect this matter. The recommended modelling of the primary key is to add an Entity independent primary key. Note that it is not necessary to model a key for every entity explicit. The Fornax Hibernate Cartridge search every <<Entity>> for a <<Key>>. If no key is found, a default primary key is added to the <<Entity>>. This reduces the Entities on the relevant attributes.
Attributes can be declared as natural key. Please refer the hibernate online documentation for more
information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-naturalid.
Attributes can be declared as natural key. Snippet of the Hibernate Reference Documentation:
A natural key is a property or combination of properties that is unique and non-null. If it is also immutable, even better.
Creates a relational table index. Please refer the hibernate online documentation for more information: http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-property.
If an attributes is marked as <<Index>>, then an Index with the name of the Tagged Value index_Name is generated.
Snippet of the Hibernate Reference Documentation:
The optional verb+¡timestamp¿+ element indicates that the table contains timestamped data. This is intended as an alternative to versioning. Timestamps are by nature a less safe implementation of optimistic locking. However, sometimes the application might use the timestamps in other ways. Please refer the hibernate online documentation for more information: http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-timestamp.
If a attributes is marked as <<Timestamp>>, then a timestamp element is generated.
Snippet of the Hibernate Reference Documentation:
The ¡version¿ element is optional and indicates that the table contains versioned data. Please refer the hibernate online documentation for more information: http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-version.
If a attributes is marked as <<Version>>, then a version element is generated.
The Fornax Hibernate Cartridge is not able to support all of the features Hibernate provides. On the other hand you maybe dislike the way, the cartridge handles some things. In this case you are able to define Hibernate mapping for an attribute that fits all your needs. Iff you assign the stereotype <<CcustomMapped>> to a property, the generation of a mapping is not derived from the model. The custom mapping placed in the tagged value hibernateMapping is generated instead.
The generation of the Java-artefacts is not affected! Note: That is the only way to map enumerations at this time. A further support for enumerations is planned in the future. Please use our forum if you want to take part in the discussion.
If a attributes is marked as <<Version>>, then a version element is generated.
| Listing 5.1: | SnippedofStereotypeFieldTestsImpl.hbm.xml |
References from an entity to another entity or an value type is supported. Use associations to realise
them. The Hibernate O/R-mapping properties can be customised if the association is declared as an
<<EntityRelation>> (see description in 5.14). Please refer the hibernate online documentation for more
information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-manytoone.
—
Entities can have references to other Entities or value types. Value types cannot have references to other
value types or entities. The Fornax Hibernate Cartridge differs between ’normal’ associations on the one
site and compositions on the other. With compositions you model a- part-of relationship (see
5.13).
This is realized by setting the cascade attribute in the hibernate O/R-mapping to all whereas for the
other associations a save-update is generated. This behavior can be overwritten by using the Tagged
Value cascade .
The cardinalities of the association ends can be customized. The multiplicities 0, 1, * are allowed. Naming
an Association-End is optional. If the Association-End has no name, a name is added by an
model-modification during the generation Process (name of the association end = name of the referenced
entity or value type). Directed Associations are supported. If an association is ordered (isOrdered = true)
then a List is generated instead of an Set.
References from an entity to another entity or an value type is supported. If a reference is modeled as a
composition, a part-of-Relationship is modeled. The resulting Hibernate mappings take care of that.
Please refer the hibernate online documentation for more information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-manytoone.
—
Entities can have references to other Entities or value types. Value types cannot have references to other
value types or entities. The Fornax Hibernate Cartridge differs between ’normal’ associations on the one
site and compositions on the other. With compositions you model a- part-of relationship (see
5.13).
This is realized by setting the cascade attribute in the hibernate O/R-mapping to all whereas for the
other associations a save-update is generated. This behavior can be overwritten by using the Tagged
Value cascade .
—
References from an entity to another entity or an value type is supported. Use associations to realise
them. The Hibernate O/R-mapping properties can be customised if the association is declared as an
<<EntityRelation>> (see description in 5.14). Please refer the hibernate online documentation for more
information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-manytoone.
Entities can have associations to other Entities or value types. Value types cannot have references to other value types or entities. Use the <<EntityRelation>> for further customization.
—
Only a sub set of properties of an <<Embedded>> can be mapped to specific columns. Use dependencies pointing from <<UseSubSetOfComponent>> to the property.
—
<<UseSubSetOfComponent>> is always pointing from an <<Entity>> to an <<Embedded>>. Instead mapping all the properties of the embedded, only the properties which are the target of an dependency are mapped.
An entity Product has two mappings to a Person. A Buyer and a Seller both are of type Person. The Person has only a name and an address. Now we want to map the name and address with the prefix buyer_ and seller_.
—
A reference to another entity can also be part of an primary key of an entity. Please refer the hibernate
online documentation for more information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-compositeid.
Also references to other entities can be declared as primary key. This references are directed. Note that Hibernate strongly discourages the use of it!
References to other entities can be declared as natural key. Please refer the hibernate online
documentation for more information:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-naturalid.
References to other entities can be declared as natural key. This references are directed. Snippet of the Hibernate Reference Documentation:
A natural key is a property or combination of properties that is unique and non-null. If it is also immutable, even better.
It is possible to map inheritance of entities. Hibernate knows different ways to map inheritance. Please
refer the hibernate online documentation for more information about mapping Hibernate
strategies:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.htmlinheritance.html#inheritance-strategies.
The Fornax Hibernate Cartridge offers two ways to map inheritance. The first possibility, and the default,
is to create a table per sub class. The second way is to generate one table per inheritance hierarchy. Use
the <<TablePerClassHierarchy>> stereotype to use this strategy.
—
—
A simple inheritance mapping is done by the Hibernate joined-subclass inheritance mapping. Please
refer the hibernate online documentation for more information about mapping Hibernate
strategies:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-joinedsubclass.
Don’t mix different inheritance mapping strategies in one inheritance hierarchy.
This is the default inheritance mapping strategy. Therefore there is no difference between the use of a uml::Generalization and <<TablePerSubClass>>
—
—
—
Hibernate provides three different inheritance mapping strategies. This describes the Table per Class Hierarchy strategy. Please refer the Hibernate Reference Manual for more information about inheritance and the different inheritance strategies.
Use the stereotype <<TablePerClassHierarchy>> to use the table per class strategy mapping strategy
Please refer the hibernate online documentation for more information about mapping Hibernate mapping
strategy:
http://www.hibernate.org/hib_docs/v3/reference/en/html/inheritance.html#inheritance-tableperclass.
and the configuration facilities of the discriminator:
http://www.hibernate.org/hib_docs/v3/reference/en/html/mapping.html#mapping-declaration-discriminator.
—
Hibernate provides three different inheritance mapping strategies. This describes the Table per Concrete Class strategy. Please refer the Hibernate Reference Manual for more information about inheritance and the different inheritance strategies.
—
—
—
All standard UML2 data-types are supported naturally. If you want to use non standard UML2 data-types like java.math.BigInteger you have first to add the data type to your model manually.
All standard UML2 data types are supported naturally. If you want to use non standard UML2 data types like java.math.BigInteger you have first to add the data type to your model manually.
Therefore a data type has to be added in the right package. Example for java.math.BigInteger:
The data type is no ready for usage.
This chapter explains how to model a domain model with the Fornax Hibernate Cartridge. It is planned to explain all relevant features in node form. The goal is to write a look up and not larger examples. Therefore please refer the tutorials.
This document is not complete. If you want to provide some input, please contact me.
Some tools do not provide the standard data types like Integer, String or Boolean. And sometimes you want to add new data types like java.sql.Timestamp. This section explains how to create this data types.
The UML differ between uml::Datatype and uml::PrimitiveType.
If you want to use some of the listed data types below, please add an uml::Datatype to your model, placed in the appropriate package structure, e.g.:
To create some datatypes you need to define a uml::PrimitiveType:
At last, some Hibernate types are generated implicit:
This HowTo explains how to configure references between entities. Hibernate differs between a lot of different references.
|
|
1:1 references are mapped to many-to-one. Iff the reference is bidirectional the opposite side is mapped to one-to-one. The cartridge has to desice, which side become the ”one” end and which becomes the ”many” end.
To determine the ’many’ end, the following rules are used (decreasing priority):
The figure 6.5 shows an example for the most simple 1:1 reference.
The drawing of such a 1:1 reference causes this mapping:
| Listing 6.1: | SnippedofClassOne2Impl.hbm.xml |
Note: The 1:1 reference is mapped to <many-to-on> as you can see in listing 6.1. That is not a bug! This mapping is recommended by the Hibernate documentation!
Explanations: This end of the 1:1 reference is mapped to many-to-one because, the name of the
property (one1) is in a lexicographical lesser order as the opposite order (one2). The unique="true"
constraint is also recomented by Hibernate.
If the reference is bidirectional, the opposite side is mapped to <one-to-one>.
| Listing 6.2: | SnippedofClassOne2Impl.hbm.xml |
The figure 6.6 shows an example for a more complex 1:1 reference.
The drawing of such a 1:1 reference causes this mapping:
| Listing 6.3: | SnippedofClassOne2Impl.hbm.xml |
| Listing 6.4: | SnippedofClassOne2Impl.hbm.xml |
Explanations: Contrary to the last example, the end of the 1:1 reference is not mapped to many-to-one, because the end assigned to <<Field>> is the many side. If both sides are <<Fields>>, then the side with columnName set, is the many side. Also the column to map to is customized. Both sides have also an cascade constrain. This can be customized by setting the cascade tagged value. If this tagged value is set for the association then both sides inherit this constraint. It is also possible the configure this constrain for only one side, or for each side separately. In this case you have to configure the cascade tagged value of each association end.
The Fornax Hibernate Cartridge supports collections. The collections are implemented as Set or List. The cartridge differs between:
collections. Figure 6.7 shows some examples. Only one flag is evaluated for generation. The property list.set.property is set by default to order (the isOrdered-Flag is evaluated). You can overwrite this property by declare it in your workflow.properties.
Also many-tomany references are supported. Figure ?? shows the customizing facilities of many-to-many references.
The figure 6.8 shows a association with multiplicities 0..*. Note that one association end is ’not unique and have a name. The other association end is declared as ordered.
Ordered associations are generated as List. This takes effect in the Java classes (see Listing 6.5).
| Listing 6.5: | SnippedofAbstractBook.java |
Also in the O/R-mapping a List is generated. See the snipped in BookImpl.hbm.xml.
| Listing 6.6: | SnippedofBook.hbm.xml |
Not ordered associations implemented as Set. This takes effect in the Java classes. See the snippet in AbstractCustomer.java. Note that the name of the association end is wrapped up in the attributes name.
| Listing 6.7: | SnippedofAbstractCustomer.java |
Also in the O/R-mapping a Set is generated. See the snipped in CustomerImpl.hbm.xml.
| Listing 6.8: | SnippedofCustomer.hbm.xml |
Please try to customize the references by using the <<EntityRelation>>. Also the different ends of an association can be customized by applying the stereotype <<Field>>. Find a more detailed How-To in the next release!
Find a more detailed How-To in the next release!
This section shows how to realize the three possible inheritance strategies, provided by Hibernate. A closer description of the inheritance strategies is given in the Hibernate Reference Manual.
Hibernate supports the three basic inheritance mapping strategies:
In general inheritance is modeled by drawing an uml::Generalization between two classes (see 6.9). A generalization, without further configuration, like shown in fig 6.9 is mapped, by default to table per subclass strategy.
This strategy is the default strategy. That is if you declare an generalization as <<TablePerSubClass>> or not, this strategy is chosen.
The model snipped shown in 6.10 results in this mapping:
| Listing 6.9: | SnippedofSuperClassImpl.hbm.xml |
You can see that the SubClass is part of the SuperClass mapping. It is embedded into a joined-subclass tag (marked red in the listing above).
To use this strategy the generalization must be marked as <<TablePerClassHierarchy>>. Iff you want to use this strategy, informations about the discriminator has to be given. This informations can be configured by tagged values of <<TablePerClassHierarchy>>. Some of the tagged values are mandatory. If you forget to configure this mandatory tagged values, the generator will stop with an error message.
The model snipped shown in 6.11 results in this mapping:
| Listing 6.10: | SnippedofTablePerClassHierarchyImpl.hbm.xml |
To use this strategy the generalization must be marked as <<TablePerConcreteClass>>
The model snipped shown in 6.12 results in this mapping:
| Listing 6.11: | SnippedofTablePerConcreteClassImpl.hbm.xml |
The Fornax Hibernate Cartridge uses three different configuration files. The hibernateConfig.txt the hibernateCartridgeDefault.properties and the hibernateCartridge.properties.
This file should be placed in your resources folder. The name of the file can be customized. Just change the TextConfigurationReader of your workflow:
<component
class="org.openarchitectureware.util.featureconfig.text.TextConfigurationReader"> <configFile value="${feature.model}" /> </component> |
or change the feature.model in the workflow.properties.
Snipped of the feature configuration model:
The hibernateCartridgeDefault.properties are part of the
fornax-cartridges-uml2-hibernate-generator-X.X.X.jar To edit this properties, you have to copy
and edit the property in a property file, used by your workflow.
Snippet of hibernateCartridgeDefault.properties:
Snippet of hibernateCartridge.properties: Since version 1.4.2 of the Fornax Hibernate Cartridge some
properties are hold in the hibernateCartridge.properties file. You can change the name of the
property file by editing the property
hibernate.properties.file = ’hibernateCartridge.properties’ in the workflow.properties
The Fornax-Platform is a development platform for tools related to the Model-Driven-Software-Development - MDSD. In this context tools are cartridges, transforms, ready-to-use generators or simple enhancements to make it easier to work in a MDSD environment.
http://www.fornax-platform.org/
itemis AG: itemis AG is an independent IT consulting company that supports its customers in the planning, realization, and implementation of business solutions. Our mission is to work together with our clients to find the optimal route to the best solution.
Our extensive product and service offerings in the areas of Model Driven Architecture (MDA) and Service Oriented Architecture (SOA) is based on three pillars of successful IT projects:
build process, 7
build.xml, 7
Business Key, 25, 32
CheckComponent, 15
Checks, 17
CollectionElement, 23
Composition, 29
Configuration, 11
Contact, 5
CustomMapped, 27
Data-Types, 34
Datatype, 36
BigDecimal, 36
BigInteger, 36
binary, 36
byte[], 36
Calender, 36
Currency, 36
custom data type, 36
Date, 36
Locale, 36
String, 36
text, 36
Time, 36
Timestamp, 36
TimeZone, 36
Dependency, 30
DSL, 20
Eclipse, 7
Embedded, 21
Entity, 20
EntityRelation, 30
Feature
hibernate_dirCleaner, 15
Mappings, 17
mappings, 12, 15
pojo, 12, 15, 18
preProcessing, 12, 15
schemaExport, 12
Feature configuration, 12
feature configuration model, 15, 48
Features, 14
FeaturesSchemaExport, 19
Field, 23
FieldsAreNaturalKeys, 17
Fornax-Platform, 5
Forum, 5
Generalization, 32
hibernateCartridge.properties, 11, 49
hibernateCartridgeDefault.properties, 11, 48
hibernateConfig.txt, 15, 48
hilo, 25
HowTo, 36
Index, 26
Inheritance, 32–34, 42
Installation, 6
inverse, 37
isOrdered, 39
isUnique, 39
joined-subclass, 33
Key, 24
KeyReference, 31
List, 39
Logging, 12
lowercase, 18
Mapping, 36
Model-to-Model-Transformations, 15
NaturalKey, 25
NaturalKeyReference, 32
one-to-many, 39
pojo.package, 17
PrimaryKey, 24
Project structure, 8
Properties, 11
Property, 22
Reference, 37
Set, 39
Stereotype
CustomMapped, 47
EmbeddedValue, 47
Entity, 47
EntityRelation, 47
Field, 47
Index, 47
Key, 47
KeyReference, 47
NaturalKey, 47
NaturalKeyReference, 47
Non_Persistend, 47
TablePerClassHierarch, 47
TablePerConcreteClass, 47
TablePerSubClass, 47
Timestamp, 47
UseSubSetOfComponent, 47
Version, 47
subclass, 33, 34
subpackage, 17
table per class hierarchy, 42, 44
table per concrete class, 42, 45
table per subclass, 42
TablePerClassHierarchy, 33
TablePerConcreteClass, 34
TablePerSubClass, 33
Timestamp, 26
Tracker, 5
Transformations, 16
UML2 Modelling Tool, 9
union-subclass, 34
uppercase, 18
UseSubSetOfComponent, 30
Value Type, 21
Version, 27
workflow.oaw, 9
workflow.properties, 11
XtendComponent, 15
