HTTP Bundle

The HTTP Bundle hosts an integrated Web server that allows access to server and bundle resources over HTTP 1.1 (HyperText Transfer Protocol). The HTTP Service of the HTTP Bundle complies completely with the OSGi HTTP Service Specification 1.2. Furthermore, the HTTP Bundle has services for direct resource requests and for monitoring valid aliases.

Contents:

• Bundle Information
  • Bundle JAR
  • Import
  • Export
• Main Features
  • Plain Connection
  • Persistent Connection
  • Servlet Support
  • HTTP Aliases
  • HTTP Access Authentication
  • Root Directory
  • GZIP Compression
• Services
  • HTTP Service
    • Service Property
    • Using Aliases
    • Registering Resources
    • Registering Servlets
    • Specifying Character Encoding of Posted Data
    • Notes
    • HTTP Context
  • HTTP Helper Service
  • Pluggable Commands
  • Managed Service
• Console Commands
• Configuration
  • Configuration Resources
    • HTTP Common Configuration
    • HTTP Plain Server Configuration
  • Visual Administration
    • HTTP Plain Server Configuration
    • HTTP Aliases
    • HTTP Common Configuration
  • System Properties
• Troubleshooting
• Demo
• References

Bundle Information

Bundle JAR

The JAR file of the HTTP Bundle is http.jar, and is found in the bundles folder.

There are two other JAR files related to this bundle - httpapi.jar and servlet.jar. The first one only exports the OSGi HTTP service APIs. The servlet.jar exports Java Servlet APIs version 2.2.

The HTTP Bundle supports only plain connections. For secure connections a Secure HTTP Bundle exists whose JAR is https.jar.

Import

The HTTP Bundle imports the following packages, all of which are from the Framework Package:

Export

The HTTP Bundle exports com.prosyst.mbs.services.http package. It holds additional elements for faster and lighter HTTP communication.

Main Features

The HTTP Service is essential for the proper functioning of the ProSyst mBedded Server - it realizes the server functionality of the Hypertext Transfer Protocol (HTTP) specified in RFC 2616 and is the basic platform for accessing remotely the OSGi framework over the Internet.

Plain Connection

The HTTP protocol is the base mechanism for data transmission over the World Wide Web. Its scope of influence includes distributed and collaborative information systems with hypermedia support. Since computing systems have increased their complexity, HTTP is designed to provide a full use of the resources found on the Web.

Briefly, a request encloses specifying an operation on a resource (an HTML page, an image, etc.) located on a remote origin server. Conventional HTTP client applications are the Web browsers.

The major unit in the HTTP is the Uniform Resource Identifier (URI). It is also referred to as a Uniform Resource Locator (URL) or as an Uniform Resource Name (URN). The URI indicates the network resource to which to apply a method. Messages are delivered in a format defined by the Multipurpose Internet Mail Extensions (MIME). MIME types and formats are described in RFC 2387.

The HTTP Bundle holds an HTTP server that delivers resources to its clients by using TCP/IP sockets. The HTTP Bundle supports the HEAD, GET, and POST methods of HTTP 1.1, using primary port # 80, which is conventional, and secondary port # 8080 to listen for client requests. It processes the requests and sends adequate responses to the clients.

Persistent Connection

Opening and closing TCP sockets consumes a considerable amount of CPU time, bandwidth and memory. Both version of HTTP - 1.0 and 1.1 offer mechanisms to reuse TCP/IP connections.

HTTP 1.0 has defined a value for the Connection header, Keep-Alive, which is sent whenever the client or the server wishes to keep the connection alive. This header is usable only if the Content-Length of the body can be sent, otherwise the connection must be closed in order to mark the end of the response body.

HTTP 1.1 introduces the Transfer-Encoding: chunked header, which provides a mechanism to make a connection persistent, while transferring dynamic data.

When an HTTP 1.0 request comes, HTTP Bundle tries to implement the keep-alive mechanism, but if a servlet generates the response body, then the connection can be kept only if the servlet has set the Content-Length header.

Responses to HTTP 1.1 requests generally contain the Transfer-Encoding: chunked, this header is not sent only if the servlet defines the content length.

Servlet Support

Servlets are Java objects that run on an HTTP server and change dynamically the HTTP content in response to client requests. Servlets must be written according to the Java Servlet API from Sun Microsystems. The Servlet Engine of the HTTP Bundle supports the 2.2 version of the API. The OSGi Library Bundle contains the Java Servlet API classes.

