svn commit: r1575955 - /felix/site/trunk/content/documentation/subprojects/apache-felix-http-service.mdtext

[ja...@apache.org]

Author: jawi
Date: Mon Mar 10 14:43:00 2014
New Revision: 1575955

URL: http://svn.apache.org/r1575955
Log:
Added section on usage of all-in-one bundle and updated the accepted configuration properties.

Modified:
    felix/site/trunk/content/documentation/subprojects/apache-felix-http-service.mdtext

Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-http-service.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-http-service.mdtext?rev=1575955&r1=1575954&r2=1575955&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-http-service.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-http-service.mdtext Mon Mar 10 14:43:00 2014
@@ -17,10 +17,13 @@ The Apache Felix HTTP Service project in
   * `org.apache.felix.http.jetty` - HTTP Service implementation that is embedding Jetty server;
   * `org.apache.felix.http.whiteboard` - Whiteboard implementation that uses any HTTP Service implementation;
   * `org.apache.felix.http.bridge` - HTTP Service implementation that uses the host application server (bridged mode). Must be used with proxy;
+  * `org.apache.felix.http.cometd` - Adds Comet/Ajax Push functionality to the HTTP Service implementation;
   * `org.apache.felix.http.bundle` - All in one bundle that includes all of the above;
   * `org.apache.felix.http.proxy` - Proxy that is needed inside WAR when deployed inside an application server. 
 
