Bug 451636 - [http] update to the latest R6 APII20141202-0800I20141125-0800I20141118-0830I20141118-0800

20 files changed, 337 insertions, 261 deletions

diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/context/ServletContextHelper.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/context/ServletContextHelper.java
index ecd33a7fa..56f11630c 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/context/ServletContextHelper.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/context/ServletContextHelper.java
@@ -27,55 +27,71 @@ import org.osgi.annotation.versioning.ConsumerType;
 import org.osgi.framework.Bundle;
 
 /**
- * Helper service for the servlet context used by whiteboard services for HTTP
- * requests.
+ * Helper service for a servlet context used by a Http Whiteboard implementation
+ * to serve HTTP requests.
+ *
+ * <p>
+ * This service defines methods that the Http Whiteboard Implementation may call
+ * to get information for a request when dealing with whiteboard services.
  * 
  * <p>
- * This service defines methods that the Http Whiteboard Service implementation
- * may call to get information for a request when dealing with whiteboard
- * services.
+ * Each {@code ServletContextHelper} is registered with a
+ * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_NAME
+ * service property} containing a name to reference by servlets, servlet
+ * filters, resources, and listeners. If there is more than one
+ * {@code ServletContextHelper} registered with the same context name, the one
+ * with the highest service ranking is active, the others are inactive.
+ * 
+ * <p>
+ * A context is registered with the
+ * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_PATH
+ * service property} to define a path under which all services registered with
+ * this context are reachable. If there is more than one
+ * {@code ServletContextHelper} registered with the same path, the one with the
+ * highest service ranking is active, the others are inactive.
  * 
  * <p>
  * Servlets, servlet filters, resources, and listeners services may be
- * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_NAME
- * associated} with an {@code ServletContextHelper} service. Those whiteboard
- * services that are associated using the same {@code ServletContextHelper}
- * object will share the same {@code ServletContext} object.
+ * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_SELECT
+ * associated} with a {@code ServletContextHelper} service. If the referenced
+ * {@code ServletContextHelper} service does not exist or is currently not
+ * active, the whiteboard services for that {@code ServletContextHelper} are not
+ * active either.
+ * 
+ * <p>
+ * If no {@code ServletContextHelper} service is associated, that is no
+ * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_SELECT
+ * HTTP_WHITEBOARD_CONTEXT_SELECT} is configured for a whiteboard service, a
+ * default {@code ServletContextHelper} is used.
+ * 
+ * <p>
+ * Those whiteboard services that are associated using the same
+ * {@code ServletContextHelper} object will share the same
+ * {@code ServletContext} object.
  * 
  * <p>
- * If no {@code ServletContextHelper} service is associated, a default
- * {@code ServletContextHelper} is used. The behavior of the methods on the
- * default {@code ServletContextHelper} is defined as follows:
+ * The behavior of the methods on the default {@code ServletContextHelper} is
+ * defined as follows:
  * <ul>
  * <li>{@code getMimeType} - Does not define any customized MIME types for the
- * {@code Content-Type} header in the response, and calls the parent context if
- * it exists. Otherwise it always returns {@code null}.</li>
+ * {@code Content-Type} header in the response, and always returns {@code null}.
+ * </li>
  * <li>{@code handleSecurity} - Performs implementation-defined authentication
  * on the request.</li>
  * <li>{@code getResource} - Assumes the named resource is in the bundle of the
  * whiteboard service. This method calls the whiteboard service bundle's
  * {@code Bundle.getEntry} method, and returns the appropriate URL to access the
  * resource. On a Java runtime environment that supports permissions, the Http
- * Whiteboard Service needs to be granted
+ * Whiteboard Implementation needs to be granted
  * {@code org.osgi.framework.AdminPermission[*,RESOURCE]}.</li>
  * <li>{@code getResourcePaths} - Assumes that the resources are in the bundle
  * of the whiteboard service. This method calls {@code Bundle.findEntries}
  * method, and returns the found entries. On a Java runtime environment that
- * supports permissions, the Http Whiteboard Service needs to be granted
+ * supports permissions, the Http Whiteboard Implementation needs to be granted
  * {@code org.osgi.framework.AdminPermission[*,RESOURCE]}.</li>
- * <li>{@code getRealPath} - This method returns {@code null}.
+ * <li>{@code getRealPath} - This method returns {@code null}.</li>
  * </ul>
  * 
- * It is possible to register own {@code ServletContextHelper} services with a
- * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_NAME
- * service property}.
- * 
- * <p>
- * A context can be registered with the
- * {@link org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_PATH
- * service property} to define a path under which all services registered with
- * this context are reachable.
- * 
  * @ThreadSafe
  * @author $Id$
  * @see org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_NAME
@@ -131,9 +147,9 @@ public abstract class ServletContextHelper {
 	 * Handles security for the specified request.
 	 * 
 	 * <p>
-	 * The Http Whiteboard Service calls this method prior to servicing the
-	 * specified request. This method controls whether the request is processed
-	 * in the normal manner or an error is returned.
+	 * The Http Whiteboard Implementation calls this method prior to servicing
+	 * the specified request. This method controls whether the request is
+	 * processed in the normal manner or an error is returned.
 	 * 
 	 * <p>
 	 * If the request requires authentication and the Authorization header in
@@ -150,10 +166,10 @@ public abstract class ServletContextHelper {
 	 * object to Forbidden(403) and return {@code false}.
 	 * 
 	 * <p>
-	 * When this method returns {@code false}, the Http Whiteboard Service will
-	 * send the response back to the client, thereby completing the request.
-	 * When this method returns {@code true}, the Http Whitboard Service will
-	 * proceed with servicing the request.
+	 * When this method returns {@code false}, the Http Whiteboard
+	 * Implementation will send the response back to the client, thereby
+	 * completing the request. When this method returns {@code true}, the Http
+	 * Whitboard Implementation will proceed with servicing the request.
 	 * 
 	 * <p>
 	 * If the specified request has been authenticated, this method must set the
@@ -178,11 +194,11 @@ public abstract class ServletContextHelper {
 	 * @param request The HTTP request.
 	 * @param response The HTTP response.
 	 * @return {@code true} if the request should be serviced, {@code false} if
-	 *         the request should not be serviced and Http Whiteboard Service
-	 *         will send the response back to the client.
+	 *         the request should not be serviced and Http Whiteboard
+	 *         Implementation will send the response back to the client.
 	 * @throws java.io.IOException may be thrown by this method. If this occurs,
-	 *         the Http Whiteboard Service will terminate the request and close
-	 *         the socket.
+	 *         the Http Whiteboard Implementation will terminate the request and
+	 *         close the socket.
 	 */
 	public boolean handleSecurity(final HttpServletRequest request,
 			                      final HttpServletResponse response)
