The Apache Felix Web Console is extensible in various ways described on this page.
The Web Console can be extended by registering an OSGi service for the interface javax.servlet.Servlet with the service property felix.webconsole.label set to the label (last segment in the URL) of the page. The respective service is called a Web Console Plugin or a plugin for short.
The most basic plugin is a plain old Servlet whose service(ServletRequest, ServletResponse) method is called by the Apache Felix Web Console. Before calling the servlet the web console sets two request attributes helping the plugin rendering the response:
felix.webconsole.appRoot – This request attribute of type String provides the absolute path of the Web Console root. This path consists of the servlet context path (from <code>ServletRequest.getContextPath()</code>) and the Web Console servlet path (from HttpServletRequest.getServletPath(), /system/console by default). This attribute can be used to provide absolute links to resources (images, CSS, scripts, etc.) or other plugins.felix.webconsole.labelMap – This request attribute of type Map provides a mapping of labels to page titles of registered console plugins. This map may be used to render a navigation of the console plugins such as the AbstractWebConsolePlugin.renderTopNavigation method does. The keys and values of the map are of type String.To help rendering the response the Apache Felix Web Console bundle provides two options: One option is to extend the AbstractWebConsolePlugin overwriting the renderContent method. The other option is to register the servlet with another service registration property to indicate the desire to wrap the response.
To leverage the rendering of the common header and footer around the plugin's data area, the plugin can extend the abstract org.apache.felix.webconsole.AbstractWebConsolePlugin class implementing the following methods:
renderContext(HttpServletRequest, HttpServletResponse) – This method is called to render the actual plugin data area.getLabel() – Returns the last path segment of the plugin page. This should return the value to which the felix.webconsole.label service registration propery is set.getTitle() – Returns a human readable title to be displayed at the top of the plugin page.To fully leverage the AbstractWebConsolePlugin it must be initialiazed before registering the extension as a service. Likewise after unregistering the service, the plugin should be destroyed. To this avail the following methods are provided in the AbstractWebConsolePlugin:
activateBundle(BundleContext) – Initializes the plugin with the BundleContext and prepares some data to be rendered in the header and footer areas.deactivate() – Destroys the plugin.In addition to these OSGi-oriented setup methods the Web Console itself will call the Servlet.init(ServletConfig) method before putting the plugin into service and the Servlet.destroy() method when the plugin is removed.
While being very simple and straight forward, extending the AbstractWebConsolePlugin actually creates a binding from the plugin provider bundle to the Web Console bundle, which may be undesired. To support the use case of wanting the benefits of the AbstractWebConsolePlugin but wiring independency of the Web Console, a plugin servlet may be registered with a second service registration property (besides the required felix.webconsole.label):
felix.webconsole.title – If registered servlet does not extend the AbstractWebConsolePlugin but provides this property (of type String) the servlet is wrapped in an adapter to the AbstractWebConsolePlugin which calls Servlet.service(ServletRequest, ServletResponse) method on behalf of the renderContent implementation.The wrapper around the plugin itself extends the AbstractWebConsolePlugin as follows:
renderContext(HttpServletRequest, HttpServletResponse) – Calls the service(HttpServletRequest, HttpServletResponse) method of the plugin to render the actual contents of the plugin.getLabel() – Returns the value of the felix.webconsole.label service registration property of the plugin.getTitle() – Returns the value of the felix.webconsole.title service registration property of the plugin.service(ServletRequest, ServletResponse) – If the request method is GET the service(ServletRequest, ServletResponse) method of the AbstractWebConsolePlugin is called which ultimately calls the renderContent method. For all other requests, the service(ServletRequest, ServletResponse) method of the plugin is called directly to have the plugin handle any non-GET requests directly.It is suggested that plugins extend from the javax.servlet.http.HttpServlet class and implement the appropriate doXxx(HttpServletRequest, HttpServletResponse) methods such as doGet and doPost. In addition, unless non-GET requests are handled through AJAX calls, it is suggested that non-GET requests return a redirect after processing the request.
ResourceProvider && getResource && spool
Extending the Apache Felix Web Console with new functionality is as easy as registering a javax.servlet.Servlet with at least the felix.webconsole.label service registration property set (see above). Providing resources is a bit more complex and requires more work on behalf of the plugin.
Out of the box the Apache Felix Web Console plugin servces resources through the OSGi HttpContext used to register the web console with OSGi HttpService. This is done by registering resources with the HttpService below the /res alias. This mechanism though does not lend itself for easy extensibility. Therefore another mechanism has been chosen, which relies on similar mechanisms.
A web console plugin may implement a getResource method which is looked up using reflection. This method is called by the AbstractWebConsole.doGet to check whether the request is actually for a resource.
The method has the following signature:
|
modifier URL getResource(String path); |
Where the modifier may be public, protected, or private (if the method is declared in the class of the resource provider). It is suggested to use the private modifier if the method is declared in the resource provider class or the protected modifier if the method is declared in a base class of the resource provider.
This method is called with the path info of the request (HttpServletRequest.getPathInfo()) and expects and URL to the resource to be sent to the client. If the path cannot be resolved to a resource the getResource method is expected to return null thus causing regular processing of rendering the page.
If the getResource method returns an accessible non-null URL, the request is serviced by sending back the contents of the given URL. Simple caching support is included which handles the If-Modified-Since header and sets the Last-Modified header from the resource URL.
Branding the Web Consle mainly concerns hooking into the looks of the Web Console providing vendor-provided setup like
Branding support is currently work in progress tracked by FELIX-1015.
Task FELIX-1013 regarding extensibility of the web console is maintained in our resource tracking system. Please create issues regarding extensibility as subtasks of this master task or at least link to the master task as being related.
The following issues are already listed as part of FELIX-1013: