org.xins.server
Class StandardCallingConvention

java.lang.Object
  extended byorg.xins.common.manageable.Manageable
      extended byorg.xins.server.CallingConvention
          extended byorg.xins.server.StandardCallingConvention
Direct Known Subclasses:
XSLTCallingConvention

public class StandardCallingConvention
extends org.xins.server.CallingConvention

Standard calling convention. The technical name for this calling convention is _xins-std.

Version:
$Revision: 1.65 $ $Date: 2008/07/04 10:22:51 $
Author:
Anthony Goubard, Ernst de Haan

Nested Class Summary
 
Nested classes inherited from class org.xins.common.manageable.Manageable
Manageable.State
 
Field Summary
protected static String RESPONSE_CONTENT_TYPE
          The content type of the HTTP response.
protected static String RESPONSE_ENCODING
          The response encoding format.
 
Fields inherited from class org.xins.common.manageable.Manageable
BOOTSTRAPPED, BOOTSTRAPPING, DEINITIALIZING, INITIALIZING, UNUSABLE, USABLE
 
Constructor Summary
StandardCallingConvention()
           
 
Method Summary
protected  FunctionRequest convertRequestImpl(HttpServletRequest httpRequest)
          Converts an HTTP request to a XINS request (implementation method).
protected  void convertResultImpl(FunctionResult xinsResult, HttpServletResponse httpResponse, HttpServletRequest httpRequest)
          Converts a XINS result to an HTTP response (implementation method).
protected  API getAPI()
          Determines the current API.
protected  String[] getSupportedMethods()
          Determines which HTTP methods are supported for function invocations.
protected  String[] getSupportedMethods(HttpServletRequest request)
          Determines which HTTP methods are supported for function invocations, for the specified request.
protected  boolean matches(HttpServletRequest httpRequest)
          Checks if the specified request can be handled by this calling convention.
protected  Element parseXMLRequest(HttpServletRequest httpRequest)
          Parses XML from the specified HTTP request and checks that the content type is correct.
protected  Element parseXMLRequest(HttpServletRequest httpRequest, boolean checkType)
          Parses XML from the specified HTTP request and optionally checks that the content type is correct.
 
Methods inherited from class org.xins.common.manageable.Manageable
assertUsable, bootstrap, bootstrapImpl, deinit, deinitImpl, getState, init, initImpl, isBootstrapped, isUsable
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

RESPONSE_ENCODING

protected static final String RESPONSE_ENCODING
The response encoding format.

See Also:
Constant Field Values

RESPONSE_CONTENT_TYPE

protected static final String RESPONSE_CONTENT_TYPE
The content type of the HTTP response.

See Also:
Constant Field Values
Constructor Detail

StandardCallingConvention

public StandardCallingConvention()
Method Detail

matches

protected boolean matches(HttpServletRequest httpRequest)
Checks if the specified request can be handled by this calling convention.

This method will not throw any exception.

Parameters:
httpRequest - the HTTP request to investigate, cannot be null.
Returns:
true if this calling convention is possibly able to handle this request, or false if it definitely not able to handle this request.

convertRequestImpl

protected FunctionRequest convertRequestImpl(HttpServletRequest httpRequest)
                                      throws InvalidRequestException,
                                             FunctionNotSpecifiedException
Converts an HTTP request to a XINS request (implementation method). This method should only be called from class CallingConvention. Only then it is guaranteed that the httpRequest argument is not null.

Parameters:
httpRequest - the HTTP request, will not be null.
Returns:
the XINS request object, never null.
Throws:
InvalidRequestException - if the request is considerd to be invalid.
FunctionNotSpecifiedException - if the request does not indicate the name of the function to execute.

convertResultImpl

protected void convertResultImpl(FunctionResult xinsResult,
                                 HttpServletResponse httpResponse,
                                 HttpServletRequest httpRequest)
                          throws IOException
Converts a XINS result to an HTTP response (implementation method).

Parameters:
xinsResult - the XINS result object that should be converted to an HTTP response, will not be null.
httpResponse - the HTTP response object to configure, will not be null.
httpRequest - the HTTP request, will not be null.
Throws:
IOException - if calling any of the methods in httpResponse causes an I/O error.

getAPI

protected final API getAPI()
Determines the current API.

Returns:
the current API, never null.
Since:
XINS 1.5.0

getSupportedMethods

protected String[] getSupportedMethods()
Determines which HTTP methods are supported for function invocations.

Each String in the returned array must be one supported method.

The returned array must not be null, it must only contain valid HTTP method names, so they may not contain whitespace, for example. Duplicates will be ignored. HTTP method names must be in uppercase.

There must be at least one HTTP method supported for function invocations.

Note that OPTIONS must not be returned by this method, as it is not an HTTP method that can ever be used to invoke a XINS function.

HTTP OPTIONS requests are treated differently. For the path * the capabilities of the whole server are returned. For other paths, the appropriate calling convention is determined, after which the set of supported HTTP methods is returned to the called.

Returns:
the HTTP methods supported, in a String array, must not be null.
Since:
XINS 1.5.0

getSupportedMethods

protected String[] getSupportedMethods(HttpServletRequest request)
Determines which HTTP methods are supported for function invocations, for the specified request.

Each String in the returned array must be one supported method.

The returned array may be null. If it is not, then the returned array must only contain valid HTTP method names, so they may not contain whitespace, for example. HTTP method names must be in uppercase.

There must be at least one HTTP method supported for function invocations.

Note that OPTIONS must not be returned by this method, as it is not an HTTP method that can ever be used to invoke a XINS function.

The set of supported methods must be a subset of the set returned by CallingConvention.getSupportedMethods().

The default implementation of this method returns the set returned by CallingConvention.getSupportedMethods().

Parameters:
request - the request to determine the supported methods for.
Returns:
the HTTP methods supported for the specified request, in a String array, can be null.
Since:
XINS 1.5.0

parseXMLRequest

protected Element parseXMLRequest(HttpServletRequest httpRequest)
                           throws IllegalArgumentException,
                                  InvalidRequestException
Parses XML from the specified HTTP request and checks that the content type is correct.

This method uses a cache to optimize performance if either of the parseXMLRequest methods is called multiple times for the same request.

Calling this method is equivalent with calling CallingConvention.parseXMLRequest(HttpServletRequest,boolean) with the checkType argument set to true.

Parameters:
httpRequest - the HTTP request, cannot be null.
Returns:
the parsed element, never null.
Throws:
IllegalArgumentException - if httpRequest == null.
InvalidRequestException - if the HTTP request cannot be read or cannot be parsed correctly.
Since:
XINS 1.4.0

parseXMLRequest

protected Element parseXMLRequest(HttpServletRequest httpRequest,
                                  boolean checkType)
                           throws IllegalArgumentException,
                                  InvalidRequestException
Parses XML from the specified HTTP request and optionally checks that the content type is correct.

Since XINS 1.4.0, this method uses a cache to optimize performance if either of the parseXMLRequest methods is called multiple times for the same request.

Parameters:
httpRequest - the HTTP request, cannot be null.
checkType - flag indicating whether this method should check that the content type of the request is text/xml.
Returns:
the parsed element, never null.
Throws:
IllegalArgumentException - if httpRequest == null.
InvalidRequestException - if the HTTP request cannot be read or cannot be parsed correctly.
Since:
XINS 1.3.0


See http://www.xins.org/.