org.apache.xmlrpc.server
Class AbstractReflectiveHandlerMapping

java.lang.Object
  extended by org.apache.xmlrpc.server.AbstractReflectiveHandlerMapping
All Implemented Interfaces:
XmlRpcListableHandlerMapping, XmlRpcHandlerMapping
Direct Known Subclasses:
DynamicHandlerMapping, PropertyHandlerMapping

public abstract class AbstractReflectiveHandlerMapping
extends java.lang.Object
implements XmlRpcListableHandlerMapping

Abstract base class of handler mappings, which are using reflection.


Nested Class Summary
static interface AbstractReflectiveHandlerMapping.AuthenticationHandler
          An object implementing this interface may be used to validate user names and passwords.
static interface AbstractReflectiveHandlerMapping.InitializationHandler
          An object, which is called for initializing the actual handler object.
 
Field Summary
protected  java.util.Map handlerMap
           
 
Constructor Summary
protected AbstractReflectiveHandlerMapping(TypeConverterFactory pTypeConverterFactory, boolean pInstanceIsStateless)
          Creates a new instance.
 
Method Summary
 AbstractReflectiveHandlerMapping.AuthenticationHandler getAuthenticationHandler()
          Returns the authentication handler, if any, or null.
 XmlRpcHandler getHandler(java.lang.String pHandlerName)
          Returns the XmlRpcHandler with the given name.
 AbstractReflectiveHandlerMapping.InitializationHandler getInitializationHandler()
          Returns the initialization handler, if any, or null.
 java.lang.String[] getListMethods()
          This method implements the introspection method system.listMethods, which is specified as follows:
protected  java.lang.String getMethodHelp(java.lang.Class pClass, java.lang.reflect.Method[] pMethods)
          Creates a help string for the given method, when applied to the given class.
 java.lang.String getMethodHelp(java.lang.String pHandlerName)
          This method implements the introspection method system.methodSignature, which is specified as follows:
 java.lang.String[][] getMethodSignature(java.lang.String pHandlerName)
          This method implements the introspection method system.methodSignature, which is specified as follows:
protected  java.lang.String[][] getSignature(java.lang.reflect.Method[] pMethods)
          Creates a signature for the given method.
protected  XmlRpcHandler newXmlRpcHandler(java.lang.Class pClass, java.lang.reflect.Method[] pMethods)
          Creates a new instance of XmlRpcHandler.
protected  void registerPublicMethods(java.util.Map pMap, java.lang.String pKey, java.lang.Class pType)
          Searches for methods in the given class.
 void setAuthenticationHandler(AbstractReflectiveHandlerMapping.AuthenticationHandler pAuthenticationHandler)
          Sets the authentication handler, if any, or null.
 void setInitializationHandler(AbstractReflectiveHandlerMapping.InitializationHandler pInitializationHandler)
          Sets the initialization handler, if any, or null.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

handlerMap

protected java.util.Map handlerMap
Constructor Detail

AbstractReflectiveHandlerMapping

protected AbstractReflectiveHandlerMapping(TypeConverterFactory pTypeConverterFactory,
                                           boolean pInstanceIsStateless)
Creates a new instance.

Parameters:
pInstanceIsStateless - The handler can operate in either of two operation modes:
  1. The object, which is actually performing the requests, is initialized at startup. In other words, there is only one object, which is performing all the requests. Obviously, this is the faster operation mode. On the other hand, it has the disadvantage, that the object must be stateless.
  2. A new object is created for any request. This is slower, because the object needs to be initialized. On the other hand, it allows for stateful objects, which may take request specific configuration like the clients IP address, and the like.
Method Detail

getAuthenticationHandler

public AbstractReflectiveHandlerMapping.AuthenticationHandler getAuthenticationHandler()
Returns the authentication handler, if any, or null.


setAuthenticationHandler

public void setAuthenticationHandler(AbstractReflectiveHandlerMapping.AuthenticationHandler pAuthenticationHandler)
Sets the authentication handler, if any, or null.


getInitializationHandler

public AbstractReflectiveHandlerMapping.InitializationHandler getInitializationHandler()
Returns the initialization handler, if any, or null.


setInitializationHandler

public void setInitializationHandler(AbstractReflectiveHandlerMapping.InitializationHandler pInitializationHandler)
Sets the initialization handler, if any, or null.


registerPublicMethods

protected void registerPublicMethods(java.util.Map pMap,
                                     java.lang.String pKey,
                                     java.lang.Class pType)
                              throws XmlRpcException
