felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Apache Felix HTTP Service
Date Thu, 05 Jan 2012 11:31:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+HTTP+Service">Apache
Felix HTTP Service</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>* {{org.apache.felix.host}}
- Host name or IP Address of the interface to listen on. The default is {{null}} causing Jetty
to listen on all interfaces. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*
{{org.apache.felix.http.context_path}} - The Servlet Context Path to use for the Http Service.
If this property is not configured it  defaults to &quot;/&quot;. This must be a valid
path starting with a slash and not  ending with a slash (unless it is the root context). <br></td></tr>
            <tr><td class="diff-unchanged" >* {{org.apache.felix.http.timeout}}
- Connection timeout in milliseconds. The default is 60000 (60 seconds). <br>* {{org.apache.felix.http.session.timeout}}
- Allows for the specification of the Session life time as a number of minutes. This property
serves the same purpose as the {{session-timeout}} element in a Web Application descriptor.
The default is zero for no timeout at all. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="ApacheFelixHTTPService-ApacheFelixHTTPService"></a>Apache
Felix HTTP Service</h1>

<div><a href='#ApacheFelixHTTPService-Installing'>Installing</a> | <a
href='#ApacheFelixHTTPService-UsingtheHttpService'>Using the HttpService</a> | <a
href='#ApacheFelixHTTPService-UsingtheExtHttpService'>Using the ExtHttpService</a>
| <a href='#ApacheFelixHTTPService-UsingtheWhiteboard'>Using the Whiteboard</a>
| <a href='#ApacheFelixHTTPService-UsingtheServletBridge'>Using the Servlet Bridge</a>
| <a href='#ApacheFelixHTTPService-ConfigurationProperties'>Configuration Properties</a>
| <a href='#ApacheFelixHTTPService-ServletAPIEvents'>Servlet API Events</a> |
<a href='#ApacheFelixHTTPService-ServletContextNotes'>Servlet Context Notes</a>
| <a href='#ApacheFelixHTTPService-Examples'>Examples</a> | <a href='#ApacheFelixHTTPService-MavenArtifacts'>Maven
Artifacts</a></div>

<p>This is 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 and resources in a Servlet container, and to associate them with URIs. It also implement
a non-standard extension for registering servlet filters as well as a whiteboard implementation.
Complete set of features:</p>

<ul>
	<li>Standard HTTP Service implementation.</li>
	<li>Extended HTTP Service implementation that allows for servlet filter registration.</li>
	<li>Run either with Jetty or inside your own application server using the servlet bridge.</li>
	<li>A whiteboard implementation for easy registration of servlets and filters.</li>
	<li>One complete bundle that includes everything to simplify deployment.</li>
</ul>


<h2><a name="ApacheFelixHTTPService-Installing"></a>Installing</h2>

<p>The Apache Felix HTTP Service project includes several bundles. </p>

<ul>
	<li>org.apache.felix.http.jetty - HTTP Service implementation that is embedding Jetty
server.</li>
	<li>org.apache.felix.http.whiteboard - Whiteboard implementation that uses any HTTP
Service implementation.</li>
	<li>org.apache.felix.http.bridge - HTTP Service implementation that uses the host applicaiton
server (bridged mode). Must be used with proxy.</li>
	<li>org.apache.felix.http.bundle - All in one bundle that includes all of the above.</li>
	<li>org.apache.felix.http.proxy - Proxy that is needed inside WAR when deployed inside
an application server.</li>
</ul>


<p>So, in most cases you could just use <b>org.apache.felix.http.bundle</b>
and forget about all the other ones.</p>

<h2><a name="ApacheFelixHTTPService-UsingtheHttpService"></a>Using the HttpService</h2>

<p>The main components provided by the Apache Felix HTTP Service bundle are:</p>
<ul>
	<li><tt>HttpService</tt> - Service used to dynamically register resources
and servlets</li>
	<li><tt>HttpContext</tt> - Additional (optional) component to handle authentication,
resource and mime type mappings</li>
</ul>


<p>Servlets created for the OSGi HTTP service don't need to have any reference to the
OSGi specification (they only need to conform to the Servlet specification), like in the example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class HelloWorld <span class="code-keyword">extends</span>
HttpServlet
{
  @Override
  <span class="code-keyword">protected</span> void doGet(HttpServletRequest req,
HttpServletResponse resp) <span class="code-keyword">throws</span> ServletException,
IOException 
  {
    resp.getWriter().write(<span class="code-quote">"Hello World"</span>);		
  }	
}
</pre>
</div></div>

