[CONF] Apache Felix: Apache Felix Web Console (page edited)

Tue, 09 Jun 2009 00:54:35 -0700

Page Edited : FELIX : Apache Felix Web Console

Apache Felix Web Console has been edited by Felix Meschberger (Jun 09, 2009).

(View changes)

Content:

The Apache Felix Web Console is a simple tool to inspect and manage OSGi framework instances using your favourite Web Browser.

Requirements

Top

The Web Console only has a single required dependency on the framework: A running implementation of the OSGi Http Service Specification. The reason for this is, that the Web Console is implemented as a servlet (actually just a gateway servlet dispatching to Web Console plugins) which is registered with the Http Service. If your framework does not yet have a Http Service installed, you might select from a variety of such implementations. The following is just an incomplete list:

  • Apache Felix HTTP Service. This is a very basic implementation of the OSGi Http Service based on Jetty 6.1.7. The Apache Felix HTTP Service has not been released yet, so you would have to build it yourself.
  • PAX Web Service. The PAX Web Service is the basis for a whole range of additions from the OPS4J project. The PAX Web Service is also based on Jetty 6 and may be dowloaded from the OPS4J PAX Web page.
  • Equinox HTTP Service implementation. You can get more information on the Equinox implementation from the Server-Side Equinox page.

Apart from that Web Console has the following dependencies, which do not need to be satisfied. In this case the respective functionality is just missing.

  • OSGi Log Service – The Log Service is used for logging. If the service is not available the Web Console prints logging to the standard output
  • OSGi Configuration Admin Service and OSGi Metatype Service – The Configuration Admin and Metatype services are used to support simple form based configuration administration
  • Apache Felix Declarative Services – If your framework uses the Apache Felix Declarative Services implementation, you can use to the Web Console to inspect the declared components available from the various bundles and managed by the Service Component Runtime.

Note, that the Apache Felix Declarative Services implementation is the only Apache Felix dependency contained in the Web Console. If you do not use the Apache Felix Declarative Services implementation, you just cannot inspect the declared components (because there is no official public API for this). Otherwise the Web Console perfectly operates without any problems.

Installation

Top

To install just use your favourite current means of installing new bundles in to the OSGi framework. For example using the Apache Felix shell console you might do:

> install http://mirror.switch.ch/mirror/apache/dist/felix/org.apache.felix.webconsole-1.0.0.jar
bundle x
> start x



where x is the bundle number printed by the Shell Console indicating the Bundle ID of the Web Console bundle.




Configuration


Top



The configuration of the Web Console consists of two parts: One part is the configuration of the Http Service defining at which host address (host and port number) the servlet container is accessible. This configuration is technically outside of the scope of the Web Console configuration. See below for more information and how this is influenced.



The second part of the Web Console configuration is the configuration of the console itself. The Web Console is configured using the OSGi Configuration Admin Service in that the Web Console registered a ManagedService with Service PID org.apache.felix.webconsole.internal.servlet.OsgiManager (of course you may well use the Web Console to edit the configuration of the Web Console itself).



The Web Console supports the following settings with their corresponding default values:






 Property 
 Default Value 
 Description 




 realm 
 OSGi Management Console 
 The name of the HTTP Authentication Realm. 




 username 
 admin 
 The name of the user allowed to access the OSGi Management Console. To disable authentication clear this value. 




 password 
 admin 
 The password for the user allowed to access the OSGi Management Console. 




 manager.root 
 /system/console 
 The root path to the OSGi Management Console. 




 default.render 
 bundles 
 The name of the default configuration page  when invoking the OSGi Management console. 






The default values apply if the respective property is missing from the configuration or if no configuration is provided at all.




Configuration of the OSGi Http Service



As said above, the configuration of the OSGi Http Service used by the Web Console to register itself is outside of the scope of the Web Console. Lets just say, the OSGi Http Service specification defines a system propety – org.osgi.service.http.port – which may be set to define the port at which the Http Service should listen for HTTP requests. The respective Http Service implementation may define additional properties to define the actual interface on which to listen or to define a servlet context path.



By default it is probably safe to assume, that having set the org.osgi.service.http.port to a defined value, the Http Service implementation will listen on all interfaces for requests at the set port number and that no servlet context path actually exists. For example, given the org.osgi.service.http.port property is set to 8888 the Web Console in the local system can be reached at : http://localhost:8888/system/console, where the /system/console path is configured using the manager.root configuration property (see the Configuration section).



If you happen to deploy an OSGi framework instance inside a traditional web application and thus the Http Service implementation is actually a bridge into the existing servlet container (see for example Equinox in a Servlet Container or the Apache Sling Launchpad Web application), the host, port and context path are defined by your servlet container and web application deployment. For example, if the servlet container listens on host sample.org at port 8888 and the web application with your OSGi container is available in the /osgi context, the Web Console would be accessible at http://sample.org:8888/osgi/system/console.




Security


Top



The Web Console only has very basic security at the moment supporting only HTTP Basic authentication. This security is enabled by default and may be disabled by simply clearing the username property.



To enhance the security of the Web Console you strongly encouraged to change at least the password for the admin user.




Browser Compliance


Top



The goal of the Web Console is to support as big a range of Web Browsers as possible. As it stands now, Firefox (versions 2 and 3), Opera and Internet Explorer (versions 6 and 7) seem to be capable of using the Web Console. Should you encounter any problems with your particular browser, please report an issue for the Web Console in our issue tracking system (JIRA).



Beginning with Release 1.2.8 the Web Console is using JQuery to enhance the user experience. This should also help in keeping browser support on the broadest possible basis.




Extending the Web Console


Top



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 AbstractWebConsolePlugin



To leverage the rendering of the common header and footer around the plugin's data area, the plugin must 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.




Helper



Before calling the plugin the Web Console sets the org.apache.felix.webconsole.internal.servlet.OsgiManager.appRoot request attribute to the root path of the web console consisting of the servlet context path (HttpServletRequest.getContextPath()) and the servlet path of the web console (HttpServletRequest.getServletPath()). This request attribute may be used by plugins to render absolute links.





Further issues with respect to extensions



    
	
  • It is currently not yet resolved how to add resources in plugins.
    • 
	
  • Many requirements exist to be able to customize some areas of look and feel of the console; most notably the logo and vendor links.
    • 






Issues


Top



Should you have any questions using the Web Console, please send a note to one of our Mailing Lists.



Please report any issues with the Web Console in our issue tracking system (JIRA) and be sure to report for the Web Console component. See our Issue Tracking page for more details.




Screenshots


Top






  
  
  




 Bundle List 
 Bundle Details 
 Declarative Services Components (requires Apache Felix SCR) 




  
  
  




 Configuration Admin 
 System Status 
 System Information

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences

Reply via email to