What is an .episode file..?

Question

what is a .episode file in JAXB..? Is it generated by the JAXB or is it a configuration file that we'd manipulate to avoid regeneration of the same classes by JAXB..?

Answer 1

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

Answer 2

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.

Answer 3

Just an addon to the answer, I would like to provide an input on how to avoid having .episode file generated while using maven-jaxb2-plugin

         `<plugin>
            <groupId>org.jvnet.jaxb2.maven2</groupId>
            <artifactId>maven-jaxb2-plugin</artifactId>
            <version>0.12.3</version>
            <executions>
                <execution>
                    <id>schema-conversion</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <schemaDirectory>src/main/schema/myschema</schemaDirectory>
                        <bindingDirectory>src/main/schema/myschema</bindingDirectory>
                        <bindingIncludes>
                            <include>binding_info.xjb</include>
                        </bindingIncludes>
                        <generateDirectory>src/main/java/</generateDirectory>
                        <episode>false</episode>
                    </configuration>
                </execution>
            </executions>
        </plugin>`

<episode>false</episode> will make it disappear.

Answer 4

Apparently, they're for modular schema creation.

This implies that the files themselves can be used both as a configurator and as a generative view of a data layer for downstream processing. More context would be needed to determine which is being referred to here.