This is an automated email from the ASF dual-hosted git repository. djencks pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/felix-antora-site.git
commit 778aa40604edc747ec3cd14c53e6caa2d5595cbd Author: David Jencks <[email protected]> AuthorDate: Sun Jul 11 15:52:51 2021 -0700 remove upnp doc (unmaintained) --- modules/ROOT/pages/documentation/subprojects.adoc | 2 +- .../subprojects/apache-felix-upnp.adoc | 23 ---- .../apache-felix-upnp/upnp-acknowledgments.adoc | 11 -- .../upnp-driver-architecture.adoc | 61 ----------- .../apache-felix-upnp/upnp-getting-started.adoc | 56 ---------- .../apache-felix-upnp/upnp-known-issues.adoc | 12 --- .../apache-felix-upnp/upnp-testing-devices.adoc | 54 ---------- .../upnp-testing-devices/upnp-examples.adoc | 41 -------- .../upnp-examples/upnp-writing-cd-and-cp.adoc | 117 --------------------- 9 files changed, 1 insertion(+), 376 deletions(-) diff --git a/modules/ROOT/pages/documentation/subprojects.adoc b/modules/ROOT/pages/documentation/subprojects.adoc index b125e82..2584fbe 100644 --- a/modules/ROOT/pages/documentation/subprojects.adoc +++ b/modules/ROOT/pages/documentation/subprojects.adoc @@ -128,5 +128,5 @@ The last documentation may be found in the https://github.com/apache/felix-site- * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-osgi-core.html[OSGi Core] * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-script-console-plugin.html[Script Console Plugin] * https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-serialization-framework.html[Serialization Framework] -* xref:documentation/subprojects/apache-felix-upnp.adoc[UPnP] +* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-upnp.html[UPnP] * xref:documentation/subprojects/apache-felix-user-admin.adoc[User Admin] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp.adoc deleted file mode 100644 index d5a6cc4..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp.adoc +++ /dev/null @@ -1,23 +0,0 @@ -= Apache Felix UPnP - -== Introduction - -The Felix UPnP project provides an implementation of the OSGi UPnP specification (version 1.1) as described in the http://www.osgi.org/Specifications/HomePage[OSGi Service Compendium (Release 4)] . The specification is implemented by the _org.apache.felix.upnp.basedriver_ bundle and it comes with other bundles, which have been developed to ease the writing and testing of UPnP code. - -The OSGi UPnP specification defines a set of interfaces which should be used by the developers in order to write UPnP Devices and UPnP Control Points on the OSGi Service Platform. -From the OSGi point of view, UPnP devices are services registered with the framework, thus the different phases of the UPnP protocol stack, as defined in the http://www.upnp.org/resources/documents/CleanUPnPDA101-20031202s.pdf[UPnP™ Device Architecture (UDA 1.0)], have been mapped to the discovery and notification mechanisms offered by the OSGi framework. - -The specification defines a UPnP Base Driver component that acts as software bridge between UPnP networks and OSGi. -Developers writing UPnP code do not need to interact directly with the driver through some API. -The driver works in background by exporting the registered services as UPnP devices, and by registering as services the UPnP devices discovered on UPnP networks. -However, the Felix UPnP project has defined few additional interfaces, so a base knowledge of the way the UPnP Base Driver works is useful and will help developers to write their code. - -Table of Content: - -. xref:documentation/subprojects/apache-felix-upnp/upnp-getting-started.adoc[Getting Started] -. xref:documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.adoc[Overview of the Base Driver Architecture] -. xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices.adoc[Testing UPnP devices] -. xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.adoc[The UPnP examples] -. xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.adoc[Writing UPnP Devices and Control Points] -. xref:documentation/subprojects/apache-felix-upnp/upnp-known-issues.adoc[Known issues] -. xref:documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.adoc[Acknowledgments] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.adoc deleted file mode 100644 index 8b8cf6b..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= UPnP Acknowledgments - -[cols=2*] -|=== -| The Felix UPnP base driver and related bundles were originally developed by the http://domoware.isti.cnr.it/[Domoware] project which targeted the OSGi R3. -The driver is based on a modified version of the "UPnP for Java" library released by the [Cyberlink -| http://www.cybergarage.org/net/upnp/java/index.html] project. -This version, called CyberDomo, is currently maintained by the Domoware project team and aligned to the Cyberlink library regularly. -|=== - -== xref:documentation/subprojects/apache-felix-upnp/upnp-known-issues.adoc[Known Issues] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.adoc deleted file mode 100644 index 3c9a342..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= Overview of the Base Driver Architecture - -The Figure 4 shows a simplified component view of the base driver. -The driver is composed of two components, the _exporter_ and _importer_; -both using the _CyberDomo_ library, which is a modified version of the library released by the http://www.cybergarage.org/net/upnp/java/index.html["CyberLink for Java" project], maintained by the [Domoware project|http://domoware.isti.cnr.it/ ]. -The library implements a full UPnP stack. -The base driver acts as a bridge between OSGi and the UPnP networks . !BaseDriverArchitecture.jpg! -_Figure 4_ The UPnP Base Driver architecture - -In order to instantiate UPnP devices, developers must register services implementing the interfaces represented in Figure 5 and provided by the _org.osgi.compendium bundle_. -The _exporter_ is registered as http://www.osgi.org/javadoc/r4/org/osgi/framework/ServiceListener.html[ServiceListener]with the framework and it automatically exposes on the networks each [UPnPDevice |http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html]service registered with the registration property [UPNP__EXPORT|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html#UPNP__EXPORT]. -The _importer_ listens to the advertisements sent on the networks by external devices and registers with the framework one or more UPnPDevice services. -Even if it is not required by the specification, the devices imported by the Felix base driver are labeled with the registration property [UPNP_IMPORT|http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/basedriver/util/Constants.java?view=markup]. -!UPnPDeviceInterfaces.jpg! -_Figure 5_ The UPnP Device interfaces - -Working with UPnP Device from the OSGi point of view means to operate with services; -the discovery, controlling and eventing phases of the UPnP protocol are naturally mapped to the OSGi service layer, which allows to publish, find, bind and notify events. -There are some aspects that make it different to work with UPnP in OSGi with respect to other UPnP libraries, due basically to the centralized nature of the OSGi registry opposed to the distributed approach used in UPnP networks; -some hints are provided in the section "Writing UPnP Devices and Control Points" - -The Felix base driver comes with some system properties you can use to configure it at startup. - -The system properties: • _cyberdomo.ssdp.mx_ (default 5) • _cyberdomo.ssdp.buffersize_ (default 2048) • _cyberdomo.ssdp.port_ (default 1900) - -[cols=2*] -|=== -| are used by the UPnP stack library during the UPnP discovery process. -The paper "http://w3.antd.nist.gov/~mills/papers/Paper521.pdf[Adaptive Jitter Control for UPnP M-Search]" [1] provides a good analysis of the tuning of such parameters related to scalability issues. -The MX parameter default has been set to 5 sec. -Higher values improve the discovery effectiveness but increase the latency for new device discovery. -The Intel "[Device Spy -| http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/index.htm]"; tool uses a delay of 10 sec, the "CyberLink for Java" library 3 sec. -The SSDP port in UPnP specification is by default 1900 we allow the modification of such parameter. -|=== - -The following system properties: • _felix.upnpbase.exporter.enabled_ (default true) • _felix.upnpbase.importer.enabled_ (default true) - -can be used to enable or disable the two main components of the base driver. -For example with small devices (ARM-based processor), disabling the exporting or importing of devices might reduce the resource consumption. - -• _felix.upnpbase.log_ (default 2) • _felix.upnpbase.cyberdomo.log_ (default false) - -are properties used to enable the different logging facilities offered by the base driver. -You can also modify them at run time by using the GUI provided by the UPnP Tester bundle - -Finally the following properties are used to set the networking parameters. -The loopback interface is usually disabled : - -• _felix.upnpbase.cyberdomo.net.loopback_ (default false) • _felix.upnpbase.cyberdomo.net.onlyIPV4_ (default true) • _felix.upnpbase.cyberdomo.net.onlyIPV6_ (default false) - -[discrete] -===== xref:documentation/subprojects/apache-felix-upnp/upnp-getting-started.adoc[Getting Started] [Testing UPnP Devices| UPnP Testing Devices] - -''' - -[1]({{ refs.1.path }}) K. -Mills, C. -Dabrowski "Adaptive Jitter Control for UPnP M-Search" IEEE International Conference on Communications, 2003. -ICC '03. -page(s): 1008- 1013 vol.2 diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-getting-started.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-getting-started.adoc deleted file mode 100644 index 742bd04..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-getting-started.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= Getting Started - -Assuming that, as described in xref:documentation/subprojects/building-felix.adoc[Building Felix] 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" - -[cols=2*] -|=== -| 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 "xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices.adoc[Testing UPnP devices]" 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. - -// -* xref:documentation/subprojects/apache-felix-upnp.adoc[Introduction] -* xref:documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.adoc[UPnP Driver architecture] - -''' - -[1]({{ refs.1.path }}) The actual version of the bundles may be different diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-known-issues.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-known-issues.adoc deleted file mode 100644 index 633f11f..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-known-issues.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= 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 - -// -* xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.adoc[Writing UPnP Devices and Control Points] -* xref:documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.adoc[UPnP Acknowledgments ] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.adoc deleted file mode 100644 index e9cfd5d..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= Testing UPnP devices - -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. - -// -* xref:documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.adoc[Overview of the Base Driver Architecture] -* xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.adoc[The Felix UPnP Examples| UPnP Examples] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.adoc deleted file mode 100644 index b3221b9..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.adoc +++ /dev/null @@ -1,41 +0,0 @@ -= 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. - -=== xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices.adoc[Testing UPnP Devices] [Writing UPnP Devices and Control Points| UPnP Writing CD and CP] diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.adoc deleted file mode 100644 index 635dddb..0000000 --- a/modules/ROOT/pages/documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples/upnp-writing-cd-and-cp.adoc +++ /dev/null @@ -1,117 +0,0 @@ -= Writing UPnP Devices and Control Points - -[cols=2*] -|=== -| The http://www.osgi.org/Specifications/HomePage[OSGi UPnP Specification (v 1.1)] 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 http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPEventListener.html[UPnPEventListener]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. - -[cols=3*] -|=== -| On the other hand, even if it is enough to register a service implementing the http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html[UPnPDevice]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 UPnPStateVariable 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. - -[cols=4*] -|=== -| In the Extra bundle the class http://svn.apache.org/viewvc/felix/trunk/upnp/extra/src/main/java/org/apache/felix/upnp/extra/util/UPnPSubscriber.java?view=markup[org.apache.felix.upnp.extra.util.UPnPSubscriber] 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 http://svn.apache.org/viewvc/felix/trunk/upnp/samples/tv/src/main/java/org/apache/felix/upnp/sample/tv/TvDevice.java?view=markup[org.apache.felix.upnp.sample.tv.TVDevice] 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();} ----- - -[cols=8*] -|=== -| The class http://svn.apache.org/viewvc/felix/trunk/upnp/extra/src/main/java/org/apache/felix/upnp/extra/util/UPnPEventNotifier.java?view=markup[org.apache.felix.upnp.extra.util.UPnPEventNotifier] 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 propertyChange(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?view=markup] class in the BinaryLight bundle{color:black}.\{color} -|=== - -The Felix UPnP base driver registers a non standard service implementing two interfaces: - -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.DevicesInfo]; -http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/basedriver/controller/DriverController.java?view=markup[org.apache.felix.upnp.basedriver.controller.DriverController]; - -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. - -* xref:documentation/subprojects/apache-felix-upnp/upnp-testing-devices/upnp-examples.adoc[The Felix UPnP Examples] -* xref:documentation/subprojects/apache-felix-upnp/upnp-known-issues.adoc[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.
