xmlrpc/ExampleUsingOwnConceteTypes.md

+## [Home](https://git.opendfki.de/delight/delight/wikis/Home) | [Documentation](https://git.opendfki.de/delight/delight/wikis/Documentation) | [People / Contact](https://git.opendfki.de/delight/delight/wikis/people)
+---
+
+### Using own concete types
+
+#### Server side
+
+We want to use the type ```Param``` in our API. Normally, this will cause an error message. See how we can make this type
+XML-RPC compliant with only a few lines of code:
+
+```java
+public interface Api
+{
+    Param returnParam();
+    
+    void passAsParameter( Param p );
+}
+
+public class Impl implements Api
+{
+    public Param returnParam() { return createParam( ... ); }
+    
+    void passAsParameter( Param p ) { doSomethingWith( p ); }
+}
+```
+
+To use type Param, we have to make it XML-RPC compliant. We use java annotations and
+user-defined conversion operations to do this.
+
+ - the @!XmlRpc annotation declares that type Param uses XML-RPC type ARRAY as transport representation
+
+ - The interface ```Convertable``` declares what specific java type is used for transfer via XML-RPC
+
+ - toXmlRpc converts an instance of type Param into its XML-RPC representation
+
+ - the constructor creates an instance of type Param back from it's XML-RPC representation
+
+```java
+@XmlRpc( type=Type.ARRAY )      
+public class Param 
+               implements Convertable<Collection<String>>
+{
+    public Param( Collection<String> xmlRpcRepresentation ) { ... }
+
+    public Collection<String> toXmlRpc() { return ... }
+}
+```
+
+Now our type is XML-RPC compliant! We can register the implementation as usual...
+```java
+WebServer xmlRpcServer = new WebServer( port );
+xmlRpcServer.addHandler( "handlerId", XmlRpcHandlerFactory.createHandlerFor( new Impl() );
+xmlRpcServer.start();
+```
+
+
+#### Client Side
+
+Our client can be used without any extra statements:
+```java
+Api remote_api = XmlRpc.createClient( Api.class, "handlerId", host, port );
+
+Param p = remote_api.returnParam();
+
+Param asParam = ...;
+remote_api.passAsParameter( asParam );
+
+...
+```
+
+#### Using own types in Collections and Maps
+
+Collections, maps and arrays using the user-defined type as content can also be used out-of-the-box.
+
+```java
+// WORKS!
+public interface Api
+{
+    Map<String,Param> returnMyParamInMap();
+    
+    void passManyParams( Collection<Param> params );
+
+    void passParamsInArray( Param[] params );
+}
+```
+
+#### Client Side
+Now remote clients can also use Collections and Maps containing own types:
+```java
+Api remote_api = XmlRpc.createClient( Api.class, "handlerId", host, port );
+
+Map<String,Param> map = remote_api.returnMyParamInMap();
+for( Param p : map.values() )
+{
+  ...
+}
+
+remote_api.passManyParams( Collections.asList( new Param[]{new Param(), new Param()} ) );
+...
+```
+
+Examples in source code: [here](https://git.opendfki.de/delight/delight/tree/master/example-delight-webapp)
\ No newline at end of file