stbischof commented on code in PR #303:
URL: https://github.com/apache/felix-dev/pull/303#discussion_r1561368301
##########
http/README.md:
##########
@@ -58,48 +77,75 @@ of additional bundles to deploy [as described in the jetty
documentation](https:
The OSGi whiteboard implementation simplifies the task of registering
servlets, filters, resources, listeners, and servlet contexts. For a complete
introduction, please refer to the OSGi R7 Compendium or Enterprise
specification.
-For a short introduction: Such a whiteboard service can be registered by
exporting it as a service, making it no longer necessary to track and use the
`HttpService` directly. The
-whiteboard implementation detects all `javax.servlet.Servlet` and
`javax.servlet.Filter` services with the right service properties. Let us
illustrate the usage by registering a servlet:
+For a short introduction: Such a whiteboard service can be registered by
exporting it as a service, making it no longer necessary to track and use the
`HttpService` directly (or the `ExtHttpService` in legacy implementations, for
registering filters). The
+whiteboard implementation detects all `jakarta.servlet.Servlet` and
`jakarta.servlet.Filter` services with the right service properties. Let us
illustrate the usage by registering a servlet and a filter:
```java
public class Activator implements BundleActivator {
- private ServiceRegistration registration;
+ private ServiceRegistration<Servlet> servletRegistration;
+ private ServiceRegistration<Filter> filterRegistration;
public void start(BundleContext context) throws Exception {
- Hashtable props = new Hashtable();
- props.put("osgi.http.whiteboard.servlet.pattern", "/hello");
- props.put("servlet.init.message", "Hello World!");
+ Hashtable propsServlet = new Hashtable();
+
propsServlet.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_PATTERN,
"/hello");
+
propsServlet.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_ASYNC_SUPPORTED,
true);
+
propsServlet.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_INIT_PARAM_PREFIX
+ "message", "Hello World servlet!");
+
+ this.servletRegistration =
context.registerService(Servlet.class.getName(), new HelloWorldServlet(),
propsServlet);
+
+ Hashtable propsFilter = new Hashtable();
+ propsFilter.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_FILTER_REGEX,
".*");
+
propsFilter.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_FILTER_ASYNC_SUPPORTED,
true);
+
propsFilter.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_FILTER_INIT_PARAM_PREFIX
+ "message", "Hello World filter!");
- this.registration = context.registerService(Servlet.class.getName(),
new HelloWorldServlet(), props);
+ this.filterRegistration =
context.registerService(Filter.class.getName(), new HelloWorldFilter(),
propsFilter);
}
public void stop(BundleContext context) throws Exception {
- this.registration.unregister();
+ this.servletRegistration.unregister();
+ this.filterRegistration.unregister();
}
}
```
+An implementation note for when using the Felix HTTP Jetty 12 bundle: only
registering a filter without a servlet, will not work. Make sure that there is
a servlet registered (on the same path as the filter) when registering a
filter, even when that servlet is not hit eventually.
To ensure the HTTP whiteboard service picks up your servlet and filter
correctly, your service
registration *must* provide several service properties.
### Servlet service properties
+See full reference in the [OSGi
specification](https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.http.whiteboard.html#service.http.whiteboard-i21223311).
+The most important properties are:
+
* `osgi.http.whiteboard.servlet.pattern` - defines the servlet pattern to
register the servlet under, should be a path as defined in the Servlet
specification.
* `osgi.http.whiteboard.context.select` - Filter expression to select the
servlet context (optional).
+ * `osgi.http.whiteboard.servlet.asyncSupported` - Declares whether the
servlet supports the asynchronous operation mode. Allowed values are true and
false independent of case. Defaults to false. (optional)
+ * `osgi.http.whiteboard.servlet.multipart.enable` - Enables support for
multipart configuration on the servlet. Allowed values are true and false
independent of case. Defaults to false. (optional)
* `servlet.init.*` - these properties (sans the `servlet.init.` prefix) are
made available throught the `ServletConfig` object of your servlet. This allows
you to supply your servlet initialization parameters as you would normally do
in the web descriptor (web.xml).
### Filter service properties
+See full reference in the [OSGi
specification](https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.http.whiteboard.html#d0e121055).
+The most important properties are:
+
* `osgi.http.whiteboard.filter.regex` - The regular expression pattern to
register filter with.
* `osgi.http.whiteboard.context.select` - Filter expression to select the
servlet context (optional).
- * `service.ranking` - an integer value that allows you to specify where in
the filter chain the filter should be registered. Higher rankings will be
placed first in the chain, that is, filter chains are sorted in descending
order. If omitted, a ranking of zero (0) is used.
+ * `osgi.http.whiteboard.filter.pattern` - Apply this servlet filter to the
specified URL path patterns. The format of the patterns is specified in the
servlet specification.
+ * `osgi.http.whiteboard.filter.asyncSupported` - Declares whether the
servlet filter supports asynchronous operation mode. Allowed values are true
and false independent of case. Defaults to false. (optional)
* `filter.init.*` - these properties (sans the `filter.init.` prefix) are
made available throught the `FilterConfig` object of your filter. This allows
you to supply your filter initialization parameters as you would normally do in
the web descriptor (web.xml).
+The order of filters is no longer managed by the `service.ranking` property,
but by implementing the `compareTo` method.
+Multiple servlet filters can process the same servlet request/response. If
more than one Filter matches, they are processed in ranking order, as specified
in `ServiceReference.compareTo`. The servlet filter with the highest ranking is
processed first in the filter chain, while the servlet filter with the lowest
ranking is processed last, before the Servlet.service method is called. After
the servlet completes its service method the filter chain is unwound in reverse
order.
+
### ServletContextHelper service properties
+See full reference in the [OSGi
specification](https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.http.whiteboard.html#service.http.whiteboard.servletcontext).
Review Comment:
https://docs.osgi.org/specification/osgi.cmpn/8.1.0/
we should look to 8.1 release
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@felix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
