Package org.osgi.service.http

Description

The OSGi HttpService Specification.

HttpService allows other bundles in the OSGi Framework to register resources and servlets to be accessed via Hypertext Transfer Protocol (HTTP). HttpService may implement either HTTP/1.0 (http://www.ietf.org/rfc/rfc1945.txt) or HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt).

Two entity types can be registered with HttpService: servlets and resources. A servlet is an object which implements the Java Servlet API (http://java.sun.com/products/servlet/). Registering a servlet gives that servlet control over some part of the URI namespace. Registering resources allows HTML files, GIF files, class files, etc. to be made visible in the URI namespace by the requesting bundle.

Registering Servlets

Servlets which are registered using the same HttpContext object will share the same ServletContext. This is, HttpService provides a one-to-one mapping between ServletContexts and HttpContexts. Servlets can be registered using the registerServlet method.

For example:

HttpContext context = new HttpContext() {
   public boolean handleSecurity(
       HttpServletRequest request,
       HttpServletResponse response) throws IOException {
       return(true);
   }
   public URL getResource(String name) {
       return(getClass().getResource(name));
   }
   public String getMimeType(String name) {
       return(null);
   }
};
Hashtable initparams = new Hashtable();
initparams.put("some-key-name", "some-value-string");
Servlet myServlet = new MyServlet();
httpService.registerServlet("/servletAlias",
                            myServlet,
                            initparams,
                            context);
/* myServlet has been registered and its init method
   has been called */
...
httpService.unregister("/servletAlias");
/* myServlet has been unregistered and its destroy method
   has been called */

This would register the servlet “myServlet” at alias “/servletAlias.” A request for http://myserver:port/servletAlias would map to the servlet myServlet and its service method will be called to process the request.

The context object in this example provides simple implementations of the HttpContext methods.

Registering Resources

Resources can be registered using the registerResources method.

For example:

HttpContext context = new HttpContext() {
    public boolean handleSecurity(
        HttpServletRequest request,
        HttpServletResponse response) throws IOException {
        return(true);
    }
    public URL getResource(String name) {
        return(getClass().getResource(name));
    }
    public String getMimeType(String name) {
        return(null);
    }
};
httpService.registerResources("/files",
                              "/bundlefiles",
                              context);
...
httpService.unregister("/files");

The example registers the resource name “/bundlefiles” to the alias “/files.” A request for http://myserver:port/files/myfile.htm would map to the name “/bundlefiles/myfile.htm.” The context object will be called at the getResource method to maps the resource name “/bundlefiles/myfile.htm” to a URL. HttpService will then use the URL to read the read the resource and respond to the request.

The context object in this example provides simple implementations of the HttpContext methods. The implementation of getResource uses the bundle's class loader to return an URL for the resource. More sophisticated implementations could filter the input name restricting the resources that may be returned or map the input name onto the file system.

Mapping HTTP Requests to Servlet and Resource Registrations

HttpService's URI namespace may be “shared.” For example, caller A registers alias “/a” and caller B registers alias “/a/b.” A request URI of “/a/b” or request URIs that start with “/a/b/” will be mapped to B's registration. Other request URIs that start with “/a” will not be mapped to B's registration and may be mapped to A's registration. This implies that one registration can “hide” part of another registration. Registrations for identical aliases are not allowed. If caller A registers “/myAlias” and then caller B tries to register “/myAlias,” caller B will receive a NamespaceException and its resource or servlet will not be registered. However, caller B can register “/myAlias/more” (if no other registration for this alias exists).

When an HTTP request comes in from a client, HttpService checks to see if the request URI matches any registered aliases. If it does, then we have a matching registration. If the registration corresponds to a servlet, then the servlet will be called at its service method to complete the HTTP request. If the registration corresponds to a resource, then a target resource name is constructed by substituting the alias name from the registration with the resource name from the registration. For example:

registrationName+requestURI.substring(registrationAlias.length())

The target resource name will be passed to the getResource method of the registration's HttpContext object. If the returned URL object is not null, then HttpService will return the contents of the URL to the client completing the HTTP request. If the returned URL object is null, then we continue as if there was no match.

If there is not a match, HttpService will attempt to match substrings of the requestURI to registered aliases. The substrings of the request URI are selected as follows: Remove the last '/' and everything to the right of it. HttpService will repeat this process until either a match is found or the substring is an empty string. If this happens, HttpService will return error Not Found(404) to the client.

For example, an HTTP request comes in with a request URI of “/a/b/foo.txt” and the only registered alias is “/a.” The search for “/a/b/foo.txt” will not match an alias, therefore HttpService with search for aliases “/a/b” and then “/a.” The search for alias “/a” will result in a match and its registration will be used.