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

"Consumers of this API must not implement this interface"

Method Summary

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(String alias, String name, HttpContext context) Registers resources into the URI namespace.
void	registerServlet(String alias, javax.servlet.Servlet servlet, Dictionary<?,?> initparams, HttpContext context) Registers a servlet into the URI namespace.
void	unregister(String alias) Unregisters a previous registration done by registerServlet or registerResources methods.

Method Detail

registerServlet

void registerServlet(String alias,
                     javax.servlet.Servlet servlet,
                     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.

IllegalArgumentException - if any of the arguments are invalid

registerResources

void registerResources(String alias,
                       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.

IllegalArgumentException - if any of the parameters are invalid

unregister

void unregister(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:

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