| 57 | | == Using !XmlRpcBeans in you API == |
| 58 | | |
| 59 | | What are !XmlRpcBeans?? |
| 60 | | |
| 61 | | Sometimes parameter conversion is a straight-forward task which can be handed over to the XML-RPC runtime system. |
| 62 | | When a java class fulfills certain conditions (roughly, being a java bean with compatible types) it can be turned into a !XmlRpcBean |
| 63 | | by annotating it with the @!XmlRpcBean annotation. It then can be used in every XML-RPC call without restriction.[[BR]] |
| 64 | | |
| 65 | | A !XmlRpcBean must have |
| 66 | | |
| 67 | | - a public constructor taking no arguments |
| 68 | | |
| 69 | | - 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 |
| 70 | | |
| 71 | | - each property type has to be a XML-RPC compliant type, that is it has to have one of the follwoing properties: |
| 72 | | - it is a standard XML-RPC type |
| 73 | | - it is annotated with a @!XmlRpc annotation and defines proper conversion methods |
| 74 | | - a conversion mapping for that type is put at the !XmlRpcBean (which then acts as an API itself) |
| 75 | | - it is an !XmlRpcBean (that is, !XmlRpcBeans can be nested) |
| 76 | | - it is a Collection or Map containing a type which is XML-RPC compliant and is annotated with the @Contains annotation |
| 77 | | |
| 78 | | |
| 79 | | 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. |
| 80 | | |
| 81 | | |
| 82 | | Lets look at an example !XmlRpcBean (note that this bean also defines a converter mapping for type ''URL''): |
| 83 | | {{{ |
| 84 | | @XmlRpcBean |
| 85 | | @ConverterMappings( @Mapping(type=URL.class,converter=URLConverter.class) ) |
| 86 | | public class CoffeeBean |
| 87 | | { |
| 88 | | public URL getOrigin() |
| 89 | | { |
| 90 | | return mOrigin; |
| 91 | | } |
| 92 | | public void setOrigin( URL origin ) |
| 93 | | { |
| 94 | | mOrigin = origin; |
| 95 | | } |
| 96 | | public String getType() |
| 97 | | { |
| 98 | | return mType; |
| 99 | | } |
| 100 | | public void setType( String type ) |
| 101 | | { |
| 102 | | mType = type; |
| 103 | | } |
| 104 | | |
| 105 | | public String toString() |
| 106 | | { |
| 107 | | return( "CoffeeBean(" + getType() + ") comming from '" + getOrigin() + "'" ); |
| 108 | | } |
| 109 | | private String mType; |
| 110 | | private URL mOrigin; |
| 111 | | } |
| 112 | | }}} |
| 113 | | |
| 114 | | == Client side == |
| 115 | | |
| 116 | | Again, the client has no restrictions using the bean class: |
| 117 | | {{{ |
| 118 | | public interface Api |
| 119 | | { |
| 120 | | @Contains(CoffeeBean.class) |
| 121 | | Collection<CoffeeBean> getAllBeans(); |
| 122 | | } |
| 123 | | |
| 124 | | ---- |
| 125 | | |
| 126 | | Api remote_api = XmlRpc.createClient( Api.class, "handlerId", host, port ); |
| 127 | | |
| 128 | | Collection<CoffeeBean> beans = remote_api.getAllBeans(); |
| 129 | | |
| 130 | | for( CoffeeBeans b: beans ) |
| 131 | | { |
| 132 | | System.out.println( "Bean of type " + b.getType() + " comes from " + b.getOrigin() ); |
| 133 | | } |
| 134 | | ... |
| 135 | | }}} |
