felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Providing Web Console Plugins
Date Thu, 24 Sep 2009 15:00:01 GMT
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/FELIX/Providing+Web+Console+Plugins">Providing
Web Console Plugins</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~fmeschbe">Felix
     update for SLING-1636 (header/footer only for html requests)
          <div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
     update for SLING-1636 (header/footer only for html requests)<br />
     <div class="notificationGreySide">
         <h1><a name="ProvidingWebConsolePlugins-ProvidingWebConsolePlugins"></a>Providing
Web Console Plugins</h1>

<p>The Web Console can be extended by registering an OSGi service for the interface
<tt>javax.servlet.Servlet</tt> with the service property <tt>felix.webconsole.label</tt>
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.</p>

<p>The most basic plugin is a plain old Servlet whose <tt>service(ServletRequest,
ServletResponse)</tt> 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:</p>

	<li><b><tt>felix.webconsole.appRoot</tt></b> &#8211; This
request attribute of type <tt>String</tt> provides the absolute path of the Web
Console root. This path consists of the servlet context path (from &lt;code&gt;ServletRequest.getContextPath()&lt;/code&gt;)
and the Web Console servlet path (from <tt>HttpServletRequest.getServletPath()</tt>,
<tt>/system/console</tt> by default). This attribute can be used to provide absolute
links to resources (images, CSS, scripts, etc.) or other plugins.</li>
	<li><b><tt>felix.webconsole.labelMap</tt></b> &#8211; This
request attribute of type <tt>Map</tt> 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 <tt>AbstractWebConsolePlugin.renderTopNavigation</tt> method
does. The keys and values of the map are of type <tt>String</tt>.</li>

<p>To help rendering the response the Apache Felix Web Console bundle provides two options:
One option is to extend the <tt>AbstractWebConsolePlugin</tt> overwriting the
<tt>renderContent</tt> method. The other option is to register the servlet with
another service registration property to indicate the desire to wrap the response.</p>

<h2><a name="ProvidingWebConsolePlugins-ExtendingTheAbstractWebConsolePlugin"></a>Extending
The AbstractWebConsolePlugin</h2>

<p>To leverage the rendering of the common header and footer around the plugin's data
area, the plugin can extend the abstract <tt>org.apache.felix.webconsole.AbstractWebConsolePlugin</tt>
class implementing the following methods:</p>

	<li><b><tt>renderContext(HttpServletRequest, HttpServletResponse)</tt></b>
&#8211; This method is called to render the actual plugin data area.</li>
	<li><b><tt>getLabel()</tt></b> &#8211; Returns the last
path segment of the plugin page. This should return the value to which the <tt>felix.webconsole.label</tt>
service registration propery is set.</li>
	<li><b><tt>getTitle()</tt></b> &#8211; Returns a human
readable title to be displayed at the top of the plugin page.</li>
	<li><b><tt>getCssReferences()</tt></b> &#8211; See the
section <em>Providing CSS Files</em> below.</li>

<p>To fully leverage the <tt>AbstractWebConsolePlugin</tt> 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 <tt>AbstractWebConsolePlugin</tt>:</p>

	<li><b><tt>activateBundle(BundleContext)</tt></b> &#8211;
Initializes the plugin with the <tt>BundleContext</tt> and prepares some data
to be rendered in the header and footer areas.</li>
	<li><b><tt>deactivate()</tt></b> &#8211; Destroys the plugin.</li>

<p>In addition to these OSGi-oriented setup methods the Web Console itself will call
the <tt>Servlet.init(ServletConfig)</tt> method before putting the plugin into
service and the <tt>Servlet.destroy()</tt> method when the plugin is removed.</p>

<h4><a name="ProvidingWebConsolePlugins-ProvidingCSSFiles"></a>Providing
CSS Files</h4>

<p>Part of rendering the header, the <tt>AbstractWebConsolePlugin</tt> 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 <tt>getCssReferences()</tt>
method is provided. This method is called to create links for additional CSS files. The default
implementation of this method returns <tt>null</tt> meaning no additional CSS
links to be rendered. Extensions of the <tt>AbstractWebConsolePlugin</tt> may
overwrite this method to provide a list of CSS links.</p>

<p>The CSS links provided by the <tt>getCssReferences()</tt> 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 <tt>felix.webconsole.appRoot</tt>
request attribute.</p>

<h2><a name="ProvidingWebConsolePlugins-TransparentResponseWrapping"></a>Transparent
Response Wrapping</h2>

<p>While being very simple and straight forward, extending the <tt>AbstractWebConsolePlugin</tt>
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 <tt>AbstractWebConsolePlugin</tt>
but wiring independency of the Web Console, a plugin servlet may be registered with a second
service registration property (besides the required <tt>felix.webconsole.label</tt>):</p>

	<li><b><tt>felix.webconsole.title</tt></b> &#8211; If registered
servlet does not extend the <tt>AbstractWebConsolePlugin</tt> but provides this
property (of type <tt>String</tt>) the servlet is wrapped in an adapter to the
<tt>AbstractWebConsolePlugin</tt> which calls <tt>Servlet.service(ServletRequest,
ServletResponse)</tt> method on behalf of the <tt>renderContent</tt> implementation.</li>
	<li><b><tt>felix.webconsole.css</tt></b> &#8211; Defines
a single string, an array of strings or a Collection of strings to be used as the values provided
by the <tt>getCssReferences()</tt> method. This property is optional. If this
property is missing or if the value does not have the correct type, the <tt>getCssReferences()</tt>
just returns <tt>null</tt> assuming there are no additional CSS resources to reference.</li>

<p>The wrapper around the plugin itself extends the <tt>AbstractWebConsolePlugin</tt>
as follows:</p>

	<li><b><tt>renderContext(HttpServletRequest, HttpServletResponse)</tt></b>
&#8211; Calls the <tt>service(HttpServletRequest, HttpServletResponse)</tt>
method of the plugin to render the actual contents of the plugin.</li>
	<li><b><tt>getLabel()</tt></b> &#8211; Returns the value
of the <tt>felix.webconsole.label</tt> service registration property of the plugin.</li>
	<li><b><tt>getTitle()</tt></b> &#8211; Returns the value
of the <tt>felix.webconsole.title</tt> service registration property of the plugin.</li>
	<li><b><tt>getCssReferences()</tt></b> &#8211; Returns
the values of the <tt>felix.webconsole.css</tt> service registration property
of the plugin.</li>
	<li><b><tt>service(ServletRequest, ServletResponse)</tt></b>
&#8211; If the request method is <tt>GET</tt> the <tt>service(ServletRequest,
ServletResponse)</tt> method of the <tt>AbstractWebConsolePlugin</tt> is
called which ultimately calls the <tt>service</tt> method. For all other requests,
the <tt>service(ServletRequest, ServletResponse)</tt> method of the plugin is
called directly to have the plugin handle any non-<tt>GET</tt> requests directly.</li>

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

<p>It is suggested that plugins extend from the <tt>javax.servlet.http.HttpServlet</tt>
class and implement the appropriate <tt>doXxx(HttpServletRequest, HttpServletResponse)</tt>
methods such as <tt>doGet</tt> and <tt>doPost</tt>. 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.</p>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>

       <a href="http://cwiki.apache.org/confluence/display/FELIX/Providing+Web+Console+Plugins">View
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=2853650&revisedVersion=3&originalVersion=2">View
       <a href="http://cwiki.apache.org/confluence/display/FELIX/Providing+Web+Console+Plugins?showComments=true&amp;showCommentArea=true#addcomment">Add

View raw message