oracle.portal.provider.v1.http
Class HttpProvider

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--oracle.portal.provider.v1.http.HttpProvider

public class HttpProvider

extends javax.servlet.http.HttpServlet

implements ProviderLog

HttpProvider is the entry point into the JPDK runtime. It is a servlet. It hides the details of HTTP communication from the provider/portlet implementor. It is responsible for unmarshalling the HTTP provider request and mapping that request to the Provider interfaces. Likewise, it takes the results of these calls and marshals them into the Http response.

Each HttpProvider instance (servlet) represents a single Provider. The particular provider the HttpProvider servlet represents is registered in one of two ways. Most commonly, the Provider is registered declaratively, in the provider descriptor file called provider.xml. The HttpProvider servlet locates its descriptor file from a serlvet initArgs. The initArg is called provider_root. Its value defines the provider's root or home directory. The HttpProvider locates the provider.xml in this directory.

Note: when using this method, be sure to configure the HttpProvider servlet using servlet aliasing. This allows distinct configurations (and therefore providers) to run in the same server.

Alternatively, one can subclass the HttpProvider servlet to register the Provider class. In this case, the subclass should implement a single (overridden) method getProviderClass. This method returns the class implementing the provider this servlet represents.

Though the HttpProvider servlet represents a single provider (class), the servlet maintains distinct provider instances. One instance is maintained per portal. That is if your web provider is registered in two portals, the HttpProvider servlet will maintain a provider instance for each portal. Provider instances have the same duration as the HttpProvider servlet. That is, once instantiated the instance is maintained (and reused) by the HttpProvider until it itself is destroyed.

As this servlet is designed to be communicated to via the Portal, duplicating these requests in a browser to determine if the serlvet/provider is properly configured and running is difficult. To address this the HttpProvider supports a test mode. If you send a default (unqualified) request to the HttpProvider it will perform various tests and output an HTML response indicating status. For example, in Apache, if the HttpProvider is configured with the servlet alias "sample" you commonly would access it via the URL "http://myserver/servlet/sample. Invoking the HttpProvider in this manner, without any parameters, causes it to run configuration test and report the results back to you in your browser.

HttpProvider is responsible for initializing the provider instance. This can occur by one of two ways. The first is if the provider implements Provider. In this case HttpProvider calls the Provider.init(long,ProviderLog) method. The second is if the provider additionally implements the Initializable interface. In this case, the Initializable.init(ParameterMap) method is called. The ParameterMap passed contains the same information as the first method, accessed using the parameter names

ProviderConstants.PROVIDER_ID
ProviderConstants.PROVIDER_LOG

and additional context information, such as init args, which are also accessible using the ParameterMap.getParameterValue(String) method.

See Also:

Serialized Form

Field Summary

static java.lang.String	AUTO_RELOAD
static java.lang.String	CACHE_LEVEL_HEADER The constant that defines the validate cache header label that identifies the cache (user) level being specified.
static java.lang.String	CACHE_LEVEL_SYSTEM The constant that identifies "system" level caching.
static java.lang.String	CACHE_LEVEL_USER The constant that identifies "user" level caching.
static java.lang.String	CACHE_UPDATE_HEADER_VALUE The constant value that indicates the current response is new and should replace the existing cached content.
static java.lang.String	CACHE_USE_HEADER The constant for the validation based cache header label that is used to indicate the existing (cached) version is valid and should be reused.
static java.lang.String	CACHE_USE_HEADER_VALUE The constant value that indicates the current cached content is still valid and should be returned to the requester.
static java.lang.String	CACHE_VERSION_HEADER The constant that defines the the validate cache header label.
static java.lang.String	DEBUG_LEVEL
static java.lang.String	EXPIRES_HEADER The constant that defines the expires cache header label.
static java.lang.String	PORTLET_RENDER_REQUEST The constant that is used as the key for retrieving the PortletRenderRequest from a HttpServletRequest using getAttribute().
static java.lang.String	PROVIDER_ROOT
static java.lang.String	PROVIDER_USER The constant that is used as the key for retrieving the ProviderUser from the servlet session.
static java.lang.String	RELOAD_INTERVAL
static java.lang.String	REQUEST_ID_HEADER The header used for oracle specific request id.
static java.lang.String	SERVLET_CONFIG The constant that is used as the key for retrieving the ServletConfig from a ServletPortletRenderRequest using getAttribute().
static java.lang.String	SERVLET_CONTEXT The constant that is used as the key for retrieving the ServletContext from a ServletPortletRenderRequest using getAttribute().
static java.lang.String	SERVLET_REQUEST The constant that is used as the key for retrieving the HttpServletRequest from a ServletPortletRenderRequest using getAttribute().
static java.lang.String	SERVLET_RESPONSE The constant that is used as the key for retrieving the HttpServletResponse from a ServletPortletRenderRequest using getAttribute().
static java.lang.String	SESSION_TIMEOUT
static java.lang.String	SHOW_TEST_PAGE
static int	SYSTEM_LEVEL Constant integer value used to indicate system level caching.
static int	USER_LEVEL Constant integer value used to indicate user level caching.

