Precompiled bindings

Prior to version 1.2, the JiBX binding compiler required you to compile all the bindings being used with a set of classes at one time. This requirement created problems for enterprise users who need to work with independent extensions to base libraries, as often occurs when different development groups are involved in extending some shared code. With version 1.2 there's now a way around the compilation issue, at least in this case of extensions to base libraries.

Binding extension with separate compiles is implemented in 1.2 as an extension to the <include> binding element. The new precompiled attribute lets you to tell the binding compiler that the included binding has already been compiled. The binding compiler then looks up information from the precompiled binding and links to the already-generated code rather than regenerating the code for the included binding, allowing you to use <mapping> definitions defined in the included binding within the including binding (just as with normal includes).

Call the precompiled binding a "base" binding, and the binding which includes that base binding an "extension" binding. Using this terminology, you can include a base binding in multiple, independent, extension bindings. You can also include multiple, independent, base bindings from a single extension binding. You can even work with multiple layers of extension, and use different extensions of a single base binding as the base for further extension. The only restriction is that classes which are bound by a base binding cannot be bound by any extension binding - the extension bindings can only work with those classes by refering to the <mapping> definitions present in the base binding.

Extending a base binding

When you extend a precompiled base binding you need to specify a binding definition for the base binding in the <include> element, just as with a regular <include>. The binding definition doesn't need to include all the details of the actual binding, though, since those details have already been used in the code generated by the binding compiler for the base binding. You do need to have a mapping definition for each base binding mapping you're going to be using in the extension binding, but you don't need to include any content for the mapping - the <mapping> element itself is all that's required. You also need to use the package attribute of the <binding> element in the included binding to specify the package which contains the generated binding factory class. You don't need to include any base binding mappings which you're not using in the extension binding.

When running the binding compiler for an extension binding, the output from the binding compiler for the base binding (including both the modified bound classes, and the classes added by the binding compiler) needs to be in the classpath. The binding compiler will load the base binding information from the classpath, looking for it in the package specified by the included <binding> element's package attribute, and verify that the mapping definitions in the included binding are actually present in the compiled version of that binding.

It's often convenient to package a base binding with the bound class files in a jar. You can use classpath: URLs in <include> references for access to base bindings packaged in this way. As an example, if the binding definition was named base-binding.xml and in the root directory of the jar file you'd reference it as classpath:base-binding.xml or classpath:/base-binding.xml. If it was in the META-INF directory of a jar you'd reference it as classpath:META-INF/base-binding.xml or classpath:/META-INF/base-binding.xml. Naturally, the jar file containing the binding definition needs to be in the classpath when this type of reference is used - but as mentioned above, you need to have the bound class files for the base binding in the classpath anyway.

Runtime usage

At runtime, you'll need to have the precompiled base binding classes in your classpath when you create the extension binding factory. As part of loading the extension binding factory, the JiBX runtime will also load and base bindings and will check that the version of those base bindings is the same as that used when the extension binding was compiled. Since the binding compiler links to specific added methods in the bound classes, it's not possible to substitute a newer version of the base binding without recompiling the extension binding.