What is an .episode file..?

I'll add some trivia.

• Actually, .episode files are just normal binding files (that's why they work with xjc -b).
• They can be generated with a special built-in plugin (that's what -episode does).
• If placed in a JAR under the META-INF/sun-jaxb.episode path, you can do xjc b.xsd a.jar - XJC will scan JARs for episode files then an use the as binding files automatically.
• All of this beauty works fine with Maven (maven-jaxb2-plugin). However, with later version you can use binding files from JAR artifacts even without episodes.

Note: I'm the EclipseLink JAXB (MOXy) lead and a member of the JAXB 2 (JSR-222) expert group.

A .episode file is generated by the XJC (XML Schema to Java) compiler. It is a schema bindings that associates schema types with existing classes. It is useful when you have one XML schema that is imported by other schemas as it prevents the model from being regenerated. Below is an example:

Product.xsd

<?xml version="1.0" encoding="UTF-8"?>
<schema 
    xmlns="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://www.example.org/Product" 
    xmlns:tns="http://www.example.org/Product" 
    elementFormDefault="qualified">
    <element name="product">
        <complexType>
            <sequence>
                <element name="id" type="string"/>
                <element name="name" type="string"/>
            </sequence>
        </complexType>
    </element>
</schema>

Since multiple XML schemas import Product.xsd we can leverage episode files so that the classes corresponding to Product.xsd are only generated once.

xjc -d out -episode product.episode Product.xsd

ProductPurchaseRequest.xsd

Below is an example of an XML schema that imports Product.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<schema 
    xmlns="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://www.example.org/ProductPurchaseRequest" 
    xmlns:tns="http://www.example.org/ProductPurchaseRequest"
    xmlns:prod="http://www.example.org/Product" 
    elementFormDefault="qualified">
    <import namespace="http://www.example.org/Product" schemaLocation="Product.xsd"/>
    <element name="purchase-request">
        <complexType>
            <sequence>
                <element ref="prod:product" maxOccurs="unbounded"/>
            </sequence>
        </complexType>
    </element>
</schema>

When we generate classes from this XML schema we will reference the episode file we created when we generated Java classes from Product.xsd.

xjc -d out ProductPurchaseRequest.xsd -extension -b product.episode

ProductQuoteRequest.xsd

Below is another example of an XML schema that imports Product.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<schema 
    xmlns="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://www.example.org/ProductQuoteRequest" 
    xmlns:tns="http://www.example.org/ProductQuoteRequest" 
    xmlns:prod="http://www.example.org/Product" 
    elementFormDefault="qualified">
    <import namespace="http://www.example.org/Product" schemaLocation="Product.xsd"/>
    <element name="quote">
        <complexType>
            <sequence>
                <element ref="prod:product"/>
            </sequence>
        </complexType>
    </element>
</schema>

Again when we generate classes from this XML schema we will reference the episode file we created when we generated Java classes from Product.xsd.

xjc -d out ProductQuoteRequest.xsd -extension -b product.episode

For More Information

• http://blog.bdoughan.com/2011/12/reusing-generated-jaxb-classes.html