com.nitido.nimbox.http
Class HttpNimletDriver

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          com.nitido.nimbox.http.HttpNimletDriver

All Implemented Interfaces:

HttpNimletConstants, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public class HttpNimletDriver
extends javax.servlet.http.HttpServlet
implements HttpNimletConstants

The HttpNimletDriver is an adaptor for a J2EE container to support the dispatching of Nimlets. This module is also know as the HTTP NiMBox. It requires three types of configurations provided by NiM's Configuration Service:

1. HTTP NiMBox Configurations
   - contains the core configuration required by this object.
2. Skin Dispatcher Configuration
   - define the skin dispatchers to be used by this object. This includes the class name of the target skin dispatchers, the mapped protocol name and the settings for each skin dispatcher.
3. Nimlet Configurations
   - specifies all the nimlets to be hosted by this object. This includes the class name of the nimlets, the mapped nimlet name and the settings for each nimlet.
4. Parser Configurations
   - specifies the settings for the HTTP request parser.

HTTP NiMBox Configuration This object requires the following core configuration in order to function properly.

• com.nitido.nimbox.http.container.entityid (Constant is HttpNimletConstants.CONF_KEY_CONTAINER_ENTITY_ID)
  - the identifier of the entity for the HTTP NiMBox. The credential of this entity is used by NiM to authorize the loading and initializing the nimlets.
• com.nitido.nimbox.http.container.entitypwd (Constant is HttpNimletConstants.CONF_KEY_CONTAINER_ENTITY_PWD)
  - the password of the entity for the HTTP NiMBox. The credential of this entity is used by NiM to authorize the loading and initializing the nimlets.
• com.nitido.nimbox.http.container.initallnimlets (Constant is HttpNimletConstants.CONF_KEY_CONTAINER_INIT_ALL_NIMLETS)
  - indicates whether the container will instantiate and initialize ALL specified nimlets when the NiMBox is load. The container will init. all nimlets only if the configuration value is "true". It is recommended to set this value to be "true" so that the system can check if all the nimlet is properly configured before starting the NiMBox.
• com.nitido.nimbox.http.container.errorskin (Constant is HttpNimletConstants.CONF_KEY_ERROR_SKIN)
  - the error skin to be used by this class if there are errors when parsing a HTTP request. For example, when the client submit a multi-part HTTP request, exceptions may generated if the submitted data is too big.

Skin Dispatcher Configuration Every skin dispatcher is registered under a skin type, for example, "nimlet", "dynamic", "static", etc. The configuration for each skin dispatcher type includes the full class name that implements the specific skin dispatcher and the settings for that class.

These configurations will start with the following prefixes:

• com.nitido.nimbox.http.skintype.<TypeName> - Specifies the full class name of the implementation for the specified TypeName of the skin dispatcher.
• com.nitido.nimbox.http.skinsetting.<TypeName>.<SettingKey> - Specifies the value for the setting SettingKey that is associated to the specified skin dispatcher type. To the skin dispatcher, it will receive the SettingKey=SettingValue pair in the HashMap parameter for its initialization method. The required SettingKeys depens on the actual implementation of the skin dispatcher. You should read the corresponding JavaDoc or the operation guide for details.

For example, if I have a nimlet skin dispatcher, I will have the following settings:

• com.nitido.nimbox.http.skintype.nimlet=com.nitido.nimbox.http.SkinDispatcherForNimlet
• com.nitido.nimbox.http.skinsetting.nimlet.timelog=NimletTime
• com.nitido.nimbox.http.skinsetting.nimlet.errorskin=nimlet://ErrorNimlet

This means the "nimlet" skin dispatcher is implemented by "com.nitido.nimbox.http.SkinDispatcherForNimlet". It will have the settings "timelog=NimletTime" and "errorskin=nimlet://ErrorNimlet".

Nimlet Configuration Similar to the skin dispatcher, each nimlet require specification for the implementation's full class name as well as the associated settings. The configurations should have the following format:

• com.nitido.nimbox.http.nimletmap.<NimletName> - Specifies the full class name of the implementation for the specified NimletName of the nimlet.
• com.nitido.nimbox.http.nimletsetting.<NimletName>.<SettingKey> - Specifies the value for the setting SettingKey that is associated to the specified nimlet. To the Nimlet, it will receive the SettingKey=SettingValue pair in the HashMap parameter for its initialization method. The required SettingKeys depens on the actual implementation of the Nimlet. You should read the corresponding JavaDoc or the operation guide for details.

