Java Doc for CallingConvention.java in  » Web-Services » xins » org » xins » server » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Thread safety

Calling convention implementations must be thread-safe.
version:
   $Revision: 1.105.2.1 $ $Date: 2007/09/27 14:43:33 $
author:
   Anthony Goubard
author:
   Ernst de Haan
See Also:   CallingConventionManager

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.

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

The returned array may be null.

Implementations of this method should be optimized for performance, as this method may be called for each incoming request.

A parameter will be removed if it matches any of the following conditions:

• parameter name is null;
• parameter name is empty;
• parameter value is null;
• parameter value is empty;
• parameter name equals "function".

• the state is usable;
• the httpRequest argument is not null;
• the HTTP method is in the set of supported methods, as indicated by CallingConvention.getSupportedMethods() .

Note that CallingConvention.getSupportedMethods(HttpServletRequest) will not have been called prior to this method call.
Parameters:
  httpRequest - the HTTP request.the XINS request object, should not be null.
throws:
  InvalidRequestException - if the request is considerd to be invalid.
throws:
  FunctionNotSpecifiedException - if the request does not indicate the name of the function to execute.

Note that this method is not called if there is an error while converting the request.
Parameters:
  xinsResult - the XINS result object that should be converted to an HTTP response,cannot be null.
Parameters:
  httpResponse - the HTTP response object to configure, cannot be null.
Parameters:
  httpRequest - the HTTP request, cannot be null.
throws:
  IllegalStateException - if this calling convention is currently not usable, seeManageable.assertUsable.
throws:
  IllegalArgumentException - if xinsResult == null|| httpResponse == null|| httpRequest == null.
throws:
  IOException - if the invocation of any of the methods in eitherhttpResponse or httpRequest caused an I/Oerror.

If a parameter is found to have multiple values, then an InvalidRequestException is thrown.
Parameters:
  httpRequest - the HTTP request to get the parameters from, cannot benull.the properties found, or null if none were found.
throws:
  InvalidRequestException - if a parameter is found that has multiple values.

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. the HTTP methods supported, in a String array, mustnot be null.
since:
   XINS 1.5.0

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.the HTTP methods supported for the specified request, in aString array, can be null.
since:
   XINS 1.5.0

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.
Parameters:
  httpRequest - the HTTP request to investigate, never null.true if this calling convention is possiblyable to handle this request, or false if it isdefinitely not able to handle this request.
throws:
  Exception - if analysis of the request causes an exception; in this casefalse will be assumed by the framework.
since:
   XINS 1.4.0

If this calling convention is not usable (see CallingConvention.isUsable() ), then false is returned, even before calling CallingConvention.matches(HttpServletRequest) .

If this method does not support the HTTP method for function invocations, then false is returned.

If CallingConvention.matches(HttpServletRequest) throws an exception, then this exception is ignored and false is returned.

This method is guaranteed not to throw any exception.
Parameters:
  httpRequest - the HTTP request to investigate, cannot be null.true if this calling convention is possiblyable to handle this request, or false if it isdefinitely not able to handle this request.

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.the parsed element, never null.
throws:
  IllegalArgumentException - if httpRequest == null.
throws:
  InvalidRequestException - if the HTTP request cannot be read or cannot be parsed correctly.
since:
   XINS 1.4.0

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.
Parameters:
  checkType - flag indicating whether this method should check that the contenttype of the request is text/xml.the parsed element, never null.
throws:
  IllegalArgumentException - if httpRequest == null.
throws:
  InvalidRequestException - if the HTTP request cannot be read or cannot be parsed correctly.
since:
   XINS 1.3.0