- Customization basics
- Customizing classes
- Customizing properties and associations
- Selecting the identifier property
- Selecting the version property
- Customizing the basic property
- Customizing the many-to-one property
- Customizing the one-to-one property
- Customizing the one-to-many property
- Customizing the many-to-many property
- Customizing the embedded property
- Customizing the generated identifier property
- Customizing the generated version property
- Customizing generated properties
- Customizing default mappings
- Customizing default mappings - Introduction
- Customizing the default entity
- Customizing the default mapped superclass
- Customizing the default embeddable
- Customizing the default identifier property
- Customizing the default generated identifier property
- Customizing the default embedded identifier property
- Customizing the default version property
- Customizing the default generated version property
- Customizing the default basic property
- Customizing the default to-one mapping
- Customizing the default to-many mapping
- Customizing the default many-to-one mapping
- Customizing the default one-to-many mapping
- Customizing the default one-to-one mapping
- Customizing the default many-to-many mapping
- Customizing the default embedded mapping
- Miscellaneous customizations
- Per-type customization
- XML Schema for customizations
There is no "one and only true" object-relational mapping for your classes. There are many ways to express object constructs, properties and associations relationally.
By default, Hyperjaxb3 does its best to generate the most suitable and reasonable mappings. However, Hyperjaxb3 also allows you to influence the generated object-relational mappings or annotations using the constomization elements.
Hyperjaxb3 customization elements are essentially XML elements in the Hyperjaxb3 customization namespace associated with target XML Schema constructs (complex types, elements, the schema itself and so on). This association can be done directly in the schema file or alternatively in external binding files.
When Hyperjaxb3 processes schema constructs, it detects the associated customization elements and use the provided information to customize the generated mappings.
Customizing in schema and in binding files
As mentioned before, customization elements can be provided directly in schema or in external binding files. In both cases you'll need to define customization namespaces:
This is done by adding the appropriate prefixes (
orm for the declarations above) to the
In you customize in schema, this will look as follows:
If you're customizing in an external binding file
Note that in the declaration above the inner
jaxb:bindings element is associated with the target schema located in
src/main/resources/schema.xsd (schema location
schema.xsd relative to the binding file
If you want to define customization elements directly in schema, just include them into
xsd:annotation/xsd:appinfo elements into the target construct. The following example associates the
hj:basic customization element with
productName element of the
Items complex type:
On the Java side the customization above is applied to the
productName field of the
Items class. The
hj:basic/orm:column/@length="1024" element instructs Hyperjaxb3 to generate the following property annotation:
As the result, the
PRODUCTNAME column of the
ITEMS database table will have the length of 1024.
If you prefer to customize in external binding files, you'll have to associate customization elements with target constructs using XPath expressions in
In this example, outer
jaxb:bindings element is associated with the
xs:schema element of the
schema.xsd schema. Inner
jaxb:bindings element is associated with the
productName element of the
Items complex type defined in this schema. This customization is actually the same as the in-schema customization demonstrated earlier.
Hyperjaxb3 customizations and JPA ORM mapping elements
Hyperjaxb3 customization elements are defined in the XML schema which can be found here. This schema is based on the XML schema for JPA persistence object-relational mapping. In fact, most of the Hyperjaxb3 customization elements are slightly extended or slightly modified elements of the JPA ORM schema. For instance,
hj:basic element we've seen in examples above is a modification of the
orm:basic element. Main difference between Hyperjaxb3 elements and ORM elements is that Hyperjaxb3 elements like
hj:one-to-many do not specify the target field or property name.
The fact that Hyperjaxb3 elements are based on JPA ORM elements may help you to understand, which customizations you need to define for Hyperjaxb3 in order to get some specific result. I'll illustrate this with the following example.
Per default Hyperjaxb3 maps 1:M relationships as one-to-many associations using a join table. Consider the following schema fragment:
This will be represented by the following JPA annotations:
The corresponding JPA mapping in XML will look as follows:
Now, assume you want 1:M join to be implemented via a join column (instead of a join table). If you were to define your JPA mapping in XML, you'd write something like:
To corresponding customization will look as follows:
And the generated annotations will be:
In order to customize a class you need to associate your customization with the appropriate XML schema construct which produces the class. Typically it is the complex type from which the class is derived. Here's a couple of examples.
Customizing complex type directly in schema:
Customizing an anonymous complex type using external bindings:
Hyperjaxb3 supports the following customization elements for classes:
hj:ignored- ignores the class;
hj:enity- maps class as entity (default), customizes the entity mapping;
hj:mapped-superclass- maps class as mapped superclass, customizes the mapped superclass mapping;
hj:embeddable- maps class as embeddable, customizes the embeddable mapping.
Please note that these four customization options are mutually exclusive.
hj:ignored element instructs Hyperjaxb3 not to map a certain class. Ignoring a class has the following consequences:
- No annotations or mappings will be generated for the ignored class as well as its subclasses.
- All properties and associations referencing this class will be made transient.
By default, Hyperjaxb3 maps schema-derived classes as entities (unless otherwise specified by customizations). The
hj:entity element customizes the generated entity mapping.
One of the most frequent usages of
hj:entity customization is to customize table name for the entity:
Here's how you override the inheritance strategy:
Cutomizing mapped superclass
In JPA, an entity may inherit from a superclass that provides persistent entity state and mapping information, but which is not itself an entity.
hj:mapped-superclass element allows you to map a schema-derived class as such "mapped superclass" instead of entity.
Customizing embeddable classes
JPA defines a notion of embeddable class:
An entity may use other fine-grained classes to represent entity state. Instances of these classes, unlike entity instances themselves, do not have persistent identity. Instead, they exist only as embedded objects of the entity to which they belong.
If this notion better represents the semantics of your schema-derived class, you can map it as embeddable class using the
Customizing properties and associations
In order to customize a schema-derived property you need to associate your annotation with the appropriate XML schema construct. This is typically
Supported customization elements for properties or associations are:
hj:id- marks an existing property as identifier property;
hj:version- marks an existing property as version property;
hj:basic- customizes the basic property;
hj:many-to-one- maps X:1 property as many-to-one (default strategy), customizes the many-to-one mapping;
hj:one-to-one- maps X:1 property as one-to-one, customizes the one-to-one mapping;
hj:one-to-many- maps X:M property as one-to-many (default strategy), customizes the one-to-many mapping;
hj:many-to-many- maps X:M property as many-to-many, customizes the many-to-many mapping;
hj:embedded- maps the property as embedded, customizes the embedded mapping.
hj:generated-id- customizes the generated identifier property.
hj:generated-version- instructs Hyperjaxb3 to generate a version property an customizes it.
hj:generated-property- customizes artificially generated properties.
Selecting the identifier property
In JPA, every entity must have a primary key. With Hyperjaxb3, you have two options for the primary key: either let Hyperjaxb3 generate a default identifier property for you or mark one of existing properties as identifier property using the
hj:id customization element.
In the following example I've selected an existing element
id as identifier property, customized column name and the value generation strategy:
The following customization would surely work as well:
Selecting the version property
Similar to marking an existing property as identifier, you may mark an existing property as version property which can be used by persistence provider to perform optimistic locking. Use
hj:version customization element for this purpose:
Customizing the basic property
Customizing the basic enumerated property
Hyperjaxb3 automatically detects enumerated properties an generates the appropriate @Basic/@Enumerated annotation.
By default, JPA maps enums as strings or integers. You can select enumerated type using
STRING enumerated type per default.
Apart from the default
STRING mappings, Hyperjaxb3 can also map enums by value. Use
hj:basic/hj:enumerated-value customization element for this option:
In this case Hyperjaxb3 will generate an additional property which exposes the value of the enum. Generated wrapped property will be persisted, core property will be made transient.
Customizing the many-to-one property
Customizing the one-to-one property
Customizing the one-to-many property
Order column for one-to-many property
With JPA 2 you can add an order column:
You can customize
column-definition. If you don't provide the
name, it will be generated for you:
Customizing the many-to-many property
Order column for many-to-many property
With JPA 2 you can add an order column:
See #Order column for one-to-many property - it works exactly the same for many-to-many properties.
Customizing the embedded property
Customizing the generated identifier property
In some cases Hyperjaxb3 has to generate an identifier property for the entity. You may use the
hj:generated-id customization element to customize this property:
hj:generated-id customization element has a number of settings like Java type and XML Schema type of the generated id property, its name (in Java) an attribute (in XML) and so on (see Xsddoc on
hj:generated-id for details).
One of the most important things worth mentioning here is the
transient attribute. It is
false by default which means that identifier property will appear as an attribute in XML. You may set it to
false - in this case identifier property will be generated as
@XmlTransient and will not appear in your XML.
Since 0.5.7 you can use the
hj:generated-id customization on mapped superclasses. This will force generation of the identifier property on the mapped superclass.
Customizing the generated version property
By default Hyperjaxb3 does not generate artificial version properties. You can, however, generate a version property by customizing your type with
Since 0.5.7 you can use the
hj:generated-version customization on mapped superclasses. This will force generation of the version property on the mapped superclass.
Customizing generated properties
Apart from identifier and version, in certain cases Hyperjaxb3 may have to generate additional properties. For instance, consider a construct like:
Since this "any" property can't be persisted directly with JPA, Hyperjaxb3 will generate an additiona wrapping property. The
hj:generated-property customization element allows you to customize this generated property. For instance, you can customize the name of the generated property:
hj:generated-property element can be specified in the bindings of the originating property (as shown above) or in the bindings of the class. In this case you must provide specify the name of the originating property in the
Contents of the
hj:generated-property will be used as customizations for the wrapping property. For instance, you could customize the mapping of the generated property:
Customizing default mappings
Customizing default mappings - Introduction
Although Hyperjaxb3 is highly customizable, you don't actually have to customize. If you don't customize, Hyperjaxb3 will follow its default strategies when generating mappings. For instance default strategy for collection mapping is one-to-many with join columns, default generated identifier property will be called
Hjid and typed as
long and so on.
No matter how reasonable and good default mappings are, there may be need to override the globally - for all entities, all properties. For instance, you may want map 1:M properties using a join table (instead of the default join column). While you you can surely use the
hj:one-to-many customization for each of your 1:M properties, this will require a lot of work.
To address such "global customization tasks" Hyperjaxb3 provides the possibility to customize default mappings. This is accomplished by customizing the schema with the
hj:persistence element may contain a number of sub-elements which customize default mappings, applied globally. For example, you may make all generated identifier properties to be named
Id (instead of
Overriding and merging customizations
Customizing the default entity
Customizing the default mapped superclass
Customizing the default embeddable
Customizing the default identifier property
Customizing the default generated identifier property
This will make all the generated identifier properties to be named
MyId (instead of
Hjid) by default. They'll be also generated transient.
Customizing the default embedded identifier property
Customizing the default version property
Customizing the default generated version property
This will make all the generated version properties to be named
Version (instead of
Hjversion) by default.
Note that Hyperjaxb3 will not generate version properties by default. If you want to generate version property for a certain type, use the
hj:generated-version customization. If you want to generate version properties for all the types, set the
forced attribute of the
hj:default-generated-version element to
Customizing the default basic property
Customizing the default to-one mapping
Customizing the default to-many mapping
Customizing the default many-to-one mapping
Customizing the default one-to-many mapping
Customizing the default one-to-one mapping
Customizing the default many-to-many mapping
Customizing the default embedded mapping
Customizing JAXB context path
"Any"-type properties need a JAXB context for marshalling/unmarshalling operations. By default the context path of this JAXB context is derived from the compiled schemas. In some cases it may not be suitable and you may want to customize the context path. In order to do it, you may use the
hj:jaxb-context customization element:
Previous sections explained how you can customize mapping generated for a certain property. A further feature of Hyperjaxb3 is the ability to customize all properties of the certain type (I mean an XML Schema type here) with one shot. This allows you to express things like "all strings must be mapped to columns of length 1000" or "properties of
xs:hexBinary are mapped as LOBs".
Since single and collection properties of the same type have different mappings, per-type customizations are distinguished by cardinality. You will typically use
hj:default-single-property element for single properties and
hj:default-collection-property element for collection properties.
Per-type customization for single properties
In order to customize certain type, define
hj:default-single-property sub-element of
You can even override the mappings for built-in types, for instance change the precision of
xsd:double mapping (default is 10/20):
See the following project for example:
Per-type customization for collection properties
XML Schema for customizations
XML Schema files for customizations can be found here:
Xsddoc (generated documentation) for customization schema can be found here: