felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1421893 [18/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/...
Date Fri, 14 Dec 2012 14:30:22 GMT
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-getting-started.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-getting-started.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-getting-started.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-getting-started.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,52 @@
+Title: UPnP Getting Started
+
+# Getting Started
+
+Assuming that, as described in [Building Felix]({{ refs.building-felix.path }}) web page, you have already checked out the Felix project in the $FELIX*HOME directory, the Felix UPnP project is located at $FELIX*HOME/trunk/upnp directory. The project is organized in different directories shown in Figure 1.
+
+!UPnP-Project-Structure.jpg!
+*Figure 1* The Felix UPnP project structure
+
+The *basedriver* directory contains the project of the bundle implementing the UPnP spec. In the *samples{*}directory there are three projects implementing simple test devices, while the *tester* and *extra* directories are projects providing additional utilities for the UPnP development. At last, the *doc* directory contains this documentation and a script file to launch all the Felix UPnP bundles.
+
+After building the Felix project, you can start the script file "upnp.sh.bat" inside the /upnp/doc directory; it launches a Felix runtime with all the UPnP bundles released by the project. The script file defines a profile called "upnp" and the list of bundles\[1\]({{ refs.1.path }})installed with the profile is shown in Figure 2. The UPnP Tester is a bundle that provides a browser utility to control and subscribe all the UPnP devices registered with the OSGi framework. After executing the script, you should see in the window opened by the UPnP Tester bundle three UPnP devices (left panel in Figure 3.a), which correspond to the TV, Clock and BinaryLight devices shown in Figure 3. Of course the number of discovered devices may be higher if other UPnP devices are installed in your local network
+
+!Bundle-List.jpg!
+*Figure 2* Bundles installed by the script "upnp.sh.bat"
+
+To stop the devices launched by the script you can close their windows, while to start them again type "start 10 11 12 13" from the Felix shell. See the sections "[Testing UPnP devices]({{ refs.upnp-testing-devices.path }})" and "[The UPnP Examples|UPnP Examples]" for details on how to use the these bundles.
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+                     d) UPnP BinaryLight |
+*Figure 3* The GUIs started by the script "upnp.sh.bat"
+
+The Felix build process by default uses the JDK1.4 as target class library for all the UPnP bundles. The UPnP Base Driver can be built also with the JDK1.3 as target; to this end you have to define the "platform" property in the command line: type "mvn Dplatform=jdk13 install" from the /upnp/basedriver directory. For details on configuring your Eclipse IDE see \[3\]({{ refs.3.path }}).
+
+### Common Issues
+
+If you experience problems discovering the UPnP devices of your network:
+* Check the configuration of your firewalls. UPnP discovery is based on multicast messages over UDP that usually are not filtered by firewalls, on the contrary the XML description of devices is retrieved using HTTP protocol; usually bound to non standard ports which might be blocked. Check whether firewall is active on your host or on the host of the device you want discover.
+* Install a loopback interface if needed. The base driver by default is configured for not using the localhost as loopback interface. If you want to run and test UPnP devices on a machine disconnected by any network, you should install and activate a loopback interface. Pay attention to disable the loopback interface when you are connected to a network again, otherwise both interfaces will be used to expose the UPnP services registered with the framework.
+  
+  
+  
+  
+
+##### [Introduction ]({{ refs.apache-felix-upnp.path }}) << \| >> [Overview of the Base Driver Architecture|UPnP Driver architecture]
+
+----
+\[1\]({{ refs.1.path }}) The actual version of the bundles may be different
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-known-issues.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-known-issues.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-known-issues.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-known-issues.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,13 @@
+Title: UPnP Known Issues
+
+# Known issues
+
+
+Currently the bundle does not support the following requirements:
+* upnp.ssdp.address Configuration Service
+* exported device changes: if a service already exported as UPnP Device changes its own configuration, i.e.: implements new service, changes the friendly name, etc., the new service description is not reflected on the UPnP Device
+* icons for exported device are not tested
+* no localization support
+
+
+##### [Writing UPnP Devices and Control Points]({{ refs.upnp-writing-cd-and-cp.path }}) << | >> [Acknowledgments |UPnP Acknowledgments ]

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,38 @@
+Title: UPnP Testing Devices
+
+# Testing UPnP devices&nbsp;
+
+The *org.apache.felix.upnp.tester* bundle installs a component that shows the UPnP devices registered with the OSGi framework. It provides a GUI shown in the Figure 6 that can be used for controlling the discovered devices: by invoking actions and by subscribing for the state variable changes occurring on them.
+
+!TesterGUI.jpg!
+Figure6 The UPnP Tester GUI
+
+
+In the left panel you can browse the devices discovered on the OSGi platform. Remember that they may be registered by the base driver as well as by other bundles installed on the platform. Therefore stopping the base driver you will continue to see the local devices, but they will be no more exported. The devices with their hierarchy of the embedded devices and services are represented as nodes of a tree with the following icons:
+* !RootDevice.gif! Root Device
+* !EmbeddedDevice.gif! Embedded Device
+* !Service.gif! Service
+* !Action.gif! Action
+* !StateVariable.gif! State Variable
+* !EventedSteateVariable.gif! Evented State Variable
+* !SubscribedStateVariable.gif! Subscribed State Variable
+
+By clicking on the Root Device icon, the register properties defined by the device are shown on the right panel. You can distinguish between exported and imported devices by looking for the property key "UPnP.export" and "UPnP.device.imported" respectively.
+
+By right-clicking on the Root Device, Embedded device, or Service icon a context menu is displayed to open the XML description of devices and services (see Figure 6)
+
+By clicking on the Service icon, the Service Id and Type are shown in the right panel together with buttons for subscribing all the state variables of the service. The received notify message is displayed on the bottom panel.
+
+By clicking on the Action icons, the right panel displays a form where the input parameters of the action can be inserted. Use the "do Action" button to execute it; the results, if any, will be displayed in the table below the input parameters.
+
+Finally, by clicking on the state variables shows the associated property keys as the default value and minimum and maximum value, if any.
+
+*Menus*
+* The "Search" menu forces the UPnP Base Driver to execute a UPnP M-Search for UPnP Root Devices or for all types of devices. This search is usually automatically executed during the start up of the base driver.
+* The "Felix Logger" and "Cyber Debugger" menus enable displaying of the messages received and sent by the base driver (i.e. the content of the UDP communication).
+* The "Print Pending Devices" is a utility menu to verify whether incomplete hierarchy of embedded devices have been registered with the framework.
+* The "Check Errata UPnPDevices" menu may help the user verify that all the local UPnP Devices have been registered with the mandatory properties, otherwise they would not be exported.
+  
+  
+
+##### [Overview of the Base Driver Architecture]({{ refs.upnp-driver-architecture.path }}) << \| >> [The Felix UPnP Examples| UPnP Examples]

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,24 @@
+Title: UPnP Examples
+
+# The Felix UPnP Examples
+
+The UPnP examples released by the UPnP project are simple UPnP devices developed as a proof of concept. The first two examples, the TV and Clock, are used to check the importing and exporting capabilities of the base driver. The third one, the Binary Light, implements a standard UPnP DCP and provides additionally a UPnP presentation page.
+
+## Sample TV and Clock
+
+These devices are dual version of the sample devices developed by the project "Cyberlink for Java" by Satoshi Konno. They have been rewritten according to the OSGi specification and can be used to check the importing and exporting capabilities of the base driver. The simulated TV screen is used to show the messages received by the Clock device and other simulated device like the Air Conditionator and Washing Machine. When launching the original version of such devices you will see that the Felix TV running on the OSGi platform is able to receive the messages from UPnP devices running on different platform and imported in OSGi. At the same time, the Cyberlink TV is able to receive the time event generated by the Felix Clock device and exported by the base driver.
+| !FelixUPnPTV.jpg! | !FelixClock.jpg! |
+| *Figure 7* The Felix UPnP TV GUI | *Figure 8* The Felix UPnP Clock GUI |
+If you want to avoid installing the Cyberlink devices, you can run a second instance of Felix by clicking on the batch file again. In this case the Felix TV and Clock will be exported and re-imported by both Felix runtimes and you will see a duplicated TV and Clock device on each platform. Notice that you can stop in any moment a device by closing its window. You can start it again from the Felix shell by selecting the respective bundle ID. Starting with two running instances of the Felix Clock, you can stop the first one and the TVs will lose for a moment the time signal. In fact, being subscribed to the Clock device type and not to a specific device instance, they will receive the time event from the remaining device Clock. One TV will be notified from the clock running on the same platform, while the other will receive the events from an imported TV device. As soon as you stop also the second clock device, the Time message will disappear from both the TVs.
+
+## The BinaryLight example
+
+The Binary Light device, according the UPnP DCP, shows a graphical interface you can use to switch on/off the light and to simulate the breaking of the lamp bulb. In this last circumstance you can see, by using the Felix UPnPDevice Tester interface, that the values of the "Status" and "Target" variable may be different. While the "Target" variable represents the expected status after invoking the related action, the "Status" variable describes the real status of the Light Device.
+This example, by exploiting the Felix HTTP Service implementation, installs a UPnP presentation page. By code you can retrieve the presentation page URL by looking for the service property called "UPnP.presentationURL". This property is also visible, as link, through the interface provided by the Tester bundle. Accessing the presentation page by means of a web browser you can switch the light status by clicking on the Light image: the icon on the device windows changes accordingly.
+| !FelixLight.jpg! | !FelixLightBroken.jpg! | !LightPresentationPage.jpg! |
+*Figure 9* The BinaryLight  GUI and the presentation page
+
+
+The source code for the Binary light is slightly different from the one for TV and Clock code because it has been written starting from a Light model which notifies its changes through the PropertyChangeListener interface. 
+
+##### [Testing UPnP Devices]({{ refs.upnp-testing-devices.path }}) << \| >> [Writing UPnP Devices and Control Points| UPnP Writing CD and CP]

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,60 @@
+Title: UPnP Writing CD and CP
+
+# Writing UPnP Devices and Control Points
+
+The [OSGi UPnP Specification (v 1.1)](http://www.osgi.org/Specifications/HomePage) dedicates section 111.6 "Working with a UPnP Device" to describe the details of implementing UPnP Devices on OSGi. Here we provide some hints on the main differences you may encounter working with OSGi with respect to the [UDA 1.0 Specification|http://www.upnp.org/resources/documents/CleanUPnPDA101-20031202s.pdf] .
+
+The first peculiarity is that OSGi provides a centralized register for discovering of UPnP devices as opposed to the distributed mechanism of the UPnP protocol stack. Thus, while in the UPnP networks the steps for subscribing the services of some device are typically 1) *discover* the required device and 2) *subscribe* the service, within the OSGi platform a Control Point may register an interest in receiving notify events even before the device is really plugged on the network. This is possible because the subscription mechanism is based on the [UPnPEventListener](http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPEventListener.html)interface that is used for registering OSGi services, which ultimately handles the notify messages sent by the producers of the events. The base driver (importer) keeps track of such UPnPEventListener services and as soon as a matching service is discovered on the UPnP network, a subscription is made on behalf of the registered listeners.
+
+On the other hand, even if it is enough to register a service implementing the [UPnPDevice](http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html)interface to expose it as UPnP devices on the network, the developers have to implement on their own the event management required by the UPnP technology. From this point of view, for each evented state variable declared by the UPnP device, the developers have to monitor UPnPEventListenerservices that is error prone\[1\]. The correct implementation of the UPnP eventing phase is left entirely to developers. In particular, in UDA 1.0, the first time a Control Point subscribes a service, the current value of its state variables should soon be delivered to it. To manage this situation in a standard way, the last OSGi UPnP specification defined the extended interface [UPnPLocalStateVariable|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPLocalStateVariable.html]. In fact, the previous basic interface UPnPStateVar
 iable provided only a descriptive interface which did not enable to get the value of a state variable without knowing the final implementation class. Every developer should use this new interface in order to allow the specification of helper classes that ease the subscription/notify management (see [UPnPEventNotifier|http://svn.apache.org/viewvc/felix/trunk/upnp/extra/src/main/java/org/apache/felix/upnp/extra/util/UPnPSubscriber.java?view=markup] below).
+
+We have factorized and released part of the code used by the UPnP examples with the *org.apache.felix.upnp.extra* bundle.
+
+## The Extra bundle and the driver interfaces
+
+We provide some utility classes and services through the extra bundle and the services registered by the UPnP Base Driver.
+
+In the Extra bundle the class [org.apache.felix.upnp.extra.util.UPnPSubscriber](http://svn.apache.org/viewvc/felix/trunk/upnp/extra/src/main/java/org/apache/felix/upnp/extra/util/UPnPSubscriber.java?view=markup) can be instantiated to subscribe one or more services. The constructor takes two parameters a [BundleContext |http://www.osgi.org/javadoc/r4/org/osgi/framework/BundleContext.html] reference and a [UPnPEventListener |http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPEventListener.html] reference. In this class the method subscribe(Filter aFilter) is a general and powerful way to subscribe to any service by using an [LDAP filter|http://www.osgi.org/javadoc/r4/org/osgi/framework/Filter.html]. For example by using the string :
+
+    "(& (UPnP.device.type=urn:schemas-upnp-org:device:BinaryLight:1) (UPnP.service.type= urn:schemas-upnp-org:service:SwitchPower:1))"
+
+we would subscribe to the SwitchPower service offered by any device implementing the BinaryLight profile. Looking at the Felix UPnP TV sample code, the UPnPSubscriber class is used in the file [org.apache.felix.upnp.sample.tv.TVDevice](http://svn.apache.org/viewvc/felix/trunk/upnp/samples/tv/src/main/java/org/apache/felix/upnp/sample/tv/TvDevice.java?view=markup) to subscribe to the different service types offered by the Cyberlink sample devices. However, in this case, the utility method {color:black}{*}subscribeEveryServiceType{*}{color} is used to provide just the device and service types.
+
+    private final static String CLOCK_DEVICE_TYPE = "urn:schemas-upnp-org:device:clock:1";
+    private final static String TIME_SERVICE_TYPE = "urn:schemas-upnp-org:service:timer:1";
+    
+    private final static String LIGHT_DEVICE_TYPE = "urn:schemas-upnp-org:device:light:1";
+    private final static String POWER_SERVICE_TYPE = "urn:schemas-upnp-org:service:power:1";
+    
+    private final static String AIRCON_DEVICE_TYPE = "urn:schemas-upnp-org:device:aircon:1";
+    private final static String TEMP_SERVICE_TYPE = "urn:schemas-upnp-org:service:temp:1";
+    
+    private final static String WASHER_DEVICE_TYPE = "urn:schemas-upnp-org:device:washer:1";
+    private final static String STATUS_SERVICE_TYPE = "urn:schemas-upnp-org:service:state:1";
+    
+    public void doSubscribe() {
+      subscriber = new UPnPSubscriber(Activator.context, this);
+      subscriber.subscribeEveryServiceType(CLOCK_DEVICE_TYPE, TIME_SERVICE_TYPE);
+      subscriber.subscribeEveryServiceType(AIRCON_DEVICE_TYPE, TEMP_SERVICE_TYPE);
+      subscriber.subscribeEveryServiceType(LIGHT_DEVICE_TYPE, POWER_SERVICE_TYPE);
+      subscriber.subscribeEveryServiceType(WASHER_DEVICE_TYPE, STATUS_SERVICE_TYPE);
+    }
+    
+    public void undoSubscribe(){
+           subscriber.unsubscribeAll();}
+
+The class [org.apache.felix.upnp.extra.util.UPnPEventNotifier](http://svn.apache.org/viewvc/felix/trunk/upnp/extra/src/main/java/org/apache/felix/upnp/extra/util/UPnPEventNotifier.java?view=markup) is a utility class that manages the delivery of notifications for you. There are two constructors. The first one takes a [BundleContext|http://www.osgi.org/javadoc/r4/org/osgi/framework/BundleContext.html], a [UPnPDevice|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html] , and a [UPnPService |http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPService.html] reference. They are internally used to keep trace of all the registered UPnPEvenListener that are interested in monitoring events generated by your UPnP service. UPnPEventNotifier implements the java beans [PropertyChangeListener |http://java.sun.com/j2se/1.4.2/docs/api/java/beans/PropertyChangeListener.html] interface; once changes of the service state variables occurs you should call the method propert
 yChange(PropertyChangeEvent evt). Alternatively, you may use the second constructor to pass a reference to a model implementing the interface: [EventSource |http://svn.apache.org/viewvc/felix/trunk/upnp/extra/src/main/java/org/apache/felix/upnp/extra/util/EventSource.java?view=markup] defined in the Extra bundle. This model should use the [PropertyChangeSupport |http://java.sun.com/j2se/1.4.2/docs/api/java/beans/PropertyChangeSupport.html] to keep trace of PropertyChangeListener, {color:}and the related method firePropertyChange{color} to notify changes. The {color:black}EventSource{color} interface is used internally by the UPnPEventNotifier to register itself as propertychangeListener of the model. Thus, in this case, you don't have to call propertyChange()directly: it is a duty of your model. As an example, take a look at [LightModel |http://svn.apache.org/viewvc/felix/trunk/upnp/samples/binarylight/src/main/java/org/apache/felix/upnp/sample/binaryLight/LightModel.java?vi
 ew=markup] class in the BinaryLight bundle{color:black}.{color}
+
+The Felix UPnP base driver registers a non standard service implementing two interfaces:
+
+[org.apache.felix.upnp.basedriver.controller.DevicesInfo](http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/basedriver/controller/DevicesInfo.java?view=markup);
+[org.apache.felix.upnp.basedriver.controller.DriverController](http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/basedriver/controller/DriverController.java?view=markup);
+
+The former can be used to retrieve the XML description of both devices and services. Other than be used for debugging purpose, it allows access to the UPnP schema extensions defined by UPnP Vendors. According to the UDA 1.0 they consist of elements inserted in different points of the XML description and by convention starting with the prefix "X_". This interface is used by the context menu handler of the UPnP Tester bundle.
+
+The latter interface can be used to change the log messages of the base driver at runtime. Two different methods are available to modify the log level of the base driver or to enable the visualization of low level messages related to the UPnP stack protocol (CyberDomo). Furthermore, the interface allows developers to send an M-SEARCH discovery message to the UPnP networks, thus refreshing the list of imported devices.
+
+
+##### [The Felix UPnP Examples]({{ refs.upnp-examples.path }}) << \| >> [Known Issues| UPnP Known Issues]
+----
+\[1\]({{ refs.1.path }}) Developers should monitor UPnpEventListener services with a filter matching either the own service Id or service type, either the own device Id or device type and even a empty filter which are usually used to express interest for every UPnP device.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,14 @@
+Title: Apache Felix User Admin
+
+# Apache Felix User Admin
+
+{include:Apache Felix User Admin - Introduction}
+
+## Table of contents
+
+* [Background]({{ refs.apache-felix-user-admin-background.path }}) explains the problem being solved and the main design goals;
+* [Getting Started]({{ refs.apache-felix-user-admin-getting-started.path }}) helps you with the basic concepts by example;
+* [Using the file store]({{ refs.apache-felix-user-admin-file-store.path }}) helps you with using the file-based repository store;
+* [Using the MongoDB store]({{ refs.apache-felix-user-admin-mongodb-store.path }}) helps you with using the MongoDB-based repository store;
+* [Writing custom repository stores]({{ refs.apache-felix-user-admin-custom-repository-store.path }}) helps you in writing your own repository store.
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-background.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-background.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-background.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-background.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,20 @@
+Title: Apache Felix User Admin - Background
+
+For a detailed overview on the UserAdmin service, see the OSGi compendium specification version 4.0 or later. 
+
+## Roles
+
+The UserAdmin service defines two types of roles: *users* and *groups*. Other types of roles are not and cannot be defined.
+
+### Users
+
+According to the UserAdmin specification, a `User` role refers to "??any entity that may have any number of credentials associated with it that it may use to authenticate itself??." Normally, `User` roles are used to authenticate an initiator of a certain action. Although the name suggests otherwise, a `User` role can also denote anything other than a human being. Examples of valid `User` roles are:
+
+* A human being with a username and password;
+* A machine with a hostname and SSL-certificate.
+
+### Groups
+
+A group is an aggregation of other users and groups, allowing you to create authorization schemes. Roles are either *required* or *basic* members of a group. The basic members of a group define the set of members that can be authorized. This set is further reduced by requiring an initiator of an action to imply all required member of a group. A group can be implied only if it has at least one basic member and at least one required member. 
+
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-file-store.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-file-store.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-file-store.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-file-store.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,11 @@
+Title: Apache Felix User Admin - File Store
+
+The Apache Felix User Admin file store provides a file-based store for use with the Felix UserAdmin service. It uses a binary file-format to persist the role information. This file will always be written in the data area of the bundle and be called "`ua_repo.dat`".
+
+The file-based store service this bundle provides can be configured at runtime by using the service PID "`org.apache.felix.useradmin.filestore`". The configuration options recognized by this service are:
+
+* "`background.write.disabled`"; by default, all changes made to the UserAdmin repository are flushed to disk. By setting this value to "`true`", this no longer will happen for each change, but only when the file-store service is stopped. This value is optional and defaults to "`false`";
+* "`background.write.delay.value`"; denotes the period after which the changes should be persisted to disk. If other changes to the repository occur during this period, the period will start over. This value is optional and defaults to "`500`";
+* "`background.write.delay.timeunit`"; denotes the time unit for "background.write.delay.value". This value is optional and defaults to "`milliseconds`". Possible values are: "`days`", "`hours`", "`minutes`", "`seconds`", "`milliseconds`", "`microseconds`" and "`nanoseconds`".
+
+Alternatively, one can also supply the above mentioned configuration keys prefixed with "`org.apache.felix.useradmin.filestore.`" as system properties. For example by adding `-Dorg.apache.felix.useradmin.filestore.background.write.disabled=true` to your JVM arguments will disable persisting the changes upon each change. However, using system properties will imply that only a single store can be configured on a system (which could be a sensible default for some situations)!

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-getting-started.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-getting-started.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-getting-started.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-getting-started.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,31 @@
+Title: Apache Felix User Admin - Getting Started
+
+## Authentication
+
+To test whether an initiator of an action is known to the UserAdmin service, it should be authenticated. To authenticate a user, you typically do something like:
+
+{code:java}
+private UserAdmin m_userAdmin;
+// ...
+User user = m_userAdmin.getUser("username", getUserName());
+if (user == null || !user.hasCredential("password", getPassword())) {
+  throw new InvalidUsernameOrPasswordException();
+}
+
+    
+    h2. Authorization
+    
+    Only authorized users should be able to initiate privileged actions. Whether a user is authorized to do so depends on its membership in groups. The UserAdmin service aids in this by providing an {{Authorization}} facade that helps you to determine whether or not users are authorized to initiate certain actions.
+    
+    Note that the UserAdmin only provides answer to the question whether a user is allowed to initiate a certain action, it does not actually shield it from doing this, like, for example, the SecurityManager in Java. This means that the common pattern used to authorize users with UserAdmin looks something like:
+    
+    {code:java}
+    private UserAdmin m_userAdmin;
+    // ...
+    User user = m_userAdmin.getUser("username", getUserName());
+    // assume user is already authenticated...
+    Authorization auth = m_userAdmin.getAuthorization(user);
+    if (!auth.hasRole("admin")) {
+      throw new InsufficientRightsException();
+    }
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-introduction.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-introduction.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-introduction.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-introduction.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,3 @@
+Title: Apache Felix User Admin - Introduction
+
+The Apache Felix User Admin provides an implementation of the OSGi UserAdmin compendium service. It allows you to manage roles (users and groups), define RBAC-like authorization schemes and test whether certain roles are authorized to initiate certain actions. 

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-mongodb-store.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-mongodb-store.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-mongodb-store.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-user-admin/apache-felix-user-admin-mongodb-store.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,16 @@
+Title: Apache Felix User Admin - MongoDB Store
+
+The Apache Felix User Admin MongoDB store provides a MongoDB-based store for use with the Felix UserAdmin service. It uses MongoDB to persist the role information.
+
+Note that this driver additionally needs the [MongoDB java driver](http://www.mongodb.org/display/DOCS/Java+Language+Center) in order to operate! 
+
+The MongoDB-based store service this bundle provides can be configured at runtime by using the service PID "`org.apache.felix.useradmin.mongodb`". The configuration options recognized by this service are:
+
+* "`server`": a space separated string containing the MongoDB servers. The format for this string is: "`<host1:port1> <host2:port2>`". This value is optional and defaults to "`localhost:27017`";
+* "`dbname`": a string value containing the name of the database to use for this store. This value is optional and defaults to "`ua_repo`";
+* "`collection`": the name of the database collection to use for this store. This value is optional and defaults to "`useradmin`";
+* "`username`": a string value representing the name of the user to authenticate against MongoDB. This value is optional and defaults to "" (empty string);
+* "`password`": a string value representing the password to authenticate against MongoDB. This value is optional and defaults to "" (empty string). 
+
+Alternatively, one can also supply the above mentioned configuration keys prefixed with "`org.apache.felix.useradmin.mongodb.`" as system properties. For
+example by adding `-Dorg.apache.felix.useradmin.mongodb.server=my.mongo.server:29000` to your JVM arguments will let this service use the MongoDB server at "`my.mongo.server`" on port 29000. However, using system properties will imply that only a single store can be configured on a system (which could be a sensible default for some situations)!
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,159 @@
+Title: Apache Felix Web Console
+
+
+
+# Apache Felix Web Console
+
+[TOC]
+
+The Apache Felix Web Console is a simple tool to inspect and manage OSGi framework instances using your favourite Web Browser.
+
+
+## Requirements
+[Top]({{ refs.-top.path }})
+
+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](http://www.ops4j.org) project. The PAX Web Service is also based on Jetty 6 and may be dowloaded from the [OPS4J PAX Web|http://wiki.ops4j.org/confluence/display/ops4j/Pax+Web] page.
+   * Equinox HTTP Service implementation. You can get more information on the Equinox implementation from the [Server-Side Equinox](http://www.eclipse.org/equinox/server/) 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.
+
+
+
+## Variants
+[Top]({{ refs.-top.path }})
+
+The Web Console Bundle is available in two variants: A *full* variant and a *bare* variant. The *full* variant embeds three Java libraries which are not embedded in the *bare* variant. The *bare* variant expects the packages provided by those libraries to be exported from bundles installed in the framework.
+
+The three libraries are :
+
+  * Apache Commons IO
+  * Apache Commons FileUpload
+  * JSON
+
+Version 2.0.6 is the first release providing a *bare* variant. In this release both variants have the same symbolic name but a different file name: `org.apache.felix.webconsole-2.0.6.jar` for the *full* variant and `org.apache.felix.webconsole-2.0.6-bare.jar` for the *bare* variant. This is [considered a bug](https://issues.apache.org/jira/browse/FELIX-2086) and will be fixed in the next release as follows:
+
+  * *Full* variant symbolic name: `org.apache.felix.webconsole`
+  * *Bare* variant symbolic name: `org.apache.felix.webconsole.bare`
+
+
+## Installation
+[Top]({{ refs.-top.path }})
+
+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-2.0.6.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]({{ refs.-top.path }})
+
+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 |
+|--|--|--|
+| `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. |
+| `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. |
+| `plugins` | all plugins enabled | The labels of the plugins enabled and displayed. |
+| `loglevel` | `2` | Log level filter for the `AbstractWebConsole` log methods. This is an integer value matching the levels defined by the OSGi Log Service. |
+| `locale` | -- | If set, this locale forces the localization to use this locale instead of the one requested by the web browser. |
+
+The default values apply if the respective property is missing from the configuration or if no configuration is provided at all.
+
+
+#### Framework Properties
+
+Some of the configuration properties supported through the OSGi Configuration Admin service can also be set globally and statically as framework properties. Such framework properties will also be considered actual default values for missing properties in Configuration Admin configuration as well as for the Metatype descriptor.
+
+| Framework Property | Configuration Admin Property |
+|--|--|
+| `felix.webconsole.manager.root` | `manager.root` |
+| `felix.webconsole.realm` | `realm` |
+| `felix.webconsole.username` | `username` |
+| `felix.webconsole.password` | `password` |
+| `felix.webconsole.loglevel` | `loglevel` |
+| `felix.webconsole.locale` | `locale` |
+
+Please note that setting any of these properties as framework property makes them visible to all bundles deployed. This is particularly to be considered in case of the `felix.webconsole.password` property (as for authentication, the use of a [Web Console Security Provider]({{ refs.web-console-security-provider.path }}) is suggested anyway).
+
+#### 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](http://www.eclipse.org/equinox/server/http*in*container.php) 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]({{ refs.-top.path }})
+
+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.
+
+As of Web Console 3.1.0 this simple user setup can be extended by providing [Web Console Security Provider]({{ refs.web-console-security-provider.path }}). See that page for more information.
+
+
+## Browser Compliance
+[Top]({{ refs.-top.path }})
+
+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](https://issues.apache.org/jira/browse/Felix)).
+
+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]({{ refs.-top.path }})
+
+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.
+
+Please for to the [Extending the Apache Felix Web Console]({{ refs.extending-the-apache-felix-web-console.path }}) for full documentation on extending the Apache Felix Web Console.
+
+
+## RESTful API
+[Top]({{ refs.-top.path }})
+
+While the Web Console does not have a full featured and documented REST-ful API, most plugins try to follow REST approaches. For example the Bundles plugin is able to send information on all bundles or a single directly addressed bundle.
+
+An attempt is made to document the current state of REST-like APIs at [Web Console RESTful API]({{ refs.web-console-restful-api.path }})
+
+
+## Issues
+[Top]({{ refs.-top.path }})
+
+Should you have any questions using the Web Console, please send a note to one of our [Mailing Lists]({{ refs.mailinglists.path }}).
+
+Please report any issues with the Web Console in our issue tracking system ([JIRA](https://issues.apache.org/jira/browse/Felix)) and be sure to report for the *Web Console* component. See our [Issue Tracking] page for more details.
+
+
+## Screenshots
+[Top]({{ refs.-top.path }})
+
+| !console-bundles.png|thumbnail! | !console-bundles-details.png|thumbnail! | !console-components.png|thumbnail! |
+| Bundle List | Bundle Details | Declarative Services Components (requires Apache Felix SCR) |
+| !console-config.png|thumbnail! | !console-status.png|thumbnail! | !console-system-info.png|thumbnail! |
+| Configuration Admin | System Status | System Information |

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,12 @@
+Title: Extending the Apache Felix Web Console
+
+# Extending the Apache Felix Web Console
+
+The [Apache Felix Web Console]({{ refs.apache-felix-web-console.path }}) is extensible in various ways described no these pages:
+
+* [Providing Web Console Plugins]({{ refs.providing-web-console-plugins.path }})
+* [Providing Resources]({{ refs.providing-resources.path }})
+* [Branding the Web Console]({{ refs.branding-the-web-console.path }})
+* [Web Console Output Templating]({{ refs.web-console-output-templating.path }})
+* [Web Console Logging]({{ refs.web-console-logging.path }})
+* [Web Console Security Provider]({{ refs.web-console-security-provider.path }})
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/branding-the-web-console.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/branding-the-web-console.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/branding-the-web-console.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/branding-the-web-console.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,117 @@
+Title: Branding the Web Console
+
+# Branding the Web Console
+
+Branding the Web Consle mainly concerns hooking into the looks of the Web Console providing vendor-provided setup like CSS, Logo, Main Title, Vendor URL, etc.
+
+
+
+## BrandingPlugin and DefaultBrandingPlugin
+
+
+Branding for the Web Console can be provided in two ways: By registering a `BrandingPlugin` service or by providing a branding properties files. The Web Console uses the branding from the `BrandingPlugin` service registered with the highest ranking.
+
+The `BrandingPlugin` interface provides the following information used for branding:
+
+
+    // Returns an indicative name of the branding plugin
+    // This value is used as the Window/Page title together with the
+    // title of the respective plugin
+    String getBrandName();
+    
+    // Returns the name of the product in which the web console is contained
+    // and to which the web console is branded.
+    String getProductName();
+    
+    // Returns an (absolute) URL to a web site representing the product to
+    // which the web console is branded.
+    String getProductURL();
+    
+    // Returns an absolute path to an image to be rendered as the logo of the
+    // branding product.
+    String getProductImage();
+    
+    // Returns the name of the branding product vendor.
+    String getVendorName();
+    
+    // Returns an (absolute) URL to the web site of the branding product
+    // vendor.
+    String getVendorURL();
+    
+    // Returns an absolute path to an image to be rendered as the logo of the
+    // branding product vendor.
+    String getVendorImage();
+    
+    // Returns the absolute path to an icon to be used as the web console
+    // "favicon".
+    String getFavIcon();
+    
+    // Returns the absolute path to a CSS file to be used as the main CSS for
+    // the basic admin site.
+    String getMainStyleSheet();
+
+
+
+If no `BrandingPlugin` service is registered, the `DefaultBrandingPlugin` is used.
+
+
+The `DefaultBrandingPlugin` reads the `/META-INF/webconsole.properties` from the web console bundle to setup the branding using the following properties:
+
+| Property Name | Default Value | `BrandingPlugin` method name |
+|--|--|--|
+| `webconsole.brand.name` | Apache Felix Web Console | `getBrandName()` |
+| `webconsole.product.name` | Apache Felix | `getProductName()` |
+| `webconsole.product.url` | http://felix.apache.org | `getProductURL()` |
+| `webconsole.product.image` | /res/imgs/logo.png | `getProductImage()` |
+| `webconsole.vendor.name` | The Apache Software Foundation | `getVendorName()` |
+| `webconsole.vendor.url` | http://www.apache.org | `getVendorURL()` |
+| `webconsole.vendor.image` | /res/imgs/logo.png | `getVendorImage()` |
+| `webconsole.favicon` | /res/imgs/favicon.ico | `getFavIcon()` |
+| `webconsole.stylesheet` | /res/ui/webconsole.css | `getMainStyleSheet()` |
+
+*Note:* The `/META-INF/webconsole.properties` file is not contained in the Apache Felix Web Console bundle itself. It may be provided by a Fragment Bundle attaching to the Apache Felix Web Console bundle. For an example of such a fragment bundle see prototype [Sling Web Console Branding Bundle](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/webconsolebranding/) with its [`webconsole.properties`|https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/webconsolebranding/src/main/resources/META-INF/webconsole.properties?view=markup]
+
+
+## Branding the Stylesheet
+
+Branding the CSS Stylesheet is basically possible with the `BrandingPlugin.getMainStyleSheet()` method. The default value of the `DefaultBrandingPlugin` points to [`webconsole.css`](http://svn.apache.org/viewvc/felix/trunk/webconsole/src/main/resources/res/ui/webconsole.css?view=markup). This allows styling the main content structure as shown here:
+
+{code:html}
+<body>
+    <div id="main">
+
+        <!-- Lead -->
+        <div id="lead">
+            <h1>
+                Bundle Name
+                <br>
+                Page Title
+            </h1>
+            <p>
+                <a target="_blank" href="productURL" title="productName">
+                    <img src="productImage" border="0"/>
+                </a>
+            </p>
+        </div>
+
+        <!-- Top Navigation -->
+        <div id="technav">
+            <!-- regular link -->
+            <a href="">title</a>
+            <!-- label of current page -->
+            <span class="technavat">title</span>
+            <!-- label of current page if drawing as link -->
+            <a href="" class="technavat">title</a>
+        </div>
+
+        <!-- this should be inside a div ... -->
+        <div id="content">
+            <!-- here comes the content -->
+        </div>
+    </div>
+</body>
+
+    
+    Predefined plugins use other styles defined by further CSS styles contained in the web console bundle.
+    
+    It is yet unclear how these plugins can be styled....
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-resources.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-resources.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-resources.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-resources.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,24 @@
+Title: Providing Resources
+
+# Providing Resources
+
+
+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.
+
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-web-console-plugins.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-web-console-plugins.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-web-console-plugins.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/providing-web-console-plugins.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,64 @@
+Title: Providing Web Console Plugins
+
+# 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:
+
+
+* *`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. This request attribute is available to client side JavaScript as the global *`appRoot`* variable.
+* *`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 <code>ServletRequest.getContextPath()</code>), 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.
+* *`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.
+
+
+
+## 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:
+
+* *`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.
+* *`getCssReferences()`* -- See the section *Providing CSS Files* below.
+
+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.
+
+
+#### 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`):
+
+* *`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.
+* *`felix.webconsole.css`* -- Defines a single string, an array of strings or a Collection of strings to be used as the values provided by the `getCssReferences()` method. This property is optional. If this property is missing or if the value does not have the correct type, the `getCssReferences()` just returns `null` assuming there are no additional CSS resources to reference.
+
+
+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.
+* *`getCssReferences()`* -- Returns the values of the `felix.webconsole.css` 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 `service` 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.
+
+
+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.

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-logging.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-logging.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-logging.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-logging.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,23 @@
+Title: Web Console Logging
+
+# Web Console Logging
+
+The Web Console does not provide its own mechanism for logging. Rather the Servlet Container logging mechanism is used by calling the `GenericServlet.log` methods for logging. It is expected by the OSGi Http Service implementation implements these `log` methods writing to the OSGi Log Service.
+
+The drawback of using servlet container logging is that we have no control over the logging levels used and applied to log messages. To at least allow some level of log message filtering the Web Console can be configured with a logging level using the `loglevel` property of the *Apache Felix OSGi Management Console* (`org.apache.felix.webconsole.internal.servlet.OsgiManager`).
+
+The `AbstractWebConsolePlugin` class provides two addition `log` methods taking a `level` parameter which allow plugins to filter certain log messages:
+
+| `log(int level, String message)` | Calls `GenericaServlet.log(String)` if the configured log level is less than or equal to the `level` parameter. |
+| `log(int level, String message, Throwable t)` | Calls `GenericaServlet.log(String, Throwable)` if the configured log level is less than or equal to the `level` parameter. |
+
+*Note 1:* The `level` parameter is just used for filtering calls to the `GenericeServlet.log` methods and cannot define the actual log level used by the servlet container.
+
+*Note 2:* Direct calls to one of the `GenericServlet.log` or `ServletContext.log` methods are not intercepted and are not filtered by the log level configured for the Web Console.
+
+The `level` parameter and the `loglevel` configuration property can be set to any of the constant values defined by the OSGi `LogService` class:
+
+| 1 | LOG_ERROR | This log entry indicates the bundle or service may not be functional. |
+| 2 | LOG_WARNING | This log entry indicates a bundle or service is still functioning but may experience problems in the future because of the warning condition. |
+| 3 | LOG_INFO | This log entry may be the result of any change in the bundle or service and does not indicate a problem. |
+| 4 | LOG_DEBUG | This log entry is used for problem determination and may be irrelevant to anyone but the bundle developer. |
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-output-templating.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-output-templating.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-output-templating.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-web-console/extending-the-apache-felix-web-console/web-console-output-templating.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,66 @@
+Title: Web Console Output Templating
+
+Templating and Internationalization support of the Web Console is based on Java Resource Bundles loaded from the plugin bundles and is transparent to the plugin itself.
+
+
+## Basic Mechanism
+
+All requests handled by web console plugins are wrapped by response wrapper, which installs a Writer filter if the response is a `text/html` response. This writer filter recognizes variables of the pattern `$&#123;name&#125;` and tries to replace that part of the output with another string:
+
+    * If a variable of that name exists, the value of that variable is used. See Variable Resolution below.
+    * Otherwise if a resource bundle provides a translated string for the name, that string is used. See Resource Bundles below.
+    * Otherwise the name itself is just placed in the output.
+
+
+### Example
+
+Consider the plugin bundle provides a localization for the default german locale `de`:
+
+{panel:title=OSGI-INF/l10n/bundle_de.properties}
+Hello = Guten Tag
+{panel}
+
+And the plugin defines a variable replacement and writes output with the following code:
+
+
+    WebConsoleUtil.getVariableResolver().put("world", "Schweiz");
+    response.getWriter().println("${Hello} ${world}");
+
+
+
+The response sent to the client whose primary locale is `de` is then filtered to be:
+
+
+    Guten Tag Schweiz
+
+
+
+
+## Variable Resolution
+
+Variable Resolution is based on a `org.apache.felix.webconsole.VariableResolver` object provided as a request attribute prior to calling the `ServletResponse.getWriter()` method. If no such resolver is provided in the request, an instance of the `org.apache.felix.webconsole.DefaultVariableResolver` is used and stored in the request. Replacing the `VariableResolver` after the `getWriter()` has been called has no effect for variable resolution. Variables may be added to the `VariableResolver` even after the `getWriter()` method has been called.
+
+
+
+## Resource Bundles
+
+Resources for the Resource Bundles is provided by the Web Console bundle on the one hand and by the bundle providing the plugin on the other hand. Resources are identified inside a bundle with the `Bundle-Localization` manifest header as described in Section 3.10 Localization in the Core Specification.
+
+This also means, that additional translations may be provided by fragment bundles.
+
+During request processing the `Locale` of the request (`ServletRequest.getLocale()`) is used to identify the actual resources to use. From this information a `ResourceBundle` is constructed from a collection of the resources provided by the plugin bundle and the resources provided by the Web Console.
+
+
+### Web Console Localization
+
+The Web Console contains a single localization file `OSGI-INF/l10n/bundle.properties`. Fragments attached to the Web Console bundle may provide translations for these resources. All plugins of the Web Console itself will use a ReosurceBundle, which is only based on the localization of the Web Console itself.
+
+
+
+## Using Templating
+
+To use the described templating, the plugin developer may provide the following:
+
+1. Use templated strings in the generated response. Such templated strings will be replaced with variable values or localization strings as available.
+1. Set variable mappings in a `VariableResolver`. The simplest thing is to get a default `VariableResolver` calling the `WebConsoleUtil.getVariableResolver(ServletRequest)` method.
+1. Provide localization files and optionally set the `Bundle-Localization` header if the base file name is not the default `OSGI-INF/l10n/bundle`.
\ No newline at end of file



Mime
View raw message