Introduction

Introduction

Introduction

If you already use JAXB, you know how much easier does this great tool make the XML processing in Java. Few lines of code and your XML is turned into an object stucture which is much suitable for Java code than, for instance, DOM or SAX. And you can always turn your object structure back to XML with almoust zero effort.

Generally speaking, there are two principal alternatives for using JAXB in your applications:

• You may start with existing classes and annotate them JAXB annotations.
• You may also start with an XML schema and use the schema compiler (XJC) to compile it into a set of schema-derived classes.

Although the first method is very useful if you want to XMLize existing class hierarchies, the real power of JAXB lies in the second, schema-driven approach. In this case you do not write the code manually - you just provide the XML schema and let JAXB generate the code for you. Schema compiler will analyze the schema and generate the sources of Java classes that represent the XML content.

These classes are called schema-derived classes. They are just normal POJOs (well, almost) and therefore quite easy to handle in Java code. At the same time schema-derived classes contain all the required JAXB annotations (generated by the schema compiler).

Hyperjaxb3 takes you one step further. It makes schema-derived classes persistable with JPA (Java Persistence API), allowing for storing and querying your JAXB objects (instances of schema-derived classes) in a relational database.

Now, if consider JAXB implementing the XML <> objects connection and Hyperjaxb3 providing relational persistence (objects <> RDB), you get the full XML <> objects <> RDB roundtrip.

Mission statement

The goal of Hyperjaxb3 is to provide relational persistence for schema-derived classes. The principal task of Hyperjaxb3 is to turn JAXB schema-derived classes into JPA entity classes so that JPA layer could persist them in a relational database.

In order to achieve this goal, Hyperjaxb3 implements a plugin for JAXB schema compiler which augments modifies or customizes the generated code so that the produced schema-derived classes become valid persistent entity classes.

Tasks solved by Hyperjaxb3

In order to make schema-derived classes persistable with JPA, Hyperjaxb3 must ensure that they fulfill requirements on the entity class as defined in the JPA specificaltion (see section 2.1). Moreover, to expose generated entities as a persistence unit, Hyperjaxb3 must generate additional files needed for entity packaging (namely the META-INF/persistence.xml file) as described in the Chapter 6 of the JPA specification.

More specifically, to turn schema-derived classes into JPA entities, Hyperjaxb3 solves the following tasks:

• Generate the equals(...) and hashCode() methods
• Apply workarounds for JAXB/JPA incompatibilities
• Add required properties (for instance, identifier or version properties)
• Generate the ORM metadata in form of JPA annotations or XML mapping resources
• Generate the persistence unit descriptor (META-INF/persistence.xml)

The following sections of this reference describe how Hyperjaxb3 solves each of these tasks in particular.