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 Fri, 16 Nov 2012 16:28: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/Providing+Web+Console+Plugins">Providing
Web Console Plugins</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
        <br/>
                         <h4>Changes (2)</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> <br></td></tr>
            <tr><td class="diff-changed-lines" >* *{{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 &lt;code&gt;ServletRequest.getContextPath()&lt;/code&gt;)
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. <span class="diff-added-words"style="background-color:
#dfd;">This request attribute is available to client side JavaScript as the global *{{appRoot}}*
variable.</span> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*
*{{felix.webconsole.pluginRoot}}* -- This request attribute of type {{String}} provides the
absolute path of the current plugin. This path consists of the servlet context path (from
&lt;code&gt;ServletRequest.getContextPath()&lt;/code&gt;), the Web Console
servlet path (from {{HttpServletRequest.getServletPath()}}, {{/system/console}} by default)
and the plugin label. This attribute can be used to provide absolute links to the plugin itself.
This request attribute is available to client side JavaScript as the global *{{pluginRoot}}*
variable. <br></td></tr>
            <tr><td class="diff-unchanged" >* *{{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}}. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >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. <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <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>


<ul>
	<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. This request attribute is
available to client side JavaScript as the global <b><tt>appRoot</tt></b>
variable.</li>
	<li><b><tt>felix.webconsole.pluginRoot</tt></b> &#8211;
This request attribute of type <tt>String</tt> provides the absolute path of the
current plugin. This path consists of the servlet context path (from &lt;code&gt;ServletRequest.getContextPath()&lt;/code&gt;),
the Web Console servlet path (from <tt>HttpServletRequest.getServletPath()</tt>,
<tt>/system/console</tt> by default) and the plugin label. This attribute can
be used to provide absolute links to the plugin itself. This request attribute is available
to client side JavaScript as the global <b><tt>pluginRoot</tt></b>
variable.</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>
</ul>


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

<ul>
	<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>
</ul>


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

<ul>
	<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>
</ul>


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

<ul>
	<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>
</ul>



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

<ul>
	<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>
</ul>



<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>
        <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/Providing+Web+Console+Plugins">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=2853650&revisedVersion=4&originalVersion=3">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Providing+Web+Console+Plugins?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message