HttpService
Date: 2016-06-25

org.osgi.service.http

## Interface HttpService

-     public interface HttpService

  The Http Service allows other bundles in the OSGi environment to dynamically register resources and servlets into the URI namespace of Http Service. A bundle may later unregister its resources or servlets.
  See Also:
    `HttpContext`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `HttpContext` | `createDefaultHttpContext()` Creates a default `HttpContext` for registering servlets or resources with the HttpService, a new `HttpContext` object is created each time this method is called.
    `void` | `registerResources(java.lang.String alias, java.lang.String name, HttpContext context)` Registers resources into the URI namespace.
    `void` | `registerServlet(java.lang.String alias, javax.servlet.Servlet servlet, java.util.Dictionary initparams, HttpContext context)` Registers a servlet into the URI namespace.
    `void` | `unregister(java.lang.String alias)` Unregisters a previous registration done by `registerServlet` or `registerResources` methods.

- - ### Method Detail

    - #### registerServlet

          void registerServlet(java.lang.String alias,
                             javax.servlet.Servlet servlet,
                             java.util.Dictionary initparams,
                             HttpContext context)
                               throws javax.servlet.ServletException,
                                      NamespaceException

      Registers a servlet into the URI namespace.

      The alias is the name in the URI namespace of the Http Service at which the registration will be mapped.

      An alias must begin with slash ('/') and must not end with slash ('/'), with the exception that an alias of the form "/" is used to denote the root alias. See the specification text for details on how HTTP requests are mapped to servlet and resource registrations.

      The Http Service will call the servlet's `init` method before returning.

           httpService.registerServlet("/myservlet", servlet, initparams, context);

      Servlets registered with the same `HttpContext` object will share the same `ServletContext`. The Http Service will call the `context` argument to support the `ServletContext` methods `getResource`,`getResourceAsStream` and `getMimeType`, and to handle security for requests. If the `context` argument is `null`, a default `HttpContext` object is used (see `createDefaultHttpContext()`).

      Parameters:
        `alias` - name in the URI namespace at which the servlet is registered
        `servlet` - the servlet object to register
        `initparams` - initialization arguments for the servlet or `null` if there are none. This argument is used by the servlet's `ServletConfig` object.
        `context` - the `HttpContext` object for the registered servlet, or `null` if a default `HttpContext` is to be created and used.
      Throws:
        `NamespaceException` - if the registration fails because the alias is already in use.
        `javax.servlet.ServletException` - if the servlet's `init` method throws an exception, or the given servlet object has already been registered at a different alias.
        `java.lang.IllegalArgumentException` - if any of the arguments are invalid

    - #### registerResources

          void registerResources(java.lang.String alias,
                               java.lang.String name,
                               HttpContext context)
                                 throws NamespaceException

      Registers resources into the URI namespace.

      The alias is the name in the URI namespace of the Http Service at which the registration will be mapped. An alias must begin with slash ('/') and must not end with slash ('/'), with the exception that an alias of the form "/" is used to denote the root alias. The name parameter must also not end with slash ('/') with the exception that a name of the form "/" is used to denote the root of the bundle. See the specification text for details on how HTTP requests are mapped to servlet and resource registrations.

      For example, suppose the resource name /tmp is registered to the alias /files. A request for /files/foo.txt will map to the resource name /tmp/foo.txt.

           httpservice.registerResources("/files", "/tmp", context);

      The Http Service will call the `HttpContext` argument to map resource names to URLs and MIME types and to handle security for requests. If the `HttpContext` argument is `null`, a default `HttpContext` is used (see `createDefaultHttpContext()`).
      Parameters:
        `alias` - name in the URI namespace at which the resources are registered
        `name` - the base name of the resources that will be registered
        `context` - the `HttpContext` object for the registered resources, or `null` if a default `HttpContext` is to be created and used.
      Throws:
        `NamespaceException` - if the registration fails because the alias is already in use.
        `java.lang.IllegalArgumentException` - if any of the parameters are invalid

    - #### unregister

          void unregister(java.lang.String alias)

      Unregisters a previous registration done by `registerServlet` or `registerResources` methods.

      After this call, the registered alias in the URI name-space will no longer be available. If the registration was for a servlet, the Http Service must call the `destroy` method of the servlet before returning.

      If the bundle which performed the registration is stopped or otherwise "unget"s the Http Service without calling `unregister(String)` then Http Service must automatically unregister the registration. However, if the registration was for a servlet, the `destroy` method of the servlet will not be called in this case since the bundle may be stopped. `unregister(String)` must be explicitly called to cause the `destroy` method of the servlet to be called. This can be done in the `BundleActivator.stop` method of the bundle registering the servlet.

      Parameters:
        `alias` - name in the URI name-space of the registration to unregister
      Throws:
        `java.lang.IllegalArgumentException` - if there is no registration for the alias or the calling bundle was not the bundle which registered the alias.

    - #### createDefaultHttpContext

          HttpContext createDefaultHttpContext()

      Creates a default `HttpContext` for registering servlets or resources with the HttpService, a new `HttpContext` object is created each time this method is called.

      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 context bundle; this method calls the context 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]`.
      Returns:
        a default `HttpContext` object.
      Since:
        1.1