{excerpt:hidden=true}Pax Web Extender Whiteboard is an extender bundle that ease the pain of registering servlets, resources, filters and listeners  and keeping track of Http Service availability.{excerpt}
{ops4j-style}

{warning}
Starting with May 25, 2009 Pax Web Extender has been merged into [paxweb:Pax Web].
The following information is only valid for versions before and including 0.5.1.
{warning}

{section}
{column:width=70%}
{ops4j-roundrect:Overview}

Pax Web Extender Whiteboard is an extender bundle that ease the pain of registering servlets, resources, filters and listeners  and keeping track of Http Service availability.
Note that the extender does not mandatory work with Pax Web, it can work with any Http Service implementation.

h4. Keeping track of Http Service availability
There are many situations that you have to handle as a bundle developer to keep track of http service availability:
* The Http Service is not present
* The Http Service gets started after your bundle starts
* The service gets unregister during the lifetime of your servlet
* A new service gets registered

Pax Web Extender handles all of this cases for you. You just have to have a servlet :)

h4. How does it work:
# [Publish|#publish] your [web elements|#elements] using one of the methods [bellow|#publish];
# Start the Pax Web Extender bundle. It does not matter if the Extender starts before or after you bundle or if is not even installed by the time your bundle starts.

h4. What Extender will do:
# Once it starts it will find out all [published|#publish] [web elements|#elements];
# Once a http service become available (including the moment when Extender starts) it will register all the [published|#publish] [web elements|#elements];
# If the in use http service gets unregister it will automatically unregister the (already) registered [web elements|#elements];
# If you register a [web element|#elements] as a service it will register it automatically with the http service in use (if any);
# If you unregister a [web element|#elements] it will unregister it automatically from the http service (if was registered before);
# If you stop your bundle all registered [web elements|#elements] are automatically unregister

{anchor:publish}
h4. How does it help on servlet registration
Usually you will have to register servlets by getting an http service and registering each servlet you have with the http service.
By using the whiteboard approach you will just have to register each servlet that you expect to be published to an http service under the Servlet interface ([see in jira|http://issues.ops4j.org/jira/browse/PAXWEBEX-2]):
{code}
Dictionary props = new Hashtable();
props.put( "alias", "/whiteboard" );
props.put("servlet-name", "My Servlet");
bundleContext.registerService( Servlet.class.getName(), new MyServlet(), props );
{code}

This is all you have to do to register a servlet. As you can see there is no necessity to lookup a http service or to track it's availability.

Nice to know: your bundle will not have to import/depend on Http Service packages.

(i) *Note:* Registering with Servlet names becomes necessary if you want to register a Filter against it. See below.

h4. How does it help on resource registration
Usually you will have to register resources by getting an http service and registering each resource dir you have with the http service.
By using the whiteboard approach you will just have to register each resource dir that you expect to be published to an http service under the Resources class ([see in jira|http://issues.ops4j.org/jira/browse/PAXWEBEX-4]):
{code}
import org.ops4j.pax.web.extender.whiteboard.ResourceMapping;
import org.ops4j.pax.web.extender.whiteboard.runtime.DefaultResourceMapping;
...
DefaultResourceMapping resourceMapping = new DefaultResourceMapping();
resourceMapping.setAlias( "/whiteboardresources" );
resourceMapping.setPath( "/images" );
bundleContext=bundleContext.registerService( ResourceMapping.class.getName(), resourceMapping, null );
{code}
Don't forget to import org.ops4j.pax.web.extender.whiteboard package.

This is all you have to do to register resources. As you can see there is no necesity to lookup a http service or to track it's availablity. The resources are served upon exact match, so listing directories in this fashion is not supported right now.

Note: your bundle must import org.ops4j.pax.web.extender.whiteboard package.

h4. How does it help on filter registration
Filters can be registered against URL Patterns and/or against Servlets (identified using their names).
{code}
Dictionary props = new Hashtable();
String[] urls = {"/foo", "/protected"};
String[] servlets = {"My Servlet", "Faces Servlet"};
props.put("filter-name", "My Crazy Filter");
props.put("urlPatterns", urls);
props.put("servletNames", servlets);
bundleContext.registerService(Filter.class.getName(), new MyCrazyFilter(), props );
{code}
(!) *Note:*
# For URL Patterns, the pattern registered must be already mapped, either as Resource or a Servlet alias - e.g there should already be a Resource or aServlet registered to the path {{/foo}}.
# For Servlet names, the names used should have been the name that has been explicitly given to the Servlet (as {{servlet-name}}), when registering.

h4. How does it help on listener registration
(!) TODO

{anchor:elements}
h4. Web elements
By web elements we mean any of http context, servlet, resources, filter, listener.

h4. Other resources
{children:excerpt=true}

h4. Issue tracker
Issues, bugs, and feature requests can be submitted to the [issue tracking system|http://issues.ops4j.org/jira/browse/PAXWEBEX?report=com.atlassian.jira.plugin.system.project:roadmap-panel].

{ops4j-roundrect}
{ops4j-roundrect:Usage}

h4. System requirements
* any OSGI R4 compilant framework
* (optional) any Http Service Implementation or [Pax Web] (if you need the extended functionality: context, filters, listeners)

{anchor:install}
h4. Manual installation
* Download the latest version from http://repository.ops4j.org/maven2/org/ops4j/pax/web-extender/pax-web-ex-whiteboard/
[0.5.1|http://repository.ops4j.org/maven2/org/ops4j/pax/web-extender/pax-web-ex-whiteboard/0.5.1/pax-web-ex-whiteboard-0.5.1.jar]
[0.5.0|http://repository.ops4j.org/maven2/org/ops4j/pax/web-extender/pax-web-ex-whiteboard/0.5.0/pax-web-ex-whiteboard-0.5.0.jar] [0.4.0|http://repository.ops4j.org/maven2/org/ops4j/pax/web-extender/pax-web-ex-whiteboard/0.4.0/pax-web-ex-whiteboard-0.4.0.jar] [0.3.0|http://repository.ops4j.org/maven2/org/ops4j/pax/web-extender/pax-web-ex-whiteboard/0.3.0/pax-web-ex-whiteboard-0.3.0.jar] [0.2.0|http://repository.ops4j.org/maven2/org/ops4j/pax/web-extender/pax-web-ex-whiteboard/0.2.0/pax-web-ex-whiteboard-0.2.0.jar]
* Deploy the downloaded bundle to your preferred OSGi framework

h4. [Pax Runner] installation
{code}
pax-run mvn:org.ops4j.pax.web-extender/pax-web-ex-whiteboard
{code}

{anchor:source}
h4. Source code
*[https://scm.ops4j.org/repos/ops4j/projects/pax/web-extender/whiteboard]* ( or [browse via FishEye|http://scm.ops4j.org/browse/OPS4J/projects/pax/web-extender/whiteboard] )
This project builds with [Apache Maven|http://maven.apache.org] and uses [Apache Felix|http://felix.apache.org]'s [maven-bundle-plugin|http://cwiki.apache.org/FELIX/bundle-plugin-for-maven-bnd.html], and Peter Krien's [bnd|http://www.aqute.biz/Code/Bnd] tool.

{ops4j-roundrect}
{column}
{column:width=30%}
{ops4j-roundrect:Latest News}

{blog-posts:5|labels=pax-web-extender-whiteboard}

{ops4j-roundrect}
{column}
{section}