== Using Third Party Types in your API ==

Eventually, you want to use third party types in your remote calls. Unfortunately the nice annotation features we saw in [wiki:ExampleUsingOwnConceteTypes] and [wiki:ExampleUsingOwnInterfaceTypes] are not applicable here because you are neither allowed to modify the classes nor makes it sense to add an additional dependency to that type.[[BR]]
The Delight XML-RPC framework offers a solution to this problem by offering conversion mappings to be declared with the API (of course you can add as many mapping you want):

{{{
@ConverterMappings( 
      @Mapping(type=URL.class,converter=URLConverter.class) 
)
public interface Api
{
    URL getHomepageLocation();
    void addSite( URL url );
}
}}}

We have to define a standalone converter to transfer instances of type URL to a XML-RPC representation and vice versa. 
Therefor, the converter has to implemente the interface ''!ParameterConverter'' to define three methods:

 - getXmlRpcRepresentationType(): states what XML-RPC type will be useed as transport representation

 - createFrom(): takes a XML-RPC representation and creates a corresponding instance of type ''URL''.

 - toXmlRpc(): takes an instance of type ''URL'' and converts it into it's XML-RPC representation.

See the complete class here:
{{{
public class URLConverter implements ParameterConverter<URL, String>
{
    /** Converter uses XML-RPC type {@value XmlRpc.Type.STRING} as XML-RPC representation.*/
    public Type getXmlRpcRepresentationType()
    {
        return( XmlRpc.Type.STRING );
    }
    
    public URL createFrom( String xmlRepresentation )
        throws TypeConversionException
    {
        URL url = null;
        try
        {
            url = new URL( xmlRepresentation );
        }
        catch( MalformedURLException e )
        {
            throw( new TypeConversionException( e ) );
        }
        return( url );
    }

    public String toXmlRpc( URL param )
        throws TypeConversionException
    {
        return( param.toExternalForm() );
    }
}
}}}

Now, without having to modify it, the type ''URL'' can be used in XML-RPC calls.
{{{
Api remote_api = XmlRpc.createClient( Api.class, "handlerId", host, port );

URL homepageUrl = remote_api.getHomepageLocation();
InputStream is = homepageUrl.openStream();
...

remote_api.addSite( new URL( "http://middle.of.nowhere" ) );

...
}}}

See also: [http://delight.opendfki.de/wiki/ExampleUsingOwnConceteTypes#UsingowntypesinCollectionsandMaps How to use own types contained in Collections an Maps].

== 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 compatible 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.[[BR]]

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 [http://delight.opendfki.de/wiki/ExampleUsingOwnConceteTypes#UsingowntypesinCollectionsandMaps How to use own types in Collections an Maps].

Examples in source code: [http://delight.opendfki.de/repos/trunk/XmlRpcDelight/src/examples/de/dfki/util/xmlrpc/examples/external_types/]