org.xins.server
Class APIServlet

java.lang.Object
  extended byjavax.servlet.GenericServlet
      extended byjavax.servlet.http.HttpServlet
          extended byorg.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.285 $ $Date: 2007/09/18 08:45:03 $
Author:
Ernst de Haan, Anthony Goubard, Mees Witteman
See Also:
Serialized Form

Constructor Summary
APIServlet()
          Constructs a new APIServlet object.
 
Method Summary
 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.

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 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.

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.

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.



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