-So, in most cases you could just use **org.apache.felix.http.bundle** and forget about all the other ones.
+So, in most cases you could just use **org.apache.felix.http.bundle** and forget about all the other ones. 
+Note that by default, this bundle operates in "bridged mode" and needs explicit configuration to enable or operate
+in other modes. See [this section](#using-the-all-in-one-bundle) for more information.
 
 ## Using the HttpService
 
@@ -281,43 +284,63 @@ applicaiton server. A little setup is ne
 
 A detailed example can be found [here](http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge).
 
+## Using the all-in-one bundle
+
+The all-in-one bundle combines the the Jetty server, the whiteboard implementation, the servlet bridge and the
+CometD functionality in a single, easy to use bundle. By default its functionality is equivalent to the Servlet Bridge,
+meaning that the Jetty, Whiteboard and CometD features are *disabled*. To *enable* these features, you need to supply
+one or more configuration properties as described in the [next section](#configuration-properties).
+
 ## Configuration Properties
 
 The service can both be configured using OSGi environment properties and using Configuration Admin. The service PID for this service is `"org.apache.felix.http"`. If you use both methods, Configuration Admin takes precedence. The following properties can be used (some legacy property names still exist but are not documented here on purpose):
 
-* `org.osgi.service.http.port` - The port used for servlets and resources available via HTTP. The default is `80`. A negative port number has the same effect as setting `org.apache.felix.http.enable` to `false`.
-* `org.osgi.service.http.port.secure` - The port used for servlets and resources available via HTTPS. The default is `443`. A negative port number has the same effect as setting `org.apache.felix.https.enable` to `false`.
-* `org.apache.felix.http.nio` - Flag to enable the use of NIO instead of traditional IO for HTTP. One consequence of using NIO with HTTP is that the bundle needs at least a Java 5 runtime. The default is `true`.
-* `org.apache.felix.https.nio` - Flag to enable the use of NIO instead of traditional IO for HTTPS. One consequence of using NIO with HTTPS is that the bundle needs at least a Java 5 runtime. If this property is not set the (default) value of the `org.apache.felix.http.nio` property is used.
-* `org.apache.felix.http.enable` - Flag to enable the use of HTTP. The default is `true`.
-* `org.apache.felix.https.enable` - Flag to enable the user of HTTPS. The default is `false`.
-* `org.apache.felix.https.keystore` - The name of the file containing the keystore.
-* `org.apache.felix.https.keystore.password` - The password for the keystore.
-* `org.apache.felix.https.keystore.key.password` - The password for the key in the keystore.
-* `org.apache.felix.https.truststore` - The name of the file containing the truststore.
-* `org.apache.felix.https.truststore.password` - The password for the truststore.
-* `org.apache.felix.https.clientcertificate` - Flag to determine if the HTTPS protocol requires, wants or does not use client certificates. Legal values are `needs`, `wants` and `none`. The default is `none`.
-* `org.apache.felix.http.debug` - Flag to enable debugging for this service implementation. The default is `false`.
+| Property | Description |
+|--|--|
+| `org.apache.felix.http.debug` | Flag to enable debugging for this service implementation. The default is `false` |
+| `org.apache.felix.http.host` | Host name or IP Address of the interface to listen on. The default is `null` causing Jetty to listen on all interfaces |
+| `org.osgi.service.http.port` | The port used for servlets and resources available via HTTP. The default is `80`. A negative port number has the same effect as setting `org.apache.felix.http.enable` to `false` |
+| `org.osgi.service.http.port.secure` | The port used for servlets and resources available via HTTPS. The default is `443`. A negative port number has the same effect as setting `org.apache.felix.https.enable` to `false` |
+| `org.apache.felix.http.context_path` | The Servlet Context Path to use for the Http Service. If this property is not configured it  defaults to "/". This must be a valid path starting with a slash and not  ending with a slash (unless it is the root context) |
+| `org.apache.felix.http.timeout` | Connection timeout in milliseconds. The default is 60000 (60 seconds) |
+| `org.apache.felix.http.session.timeout` | Allows for the specification of the Session life time as a number of minutes. This property serves the same purpose as the `session-timeout` element in a Web Application descriptor. The default is zero for no timeout at all |
+| `org.apache.felix.http.nio` | Flag to enable the use of NIO instead of traditional IO for HTTP. One consequence of using NIO with HTTP is that the bundle needs at least a Java 5 runtime. The default is `true` |
+| `org.apache.felix.https.nio` | Flag to enable the use of NIO instead of traditional IO for HTTPS. One consequence of using NIO with HTTPS is that the bundle needs at least a Java 5 runtime. If this property is not set the (default) value of the `org.apache.felix.http.nio` property is used |
+| `org.apache.felix.http.enable` | Flag to enable the use of HTTP. The default is `true` |
+| `org.apache.felix.https.enable` | Flag to enable the user of HTTPS. The default is `false` |
+| `org.apache.felix.https.keystore` | The name of the file containing the keystore |
+| `org.apache.felix.https.keystore.password` | The password for the keystore |
+| `org.apache.felix.https.keystore.key.password` | The password for the key in the keystore |
+| `org.apache.felix.https.truststore` | The name of the file containing the truststore |
+| `org.apache.felix.https.truststore.type` | The type of truststore to use. The default is `JKS` |
+| `org.apache.felix.https.truststore.password` | The password for the truststore |
+| `org.apache.felix.https.clientcertificate` | Flag to determine if the HTTPS protocol requires, wants or does not use client certificates. Legal values are `needs`, `wants` and `none`. The default is `none` |
+| `org.mortbay.jetty.servlet.SessionCookie` | Name of the cookie used to transport the Session ID. The default is `JSESSIONID` |
+| `org.mortbay.jetty.servlet.SessionURL` | Name of the request parameter to transport the Session ID. The default is `jsessionid` |
+| `org.mortbay.jetty.servlet.SessionDomain` | Domain to set on the session cookie. The default is `null` |
+| `org.mortbay.jetty.servlet.SessionPath` | The path to set on the session cookie. The default is the configured session context path (`/`) |
+| `org.mortbay.jetty.servlet.MaxAge` | The maximum age value to set on the cookie. The default is `-1` |
+| `org.apache.felix.http.jetty.headerBufferSize` | Size of the buffer for request and response headers. Default is 16 KB |
+| `org.apache.felix.http.jetty.requestBufferSize` | Size of the buffer for requests not fitting the header buffer. Default is 8 KB |
+| `org.apache.felix.http.jetty.responseBufferSize` | Size of the buffer for responses. Default is 24 KB |
+| `org.apache.felix.http.jetty.maxFormSize` | The maximum size accepted for a form post. Defaults to 200 KB |
+| `org.apache.felix.https.jetty.cipersuites.excluded` | Configures comma-separated list of cipher suites to *exclude*. Default is `null`, meaning that no cipher suite is excluded |
+| `org.apache.felix.https.jetty.cipersuites.included` | Configures comma-separated list of cipher suites to *include*. Default is `null`, meaning that the default cipher suites are used |
+| `org.apache.felix.http.mbeans` | If `true`, enables the MBean server functionality. The default is `false` |
 
 Additionally, the all-in-one bundle uses the following environment properties:
 
-* `org.apache.felix.http.jettyEnabled` - True to enable jetty as the http container. The default is `false`.
-* `org.apache.felix.http.whiteboardEnabled` - True to enable the whiteboard implementation. The default is `false`.
+| Property | Description |
+|--|--|
+| `org.apache.felix.http.jettyEnabled` | If `true`, the embedded Jetty server is used as HTTP container. The default is `false` |
+| `org.apache.felix.http.whiteboardEnabled` | If `true`, the whiteboard-style registration of servlets and filters is enabled. The default is `false` |
+| `org.apache.felix.http.cometdEnabled` | If `true` the CometD/Ajax Push feature is enabled. The default is `false` |
 
-The Jetty based implementation supports the following Jetty specific configuration as of Http Service Jetty Bundle 2.4:
+The CometD bundle supports the following configuration options:
 
-* `org.apache.felix.http.host` - Host name or IP Address of the interface to listen on. The default is `null` causing Jetty to listen on all interfaces.
-* `org.apache.felix.http.context_path` - The Servlet Context Path to use for the Http Service. If this property is not configured it  defaults to "/". This must be a valid path starting with a slash and not  ending with a slash (unless it is the root context).
-* `org.apache.felix.http.timeout` - Connection timeout in milliseconds. The default is 60000 (60 seconds).
-* `org.apache.felix.http.session.timeout` - Allows for the specification of the Session life time as a number of minutes. This property serves the same purpose as the `session-timeout` element in a Web Application descriptor. The default is zero for no timeout at all.
-* `org.mortbay.jetty.servlet.SessionCookie` - Name of the cookie used to transport the Session ID. The default is `JSESSIONID`.
-* `org.mortbay.jetty.servlet.SessionURL` - Name of the request parameter to transport the Session ID. The default is `jsessionid`.
-* `org.mortbay.jetty.servlet.SessionDomain` - Domain to set on the session cookie. The default is `null`.
-* `org.mortbay.jetty.servlet.SessionPath` - The path to set on the session cookie. The default is the configured session context path (`/`).
-* `org.mortbay.jetty.servlet.MaxAge` - The maximum age value to set on the cookie. The default is `-1`.
-* `org.apache.felix.http.jetty.headerBufferSize` - Size of the buffer for request and response headers. Default is 16KB.
-* `org.apache.felix.http.jetty.requestBufferSize` - Size of the buffer for requests not fitting the header buffer. Default is 8KB.
-* `org.apache.felix.http.jetty.responseBufferSize` - Size of the buffer for responses. Default is 24KB.
+| Property | Description |
+|--|--|
+| `org.apache.felix.http.cometd.path` | Defines the path for the CometD endpoint. Default is `/system/cometd` |
 
 ## Servlet API Events