Package org.osgi.service.http

Interface HttpContext

  • public interface HttpContext
    Context for HTTP Requests.

    This service defines methods that the Http Service may call to get information for a request.

    Servlets may be associated with an HttpContext service. Servlets that are associated using the same HttpContext object will share the same ServletContext object.

    If no HttpContext service is associated, a default HttpContext is used. The behavior of the methods on the default HttpContext is defined as follows:

    • getMimeType - Does not define any customized MIME types for the Content-Type header in the response, and always returns null.
    • handleSecurity - Performs implementation-defined authentication on the request.
    • getResource - Assumes the named resource is in the bundle of the servlet service. This method calls the servlet bundle's Bundle.getResource method, and returns the appropriate URL to access the resource. On a Java runtime environment that supports permissions, the Http Service needs to be granted org.osgi.framework.AdminPermission[*,RESOURCE].

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String AUTHENTICATION_TYPE
      HttpServletRequest attribute specifying the scheme used in authentication.
      static java.lang.String AUTHORIZATION
      HttpServletRequest attribute specifying the Authorization object obtained from the org.osgi.service.useradmin.UserAdmin service.
      static java.lang.String REMOTE_USER
      HttpServletRequest attribute specifying the name of the authenticated user.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.String getMimeType​(java.lang.String name)
      Maps a name to a MIME type.
      java.net.URL getResource​(java.lang.String name)
      Maps a resource name to a URL.
      boolean handleSecurity​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
      Handles security for the specified request.

    • Field Detail

      • REMOTE_USER

        static final java.lang.String REMOTE_USER
        HttpServletRequest attribute specifying the name of the authenticated user. The value of the attribute can be retrieved by HttpServletRequest.getRemoteUser. This attribute name is org.osgi.service.http.authentication.remote.user.
        Since:
        1.1
        See Also:
        Constant Field Values

      • AUTHENTICATION_TYPE

        static final java.lang.String AUTHENTICATION_TYPE
        HttpServletRequest attribute specifying the scheme used in authentication. The value of the attribute can be retrieved by HttpServletRequest.getAuthType. This attribute name is org.osgi.service.http.authentication.type.
        Since:
        1.1
        See Also:
        Constant Field Values

      • AUTHORIZATION

        static final java.lang.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(HttpContext.AUTHORIZATION). This attribute name is org.osgi.service.useradmin.authorization.
        Since:
        1.1
        See Also:
        Constant Field Values

    • Method Detail

      • handleSecurity

        boolean handleSecurity​(javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response)
                throws java.io.IOException
        Handles security for the specified request.

        The Http Service 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 (available at http://www.ietf.org/rfc/rfc2617.txt).

        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 Service will send the response back to the client, thereby completing the request. When this method returns true, the Http Service 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.

        Parameters:
        request - The HTTP request.
        response - The HTTP response.
        Returns:
        true if the request should be serviced, false if the request should not be serviced and Http Service will send the response back to the client.
        Throws:
        java.io.IOException - may be thrown by this method. If this occurs, the Http Service will terminate the request and close the socket.

      • getResource

        java.net.URL getResource​(java.lang.String name)
        Maps a resource name to a URL.

        Called by the Http Service to map a resource name to a URL. For servlet registrations, Http Service will call this method to support the ServletContext methods getResource and getResourceAsStream. For resource registrations, Http Service 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).toURL() or to a resource in the context's bundle via getClass().getResource(name)

        Parameters:
        name - the name of the requested resource
        Returns:
        URL that Http Service can use to read the resource or null if the resource does not exist.

      • getMimeType

        java.lang.String getMimeType​(java.lang.String name)
        Maps a name to a MIME type.

        Called by the Http Service to determine the MIME type for the specified name. For servlets, the Http Service will call this method to support the ServletContext method getMimeType. For resources, the Http Service will call this method to determine the MIME type for the Content-Type header in the response.

        Parameters:
        name - The name for which to determine the MIME type.
        Returns:
        The MIME type (e.g. text/html) of the specified name or null to indicate that the Http Service should determine the MIME type itself.