org.xins.server
Class APIServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          org.xins.server.APIServlet

All Implemented Interfaces:

Serializable, Servlet, ServletConfig

public final class APIServlet

extends HttpServlet

HTTP servlet that forwards requests to an API.

HTTP status codes

This servlet supports various HTTP methods, depending on the calling conventions. A request with an unsupported method makes this servlet return the HTTP status code 405 Method Not Allowed.

If no matching function is found, then this servlet returns HTTP status code 404 Not Found.

If the servlet is temporarily unavailable, then the HTTP status 503 Service Unavailable is returned.

If the servlet encountered an initialization error, then the HTTP status code 500 Internal Server Error is returned.

If the state is ready then the HTTP status code 200 OK is returned.

Initialization

When the servlet is initialized, it gathers configuration information from different sources:

1. Build-time settings

The application package contains a web.xml file with build-time settings. Some of these settings are required in order for the XINS/Java Server Framework to start up, while others are optional. These build-time settings are passed to the servlet by the application server as a ServletConfig object. See init(ServletConfig).
The servlet configuration is the responsibility of the assembler.

2. System properties

The location of the configuration file must be passed to the Java VM at startup, as a system property.
System properties are the responsibility of the system administrator.
Example:
java -Dorg.xins.server.config=`pwd`/config/xins.properties -jar orion.jar

3. Configuration file

The configuration file should contain runtime configuration settings, like the settings for the logging subsystem.
Runtime properties are the responsibility of the system administrator.
Example contents for a configuration file:

log4j.rootLogger=DEBUG, console
log4j.appender.console=org.apache.log4j.ConsoleAppender
log4j.appender.console.layout=org.apache.log4j.PatternLayout
log4j.appender.console.layout.ConversionPattern=%d %-5p [%c] %m%n

Since:

XINS 1.0.0

Version:

$Revision: 1.268 $ $Date: 2006/09/06 10:54:31 $

Author:

Ernst de Haan, Anthony Goubard, Mees Witteman

See Also:

Serialized Form

Field Summary

static String	API_BUILD_VERSION_PROPERTY The name of the build property that specifies the version with which the API was built.
static String	API_CALLING_CONVENTION_CLASS_PROPERTY The name of the build property that specifies the class of the default calling convention.
static String	API_CALLING_CONVENTION_PROPERTY The name of the build property that specifies the name of the default calling convention.
static String	API_CLASS_PROPERTY The name of the build property that specifies the name of the API class to load.
static String	API_NAME_PROPERTY The name of the build property that specifies the name of the API.
static String	CALLING_CONVENTION_PARAMETER The name of the request parameter that specifies the name of the calling convention to use.
static String	CONFIG_FILE_SYSTEM_PROPERTY The name of the system property that specifies the location of the configuration file.
static String	CONFIG_RELOAD_INTERVAL_PROPERTY The name of the runtime property that specifies the interval for the configuration file modification checks, in seconds.
static int	DEFAULT_CONFIG_RELOAD_INTERVAL The default configuration file modification check interval, in seconds.
static String	HOSTNAME_PROPERTY The name of the runtime property that hostname for the server running the API.
static String	LOG_LOCALE_PROPERTY Deprecated. Use LogCentral.LOG_LOCALE_PROPERTY.
static String	OLD_STYLE_CALLING_CONVENTION The old-style XINS calling convention.
static String	SOAP_CALLING_CONVENTION The name of the SOAP calling convention.
static String	STANDARD_CALLING_CONVENTION The name of the XINS standard calling convention.
static String	XML_CALLING_CONVENTION The XINS XML calling convention.
static String	XML_RPC_CALLING_CONVENTION The name of the XML-RPC calling convention.
static String	XSLT_CALLING_CONVENTION The XINS XSLT calling convention.

Constructor Summary

APIServlet()
Constructs a new APIServlet object.

Method Summary

void	destroy() Destroys this servlet.
ServletConfig	getServletConfig() Returns the ServletConfig object which contains the build properties for this servlet.
String	getServletInfo() Returns information about this servlet, as plain text.
void	init(ServletConfig config) Initializes this servlet using the specified configuration.
void	initImpl(ServletConfig config) Deprecated. Deprecated since XINS 1.3.0. Use init(ServletConfig) instead.
void	service(HttpServletRequest request, HttpServletResponse response) Handles an HTTP request to this servlet.
void	service(ServletRequest request, ServletResponse response) Handles a request to this servlet.

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletContext, getServletName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONFIG_FILE_SYSTEM_PROPERTY

public static final String CONFIG_FILE_SYSTEM_PROPERTY

The name of the system property that specifies the location of the configuration file.

See Also:

Constant Field Values

CONFIG_RELOAD_INTERVAL_PROPERTY

public static final String CONFIG_RELOAD_INTERVAL_PROPERTY

The name of the runtime property that specifies the interval for the configuration file modification checks, in seconds.

See Also:

Constant Field Values

HOSTNAME_PROPERTY

public static final String HOSTNAME_PROPERTY

The name of the runtime property that hostname for the server running the API.

See Also:

Constant Field Values

DEFAULT_CONFIG_RELOAD_INTERVAL

