Author: rwesten
Date: Wed Nov 23 17:56:46 2011
New Revision: 1205511
URL: http://svn.apache.org/viewvc?rev=1205511&view=rev
Log:
Added README.md files for
* Bundle Provider for the Apache Sling OSGI Installer
* DataFileProvider and DataFileTracker service
* Bundle DataFileProvider
Added:
incubator/stanbol/trunk/commons/installer/bundleprovider/README.md
incubator/stanbol/trunk/commons/stanboltools/bundledatafileprovider/README.md
incubator/stanbol/trunk/commons/stanboltools/datafileprovider/README.md
Added: incubator/stanbol/trunk/commons/installer/bundleprovider/README.md
URL:
http://svn.apache.org/viewvc/incubator/stanbol/trunk/commons/installer/bundleprovider/README.md?rev=1205511&view=auto
==============================================================================
--- incubator/stanbol/trunk/commons/installer/bundleprovider/README.md (added)
+++ incubator/stanbol/trunk/commons/installer/bundleprovider/README.md Wed Nov
23 17:56:46 2011
@@ -0,0 +1,52 @@
+OSGI Bundle Provider
+--------------------
+
+Provider for the Apache Sling OSGI Installer Framework that installs Resources
+provided by OSGI Bundles.
+
+### Apache Sling OSGI Installer
+
+The [OSGi installer](http://sling.apache.org/site/osgi-installer.html)
+is a central service for handling installs, updates and uninstall of
"artifacts".
+By default, the installer supports bundles and configurations for the OSGi
+configuration admin. Apache Stanbol extends this by the possibility to install
+Solr indexes (see "org.apache.stanbol.commons.solr.install" for details).
+
+Note: While the Sling OSGI Installer by default supports the installation of
+Bundles this extension allows to install resources provided by bundles.
+
+### Usage
+
+This implementation tracks all Bundles of the OSGI Environment that define the
+"Install-Path" key. The value is interpreted as path to the folder within the
+bundle where all installable resources are located. Also resources in
+sub-directories will be installed.
+
+If a Bundle defining this key is
+
+* STARTED: all installable resources will be installed
+* STOPED: all installable resource will be uninstalled
+* UPDATED: all installable resources will be first uninstalled and than
installed
+
+
+### Defining Manifest keys with Maven
+
+When using the maven-bundle-plugin the "Install-Path" header can be defined
+like this:
+
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ ...
+ <configuration>
+ <instructions>
+ <Install-Path>data/config</Install-Path>
+ </instructions>
+ </configuration>
+ </plugin>
+
+This would install all resrouces located within
+
+ data/config/*
+
+Note: that also Resource within sub-directories would be installed.
Added:
incubator/stanbol/trunk/commons/stanboltools/bundledatafileprovider/README.md
URL:
http://svn.apache.org/viewvc/incubator/stanbol/trunk/commons/stanboltools/bundledatafileprovider/README.md?rev=1205511&view=auto
==============================================================================
---
incubator/stanbol/trunk/commons/stanboltools/bundledatafileprovider/README.md
(added)
+++
incubator/stanbol/trunk/commons/stanboltools/bundledatafileprovider/README.md
Wed Nov 23 17:56:46 2011
@@ -0,0 +1,61 @@
+DataFileProvider for OSGI Bundles
+---------------------------------
+
+Implemenation of a DataFileProvider that allows to load DataFiles from
+OSGI Bundles.
+
+### Apache Sling OSGI Installer
+
+The [OSGi installer](http://sling.apache.org/site/osgi-installer.html)
+is a central service for handling installs, updates and uninstall of
"artifacts".
+By default, the installer supports bundles and configurations for the OSGi
+configuration admin. Apache Stanbol extends this by the possibility to install
+Solr indexes (see "org.apache.stanbol.commons.solr.install" for details).
+
+Note: While the Sling OSGI Installer by default supports the installation of
+Bundles this extension allows to install resources provided by bundles.
+
+### Usage
+
+This implementation tracks all Bundles of the OSGI Environment that define the
+"Data-Files" key. The value is interpreted as a comma separated list of
+paths to the folders that contain the data files.
+
+For each Bundle that provides Data-Files an own DataFileProvider instance is
+registered if the Bundle is STARTED and ungegisterd as soon as the Bundle is
+STOPPED.
+The MainDataFileProvider keeps track of all active DataFileProviders.
+
+In addition to the "Data-Files" key an optional "Data-Files-Priority" can be
+used to spefify the service-ranking for the DataFileProvider created for the
+configured folders within a Bundle.
+If a data file is provided by more than one DataFileProvider the one provided
+by the DataFileProvider with the higest Ranking will be returned.
+The default ranking is "0".
+
+Data file names parsed to this DataFileProvider are interpreted as relative to
+all configured data file paths.
+
+### Defining Manifest keys with Maven
+
+When using the maven-bundle-plugin the "Install-Path" header can be defined
+like this:
+
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ ...
+ <configuration>
+ <instructions>
+ <Data-Files>data,extras/data</Data-Files>
+ <Data-Files-Priority>-100</Data-Files-Priority>
+ </instructions>
+ </configuration>
+ </plugin>
+
+This would install all data files located within
+
+ data/
+ extras/data
+
+and will register them with a priority of "-100".
Added: incubator/stanbol/trunk/commons/stanboltools/datafileprovider/README.md
URL:
http://svn.apache.org/viewvc/incubator/stanbol/trunk/commons/stanboltools/datafileprovider/README.md?rev=1205511&view=auto
==============================================================================
--- incubator/stanbol/trunk/commons/stanboltools/datafileprovider/README.md
(added)
+++ incubator/stanbol/trunk/commons/stanboltools/datafileprovider/README.md Wed
Nov 23 17:56:46 2011
@@ -0,0 +1,83 @@
+Data File Provider
+==================
+
+The DataFileProvider provides data files (InputStreams actually) to
+OSGi components.
+
+Usage
+-----
+
+Datafiles are requested by name. Optionally the symbolic name of the bundle
+requesting the data file can be parsed. This allows to serve different versions
+of the same data file to different bundles. In addition requesters can provide
+a Map<String,Stirng> with additional information about the requested file.
+Currently this information are only used for visualisation purposes, but future
+versions might also bind specific actions to known keys.
+
+Main DataFileProvider
+---------------------
+
+The MainDataFileProvider is the default implementation of the DataFileProvider
+interface. It registers itself with a service.ranking of Integer.MAX_VALUE to
+make it the default provider. I also keeps a list of all the other
+DataFileProviders.
+
+The main DataFileProvider ignores other providers if it finds the requested
data
+file in the filesystem, in a specific folder ("datafiles folder").
+The name of that folder is configurable in the main DataFileProvider service.
+The default value is "sling/datafiles".
+
+If it can not find the requested file it forwards the request to all other
+active DataFileProvider instances sorted by service.ranking.
+
+When a bundle with symbolic name foo asks for data file bar.bin, the main
+DataFileProvider first looks for a file named foo-bar.bin in the datafiles
+folder, then for a file named bar.bin. Only if both files could not be found
the
+request is forwarded to the other registered DataFileProviders.
+
+Providing DataFiles
+-------------------
+
+Bundles may provide there own DataFileProvider service. This might be useful
+if they need to provide a default version for a data file, but intend to allow
+users to override this by copying an other version to the "datafiles folder"
+of the Main DataFileProvider.
+
+It they provide such a DataFileProvider service it must register it in its
+Activator, so that it's up before any component of the bundle asks for it.
+
+If the Bundle does not want to provide a file also to other bundles than it
+should check if the parsed bundleSymbolicName is equals to its own.
+
+[Bundle DataFileProvider](../bundledatafileprovider/README.md)
+-----------------------
+
+This extension allows to provide data files within a Bundle by using the
+"Data-Files" key in the Bundles manifest to point to a comma separated list
+of paths within the bundle that contains the data files.
+
+OSGI Console Pligin
+-------------------
+
+An OSGi console plugin lists all (successful or failed) requests to the main
+DataFileProvider service, along with their downloadExplanations. This list of
+requests can also be queried so that failed requests can be shown on the
stanbol
+server home page, for example. This provides a single location where stanbol
+users see what data files are needed and which ones were actually loaded from
+where.
+
+
+Data File Tracker
+=================
+
+While the DataFileProvider only supports requests for resources the Tracker
+allows register DataFileListener for a specific DataFile.
+
+If the requested DataFile becomes available or unavailable the listener is
+notified about the state.
+
+Because the DataFileProvider does not natively support such events the
+tracker uses periodical requests for all tracked DataFiles.
+
+Note that registered Listeners are not kept if the DataFileTracker service is
+restarted.
