Version 32
Created by tfennelly on Jul 4, 2007 8:59 AM. Last modified by ozizka on Nov 12, 2009 9:02 AM.

    JAXB is an XML to Java Binding standard.  Implementations of JAXB enable binding of XML to and from Java.

     

    JAXB is heavily driven by Java Annotations on the Java Bindings.  It currently doesn't support an external binding configuration.  This recently became an issue for us on JBossESB since the JBossWS 2.0.0 native SOAP stack uses JAXB to perform the SOAP to Java bindings (see 1, 2).  It's an issue for JBossESB simply because it needs to be able to support user definition of JBossWS native Webservice Endpoints (e.g. JSR 181) using Java typesets that have not been "JAXB Annotated" (see JAXBIntroductionsOnJBossWS).

     

    In order to support this, we built on a JAXB RI feature whereby it allows you to specify a RuntimeInlineAnnotationReader implementation during JAXBContext creation (see JAXBRIContext).

     

    We call this feature "JAXB Annotation Introduction" and we've made it available for general consumption i.e. it can be checked out, built and used from SVN.

     

    JAXB Annotation Introduction allows you to specify JAXB Annotations in an external XML configuration file, allowing you to use JAXB for binding to and from Java typesets that have not been JAXB Annotated.  It "Introduces" the JAXB annotations for a given JAXBContext via a RuntimeInlineAnnotationReader implementation called the IntroductionsAnnotationReader.

     

    IntroductionsAnnotationReader works by creating dynamic proxies for the annotations as they are requested by JAXB RI, with the dynamic proxies being fed via an XML configuration (see below).

     

    Question/Comments

     

    Getting and Building JAXB Intros

    1. Checkout the code from here.

    2. Build the code by simply running the Ant script (default target).

     

    This builds the jboss-jaxb-intros.jar file in the "output/lib" directory.

     

    Writing JAXB Intro Configurations

    JAXB Annotation Introduction configurations are very easy to write.  If you're already familiar with the JAXB Annotations, you'll have no problem writing a JAXB Annotation Introduction configuration.

     

    The XSD for the configuration is available online.  In your IDE, register this XSD against the <http://www.jboss.org/xsd/jaxb/intros> namespace.

     

    The following annotations are currently supported (I'm sure we'll need to add more):

    1. @XmlType: On the <Class> element.

    2. @XmlAccessorType: On the <Class> element. (Contributed by Chris McClelland).

    3. @XmlRootElement: On the <Class> element. (Contributed by Chris McClelland).

    4. @XmlElement: On the <Field> and <Method> elements.

    5. @XmlAttribute: On the <Field> and <Method> elements.

     

    The basic structure of the configuration file follows the basic structure of a Java class i.e. a <Class> containing <Fields> and <Methods> (the config file can contain 1+

    elements all require a <name> attribute for the name of the Class, Field or Method.  The value of this name attribute supports regular expressions.  This allows a single Annotation Introduction configuration to be targeted at more than one Class, Field or Member e.g. setting the namespace for a fields in a Class, or for all Classes in a package etc.

     

    The Annotation Introduction configurations match exactly with the Annotation definitions themselves, with each annotation <element-value pair> represented by an attribute on the annotations introduction configuration.  Use the XSD and your IDE to editing the configuration.

     

    So here's an example:

         <?xml version = "1.0" encoding = "UTF-8"?>
     <jaxb-intros xmlns="http://www.jboss.org/xsd/jaxb/intros">
     
         <Class name="com.activebpel.ordermanagement.CustomerOrder">
             <XmlType propOrder="orderDate,name,address,items" ></XmlType>
                 <XmlAccessorType value="FIELD" ></XmlAccessorType>
             <Field name="orderDate">
                 <XmlAttribute name="date" required="true" ></XmlAttribute>
             </Field>
             <Field name="getXYZ">
                 <XmlElement namespace="http://org.jboss.esb/quickstarts/bpel/ABI_OrderManager" nillable="true" ></XmlElement>
             </Field>
         </Class>

         <Class name="com.activebpel.ordermanagement.*">
             <Method name="get.*">
                 <XmlElement namespace="http://ordermanagement.activebpel.com/jaws" ></XmlElement>
             </Method>
         </Class>
     
     </jaxb-intros>

     

    Using JAXB Intros

    The following is a piece of sample code that illustrates how to create a JAXBContext instance that uses the IntroductionsAnnotationReader.

     

            JaxbIntros config = IntroductionsConfigParser.parseConfig(getClass().getResourceAsStream("intro-config-03.xml"));
        IntroductionsAnnotationReader reader = new IntroductionsAnnotationReader(config);
        Map<String, Object> jaxbConfig = new HashMap<String, Object>();

        jaxbConfig.put(JAXBRIContext.DEFAULT_NAMESPACE_REMAP, config.getDefaultNamespace());
        jaxbConfig.put(JAXBRIContext.ANNOTATION_READER, reader);

        JAXBContext jaxbContext = JAXBContext.newInstance(new Class[] {CustomerOrder.class}, jaxbConfig);

     

    Note also how the default namespace can be specified on the JAXB Intros configuration and retrieved via the JaxbIntros.getDefaultNamespace method.

     

    For more code examples, see the unit tests.