{"payload":{"allShortcutsEnabled":false,"path":"http","repo":{"id":242854622,"defaultBranch":"master","name":"felix-dev","ownerLogin":"apache","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2020-02-24T22:09:29.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/47359?v=4","public":true,"private":false,"isOrgOwned":true},"currentUser":null,"refInfo":{"name":"master","listCacheKey":"v0:1709104937.0","canEdit":false,"refType":"branch","currentOid":"f495351917b0d122138cd6ea70d6c4e61f475629"},"tree":{"items":[{"name":"base","path":"http/base","contentType":"directory"},{"name":"bridge","path":"http/bridge","contentType":"directory"},{"name":"inventoryprinter","path":"http/inventoryprinter","contentType":"directory"},{"name":"itest","path":"http/itest","contentType":"directory"},{"name":"jetty","path":"http/jetty","contentType":"directory"},{"name":"jetty12","path":"http/jetty12","contentType":"directory"},{"name":"proxy","path":"http/proxy","contentType":"directory"},{"name":"samples/whiteboard","path":"http/samples/whiteboard","contentType":"directory","hasSimplifiedPath":true},{"name":"servlet-api","path":"http/servlet-api","contentType":"directory"},{"name":"sslfilter","path":"http/sslfilter","contentType":"directory"},{"name":"webconsoleplugin","path":"http/webconsoleplugin","contentType":"directory"},{"name":"wrappers","path":"http/wrappers","contentType":"directory"},{"name":"LICENSE","path":"http/LICENSE","contentType":"file"},{"name":"README.md","path":"http/README.md","contentType":"file"},{"name":"pom.xml","path":"http/pom.xml","contentType":"file"}],"templateDirectorySuggestionUrl":null,"readme":{"displayName":"README.md","richText":"

Apache Felix HTTP Service

\n

This is an implementation of the HTTP Whiteboard Service as described in chapter 140 of the OSGi Compendium (R7) in combination with an implementation of the HTTP Service Specification as described in chapter 102 of the OSGi Compendium. The goal is to provide a standard and simplified way to register servlets, listeners, filters, and resources in a servlet container, to managed them in servlet contexts, and to associate them with URIs. Complete set of features:

\n\n

Installing

\n

The Apache Felix HTTP Service project includes several bundles.

\n\n

Note that as of version 3.x, the Servlet APIs are no longer packaged with the implementation bundles! If you are migrating from lower versions, be sure to add the\norg.apache.felix.http.servlet-api (or any other compatible Serlvet API bundle) to your\nclasspath and deployment!

\n

Installing additional bundles for the optional HTTP/2 support with jetty

\n

The jetty implementation uses the OSGi ServiceLoader mediator technique to find certain pluggable components that are required for HTTP/2 support. Your OSGi runtime must first have the bundles needed for OSGi ServiceLoader support deployed. Background information about the OSGi ServiceLoader integration is discussed here

\n

Deploying the following set of bundles would be one way to enable the ServiceLoader mediator support:

\n\n

Next, depending on your server environment you must choose only one of the following sets\nof additional bundles to deploy as described in the jetty documentation

\n
    \n
  1. \n

    For java 9 or later:

    \n
      \n
    • org.eclipse.jetty.alpn:alpn-api:1.1.3.v20160715
    • \n
    • org.eclipse.jetty:jetty-alpn-java-server:${jetty.version}
    • \n
    \n
  2. \n
  3. \n

    For java 8:

    \n
      \n
    • \n

      org.eclipse.jetty:jetty-alpn-openjdk8-server:${jetty.version}

      \n
    • \n
    • \n

      For java 8 versions earlier than 1.8.0_252 download and add -Xbootclasspath/p:/path_to_file_here/alpn-boot-8.1.13.v20181017.jar as an argument to the java process and then deploy the following bundle:

      \n
        \n
      • org.eclipse.jetty.osgi:jetty-osgi-alpn:${jetty.version}
      • \n
      \n
    • \n
    • \n

      For java 8 version 1.8.0_252 or later skip the bootclasspath argument and deploy the following bundle instead:

      \n
        \n
      • org.eclipse.jetty.alpn:alpn-api:1.1.3.v20160715
      • \n
      \n
    • \n
    \n
  4. \n
\n

Using the OSGi Http Whiteboard

\n

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.

\n

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\nwhiteboard 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:

\n
public class Activator implements BundleActivator {\n    private ServiceRegistration registration;\n\n    public void start(BundleContext context) throws Exception {\n        Hashtable props = new Hashtable();\n        props.put(\"osgi.http.whiteboard.servlet.pattern\", \"/hello\");\n        props.put(\"servlet.init.message\", \"Hello World!\");\n\n        this.registration = context.registerService(Servlet.class.getName(), new HelloWorldServlet(), props);\n    }\n\n    public void stop(BundleContext context) throws Exception {\n        this.registration.unregister();\n    }\n}
\n

To ensure the HTTP whiteboard service picks up your servlet and filter correctly, your service\nregistration must provide several service properties.

\n

Servlet service properties

\n\n

Filter service properties

\n\n

ServletContextHelper service properties

\n\n

Using the HttpService

\n

In general the Http Service is regarded legacy and the OSGi Http Whiteboard should be used instead. If you still want to use the Http Service, this is a brief introduction. The main components provided by the Apache Felix HTTP Service bundle are:

\n\n

Servlets created for the OSGi HTTP service don't need to have any reference to the OSGi specification (they only need to\nconform to the Servlet specification), like in the example:

\n
public class HelloWorld extends HttpServlet {\n    @Override\n    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {\n        resp.getWriter().write(\"Hello World\");\t\t\n    }\n}
\n

To register a servlet and map it to a URI, you need to retrieve the HttpService and call its registerServlet method.\nFor this example, a ServiceTracker is used to ensure that the registration occurs when a HttpService actually is\navailable, and a deregistration occurs when the HttpService becomes unavailable. Alternatively, you can use more\nhigh-level dependency management libraries, like Declarative Services, Felix Dependency Manager, or Felix HTTP\nwhiteboard service (see below).

\n
public class Activator implements BundleActivator {\n    private ServiceTracker httpTracker;\n\n    public void start(BundleContext context) throws Exception {\n        httpTracker = new ServiceTracker(context, HttpService.class.getName(), null) {\n          public void removedService(ServiceReference reference, Object service) {\n            // HTTP service is no longer available, unregister our servlet...\n            try {\n               ((HttpService) service).unregister(\"/hello\");\n            } catch (IllegalArgumentException exception) {\n               // Ignore; servlet registration probably failed earlier on...\n            }\n          }\n\n          public Object addingService(ServiceReference reference) {\n            // HTTP service is available, register our servlet...\n            HttpService httpService = (HttpService) this.context.getService(reference);\n            try {\n              httpService.registerServlet(\"/hello\", new HelloWorld(), null, null);\n            } catch (Exception exception) {\n              exception.printStackTrace();\n            }\n            return httpService;\n          }\n        };\n        // start tracking all HTTP services...\n        httpTracker.open();\n    }\n\n    public void stop(BundleContext context) throws Exception {\n        // stop tracking all HTTP services...\n        httpTracker.close();\n    }\n}
\n

In the same way, you can unregister a servlet (for instance, in the removedMethod method in the former example) by\ncalling the HttpService.unregister method.

\n

As you notice in the example above, the registerServlet method accepts four parameters:

\n\n

The servlet alias must begin with a slash and must not end with a slash. When a request is processed, the HTTP Service\nwill try to exact match the requested URI with a registered servlet. If not existent, it will remove the last '/' in the\nURI and everything that follows, and try to match the remaining part, and so on.

\n

An additional configuration Map can be optionally specified; if present, all the parameters contained will be copied in\nthe ServletContext object.

\n

Finally, an HttpContext object can be optionally specified to handle authentication, mime type and resource mapping. The\nHttpContext interface is quite simple:

\n
public interface HttpContext {\n    /** Returns the mime type of the specified resource */\n    String getMimeType(java.lang.String name);\n\n    /** Returns the URL to retrieve the specified resource */\n    URL getResource(java.lang.String name);\n\n    /** Manages security for the specified request */\n    boolean handleSecurity(HttpServletRequest request, HttpServletResponse response);\n}
\n

The use of a custom HttpContext is typical when you want to serve static contents with the HTTP Service. Let's first\nsee an example of resource registration without HttpContext:

\n
public class Activator implements BundleActivator {\n    private ServiceTracker httpTracker;\n\n    public void start(BundleContext context) throws Exception {\n        httpTracker = new ServiceTracker(context, HttpService.class.getName(), null) {\n          public void removedService(ServiceReference reference, Object service) {\n            // HTTP service is no longer available, unregister our resources...\n            try {\n               ((HttpService) service).unregister(\"/static\");\n            } catch (IllegalArgumentException exception) {\n               // Ignore; servlet registration probably failed earlier on...\n            }\n          }\n\n          public Object addingService(ServiceReference reference) {\n            // HTTP service is available, register our resources...\n            HttpService httpService = (HttpService) this.context.getService(reference);\n            try {\n              httpService.registerResources(\"/static\", \"/etc/www\", null);\n            } catch (Exception exception) {\n              exception.printStackTrace();\n            }\n            return httpService;\n          }\n      };\n      // start tracking all HTTP services...\n      httpTracker.open();\n    }\n\n    public void stop(BundleContext context) throws Exception {\n      // stop tracking all HTTP services...\n      httpTracker.close();\n    }\n}
\n

As a result of the httpService.registerResources(\"/static\", \"/etc/www\", null) code, all the files available under\n/etc/www will be exposed under /static (e.g. http://localhost:8080/static/001.jpg will render the\n/etc/www/001.jpg). However, the example above can be simplistic in practice; the HttpContext object is the solution\nto customize the resource handling.

\n

For instance, you can set the define more complex URI to file mappings overriding the HttpContext.getResource method,\nor the correct MIME type implementing the method HttpContext.getMimeType like in the example:

\n
//....\npublic String getMimeType(String file) {\n    if (file.endsWith(\".jpg\") {\n        return \"image/jpeg\";  \n    } else if (file.endsWith(\".png\")) {\n        return \"image/png\";  \n    } else {  \n        return \"text/html\";  \n    }\n}\n//....
\n

If you implement a customised HttpContext object, don't forget to specify it as third parameter of the registerResources method invocation:

\n
// ....\npublic Object addingService(ServiceReference reference) {\n    // HTTP service is available, register our resources...\n    HttpService httpService = (HttpService) this.context.getService(reference);\n    try {\n        // explicitly use our own context as 3rd parameter...\n        httpService.registerResources(\"/static\", \"/etc/www\", new MyHttpContext());\n    } catch (Exception exception) {\n        exception.printStackTrace();\n    }\n    return httpService;\n}\n// ....
\n

Using the Servlet Bridge

\n

The servlet bridge is used if you want to use the HTTP service inside a WAR deployed on a 3rd part applicaiton server. A\nlittle setup is needed for this to work:

\n
    \n
  1. deploy org.apache.felix.http.proxy jar file inside the web application (WEB-INF/lib);
  2. \n
  3. in a startup listener (like ServletContextListener) set the BundleContext as a servlet context attribute (see example;
  4. \n
  5. define org.apache.felix.http.proxy.ProxyServlet inside your web.xml and register it to serve on all requests /* (see example;
  6. \n
  7. define org.apache.felix.http.proxy.ProxyListener as a <listener> in your web.xml to allow HTTP session related events to be forwarded (see the section of Servlet API Event forwarding below and example;
  8. \n
  9. be sure to add javax.servlet;javax.servlet.http;version=2.6 to OSGi system packages (org.osgi.framework.system.packages);
  10. \n
  11. deploy org.apache.felix.http.bridge (or org.apache.felix.http.bundle) inside the OSGi framework.
  12. \n
\n

A detailed example can be found here.

\n

Using the SSL filter

\n

This filter provides you means to transparently handle SSL termination proxies,\nallowing your servlets and filters to work like they were accessed directly through HTTPS. This filter is useful when\ndeploying applications in large datacenters where frontend load-balancers distribute the load among several servers in\nthe same datacenter by stripping the SSL encryption.

\n

The SSL filter can be configured to let it detect whether the request was originating from\nan SSL connection. There are several non-standard request headers in use:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Header nameUsed valueDescription
X-Forwarded-Protohttpsused by Amazon ELBs and Nginx and more or less the de-facto standard to indicate a SSL-terminated connection.
X-Forwarded-Protocolhttpsalternative to X-Forwarded-Proto.
X-Forwarded-SSLonnon-standard way used by some applications.
Front-End-Httpsonused by Microsoft to indicate a SSL-terminated connection.
\n

In case a client connected using a certificate, this certificate can be forwarded as well by the SSL filter. Several\nnon-standard request headers are used for this:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderDescription
X-Forwarded-SSL-CertificateThe de-facto(?) standard used to forward the client certificate by a proxy.
X-Forwarded-SSL-Client-CertAlternative header used by some proxies.
\n

Note: instead of deploying the SSL filter bundle, you can also set the org.apache.felix.proxy.load.balancer.connection.enable property to true in order to achieve the same effect.

\n

Configuration Properties

\n

The service can both be configured using OSGi environment properties and using Configuration Admin. The service PID for\nthis service is \"org.apache.felix.http\". If you use both methods, Configuration Admin takes precedence. The following\nproperties can be used (some legacy property names still exist but are not documented here on purpose):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropertyDescription
org.apache.felix.http.debugFlag to enable debugging for this service implementation. The default is false.
org.apache.felix.http.hostHost name or IP Address of the interface to listen on. The default is null causing Jetty to listen on all interfaces.
org.osgi.service.http.portThe port used for servlets and resources available via HTTP. The default is 8080. See port settings below for additional information. A negative port number has the same effect as setting org.apache.felix.http.enable to false.
org.osgi.service.http.port.secureThe port used for servlets and resources available via HTTPS. The default is 8443. See port settings below for additional information. A negative port number has the same effect as setting org.apache.felix.https.enable to false.
org.apache.felix.http.context_pathThe servlet Context Path to use for the Http Service. If this property is not configured it defaults to \"/\". This must be a valid path starting with a slash and not ending with a slash (unless it is the root context).
org.apache.felix.http.timeoutConnection timeout in milliseconds. The default is 60000 (60 seconds).
org.apache.felix.http.session.timeoutAllows for the specification of the Session life time as a number of minutes. This property serves the same purpose as the session-timeout element in a Web Application descriptor. The default is \"0\" (zero) for no timeout at all.
org.apache.felix.http.nioFlag to enable the use of NIO instead of traditional IO for HTTP. One consequence of using NIO with HTTP is that the bundle needs at least a Java 5 runtime. The default is true.
org.apache.felix.https.nioFlag to enable the use of NIO instead of traditional IO for HTTPS. One consequence of using NIO with HTTPS is that the bundle needs at least a Java 5 runtime. If this property is not set the (default) value of the org.apache.felix.http.nio property is used.
org.apache.felix.http.enableFlag to enable the use of HTTP. The default is true.
org.apache.felix.https.enableFlag to enable the user of HTTPS. The default is false.
org.apache.felix.https.keystoreThe name of the file containing the keystore.
org.apache.felix.https.keystore.passwordThe password for the keystore.
org.apache.felix.https.keystore.key.passwordThe password for the key in the keystore.
org.apache.felix.https.truststoreThe name of the file containing the truststore.
org.apache.felix.https.truststore.typeThe type of truststore to use. The default is JKS.
org.apache.felix.https.truststore.passwordThe password for the truststore.
org.apache.felix.https.jetty.ciphersuites.excludedConfigures comma-separated list of SSL cipher suites to exclude. Default is null, meaning that no cipher suite is excluded.
org.apache.felix.https.jetty.ciphersuites.includedConfigures comma-separated list of SSL cipher suites to include. Default is null, meaning that the default cipher suites are used.
org.apache.felix.https.jetty.protocols.excludedConfigures comma-separated list of SSL protocols (e.g. SSLv3, TLSv1.0, TLSv1.1, TLSv1.2) to exclude. Default is null, meaning that no protocol is excluded.
org.apache.felix.https.jetty.protocols.includedConfigures comma-separated list of SSL protocols to include. Default is null, meaning that the default protocols are used.
org.apache.felix.https.clientcertificateFlag to determine if the HTTPS protocol requires, wants or does not use client certificates. Legal values are needs, wants and none. The default is none.
org.apache.felix.http.jetty.headerBufferSizeSize of the buffer for request and response headers, in bytes. Default is 16 KB.
org.apache.felix.http.jetty.requestBufferSizeSize of the buffer for requests not fitting the header buffer, in bytes. Default is 8 KB.
org.apache.felix.http.jetty.responseBufferSizeSize of the buffer for responses, in bytes. Default is 24 KB.
org.apache.felix.http.jetty.maxFormSizeThe maximum size accepted for a form post, in bytes. Defaults to 200 KB.
org.apache.felix.http.mbeansIf true, enables the MBean server functionality. The default is false.
org.apache.felix.http.jetty.sendServerHeaderIf false, the Server HTTP header is no longer included in responses. The default is false.
org.eclipse.jetty.servlet.SessionCookieName of the cookie used to transport the Session ID. The default is JSESSIONID.
org.eclipse.jetty.servlet.SessionURLName of the request parameter to transport the Session ID. The default is jsessionid.
org.eclipse.jetty.servlet.SessionDomainDomain to set on the session cookie. The default is null.
org.eclipse.jetty.servlet.SessionPathThe path to set on the session cookie. The default is the configured session context path (\"/\").
org.eclipse.jetty.servlet.MaxAgeThe maximum age value to set on the cookie. The default is \"-1\".
org.apache.felix.proxy.load.balancer.connection.enableSet this to true when running Felix HTTP behind a (offloading) proxy or load balancer which rewrites the requests. The default is false.
org.apache.felix.http.runtime.init.Properties starting with this prefix are added as service registration properties to the HttpServiceRuntime service. The prefix is removed for the property name.
org.apache.felix.jetty.gziphandler.enableWhether the server should use a server-wide gzip handler. Default is false.
org.apache.felix.jetty.gzip.minGzipSizeThe minimum response size to trigger dynamic compression. Default is GzipHandler.DEFAULT_MIN_GZIP_SIZE.
org.apache.felix.jetty.gzip.compressionLevelThe compression level to use. Default is Deflater.DEFAULT_COMPRESSION.
org.apache.felix.jetty.gzip.inflateBufferSizeThe size in bytes of the buffer to inflate compressed request, or <= 0 for no inflation. Default is -1.
org.apache.felix.jetty.gzip.syncFlushTrue if Deflater#SYNC_FLUSH should be used, else Deflater#NO_FLUSH will be used. Default is false.
org.apache.felix.jetty.gzip.excludedUserAgentsThe regular expressions matching additional user agents to exclude. Default is none.
org.apache.felix.jetty.gzip.includedMethodsThe additional http methods to include in compression. Default is none.
org.apache.felix.jetty.gzip.excludedMethodsThe additional http methods to exclude in compression. Default is none.
org.apache.felix.jetty.gzip.includedPathsThe additional path specs to include. Inclusion takes precedence over exclusion. Default is none.
org.apache.felix.jetty.gzip.excludedPathsThe additional path specs to exclude. Inclusion takes precedence over exclusion. Default is none.
org.apache.felix.jetty.gzip.includedMimeTypesThe included mime types. Inclusion takes precedence over exclusion. Default is none.
org.apache.felix.jetty.gzip.excludedMimeTypesThe excluded mime types. Inclusion takes precedence over exclusion. Default is none.
org.apache.felix.http2.enableWhether to enable HTTP/2. Default is false.
org.apache.felix.jetty.http2.maxConcurrentStreamsThe max number of concurrent streams per connection. Default is 128.
org.apache.felix.jetty.http2.initialStreamRecvWindowThe initial stream receive window (client to server). Default is 524288.
org.apache.felix.jetty.http2.initialSessionRecvWindowThe initial session receive window (client to server). Default is 1048576.
org.apache.felix.jetty.alpn.protocolsThe ALPN protocols to consider. Default is h2, http/1.1.
org.apache.felix.jetty.alpn.defaultProtocolThe default protocol when negotiation fails. Default is http/1.1.
\n

All-in-one-bundle configuration properties

\n

Additionally, the all-in-one bundle uses the following environment properties (no support for Configuration Admin):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropertyDescription
org.apache.felix.http.jettyEnabledIf true, the embedded Jetty server is used as HTTP container. The default is false.
org.apache.felix.http.whiteboardEnabledIf true, the whiteboard-style registration of servlets and filters is enabled. The default is false.
org.apache.felix.http.cometdEnabledIf true the CometD/Ajax Push feature is enabled. The default is false.
\n

Multiple Servers

\n

It is possible to configure several Http Services, each running on a different port. The first service can be configured as outlined above using the service PID for \"org.apache.felix.http\". Additional servers can be configured through OSGi factory configurations using \"org.apache.felix.http\" as the factory PID. The properties for the configuration are outlined as above.

\n

The default server using the PID \"org.apache.felix.http\" can be disabled by specifying a negative port and then all servers can be used through factory configurations.

\n

CometD configuration properties

\n

The CometD bundle supports the following configuration options, using the PID org.apache.felix.http.cometd or through\nenvironment properties:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropertyDescription
org.apache.felix.http.cometd.pathDefines the path for the CometD endpoint. Default is /system/cometd.
\n

SSL filter configuration properties

\n

The SSL-filter bundle supports the following configuration options, using the PID\norg.apache.felix.http.sslfilter.SslFilter (no fallback to environment properties!):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropertyDescription
ssl-forward.headerDefines what HTTP header to look for in a request to determine whether a request is a forwarded SSL request. The default is X-Forwarded-SSL.
ssl-forward.valueDefines what HTTP header value to look for in a request to determine whether a request is a forwarded SSL request in a request. The default is on.
ssl-forward-cert.headerDefines what HTTP header to look for in a request to obtain the forwarded client certificate. The default is X-Forwarded-SSL-Certificate.
\n

HTTP port settings

\n

As of HTTP Jetty version 2.2.2, it is possible to assign a free port for HTTP or HTTPS automatically, based on certain\nrules, for example, a range between 8000 and 9000. The syntax is based on the version ranges, as described in the OSGi\nspecification. The following forms are supported:

\n\n

Note that picking a port is not performed atomically and multiple instances can try to bind to the same port at the\nsame time.

\n

Servlet API Events

\n

The Servlet API defines a number of EventListener interfaces to catch servlet or filter related events. As of HTTP\nService 2.1.0 most events generated by the servlet container are forwarded to interested service. To be registered to\nreceive events services must be registered with the respective EventListener interface:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
InterfaceDescription
javax.servlet.ServletContextAttributeListenerEvents on servlet context attribute addition, change and removal.
javax.servlet.ServletRequestAttributeListenerEvents on request attribute addition, change and removal.
javax.servlet.ServletRequestListenerEvents on request start and end.
javax.servlet.http.HttpSessionAttributeListenerEvents on session attribute addition, change and removal. To receive such events in a bridged environment, the ProxyLister must be registered with the servlet container. See the Using the Servlet Bridge section above.
javax.servlet.http.HttpSessionListenerEvents on session creation and destroyal. To receive such events in a bridged environment, the ProxyLister must be registered with the servlet container. See the Using the Servlet Bridge section above.
\n

Of the defined EventListener interfaces in the Servlet API, the javax.servlet.ServletContextListener events are\ncurrently not support (but will be in the near future). For one thing they do not make much sense in an OSGi\nenvironment. On the other hand they are hard to capture and propagate. For example in a bridged environment the\ncontextInitialized event may be sent before the framework and any of the contained bundles are actually ready to act.\nLikewise the contextDestroyed event may come to late.

\n

Servlet Context Notes

\n

ServletContext instances are managed internally by the Http Service implementation. For each HttpContext instance\nused to register one or more servlets and/or resources a corresponding ServletContext instance is created. These\nServletContext instances is partly based on the single ServletContext instance received from the Servlet Container\n--- either embedded Jetty or some external Servlet Container when using the Http Service Bridge --- and partly based on\nthe provided HttpContext instance:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Method(s)Based on ...
getContextPath, getContext, getMajorVersion, getMinorVersion, getServerInfoServlet Containers ServletContext
getResourcePathsBundle.getEntryPaths of the bundle using the Http Service
getResource, getResourceAsStreamHttpContext.getResource
getMimeTypeHttpContext.getMimeType
getRequestDispatcher, getNamedDispatcher, getInitParameter, getServlet, getRealPathAlways return null
getInitParameterNames, getServlets, getServletNamesAlways returns empty Enumeration
getAttribute, getAttributeNames, setAttribute, removeAttributeBy default maintained for each ServletContext managed by the Http Service. If the org.apache.felix.http.shared*servlet*context_attributes framework property is set to true these methods are actually based on the ServletContext provided by the servlet container and thus attributes are shared amongst all ServlectContext instances, incl. the ServletContext provided by the servlet container
\n

Examples

\n

A set of simple examples illustrating the various features are available.

\n\n

Maven Artifacts

\n

This is a list of the most recent artifacts at the time of writing this document. There might already be never versions available:

\n
<dependency>\n    <groupId>org.apache.felix</groupId>\n    <artifactId>org.apache.felix.http.servlet-api</artifactId>\n    <version>1.1.2</version>\n</dependency>\n<dependency>\n    <groupId>org.apache.felix</groupId>\n    <artifactId>org.apache.felix.http.jetty</artifactId>\n    <version>4.0.14</version>\n</dependency>\n<dependency>\n    <groupId>org.apache.felix</groupId>\n    <artifactId>org.apache.felix.http.bridge</artifactId>\n    <version>4.0.8</version>\n</dependency>\n<dependency>\n    <groupId>org.apache.felix</groupId>\n    <artifactId>org.apache.felix.http.cometd</artifactId>\n    <version>2.3.2</version>\n</dependency>\n<dependency>\n    <groupId>org.apache.felix</groupId>\n    <artifactId>org.apache.felix.http.proxy</artifactId>\n    <version>3.0.6</version>\n</dependency>\n<dependency>\n    <groupId>org.apache.felix</groupId>\n    <artifactId>org.apache.felix.http.sslfilter</artifactId>\n    <version>1.2.6</version>\n</dependency>
\n
","errorMessage":null,"headerInfo":{"toc":[{"level":1,"text":"Apache Felix HTTP Service","anchor":"apache-felix-http-service","htmlText":"Apache Felix HTTP Service"},{"level":2,"text":"Installing","anchor":"installing","htmlText":"Installing"},{"level":2,"text":"Installing additional bundles for the optional HTTP/2 support with jetty","anchor":"installing-additional-bundles-for-the-optional-http2-support-with-jetty","htmlText":"Installing additional bundles for the optional HTTP/2 support with jetty"},{"level":2,"text":"Using the OSGi Http Whiteboard","anchor":"using-the-osgi-http-whiteboard","htmlText":"Using the OSGi Http Whiteboard"},{"level":3,"text":"Servlet service properties","anchor":"servlet-service-properties","htmlText":"Servlet service properties"},{"level":3,"text":"Filter service properties","anchor":"filter-service-properties","htmlText":"Filter service properties"},{"level":3,"text":"ServletContextHelper service properties","anchor":"servletcontexthelper-service-properties","htmlText":"ServletContextHelper service properties"},{"level":2,"text":"Using the HttpService","anchor":"using-the-httpservice","htmlText":"Using the HttpService"},{"level":2,"text":"Using the Servlet Bridge","anchor":"using-the-servlet-bridge","htmlText":"Using the Servlet Bridge"},{"level":2,"text":"Using the SSL filter","anchor":"using-the-ssl-filter","htmlText":"Using the SSL filter"},{"level":2,"text":"Configuration Properties","anchor":"configuration-properties","htmlText":"Configuration Properties"},{"level":3,"text":"All-in-one-bundle configuration properties","anchor":"all-in-one-bundle-configuration-properties","htmlText":"All-in-one-bundle configuration properties"},{"level":3,"text":"Multiple Servers","anchor":"multiple-servers","htmlText":"Multiple Servers"},{"level":3,"text":"CometD configuration properties","anchor":"cometd-configuration-properties","htmlText":"CometD configuration properties"},{"level":3,"text":"SSL filter configuration properties","anchor":"ssl-filter-configuration-properties","htmlText":"SSL filter configuration properties"},{"level":3,"text":"HTTP port settings","anchor":"http-port-settings","htmlText":"HTTP port settings"},{"level":2,"text":"Servlet API Events","anchor":"servlet-api-events","htmlText":"Servlet API Events"},{"level":2,"text":"Servlet Context Notes","anchor":"servlet-context-notes","htmlText":"Servlet Context Notes"},{"level":2,"text":"Examples","anchor":"examples","htmlText":"Examples"},{"level":2,"text":"Maven Artifacts","anchor":"maven-artifacts","htmlText":"Maven Artifacts"}],"siteNavLoginPath":"/login?return_to=https%3A%2F%2Fgithub.com%2Fapache%2Ffelix-dev%2Ftree%2Fmaster%2Fhttp"}},"totalCount":15,"showBranchInfobar":false},"fileTree":{"":{"items":[{"name":"bundlerepository.osgi-ct","path":"bundlerepository.osgi-ct","contentType":"directory"},{"name":"bundlerepository","path":"bundlerepository","contentType":"directory"},{"name":"cm.json","path":"cm.json","contentType":"directory"},{"name":"configadmin-plugins","path":"configadmin-plugins","contentType":"directory"},{"name":"configadmin","path":"configadmin","contentType":"directory"},{"name":"configurator","path":"configurator","contentType":"directory"},{"name":"connect","path":"connect","contentType":"directory"},{"name":"coordinator","path":"coordinator","contentType":"directory"},{"name":"dependencymanager","path":"dependencymanager","contentType":"directory"},{"name":"doap","path":"doap","contentType":"directory"},{"name":"eventadmin","path":"eventadmin","contentType":"directory"},{"name":"examples","path":"examples","contentType":"directory"},{"name":"features","path":"features","contentType":"directory"},{"name":"fileinstall","path":"fileinstall","contentType":"directory"},{"name":"framework.security","path":"framework.security","contentType":"directory"},{"name":"framework","path":"framework","contentType":"directory"},{"name":"gogo","path":"gogo","contentType":"directory"},{"name":"healthcheck","path":"healthcheck","contentType":"directory"},{"name":"http","path":"http","contentType":"directory"},{"name":"inventory","path":"inventory","contentType":"directory"},{"name":"ipojo","path":"ipojo","contentType":"directory"},{"name":"log.extension","path":"log.extension","contentType":"directory"},{"name":"log","path":"log","contentType":"directory"},{"name":"main.distribution","path":"main.distribution","contentType":"directory"},{"name":"main","path":"main","contentType":"directory"},{"name":"metatype","path":"metatype","contentType":"directory"},{"name":"pom","path":"pom","contentType":"directory"},{"name":"resolver","path":"resolver","contentType":"directory"},{"name":"rootcause","path":"rootcause","contentType":"directory"},{"name":"scr-ext-anno","path":"scr-ext-anno","contentType":"directory"},{"name":"scr","path":"scr","contentType":"directory"},{"name":"systemready","path":"systemready","contentType":"directory"},{"name":"tools","path":"tools","contentType":"directory"},{"name":"utils","path":"utils","contentType":"directory"},{"name":"webconsole-plugins","path":"webconsole-plugins","contentType":"directory"},{"name":"webconsole","path":"webconsole","contentType":"directory"},{"name":".gitignore","path":".gitignore","contentType":"file"},{"name":"CODE_OF_CONDUCT.md","path":"CODE_OF_CONDUCT.md","contentType":"file"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","contentType":"file"},{"name":"LICENSE","path":"LICENSE","contentType":"file"},{"name":"README.md","path":"README.md","contentType":"file"},{"name":"check_staged_release.sh","path":"check_staged_release.sh","contentType":"file"},{"name":"stage_existing_artifact.sh","path":"stage_existing_artifact.sh","contentType":"file"}],"totalCount":43}},"fileTreeProcessingTime":5.422142,"foldersToFetch":[],"treeExpanded":true,"symbolsExpanded":false,"csrf_tokens":{"/apache/felix-dev/branches":{"post":"H7HXomauanLjjm56GzF5QSyz-Mp8X0q2c1zlCP6zJ0mKCg0g4yXyGx4mZeZ5t3txnp-A-_sbxsQe8idQrw8s_w"},"/apache/felix-dev/branches/fetch_and_merge/master":{"post":"8-FYR08rFIGNLUBcsk0WSkWCkzN19fGvjd8I2-TMkIBX7v2M4AcnJjKQf8nBfT4iuVndVO2vYhLirBsZsDRstw"},"/apache/felix-dev/branches/fetch_and_merge/master?discard_changes=true":{"post":"ctqm0b_actk5VH-DTVzgau1pGIqzx5QM4kyU1XBPYuTW1QMaEPZBfobpQBY-bMgCEbJW7SudB7GNP4cXJLee0w"}}},"title":"felix-dev/http at master ยท apache/felix-dev"}