public static final int DEFAULT_CONFIG_RELOAD_INTERVAL

The default configuration file modification check interval, in seconds.

See Also:

Constant Field Values

API_CLASS_PROPERTY

public static final String API_CLASS_PROPERTY

The name of the build property that specifies the name of the API class to load.

See Also:

Constant Field Values

API_NAME_PROPERTY

public static final String API_NAME_PROPERTY

The name of the build property that specifies the name of the API.

See Also:

Constant Field Values

API_BUILD_VERSION_PROPERTY

public static final String API_BUILD_VERSION_PROPERTY

The name of the build property that specifies the version with which the API was built.

See Also:

Constant Field Values

API_CALLING_CONVENTION_PROPERTY

public static final String API_CALLING_CONVENTION_PROPERTY

The name of the build property that specifies the name of the default calling convention.

See Also:

Constant Field Values

API_CALLING_CONVENTION_CLASS_PROPERTY

public static final String API_CALLING_CONVENTION_CLASS_PROPERTY

The name of the build property that specifies the class of the default calling convention.

See Also:

Constant Field Values

CALLING_CONVENTION_PARAMETER

public static final String CALLING_CONVENTION_PARAMETER

The name of the request parameter that specifies the name of the calling convention to use.

See Also:

Constant Field Values

STANDARD_CALLING_CONVENTION

public static final String STANDARD_CALLING_CONVENTION

The name of the XINS standard calling convention.

See Also:

Constant Field Values

OLD_STYLE_CALLING_CONVENTION

public static final String OLD_STYLE_CALLING_CONVENTION

The old-style XINS calling convention.

See Also:

Constant Field Values

XML_CALLING_CONVENTION

public static final String XML_CALLING_CONVENTION

The XINS XML calling convention.

See Also:

Constant Field Values

XSLT_CALLING_CONVENTION

public static final String XSLT_CALLING_CONVENTION

The XINS XSLT calling convention.

See Also:

Constant Field Values

SOAP_CALLING_CONVENTION

public static final String SOAP_CALLING_CONVENTION

The name of the SOAP calling convention.

Since:

XINS 1.3.0

See Also:

Constant Field Values

XML_RPC_CALLING_CONVENTION

public static final String XML_RPC_CALLING_CONVENTION

The name of the XML-RPC calling convention.

Since:

XINS 1.3.0

See Also:

Constant Field Values

LOG_LOCALE_PROPERTY

public static final String LOG_LOCALE_PROPERTY

Deprecated. Use LogCentral.LOG_LOCALE_PROPERTY.

The name of the runtime property that specifies the locale for the log messages.

See Also:

Constant Field Values

Constructor Detail

APIServlet

public APIServlet()

Constructs a new APIServlet object.

Method Detail

getServletInfo

public String getServletInfo()

Returns information about this servlet, as plain text.

Returns:

textual description of this servlet, not null and not an empty character string.

init

public void init(ServletConfig config)
          throws IllegalArgumentException,
                 ServletException

Initializes this servlet using the specified configuration.

Parameters:

config - the ServletConfig object which contains build properties for this servlet, as specified by the assembler, cannot be null.

Throws:

IllegalArgumentException - if config == null || config.ServletConfig.getServletContext() == null.

ServletException - if the servlet could not be initialized.

initImpl

public void initImpl(ServletConfig config)
              throws ServletException

Deprecated. Deprecated since XINS 1.3.0. Use init(ServletConfig) instead.

Initializes this servlet using the specified configuration. This is a alias for init(ServletConfig). That method should be used instead.

Parameters:

config - the ServletConfig object which contains build properties for this servlet, as specified by the assembler, cannot be null.

Throws:

ServletException - if the servlet could not be initialized.

getServletConfig

public ServletConfig getServletConfig()

Returns the ServletConfig object which contains the build properties for this servlet. The returned ServletConfig object is the one passed to the init(ServletConfig) method.

Returns:

the ServletConfig object that was used to initialize this servlet, or null if this servlet is not yet initialized.

service

public void service(ServletRequest request,
                    ServletResponse response)
             throws NullPointerException,
                    ClassCastException,
                    ServletException,
                    IOException

Handles a request to this servlet. If any of the arguments is null, then the behaviour of this method is undefined.

Parameters:

request - the servlet request, should not be null.

response - the servlet response, should not be null.

Throws:

NullPointerException - if this servlet is yet uninitialized.

ClassCastException - if ! (request instanceof HttpServletRequest && response instanceof HttpServletResponse).

ServletException - if this servlet failed for some other reason that an I/O error.

IOException - if there is an error error writing to the response output stream.

service

public void service(HttpServletRequest request,
                    HttpServletResponse response)
             throws NullPointerException,
                    IOException

Handles an HTTP request to this servlet. If any of the arguments is null, then the behaviour of this method is undefined.

Parameters:

request - the servlet request, should not be null.

response - the servlet response, should not be null.

Throws:

NullPointerException - if this servlet is yet uninitialized.

IOException - if there is an error error writing to the response output stream.

destroy

public void destroy()

Destroys this servlet. A best attempt will be made to release all resources.

After this method has finished, no more requests will be handled successfully.