Parser Configuration The HttpNimletDriver supports two type of request parser: regular and multipart. The Multipart parser is usually invoked when the browser posts a request that contains a large attachment stream, usually a file for upload.

All multipart parser configuration should starts with the prefix "com.nitido.nimbox.http.parser.multipart." For example, the "maxpostsize" setting specifies the maximum byte a post data file can be handled by the multipart parser. If you want to make it to be 10K (10240 bytes), the corresponding configuration would be "com.nitido.nimbox.http.parser.multipart.maxpostsize=10240".

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.nitido.nimbox.http.HttpNimletConstants

CONF_KEY_CONTAINER_ENTITY_ID, CONF_KEY_CONTAINER_ENTITY_PWD, CONF_KEY_CONTAINER_INIT_ALL_NIMLETS, CONF_KEY_ERROR_SKIN, CONF_KEY_PREFIX_NIMLET_MAP, CONF_KEY_PREFIX_NIMLET_SETTING, CONF_KEY_PREFIX_PARSER_MULTIPART, CONF_KEY_PREFIX_SKIN_SETTING, CONF_KEY_PREFIX_SKIN_TYPE, CONF_KEY_REG_ENCODING, CONTAINER_TYPE, DEF_SAVE_DIRECTORY, KEY_ENABLE_AD_SERVICE_FLAG, KEY_ERROR_EXCEPTION, KEY_ERROR_MESSAGE, KEY_ERROR_OLD_SKIN, KEY_NIM_ENTITY, KEY_RESPONSE_EXCLUDED_SKINS, KEY_RESPONSE_OVERRIDE_HEADERS, KEY_SKIN_AD_MAP, LEN_KEY_PREFIX_NIMLET_MAP, LEN_KEY_PREFIX_PARSER_MULTIPART, LEN_KEY_PREFIX_SKIN_TYPE, LEN_PREFIX_KEY_RESPONSE_HEADER, LEN_PROTOCOL_DYNAMIC, LEN_PROTOCOL_FORWARD, LEN_PROTOCOL_INCLUDE, LEN_PROTOCOL_NIMLET, LEN_PROTOCOL_REDIRECT, LEN_PROTOCOL_STATIC, LEN_PROTOCOL_VOID, MSG_NO_NIMLET, MULTIPART_PARSER, PARAM_KEY_NIMLET, PREFIX_KEY_RESPONSE_HEADER, PROTOCOL_DYNAMIC, PROTOCOL_FORWARD, PROTOCOL_INCLUDE, PROTOCOL_NIMLET, PROTOCOL_REDIRECT, PROTOCOL_SEPARATOR, PROTOCOL_STATIC, PROTOCOL_VOID, REGULAR_PARSER, REQ_HEADER_CONTENT_TYPE, SKIN_START_DYNAMIC, SKIN_START_FORWARD, SKIN_START_INCLUDE, SKIN_START_NIMLET, SKIN_START_REDIRECT, SKIN_START_STATIC, SKIN_START_VOID, TYPE_MULTIPART_FORM

Constructor Summary

HttpNimletDriver()
Default constructor.

Method Summary

void	doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) This method is responsible for handling HTTP-GET requests and it is automatically invoked by the J2EE servlet container.
void	doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) This method is responsible for handling HTTP-POST requests and it is automatically invoked by the J2EE servlet container.
protected Nimlet	getNimlet(java.lang.String nimletName) This method is used by the NimletSkinDispatcher for getting the actual instance of the Nimlet being dispatched.
protected SkinDispatcher	getSkinDispatcher(java.lang.String skinProtocol) This method returns a reference to the instance of the SkinDispatcher used to dispatch the given skin protocol.
protected void	handleError(HttpNimletContainer container, java.lang.Exception e) This method is invoked by the handleRequest() method of the class when this method encounters an error.
protected void	handleRequest(java.lang.String requestType, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) This method is used to handle regular HTTP request from the client.
void	init() This method is used to initialized the Nimlet driver.
protected void	notifyOfError(HttpNimletContainer container, java.lang.Exception rootCause, int errorCode) This method notifies the user of a system exception.
protected void	sendSystemResponse(javax.servlet.http.HttpServletResponse response, int errorCode, java.lang.String errorMessage) This method sends the given HTTP error code and error message back to the client browser.

Methods inherited from class javax.servlet.http.HttpServlet

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

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpNimletDriver

public HttpNimletDriver()

Default constructor.

Method Detail

init

public void init()
          throws javax.servlet.ServletException

This method is used to initialized the Nimlet driver. This method is guaranteed to be called at most one time, by the J2EE application server.

Overrides:

init in class javax.servlet.GenericServlet