@@ -194,11 +210,12 @@ public abstract class ServletContextHelper {
 	 * Maps a resource name to a URL.
 	 * 
 	 * <p>
-	 * Called by the Http Whiteboard Service to map the specified resource name
-	 * to a URL. For servlets, Http Whiteboard Service will call this method to
-	 * support the {@code ServletContext} methods {@code getResource} and
-	 * {@code getResourceAsStream}. For resource servlets, Http Whiteboard
-	 * Service will call this method to locate the named resource.
+	 * Called by the Http Whiteboard Implementation to map the specified
+	 * resource name to a URL. For servlets, the Http Whiteboard Implementation
+	 * will call this method to support the {@code ServletContext} methods
+	 * {@code getResource} and {@code getResourceAsStream}. For resources, the
+	 * Http Whiteboard Implementation will call this method to locate the named
+	 * resource.
 	 * 
 	 * <p>
 	 * The context can control from where resources come. For example, the
@@ -207,8 +224,8 @@ public abstract class ServletContextHelper {
 	 * the context's bundle via {@code getClass().getResource(name)}
 	 * 
 	 * @param name The name of the requested resource.
-	 * @return A URL that Http Whiteboard Service can use to read the resource
-	 *         or {@code null} if the resource does not exist.
+	 * @return A URL that a Http Whiteboard Implementation can use to read the
+	 *         resource or {@code null} if the resource does not exist.
 	 */
 	public URL getResource(String name) {
 		final Bundle localBundle = this.bundle;
@@ -226,12 +243,12 @@ public abstract class ServletContextHelper {
 	 * Maps a name to a MIME type.
 	 * 
 	 * <p>
-	 * Called by the Http Whiteboard Service to determine the MIME type for the
-	 * specified name. For whiteboard services, the Http Whiteboard Service will
-	 * call this method to support the {@code ServletContext} method
-	 * {@code getMimeType}. For resource servlets, the Http Whiteboard Service
-	 * will call this method to determine the MIME type for the
-	 * {@code Content-Type} header in the response.
+	 * Called by the Http Whiteboard Implementation to determine the MIME type
+	 * for the specified name. For whiteboard services, the Http Whiteboard
+	 * Implementation will call this method to support the
+	 * {@code ServletContext} method {@code getMimeType}. For resource servlets,
+	 * the Http Whiteboard Implementation will call this method to determine the
+	 * MIME type for the {@code Content-Type} header in the response.
 	 *
 	 * @param name The name for which to determine the MIME type.
 	 * @return The MIME type (e.g. text/html) of the specified name or
@@ -248,7 +265,7 @@ public abstract class ServletContextHelper {
 	 * argument.
 	 * 
 	 * <p>
-	 * Called by the Http Whiteboard Service to support the
+	 * Called by the Http Whiteboard Implementation to support the
 	 * {@code ServletContext} method {@code getResourcePaths} for whiteboard
 	 * services.
 	 * 
@@ -277,7 +294,7 @@ public abstract class ServletContextHelper {
 	 * Gets the real path corresponding to the given virtual path.
 	 * 
 	 * <p>
-	 * Called by the Http Whiteboard Service to support the
+	 * Called by the Http Whiteboard Implementation to support the
 	 * {@code ServletContext} method {@code getRealPath} for whiteboard
 	 * services.
 	 * 
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntime.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntime.java
index a4b1539bc..d854f839a 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntime.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntime.java
@@ -22,7 +22,7 @@ import org.osgi.service.http.runtime.dto.RuntimeDTO;
 
 /**
  * The {@code HttpServiceRuntime} service represents the runtime information of
- * a Http (Whiteboard) Service implementation.
+ * a Http (Whiteboard) Implementation.
  *
  * <p>
  * It provides access to DTOs representing the current state of the service.
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java
index 7357ae7c1..21f874cde 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java
@@ -28,17 +28,17 @@ public final class HttpServiceRuntimeConstants {
 	}
 
 	/**
-	 * Http service runtime registration property specifying the endpoints upon
-	 * which the Http service runtime is listening.
+	 * Http Runtime Service registration property specifying the endpoints upon
+	 * which the Http Service Runtime is listening.
 	 * 
 	 * <p>
 	 * An endpoint value is a URL or a relative path, to which the Http service
 	 * runtime is listening. For example, {@code http://192.168.1.10:8080/} or
 	 * {@code /myapp/}. A relative path may be used if the scheme and authority
 	 * parts of the URL are not known, e.g. in a bridged Http Service
-	 * implementation. If the Http Service implementation is serving the root context and
-	 * neither scheme nor authority is known, the value of the property is "/".
-	 * Both, a URL and a relative path, must end with a slash.
+	 * implementation. If the Http Service implementation is serving the root
+	 * context and neither scheme nor authority is known, the value of the
+	 * property is "/". Both, a URL and a relative path, must end with a slash.
 	 * <p>
 	 * An Http Service Runtime can be listening on multiple endpoints.
 	 * 
@@ -47,4 +47,18 @@ public final class HttpServiceRuntimeConstants {
 	 * {@code String[]}, or {@code Collection<String>}.
 	 */
 	public static final String	HTTP_SERVICE_ENDPOINT_ATTRIBUTE			= "osgi.http.endpoint";
+
+	/**
+	 * Http Runtime Service registration property to associate the Http Runtime
+	 * Service with a Http Service implementation.
+	 * 
+	 * <p>
+	 * If this Http Whiteboard implementation also implements the Http Service
+	 * Specification this property is set to the {@code service.id} of the
+	 * {@code HttpService} provided by this implementation.
+	 * 
+	 * <p>
+	 * The value of this attribute must be of type {@code Integer}.
+	 */
+	public static final String	HTTP_SERVICE_ID_ATTRIBUTE		= "osgi.http.service.id";
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/BaseServletDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/BaseServletDTO.java
index 569064a25..1bca590bf 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/BaseServletDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/BaseServletDTO.java
@@ -27,7 +27,7 @@ import org.osgi.dto.DTO;
  */
 public abstract class BaseServletDTO extends DTO {
 	/**
-	 * The name of the servlet.
+	 * The name of the servlet. This value is never {@code null}.
 	 */
 	public String				name;
 
@@ -45,24 +45,26 @@ public abstract class BaseServletDTO extends DTO {
 	public boolean				asyncSupported;
 
 	/**
-	 * The servlet initialization parameters as provided during registration
-	 * of the servlet. Additional parameters like the Http Service Runtime
-	 * attributes are not included.
+	 * The servlet initialization parameters as provided during registration of
+	 * the servlet. Additional parameters like the Http Service Runtime
+	 * attributes are not included. If the service has no initialization
+	 * parameters, the map is empty.
 	 */
 	public Map<String, String>	initParams;
 
 	/**
-	 * The service id of the {@code ServletContext} for the servlet.
+	 * The service id of the servlet context for the servlet represented by this
+	 * DTO.
 	 */
 	public long		servletContextId;
 
 	/**
-	 * Service property identifying the servlet. In the case of a servlet registered
-	 * in the service registry and picked up by a whiteboard implementation, this value 
-	 * is not negative and corresponds to the service id in the registry. 
-	 * If the servlet has not been registered in the service registry, the value
-	 * is negative and a unique negative value is generated by the Http Service Runtime
-	 * in this case.
+	 * Service property identifying the servlet. In the case of a servlet
+	 * registered in the service registry and picked up by a Http Whiteboard
+	 * Implementation, this value is not negative and corresponds to the service
+	 * id in the registry. If the servlet has not been registered in the service
+	 * registry, the value is negative and a unique negative value is generated
+	 * by the Http Service Runtime in this case.
 	 */
 	public long		serviceId;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/DTOConstants.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/DTOConstants.java
index 8b4538395..69942753b 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/DTOConstants.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/DTOConstants.java
@@ -32,15 +32,15 @@ public final class DTOConstants {
 	public static final int	FAILURE_REASON_UNKNOWN		= 0;
 
 	/**
-	 * No matching servlet context
+	 * No matching {@code ServletContextHelper}.
 	 * <p>
 	 * The value of {@code FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING} is 1.
 	 **/
 	public static final int	FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING	= 1;
 
 	/**
-	 * Matching servlet context, but servlet context is not used due to a
-	 * problem with the context.
+	 * Matching {@code ServletContextHelper}, but the context is not used due to
+	 * a problem with the context.
 	 * <p>
 	 * The value of {@code FAILURE_REASON_SERVLET_CONTEXT_FAILURE} is 2.
 	 */
@@ -63,7 +63,7 @@ public final class DTOConstants {
 	public static final int	FAILURE_REASON_EXCEPTION_ON_INIT			= 4;
 
 	/**
-	 * The service is registered in the servlet registry but getting the service
+	 * The service is registered in the service registry but getting the service
 	 * fails as it returns {@code null}.
 	 * <p>
 	 * The value of {@code FAILURE_REASON_SERVICE_NOT_GETTABLE} is 5.
@@ -71,7 +71,7 @@ public final class DTOConstants {
 	public static final int	FAILURE_REASON_SERVICE_NOT_GETTABLE			= 5;
 
 	/**
-	 * The service is registered in the servlet registry but the provided
+	 * The service is registered in the service registry but the provided
 	 * registration properties are invalid.
 	 * <p>
 	 * The value of {@code FAILURE_REASON_VALIDATION_FAILED} is 6.
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ErrorPageDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ErrorPageDTO.java
index 8230d5c92..80437fba4 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ErrorPageDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ErrorPageDTO.java
@@ -17,8 +17,8 @@
 package org.osgi.service.http.runtime.dto;
 
 /**
- * Represents a {@code javax.servlet.Servlet} servlet for handling errors and
- * currently being used by a servlet context.
+ * Represents a {@code javax.servlet.Servlet} for handling errors and currently
+ * being used by a servlet context.
  *
  * @NotThreadSafe
  * @author $Id$
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java
index 0003c01bf..ac6a6c0be 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java
@@ -18,11 +18,11 @@ package org.osgi.service.http.runtime.dto;
 
 /**
  * Represents a {@code javax.servlet.Servlet} service registered as an error
- * page but currently not being used for a servlet context due to a problem.
+ * page but currently not being used by a servlet context due to a problem.
  * <p>
  * As the servlet represented by this DTO is not used due to a failure, the
  * field {@link FailedErrorPageDTO#servletContextId} always returns {@code 0}
- * and does not point to an existing servlet context.
+ * and does not point to an existing {@code ServletContextHelper}.
  * 
  * @NotThreadSafe
  * @author $Id$
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedFilterDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedFilterDTO.java
index 01f84828b..e1016e9e3 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedFilterDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedFilterDTO.java
@@ -17,8 +17,8 @@
 package org.osgi.service.http.runtime.dto;
 
 /**
- * Represents a servlet {@code Filter} filter which is currently not being 
- * used for a servlet context due to a problem.
+ * Represents a servlet {@code Filter} service which is currently not being used
+ * by a servlet context due to a problem.
  * <p>
  * As the service represented by this DTO is not used due to a failure, the
  * field {@link FailedFilterDTO#servletContextId} always returns {@code 0} and
@@ -30,7 +30,7 @@ package org.osgi.service.http.runtime.dto;
 public class FailedFilterDTO extends FilterDTO {
 
 	/**
-	 * The reason why the filter represented by this DTO is not used.
+	 * The reason why the servlet filter represented by this DTO is not used.
 	 * 
 	 * @see DTOConstants#FAILURE_REASON_UNKNOWN
 	 * @see DTOConstants#FAILURE_REASON_EXCEPTION_ON_INIT
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedListenerDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedListenerDTO.java
index e6b1e1a42..5e2130cba 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedListenerDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedListenerDTO.java
@@ -17,8 +17,8 @@
 package org.osgi.service.http.runtime.dto;
 
 /**
- * Represents a listener service which is currently not being 
- * used for a servlet context due to a problem.
+ * Represents a listener service which is currently not being used by a servlet
+ * context due to a problem.
  * <p>
  * As the listener represented by this DTO is not used due to a failure, the
  * field {@link FailedErrorPageDTO#servletContextId} always returns {@code 0}
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedResourceDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedResourceDTO.java
index 9ebead085..2f8ab091c 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedResourceDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedResourceDTO.java
@@ -17,10 +17,10 @@
 package org.osgi.service.http.runtime.dto;
 
 /**
- * Represents a resource definition which is currently not being 
- * used for a servlet context due to a problem.
+ * Represents a resource definition which is currently not being used by a
+ * servlet context due to a problem.
  * <p>
- * As the service represented by this DTO is not used due to a failure, the
+ * As the resource represented by this DTO is not used due to a failure, the
  * field {@link FailedResourceDTO#servletContextId} always returns {@code 0} and
  * does not point to an existing servlet context.
  * 
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java
index 6d47980b4..40beb0805 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java
@@ -17,8 +17,7 @@
 package org.osgi.service.http.runtime.dto;
 
 /**
- * Represents a {@code javax.servlet.ServletContext} servlet context that is
- * currently not used due to some problem.
+ * Represents a servlet context that is currently not used due to some problem.
  * 
  * The following fields return an empty array for a
  * {@code FailedServletContextDTO}:
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletDTO.java
index 6127b1869..7fa7499d9 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FailedServletDTO.java
@@ -17,8 +17,8 @@
 package org.osgi.service.http.runtime.dto;
 
 /**
- * Represents a {@code javax.servlet.Servlet} servlet which is currently not
- * being used for a servlet context due to a problem.
+ * Represents a {@code javax.servlet.Servlet} service which is currently not
+ * being used by a servlet context due to a problem.
  * <p>
  * As the servlet represented by this DTO is not used due to a failure, the
  * field {@link FailedErrorPageDTO#servletContextId} always returns {@code 0}
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FilterDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FilterDTO.java
index 88adede63..d9df0a9aa 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FilterDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/FilterDTO.java
@@ -20,15 +20,15 @@ import java.util.Map;
 import org.osgi.dto.DTO;
 
 /**
- * Represents a servlet {@code javax.servlet.Filter} filter currently being used
- * for a servlet context.
+ * Represents a servlet {@code javax.servlet.Filter} service currently being
+ * used for by a servlet context.
  * 
  * @NotThreadSafe
  * @author $Id$
  */
 public class FilterDTO extends DTO {
 	/**
-	 * The name of the servlet filter.
+	 * The name of the servlet filter. This field is never {@code null}.
 	 */
 	public String				name;
 
@@ -36,8 +36,8 @@ public class FilterDTO extends DTO {
 	 * The request mappings for the servlet filter.
 	 * 
 	 * <p>
-	 * The specified patterns are used to determine whether a request is
-	 * mapped to the servlet filter.
+	 * The specified patterns are used to determine whether a request is mapped
+	 * to the servlet filter. This array might be empty.
 	 */
 	public String[]				patterns;
 
@@ -45,8 +45,8 @@ public class FilterDTO extends DTO {
 	 * The servlet names for the servlet filter.
 	 * 
 	 * <p>
-	 * The specified names are used to determine the servlets whose requests
-	 * are mapped to the servlet filter.
+	 * The specified names are used to determine the servlets whose requests are
+	 * mapped to the servlet filter. This array might be empty.
 	 */
 	public String[]				servletNames;
 
@@ -55,7 +55,7 @@ public class FilterDTO extends DTO {
 	 * 
 	 * <p>
 	 * The specified regular expressions are used to determine whether a request
-	 * is mapped to the servlet filter.
+	 * is mapped to the servlet filter. This array might be empty.
 	 */
 	public String[]				regexs;
 
@@ -69,29 +69,31 @@ public class FilterDTO extends DTO {
 	 * 
 	 * <p>
 	 * The specified names are used to determine in what occasions the servlet
-	 * filter is called
+	 * filter is called. This array is never {@code null}.
 	 */
 	public String[]				dispatcher;
 
 	/**
-	 * The filter initialization parameters as provided during registration
-	 * of the filter. Additional parameters like the Http Service Runtime
-	 * attributes are not included.
+	 * The servlet filter initialization parameters as provided during
+	 * registration of the servlet filter. Additional parameters like the Http
+	 * Service Runtime attributes are not included. If the servlet filter has
+	 * not initialization parameters, this map is empty.
 	 */
 	public Map<String, String>	initParams;
 
 	/**
-	 * Service property identifying the filter. In the case of a filter registered
-	 * in the service registry and picked up by a whiteboard implementation, this value 
-	 * is not negative and corresponds to the service id in the registry. 
-	 * If the filter has not been registered in the service registry, the value
-	 * is negative and a unique negative value is generated by the Http Service Runtime
-	 * in this case.
+	 * Service property identifying the servlet filter. In the case of a servlet
+	 * filter registered in the service registry and picked up by a Http
+	 * Whiteboard Implementation, this value is not negative and corresponds to
+	 * the service id in the registry. If the servlet filter has not been
+	 * registered in the service registry, the value is negative and a unique
+	 * negative value is generated by the Http Service Runtime in this case.
 	 */
 	public long					serviceId;
 
 	/**
-	 * The service id of the {@code ServletContext} for the servlet filter.
+	 * The service id of the servlet context for the servlet filter represented
+	 * by this DTO.
 	 */
 	public long		servletContextId;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ListenerDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ListenerDTO.java
index 05556c184..6122537f6 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ListenerDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ListenerDTO.java
@@ -19,7 +19,7 @@ package org.osgi.service.http.runtime.dto;
 import org.osgi.dto.DTO;
 
 /**
- * Represents a listener currently being used for a servlet context.
+ * Represents a listener currently being used by a servlet context.
  * 
  * @NotThreadSafe
  * @author $Id$
@@ -27,14 +27,14 @@ import org.osgi.dto.DTO;
 public class ListenerDTO extends DTO {
 
 	/**
-	 * The fully qualified type names the listener.
+	 * The fully qualified type names the listener. This array is never empty.
 	 */
 	public String[]				types;
 
 	/**
-	 * Service property identifying the listener. In the case of a listener
-	 * registered in the service registry and picked up by a whiteboard
-	 * implementation, this value is not negative and corresponds to the service
+	 * Service property identifying the listener. In the case of a Listener
+	 * registered in the service registry and picked up by a Http Whiteboard
+	 * Implementation, this value is not negative and corresponds to the service
 	 * id in the registry. If the listener has not been registered in the
 	 * service registry, the value is negative and a unique negative value is
 	 * generated by the Http Service Runtime in this case.
@@ -42,7 +42,8 @@ public class ListenerDTO extends DTO {
 	public long					serviceId;
 
 	/**
-	 * The service id of the {@code ServletContext} for the listener.
+	 * The service id of the servlet context for the listener represented by
+	 * this DTO.
 	 */
 	public long		servletContextId;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RequestInfoDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RequestInfoDTO.java
index e6df7dc86..bea86cedc 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RequestInfoDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RequestInfoDTO.java
@@ -31,30 +31,30 @@ public class RequestInfoDTO extends DTO {
 	public String				path;
 
 	/**
-	 * The service id of the {@code ServletContext} for this request.
+	 * The service id of the servlet context processing the request represented
+	 * by this DTO.
 	 */
 	public long		servletContextId;
 	
 	/**
-	 * The filters processing this request.
+	 * The servlet filters processing this request. If no servlet filters are
+	 * called for processing this request, an empty array is returned.
 	 */
 	public FilterDTO[] filterDTOs;
 	
 	/**
-	 * The servlet processing this request. 
-	 * If the request is processed by a servlet, this field
-	 * points to the DTO of the servlet. If the request is
-	 * processed by another type of component like a resource, this
-	 * field is null.
+	 * The servlet processing this request. If the request is processed by a
+	 * servlet, this field points to the DTO of the servlet. If the request is
+	 * processed by another type of component like a resource, this field is
+	 * {@code null}.
 	 */
 	public ServletDTO servletDTO;
 
 	/**
-	 * The resource processing this request. 
-	 * If the request is processed by a resource, this field
-	 * points to the DTO of the resource. If the request is
-	 * processed by another type of component like a servlet, this
-	 * field is null.
+	 * The resource processing this request. If the request is processed by a
+	 * resource, this field points to the DTO of the resource. If the request is
+	 * processed by another type of component like a servlet, this field is
+	 * {@code null}.
 	 */
 	public ResourceDTO resourceDTO;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ResourceDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ResourceDTO.java
index 4b8b1925a..9bf52d592 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ResourceDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ResourceDTO.java
@@ -19,7 +19,7 @@ package org.osgi.service.http.runtime.dto;
 import org.osgi.dto.DTO;
 
 /**
- * Represents a resource definition currently being used for a servlet context.
+ * Represents a resource definition currently being used by a servlet context.
  * 
  * @NotThreadSafe
  * @author $Id$
@@ -29,8 +29,8 @@ public class ResourceDTO extends DTO {
 	 * The request mappings for the resource.
 	 * 
 	 * <p>
-	 * The specified patterns are used to determine whether a request is
-	 * mapped to the resource.
+	 * The specified patterns are used to determine whether a request is mapped
+	 * to the resource. This value is never {@code null}.
 	 */
 	public String[]				patterns;
 
@@ -40,17 +40,18 @@ public class ResourceDTO extends DTO {
 	public String				prefix;
 
 	/**
-	 * Service property identifying the resource. In the case of a resource registered
-	 * in the service registry and picked up by a whiteboard implementation, this value 
-	 * is not negative and corresponds to the service id in the registry. 
-	 * If the resource has not been registered in the service registry, the value
-	 * is negative and a unique negative value is generated by the Http Service Runtime
-	 * in this case.
+	 * Service property identifying the resource. In the case of a resource
+	 * registered in the service registry and picked up by a Http Whiteboard
+	 * Implementation, this value is not negative and corresponds to the service
+	 * id in the registry. If the resource has not been registered in the
+	 * service registry, the value is negative and a unique negative value is
+	 * generated by the Http Service Runtime in this case.
 	 */
 	public long					serviceId;
 
 	/**
-	 * The service id of the {@code ServletContext} for the resource.
+	 * The service id of the servlet context for the resource represented by
+	 * this DTO.
 	 */
 	public long		servletContextId;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RuntimeDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RuntimeDTO.java
index 61a7c833e..6facc3683 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RuntimeDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/RuntimeDTO.java
@@ -28,14 +28,15 @@ import org.osgi.dto.DTO;
 public class RuntimeDTO extends DTO {
 
 	/**
-	 * The runtime attributes.
+	 * The runtime attributes. This value is never {@code null}.
 	 */
 	public Map<String, String>	attributes;
 
 	/**
-	 * Returns the representations of the {@code javax.servlet.ServletContext} objects used by
-	 * the Http service runtime. The returned array may be empty if the Http service 
-	 * runtime is currently not using any {@code ServletContext} objects.
+	 * Returns the representations of the {@code javax.servlet.ServletContext}
+	 * objects used by the Http Service Runtime. The returned array may be empty
+	 * if the Http Service Runtime is currently not using any
+	 * {@code javax.servlet.ServletContext} objects.
 	 */
 	public ServletContextDTO[] servletContextDTOs;
 
@@ -47,37 +48,37 @@ public class RuntimeDTO extends DTO {
 	public FailedServletContextDTO[] failedServletContextDTOs;
 
 	/**
-	 * Returns the representations of the {@code javax.servlet.Servlet} servlets associated
-	 * with this runtime but currently not used due to some problem.
+	 * Returns the representations of the {@code javax.servlet.Servlet} services
+	 * associated with this runtime but currently not used due to some problem.
 	 * The returned array may be empty.
 	 */
 	public FailedServletDTO[] failedServletDTOs;
 
 	/**
-	 * Returns the representations of the resources associated with this
-	 * runtime but currently not used due to some problem.
-	 * The returned array may be empty.
+	 * Returns the representations of the resources associated with this runtime
+	 * but currently not used due to some problem. The returned array may be
+	 * empty.
 	 */
 	public FailedResourceDTO[] failedResourceDTOs;
 
 	/**
-	 * Returns the representations of the servlet {@code javax.servlet.Filter} filters
-	 * associated with this runtime but currently not used due to some problem.
-	 * The returned array may be empty.
+	 * Returns the representations of the servlet {@code javax.servlet.Filter}
+	 * services associated with this runtime but currently not used due to some
+	 * problem. The returned array may be empty.
 	 */
 	public FailedFilterDTO[] failedFilterDTOs;
 
 	/**
-	 * Returns the representations of the error page {@code javax.servlet.Servlet} servlets
-	 * associated with this runtime but currently not used due to some problem.
-	 * The returned array may be empty.
+	 * Returns the representations of the error page
+	 * {@code javax.servlet.Servlet} services associated with this runtime but
+	 * currently not used due to some problem. The returned array may be empty.
 	 */
 	public FailedErrorPageDTO[] failedErrorPageDTOs;
 
 	/**
-	 * Returns the representations of the listeners
-	 * associated with this runtime but currently not used due to some problem.
-	 * The returned array may be empty.
+	 * Returns the representations of the listeners associated with this runtime
+	 * but currently not used due to some problem. The returned array may be
+	 * empty.
 	 */
 	public FailedListenerDTO[] failedListenerDTOs;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletContextDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletContextDTO.java
index d4d067f5b..668a57ac5 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletContextDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletContextDTO.java
@@ -20,8 +20,9 @@ import java.util.Map;
 import org.osgi.dto.DTO;
 
 /**
- * Represents a {@code javax.servlet.ServletContext} created for used servlets,
- * resources, servlet filters, and listeners. The servlet context is backed by a
+ * Represents a {@code javax.servlet.ServletContext} created for servlets,
+ * resources, servlet Filters, and listeners associated with that servlet
+ * context. The Servlet Context is usually backed by a
  * {@link org.osgi.service.http.context.ServletContextHelper} service.
  * 
  * @NotThreadSafe
@@ -29,12 +30,12 @@ import org.osgi.dto.DTO;
  */
 public class ServletContextDTO extends DTO {
 	/**
-	 * The names of the HTTP context.
+	 * The name of the servlet context.
 	 * 
-	 * An array of the names the corresponding
-	 * {@link org.osgi.service.http.context.ServletContextHelper} is used for.
+	 * The name of the corresponding
+	 * {@link org.osgi.service.http.context.ServletContextHelper}.
 	 */
-	public String[]				names;
+	public String				name;
 
 	/**
 	 * The context name of the servlet context.
@@ -54,9 +55,10 @@ public class ServletContextDTO extends DTO {
 	public String				contextPath;
 
 	/**
-	 * The servlet context initialization parameters. This is the set of parameters
-	 * provided when registering this context. Additional parameters like the Http Service Runtime
-	 * attributes are not included.
+	 * The servlet context initialization parameters. This is the set of
+	 * parameters provided when registering this context. Additional parameters
+	 * like the Http Service Runtime attributes are not included. If the context
+	 * has no initialization parameters, this map is empty.
 	 */
 	public Map<String, String>	initParams;
 
@@ -64,19 +66,22 @@ public class ServletContextDTO extends DTO {
 	 * The servlet context attributes.
 	 * 
 	 * <p>
-	 * The value type must be a numerical type, Boolean, String, DTO or an array
-	 * of any of the former. Therefore this method will only return the
-	 * attributes of the servlet context conforming to this constraint.
+	 * The value type must be a numerical type, {@code Boolean}, {@code String},
+	 * {@code DTO} or an array of any of the former. Therefore this method will
+	 * only return the attributes of the servlet context conforming to this
+	 * constraint. Other attributes are omitted. If there are no attributes
+	 * conforming to the constraint, an empty map is returned.
 	 */
 	public Map<String, Object>	attributes;
 
 	/**
-	 * Service property identifying the servlet context. In the case of a servlet context registered
-	 * in the service registry and picked up by a whiteboard implementation, this value 
-	 * is not negative and corresponds to the service id in the registry. 
-	 * If the servlet context has not been registered in the service registry, the value
-	 * is negative and a unique negative value is generated by the Http Service Runtime
-	 * in this case.
+	 * Service property identifying the servlet context. In the case of a
+	 * servlet context backed by a {@code ServletContextHelper} registered in
+	 * the service registry and picked up by a Http Whiteboard Implementation,
+	 * this value is not negative and corresponds to the service id in the
+	 * registry. If the servlet context is not backed by a service registered in
+	 * the service registry, the value is negative and a unique negative value
+	 * is generated by the Http Service Runtime in this case.
 	 */
 	public long					serviceId;
 
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletDTO.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletDTO.java
index a40ffc801..4b078f335 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletDTO.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/runtime/dto/ServletDTO.java
@@ -18,7 +18,7 @@ package org.osgi.service.http.runtime.dto;
 
 
 /**
- * Represents a {@code javax.servlet.Servlet} currently being used for a servlet
+ * Represents a {@code javax.servlet.Servlet} currently being used by a servlet
  * context.
  * 
  * @NotThreadSafe
@@ -29,8 +29,8 @@ public class ServletDTO extends BaseServletDTO {
 	 * The request mappings for the servlet.
 	 * 
 	 * <p>
-	 * The specified patterns are used to determine whether a request is
-	 * mapped to the servlet.
+	 * The specified patterns are used to determine whether a request is mapped
+	 * to the servlet. This array is never empty.
 	 */
 	public String[]				patterns;
 }
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java
index 77173e81d..42fee06d6 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java
@@ -17,7 +17,7 @@
 package org.osgi.service.http.whiteboard;
 
 /**
- * Defines standard names for Http Whiteboard Service constants.
+ * Defines standard constants for the whiteboard services.
  * 
  * @author $Id$
  */
@@ -27,63 +27,62 @@ public final class HttpWhiteboardConstants {
 	}
 
 	/**
-	 * The name of the default
-	 * {@link org.osgi.service.http.context.ServletContextHelper}. If a service
-	 * is registered with this property, it is overriding the default context
-	 * with a custom provided context.
-	 * 
-	 * @see #HTTP_WHITEBOARD_CONTEXT_NAME
-	 */
-	public static final String	HTTP_WHITEBOARD_DEFAUT_CONTEXT_NAME		= "default";
-
-	/**
-	 * Service property specifying the name(s) of an
+	 * Service property specifying the name of an
 	 * {@link org.osgi.service.http.context.ServletContextHelper} service.
 	 * 
 	 * <p>
 	 * For {@link org.osgi.service.http.context.ServletContextHelper} services,
 	 * this service property must be specified. Context services without this
-	 * service property must be ignored.
+	 * service property are ignored.
 	 * 
 	 * <p>
-	 * Servlet, listener, servlet filter, and resource servlet services might
-	 * refer to a specific
-	 * {@link org.osgi.service.http.context.ServletContextHelper} service
-	 * referencing the name with the {@link #HTTP_WHITEBOARD_CONTEXT_SELECT}
-	 * property.
+	 * Servlet, listener, servlet filter, and resource services might refer to a
+	 * specific {@link org.osgi.service.http.context.ServletContextHelper}
+	 * service referencing the name with the
+	 * {@link #HTTP_WHITEBOARD_CONTEXT_SELECT} property.
 	 * 
 	 * <p>
 	 * For {@link org.osgi.service.http.context.ServletContextHelper} services,
-	 * the value of this service property must be of type {@code String},
-	 * {@code String[]}, or {@code Collection<String>}. Each value must follow
-	 * the "symbolic-name" specification from Section 1.3.2 of the OSGi Core
-	 * Specification.
+	 * the value of this service property must be of type {@code String}. The
+	 * value must follow the "symbolic-name" specification from Section 1.3.2 of
+	 * the OSGi Core Specification.
 	 * 
 	 * @see #HTTP_WHITEBOARD_CONTEXT_PATH
 	 * @see #HTTP_WHITEBOARD_CONTEXT_SELECT
-	 * @see #HTTP_WHITEBOARD_DEFAUT_CONTEXT_NAME
+	 * @see #HTTP_WHITEBOARD_DEFAULT_CONTEXT_NAME
 	 */
 	public static final String	HTTP_WHITEBOARD_CONTEXT_NAME			= "osgi.http.whiteboard.context.name";
 
 	/**
+	 * The name of the default
+	 * {@link org.osgi.service.http.context.ServletContextHelper}. If a service
+	 * is registered with this property, it is overriding the default context
+	 * with a custom provided context.
+	 * 
+	 * @see #HTTP_WHITEBOARD_CONTEXT_NAME
+	 */
+	public static final String	HTTP_WHITEBOARD_DEFAULT_CONTEXT_NAME	= "default";
+
+	/**
 	 * Service property specifying the path of an
 	 * {@link org.osgi.service.http.context.ServletContextHelper} service.
 	 * 
 	 * <p>
 	 * For {@link org.osgi.service.http.context.ServletContextHelper} services
 	 * this service property is required. Context services without this service
-	 * property must be ignored.
+	 * property are ignored.
 	 * 
 	 * <p>
 	 * This property defines a context path under which all whiteboard services
-	 * are registered. Having different contexts with different paths allows to
-	 * separate the URL space.
+	 * associated with this context are registered. Having different contexts
+	 * with different paths allows to separate the URL space.
 	 * 
 	 * <p>
 	 * For {@link org.osgi.service.http.context.ServletContextHelper} services,
 	 * the value of this service property must be of type {@code String}. The
-	 * path must start with a slash but not end with a slash. Contexts with an
-	 * invalid path are ignored.
+	 * value is either a slash for the root or it must start with a slash but
+	 * not end with a slash. Valid characters are defined in
+	 * rfc3986#section-3.3. Contexts with an invalid path are ignored.
 	 * 
 	 * @see #HTTP_WHITEBOARD_CONTEXT_NAME
 	 * @see #HTTP_WHITEBOARD_CONTEXT_SELECT
@@ -91,22 +90,27 @@ public final class HttpWhiteboardConstants {
 	public static final String	HTTP_WHITEBOARD_CONTEXT_PATH			= "osgi.http.whiteboard.context.path";
 
 	/**
-	 * Service property referencing the
+	 * Service property referencing a
 	 * {@link org.osgi.service.http.context.ServletContextHelper} service.
 	 * 
 	 * <p>
-	 * For servlet, listener, servlet filter, or resource servlet services, this
-	 * service property refers to the associated Servlet Context Helper service.
-	 * The value of this property either directly referencing a context name or
-	 * is a filter expression which is matched against the service registration
-	 * properties of the Servlet Context Helper. If this service property is not
-	 * specified, then the default context must be used. If there is no context
-	 * service matching, the servlet, listener, servlet filter, or resource
-	 * servlet service must be ignored.
-	 * 
+	 * For servlet, listener, servlet filter, or resource services, this service
+	 * property refers to the associated {@code ServletContextHelper} service.
+	 * The value of this property is a filter expression which is matched
+	 * against the service registration properties of the
+	 * {@code ServletContextHelper} service. If this service property is not
+	 * specified, the default context is used. If there is no context service
+	 * matching, the servlet, listener, servlet filter, or resource service is
+	 * ignored.
+	 * <p>
+	 * For example, if a whiteboard service wants to select a servlet context
+	 * helper with the name &quot;Admin&quot; the expression would be
+	 * &quot;(osgi.http.whiteboard.context.name=Admin)&quot;. Selecting all
+	 * contexts could be done with
+	 * &quot;(osgi.http.whiteboard.context.name=*)&quot;.
 	 * <p>
-	 * For servlet, listener, servlet filter, or resource servlet services, the
-	 * value of this service property must be of type {@code String}.
+	 * For servlet, listener, servlet filter, or resource services, the value of
+	 * this service property must be of type {@code String}.
 	 * 
 	 * @see #HTTP_WHITEBOARD_CONTEXT_NAME
 	 * @see #HTTP_WHITEBOARD_CONTEXT_PATH
@@ -126,11 +130,11 @@ public final class HttpWhiteboardConstants {
 	 * property to apply the filter to the servlet.
 	 * 
 	 * <p>
-	 * Servlet names must be unique among all servlet services associated with
-	 * an {@link org.osgi.service.http.context.ServletContextHelper}. If
+	 * Servlet names must be unique among all servlet services associated with a
+	 * single {@link org.osgi.service.http.context.ServletContextHelper}. If
 	 * multiple servlet services associated with the same HttpContext have the
-	 * same servlet name, then all but the highest ranked servlet service must
-	 * be ignored.
+	 * same servlet name, then all but the highest ranked servlet service are
+	 * ignored.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String}.
@@ -144,7 +148,7 @@ public final class HttpWhiteboardConstants {
 	 * <p>
 	 * The specified patterns are used to determine whether a request should be
 	 * mapped to the servlet. Servlet services without this service property or
-	 * {@link #HTTP_WHITEBOARD_SERVLET_ERROR_PAGE} must be ignored.
+	 * {@link #HTTP_WHITEBOARD_SERVLET_ERROR_PAGE} are ignored.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String},
@@ -160,8 +164,10 @@ public final class HttpWhiteboardConstants {
 	 * 
 	 * <p>
 	 * The service property values may be the name of a fully qualified
-	 * exception class or a three digit HTTP status code. Any value that is not
-	 * a three digit number is considered to be the name of a fully qualified
+	 * exception class, a three digit HTTP status code, the value "4xx" for all
+	 * error codes in the 400 rage, or the value "5xx" for all error codes in
+	 * the 500 rage. Any value that is not a three digit number, or one of the
+	 * two special values is considered to be the name of a fully qualified
 	 * exception class.
 	 * 
 	 * <p>
@@ -175,7 +181,7 @@ public final class HttpWhiteboardConstants {
 	 * asynchronous processing.
 	 * 
 	 * <p>
-	 * By default Servlet services do not support asynchronous processing.
+	 * By default servlet services do not support asynchronous processing.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code Boolean}.
@@ -196,11 +202,11 @@ public final class HttpWhiteboardConstants {
 	 * 
 	 * <p>
 	 * Servlet filter names must be unique among all servlet filter services
-	 * associated with an
+	 * associated with a single
 	 * {@link org.osgi.service.http.context.ServletContextHelper}. If multiple
-	 * servlet filter services associated with the same HttpContext have the
-	 * same servlet filter name, then all but the highest ranked servlet filter
-	 * service must be ignored.
+	 * servlet filter services associated with the same context have the same
+	 * servlet filter name, then all but the highest ranked servlet filter
+	 * service are ignored.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String}.
@@ -215,7 +221,7 @@ public final class HttpWhiteboardConstants {
 	 * The specified patterns are used to determine whether a request should be
 	 * mapped to the servlet filter. Filter services without this service
 	 * property or the {@link #HTTP_WHITEBOARD_FILTER_SERVLET} or the
-	 * {@link #HTTP_WHITEBOARD_FILTER_REGEX} service property must be ignored.
+	 * {@link #HTTP_WHITEBOARD_FILTER_REGEX} service property are ignored.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String},
@@ -227,13 +233,13 @@ public final class HttpWhiteboardConstants {
 
 	/**
 	 * Service property specifying the {@link #HTTP_WHITEBOARD_SERVLET_NAME
-	 * servlet names} for a {@code Filter} service.
+	 * servlet names} for a servlet {@code Filter} service.
 	 * 
 	 * <p>
 	 * The specified names are used to determine the servlets whose requests
-	 * should be mapped to the servlet filter. Filter services without this
-	 * service property or the {@link #HTTP_WHITEBOARD_FILTER_PATTERN} or the
-	 * {@link #HTTP_WHITEBOARD_FILTER_REGEX} service property must be ignored.
+	 * should be mapped to the servlet filter. Servlet filter services without
+	 * this service property or the {@link #HTTP_WHITEBOARD_FILTER_PATTERN} or
+	 * the {@link #HTTP_WHITEBOARD_FILTER_REGEX} service propertyare ignored.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String},
@@ -242,16 +248,16 @@ public final class HttpWhiteboardConstants {
 	public static final String	HTTP_WHITEBOARD_FILTER_SERVLET			= "osgi.http.whiteboard.filter.servlet";
 
 	/**
-	 * Service property specifying the request mappings for a {@code Filter}
-	 * service.
+	 * Service property specifying the request mappings for a servlet
+	 * {@code Filter} service.
 	 * 
 	 * <p>
 	 * The specified regular expressions are used to determine whether a request
 	 * should be mapped to the servlet filter. The regular expressions must
-	 * follow the syntax defined in {@code java.util.regex.Pattern}. Filter
-	 * services without this service property or the
+	 * follow the syntax defined in {@code java.util.regex.Pattern}. Servlet
+	 * filter services without this service property or the
 	 * {@link #HTTP_WHITEBOARD_FILTER_SERVLET} or the
-	 * {@link #HTTP_WHITEBOARD_FILTER_PATTERN} service property must be ignored.
+	 * {@link #HTTP_WHITEBOARD_FILTER_PATTERN} service property are ignored.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String},
@@ -262,11 +268,12 @@ public final class HttpWhiteboardConstants {
 	public static final String	HTTP_WHITEBOARD_FILTER_REGEX			= "osgi.http.whiteboard.filter.regex";
 
 	/**
-	 * Service property specifying whether a {@code Filter} service supports
-	 * asynchronous processing.
+	 * Service property specifying whether a servlet {@code Filter} service
+	 * supports asynchronous processing.
 	 * 
 	 * <p>
-	 * By default Filters services do not support asynchronous processing.
+	 * By default servlet filters services do not support asynchronous
+	 * processing.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code Boolean}.
@@ -276,11 +283,12 @@ public final class HttpWhiteboardConstants {
 	public static final String	HTTP_WHITEBOARD_FILTER_ASYNC_SUPPORTED	= "osgi.http.whiteboard.filter.asyncSupported";
 
 	/**
-	 * Service property specifying the dispatcher handling of a {@code Filter}.
+	 * Service property specifying the dispatcher handling of a servlet
+	 * {@code Filter}.
 	 * 
 	 * <p>
-	 * By default Filters services are associated with client requests only (see
-	 * value {@link #DISPATCHER_REQUEST}).
+	 * By default servlet filter services are associated with client requests
+	 * only (see value {@link #DISPATCHER_REQUEST}).
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String},
@@ -295,7 +303,7 @@ public final class HttpWhiteboardConstants {
 
 	/**
 	 * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
-	 * property indicating the filter is applied to client requests.
+	 * property indicating the servlet filter is applied to client requests.
 	 * 
 	 * @see "Java Servlet Specification Version 3.0, Section 6.2.5 Filters and the RequestDispatcher"
 	 */
@@ -303,7 +311,7 @@ public final class HttpWhiteboardConstants {
 
 	/**
 	 * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
-	 * property indicating the filter is applied to include calls to the
+	 * property indicating the servlet filter is applied to include calls to the
 	 * dispatcher.
 	 * 
 	 * @see "Java Servlet Specification Version 3.0, Section 6.2.5 Filters and the RequestDispatcher"
@@ -312,7 +320,7 @@ public final class HttpWhiteboardConstants {
 
 	/**
 	 * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
-	 * property indicating the filter is applied to forward calls to the
+	 * property indicating the servlet filter is applied to forward calls to the
 	 * dispatcher.
 	 * 
 	 * @see "Java Servlet Specification Version 3.0, Section 6.2.5 Filters and the RequestDispatcher"
@@ -321,7 +329,8 @@ public final class HttpWhiteboardConstants {
 
 	/**
 	 * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
-	 * property indicating the filter is applied in the async context.
+	 * property indicating the servlet filter is applied in the asynchronous
+	 * context.
 	 * 
 	 * @see "Java Servlet Specification Version 3.0, Section 6.2.5 Filters and the RequestDispatcher"
 	 */
@@ -329,42 +338,67 @@ public final class HttpWhiteboardConstants {
 
 	/**
 	 * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
-	 * property indicating the filter is applied when an error page is called.
+	 * property indicating the servlet filter is applied when an error page is
+	 * called.
 	 * 
 	 * @see "Java Servlet Specification Version 3.0, Section 6.2.5 Filters and the RequestDispatcher"
 	 */
 	public static final String	DISPATCHER_ERROR						= "ERROR";
 
 	/**
-	 * Service property specifying the resource entry prefix for a
-	 * {@link javax.servlet.Servlet} servlet service.
+	 * Service property specifying the request mappings for resources.
+	 * 
+	 * <p>
+	 * The specified patterns are used to determine whether a request should be
+	 * mapped to resources. Resource services without this service property are
+	 * ignored.
+	 * 
+	 * <p>
+	 * The value of this service property must be of type {@code String},
+	 * {@code String[]}, or {@code Collection<String>}.
+	 * 
+	 * @see "Java Servlet Specification Version 3.0, Section 12.2 Specification of Mappings"
+	 * @see #HTTP_WHITEBOARD_RESOURCE_PREFIX
+	 */
+	public static final String	HTTP_WHITEBOARD_RESOURCE_PATTERN		= "osgi.http.whiteboard.resource.pattern";
+
+	/**
+	 * Service property specifying the resource entry prefix for a resource
+	 * service.
 	 * 
 	 * <p>
-	 * If a servlet service is registerd with this property, it is marked as a
-	 * resource serving servlet serving bundle resources.
+	 * If a resource service is registered with this property, requests are
+	 * served with bundle resources.
 	 * 
 	 * <p>
 	 * This prefix is used to map a requested resource to the bundle's entries.
-	 * TODO do we distinguish between "/xyz" and "xyz"?
+	 * The value must not end with slash (&quot;/&quot;) with the exception that
+	 * a name of the form &quot;/&quot; is used to denote the root of the
+	 * bundle. See the specification text for details on how HTTP requests are
+	 * mapped.
+	 *
 	 * <p>
-	 * The value of this service property must be of type {@code String}.
+	 * The value of this service property must be of type {@code String},
+	 * {@code String[]}, or {@code Collection<String>}.
+	 * 
+	 * @see #HTTP_WHITEBOARD_RESOURCE_PATTERN
 	 */
 	public static final String	HTTP_WHITEBOARD_RESOURCE_PREFIX			= "osgi.http.whiteboard.resource.prefix";
 
 	/**
 	 * Service property specifying the target filter to select the Http
-	 * Whiteboard Service runtime to process the service.
+	 * Whiteboard Implementation to process the service.
 	 * 
 	 * <p>
-	 * An Http Whiteboard Service implementation can define any number of
-	 * attributes which can be referenced by the target filter. The attributes
-	 * should always include the
+	 * An Http Whiteboard Implementation can define any number of attributes
+	 * which can be referenced by the target filter. The attributes should
+	 * always include the
 	 * {@link org.osgi.service.http.runtime.HttpServiceRuntimeConstants#HTTP_SERVICE_ENDPOINT_ATTRIBUTE
 	 * osgi.http.endpoint} attribute if the endpoint information is known.
 	 * 
 	 * <p>
 	 * If this service property is not specified, then all Http Whiteboard
-	 * Services can process the service.
+	 * Implementations can process the service.
 	 * 
 	 * <p>
 	 * The value of this service property must be of type {@code String} and be