HTTP Aliases

HTTP components are accessed through aliases that map client requests to specified resources or servlets. An alias is a pseudonym under which the corresponding servlet or resource can be found. For example a client can invoke an alias in the following way:

http://<mbs_host>[:<http_port>]/<alias_name>.

<mbs_host>stands for the IP address or DNS name of the device running mBS and the HTTP Bundle, <http_port> is the port on which the HTTP server is listening for requests (if the server port is 80, the port number can be omitted from the URL), and <alias_name> is the alias assigned to a resource or a servlet.

The HTTP Bundle offers an extra feature for aliases - alternative aliases. It allows to easily map a "fake" alias to another alias which on its behalf is associated with a servlet or a resource.

HTTP Access Authentication

There are cases which require authentication of the client requests for resources on the origin server. To challenge authentication and authorization of an HTTP client, the server sends an "unauthorized message" containing the WWW-Authenticate header field. This field carries the authentication scheme, the case-sensitive realm defining the protection space to perform authentication for, and a list of comma-separated attribute/value pairs. In result, the user agent returns an Authorization header holding credentials for the realm of the requested resource.

There are two types of authentication schemes - Basic and Digest.

In the Basic scheme, the client should identify itself through Base64 encoded user name and password for each realm. The server serves the request only if it finds the name and password in the protection space of the resource. Note that the user name may be case-sensitive depending on the authentication support of the HTTP server. A flaw of the Basic scheme is that the user name and password are transmitted over the network without encryption.

The Digest authentication scheme eliminates the Basic scheme incompleteness discussed above. The client response contains a checksum made of the user name, the password, a unique data string specified by the server, the HTTP method and the requested URI. The default algorithm used for the checksum is MD5, but the server may specify another one in the WWW-Authenticate header.

The Basic and the Digest access authentication mechanisms are specified in RFC 2617.

Root Directory

The HTTP Bundle supports a "root directory" - a directory whose content becomes automatically accessible to Web browsers without the need to register the directories and separate files as aliases.

The root directory should be associated with a location on the local file system as well as with a special alias, both configurable through the OSGi Configuration Admin service (see the "Configuration" section).

If a file's location is

<Root Directory>/mypages/mypage.html

Web browsers will open it by using URL

http://<mbs_host>:<http_port>/<root_dir_alias>/mypages/mypage.html

An additional feature of the HTTP Bundle, related to the root directory, is that if the root directory contains a Web pages called index.html, the server will automatically return the page to the Web browser when there is a request to the root directory alias ending with a trailing "/".

GZIP Compression

GZIP compression allows sending compressed text and application files to clients if requested.

In general, the exchange of compressed files proceedes like this:

1. The client sends the server a request for a resource, indicating with the Accept-Encoding:gzip, deflate request header that the response should be compressed.
2. The server reads the header, and if compression is on for the MIME type of the requested resource (see "Configuration"), returns GZIP compressed resource along with the Content-Encoding: gzip response header.
3. The client accepts the resource and uncompresses it.

Services

The HTTP Bundle registers the HTTP Service, the HTTP Helper service, three configuration Managed Services and a Pluggable Commands service.

HTTP Service

The HTTP Service in the HTTP Bundle is developed to comply with the OSGi HTTP Service Specification. The service declares the  org.osgi.service.http.HttpService OSGi interface. Installed bundles can register resources and servlets with the HTTP Service so that clients can access them over HTTP.

Service Property

The HTTP Service has the openPort registration property whose Integer value indicates the port currently opened for HTTP plain connection. The service tries to open port 80 and if it is already taken, the service is registered with port 8080 as value for this property. If you change the configuration property that corresponds to this one (for example by using the mConsole), the service property is also updated.

Tip: To be notified about changes in this property's value, you may register a service listener in the framework for ServiceEvent.MODIFIED events and get the new value.

Using Aliases

The HTTP Service introduces the following alias format: the alias name begins with a "/" and must not end with a "/". The HTTP Service is case sensitive towards aliases. Registration of "/" alias stands for the URI of the start page of the ProSyst mBS.

For more details about alias mapping, refer to the HTTP Service Specification.

Registering Resources

The resources (files and directories) that correspond to aliases must not end with a "/". You register HTTP resources by using the following syntax:

/<resource_path>

where <resource_path> is the path of the resource in the bundle JAR file. The "/" before the resource path is optional, and it means that the resource path begins from the main directory in the bundle JAR file.

