@ConsumerType public abstract class ServletContextHelper extends Object
This service defines methods that the Http Whiteboard implementation may call to get information for a request when dealing with whiteboard services.
Each ServletContextHelper
is registered with a
"osgi.http.whiteboard.context.name"
service property containing a name to
reference by servlets, servlet filters, resources, and listeners. If there is
more than one ServletContextHelper
registered with the same context
name, the one with the highest service ranking is active, the others are
inactive.
A context is registered with the
"osgi.http.whiteboard.context.path"
service property to define a path under
which all services registered with this context are reachable. If there is
more than one ServletContextHelper
registered with the same path,
each duplicate context path is searched by service ranking order according to
ServiceReference.compareTo(Object)
until a
matching servlet or resource is found.
Servlets, servlet filters, resources, and listeners services may be
associated with a ServletContextHelper
service with the
"osgi.http.whiteboard.context.select"
service property. If the referenced
ServletContextHelper
service does not exist or is currently not
active, the whiteboard services for that ServletContextHelper
are not
active either.
If no ServletContextHelper
service is associated, that is no
"osgi.http.whiteboard.context.select"
service property is configured for a
whiteboard service, a default ServletContextHelper
is used.
Those whiteboard services that are associated with the same
ServletContextHelper
object will share the same
ServletContext
object.
The behavior of the methods on the default ServletContextHelper
is
defined as follows:
getMimeType
- Always returns null
.handleSecurity
- Always returns true
.getResource
- Assumes the named resource is
in the bundle of the whiteboard service, addressed from the root. This method
calls the whiteboard service bundle's Bundle.getEntry
method, and
returns the appropriate URL to access the resource. On a Java runtime
environment that supports permissions, the Http Whiteboard implementation
needs to be granted org.osgi.framework.AdminPermission[*,RESOURCE]
.getResourcePaths
- Assumes that the
resources are in the bundle of the whiteboard service. This method calls
Bundle.findEntries
method, and returns the found entries. On a Java
runtime environment that supports permissions, the Http Whiteboard
implementation needs to be granted
org.osgi.framework.AdminPermission[*,RESOURCE]
.getRealPath
- Always returns null
.Modifier and Type | Field and Description |
---|---|
static String |
AUTHENTICATION_TYPE
HttpServletRequest attribute specifying the scheme used in
authentication. |
static String |
AUTHORIZATION
HttpServletRequest attribute specifying the Authorization
object obtained from the org.osgi.service.useradmin.UserAdmin
service. |
static String |
REMOTE_USER
HttpServletRequest attribute specifying the name of the
authenticated user. |
Constructor and Description |
---|
ServletContextHelper()
Construct a new context helper.
|
ServletContextHelper(Bundle bundle)
Construct a new context helper associated with the specified bundle.
|
Modifier and Type | Method and Description |
---|---|
void |
finishSecurity(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Finishes the security context for the specified request.
|
String |
getMimeType(String name)
Maps a name to a MIME type.
|
String |
getRealPath(String path)
Gets the real path corresponding to the given virtual path.
|
URL |
getResource(String name)
Maps a resource name to a URL.
|
Set<String> |
getResourcePaths(String path)
Returns a directory-like listing of all the paths to resources within the
web application whose longest sub-path matches the supplied path
argument.
|
boolean |
handleSecurity(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Handles security for the specified request.
|
public static final String REMOTE_USER
HttpServletRequest
attribute specifying the name of the
authenticated user. The value of the attribute can be retrieved by
HttpServletRequest.getRemoteUser
.public static final String AUTHENTICATION_TYPE
HttpServletRequest
attribute specifying the scheme used in
authentication. The value of the attribute can be retrieved by
HttpServletRequest.getAuthType
.public static final String AUTHORIZATION
HttpServletRequest
attribute specifying the Authorization
object obtained from the org.osgi.service.useradmin.UserAdmin
service. The value of the attribute can be retrieved by
HttpServletRequest.getAttribute(ServletContextHelper.AUTHORIZATION)
.public ServletContextHelper()
If needed, the subclass will have to handle the association with a specific bundle.
public ServletContextHelper(Bundle bundle)
bundle
- The bundle to be associated with this context helper.public boolean handleSecurity(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws IOException
The Http Whiteboard implementation calls this method prior to servicing the specified request. This method controls whether the request is processed in the normal manner or an error is returned.
If the request requires authentication and the Authorization
header in the request is missing or not acceptable, then this method
should set the WWW-Authenticate
header in the response object,
set the status in the response object to Unauthorized(401) and return
false
. See also RFC
2617: HTTP Authentication: Basic and Digest Access Authentication.
If the request requires a secure connection and the getScheme
method in the request does not return 'https' or some other acceptable
secure protocol, then this method should set the status in the response
object to Forbidden(403) and return false
.
When this method returns false
, the Http Whiteboard
implementation will send the response back to the client, thereby
completing the request. When this method returns true
, the Http
Whiteboard implementation will proceed with servicing the request.
If the specified request has been authenticated, this method must set the
AUTHENTICATION_TYPE
request attribute to the type of
authentication used, and the REMOTE_USER
request attribute to
the remote user (request attributes are set using the
setAttribute
method on the request). If this method does not
perform any authentication, it must not set these attributes.
If the authenticated user is also authorized to access certain resources,
this method must set the AUTHORIZATION
request attribute to the
Authorization
object obtained from the
org.osgi.service.useradmin.UserAdmin
service.
The servlet responsible for servicing the specified request determines
the authentication type and remote user by calling the
getAuthType
and getRemoteUser
methods, respectively, on
the request.
If there is the need to clean up resources at the end of the request, the
method finishSecurity(HttpServletRequest, HttpServletResponse)
can be implemented. That method is only called if this method returns true
.
request
- The HTTP request.response
- The HTTP response.true
if the request should be serviced, false
if
the request should not be serviced and Http Whiteboard
implementation will send the response back to the client.IOException
- May be thrown by this method. If this occurs,
the Http Whiteboard implementation will terminate the request
and close the socket.finishSecurity(HttpServletRequest, HttpServletResponse)
public void finishSecurity(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Implementations of this service can implement this method to clean up
resources which have been setup in
handleSecurity(HttpServletRequest, HttpServletResponse)
.
This method is only called if
handleSecurity(HttpServletRequest, HttpServletResponse)
returned
true
for the specified request. This method is called once the
pipeline finishes processing or if an exception is thrown from within the
pipeline execution.
The default implementation of this method does nothing.
request
- The HTTP request.response
- The HTTP response.handleSecurity(HttpServletRequest, HttpServletResponse)
public URL getResource(String name)
Called by the Http Whiteboard implementation to map the specified
resource name to a URL. For servlets, the Http Whiteboard implementation
will call this method to support the ServletContext
methods
getResource
and getResourceAsStream
. For resources, the
Http Whiteboard implementation will call this method to locate the named
resource.
The context can control from where resources come. For example, the
resource can be mapped to a file in the bundle's persistent storage area
via BundleContext.getDataFile(name).toURI().toURL()
or to a
resource in the context's bundle via getClass().getResource(name)
name
- The name of the requested resource.null
if the resource does not exist.public String getMimeType(String name)
Called by the Http Whiteboard implementation to determine the MIME type
for the specified name. For whiteboard services, the Http Whiteboard
implementation will call this method to support the
ServletContext
method getMimeType
. For resource servlets,
the Http Whiteboard implementation will call this method to determine the
MIME type for the Content-Type
header in the response.
name
- The name for which to determine the MIME type.null
to indicate that the Http Whiteboard implementation
should determine the MIME type itself.public Set<String> getResourcePaths(String path)
Called by the Http Whiteboard implementation to support the
ServletContext
method getResourcePaths
for whiteboard
services.
path
- The partial path used to match the resources, which must
start with a /.null
if there
are no resources in the web application whose path begins with
the supplied path.public String getRealPath(String path)
Called by the Http Whiteboard implementation to support the
ServletContext
method getRealPath
for whiteboard
services.
path
- The virtual path to be translated to a real path.null
if the translation cannot be
performed.Copyright © Contributors to the Eclipse Foundation Licensed under the Eclipse Foundation Specification License – v1.0