X2JB Restrictions

As mentioned earlier X2JB comes with few restrictions that must be satisfied. Lets call mapping interface binding interface and each method declared within it binding method. The following are the restrictions of X2JB:

• Every binding interface must be Java interface
• Every binding method cannot throw exceptions
• Every binding method name must start with "is", "set" or "get" prefix
• Every getter (getters start with "is" or "get" prefix) must follow the following rules"
  • if getter starts with "is" prefix its return type must be either boolean or Boolean
  • if getter starts with "get" prefix its return type can be any X2JB primitive type except void or Void
  • every getter must be without parameters
  • there can be only one getter for every bean type (isProperty() and getProperty() are not allowed to be declared on the same binding inteface)
• Every setter (setters start with "set" prefix) must follow the following rules:
  • setter must return either void or Void
  • setter must have only one parameter of the same bean type like associated getter method
  • there must exist getter for every defined setter (but not vice versa)
  • there must exist only one setter for every bean (setProperty(int) and setProperty(Integer) are not allowed to be declared on the same binding interface)
• If there are both setter and getter defined for particular bean, then these methods have to have identical binding definition.
• There must exist type handler for each binding method bean type. The only exception to this rule is binding method returning binding interface. (X2JB default handlers will be used when user does not specify its own in bean mapping definition)

X2JB Default Binding

If there's no binding definition associated with particular binding method the default one is generated. The generated default binding has identical defaults like binding annotation defined for X2JB annotation provider, except the required name attribute. If binding definition is generated the name attribute is set to the following value:

• if binding method starts with "set" prefix (e.g. setProperty), the name will hold value "property" (lowercased property name)
• if binding method starts with "is" prefix (e.g. isProperty), the name will hold value "property"
• if binding method starts with "get" prefix (e.g. getProperty), the name will hold value "property"

If user want to know the generated default name attribute value, here's the algorithm:

