Using XmlRpcBeans in you API

What are XmlRpcBeans??

Sometimes parameter conversion is a straight-forward task which can be handed over to the XML-RPC runtime system. When a java class fulfills certain conditions (roughly, being a java bean with complatible types) it can be turned into a XmlRpcBean by annotating it with the @XmlRpcBean annotation. It then can be used in every XML-RPC call without restriction.

A XmlRpcBean must have

• a public constructor taking no arguments

• like a java bean: for each property which is supposed to be transported over XML-RPC there has to exist a public getter and setter method

• each property type has to be a XML-RPC compliant type, that is it has to have one of the follwoing properties:
  • it is a standard XML-RPC type
  • it is annotated with a @XmlRpc annotation and defines proper conversion methods
  • a conversion mapping for that type is put at the XmlRpcBean (which then acts as an API itself)
  • it is an XmlRpcBean (that is, XmlRpcBeans can be nested)
  • it is a Collection or Map containing a type which is XML-RPC compliant and is annotated with the @Contains annotation

Technically, an XmlRpcBean is converted into a XML-RPC STRUCT. The field names of the tranfered map are the property names derived from the bean class.

Lets look at an example XmlRpcBean (note that this bean also defines a converter mapping for type URL):

@XmlRpcBean
@ConverterMappings( @Mapping(type=URL.class,converter=URLConverter.class) )
public class CoffeeBean
{
    public URL getOrigin()
    {
        return mOrigin;
    }
    public void setOrigin( URL origin )
    {
        mOrigin = origin;
    }
    public String getType()
    {
        return mType;
    }
    public void setType( String type )
    {
        mType = type;
    }
    
    public String toString()
    {
        return( "CoffeeBean(" + getType() + ") comming from '" + getOrigin() + "'" );
    }
    private String mType;
    private URL mOrigin;
}

Client side

Again, the client has no restrictions using the bean class:

public interface Api
{
    @Contains(CoffeeBean.class)
    Collection<CoffeeBean> getAllBeans();
}

Api remote_api = XmlRpc.createClient( Api.class, "handlerId", host, port );

Collection<CoffeeBean> beans = remote_api.getAllBeans();

for( CoffeeBeans b: beans )
{
    System.out.println( "Bean of type " + b.getType() + " comes from " + b.getOrigin() );
}
...

See also ​How to use own types in Collections an Maps.