de.dfki.util.xmlrpc
Class XmlRpc

java.lang.Object
  extended by de.dfki.util.xmlrpc.XmlRpc

public class XmlRpc
extends java.lang.Object

Offers some useful static methods for creating remote clients and do type conversion.

Author:
lauer

Nested Class Summary
static class XmlRpc.Type
          XML-RPC Type constants.
 
Constructor Summary
XmlRpc()
           
 
Method Summary
static
<API> API
createClient(java.lang.Class<API> apiClass, java.lang.String handlerName, java.lang.String host, int port)
          Create a remote client which connects to the given host and port using the specified API.
static
<API> API
createClient(java.lang.Class<API> apiClass, java.lang.String handlerName, XmlRpcConnection xmlRpcConnection)
          Creates a XML-RPC client for the given API class.
static
<API> API
createClient(java.lang.Class<API> apiClass, java.lang.String handlerName, XmlRpcConnection xmlRpcConnection, java.lang.ClassLoader classLoader)
          Creates a XML-RPC client for the given API class.
static
<API> API
createClient(java.lang.Class<API> apiClass, XmlRpcConnection xmlRpcConnection)
           
static
<API> API
createClientForClass(java.lang.Class<API> baseClass, java.lang.String handlerName, XmlRpcConnection xmlRpcConnection)
          Creates a remote proxy for a given class.
static
<API> API
createClientForClass(java.lang.Class<API> baseClass, java.lang.String handlerName, XmlRpcConnection xmlRpcConnection, java.lang.Class<?>[] parameterTypes, java.lang.Object[] baseCtorArgs)
          Creates a remote proxy for a given class.
static java.util.Map<java.lang.reflect.Method,java.lang.Boolean> getMethodXmlRpcComplianceMap(java.lang.Class<?> apiClass)
          Tests all methods of the given API whether they are XML-RPC compliant or not.
static TypeConverter getTypeConverter()
           
static
<T> T
getUserRepresentation(java.lang.Class<T> targetClass, java.lang.Object xmlRpcRepresentation)
          Converts a XML-RPC representation into an instance of the given type.
static java.lang.Object getXmlRpcRepresentation(java.lang.Class<?> userPrepresentationType, java.lang.Object toConvert)
          Converts an instance of a certain type into a XML-RPC representation.
static java.lang.Object getXmlRpcRepresentation(java.lang.Object toConvert)
          Same as getXmlRpcRepresentation(Class, Object).
static boolean isTreatUnknownTypesAsBeans()
           
static java.util.logging.Logger log()
           
static void treatUnknownTypesAsBeans(boolean b)
          Enables the fall-back behaviour to treat all unknown types as XmlRpcBeans (instead of throwing an exception).
static void useAutomaticNullMasking(boolean b)
          Enables/Disables the automatic null-masking ability.
static boolean usesAutomaticNullMasking()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlRpc

public XmlRpc()
Method Detail

log

public static java.util.logging.Logger log()

createClient

public static <API> API createClient(java.lang.Class<API> apiClass,
                                     java.lang.String handlerName,
                                     java.lang.String host,
                                     int port)
Create a remote client which connects to the given host and port using the specified API.

Parameters:
apiClass - The client interface class.
handlerName - The name of the server-side XML-RPC handler.
host - The host the server is located at.
port - The port the server is listening at.
Returns:
An instance of a XML-RPC client. This instance can also be casted to XmlRpcClient.

createClient

public static <API> API createClient(java.lang.Class<API> apiClass,
                                     java.lang.String handlerName,
                                     XmlRpcConnection xmlRpcConnection)
Creates a XML-RPC client for the given API class. The client will be created in ClassLoader of Thread.currentThread().

Parameters:
apiClass - The client interface class.
handlerName - The name of the server-side XML-RPC handler.
xmlRpcConnection - The connection the client should connect to.
Returns:
An instance of a XML-RPC client. This instance can also be casted to XmlRpcClient.

createClient

public static <API> API createClient(java.lang.Class<API> apiClass,
                                     java.lang.String handlerName,
                                     XmlRpcConnection xmlRpcConnection,
                                     java.lang.ClassLoader classLoader)
Creates a XML-RPC client for the given API class. The client will be created in ClassLoader of Thread.currentThread().

Parameters:
apiClass - The client interface class.
handlerName - The name of the server-side XML-RPC handler.
xmlRpcConnection - The connection the client should connect to.
classLoader - The ClassLoader to use for proxy generation
Returns:
An instance of a XML-RPC client. This instance can also be casted to XmlRpcClient.

createClientForClass

public static <API> API createClientForClass(java.lang.Class<API> baseClass,
                                             java.lang.String handlerName,
                                             XmlRpcConnection xmlRpcConnection)