<p>To register a Servlet and map it to a URI, you need to retrieve the <tt>HttpService</tt>
and call its <tt>registerServlet</tt> method:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Activator <span class="code-keyword">implements</span>
BundleActivator
{
  <span class="code-keyword">public</span> void start(BundleContext context) <span
class="code-keyword">throws</span> Exception 
  {
    ServiceReference sRef = context.getServiceReference(HttpService.class.getName());
    <span class="code-keyword">if</span> (sRef != <span class="code-keyword">null</span>)
    {
      HttpService service = (HttpService) context.getService(sRef);
      service.registerServlet(<span class="code-quote">"/hello"</span>, <span
class="code-keyword">new</span> HelloWorld(), <span class="code-keyword">null</span>,
<span class="code-keyword">null</span>);
    }
  }
}
</pre>
</div></div>

<p>In the same way, you can unregister a Servlet (for instance, in the <tt>stop</tt>
method of the Bundle Activator) calling the <tt>HttpService.unregister</tt> method.</p>

<p>As you notice in the example above, the <tt>registerServlet</tt> method
accepts four parameters:</p>
<ul>
	<li>the Servlet alias</li>
	<li>the Servlet instance</li>
	<li>an additional configuration Map</li>
	<li>an HttpContext</li>
</ul>


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

<p>An additional configuration Map can be optionally specified; if present, all the
parameters contained will be copied in the ServletContext object. </p>

<p>Finally, an HttpContext object can be optionally specified to handle authentication,
mime type and resource mapping. The <tt>HttpContext</tt> interface is quite simple:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> <span class="code-keyword">interface</span>
HttpContext
{
  <span class="code-object">String</span> getMimeType(java.lang.<span class="code-object">String</span>
name); <span class="code-comment">//Returns the mime type of the specified resource
</span>  URL getResource(java.lang.<span class="code-object">String</span>
name);   <span class="code-comment">//Returns the URL to retrieve the specified resource
</span>  <span class="code-object">boolean</span> handleSecurity(HttpServletRequest
request, HttpServletResponse response); <span class="code-comment">//Manages security
<span class="code-keyword">for</span> the specified request
</span>}
</pre>
</div></div>

<p>The use of a custom HttpContext is typical when you want to serve static contents
with the HTTP Service. Let's see first the simplest example of resource registration (without
<tt>HttpContext</tt>)</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Activator <span class="code-keyword">implements</span>
BundleActivator
{
  <span class="code-keyword">public</span> void start(BundleContext context) <span
class="code-keyword">throws</span> Exception 
  {
    ServiceReference sRef = context.getServiceReference(HttpService.class.getName());
    <span class="code-keyword">if</span> (sRef != <span class="code-keyword">null</span>)
    {
      HttpService service = (HttpService) context.getService(sRef);
      service.registerResources(<span class="code-quote">"/<span class="code-keyword">static</span>"</span>,
<span class="code-quote">"/etc/www"</span>, <span class="code-keyword">null</span>);
    }
  }
}
</pre>
</div></div>

<p>As a result of the <tt>service.registerResources("/static", "/etc/www", null)</tt>
code, all the files available under <tt>/etc/www</tt> will be exposed under <tt>/static</tt>
(f.i.  <a href="http://localhost:8080/static/001.jpg" class="external-link" rel="nofollow">http://localhost:8080/static/001.jpg</a>
will render the /etc/www/001.jpg). However, the example above can be simplistic in practice;
the HttpContext object is the solution to customize the resource handling.</p>

