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

Direct Known Subclasses:

APIServletSingleThreaded

public 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.290 $ $Date: 2011/02/12 08:22:46 $

Author:

Ernst de Haan, Anthony Goubard, Mees Witteman

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
APIServlet() Constructs a new APIServlet object.

Method Summary

Methods

Modifier and Type	Method and Description
void	destroy() Destroys this servlet.
ServletConfig	getServletConfig() Returns the ServletConfig object which contains the bootstrap 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	service(HttpServletRequest request, HttpServletResponse response) Handles an HTTP request to this servlet.

Methods inherited from class javax.servlet.http.HttpServlet

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

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

Constructor Detail

APIServlet

public APIServlet()

Constructs a new APIServlet object.

Method Detail

getServletInfo

public String getServletInfo()

Returns information about this servlet, as plain text.

Specified by:

getServletInfo in interface Servlet

Overrides:

getServletInfo in class GenericServlet

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.

Specified by:

init in interface Servlet

Overrides:

init in class GenericServlet

Parameters:

config - the ServletConfig object which contains bootstrap 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.

getServletConfig

public ServletConfig getServletConfig()

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

Specified by:

getServletConfig in interface Servlet

Overrides:

getServletConfig in class GenericServlet

Returns:

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

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.

Overrides:

service in class HttpServlet

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.

Specified by:

destroy in interface Servlet

Overrides:

destroy in class GenericServlet