package demo.bundle;

import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.service.http.HttpService;

                        . . .

  BundleContext bc = null;
  ServiceReference httpRef = null;
  HttpService httpServ = null;

                        . . .

    // Obtaining the HTTP Service from the server framework
    httpRef = bc.getServiceReference("org.osgi.service.http.HttpService");
    httpServ = (HttpService)bc.getService(httpRef);

    // Registering resources using different resource paths
    httpServ.registerResources("/aliasOne", "/resources/resource.html",httpContext);
    httpServ.registerResources("/aliasTwo","resources/resource.html",httpContext);

                        . . .

Considering the first registration of resources in the code example above, the resource file is found in:

<Bundle JAR File>/
	demo/bundle
	resources/resource.html

If there is no slash, the resource is situated in the folder of the current class file. The second registration implies that the resources is in:

<Bundle JAR File>/demo/bundle/resources/resource.html

When the HTTP server constructs its response to a resource request, it should fill in the Content-Type header. The content type of a resource can be set in the implementation of HttpContext.getMimeType method.

You can add a resource extension in the mbs.http.pid OSGi-compliant configuration dictionary. See the "Configuration" section for more details.

Registering Servlets

You should register a servlet as the OSGi HTTP Service Specification describes. The code example below uses the components, created in Listing 1.1, and registers a servlet (MyServlet) with the HTTP Service.

import javax.servlet.http.HttpServlet;

  // Obtaining the HTTP Service from the OSGi framework

                          . . .

  // Registering a servlet
  MyServlet servlet = new MyServlet();
  httpServ.registerServlet("/myServlet", servlet, httpContext);

                          . . .

By default, a newly-created HTTP session, represented by a javax.servlet.http.HttpSession object, has initial timeout (i.e. inactive interval) of 1800 seconds.

HTTP Context

The methods for registration of both resources and servlets require HttpContext objects. They contain data used by the HTTP Service during resource registration. In an HttpContext, a developer specifies the MIME type of the response sent to the HTTP client, maps a resource to an URL and manages security on received client requests. If a client request requires authentication, then security can be established with the HTTP Access Authentication schemes.

The HTTP Service provides a default implementation of HttpContext that can be loaded by passing null for the HttpContext instance when registering a resource or a servlet, or can be instantiated through the createDefaultHttpContext method of the HTTP Service. This default HttpContext handles authentication security using the Basic Access Authentication Scheme.

Specifying Character Encoding of Posted Data

In a servlet you can explicitly specify the character encoding of posted data to the HTTP Bundle through the com.prosyst.request.parameter.charset request attribute. Prior to retrieving the request parameters with getParameter, call the setAttribute method of HttpServletRequest providing the attribute as name and the character encoding string as value.

Notes

Note 1: To compile a servlet, you need the archive with the Java Servlet API classes and a path to it in your classpath. The library JAR lib/frameworklib.jar contains these classes. To run a servlet successfully with the HTTP Service, include the javax.servlet and javax.servlet.http packages in the Import-Package header of the bundle manifest.

Note 2: If you implement the javax.servlet.SingleThreadModel interface, you should supply a default constructor of the implementation class. This is necessary, because when a request to such a servlet comes, the Servlet Engine makes a new instance of the servlet to service the request using this constructor.

Note 3: Bundle developers who register resources and servlets with the HTTP Service should consider that when stopped, the HTTP Bundle unregisters all aliases. Such bundles should subscribe service listeners for starting events for the HTTP Bundle so that they can register their aliases again. If you unregister aliases after the HTTP Bundle has stopped, you should catch the Exception that is thrown in this case. If the HTTP Bundle is updated, all registered aliases are removed. Therefore, if you try to force unregistration of aliases, an IllegalArgumentException is thrown.

Note 4: If you call BundleContext.unget on an HTTP Service reference, the latter unregisters all resources that your bundle registered.

HTTP Helper Service

The HTTP Helper service returns HTTP responses to HTTP requests from bundles on the local device by using no TCP sockets. If requesting bundles are running on the same machine as the HTTP Bundle, they can exchange HTTP messages straight in bytes. You may not use sockets to contact the ProSyst mBS. The HTTP Helper Service publishes the com.prosyst.mbs.services.http.HttpHelper interface.

The code example below requests the resource of the HTTP server start page (if such is present).