<p>For instance, you can set the define more complex URI to file mappings overriding
the <tt>HttpContext.getResource</tt> method, or the correct mime type implementing
the method <tt>HttpContext.getMimeType</tt> like in the example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">//....
</span>
<span class="code-keyword">public</span> <span class="code-object">String</span>
getMimeType(<span class="code-object">String</span> file) 
{  
  <span class="code-keyword">if</span> (file.endsWith(<span class="code-quote">".jpg"</span>)
  {  
    <span class="code-keyword">return</span> <span class="code-quote">"image/jpeg"</span>;
 
  } 
  <span class="code-keyword">else</span> <span class="code-keyword">if</span>
(file.endsWith(<span class="code-quote">".png"</span>)) 
  {  
    <span class="code-keyword">return</span> <span class="code-quote">"image/png"</span>;
 
  } 
  <span class="code-keyword">else</span> 
  {  
    <span class="code-keyword">return</span> <span class="code-quote">"text/html"</span>;
 
  }  
}  
	
<span class="code-comment">//....</span>
</pre>
</div></div>

<p>If you implement a customized HttpContext object, don't forget to specify it as third
parameter of the <tt>registerResources</tt> method invocation:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Activator <span class="code-keyword">implements</span>
BundleActivator
{
  <span class="code-keyword">public</span> void start(BundleContext context) <span
class="code-keyword">throws</span> Exception 
  {
    ServiceReference sRef = context.getServiceReference(HttpService.class.getName());
    <span class="code-keyword">if</span> (sRef != <span class="code-keyword">null</span>)
    {
      HttpService service = (HttpService) context.getService(sRef);
      HttpContext myHttpContext = <span class="code-keyword">new</span> MyHttpContext());
      service.registerResources(<span class="code-quote">"/<span class="code-keyword">static</span>"</span>,
<span class="code-quote">"/etc/www"</span>, myHttpContext);
    }
  }
}
</pre>
</div></div>

<h2><a name="ApacheFelixHTTPService-UsingtheExtHttpService"></a>Using the
ExtHttpService</h2>

<p>To be able to register filters, it is possible to get hold of <tt>org.apache.felix.http.api.ExtHttpService</tt>.
This is exported by both jetty and the bridged implementation. Let's see the simplest example
of a filter registration.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Activator <span class="code-keyword">implements</span>
BundleActivator
{
  <span class="code-keyword">public</span> void start(BundleContext context) <span
class="code-keyword">throws</span> Exception 
  {
    ServiceReference sRef = context.getServiceReference(ExtHttpService.class.getName());
    <span class="code-keyword">if</span> (sRef != <span class="code-keyword">null</span>)
    {
      ExtHttpService service = (ExtHttpService) context.getService(sRef);
      service.registerFilter(<span class="code-keyword">new</span> HelloWorldFilter(),
<span class="code-quote">"/hello/.*"</span>, <span class="code-keyword">null</span>,
0, <span class="code-keyword">null</span>);
    }
  }
}
</pre>
</div></div>

<p>Notice the pattern for filters is using regular expressions. So <tt>.&#42;</tt>
is the same as a simple <tt><br class="atl-forced-newline" />*</tt> using
standard servlet patterns. </p>

<h2><a name="ApacheFelixHTTPService-UsingtheWhiteboard"></a>Using the Whiteboard</h2>

