Changes between Version 3 and Version 4 of ExampleUsingThirdPartyTypes

Timestamp:

10/09/06 14:59:57 (18 years ago)

Author:

lauer

Comment:

--

ExampleUsingThirdPartyTypes

@@ -72 +72 @@
 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/]