RPC adapter library features

Mapping results to JSON/XML

In RPC adapter, the output format is either JSON or XML.

Mapping results to XML

The various XML outputs that are generated under different scenarios are listed below.

  • The return type is void
  • If the return type is void, then the generated XML output is an empty result tag as shown below.

    <results/>
  • The return type is a primitive, wrapper or string
  • If the method in the JavaBeans is public int getSalary(),the output is similar to the following:

    <results>80000</results>

    If the method in the JavaBeans is public String getMessage() , the output is similar to the following example.
    <results>Hello World</results>

    If the method in the JavaBeans is public Boolean isLeapYear(int year), the output is similar to the following example.
    <results>true</results>
  • The return type is Collection
  • For return type collection the output is a set of elements with each element representing an entry in the collection. If the collection contains any instances of a suppressed object type then that entry is ignored.


    If the method in the JavaBeans is public Collection getEmployees() and the returned collection contains instances of Employee then one sample output is similar to the following example.
    <results> <Employee> <firstName>James</firstName> <lastName>Smith</lastName> <designation>Software Developer</designation> <company>IBM</company> </Employee> <Employee> <firstName>John</firstName> <lastName>Dow</lastName> <designation>Manager</designation> <company>IBM</company> </Employee> </results>
    You can specify alias for the object types.If the alias for the Employee class is employee then output is similar to the following example.
    <results> <employee> <firstName>James</firstName> <lastName>Smith</lastName> <designation>Software Developer</designation> <company>IBM</company> </employee> <employee> <firstName>John</firstName> <lastName>Dow</lastName> <designation>Manager</designation> <company>IBM</company> </employee> </results>
  • The return type is Array
  • For return type Array the output is a set of Elements with each element representing an entry in the array.


    If the method in the JavaBeans is public Employee[] getEmployees() and the returned Array consists of instances of Employee then one sample output is similar to the following example.
    <results> <Employee> <firstName>James</firstName> <lastName>Smith</lastName> <designation>Software Developer</designation> <company>IBM</company> </Employee> <Employee> <firstName>John</firstName> <lastName>Dow</lastName> <designation>Manager</designation> <company>IBM</company> </Employee> </results>
  • The return type is a Map
  • For return type of Map the output will be a set of Elements with each element representing a key value pair in the map.The node name is the key.
    If the method in JavaBeans is public Map getDepartments() and the returned map is a key value pair of department code to department details, one sample output is similar to the following example.

    <results> <CS> <deptName>Computer Science</deptName> <deptHead>Dan Johns</deptName> </CS> <EC> <deptName>Electronics and Communication</deptName> <deptHead>Iva Brown</deptName> </EC> </results>
  • The return type is JavaBeans
  • For return type of JavaBeans all the read methods and public fields without a read method will be considered for XML serialization. The JavaBeans are represented by an element. The node name of this element will be the type of JavaBeans that it represents. If any alias is specified for the bean then that is used as node name.
    If the method in the JavaBeans is public Employee getEmployee() , then one sample output is similar to the following example.

    <results> <Employee> <firstName>James</firstName> <lastName>Smith</lastName> <designation>Software Developer</designation> <company>IBM</company> </Employee> <results>
    If the Employee has a manager Employee reference, then the sample output is similar to the following example.
    <results> <Employee> <firstName>James</firstName> <lastName>Smith</lastName> <designation>Software Developer</designation> <company>IBM</company> <manager> <firstName>John</firstName> <lastName>Dow</lastName> <designation>Manager</designation> <company>IBM</company> </manager> </Employee> <results>
    Suggestion: If the employee has a collection field address type, then the sample output is similar to the following example. <results> <Employee> <firstName>James</firstName> <lastName>Smith</lastName> <designation>Software Developer</designation> <company>IBM</company> <manager> <firstName>John</firstName> <lastName>Dow</lastName> <designation>Manager</designation> <company>IBM</company> </manager> <addresses/> <addresses/> </Employee> <results>

    Mapping results to JSON

    The various JSON outputs generated under various scenarios are explained below.

  • The return type is void
  • If the return type is void, the JSON output generated is a JSON result object.

    {"result":null,"error":null,"id":1}
  • The return type is a primitive, wrapper or string

  • If the method in the JavaBeans is public int getSalary() then the output is similar to the following exmaple.
    {"result":20000,"error":null,"id":1}

    If the method in the JavaBeans is public String getMessage() then the output is similar to the following example.
    {"result":"Hello World","error":null,"id":1}

    If the method in the JavaBeans is public Boolean isLeapYear(int year) then the output is similar to the following example.
    {"result":true,"error":null,"id":1}
  • The return type is Collection
  • For return type collection the output is a set of elements with each element representing an entry in the collection. If the collection contains any instances of a suppressed object type then that entry is ignored.


    If the method in the JavaBeans is public Collection getEmployees() and the returned collection contains instances of Employee then one sample output is similar to the following:
    {"result":[{"firstName":"James","lastName":"Smith","designation":"Software Developer","company":"IBM"},{"firstName":"John","lastName":"Dow","designation":"CEO","company":"IBM"}],"error":null,"id":1}
  • The return type is Array
  • For return type Array the output is a set of Elements with each element representing an entry in the array.


    If the method in the JavaBeans is public Employee[] getEmployees() and the returned Array consists of instances of Employee then one sample output is similar to the following example.
    {"result":[{"firstName":"James","lastName":"Smith","designation":"Software Developer","company":"IBM"},{"firstName":"John","lastName":"Dow","designation":"CEO","company":"IBM"}],"error":null,"id":1}
  • The return type is a Map
  • For return type of Map the output will be a set of key value pairs.
    If the method in the JavaBeans is public Map getDepartments() and the returned map is a key value pair of department code to department details, then one sample output is similar to the following example.

    {"result":[{"deptName":"name1","deptHead":"head1"},{"deptName":"name2","deptHead":"head2"}],"error":null,"id":1}
  • The return type is JavaBeans
  • The JavaBeans are represented as key value pairs with the key as the name of the field and value as the value of the field. Only public fields and fields with getters are serialized.
    If the method in the JavaBeans is public Employee getEmployee() , then a sample output is similar to the following example.

    {"result":{"firstName":"James","lastName":"Smith","designation":"Software Developer","company":"IBM"},"error":null,"id":1}
    If the Employee has a manager Employee reference, then the sample output is similar to the following example.
    {"result":{"firstName":"James","lastName":"Smith","designation":"Software Developer","company":"IBM","manager":{"firstName":"Martin","lastName":"Smith","designation":"Manager","company":"IBM"}},"error":null,"id":1}
    If the employee has a collection field addresses type, then the sample output is similar to the following example. {"result":{"firstName":"James","lastName":"Smith","designation":"Software Developer","company":"IBM","adresses":["address1","address2","address3"]},"error":null,"id":1}

    Reusing Instances

    The RPC adapter can be configured (1) to instantiate JavaBeans per request or (2) to reuse instances per user. (For example, a shopping cart object might be configured as the latter.) The default behavior is to instantiate new JavaBeans per request. Reuse is configured through the Bean descriptor information. See the SampleBeanInfo API documentation for details.

    Best practices

    XML Schema:

    The following example is the XML schema for the RPCAdapterConfig.xml file.
    <xsd:schema xmlns="http://www.ibm.com/xmlns/prod/websphere/featurepack/v6.1/RpcAdapterConfig" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/xmlns/prod/websphere/featurepack/v6.1/RpcAdapterConfig" elementFormDefault="qualified"> <xsd:element name="services"> <xsd:complexType> <xsd:sequence> <xsd:element maxOccurs="unbounded" ref="POJO"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="description" type="xsd:string"/> <xsd:element name="scope"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="Application" /> <xsd:enumeration value="Session" /> <xsd:enumeration value="Request" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="validation-regex" type="xsd:string"/> <xsd:element name="validator-ref" type="xsd:string"/> <xsd:element name="default-format" type="xsd:string"/> <xsd:element name="filtered" type="xsd:string"/> <xsd:element name="recursive-object-support" type="xsd:string"/> <xsd:element name="validator"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" ref="validation-regex"/> <xsd:element minOccurs="1" ref="validation-class"/> </xsd:sequence> <xsd:attribute name="id" type="xsd:string" use="required" /> </xsd:complexType> </xsd:element> <xsd:element name="bean-class" type="xsd:string"/> <xsd:element name="converter-class" type="xsd:string"/> <xsd:element name="converter"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" ref="bean-class"/> <xsd:element minOccurs="1" ref="converter-class"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="implementation" type="xsd:string"/> <xsd:element name="methods"> <xsd:complexType> <xsd:sequence> <xsd:element ref="method" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="filter" type="xsd:string"/> </xsd:complexType> </xsd:element> <xsd:element name="name" type="xsd:string"/> <xsd:element name="parameters"> <xsd:complexType> <xsd:sequence> <xsd:element ref="parameter" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="rpcAdapter"> <xsd:complexType> <xsd:sequence> <xsd:element ref="default-format" minOccurs="0"/> <xsd:element minOccurs="0" ref="filtered" maxOccurs="1" /> <xsd:element minOccurs="0" ref="recursive-object-support" maxOccurs="1" /> <xsd:element minOccurs="0" ref="converters" maxOccurs="1" /> <xsd:element minOccurs="0" ref="validators" maxOccurs="1" /> <xsd:element minOccurs="1" ref="services" maxOccurs="1"/> <xsd:element minOccurs="0" ref="serialized-params" maxOccurs="1"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="parameter"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" ref="name"/> <xsd:element minOccurs="0" ref="description"/> <xsd:element minOccurs="0" ref="validator-ref"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="http-method" type="xsd:string"/> <xsd:element name="validation-class" type="xsd:string"/> <xsd:element name="POJO"> <xsd:complexType> <xsd:sequence> <xsd:element ref="name"/> <xsd:element ref="implementation"/> <xsd:element minOccurs="0" ref="description"/> <xsd:element ref="scope" minOccurs="0"/> <xsd:element minOccurs="0" ref="validator-ref"/> <xsd:element minOccurs="0" ref="methods"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="serialized-param-type" type="xsd:string"/> <xsd:element name="suppress" type="xsd:string"/> <xsd:element name="alias" type="xsd:string"/> <xsd:element name="suppressed-field" type="xsd:string"/> <xsd:element name="suppressed-fields"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" ref="suppressed-field" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="serialized-param"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" ref="serialized-param-type"/> <xsd:element minOccurs="0" ref="suppress"/> <xsd:element minOccurs="0" ref="alias"/> <xsd:element minOccurs="0" ref="suppressed-fields"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="serialized-params"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" ref="serialized-param" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="add-to-session" type="xsd:string"/> <xsd:element name="method"> <xsd:complexType> <xsd:sequence> <xsd:element ref="name"/> <xsd:element minOccurs="0" ref="description"/> <xsd:element minOccurs="0" ref="http-method"/> <xsd:element minOccurs="0" ref="parameters"/> <xsd:element minOccurs="0" ref="add-to-session"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="validators"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" ref="validator" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="converters"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" ref="converter" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>