import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import com.prosyst.mbs.services.http.HttpHelper;

                      . . . 

  BundleContext bc = null;
  ServiceReference helperRef = null;
  HttpHelper helper = null;

                      . . . 

    // Retrieving the HTTP Helper from the server framework
    helperRef = bc.getServiceReference("com.prosyst.mbs.services.http.HttpHelper");
    helper = (HttpHelper)bc.getService(helperRef);

    // Processing a simple HTTP Request
    String input = "GET / HTTP/1.0\r\n\r\n";
    byte[] outputBytes = helperServ.getOutput(input.getBytes());
    String output = new String(outBytes); 

                      . . . 

You can retrieve the essential attributes of an alias using the HttpHelper interface and the AliasProperties interface. For clarification, consider the following code example:

import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import com.prosyst.mbs.services.http.HttpHelper;
import com.prosyst.mbs.services.http.AliasProperties;

  BundleContext bc = null;
  ServiceReference helperRef = null;
  HttpHelper helper = null;
  String servName = "com.prosyst.mbs.services.http.HttpHelper";

                      . . . 

    // Retrieving the HTTP Helper from the server framework
    helperRef = bc.getServiceReference(servName);
    HttpHelper helper = (HttpHelper) bc.getService(helperRef);
    AliasProperties[] aliases = helper.getAliases();

    // Extracting registered aliases
    for(int i=0; i<aliases.length; i++) {
      String aliasName = aliases[i].getAlias();
    }

                      . . . 

Note: For more technical details about the features of the HTTP Helper Service explore the Framework Package APIs.

Pluggable Commands

The interface com.prosyst.util.pcommands.PluggableCommands is exported by the ProSyst Util Bundle/ProSyst Util Full Bundle for other bundles that want to add commands to the framework console. These bundles register their commands under a command group. The command group of the HTTP Bundle is http. See below the description of the command and its parameters.

Managed Services

The HTTP Bundle registers two org.osgi.cm.ManagedService services. They allow configuring the basic properties of the bundle through the OSGi Configuration Admin service registered by the Config bundle. The Managed Service with PID mbs.http.pid allows tuning parameters that are common to all types of connections. The mbs.http.plain Managed Service delivers settings for plain HTTP connection.

See the "Configuration Resources" section for more information on the content of the mbs.http.pid and mbs.http.plain configuration dictionaries.

Console Commands

The commands are accessed either by entering the group or typing the command preceded by the group name and a dot. Here is an example:

The help command is standard and is added for all pluggable commands groups. It gives a list of available commands for the group it is invoked into. The http group contains only one other command - list, that gives a roll of all registered aliases. To view the help list for the http group from another group, type help http.

Configuration

Configuration Resources

The HTTP bundle registers two ManagedServices with configuration PIDs mbs.http.pid and mbs.http.plain.

HTTP Common Configuration. The configuration properties for the Managed Service with PID mbs.http.pid are:

HTTP Plain Server Configuration. The Managed Service with PID mbs.http.plain has the following cofiguration properties:

Visual Administration

User-friendly visual administration on the HTTP Bundle is performed from the mConsole application.

In the mConsole, a property editor provides a special user interface for modifying configuration dictionaries, compliant with the OSGi Configuration Admin (see "OSGi Framework Administration through mConsole").

Basically, in the mConsole there are three property editors for the HTTP Bundle - two general property editors for the mbs.http.pid and the mbs.http.plain configuration dictionaries, and one listening the currently registered HTTP aliases. For all of them updates are handled dynamically and no restarts of the HTTP Bundle are needed to save the changes.

To activate an HTTP property editor:

1. Start ProSyst mBS if it is on the same machine, or if it is residing in a distant computer, make sure the server is on.
2. Start mConsole and log in the mBS.
3. In the bundle tree, locate the HTTP Bundle node within the osgi category and unfold it.
4. Go to one of the following nodes:
   • HTTP Plain Server Configuration - Stands for the mbs.http.plain configuration dictionary
   • HTTP Aliases - Lists the aliases, registered in the HTTP Service
   • HTTP Common Configuration - Stands for the mbs.http.pid configuration dictionary

HTTP Plain Server Configuration

The HTTP Plain Server Configuration allows configuring the parameters of plain HTTP communication, exported in the mbs.http.plain configuration dictionary. The properties, available in this dictionary, are described in details in the "Configuration Resources" section.

Figure 1: HTTP Service properties for plain connection.

You may use the Edit button to select which optional properties to include/remove for configuration in the property editor.

Figure 2: Selecting attribute to administer.

