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 ExampleUsingOwnConceteTypes and 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.
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: ​How to use own types contained in Collections an Maps.