Searches for methods in the given class. For any valid method, it creates an instance of XmlRpcHandler. Valid methods are defined as follows:

Parameters:
pMap - Handler map, in which created handlers are being registered.
pKey - Suffix for building handler names. A dot and the method name are being added.
pType - The class being inspected.
Throws:
XmlRpcException

newXmlRpcHandler

protected XmlRpcHandler newXmlRpcHandler(java.lang.Class pClass,
                                         java.lang.reflect.Method[] pMethods)
                                  throws XmlRpcException
Creates a new instance of XmlRpcHandler.

Parameters:
pClass - The class, which was inspected for handler methods. This is used for error messages only. Typically, it is the same than
pInstance.getClass()
.
pMethods - The method being invoked.
Throws:
XmlRpcException

getSignature

protected java.lang.String[][] getSignature(java.lang.reflect.Method[] pMethods)
Creates a signature for the given method.


getMethodHelp

protected java.lang.String getMethodHelp(java.lang.Class pClass,
                                         java.lang.reflect.Method[] pMethods)
Creates a help string for the given method, when applied to the given class.


getHandler

public XmlRpcHandler getHandler(java.lang.String pHandlerName)
                         throws XmlRpcNoSuchHandlerException,
                                XmlRpcException
Returns the XmlRpcHandler with the given name.

Specified by:
getHandler in interface XmlRpcHandlerMapping
Parameters:
pHandlerName - The handlers name
Returns:
Object The desired handler. Never null, an exception is thrown if no such handler is available.
Throws:
XmlRpcNoSuchHandlerException - A handler with the given name is unknown.
XmlRpcException - An internal error occurred.

getListMethods

public java.lang.String[] getListMethods()
                                  throws XmlRpcException
Description copied from interface: XmlRpcListableHandlerMapping
This method implements the introspection method system.listMethods, which is specified as follows:

This method may be used to enumerate the methods implemented by the XML-RPC server.

The system.listMethods method requires no parameters. It returns an array of strings, each of which is the name of a method implemented by the server.

Note, that the specification doesn't require that the list must be exhaustive. We conclude, that a valid method "handlerName" doesn't need to be in the list. For example, a handler, which implements XmlRpcHandler, but not XmlRpcMetaDataHandler, should possibly excluded: Otherwise, the listable handler mapping could not provide meaningful replies to system.methodSignature, and system.methodHelp.

Specified by:
getListMethods in interface XmlRpcListableHandlerMapping
Throws:
XmlRpcException - An internal error occurred.

getMethodHelp

public java.lang.String getMethodHelp(java.lang.String pHandlerName)
                               throws XmlRpcException
Description copied from interface: XmlRpcListableHandlerMapping
This method implements the introspection method system.methodSignature, which is specified as follows:

This method takes one parameter, the name of a method implemented by the XML-RPC server. It returns a documentation string describing the use of that method. If no such string is available, an empty string is returned.

The documentation string may contain HTML markup.

Specified by:
getMethodHelp in interface XmlRpcListableHandlerMapping
Throws:
XmlRpcException

getMethodSignature

public java.lang.String[][] getMethodSignature(java.lang.String pHandlerName)
                                        throws XmlRpcException
Description copied from interface: XmlRpcListableHandlerMapping
This method implements the introspection method system.methodSignature, which is specified as follows:

This method takes one parameter, the name of a method implemented by the XML-RPC server. It returns an array of possible signatures for this method. A signature is an array of types. The first of these types is the return type of the method, the rest are parameters.

Multiple signatures (ie. overloading) are permitted: this is the reason that an array of signatures are returned by this method.

Signatures themselves are restricted to the top level parameters expected by a method. For instance if a method expects one array of structs as a parameter, and it returns a string, its signature is simply "string, array". If it expects three integers, its signature is "string, int, int, int".

If no signature is defined for the method, a none-array value is returned. Therefore this is the way to test for a non-signature, if $resp below is the response object from a method call to system.methodSignature:

      $v=$resp->value();
      if ($v->kindOf()!="array") {
        // then the method did not have a signature defined
      }
    
See the introspect.php demo included in this distribution for an example of using this method.

Specified by:
getMethodSignature in interface XmlRpcListableHandlerMapping
Throws:
XmlRpcException
See Also:
XmlRpcMetaDataHandler.getSignatures()


Copyright © 2001-2006 Apache Software Foundation. All Rights Reserved.