The Set button saves the changes. The Refresh button updates the displayed information in case another administrator has altered some of the communication parameters. The Cancel button cancels the changes.

HTTP Aliases

The HTTP Aliases editor allows the administrator to see what aliases are currently registered in the HTTP Service namespace. Each alias is characterized by:

• Name at the Alias Name column
• Resource path at Resource Path. If a servlet is registered, this is indicated with the Servlet Registration keyword at Resource Path.
• ID of the bundle that has declared the alias at Bundle ID.

Figure 3: HTTP Service aliases.

Note: You cannot alter registered aliases. You can only see them.

HTTP Common Configuration

The HTTP Common Configuration part contains properties for configuring resource management and an HTTP session's timeout, exported in the mbs.http.pid configuration dictionary. More information on the format and meaning of the mbs.http.pid properties is available in the "Configuration Resources" section.

Figure 4: Common properties of the HTTP Bundle.

This pane shows all file types that will be used if a consuming bundle does not specify any MIME types. You can set the default MIME types of the HTTP Bundle here.

To add a new type to map to MIME format, use the Add button. In result, an empty row in the table with the supported MIME formats is inserted. You should type the extension in it. You should insert another row, in which you enter the description of the file extension. To remove a row, locate it in the table, and click Remove.

The other buttons at HTTP Common Configuration have similar functions to the ones at HTTP Plain Server Configuration.

System Properties

The HTTP Bundle uses the following VM system properties:

Before starting the framework you can tune them in the default.prs file for the current JVM, or straight in the framework starting script file.

At runtime, you can modify this property with the set base command before activating the HTTP Bundle. Otherwise, you should restart it. You can use the mConsole to assign values to the above properties at runtime as well.

Tip: To learn more about using system properties in mBS framework, refer to the "System Properties" document from the "Getting Started" guide.

Troubleshooting

Threads. The HTTP Bundle takes all threads for managing client requests from the Thread Pool Manager service. Each client request is processed in a separate thread except in cases of persistent connections. If the HTTP Service has already occupied a number of threads, which are waiting for the Request Timeout expiration, client disconnection or activity, it may hang down. This may happen because the default maximum capacity of the Thread Pool Manager service is 30 threads which may term insufficient. Such situations may occur if clients have too long timeouts for persistent connections. One of the following approaches (or a combination of them) may solve this problem:

1. Decreasing the HTTP Service request timeout so that inactive clients will be disconnected soon.
2. Increasing the thread capacity of the Thread Pool Manager service. If you own scanty resources, this approach is not advisory.
3. Setting the Persistent Connection flag to false.

Ports. In a Linux environment, the ports with numbers under 1024 are system ports reserved for system services. Only a root user has the rights to use these ports. This is why, if you are not a root user, you will have either to set a port over 1024 as a primary port or use the secondary port for HTTP connection.

IE browser on iPAQ H3630 and PocketPC. If you are using the embedded IE browser on iPAQ H3630 and PocketPC, better regulate data stream by changing the values of mbs.http.buffersize (1024 by default) and mbs.http.flushtimeout (false by default) system properties to 512 and true, respectively.

Encoding. Different virtual machines prefer different IDs for character encoding. If the HTTP Server cannot generate correct responses and reports an error, that the current VM does not support the encoding defined by the mbs.http.encoding property, then the value of mbs.http.encoding should be changed. Contact the documentation of the virtual machine to get the identifier of the ISO 8859_1 character encoding. It may be ISO8859_1, 8859_1, 8859-1, etc. Another way to get the ID is to inspect the archive of the virtual machine's base class library, whenever it is available, for sun.io.ByteToChar<ID>.class.

Demo

mBS offers the HTTP Demo for illustration of the HTTP Bundle's usage.

References

• RFC 1945: Hypertext Transfer Protocol - HTTP 1.0.
• RFC 2109: HTTP State Management Mechanism.
• RFC 2616: Hypertext Transfer Protocol - HTTP 1.1.
• RFC 2617: HTTP Authentication: Basic and Digest Access Authentication.
• RFC 2965: HTTP State Management Mechanism.
• SSL v3 Specification.
• OSGi Service Compendium containing the OSGi HTTP Service Specification.
• OSGi Framework Specification API.
• OSGi HTTP Service Specification API.
• Framework Professional Edition Package APIs.
• HTTP Helper Service API.
• Java Servlet Specification 2.2.
• Java Servlet API.

OSGi Bundles