moved new dm4 from sandbox to trunk.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1663056 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/dependencymanager/docs/.project b/dependencymanager/docs/.project
new file mode 100644
index 0000000..e248a4f
--- /dev/null
+++ b/dependencymanager/docs/.project
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>docs</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ </buildSpec>
+ <natures>
+ </natures>
+</projectDescription>
diff --git a/dependencymanager/docs/A_Glance_At_DependencyManager.odp b/dependencymanager/docs/A_Glance_At_DependencyManager.odp
new file mode 100644
index 0000000..7221e7a
--- /dev/null
+++ b/dependencymanager/docs/A_Glance_At_DependencyManager.odp
Binary files differ
diff --git a/dependencymanager/docs/migrating.mdtext b/dependencymanager/docs/migrating.mdtext
new file mode 100644
index 0000000..306f91e
--- /dev/null
+++ b/dependencymanager/docs/migrating.mdtext
@@ -0,0 +1,14 @@
+# Migrating from earlier versions
+
+DependencyManager 4.0 has some API changes that need to be taken into account when migrating from DependencyManager 3.
+
+* A dependency can no longer be shared accross components.
+* You no longer have to call setInstanceBound() when adding a dependency from within the init() method of a component. Therefore the setInstanceBound() method has been removed from all Dependency interfaces.
+* in the Dependency interface, the following method have been removed: isInstanceBound, invokeAdded, invokeRemoved, createCopy.
+* In the Component interface, the "Object Component.getService()" method has been replaced by the "<T> T getInstance()" method.
+* In the Component interface, the "void addStateListener(ComponentStateListener listener) method" has been replaced by the "add(ComponentStateListener listener)" method.
+* In the Component interface, the "start", "stop", "getDependencies" methods have been removed.
+* In the Component interface and in the DependencyManager class, the createTemporalServiceDependency() method is now taking a timeout parameter: createTemporalServiceDependency(long timeout).
+* The ComponentStateListener interface has changed: it is now providing a single "changed(Component c, ComponentState state)" method.
+* The DependencyManager 4 Shell commands are no longer available for framework specific shell implementations, and support the gogo shell only.
+* The TemporalServiceDependency interface has been removed.
diff --git a/dependencymanager/docs/shell.mdtext b/dependencymanager/docs/shell.mdtext
new file mode 100644
index 0000000..f2bf6c7
--- /dev/null
+++ b/dependencymanager/docs/shell.mdtext
@@ -0,0 +1,102 @@
+# Introduction
+
+The shell bundle for the dependency manager extends the gogo shell with one new command called "dm". This command can be used to get insight in the actual components and services in a running OSGi framework.
+
+Typing help ```help dm``` in the gogo shell gives an overview of the available command options.
+
+```
+dm - List dependency manager components
+ scope: dependencymanager
+ flags:
+ compact, cp Displays components using a compact form
+ nodeps, nd Hides component dependencies
+ notavail, na Only displays unavailable components
+ stats, stat, st Displays components statistics
+ wtf Detects where are the root failures
+ options:
+ bundleIds, bid, bi, b <List of bundle ids or bundle symbolic names to display (comma separated)> [optional]
+ componentIds, cid, ci <List of component identifiers to display (comma separated)> [optional]
+ components, c <Regex(s) used to filter on component implementation class names (comma separated), can be negated using "!" prefix> [optional]
+ services, s <OSGi filter used to filter some service properties> [optional]
+ top <Max number of top components to display (0=all)> This command displays components callbacks (init/start) times> [optional]
+ parameters:
+ CommandSession
+```
+
+
+# Usage examples
+Below are some examples for typical usage of the dependency manager shell commands. The examples are based on a simple component model with a dashboard which has a required dependency on four probes (temperature, humidity, radiation, pressure). The radiation probe requires a Sensor service but this sensor is not available.
+
+__List all dependency manager components__
+
+```dm```
+
+Sample output
+
+```
+[9] dm.demo
+ [6] dm.demo.Probe(type=radiation) unregistered
+ dm.demo.Sensor service required unavailable
+ [7] dm.demo.Probe(type=humidity) registered
+ [9] dm.demo.impl.Dashboard unregistered
+ dm.demo.Probe (type=temperature) service required available
+ dm.demo.Probe (type=radiation) service required unavailable
+ dm.demo.Probe (type=humidity) service required available
+ dm.demo.Probe (type=pressure) service required available
+ [5] dm.demo.Probe(type=temperature) registered
+ [8] dm.demo.Probe(type=pressure) registered
+```
+All components are listed including the dependencies and the availability of these dependencies. The top level element is the bundle and below are the components registered with that bundle's bundle context. The lowest level is that of the component's dependencies.
+
+```
+[bundleid] bundle
+ [component id] component interfaces (service properties)
+ dependency <availability>
+```
+
+The following flags can be used to tailor the output.
+
+```compact, cp``` shortens package names and dependencies and therefore gives a more compressed output.
+
+```nodeps, nd``` omits the dependencies from the output.
+
+```notavail, na``` filters out all components that are registered wich results in the output only containing those components that are in the unregistered state due to one or more unsatisfied required dependencies. This is the command option most used when using the dependency manager shell commands.
+
+Sample output for ```dm na```:
+
+```
+[9] dm.demo
+ [14] dm.demo.impl.Dashboard unregistered
+ dm.demo.Probe (type=radiation) service required unavailable
+ [11] dm.demo.Probe(type=radiation) unregistered
+ dm.demo.Sensor service required unavailable
+```
+
+The flags can be used in conjunction with the other command options.
+
+__Find all components for a given classname__
+
+```dm c .*ProbeImpl```
+
+dm c or components finds all components for which the classname of the implementation matches the regular expression.
+
+__Find all services matching a service filter__
+
+```dm s "(type=temperature)"```
+
+dm s allows finding components based on the service properties of their registered services in the service registry using a standard OSGi service filter.
+
+__Find out why components are not registered__
+
+```dm wtf```
+
+Sample output
+
+```
+2 missing dependencies found.
+-----------------------------
+The following service(s) are missing:
+ * dm.demo.Sensor is not found in the service registry
+```
+
+wtf gives the root cause for components not being registered and therefore their services not being available. In a typical application components have dependencies on services implemented by components that have dependencies on services etcetera. This transitivity means that an entire chain of components could be unregistered due to a (few) root dependencies not being satisified. wtf is about discovering those dependencies.
diff --git a/dependencymanager/docs/whatsnew.mdtext b/dependencymanager/docs/whatsnew.mdtext
new file mode 100644
index 0000000..425a31b
--- /dev/null
+++ b/dependencymanager/docs/whatsnew.mdtext
@@ -0,0 +1,22 @@
+# What's new in DependencyManager 4.0
+
+DependencyManager 4.0 has been significantly reworked to improve support for concurrency. The following principles form the basis of the new concurrency model in DM4.
+
+ * All external events that influence the state of dependencies are recorded and given to the serial executor of the component. We record whatever data comes in, so when the actual job is run by the serial executor, we still have access to the original data without having to access other sources whose state might have changed since.
+ * The serial executor of a component will execute a job immediately if it is being called by the thread that is already executing jobs.
+ * If the serial executor of a component had not yet started a job, it will queue and start it on the current thread.
+ * If the serial executor gets invoked from a different thread than the one currently executing jobs, the job will be put at the end of the queue. As mentioned before, any data associated with the event will also be recorded so it is available when the job executes.
+ * State in the component and dependency can only be modified via the serial executor thread. This means we don't need explicit synchronization anywhere.
+
+DependencyManager 4 now also supports parallel execution of component wiring.
+
+Added support for parallelism: To allow components to be started and handled in parallel, you can now register in the OSGi service registry a ComponentExecutorFactory service that is used to get an Executor for the management of all components dependencies/lifecycle callbacks. See javadoc from the org.apache.felix.dm.ComponentExecutorFactory interface for more information.
+
+You can also take a look at the the org.apache.felix.dependencymanager.samples project, which is registering a ComponentExecutorFactory from org.apache.felix.dependencymanager.samples.tpool bundle.
+
+See also the following property in the org.apache.felix.dependencymanager.samples/bnd.bnd
+
+ org.apache.felix.dependencymanager.parallel=\
+ '!org.apache.felix.dependencymanager.samples.tpool, *',\
+
+Here, all components will be handled by Executors provided by the ComponentExecutorFactory, except those having a package starting with "org.apache.felix.dependencymanager.samples.tpool" (because the threadpool is itself defined using the Dependency Manager API).