felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From uiter...@apache.org
Subject svn commit: r1665651 - in /felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides: diagrams/resources.png diagrams/resources.uxf resources.mdtext
Date Tue, 10 Mar 2015 19:18:29 GMT
Author: uiterlix
Date: Tue Mar 10 19:18:28 2015
New Revision: 1665651

URL: http://svn.apache.org/r1665651
Log:
Added resource adapters guide.

Added:
    felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.png
  (with props)
    felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.uxf
Modified:
    felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/resources.mdtext

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.png?rev=1665651&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.uxf
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.uxf?rev=1665651&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.uxf
(added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/diagrams/resources.uxf
Tue Mar 10 19:18:28 2015
@@ -0,0 +1,213 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<diagram program="umlet" version="13.2">
+  <zoom_level>10</zoom_level>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>190</x>
+      <y>420</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceRepository
+bg=orange</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>30</x>
+      <y>280</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceHandler</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>100</x>
+      <y>310</y>
+      <w>190</w>
+      <h>130</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+requires</panel_attributes>
+    <additional_attributes>10.0;10.0;170.0;110.0</additional_attributes>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>30</x>
+      <y>30</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceAdapter
+Component</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>30</x>
+      <y>160</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceDependency</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>330</x>
+      <y>30</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceAdapter
+Instance Component</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>180</x>
+      <y>30</y>
+      <w>170</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+registers</panel_attributes>
+    <additional_attributes>150.0;20.0;10.0;20.0</additional_attributes>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>100</x>
+      <y>60</y>
+      <w>30</w>
+      <h>120</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;&lt;&lt;&lt;-</panel_attributes>
+    <additional_attributes>10.0;10.0;10.0;100.0</additional_attributes>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>330</x>
+      <y>160</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceDependency</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>330</x>
+      <y>280</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceHandler</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>400</x>
+      <y>60</y>
+      <w>30</w>
+      <h>120</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;&lt;&lt;&lt;-</panel_attributes>
+    <additional_attributes>10.0;10.0;10.0;100.0</additional_attributes>
+  </element>
+  <element>
+    <id>Text</id>
+    <coordinates>
+      <x>490</x>
+      <y>290</y>
+      <w>100</w>
+      <h>70</h>
+    </coordinates>
+    <panel_attributes>url="...."
+fg=orange</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Text</id>
+    <coordinates>
+      <x>190</x>
+      <y>290</y>
+      <w>100</w>
+      <h>70</h>
+    </coordinates>
+    <panel_attributes>filter="...."
+fg=orange</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>260</x>
+      <y>310</y>
+      <w>170</w>
+      <h>130</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+requires</panel_attributes>
+    <additional_attributes>150.0;10.0;10.0;110.0</additional_attributes>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>480</x>
+      <y>30</y>
+      <w>150</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+instantiates</panel_attributes>
+    <additional_attributes>130.0;20.0;10.0;20.0</additional_attributes>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>610</x>
+      <y>30</y>
+      <w>160</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>ResourceAdapter
+Instance
+bg=orange</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>100</x>
+      <y>190</y>
+      <w>30</w>
+      <h>110</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;&lt;.</panel_attributes>
+    <additional_attributes>10.0;90.0;10.0;10.0</additional_attributes>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>400</x>
+      <y>190</y>
+      <w>30</w>
+      <h>110</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;&lt;.</panel_attributes>
+    <additional_attributes>10.0;90.0;10.0;10.0</additional_attributes>
+  </element>
+</diagram>

Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/resources.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/resources.mdtext?rev=1665651&r1=1665650&r2=1665651&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/resources.mdtext
(original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/guides/resources.mdtext
Tue Mar 10 19:18:28 2015
@@ -1,3 +1,98 @@
-Title: Apache Felix Dependency Manager - Resources
+Title: Resources
+
+Resource adapters are a special type of adapters which can adapt a resource into an OSGi
service. These resources can be all kinds of resources, e.g. bundle resources, files, database
records, anything as long as it can be resolved though a URL.
+
+The diagram below illustrates the classes involved in the resource adapter pattern:
+
+<img src="./diagrams/resources.png" alt="Resource adapters" style="width: 780px"/>
+The yellow elements have to be implemented in order to use the pattern.
+
+A resource adapter is configured as follows:
+
+```
+manager.add(createResourceAdapter("*.MF", true, null, "changed")
+				.setImplementation(ManifestAdapter.class));
+```
+
+The filter semantics depend on the resource repository. In this example the resource repository
will be serving bundle resources, so we're using a standard file wildcard filter. As the filter
specifies in this case the resource of interest is the bundle manifest. For each MANIFEST.MF
found a new instance of ManifestAdapter will be created and registered. Each instance gets
access to the resource by injecting the URL of the resource into the implementation object.
+
+```
+public class ManifestAdapter {
+
+	private volatile URL url;
+	
+	void start() {
+		System.out.println("started: " + url);
+	}
+
+}
+```
+
+
+But how does DM know where to go looking for manifest files? We'll it does not automatically.
It requires you to implement a resource repository component. For each resource adapter service
DM launches a ResourceHandler service tracking the resources the resource adapter is interested
in. A resource repository is responsible for tracking resources and notifying adding / changing
and removal of the resources from the repository. Notifying these resource 'events' is done
by invoking the corresponding method on the ResourceHandler service.
+
+We'll explain how to implement a resource repository by an example. The example resource
repository is a bundle resource repository which as it's name says, is capable of serving
bundle resources.
+
+A simplified bundle resource repository looks as follows:
+
+```
+public class BundleResourceRepositoryImpl {
+
+	private Map<ServiceReference, ResourceHandler> handlers = new ConcurrentHashMap<>();
+	private volatile BundleContext context;
+	
+	void addHandler(ServiceReference ref, ResourceHandler handler) {
+		handlers.put(ref, handler);
+		if (ref.getProperty(ResourceHandler.URL) != null) {
+			URL url = (URL) ref.getProperty(ResourceHandler.URL);
+			notifyMatchingInitialResource(url, handler);
+		} else {
+			String filter = (String) ref.getProperty(ResourceHandler.FILTER);
+			notifyMatchingInitialResources(filter, handler);
+		}
+	}
+	
+	void removeHandler(ServiceReference ref, ResourceHandler handler) {
+		handlers.remove(ref);
+	}
+	
+	private void notifyMatchingInitialResource(URL url, ResourceHandler handler) {
+		if (bundleContainsResource(url)) {
+			handler.added(url, new Hashtable<String, String>());
+		}
+	}
+	
+	@SuppressWarnings("unchecked")
+	void notifyMatchingInitialResources(String filter, ResourceHandler handler) {
+		Enumeration<URL> entries = context.getBundle().findEntries("/", filter, true);
+		while (entries.hasMoreElements()) {
+			URL entry = entries.nextElement();
+			handler.added(entry, new Hashtable<String, String>());
+		}
+	}
+	
+	private boolean bundleContainsResource(URL url) {
+		return true; // more specific checks required
+	}
+}
+``` 
+
+The resource repository is registered in the bundle activator as follows:
+
+```
+		manager.add(createComponent().setImplementation(BundleResourceRepositoryImpl.class)
+				.add(createServiceDependency().setService(ResourceHandler.class).setCallbacks("addHandler",
"removeHandler")));
+```
+
+A resource repository implementation must have a dependency on resource handlers. The ResourceHandler
service has two important service properties:
+
+- "filter" (`ResourceHandler.FILTER`)
+- "url" (`ResourceHandler.URL`)
+
+A resource handler service has either one of these properties, not both! A resource handler
with a filter can match multiple resources whereas a resource handler with a url only matches
a single resource. It's important the resource repository handles both situations.
+
+When a new handler is being added, the resource repository should inform the resource handler
on the resources it has that match the handler's filter or url. This is done by invoking the
`added(url, properties)` method on the ResourceHandler. This callback results in the ResourceAdapter's
ResourceDependency being satisfied, the url being injected into the resource adapter implementation
object and the resource adapter implementation component being started.
+
+Besides the added() callback the resource repository is also responsible for handling the
changed() and removed() methods on change or removal of the resource from the resource repository.
For a bundle resource repository that's not likely to happen, but for a filesystem resource
repository this can very well be the case.
+
 
-...
\ No newline at end of file



Mime
View raw message