Apache

Providing Web Console Plugins

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:

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.

Extending The AbstractWebConsolePlugin

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:

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:

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.

Providing CSS Files

Part of rendering the header, the AbstractWebConsolePlugin also emits links to CSS files to include for displaying the page. Since such CSS links may only be present in the header section of the generated HTML the getCssReferences() method is provided. This method is called to create links for additional CSS files. The default implementation of this method returns null meaning no additional CSS links to be rendered. Extensions of the AbstractWebConsolePlugin may overwrite this method to provide a list of CSS links.

The CSS links provided by the getCssReferences() method may be absolute or relative paths, though relative paths are recommended. Relative paths are turned into absolute path by prepending them with the value of the felix.webconsole.appRoot request attribute.

Transparent Response Wrapping

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):

The wrapper around the plugin itself extends the AbstractWebConsolePlugin as follows:

Please note, that sometimes it is not desirable to have the AbstractWebConsolePlugin render the header and footer of the response. For this reason, the AbstractWebConsolePlugin only renders the header and footer if the request to such a wrapped plugin either has no extension or if the extension is .html. For any other extension, e.g. .txt or .json, the header and footer is not rendered and the service method of the plugin is directly called.

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.

Last modified by fmeschbe on Fri Nov 16 11:27:46 EST 2012
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.