Constructor Summary

HttpProvider()

Method Summary

void	destroy() Standard servlet destroy method.
java.lang.Class	getProviderClass() Returns the Provider class this servlet manages.
void	init(javax.servlet.ServletConfig sc) Standard servlet init method.
void	log(java.lang.String msg) Log the message to the Servlet log.
void	log(java.lang.String msg, java.lang.Throwable t) Log the exception to the Servlet log.
void	service(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Standard servlet service method.

Methods inherited from class javax.servlet.http.HttpServlet

service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo

Methods inherited from class java.lang.Object

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

Field Detail

SERVLET_CONFIG

public static final java.lang.String SERVLET_CONFIG

The constant that is used as the key for retrieving the ServletConfig from a ServletPortletRenderRequest using getAttribute().

SERVLET_CONTEXT

public static final java.lang.String SERVLET_CONTEXT

The constant that is used as the key for retrieving the ServletContext from a ServletPortletRenderRequest using getAttribute().

SERVLET_REQUEST

public static final java.lang.String SERVLET_REQUEST

The constant that is used as the key for retrieving the HttpServletRequest from a ServletPortletRenderRequest using getAttribute().

SERVLET_RESPONSE

public static final java.lang.String SERVLET_RESPONSE

The constant that is used as the key for retrieving the HttpServletResponse from a ServletPortletRenderRequest using getAttribute().

PORTLET_RENDER_REQUEST

public static final java.lang.String PORTLET_RENDER_REQUEST

The constant that is used as the key for retrieving the PortletRenderRequest from a HttpServletRequest using getAttribute(). This is provided so renderers that are implemented as servlets or jsps have a way to get back to the RenderRequest if they need it.

PROVIDER_USER

public static final java.lang.String PROVIDER_USER

The constant that is used as the key for retrieving the ProviderUser from the servlet session. This is provided as an alternative way to reference the current user.

EXPIRES_HEADER

public static final java.lang.String EXPIRES_HEADER

The constant that defines the expires cache header label. Oracle Portal supports expires-based caching. To use this facility, a portlet must write a header value indicating the number of minutes this response is valid for.

CACHE_VERSION_HEADER

public static final java.lang.String CACHE_VERSION_HEADER

The constant that defines the the validate cache header label. Oracle Portal supports validation-based caching. I.e. the portal asks the portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. To support this facility, the portlet must tag their response with a "version". This is written as a header field. This constant defines this header field's name. Subsequent requests from the Portal contain this version header. Clients are expected to read this header and check whether the cached version is still valid.

CACHE_LEVEL_HEADER

public static final java.lang.String CACHE_LEVEL_HEADER

The constant that defines the validate cache header label that identifies the cache (user) level being specified. Oracle Portal supports validation-based caching. I.e. the portal asks the portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. To support this facility, the portlet must tag their response with a "version". As a portlet can render either a user specific version as well as a generic system (default) version, the portlet must also relate which response is being refrenced. This is written as a header field. This constant defines this header field's name. Values are expected to be either "USER" or "SYSTEM" though it is better to use the constants defined herein.

CACHE_LEVEL_USER

public static final java.lang.String CACHE_LEVEL_USER

The constant that identifies "user" level caching. Oracle Portal supports validation-based caching. I.e. the portal asks portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. To support this facility, the portlet must tag their response with a "version". As a portlet can render either a user specific version as weel as a generic system (default) version, the portlet must also relate which response is being refrenced. This is written as a header field. This constant is the value used for this header field that indicates the response is user specific.

USER_LEVEL

public static final int USER_LEVEL

Constant integer value used to indicate user level caching.

CACHE_LEVEL_SYSTEM

public static final java.lang.String CACHE_LEVEL_SYSTEM

The constant that identifies "system" level caching. Oracle Portal supports validation-based caching. I.e. the portal asks portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. To support this facility, the portlet must tag their response with a "version". As a portlet can render either a user specific version as weel as a generic system (default) version, the portlet must also relate which response is being refrenced. This is written as a header field. This constant is the value used for this header field that indicates the response is system (default).

SYSTEM_LEVEL

public static final int SYSTEM_LEVEL

Constant integer value used to indicate system level caching.

CACHE_USE_HEADER

public static final java.lang.String CACHE_USE_HEADER

The constant for the validation based cache header label that is used to indicate the existing (cached) version is valid and should be reused. Oracle Portal supports validation-based caching. I.e. the portal asks portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. The indication of whether to update the cache or reuse the response in the cache is written as a header field. This constant defines this header field's name. Use the constant CACHE_UPDATE_HEADER_VALUE as this header's value to indicate the current response should be cached (overwritting the existing cached response). Use CACHE_USE_HEADER_VALUE as this header's value to indicate the Portal should use the response in its cache.

CACHE_UPDATE_HEADER_VALUE

public static final java.lang.String CACHE_UPDATE_HEADER_VALUE

The constant value that indicates the current response is new and should replace the existing cached content. Oracle Portal supports validation-based caching. I.e. the portal asks portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. The indication of whether to update the cache or reuse the response in the cache is written as a header field. This constant defines the value for CACHE_USE_HEADER that indicates the current response should be cached (overwritting the existing cached response).

CACHE_USE_HEADER_VALUE

public static final java.lang.String CACHE_USE_HEADER_VALUE

The constant value that indicates the current cached content is still valid and should be returned to the requester. Oracle Portal supports validation-based caching. I.e. the portal asks portlet if the current (cached) version is still valid. If it is then it is resused rather then recomputed. The indication of whether to update the cache or reuse the response in the cache is written as a header field. This constant defines the value for CACHE_USE_HEADER that indicates the cached response is still valid and should be used.

REQUEST_ID_HEADER

public static final java.lang.String REQUEST_ID_HEADER

The header used for oracle specific request id.

PROVIDER_ROOT

public static final java.lang.String PROVIDER_ROOT

SESSION_TIMEOUT

public static final java.lang.String SESSION_TIMEOUT

AUTO_RELOAD

public static final java.lang.String AUTO_RELOAD

DEBUG_LEVEL

public static final java.lang.String DEBUG_LEVEL

SHOW_TEST_PAGE

public static final java.lang.String SHOW_TEST_PAGE

RELOAD_INTERVAL

public static final java.lang.String RELOAD_INTERVAL

Constructor Detail

HttpProvider

public HttpProvider()

Method Detail

init

public void init(javax.servlet.ServletConfig sc)
          throws javax.servlet.ServletException

Standard servlet init method. Override to get custom initArgs or to do general initialization. However, you must call super() for HttpProvider to work correctly as this is where getProviderClass() is called.

Overrides:

init in class javax.servlet.GenericServlet

destroy

public void destroy()

Standard servlet destroy method. Overridden to stop the provider thread monitor.

Overrides:

destroy in class javax.servlet.GenericServlet

service

public void service(javax.servlet.http.HttpServletRequest request,
                    javax.servlet.http.HttpServletResponse response)
             throws javax.servlet.ServletException,
                    java.io.IOException

Standard servlet service method. All of the function to adapt from the http request to the Provider interfaces is implemented here. In general you should not override this method. Added support for a test request so developers can determine if they have properly installed/configured their provider. A test request is a browser request to the Provider Adpater (servlet) with no parameters. If a test page is requested, a provider with dummy id = -1 is instantiated and initialised. If successful, showTestPage is invoked with the provider object as parameter, if unsuccessful, the error string is passed to showTestPage. Also logs a warning if a request takes more than a given time to be processed. This time is specified in milliseconds.

Parameters:

request - HttpServletRequest : detects if this is a request for a test page

response - HttpServletResponse :

getProviderClass

public java.lang.Class getProviderClass()
                                 throws javax.servlet.ServletException

Returns the Provider class this servlet manages. By default this method looks for the class name in two places. First it looks for an initArg named provider whose value is a fully qualified class name. If that doesn't exist then it checks to see if the initArg provider_root is set. If it is it looks for a provider.xml file in this root directory and tries to read the classname fron the provider tag. (Its an attribute named "class").

Developers can override this method returning their Provider if they want to have a distinguished servlet on the server.

log

public void log(java.lang.String msg)

Log the message to the Servlet log. The HttpProvider servlet implements the logging function for the provider runtime. This method is one of two defined in the ProviderLog interface. It logs the provided message to the servlet log.

Specified by:

log in interface ProviderLog

Overrides:

log in class javax.servlet.GenericServlet

Parameters:

msg - the message to log.

log

public void log(java.lang.String msg,
                java.lang.Throwable t)

Log the exception to the Servlet log. The HttpProvider servlet implements the logging function for the provider runtime. This method is one of two defined in the ProviderLog interface. It logs the provided message to the servlet log along with information about the thrown exception.

Specified by:

log in interface ProviderLog

Parameters:

msg - the message to log.

t - the exception that represents the reported problem.