• remove "is", "set" or "get" prefix from method name (let's say its methodNameWithoutPrefix)
• then java.beans.Introspector.decapitalize(methodNameWithoutPrefix) method is called for bean name construction

Users should take a look to both versions of defaultbindings sample that is part of this distribution to see how default bindings are generated from method names.

X2JB Modifiable Proxies

X2JB 1.0 introduced unmodifiable proxies. Since X2JB 2.0 there is also support for modifiable proxies. Modifiable proxies are Java proxies where user can change their values after the X2JB binding process. Users should take a look to both versions of mutability sample that is part of this distribution to see how generated X2JB Java proxies can be modified at runtime.

Built-in Type Handlers

X2JB comes with default type handlers for the following frequently used Java objects and primitives (we call them X2JB primitives):

Default handler is used in case user does not specify his custom bean type handler in the bean mapping definition.

Users should take a look to both versions of supportedtypes and defaultvalues demos that are part of this distribution to see the aforementioned default handlers in action.

Binding Providers

X2JB comes with two ready to be used binding providers.

methodName.bindingAttribute=someValue

Setting Classpath

Now, when user knows how to use both types of binding mechanisms is the time to explain how to properly set up the classpath to use the appropriate binding provider.

User must always have x2jb-core.jar and x2jb-default-handlers.jar on the classpath. Then he must have x2jb-annotation-provider.jar or x2jb-properties-provider.jar or custom binding provider on the classpath too. If there are multiple binding providers on the classpath then the first provider on the classpath is used. However user can always simply override this default behaviour. The trick is to specify -Dorg.x2jb.bind.spi.provider.BindingFactory JVM property.

Annotation Based Binding Provider is implemented by com.x2jb.bind.provider.AnnotationBindingFactoryImpl class. So if there are multiple binding providers on the classpath user can specify -Dorg.x2jb.bind.spi.provider.BindingFactory=com.x2jb.bind.provider.AnnotationBindingFactoryImpl and annotation based provider will be used.

Properties Based Binding Provider is implemented by com.x2jb.bind.provider.PropertiesBindingFactoryImpl class. So again if there are multiple binding providers on the classpath user can just specify -Dorg.x2jb.bind.spi.provider.BindingFactory=com.x2jb.bind.provider.PropertiesBindingFactoryImpl and properties provider will be used during the binding process.

Writing Custom Handler

User can always write his own binding handler. It is very easy, he just need to follow the following steps:

• write his own implementation of org.x2jb.bind.spi.handler.AttributeHandler or org.x2jb.bind.spi.handler.ElementHandler interface
• reference newly created binding handler class name in the method mapping definition (using typeHandler attribute)
• put the handler implementation on the classpath

Users should take a look to both versions of customhandler sample that is part of this distribution to see how to write custom binding handler.

Writing Custom Default Handlers

There may be situations when user will not be satisfied with default X2JB handlers implementation. If this is the case user must follow the following steps to write and activate his custom default handlers implementations:

• implement all the new default custom handlers (see previous chapter how to write it)
• create new x2jb.handlers property file and specify his default handlers mapping there. Here is the sample how it looks like for x2jb-default-handlers.jar archive:

  # file x2jb.handlers - X2JB default handlers mapping definition
  #
  # the format of this file is:
  # javaType=handlerImplementation
  #
  java.lang.Boolean=com.x2jb.bind.handler.BooleanHandler
  java.lang.Character=com.x2jb.bind.handler.CharacterHandler
  java.lang.Byte=com.x2jb.bind.handler.ByteHandler
  java.lang.Short=com.x2jb.bind.handler.ShortHandler
  java.lang.Integer=com.x2jb.bind.handler.IntegerHandler
  java.lang.Long=com.x2jb.bind.handler.LongHandler
  java.lang.Float=com.x2jb.bind.handler.FloatHandler
  java.lang.Double=com.x2jb.bind.handler.DoubleHandler
  boolean=com.x2jb.bind.handler.PrimitiveBooleanHandler
  char=com.x2jb.bind.handler.PrimitiveCharacterHandler
  byte=com.x2jb.bind.handler.PrimitiveByteHandler
  short=com.x2jb.bind.handler.PrimitiveShortHandler
  int=com.x2jb.bind.handler.PrimitiveIntegerHandler
  long=com.x2jb.bind.handler.PrimitiveLongHandler
  float=com.x2jb.bind.handler.PrimitiveFloatHandler
  double=com.x2jb.bind.handler.PrimitiveDoubleHandler
  java.math.BigInteger=com.x2jb.bind.handler.BigIntegerHandler
  java.math.BigDecimal=com.x2jb.bind.handler.BigDecimalHandler
  java.lang.String=com.x2jb.bind.handler.StringHandler
  javax.xml.namespace.QName=com.x2jb.bind.handler.QNameHandler
  org.w3c.dom.Element=com.x2jb.bind.handler.ElementHandler

• compile his newly created default handlers and package it to e.g. foo.jar including his newly created x2jb.handlers file to its META-INF directory.
• put newly created default handlers archive foo.jar to the beginning of the classpath. It is not necessary to put it on the beginning of the classpath but in such case user must ensure x2jb-default-handlers.jar is not on the classpath.

The only important information user should know is the following fact. When X2JB runtime boots it lookups the first META-INF/x2jb.handlers property file on the classpath to instantiate all default handlers specified there. All other META-INF/x2jb.handlers classpath resources are completely ignored.

Writing Custom Binding Provider

As user already knows X2JB comes with two ready to be used binding providers. But he is not forced to use them. User can always write his own X2JB binding provider. Here are the steps how to accomplish this:

• the new Binding Provider must implement org.x2jb.bind.spi.provider.BindingFactory interface. Users should read its API documentation very carefully to understand and fulfill the interface contract. Lets call this newly created BindingProvider e.g. com.mycompany.myproject.FooBindingProvider
• user must create new org.x2jb.bind.spi.provider.BindingFactory text file and specify its new implementation class name there:

  com.mycompany.myproject.FooBindingProvider

• user must compile and archive his newly created com.mycompany.myproject.FooBindingProvider to jar file including newly created org.x2jb.bind.spi.provider.BindingFactory text file in its META-INF/services directory.
• put his custom binding provider jar file to the beginning of the classpath or just put it on the classpath and specify the following JVM property when running his application:

  -Dorg.x2jb.bind.spi.provider.BindingFactory=com.mycompany.myproject.FooBindingProvider

The only important information user should know again is the following fact. When X2JB runtime boots it lookups the binding provider to use in the following way:

• it checks if the JVM property -Dorg.x2jb.bind.spi.provider.BindingFactory is specified. If yes its value is used to instantiate the binding provider
• if there is no such JVM property specified X2JB runtime searches for the first META-INF/services/org.x2jb.bind.spi.provider.BindingFactory classpath resource and reads its content. The content of this text file representing the provider class name is used to instantiate the binding provider

Here is the complete source code of annotation binding provider that is part of this distribution and is implemented in x2jb-annotation-provider.jar archive:

//
// file com.x2jb.bind.provider.AnnotationBindingFactoryImpl.java
//
package com.x2jb.bind.provider;

import java.lang.reflect.Method;

import org.x2jb.bind.Binding;
import org.x2jb.bind.spi.provider.BindingDefinition;
import org.x2jb.bind.spi.provider.BindingFactory;

public final class AnnotationBindingFactoryImpl implements BindingFactory
{

    public AnnotationBindingFactoryImpl()
    {
        super();
    }

    public BindingDefinition getBinding( final Method method )
    {
        final Binding methodMetadata = ( Binding ) method.getAnnotation( Binding.class );
        return ( methodMetadata == null ) ? null : new AnnotationBindingImpl( methodMetadata );
    }

}

Here is the referenced AnnotationBindingImpl that translated data from Java annotation to BindingDefinition interface implementation:

//
// file com.x2jb.bind.provider.AnnotationBindingImpl.java
//
package com.x2jb.bind.provider;

import org.x2jb.bind.Binding;
import org.x2jb.bind.spi.provider.BindingDefinition;

final class AnnotationBindingImpl implements BindingDefinition
{

    private Binding binding;

    AnnotationBindingImpl( final Binding b )
    {
        this.binding = b;
    }

    public String getNodeName()
    {
        return this.binding.nodeName();
    }

    public String getNodeNamespace()
    {
        return this.binding.nodeNamespace();
    }

    public boolean isElementNode()
    {
        return this.binding.isElementNode();
    }

    public boolean isNodeUnique()
    {
        return this.binding.isNodeUnique();
    }

    public boolean isNodeMandatory()
    {
        return this.binding.isNodeMandatory();
    }

    public String getTypeHandler()
    {
        return this.binding.typeHandler();
    }

    public String getDefaultValue()
    {
        return this.binding.defaultValue();
    }

}

And at last the referenced Binding Java annotation source code:

//
// file org.x2jb.bind.Binding.java
//
package org.x2jb.bind;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.METHOD } )
public @interface Binding
{

    String nodeName();

    String nodeNamespace() default "";

    boolean isElementNode() default true;

    boolean isNodeUnique() default true;

    boolean isNodeMandatory() default true;

    String typeHandler() default "";

    String defaultValue() default "";

}