FELIX-3128 : A Service Diagnostics service and graphical WebConsole plugin
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1203551 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/webconsole-plugins/servicediagnostics/README.txt b/webconsole-plugins/servicediagnostics/README.txt
new file mode 100644
index 0000000..175a3c9
--- /dev/null
+++ b/webconsole-plugins/servicediagnostics/README.txt
@@ -0,0 +1,64 @@
+OSGi Service Diagnostics and WebConsole Plugin
+==============================================
+
+This projects aims at easing diagnostics of OSGi services and finding about missing dependencies.
+
+Typically in a large system with many cascading dependencies managed by different trackers such as DeclarativeService, DependencyManager or others, tracking the root cause of a top level service not being started can become very cumbersome. When building service oriented architectures, it is often the case that a single missing requirement will lock a full stack of services, but to find that one requirement is like finding a needle in a haystack!
+
+The basic idea here is to ask each dependency manager instance about its unresolved dependencies, merge all answers and filter the result to keep only the root causes.
+
+Typically, if A depends on B which depends on C which depends on D, and D is nowhere to be found, I need only show the "C -> D" missing requirement; if D is resolved, then the whole stack is unlocked.
+
+Similarly, if D is known by another dependency management system, but unregistered because it depends on E which is missing, then only the "D -> E" requirement is relevant.
+
+Project organization (core):
+============================
+* servicediagnostics: the API package. It holds the main service interface as well as the plugin interface, to extend to other dependency management systems
+
+* servicediagnostics.impl: the implementation package. It contains plugins implementations for org.apache.felix.scr and org.apache.felix.dependencymanager, as well as the main service implementation.
+
+* servicediagnostics.webconsole: a Felix WebConsole plugin that displays a graphical view of the diagnostics result. Alternatively it can also show a graph of all services currently registered in the service registry and the bundles using them. See Screenshot-notavail.png and Screenshot-all.png.
+
+The "sample" part simply contains some test classes and a helper class to launch Felix.
+
+How to build the project:
+=========================
+
+> mvn install
+
+How to run:
+===========
+I'm providing a simple run script just to try out the service.
+Unfortunately, org.json and scala-library don't come readily packaged as OSGi bundles, so we need to wrap them ourselves and copy these runtime dependencies into a "lib" directory under the project root:
+lib/json-osgi.jar
+lib/scala-library-osgi.jar
+
+These libraries can be easily created using Bnd:
+> java -jar bnd.jar wrap $HOME/.m2/repository/org/scala-lang/scala-library/2.8.1/scala-library-2.8.1.jar
+> mv scala-library-2.8.1.bar lib/scala-library-osgi.jar
+
+> java -jar bnd.jar wrap $HOME/.m2/repository/org/json/json/20090211/json-20090211.jar
+> mv json-20090211.bar lib/json-osgi.jar
+
+Once this is done, you can simply run:
+> ./run.sh
+
+It should display:
+[INFO] Started jetty 6.1.x at port(s) HTTP:8080
+
+You can then point your browser to
+http://localhost:8080/system/console/servicegraph
+
+(login/password is admin/admin)
+then click on either "Unavail" or "All".
+The "bubbles" can be dragged around for better readability. The colors are random and don't mean anything.
+On the "All" view, arrows point from bundles to the services they use.
+On the "Unavail" view, arrows point from a leaf component to its missing dependencies.
+
+(note: the lib directory is provided for dependencies that are not readily available as OSGi bundles from maven)
+
+Issues & TODOs:
+===============
+* use of JSONObject in Servlet.scala is a bit awkward, but Scala's native json is still incomplete..
+* no support for service properties; needs to be added.
+* no support for iPojo, Blueprint, basic ServiceTrackers... more plugins could be developed. I only wrote the ones i'm using.