FELIX-4060 : Implement HTTP Service Update (RFC-189)
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1655645 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/http/api/pom.xml b/http/api/pom.xml
index e9aa923..6ad2732 100644
--- a/http/api/pom.xml
+++ b/http/api/pom.xml
@@ -22,14 +22,14 @@
<parent>
<groupId>org.apache.felix</groupId>
<artifactId>org.apache.felix.http.parent</artifactId>
- <version>5-SNAPSHOT</version>
+ <version>6-SNAPSHOT</version>
<relativePath>../parent/pom.xml</relativePath>
</parent>
<name>Apache Felix Http Api</name>
<artifactId>org.apache.felix.http.api</artifactId>
<version>3.0.0-SNAPSHOT</version>
- <packaging>jar</packaging>
+ <packaging>bundle</packaging>
<scm>
<connection>scm:svn:http://svn.apache.org/repos/asf/felix/trunk/http/api</connection>
@@ -42,28 +42,57 @@
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
<configuration>
<instructions>
<Export-Package>
- org.osgi.service.http;version=${http.service.version},
+ org.osgi.service.http,
+ org.osgi.service.http.context,
+ org.osgi.service.http.runtime,
+ org.osgi.service.http.runtime.dto,
+ org.osgi.service.http.whiteboard,
org.apache.felix.http.api
</Export-Package>
<Import-Package>
org.osgi.service.http,
+ org.osgi.service.http.context,
+ org.osgi.service.http.runtime,
+ org.osgi.service.http.runtime.dto,
+ org.osgi.service.http.whiteboard,
javax.servlet.*;version="[2.3,4)",
*
</Import-Package>
</instructions>
</configuration>
</plugin>
+ <plugin>
+ <groupId>org.apache.rat</groupId>
+ <artifactId>apache-rat-plugin</artifactId>
+ <configuration>
+ <excludes>
+ <exclude>**/packageinfo</exclude>
+ </excludes>
+ </configuration>
+ </plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>javax.servlet</groupId>
- <artifactId>servlet-api</artifactId>
- <version>2.3</version>
+ <artifactId>javax.servlet-api</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>org.osgi.core</artifactId>
+ <version>6.0.0</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>org.osgi.annotation</artifactId>
+ <version>6.0.0</version>
<scope>provided</scope>
</dependency>
<!-- Explicitely use 5.0.0 to export version 1.2.1 of the http service api -->
diff --git a/http/api/src/main/java/org/apache/felix/http/api/ExtHttpService.java b/http/api/src/main/java/org/apache/felix/http/api/ExtHttpService.java
index 2d15411..6ec0a6a 100644
--- a/http/api/src/main/java/org/apache/felix/http/api/ExtHttpService.java
+++ b/http/api/src/main/java/org/apache/felix/http/api/ExtHttpService.java
@@ -16,20 +16,64 @@
*/
package org.apache.felix.http.api;
+import java.util.Dictionary;
+
import javax.servlet.Filter;
import javax.servlet.Servlet;
import javax.servlet.ServletException;
-import org.osgi.service.http.HttpService;
+
import org.osgi.service.http.HttpContext;
-import java.util.Dictionary;
+import org.osgi.service.http.HttpService;
-public interface ExtHttpService
- extends HttpService
+import aQute.bnd.annotation.ProviderType;
+
+/**
+ * The {@link ExtHttpService} allows other bundles in the OSGi environment to dynamically
+ * register resources, {@link Filter}s and {@link Servlet}s into the URI namespace of a
+ * HTTP service implementation. A bundle may later unregister its resources, {@link Filter}s
+ * or {@link Servlet}s.
+ *
+ * @see HttpContext
+ */
+@ProviderType
+public interface ExtHttpService extends HttpService
{
- public void registerFilter(Filter filter, String pattern, Dictionary initParams, int ranking, HttpContext context)
- throws ServletException;
-
- public void unregisterFilter(Filter filter);
+ /**
+ * Allows for programmatic registration of a {@link Filter} instance.
+ *
+ * @param filter the {@link Filter} to register, cannot be <code>null</code>;
+ * @param pattern the filter pattern to register the for, cannot be <code>null</code> and
+ * should be a valid regular expression;
+ * @param initParams the initialization parameters passed to the given filter during its
+ * initialization, can be <code>null</code> in case no additional parameters should
+ * be provided;
+ * @param ranking defines the order in which filters are called. A higher ranking causes
+ * the filter to be placed earlier in the filter chain;
+ * @param context the optional {@link HttpContext} to associate with this filter, can be
+ * <code>null</code> in case a default context should be associated.
+ * @throws ServletException in case the registration failed, for example because the
+ * initialization failed or due any other problem;
+ * @throws IllegalArgumentException in case the given filter was <code>null</code>.
+ */
+ void registerFilter(Filter filter, String pattern, Dictionary initParams, int ranking, HttpContext context) throws ServletException;
- public void unregisterServlet(Servlet servlet);
+ /**
+ * Unregisters a previously registered {@link Filter}.
+ * <p>
+ * In case the given filter is not registered, this method is essentially a no-op.
+ * </p>
+ *
+ * @param filter the {@link Filter} to unregister, cannot be <code>null</code>.
+ */
+ void unregisterFilter(Filter filter);
+
+ /**
+ * Unregisters a previously registered {@link Servlet}.
+ * <p>
+ * In case the given servlet is not registered, this method is essentially a no-op.
+ * </p>
+ *
+ * @param servlet the {@link Servlet} to unregister, cannot be <code>null</code>.
+ */
+ void unregisterServlet(Servlet servlet);
}
diff --git a/http/api/src/main/java/org/apache/felix/http/api/package-info.java b/http/api/src/main/java/org/apache/felix/http/api/package-info.java
index ac502ad..741924d 100644
--- a/http/api/src/main/java/org/apache/felix/http/api/package-info.java
+++ b/http/api/src/main/java/org/apache/felix/http/api/package-info.java
@@ -17,7 +17,7 @@
* under the License.
*/
-@Version("2.0.4")
+@Version("2.0.6")
package org.apache.felix.http.api;
import aQute.bnd.annotation.Version;
diff --git a/http/api/src/main/java/org/osgi/service/http/context/ServletContextHelper.java b/http/api/src/main/java/org/osgi/service/http/context/ServletContextHelper.java
new file mode 100644
index 0000000..08c4a0d
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/context/ServletContextHelper.java
@@ -0,0 +1,308 @@
+/*
+ * Copyright (c) OSGi Alliance (2000, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.context;
+
+import java.io.IOException;
+import java.net.URL;
+import java.util.Enumeration;
+import java.util.HashSet;
+import java.util.Set;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import org.osgi.annotation.versioning.ConsumerType;
+import org.osgi.framework.Bundle;
+
+/**
+ * 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>
+ * 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, each duplicate context path is searched by service ranking order according to
+ * {@link org.osgi.framework.ServiceReference#compareTo(Object)} until a matching servlet or
+ * resource is found.
+ *
+ * <p>
+ * Servlets, servlet filters, resources, and listeners services may be
+ * {@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>
+ * 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 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 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 Implementation needs to be granted
+ * {@code org.osgi.framework.AdminPermission[*,RESOURCE]}.</li>
+ * <li>{@code getRealPath} - This method returns {@code null}.</li>
+ * </ul>
+ *
+ * @ThreadSafe
+ * @author $Id$
+ * @see org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_NAME
+ * @see org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_PATH
+ */
+@ConsumerType
+public abstract class ServletContextHelper {
+ /**
+ * {@code HttpServletRequest} attribute specifying the name of the
+ * authenticated user. The value of the attribute can be retrieved by
+ * {@code HttpServletRequest.getRemoteUser}. This attribute name is
+ * {@code org.osgi.service.http.authentication.remote.user}.
+ */
+ public static final String REMOTE_USER = "org.osgi.service.http.authentication.remote.user";
+ /**
+ * {@code HttpServletRequest} attribute specifying the scheme used in
+ * authentication. The value of the attribute can be retrieved by
+ * {@code HttpServletRequest.getAuthType}. This attribute name is
+ * {@code org.osgi.service.http.authentication.type}.
+ */
+ public static final String AUTHENTICATION_TYPE = "org.osgi.service.http.authentication.type";
+ /**
+ * {@code HttpServletRequest} attribute specifying the {@code Authorization}
+ * object obtained from the {@code org.osgi.service.useradmin.UserAdmin}
+ * service. The value of the attribute can be retrieved by
+ * {@code HttpServletRequest.getAttribute(HttpContext.AUTHORIZATION)}. This
+ * attribute name is {@code org.osgi.service.useradmin.authorization}.
+ */
+ public static final String AUTHORIZATION = "org.osgi.service.useradmin.authorization";
+
+ /** Bundle associated with this context. */
+ private final Bundle bundle;
+
+ /**
+ * Default constructor
+ */
+ public ServletContextHelper() {
+ // default constructor
+ this(null);
+ }
+
+ /**
+ * Construct a new context helper and set the bundle associated with this
+ * context.
+ *
+ * @param b The bundle
+ */
+ public ServletContextHelper(final Bundle b) {
+ this.bundle = b;
+ }
+
+ /**
+ * Handles security for the specified request.
+ *
+ * <p>
+ * 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
+ * the request is missing or not acceptable, then this method should set the
+ * WWW-Authenticate header in the response object, set the status in the
+ * response object to Unauthorized(401) and return {@code false}. See also
+ * RFC 2617: <i>HTTP Authentication: Basic and Digest Access Authentication
+ * </i> (available at http://www.ietf.org/rfc/rfc2617.txt).
+ *
+ * <p>
+ * If the request requires a secure connection and the {@code getScheme}
+ * method in the request does not return 'https' or some other acceptable
+ * secure protocol, then this method should set the status in the response
+ * object to Forbidden(403) and return {@code false}.
+ *
+ * <p>
+ * 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
+ * {@link #AUTHENTICATION_TYPE} request attribute to the type of
+ * authentication used, and the {@link #REMOTE_USER} request attribute to
+ * the remote user (request attributes are set using the
+ * {@code setAttribute} method on the request). If this method does not
+ * perform any authentication, it must not set these attributes.
+ *
+ * <p>
+ * If the authenticated user is also authorized to access certain resources,
+ * this method must set the {@link #AUTHORIZATION} request attribute to the
+ * {@code Authorization} object obtained from the
+ * {@code org.osgi.service.useradmin.UserAdmin} service.
+ *
+ * <p>
+ * The servlet responsible for servicing the specified request determines
+ * the authentication type and remote user by calling the
+ * {@code getAuthType} and {@code getRemoteUser} methods, respectively, on
+ * the request.
+ *
+ * @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
+ * 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 Implementation will terminate the request and
+ * close the socket.
+ */
+ public boolean handleSecurity(final HttpServletRequest request,
+ final HttpServletResponse response)
+ throws IOException {
+ return true;
+ }
+
+ /**
+ * Maps a resource name to a URL.
+ *
+ * <p>
+ * 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
+ * resource can be mapped to a file in the bundle's persistent storage area
+ * via {@code bundleContext.getDataFile(name).toURL()} or to a resource in
+ * the context's bundle via {@code getClass().getResource(name)}
+ *
+ * @param name The name of the requested resource.
+ * @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;
+ if (name != null && localBundle != null) {
+ if (name.startsWith("/")) {
+ name = name.substring(1);
+ }
+
+ return this.bundle.getEntry(name);
+ }
+ return null;
+ }
+
+ /**
+ * Maps a name to a MIME type.
+ *
+ * <p>
+ * 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
+ * {@code null} to indicate that the Http Service should determine
+ * the MIME type itself.
+ */
+ public String getMimeType(final String name) {
+ return null;
+ }
+
+ /**
+ * Returns a directory-like listing of all the paths to resources within the
+ * web application whose longest sub-path matches the supplied path
+ * argument.
+ *
+ * <p>
+ * Called by the Http Whiteboard Implementation to support the
+ * {@code ServletContext} method {@code getResourcePaths} for whiteboard
+ * services.
+ *
+ * @param path the partial path used to match the resources, which must
+ * start with a /
+ * @return a Set containing the directory listing, or null if there are no
+ * resources in the web application whose path begins with the
+ * supplied path.
+ */
+ public Set<String> getResourcePaths(final String path) {
+ final Bundle localBundle = this.bundle;
+ if (path != null && localBundle != null) {
+ final Enumeration<URL> e = localBundle.findEntries(path, null, false);
+ if (e != null) {
+ final Set<String> result = new HashSet<String>();
+ while (e.hasMoreElements()) {
+ result.add(e.nextElement().getPath());
+ }
+ return result;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * Gets the real path corresponding to the given virtual path.
+ *
+ * <p>
+ * Called by the Http Whiteboard Implementation to support the
+ * {@code ServletContext} method {@code getRealPath} for whiteboard
+ * services.
+ *
+ * @param path the virtual path to be translated to a real path
+ * @return the real path, or null if the translation cannot be performed
+ */
+ public String getRealPath(final String path) {
+ return null;
+ }
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/context/package-info.java b/http/api/src/main/java/org/osgi/service/http/context/package-info.java
new file mode 100644
index 0000000..906ef61
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/context/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Http Service Context Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest. This package has two types of
+ * users: the consumers that use the API in this package and the providers that
+ * implement the API in this package.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.context; version="[1.0,2.0)"}
+ * <p>
+ * Example import for providers implementing the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.context; version="[1.0,1.1)"}
+ *
+ * @author $Id$
+ */
+
+@Version("1.0")
+package org.osgi.service.http.context;
+
+import org.osgi.annotation.versioning.Version;
+
diff --git a/http/api/src/main/java/org/osgi/service/http/context/packageinfo b/http/api/src/main/java/org/osgi/service/http/context/packageinfo
new file mode 100644
index 0000000..7c8de03
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/context/packageinfo
@@ -0,0 +1 @@
+version 1.0
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/HttpServiceRuntime.java b/http/api/src/main/java/org/osgi/service/http/runtime/HttpServiceRuntime.java
new file mode 100644
index 0000000..d854f83
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/HttpServiceRuntime.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime;
+
+import org.osgi.annotation.versioning.ProviderType;
+import org.osgi.service.http.runtime.dto.RequestInfoDTO;
+import org.osgi.service.http.runtime.dto.RuntimeDTO;
+
+/**
+ * The {@code HttpServiceRuntime} service represents the runtime information of
+ * a Http (Whiteboard) Implementation.
+ *
+ * <p>
+ * It provides access to DTOs representing the current state of the service.
+ * <p>
+ * The {@code HttpServiceRuntime} service must at least be registered with the
+ * {@link HttpServiceRuntimeConstants#HTTP_SERVICE_ENDPOINT_ATTRIBUTE}
+ * attribute.
+ *
+ * @ThreadSafe
+ * @author $Id$
+ */
+@ProviderType
+public interface HttpServiceRuntime {
+
+ /**
+ * Return the runtime DTO representing the current state.
+ * @return The runtime DTO
+ */
+ public RuntimeDTO getRuntimeDTO();
+
+ /**
+ * Return a request info DTO containing the services
+ * involved with processing a request for the given
+ * path.
+ * @param path The request path, relative to the root of the
+ * Http (Whiteboard) Service.
+ * @return A request info DTO
+ */
+ public RequestInfoDTO calculateRequestInfoDTO(String path);
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java b/http/api/src/main/java/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java
new file mode 100644
index 0000000..21f874c
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/HttpServiceRuntimeConstants.java
@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime;
+
+
+/**
+ * Defines standard names for Http Runtime Service constants.
+ *
+ * @author $Id$
+ */
+public final class HttpServiceRuntimeConstants {
+ private HttpServiceRuntimeConstants() {
+ // non-instantiable
+ }
+
+ /**
+ * 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.
+ * <p>
+ * An Http Service Runtime can be listening on multiple endpoints.
+ *
+ * <p>
+ * The value of this attribute must be of type {@code String},
+ * {@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/http/api/src/main/java/org/osgi/service/http/runtime/dto/BaseServletDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/BaseServletDTO.java
new file mode 100644
index 0000000..1bca590
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/BaseServletDTO.java
@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import java.util.Map;
+import org.osgi.dto.DTO;
+
+/**
+ * Represents common information about a {@code javax.servlet.Servlet} service.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public abstract class BaseServletDTO extends DTO {
+ /**
+ * The name of the servlet. This value is never {@code null}.
+ */
+ public String name;
+
+ /**
+ * The information string from the servlet.
+ * <p>
+ * This is the value returned by the {@code Servlet.getServletInfo()}
+ * method.
+ */
+ public String servletInfo;
+
+ /**
+ * Specifies whether the servlet supports asynchronous processing.
+ */
+ 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. If the service has no initialization
+ * parameters, the map is empty.
+ */
+ public Map<String, String> initParams;
+
+ /**
+ * 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 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/http/api/src/main/java/org/osgi/service/http/runtime/dto/DTOConstants.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/DTOConstants.java
new file mode 100644
index 0000000..6994275
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/DTOConstants.java
@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * Defines standard constants for the DTOs.
+ */
+public final class DTOConstants {
+ private DTOConstants() {
+ // non-instantiable
+ }
+
+ /**
+ * Failure reason is unknown
+ * <p>
+ * The value of {@code FAILURE_REASON_UNKNOWN} is 0.
+ */
+ public static final int FAILURE_REASON_UNKNOWN = 0;
+
+ /**
+ * 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 {@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.
+ */
+ public static final int FAILURE_REASON_SERVLET_CONTEXT_FAILURE = 2;
+
+ /**
+ * Service is shadowed by another service, e.g. a service with the same
+ * registration properties but a higher service ranking.
+ * <p>
+ * The value of {@code FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE} is 3.
+ */
+ public static final int FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE = 3;
+
+ /**
+ * An exception occurred during initializing of the service. This reason can
+ * only happen for servlets and servlet filters.
+ * <p>
+ * The value of {@code FAILURE_REASON_EXCEPTION_ON_INIT} is 4.
+ */
+ public static final int FAILURE_REASON_EXCEPTION_ON_INIT = 4;
+
+ /**
+ * 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.
+ */
+ public static final int FAILURE_REASON_SERVICE_NOT_GETTABLE = 5;
+
+ /**
+ * 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.
+ */
+ public static final int FAILURE_REASON_VALIDATION_FAILED = 6;
+
+ /**
+ * The service is not registered as a prototype scoped service and is
+ * already used with one servlet context and therefore can't be used with
+ * another servlet context.
+ * <p>
+ * The value of {@code FAILURE_REASON_SERVICE_ALREAY_USED} is 7.
+ */
+ public static final int FAILURE_REASON_SERVICE_ALREAY_USED = 7;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/ErrorPageDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ErrorPageDTO.java
new file mode 100644
index 0000000..80437fb
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ErrorPageDTO.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * Represents a {@code javax.servlet.Servlet} for handling errors and currently
+ * being used by a servlet context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class ErrorPageDTO extends BaseServletDTO {
+ /**
+ * The exceptions the error page is used for. This array might be
+ * empty.
+ */
+ public String[] exceptions;
+
+ /**
+ * The error codes the error page is used for. This array might be
+ * empty.
+ */
+ public long[] errorCodes;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java
new file mode 100644
index 0000000..ac6a6c0
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedErrorPageDTO.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * Represents a {@code javax.servlet.Servlet} service registered as an error
+ * 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 {@code ServletContextHelper}.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class FailedErrorPageDTO extends ErrorPageDTO {
+
+ /**
+ * The reason why the servlet represented by this DTO is not used.
+ *
+ * @see DTOConstants#FAILURE_REASON_UNKNOWN
+ * @see DTOConstants#FAILURE_REASON_EXCEPTION_ON_INIT
+ * @see DTOConstants#FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING
+ * @see DTOConstants#FAILURE_REASON_SERVICE_NOT_GETTABLE
+ * @see DTOConstants#FAILURE_REASON_SERVLET_CONTEXT_FAILURE
+ * @see DTOConstants#FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE
+ */
+ public int failureReason;
+
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedFilterDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedFilterDTO.java
new file mode 100644
index 0000000..e1016e9
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedFilterDTO.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * 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
+ * does not point to an existing servlet context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class FailedFilterDTO extends FilterDTO {
+
+ /**
+ * 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
+ * @see DTOConstants#FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING
+ * @see DTOConstants#FAILURE_REASON_SERVICE_NOT_GETTABLE
+ * @see DTOConstants#FAILURE_REASON_SERVLET_CONTEXT_FAILURE
+ * @see DTOConstants#FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE
+ */
+ public int failureReason;
+
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedListenerDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedListenerDTO.java
new file mode 100644
index 0000000..5e2130c
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedListenerDTO.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * 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}
+ * and does not point to an existing servlet context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class FailedListenerDTO extends ListenerDTO {
+
+ /**
+ * The reason why the listener represented by this DTO is not used.
+ *
+ * @see DTOConstants#FAILURE_REASON_UNKNOWN
+ * @see DTOConstants#FAILURE_REASON_EXCEPTION_ON_INIT
+ * @see DTOConstants#FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING
+ * @see DTOConstants#FAILURE_REASON_SERVICE_NOT_GETTABLE
+ * @see DTOConstants#FAILURE_REASON_SERVLET_CONTEXT_FAILURE
+ * @see DTOConstants#FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE
+ */
+ public int failureReason;
+
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedResourceDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedResourceDTO.java
new file mode 100644
index 0000000..2f8ab09
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedResourceDTO.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * Represents a resource definition which is currently not being used by a
+ * servlet context due to a problem.
+ * <p>
+ * 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.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class FailedResourceDTO extends ResourceDTO {
+
+ /**
+ * The reason why the resource represented by this DTO is not used.
+ *
+ * @see DTOConstants#FAILURE_REASON_UNKNOWN
+ * @see DTOConstants#FAILURE_REASON_EXCEPTION_ON_INIT
+ * @see DTOConstants#FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING
+ * @see DTOConstants#FAILURE_REASON_SERVICE_NOT_GETTABLE
+ * @see DTOConstants#FAILURE_REASON_SERVLET_CONTEXT_FAILURE
+ * @see DTOConstants#FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE
+ */
+ public int failureReason;
+
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java
new file mode 100644
index 0000000..40beb08
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedServletContextDTO.java
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * Represents a servlet context that is currently not used due to some problem.
+ *
+ * The following fields return an empty array for a
+ * {@code FailedServletContextDTO}:
+ * <ul>
+ * <li>{@link ServletContextDTO#servletDTOs}</li>
+ * <li>{@link ServletContextDTO#resourceDTOs}</li>
+ * <li>{@link ServletContextDTO#filterDTOs}</li>
+ * <li>{@link ServletContextDTO#errorPageDTOs}</li>
+ * <li>{@link ServletContextDTO#listenerDTOs}</li>
+ * </ul>
+ * <p>
+ * The method {@link ServletContextDTO#attributes} returns an empty map for a
+ * {@code FailedServletContextDTO}.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class FailedServletContextDTO extends ServletContextDTO {
+
+ /**
+ * The reason why the servlet context represented by this DTO is not used.
+ *
+ * @see DTOConstants#FAILURE_REASON_UNKNOWN
+ * @see DTOConstants#FAILURE_REASON_EXCEPTION_ON_INIT
+ * @see DTOConstants#FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING
+ * @see DTOConstants#FAILURE_REASON_SERVICE_NOT_GETTABLE
+ * @see DTOConstants#FAILURE_REASON_SERVLET_CONTEXT_FAILURE
+ * @see DTOConstants#FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE
+ */
+ public int failureReason;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedServletDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedServletDTO.java
new file mode 100644
index 0000000..7fa7499
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FailedServletDTO.java
@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+/**
+ * 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}
+ * and does not point to an existing servlet context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class FailedServletDTO extends ServletDTO {
+
+ /**
+ * The reason why the servlet represented by this DTO is not used.
+ *
+ * @see DTOConstants#FAILURE_REASON_UNKNOWN
+ * @see DTOConstants#FAILURE_REASON_EXCEPTION_ON_INIT
+ * @see DTOConstants#FAILURE_REASON_NO_SERVLET_CONTEXT_MATCHING
+ * @see DTOConstants#FAILURE_REASON_SERVICE_NOT_GETTABLE
+ * @see DTOConstants#FAILURE_REASON_SERVLET_CONTEXT_FAILURE
+ * @see DTOConstants#FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE
+ */
+ public int failureReason;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/FilterDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FilterDTO.java
new file mode 100644
index 0000000..d9df0a9
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/FilterDTO.java
@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import java.util.Map;
+import org.osgi.dto.DTO;
+
+/**
+ * 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. This field is never {@code null}.
+ */
+ public String name;
+
+ /**
+ * The request mappings for the servlet filter.
+ *
+ * <p>
+ * The specified patterns are used to determine whether a request is mapped
+ * to the servlet filter. This array might be empty.
+ */
+ public String[] patterns;
+
+ /**
+ * 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. This array might be empty.
+ */
+ public String[] servletNames;
+
+ /**
+ * The request mappings for the servlet filter.
+ *
+ * <p>
+ * The specified regular expressions are used to determine whether a request
+ * is mapped to the servlet filter. This array might be empty.
+ */
+ public String[] regexs;
+
+ /**
+ * Specifies whether the servlet filter supports asynchronous processing.
+ */
+ public boolean asyncSupported;
+
+ /**
+ * The dispatcher associations for the servlet filter.
+ *
+ * <p>
+ * The specified names are used to determine in what occasions the servlet
+ * filter is called. This array is never {@code null}.
+ */
+ public String[] dispatcher;
+
+ /**
+ * 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 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 servlet context for the servlet filter represented
+ * by this DTO.
+ */
+ public long servletContextId;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/ListenerDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ListenerDTO.java
new file mode 100644
index 0000000..6122537
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ListenerDTO.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import org.osgi.dto.DTO;
+
+/**
+ * Represents a listener currently being used by a servlet context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class ListenerDTO extends DTO {
+
+ /**
+ * 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 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.
+ */
+ public long serviceId;
+
+ /**
+ * The service id of the servlet context for the listener represented by
+ * this DTO.
+ */
+ public long servletContextId;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/RequestInfoDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/RequestInfoDTO.java
new file mode 100644
index 0000000..bea86ce
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/RequestInfoDTO.java
@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import org.osgi.dto.DTO;
+
+/**
+ * Represents the services used to process a specific request.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class RequestInfoDTO extends DTO {
+ /**
+ * The path of the request relative to the root.
+ */
+ public String path;
+
+ /**
+ * The service id of the servlet context processing the request represented
+ * by this DTO.
+ */
+ public long servletContextId;
+
+ /**
+ * 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
+ * {@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
+ * {@code null}.
+ */
+ public ResourceDTO resourceDTO;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/ResourceDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ResourceDTO.java
new file mode 100644
index 0000000..9bf52d5
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ResourceDTO.java
@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import org.osgi.dto.DTO;
+
+/**
+ * Represents a resource definition currently being used by a servlet context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+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. This value is never {@code null}.
+ */
+ public String[] patterns;
+
+ /**
+ * The prefix of the resource.
+ */
+ public String prefix;
+
+ /**
+ * 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 servlet context for the resource represented by
+ * this DTO.
+ */
+ public long servletContextId;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/RuntimeDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/RuntimeDTO.java
new file mode 100644
index 0000000..6facc36
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/RuntimeDTO.java
@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import java.util.Map;
+import org.osgi.dto.DTO;
+
+/**
+ * Represents the state of a Http Service Runtime.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+public class RuntimeDTO extends DTO {
+
+ /**
+ * 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 javax.servlet.ServletContext} objects.
+ */
+ public ServletContextDTO[] servletContextDTOs;
+
+ /**
+ * Returns the representations of the {@code javax.servlet.ServletContext} objects
+ * currently not used by the Http service runtime due to some problem.
+ * The returned array may be empty.
+ */
+ public FailedServletContextDTO[] failedServletContextDTOs;
+
+ /**
+ * 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.
+ */
+ public FailedResourceDTO[] failedResourceDTOs;
+
+ /**
+ * 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} 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.
+ */
+ public FailedListenerDTO[] failedListenerDTOs;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/ServletContextDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ServletContextDTO.java
new file mode 100644
index 0000000..668a57a
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ServletContextDTO.java
@@ -0,0 +1,137 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+import java.util.Map;
+import org.osgi.dto.DTO;
+
+/**
+ * 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
+ * @author $Id$
+ */
+public class ServletContextDTO extends DTO {
+ /**
+ * The name of the servlet context.
+ *
+ * The name of the corresponding
+ * {@link org.osgi.service.http.context.ServletContextHelper}.
+ */
+ public String name;
+
+ /**
+ * The context name of the servlet context.
+ *
+ * <p>
+ * This is the value returned by the
+ * {@code ServletContext.getServletContextName()} method.
+ */
+ public String contextName;
+
+ /**
+ * The servlet context path.
+ *
+ * This is the value returned by the {@code ServletContext.getContextPath()}
+ * method.
+ */
+ 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. If the context
+ * has no initialization parameters, this map is empty.
+ */
+ public Map<String, String> initParams;
+
+ /**
+ * The servlet context attributes.
+ *
+ * <p>
+ * 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 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;
+
+ /**
+ * Returns the representations of the {@code Servlet} services associated
+ * with this context.
+ *
+ * The representations of the {@code Servlet} services associated with this
+ * context. The returned array may be empty if this context is currently not
+ * associated with any {@code Servlet} services.
+ */
+ public ServletDTO[] servletDTOs;
+
+ /**
+ * Returns the representations of the resource services associated with this
+ * context.
+ *
+ * The representations of the resource services associated with this
+ * context. The returned array may be empty if this context is currently not
+ * associated with any resource services.
+ */
+ public ResourceDTO[] resourceDTOs;
+
+ /**
+ * Returns the representations of the servlet {@code Filter} services
+ * associated with this context.
+ *
+ * The representations of the servlet {@code Filter} services associated
+ * with this context. The returned array may be empty if this context is
+ * currently not associated with any servlet {@code Filter} services.
+ */
+ public FilterDTO[] filterDTOs;
+
+ /**
+ * Returns the representations of the error page {@code Servlet} services
+ * associated with this context.
+ *
+ * The representations of the error page {@code Servlet} services associated
+ * with this context. The returned array may be empty if this context is
+ * currently not associated with any error pages.
+ */
+ public ErrorPageDTO[] errorPageDTOs;
+
+ /**
+ * Returns the representations of the listener services associated with this
+ * context.
+ *
+ * The representations of the listener services associated with this
+ * context. The returned array may be empty if this context is currently not
+ * associated with any listener services.
+ */
+ public ListenerDTO[] listenerDTOs;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/ServletDTO.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ServletDTO.java
new file mode 100644
index 0000000..4b078f3
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/ServletDTO.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.runtime.dto;
+
+
+/**
+ * Represents a {@code javax.servlet.Servlet} currently being used by a servlet
+ * context.
+ *
+ * @NotThreadSafe
+ * @author $Id$
+ */
+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. This array is never empty.
+ */
+ public String[] patterns;
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/package-info.java b/http/api/src/main/java/org/osgi/service/http/runtime/dto/package-info.java
new file mode 100644
index 0000000..77c57c1
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Http Service Runtime DTO Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest. This package has two types of
+ * users: the consumers that use the API in this package and the providers that
+ * implement the API in this package.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.runtime.dto; version="[1.0,2.0)"}
+ * <p>
+ * Example import for providers implementing the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.runtime.dto; version="[1.0,1.1)"}
+ *
+ * @author $Id$
+ */
+
+@Version("1.0")
+package org.osgi.service.http.runtime.dto;
+
+import org.osgi.annotation.versioning.Version;
+
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/dto/packageinfo b/http/api/src/main/java/org/osgi/service/http/runtime/dto/packageinfo
new file mode 100644
index 0000000..7c8de03
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/dto/packageinfo
@@ -0,0 +1 @@
+version 1.0
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/package-info.java b/http/api/src/main/java/org/osgi/service/http/runtime/package-info.java
new file mode 100644
index 0000000..80f86d1
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Http Service Runtime Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest. This package has two types of
+ * users: the consumers that use the API in this package and the providers that
+ * implement the API in this package.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.runtime; version="[1.0,2.0)"}
+ * <p>
+ * Example import for providers implementing the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.runtime; version="[1.0,1.1)"}
+ *
+ * @author $Id$
+ */
+
+@Version("1.0")
+package org.osgi.service.http.runtime;
+
+import org.osgi.annotation.versioning.Version;
+
diff --git a/http/api/src/main/java/org/osgi/service/http/runtime/packageinfo b/http/api/src/main/java/org/osgi/service/http/runtime/packageinfo
new file mode 100644
index 0000000..7c8de03
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/runtime/packageinfo
@@ -0,0 +1 @@
+version 1.0
diff --git a/http/api/src/main/java/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java b/http/api/src/main/java/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java
new file mode 100644
index 0000000..8f2496a
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/whiteboard/HttpWhiteboardConstants.java
@@ -0,0 +1,405 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.http.whiteboard;
+
+import org.osgi.framework.Filter;
+import org.osgi.service.http.context.ServletContextHelper;
+import org.osgi.service.http.runtime.HttpServiceRuntimeConstants;
+
+/**
+ * Defines standard constants for the whiteboard services.
+ *
+ * @author $Id$
+ */
+public final class HttpWhiteboardConstants {
+ private HttpWhiteboardConstants() {
+ // non-instantiable
+ }
+
+ /**
+ * Service property specifying the name of an {@link ServletContextHelper}
+ * service.
+ *
+ * <p>
+ * For {@link ServletContextHelper} services, this service property must be
+ * specified. Context services without this service property are ignored.
+ *
+ * <p>
+ * Servlet, listener, servlet filter, and resource services might refer to a
+ * specific {@link ServletContextHelper} service referencing the name with
+ * the {@link #HTTP_WHITEBOARD_CONTEXT_SELECT} property.
+ *
+ * <p>
+ * For {@link ServletContextHelper} services, 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_DEFAULT_CONTEXT_NAME
+ */
+ public static final String HTTP_WHITEBOARD_CONTEXT_NAME = "osgi.http.whiteboard.context.name";
+
+ /**
+ * The name of the default {@link 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 ServletContextHelper}
+ * service.
+ *
+ * <p>
+ * For {@link ServletContextHelper} services this service property is
+ * required. Context services without this service property are ignored.
+ *
+ * <p>
+ * This property defines a context path under which all whiteboard services
+ * associated with this context are registered. Having different contexts
+ * with different paths allows to separate the URL space.
+ *
+ * <p>
+ * For {@link ServletContextHelper} services, the value of this service
+ * property must be of type {@code String}. The 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
+ */
+ public static final String HTTP_WHITEBOARD_CONTEXT_PATH = "osgi.http.whiteboard.context.path";
+
+ /**
+ * Service property referencing a {@link ServletContextHelper} service.
+ *
+ * <p>
+ * 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 "Admin" the expression would be
+ * "(osgi.http.whiteboard.context.name=Admin)". Selecting all
+ * contexts could be done with
+ * "(osgi.http.whiteboard.context.name=*)".
+ * <p>
+ * 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
+ */
+ public static final String HTTP_WHITEBOARD_CONTEXT_SELECT = "osgi.http.whiteboard.context.select";
+
+ /**
+ * Service property specifying the servlet name of a {@code Servlet}
+ * service.
+ *
+ * <p>
+ * This name is used as the value for the
+ * {@code ServletConfig.getServletName()} method. If this service property
+ * is not specified, the fully qualified name of the service object's class
+ * is used as the servlet name. Filter services may refer to servlets by
+ * this name in their {@link #HTTP_WHITEBOARD_FILTER_SERVLET} service
+ * property to apply the filter to the servlet.
+ *
+ * <p>
+ * Servlet names must be unique among all servlet services associated with a
+ * single {@link ServletContextHelper}. If multiple servlet services
+ * associated with the same HttpContext have the 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}.
+ */
+ public static final String HTTP_WHITEBOARD_SERVLET_NAME = "osgi.http.whiteboard.servlet.name";
+
+ /**
+ * Service property specifying the request mappings for a {@code Servlet}
+ * service.
+ *
+ * <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} 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"
+ */
+ public static final String HTTP_WHITEBOARD_SERVLET_PATTERN = "osgi.http.whiteboard.servlet.pattern";
+
+ /**
+ * Service property specifying whether a {@code Servlet} service acts as an
+ * error page.
+ *
+ * <p>
+ * The service property values may 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>
+ * The value of this service property must be of type {@code String},
+ * {@code String[]}, or {@code Collection<String>}.
+ */
+ public static final String HTTP_WHITEBOARD_SERVLET_ERROR_PAGE = "osgi.http.whiteboard.servlet.errorPage";
+
+ /**
+ * Service property specifying whether a {@code Servlet} service supports
+ * asynchronous processing.
+ *
+ * <p>
+ * By default servlet services do not support asynchronous processing.
+ *
+ * <p>
+ * The value of this service property must be of type {@code Boolean}.
+ *
+ * @see "Java Servlet Specification Version 3.0, Section 2.3.3.3 Asynchronous Processing"
+ */
+ public static final String HTTP_WHITEBOARD_SERVLET_ASYNC_SUPPORTED = "osgi.http.whiteboard.servlet.asyncSupported";
+
+ /**
+ * Service property specifying the servlet filter name of a {@code Filter}
+ * service.
+ *
+ * <p>
+ * This name is used as the value for the
+ * {@code FilterConfig.getFilterName()} method. If this service property is
+ * not specified, the fully qualified name of the service object's class is
+ * used as the servlet filter name.
+ *
+ * <p>
+ * Servlet filter names must be unique among all servlet filter services
+ * associated with a single {@link ServletContextHelper}. If multiple
+ * 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}.
+ */
+ public static final String HTTP_WHITEBOARD_FILTER_NAME = "osgi.http.whiteboard.filter.name";
+
+ /**
+ * Service property specifying the request mappings for a {@code Filter}
+ * service.
+ *
+ * <p>
+ * 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 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"
+ */
+ public static final String HTTP_WHITEBOARD_FILTER_PATTERN = "osgi.http.whiteboard.filter.pattern";
+
+ /**
+ * Service property specifying the {@link #HTTP_WHITEBOARD_SERVLET_NAME
+ * 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. 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},
+ * {@code String[]}, or {@code Collection<String>}.
+ */
+ public static final String HTTP_WHITEBOARD_FILTER_SERVLET = "osgi.http.whiteboard.filter.servlet";
+
+ /**
+ * 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}. Servlet
+ * filter services without this service property or the
+ * {@link #HTTP_WHITEBOARD_FILTER_SERVLET} or the
+ * {@link #HTTP_WHITEBOARD_FILTER_PATTERN} 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.util.regex.Pattern"
+ */
+ public static final String HTTP_WHITEBOARD_FILTER_REGEX = "osgi.http.whiteboard.filter.regex";
+
+ /**
+ * Service property specifying whether a servlet {@code Filter} service
+ * supports asynchronous processing.
+ *
+ * <p>
+ * By default servlet filters services do not support asynchronous
+ * processing.
+ *
+ * <p>
+ * The value of this service property must be of type {@code Boolean}.
+ *
+ * @see "Java Servlet Specification Version 3.0, Section 2.3.3.3 Asynchronous Processing"
+ */
+ public static final String HTTP_WHITEBOARD_FILTER_ASYNC_SUPPORTED = "osgi.http.whiteboard.filter.asyncSupported";
+
+ /**
+ * Service property specifying the dispatcher handling of a servlet
+ * {@code Filter}.
+ *
+ * <p>
+ * 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},
+ * {@code String[]}, or {@code Collection<String>}. Allowed values are
+ * {@link #DISPATCHER_ASYNC}, {@link #DISPATCHER_ERROR},
+ * {@link #DISPATCHER_FORWARD}, {@link #DISPATCHER_INCLUDE},
+ * {@link #DISPATCHER_REQUEST}.
+ *
+ * @see "Java Servlet Specification Version 3.0, Section 6.2.5 Filters and the RequestDispatcher"
+ */
+ public static final String HTTP_WHITEBOARD_FILTER_DISPATCHER = "osgi.http.whiteboard.filter.dispatcher";
+
+ /**
+ * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
+ * 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"
+ */
+ public static final String DISPATCHER_REQUEST = "REQUEST";
+
+ /**
+ * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
+ * 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"
+ */
+ public static final String DISPATCHER_INCLUDE = "INCLUDE";
+
+ /**
+ * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
+ * 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"
+ */
+ public static final String DISPATCHER_FORWARD = "FORWARD";
+
+ /**
+ * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
+ * 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"
+ */
+ public static final String DISPATCHER_ASYNC = "ASYNC";
+
+ /**
+ * Possible value for the {@link #HTTP_WHITEBOARD_FILTER_DISPATCHER}
+ * 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 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 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.
+ * The value must not end with slash ("/") with the exception that
+ * a name of the form "/" is used to denote the root of the
+ * bundle. See the specification text for details on how HTTP requests are
+ * mapped.
+ *
+ * <p>
+ * 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 Implementation to process the service.
+ *
+ * <p>
+ * 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 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
+ * Implementations can process the service.
+ *
+ * <p>
+ * The value of this service property must be of type {@code String} and be
+ * a valid {@link Filter filter string}.
+ */
+ public static final String HTTP_WHITEBOARD_TARGET = "osgi.http.whiteboard.target";
+}
diff --git a/http/api/src/main/java/org/osgi/service/http/whiteboard/package-info.java b/http/api/src/main/java/org/osgi/service/http/whiteboard/package-info.java
new file mode 100644
index 0000000..ed71ba3
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/whiteboard/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2014). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Http Service Whiteboard Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest. This package has two types of
+ * users: the consumers that use the API in this package and the providers that
+ * implement the API in this package.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.whiteboard; version="[1.0,2.0)"}
+ * <p>
+ * Example import for providers implementing the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.http.whiteboard; version="[1.0,1.1)"}
+ *
+ * @author $Id$
+ */
+
+@Version("1.0")
+package org.osgi.service.http.whiteboard;
+
+import org.osgi.annotation.versioning.Version;
+
diff --git a/http/api/src/main/java/org/osgi/service/http/whiteboard/packageinfo b/http/api/src/main/java/org/osgi/service/http/whiteboard/packageinfo
new file mode 100644
index 0000000..7c8de03
--- /dev/null
+++ b/http/api/src/main/java/org/osgi/service/http/whiteboard/packageinfo
@@ -0,0 +1 @@
+version 1.0