Separate compilation in the JAXB RI 2.1

I just finished implementing the proposed separate compilation feature in the JAXB RI 2.1. So today I'm going to talk about how this proposed feature works, in the hope of getting more feedback for this proposal. You can play with this today by downloading the latest 2.1 continuous build of the JAXB RI.

The "separate compilation" that I'm talking about works like this. Alice has an extensible schema A and its corresponding JAXB classes:

<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="A">
  <complexType name="myType"/>
</schema>

@XmlType(namespace="A",name="myType")
class MyType {}

Maybe she wrote the schema and then generated the classes, or maybe she wrote classes and then generated the schema. Or maybe she wrote both by hand. It doesn't matter. Alice distributes this a.xsd and a.jar that contains these.

Now Bob has a schema B that refers to A. Maybe like this:

<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="B" xmlns:a="A">
  <import namespace="A" schemaLocation="http://alice.org/a.xsd"/>
  <complexType name="extendedType">
    <complexContent>
      <extension base="a:myType"/>
    </complexContent>
  </complexType>
</schema>

He wants to generate Java classes for this schema, and he wants the schema compiler to do this by reusing classes in a.jar and not generating a new MyType class. In 2.0, this was somewhere between hard to impossible. But in 2.1, this is going to be much easier.

Case 1: a.jar is generated by XJC

The first case to consider is when Alice wrote a.xsd and generated a.jar by XJC. In this case, when invoking XJC, Alice would do it like this:

$ xjc -episode a.episode a.xsd

This tells XJC to compile a.xsd and then also generate what I call an "episode" file, which contains information about what schema stuff produced what Java stuff. This generated file is actually just a JAXB customization file, although unfortunately this version uses SCD, which makes it non-portable (there are ways to make this portable --- more work ahead.)

Anyway, with this, Bob will compile b.xsd like the following, to generate classes that refer to existing classes in a.jar. The specified a.episode tells the compiler to do the right thing.

$ xjc b.xsd -b a.episode

Since distributing two things is tedious and error prone, Alice can also choose to put a.episode into a.jar in /META-INF/sun-jaxb.episode. With this, Bob can run XJC like this to achieve the same effect, but this time without worrying about the additional file:

$ xjc b.xsd a.jar

Case 2: a.xsd is generated by schemagen

It's really the same thing as in the above case. When Alice generates a.xsd, she'd do it like this (or use the @episode if you invoke schemagen via the ant task:)

$ schemagen -episode a.episode ....sourcefiles...

This tells schemagen to generate schema files as well as an episode file. Bob can then use this episode file, along with the schema, to refer to Alice's existing classes:

$ xjc b.xsd -b a.episode

Pretty easy, huh?

Case 3: a.xsd and a.jar are both manually written

You can manually write the episode file (if you look at a few of them, you'll find that it's pretty easy to do so), or you can run schemagen just to get the episode file and discard all the schemas.

Conclusion

So that's what' we are planning to do in 2.1. Let us know what you think, while we can still change things...