<p>The whiteboard implementation simplifies the task of registering servlets and filters.
A servlet (or filter) can be registered by exporting it as a service. The whiteboard implementation
detects all <tt>javax.servlet.Servlet</tt>, <tt>javax.servlet.Filter</tt>
and <tt>org.osgi.service.http.HttpContext</tt> services with the right service
properties. Let us illustrate the usage by registering a servlet:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Activator <span class="code-keyword">implements</span>
BundleActivator
{
  <span class="code-keyword">private</span> ServiceRegistration registration;

  <span class="code-keyword">public</span> void start(BundleContext context) <span
class="code-keyword">throws</span> Exception 
  {
    Hashtable props = <span class="code-keyword">new</span> Hashtable();
    props.put(<span class="code-quote">"alias"</span>, <span class="code-quote">"/hello"</span>);
    props.put(<span class="code-quote">"init.message"</span>, <span class="code-quote">"Hello
World!"</span>);

    <span class="code-keyword">this</span>.registration = context.registerService(Servlet.class.getName(),
<span class="code-keyword">new</span> HelloWorldServlet(), props);
  }

  <span class="code-keyword">public</span> void stop(BundleContext context) <span
class="code-keyword">throws</span> Exception 
  {
    <span class="code-keyword">this</span>.registration.unregister();
  }
}
</pre>
</div></div>

<p>Servlet service properties:</p>
<ul>
	<li><tt>alias</tt> - Servlet alias to register with.</li>
	<li><tt>contextId</tt> - Id of context to register with.</li>
	<li><tt>init.&#42;</tt> - Servlet initialization values.</li>
</ul>


<p>Filter service properties:</p>
<ul>
	<li><tt>pattern</tt> - Regular expression pattern to register filter with.</li>
	<li><tt>contextId</tt> - Id of context to register with.</li>
	<li><tt>service.ranking</tt> - Where in the chain this filter should be
placed.</li>
	<li><tt>init.&#42;</tt> - Filter initialization values.</li>
</ul>


<p>HttpContext service properties:</p>
<ul>
	<li><tt>contextId</tt> - Id of context to be referenced by a servlet or
filter service.</li>
</ul>


<h2><a name="ApacheFelixHTTPService-UsingtheServletBridge"></a>Using the
Servlet Bridge</h2>

<p>The servlet bridge is used if you want to use the Http service inside a WAR deployed
on a 3rd part applicaiton server. A little setup is needed for this to work:</p>

<ul>
	<li>Deploy <tt>org.apache.felix.http.proxy</tt> jar file inside the web
applicaiton (WEB-INF/lib).</li>
	<li>In a startup listener (like ServletContextListener) set the BundleContext as a
servlet context attribute (see <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge/src/main/java/org/apache/felix/http/samples/bridge/StartupListener.java"
class="external-link" rel="nofollow">example</a>).</li>
	<li>Define <tt>org.apache.felix.http.proxy.ProxyServlet</tt> inside your
<tt>web.xml</tt> and register it to serve on all requests <tt>/*</tt>
(see <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge/src/main/webapp/WEB-INF/web.xml"
class="external-link" rel="nofollow">example</a>).</li>
	<li>Define <tt>org.apache.felix.http.proxy.ProxyListener</tt> as a <tt>&lt;listener&gt;</tt>
in your <tt>web.xml</tt> to allow HTTP Session related events to be forwarded
(see the section of Servlet API Event forwarding below and <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge/src/main/webapp/WEB-INF/web.xml"
class="external-link" rel="nofollow">example</a>).</li>
	<li>Be sure to add <tt>javax.servlet;javax.servlet.http;version=2.5</tt>
to OSGi system packages ((<tt>org.osgi.framework.system.packages</tt>).</li>
	<li>Deploy <tt>org.apache.felix.http.bridge</tt> (or <tt>org.apache.felix.http.bundle</tt>)
inside the OSGi framework.</li>
</ul>


<p>A detailed example can be found <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge"
class="external-link" rel="nofollow">here</a>.</p>

<h2><a name="ApacheFelixHTTPService-ConfigurationProperties"></a>Configuration
Properties</h2>

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

<ul>
	<li><tt>org.osgi.service.http.port</tt> - The port used for servlets and
resources available via HTTP. The default is <tt>80</tt>. A negative port number
has the same effect as setting <tt>org.apache.felix.http.enable</tt> to <tt>false</tt>.</li>
	<li><tt>org.osgi.service.http.port.secure</tt> - The port used for servlets
and resources available via HTTPS. The default is <tt>443</tt>. A negative port
number has the same effect as setting <tt>org.apache.felix.https.enable</tt> to
<tt>false</tt>.</li>
	<li><tt>org.apache.felix.http.nio</tt> - Flag to enable the use of NIO
instead of traditional IO for HTTP. One consequence of using NIO with HTTP is that the bundle
needs at least a Java 5 runtime. The default is <tt>true</tt>.</li>
	<li><tt>org.apache.felix.https.nio</tt> - Flag to enable the use of NIO
instead of traditional IO for HTTPS. One consequence of using NIO with HTTPS is that the bundle
needs at least a Java 5 runtime. If this property is not set the (default) value of the <tt>org.apache.felix.http.nio</tt>
property is used.</li>
	<li><tt>org.apache.felix.http.enable</tt> - Flag to enable the use of HTTP.
The default is <tt>true</tt>.</li>
	<li><tt>org.apache.felix.https.enable</tt> - Flag to enable the user of
HTTPS. The default is <tt>false</tt>.</li>
	<li><tt>org.apache.felix.https.keystore</tt> - The name of the file containing
the keystore.</li>
	<li><tt>org.apache.felix.https.keystore.password</tt> - The password for
the keystore.</li>
	<li><tt>org.apache.felix.https.keystore.key.password</tt> - The password
for the key in the keystore.</li>
	<li><tt>org.apache.felix.https.truststore</tt> - The name of the file containing
the truststore.</li>
	<li><tt>org.apache.felix.https.truststore.password</tt> - The password
for the truststore.</li>
	<li><tt>org.apache.felix.https.clientcertificate</tt> - Flag to determine
if the HTTPS protocol requires, wants or does not use client certificates. Legal values are
<tt>needs</tt>, <tt>wants</tt> and <tt>none</tt>. The
default is <tt>none</tt>.</li>
	<li><tt>org.apache.felix.http.debug</tt> - Flag to enable debugging for
this service implementation. The default is <tt>false</tt>.</li>
</ul>


<p>Additionally, the all-in-one bundle uses the following environment properties:</p>

<ul>
	<li><tt>org.apache.felix.http.jettyEnabled</tt> - True to enable jetty
as the http container. The default is <tt>false</tt>.</li>
	<li><tt>org.apache.felix.http.whiteboardEnabled</tt> - True to enable the
whiteboard implementation. The default is <tt>false</tt>.</li>
</ul>


<p>The Jetty based implementation supports the following Jetty specific configuration
as of Http Service Jetty Bundle 2.4:</p>

<ul>
	<li><tt>org.apache.felix.host</tt> - Host name or IP Address of the interface
to listen on. The default is <tt>null</tt> causing Jetty to listen on all interfaces.</li>
	<li><tt>org.apache.felix.http.context_path</tt> - The Servlet Context Path
to use for the Http Service. If this property is not configured it  defaults to "/". This
must be a valid path starting with a slash and not  ending with a slash (unless it is the
root context).</li>
	<li><tt>org.apache.felix.http.timeout</tt> - Connection timeout in milliseconds.
The default is 60000 (60 seconds).</li>
	<li><tt>org.apache.felix.http.session.timeout</tt> - Allows for the specification
of the Session life time as a number of minutes. This property serves the same purpose as
the <tt>session-timeout</tt> element in a Web Application descriptor. The default
is zero for no timeout at all.</li>
	<li><tt>org.mortbay.jetty.servlet.SessionCookie</tt> - Name of the cookie
used to transport the Session ID. The default is <tt>JSESSIONID</tt>.</li>
	<li><tt>org.mortbay.jetty.servlet.SessionURL</tt> - Name of the request
parameter to transport the Session ID. The default is <tt>jsessionid</tt>.</li>
	<li><tt>org.mortbay.jetty.servlet.SessionDomain</tt> - Domain to set on
the session cookie. The default is <tt>null</tt>.</li>
	<li><tt>org.mortbay.jetty.servlet.SessionPath</tt> - The path to set on
the session cookie. The default is the configured session context path (<tt>/</tt>).</li>
	<li><tt>org.mortbay.jetty.servlet.MaxAge</tt> - The maximum age value to
set on the cookie. The default is <tt>-1</tt>.</li>
	<li><tt>org.apache.felix.http.jetty.headerBufferSize</tt> - Size of the
buffer for request and response headers. Default is 16KB.</li>
	<li><tt>org.apache.felix.http.jetty.requestBufferSize</tt> - Size of the
buffer for requests not fitting the header buffer. Default is 8KB.</li>
	<li><tt>org.apache.felix.http.jetty.responseBufferSize</tt> - Size of the
buffer for responses. Default is 24KB.</li>
</ul>


<h2><a name="ApacheFelixHTTPService-ServletAPIEvents"></a>Servlet API Events</h2>

<p>The Servlet API defines a number of <tt>EventListener</tt> interfaces
to catch Servlet API related events. As of HTTP Service 2.1.0 most events generated by the
servlet container are forwarded to interested service. To be registered to receive events
services must be registered with the respective <tt>EventListener</tt> interface:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Interface </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>javax.servlet.ServletContextAttributeListener</tt>
</td>
<td class='confluenceTd'> Events on servlet context attribute addition, change and removal.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>javax.servlet.ServletRequestAttributeListener</tt>
</td>
<td class='confluenceTd'> Events on request attribute addition, change and removal.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>javax.servlet.ServletRequestListener</tt>
</td>
<td class='confluenceTd'> Events on request start and end. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>javax.servlet.http.HttpSessionAttributeListener</tt>
</td>
<td class='confluenceTd'> Events on session attribute addition, change and removal.
To receive such events in a bridged environment, the <tt>ProxyLister</tt> must
be registered with the servlet container. See the <em>Using the Servlet Bridge</em>
section above. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>javax.servlet.http.HttpSessionListener</tt>
</td>
<td class='confluenceTd'> Events on session creation and destroyal. To receive such
events in a bridged environment, the <tt>ProxyLister</tt> must be registered with
the servlet container. See the <em>Using the Servlet Bridge</em> section above.
</td>
</tr>
</tbody></table>
</div>


<p>Of the defined <tt>EventListener</tt> interfaces in the Servlet API,
the <tt>javax.servlet.ServletContextListener</tt> events are actually not support.
For one thing they do not make much sense in an OSGi environment. On the other hand they are
hard to capture and propagate. For example in a bridged environment the <tt>contextInitialized</tt>
event may be sent before the framework and any of the contained bundles are actually ready
to act. Likewise the <tt>contextDestroyed</tt> event may come to late.</p>


<h2><a name="ApacheFelixHTTPService-ServletContextNotes"></a>Servlet Context
Notes</h2>

<p><tt>ServletContext</tt> instances are managed internally by the Http
Service implementation. For each <tt>HttpContext</tt> instance used to register
one or more servlets and/or resources a corresponding <tt>ServletContext</tt>
instance is created. These <tt>ServletContext</tt> instances is partly based on
the single <tt>ServletContext</tt> instance received from the Servlet Container
&#8212; either embedded Jetty or some external Servlet Container when using the Http Service
Bridge &#8212; and partly based on the provided <tt>HttpContext</tt> instance:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> Method(s) </td>
<td class='confluenceTd'> Based on ... </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getContextPath</tt>, <tt>getContext</tt>,
<tt>getMajorVersion</tt>, <tt>getMinorVersion</tt>, <tt>getServerInfo</tt>
</td>
<td class='confluenceTd'> Servlet Containers <tt>ServletContext</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getResourcePaths</tt> </td>
<td class='confluenceTd'> <tt>Bundle.getEntryPaths</tt> of the bundle using
the Http Service </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getResource</tt>, <tt>getResourceAsStream</tt>
</td>
<td class='confluenceTd'> <tt>HttpContext.getResource</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getMimeType</tt> </td>
<td class='confluenceTd'> <tt>HttpContext.getMimeType</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getRequestDispatcher</tt>, <tt>getNamedDispatcher</tt>,
<tt>getInitParameter</tt>, <tt>getServlet</tt>, <tt>getRealPath</tt>
</td>
<td class='confluenceTd'> Always return <tt>null</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getInitParameterNames</tt>, <tt>getServlets</tt>,
<tt>getServletNames</tt> </td>
<td class='confluenceTd'> Always returns empty <tt>Enumeration</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getAttribute</tt>, <tt>getAttributeNames</tt>,
<tt>setAttribute</tt>, <tt>removeAttribute</tt> </td>
<td class='confluenceTd'> By default maintained for each <tt>ServletContext</tt>
managed by the Http Service. If the <tt>org.apache.felix.http.shared_servlet_context_attributes</tt>
framework property is set to <tt>true</tt> these methods are actually based on
the <tt>ServletContext</tt> provided by the servlet container and thus attributes
are shared amongst all <tt>ServlectContext</tt> instances, incl. the <tt>ServletContext</tt>
provided by the servlet container </td>
</tr>
</tbody></table>
</div>




<h2><a name="ApacheFelixHTTPService-Examples"></a>Examples</h2>

<p>A set of simple examples illustrating the various features are available. </p>

<ul>
	<li>Filter registration sample: <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/filter/"
class="external-link" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/http/samples/filter/</a></li>
	<li>Servlet bridge sample: <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge/"
class="external-link" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge/</a></li>
	<li>Whiteboard sample: <a href="http://svn.apache.org/repos/asf/felix/trunk/http/samples/whiteboard/"
class="external-link" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/http/samples/whiteboard/</a></li>
</ul>


<h2><a name="ApacheFelixHTTPService-MavenArtifacts"></a>Maven Artifacts</h2>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.api&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.base&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.bridge&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.bundle&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.jetty&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.proxy&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;org.apache.felix.http.whiteboard&lt;/artifactId&gt;
  &lt;version&gt;2.0.4&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>


    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+HTTP+Service">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=110503&revisedVersion=33&originalVersion=32">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+HTTP+Service?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message