Throws:

javax.servlet.ServletException

doGet

public void doGet(javax.servlet.http.HttpServletRequest req,
                  javax.servlet.http.HttpServletResponse res)
           throws javax.servlet.ServletException,
                  java.io.IOException

This method is responsible for handling HTTP-GET requests and it is automatically invoked by the J2EE servlet container.

Overrides:

doGet in class javax.servlet.http.HttpServlet

Parameters:

req - Reference to the HttpServletRequest object with all the parameters associated with the request sent from the client.

res - Reference to the response the server sends to the client.

Throws:

javax.servlet.ServletException - If the request for the GET could not be handled.

java.io.IOException - If an input or output error is detected when the servlet handles the GET request

doPost

public void doPost(javax.servlet.http.HttpServletRequest req,
                   javax.servlet.http.HttpServletResponse res)
            throws javax.servlet.ServletException,
                   java.io.IOException

This method is responsible for handling HTTP-POST requests and it is automatically invoked by the J2EE servlet container. NOTE: This doPost method CAN handle multipart file submission.

Overrides:

doPost in class javax.servlet.http.HttpServlet

Parameters:

req - Reference to the HttpServletRequest object with all the parameters associated with the request sent from the client.

res - Reference to the response the server sends to the client.

Throws:

javax.servlet.ServletException - If the request for the POST could not be handled.

java.io.IOException - If an input or output error is detected when the servlet handles the POST request

getNimlet

protected Nimlet getNimlet(java.lang.String nimletName)
                    throws javax.servlet.ServletException

This method is used by the NimletSkinDispatcher for getting the actual instance of the Nimlet being dispatched.

Parameters:

nimletName - The name of the nimlet to be dispatched.

Returns:

Reference to the Nimlet instance that is associated with the given name

Throws:

javax.servlet.ServletException - If the specified nimlet has not been configured to be used with this driver. This is one of the standard Java Servlet exceptions.

getSkinDispatcher

protected SkinDispatcher getSkinDispatcher(java.lang.String skinProtocol)
                                    throws javax.servlet.ServletException

This method returns a reference to the instance of the SkinDispatcher used to dispatch the given skin protocol.

Parameters:

skinProtocol - The skin protocol name. This parameter must include the protocol postfix string "://". For e.g. "nimlet://" or "static://"

Throws:

javax.servlet.ServletException - This exception is thrown if the driver does not support the given skin protocol.

handleRequest

protected void handleRequest(java.lang.String requestType,
                             javax.servlet.http.HttpServletRequest req,
                             javax.servlet.http.HttpServletResponse res)
                      throws javax.servlet.ServletException,
                             java.io.IOException

This method is used to handle regular HTTP request from the client.

Parameters:

requestType - The request type.

req - Reference to the request from the client to the server

res - Reference to the response from the server to the client

Throws:

javax.servlet.ServletException - If the request could not be handled.

java.io.IOException - If an input or output error is detected when the servlet handles the request

handleError

protected void handleError(HttpNimletContainer container,
                           java.lang.Exception e)
                    throws java.io.IOException,
                           javax.servlet.ServletException

This method is invoked by the handleRequest() method of the class when this method encounters an error. This method will set the appropriate error codes and will determine the root cause of the exception before notifying the client of the problem.

Parameters:

container - Reference to the HttpNimletContainer object.

e - Reference to the exception associated with the problem when handling the client request.

Throws:

java.io.IOException - If the system is unable to notify the client of the problem.

javax.servlet.ServletException

sendSystemResponse

protected void sendSystemResponse(javax.servlet.http.HttpServletResponse response,
                                  int errorCode,
                                  java.lang.String errorMessage)
                           throws java.io.IOException

This method sends the given HTTP error code and error message back to the client browser.

Parameters:

response - Reference to the HTTP Servlet Response object

errorCode - A valid HTTP error code. It must be one of the possible HTTP error codes described in the HTTPServletResponse interface.

errorMessage - The error message to be included in the response

Throws:

java.io.IOException

notifyOfError

protected void notifyOfError(HttpNimletContainer container,
                             java.lang.Exception rootCause,
                             int errorCode)
                      throws java.io.IOException,
                             javax.servlet.ServletException

This method notifies the user of a system exception. It first attempts to dispatch the default application error skin. If no default error skin has been configured, the driver will send an HTTP error heather back to the client.

Parameters:

container - Reference to the NimletContainer.

rootCause - Reference to the exception that caused the error.

errorCode - The Http error code to send.

Throws:

java.io.IOException - If unable to notify the client.

javax.servlet.ServletException