Creates a remote proxy for a given class. Even for abstract classes. This call expects the base class to have a default constructor without arguments.

Parameters:
baseClass - The class to build the remote proxy for.
handlerName - The name of the server-side XML-RPC handler.
xmlRpcConnection - The connection the client should connect to.
Returns:
An instance of a XML-RPC client. This instance can also be casted to XmlRpcClient.

createClientForClass

public static <API> API createClientForClass(java.lang.Class<API> baseClass,
                                             java.lang.String handlerName,
                                             XmlRpcConnection xmlRpcConnection,
                                             java.lang.Class<?>[] parameterTypes,
                                             java.lang.Object[] baseCtorArgs)
Creates a remote proxy for a given class. Even for abstract classes. Parameters for the base class constructor can be passed via parameterTypes and baseCtorArgs.

Parameters:
baseClass - The class to build the remote proxy for.
handlerName - The name of the server-side XML-RPC handler.
xmlRpcConnection - The connection the client should connect to.
parameterTypes - Array of Classes identifying a unique constructor of the base class.
baseCtorArgs - Arguments passed to the constructor.
Returns:
An instance of a XML-RPC client. This instance can also be casted to XmlRpcClient.

createClient

public static <API> API createClient(java.lang.Class<API> apiClass,
                                     XmlRpcConnection xmlRpcConnection)

getMethodXmlRpcComplianceMap

public static java.util.Map<java.lang.reflect.Method,java.lang.Boolean> getMethodXmlRpcComplianceMap(java.lang.Class<?> apiClass)
Tests all methods of the given API whether they are XML-RPC compliant or not. Types which define proper type conversion operations are treated as compliant types. Use this method to detect type-based errors early in a validation phase and not at some random time in the past when using the malformed types.

Parameters:
apiClass - The API class.
Returns:
A Map which has an entry for each API method stating whether this method is XML-RPC compliant or not.

useAutomaticNullMasking

public static void useAutomaticNullMasking(boolean b)
Enables/Disables the automatic null-masking ability. That is, null-values in method calls and return statements are automatically masked (as a zero-length byte-array) and turned back to null-values on the receiver side.
NOTE: this feature works for all built-in XML-RPC types except BASE64 and for types with user-defined conversions.

Parameters:
b - true enables masking mode. false disables it.

usesAutomaticNullMasking

public static boolean usesAutomaticNullMasking()

treatUnknownTypesAsBeans

public static void treatUnknownTypesAsBeans(boolean b)
Enables the fall-back behaviour to treat all unknown types as XmlRpcBeans (instead of throwing an exception).

Parameters:
b - true, to enable this feature. false to disable it (=default)

isTreatUnknownTypesAsBeans

public static boolean isTreatUnknownTypesAsBeans()

getTypeConverter

public static TypeConverter getTypeConverter()

getXmlRpcRepresentation

public static java.lang.Object getXmlRpcRepresentation(java.lang.Class<?> userPrepresentationType,
                                                       java.lang.Object toConvert)
                                                throws TypeConversionException
Converts an instance of a certain type into a XML-RPC representation. If the type defines a type conversion (type annotation(XmlRpc) this is used for conversion. Converter mappings used in the API interface (ConverterMappings) will only be used if the API has been processed by a a createClient(java.lang.Class, java.lang.String, java.lang.String, int) or a XmlRpcHandlerFactory.createHandlerFor(Object) call before or a converter has been registered before using ParameterConverterRegistry.setParameterConverterForClass(Class, Class).

Throws:
TypeConversionException: - Denotes problems while converting representations. This may include missing annotations, illegal object types, missing converter mappings, ...
TypeConversionException

getXmlRpcRepresentation

public static java.lang.Object getXmlRpcRepresentation(java.lang.Object toConvert)
                                                throws TypeConversionException
Same as getXmlRpcRepresentation(Class, Object). The representation type is taken directly from the object to convert.

Throws:
TypeConversionException

getUserRepresentation

public static <T> T getUserRepresentation(java.lang.Class<T> targetClass,
                                          java.lang.Object xmlRpcRepresentation)
                               throws TypeConversionException
Converts a XML-RPC representation into an instance of the given type. If the type defines a type conversion (type annotation(XmlRpc) this is used for conversion. Converter mappings used in the API interface (ConverterMappings) will only be used if the API has been processed by a a createClient(java.lang.Class, java.lang.String, java.lang.String, int) or a XmlRpcHandlerFactory.createHandlerFor(Object) call before.

Parameters:
targetClass - Type to convert to.
xmlRpcRepresentation - The XML-RPC representation.
Throws:
TypeConversionException: - Denotes problems while converting representations. This may include missing annotations, illegal object types, ...
TypeConversionException


Copyright © 2012. All Rights Reserved.