org.xins.server

Class JSONRPC2CallingConvention

java.lang.Object

org.xins.common.manageable.Manageable

org.xins.server.JSONRPCCallingConvention

org.xins.server.JSONRPC2CallingConvention

public class JSONRPC2CallingConvention
extends JSONRPCCallingConvention

The JSON-RPC calling convention. Version 2.0 is supported.

Since:

XINS 3.1.

Version:

$Revision: 1.2 $ $Date: 2013/01/18 10:41:47 $

Author:

Anthony Goubard

Nested Class Summary

Nested classes/interfaces inherited from class org.xins.common.manageable.Manageable

Manageable.State

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	JSON_REQUEST_CONTENT_TYPE The jsonrequest content type.
protected static String	JSON_RPC_CONTENT_TYPE The json-rpc content type.
protected static String	RESPONSE_CONTENT_TYPE The json content type.

Fields inherited from class org.xins.common.manageable.Manageable

BOOTSTRAPPED, BOOTSTRAPPING, DEINITIALIZING, INITIALIZING, UNUSABLE, USABLE

Constructor Summary

Constructors

Constructor and Description
JSONRPC2CallingConvention(API api) Creates a new JSONRPCCallingConvention instance.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	convertResultImpl(FunctionResult xinsResult, HttpServletResponse httpResponse, Map<String,Object> backpack) Converts a XINS result to an HTTP response (implementation method).
protected API	getAPI() Determines the current API.
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 possibly be handled by this calling convention as a function invocation.
protected FunctionRequest	parseGetRequest(HttpServletRequest httpRequest) Parses the JSON-RPC HTTP GET request according to the specs.
protected FunctionRequest	parsePostRequest(HttpServletRequest httpRequest) Parses the JSON-RPC HTTP POST request according to the specs.
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.server.JSONRPCCallingConvention

convertRequestImpl, getErrorDescription, getSupportedMethods

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_CONTENT_TYPE

protected static final String RESPONSE_CONTENT_TYPE

The json content type.

See Also:

Constant Field Values

JSON_RPC_CONTENT_TYPE

protected static final String JSON_RPC_CONTENT_TYPE

The json-rpc content type.

See Also:

Constant Field Values

JSON_REQUEST_CONTENT_TYPE

protected static final String JSON_REQUEST_CONTENT_TYPE

The jsonrequest content type.

See Also:

Constant Field Values

Constructor Detail

JSONRPC2CallingConvention

public JSONRPC2CallingConvention(API api)
                          throws IllegalArgumentException

Creates a new JSONRPCCallingConvention instance.

Parameters:

api - the API, needed for the JSON-RPC messages, cannot be null.

Throws:

IllegalArgumentException - if api == null.

Method Detail

matches

protected boolean matches(HttpServletRequest httpRequest)
                   throws Exception

Checks if the specified request can possibly be handled by this calling convention as a function invocation.

Implementations of this method should be optimized for performance, as this method may be called for each incoming request. Also, this method should not have any side-effects except possibly some caching in case there is a match.

If this method throws any exception, the exception is logged as an ignorable exception and false is assumed.

This method should only be called by the XINS/Java Server Framework.

Overrides:

matches in class JSONRPCCallingConvention

Parameters:

httpRequest - the HTTP request to investigate, never null.

Returns:

true if this calling convention is possibly able to handle this request, or false if it is definitely not able to handle this request.

Throws:

Exception - if analysis of the request causes an exception; in this case false will be assumed by the framework.

parseGetRequest

protected FunctionRequest parseGetRequest(HttpServletRequest httpRequest)
                                   throws InvalidRequestException,
                                          FunctionNotSpecifiedException

Description copied from class: JSONRPCCallingConvention

Parses the JSON-RPC HTTP GET request according to the specs.

Overrides:

parseGetRequest in class JSONRPCCallingConvention

Parameters:

httpRequest - the HTTP request.

Returns:

the XINS request object, should not be 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.

parsePostRequest

protected FunctionRequest parsePostRequest(HttpServletRequest httpRequest)
                                    throws InvalidRequestException,
                                           FunctionNotSpecifiedException

Description copied from class: JSONRPCCallingConvention

Parses the JSON-RPC HTTP POST request according to the specs. http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html

Overrides:

parsePostRequest in class JSONRPCCallingConvention

Parameters:

httpRequest - the HTTP request.

Returns:

the XINS request object, should not be 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,
                     Map<String,Object> backpack)
                          throws IOException

Converts a XINS result to an HTTP response (implementation method). This method should only be called from the XINS/Java Server Framework self. Then it is guaranteed that none of the arguments is null.

Overrides:

convertResultImpl in class JSONRPCCallingConvention

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.

backpack - the backpack.

Throws:

IOException - if the invocation of any of the methods in either httpResponse or httpRequest caused 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(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 getSupportedMethods().

The default implementation of this method returns the set returned by 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 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