HttpService

Syntax

public interface HttpService

Description

HttpService allows other bundles in the OSGi Framework to dynamically register resources and servlets into the HttpService's URI namespace. A Bundle may later unregister its resources or servlets.

Methods

registerResources(String, String, HttpContext)

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

Register resources into the URI namespace. The alias is the name in the URI namespace of HttpService at which the registration will be mapped. An alias must begin with slash ('/') and must not end with slash ('/'). The name parameter must also not end with slash ('/'). See also Mapping HTTP Requests 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);

HttpService will call the HttpContext parameter to map resource names to URLs and MIME types and to handle security for requests.

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

Throws:

NamespaceException— if the registration fails because the alias is already in use.

java.lang.IllegalArgumentException— if any of the parameters are invalid

registerServlet(String, Servlet, Dictionary, HttpContext)

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

Register a servlet into the URI namespace. The alias is the name in the URI namespace of HttpService at which the registration will be mapped. An alias must begin with slash ('/') and must not end with slash ('/'). See also Mapping HTTP Requests to Servlet and Resource Registrations. HttpService will call the init method of the servlet before returning.

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

Servlets which are registered with the same HttpContext object will share the same ServletContext. HttpService will call the HttpContext parameter to support the ServletContext methods getResource, getResourceAsStream and getMimeType and to handle security for requests.

Parameters:

alias— name in the URI namespace at which the servlet is registered

servlet— the servlet object to register

initparams— initialization parameters for the servlet or null if there are none. This parameter is used by the servlet's ServletConfig object.

context— the HttpContext object for the registered servlet

Throws:

NamespaceException— if the register fails because the alias is already in use.

javax.servlet.ServletException— if the servlet's init method throws an exception

java.lang.IllegalArgumentException— if any of the parameters are invalid

unregister(String)

public void unregister(java.lang.String alias)
            throws java.lang.IllegalArgumentException

Unregisters a previous registration done by registerServlet or registerResources. After this call, the registered alias in the URI namespace will no longer be available. If the registration was for a servlet, HttpService will call the destroy method of the servlet before returning.

If the bundle which performed the registration is stopped or otherwise “unget”s HttpService without calling unregister(String), then HttpService will 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 namespace 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.