Author: cziegeler
Date: Tue Dec 30 09:45:30 2014
New Revision: 1648494
URL: http://svn.apache.org/r1648494
Log:
Update installer documentation
Added:
sling/site/trunk/content/documentation/bundles/configuration-installer-factory.mdtext
sling/site/trunk/content/documentation/bundles/file-installer-provider.mdtext
sling/site/trunk/content/documentation/bundles/subsystem-installer-factory.mdtext
Removed:
sling/site/trunk/content/site/jcr-installer-provider.html
Modified:
sling/site/trunk/content/documentation/bundles.mdtext
sling/site/trunk/content/documentation/bundles/jcr-installer-provider.mdtext
sling/site/trunk/content/documentation/bundles/osgi-installer.mdtext
sling/site/trunk/content/site/.htaccess
Modified: sling/site/trunk/content/documentation/bundles.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles.mdtext?rev=1648494&r1=1648493&r2=1648494&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles.mdtext Tue Dec 30 09:45:30
2014
@@ -20,9 +20,13 @@ Title: Bundles
* [Resource Access Security (resourceaccesssecurity)]({{
refs.resource-access-security.path }})
-## Installer
+## OSGi Installer
+The OSGi installer is a very flexible and powerful service to manage
provisioning and updates of an OSGi system. It is independent of Sling and can
be extended by several plugins.
* [OSGi Installer]({{ refs.osgi-installer.path }})
+* [Configuration Installer Factory]({{
refs.configuration-installer-factory.path }})
+* [Subsystem Installer Factory]({{ refs.subsystem-installer-factory.path }})
* [JCR Installer Provider]({{ refs.jcr-installer-provider.path }})
+* [File Installer Provider]({{ refs.file-installer-provider.path }})
## Development and Utilities
* [Commons Thread Pools]({{ refs.apache-sling-commons-thread-pool.path }})
Added:
sling/site/trunk/content/documentation/bundles/configuration-installer-factory.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/configuration-installer-factory.mdtext?rev=1648494&view=auto
==============================================================================
---
sling/site/trunk/content/documentation/bundles/configuration-installer-factory.mdtext
(added)
+++
sling/site/trunk/content/documentation/bundles/configuration-installer-factory.mdtext
Tue Dec 30 09:45:30 2014
@@ -0,0 +1,76 @@
+Title: Configuration Installer Factory
+
+The configuration installer factory provides support for configurations to the
[OSGI installer]({{ refs.osgi-installer.path }}). The provisioning of artifacts
is handled by installer providers like the file installer or the JCR installer.
+
+
+## Configurations
+
+Configuration file names are related to the PID and factory PID. The structure
of the file name is as follows:
+
+
+ filename ::= <pid> ( '-' <subname> )? ('.cfg'|'.config')
+
+
+If the form is `<pid>('.cfg'|'.config')`, the file contains the properties for
a Managed Service. The `<pid>` is then the PID of the Managed Service. See the
Configuration Admin service for details.
+
+When a Managed Service Factory is used, the situation is different. The
`<pid>` part then describes the PID of the Managed Service Factory. You can
pick any `<subname>`, the installer will then create an instance for the
factory for each unique name. For example:
+
+
+ com.acme.xyz.cfg // configuration for Managed Service
+ // com.acme.xyz
+ com.acme.abc-default.cfg // Managed Service Factory,
+ // creates an instance for com.acme.abc
+
+
+If a configuration is modified, the file installer will write the
configuration back to a file to ensure peristence across restarts (if
`sling.fileinstall.writeback` is enabled).
+
+### Property Files
+
+Configuration files ending in '.cfg' are plain property files
(`java.util.Property`). The format is simple:
+
+
+ file ::= ( header | comment ) *
+ header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
+ comment ::= '#' <any>
+
+Notice that this model only supports string properties. For example:
+
+ # default port
+ ftp.port = 21
+
+### Configuration Files
+
+Configuration files ending in '.config' use the format of the Apache Felix
ConfigAdmin implementation. It allows to specify the type and cardinality of a
configuration property and is not limited to string values.
+
+The first line of such a file might start with a comment line (a line starting
with a #). Comments within the file are not allowed.
+
+The format is:
+
+ file ::= (comment) (header) *
+ comment ::= '#' <any>
+ header ::= prop '=' value
+ prop ::= symbolic-name // 1.4.2 of OSGi Core Specification
+ symbolic-name ::= token { '.' token }
+ token ::= { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' }
+ value ::= [ type ] ( '[' values ']' | '(' values ')' | simple )
+ values ::= simple { ',' simple }
+ simple ::= '"' stringsimple '"'
+ type ::= <1-char type code>
+ stringsimple ::= <quoted string representation of the value>
+
+The 1 character type code is one of:
+
+* 'T' : simple string
+* 'I' : Integer
+* 'L' : Long
+* 'F' : Float
+* 'D' : Double
+* 'X' : Byte
+* 'S' : Short
+* 'C' : Character
+* 'B' : Boolean
+
+# Project Info
+
+* Configuration installer factory
([org.apache.sling.installer.factory.configuration](http://svn.apache.org/repos/asf/sling/trunk/installer/factories/configuration))
+
Added:
sling/site/trunk/content/documentation/bundles/file-installer-provider.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/file-installer-provider.mdtext?rev=1648494&view=auto
==============================================================================
---
sling/site/trunk/content/documentation/bundles/file-installer-provider.mdtext
(added)
+++
sling/site/trunk/content/documentation/bundles/file-installer-provider.mdtext
Tue Dec 30 09:45:30 2014
@@ -0,0 +1,37 @@
+Title: File Installer Provider
+
+The file installer provider scans configured directories and provides the
found artifacts (files) to the [OSGI installer]({{ refs.osgi-installer.path
}}). The functionality is very similar to Apache Felix FileInstall, with the
major difference that this service implements just the task of scanning a file
directory. All the management logic is implemented in the OSGi installer and
support of various artifact types like bundles, configurations or custom
formats is implemented by plugins for the OSGi installer.
+
+
+## Setup
+
+The file installer can be configured with these framework (system) properties:
+
+|Property|Default|Description|
+|--|--|--|
+|`sling.fileinstall.dir`| |The name/path of the directories to watch. Several
directories can be specified by using a comma separated list.|
+|`sling.fileinstall.interval`|5000 ms|Number of milliseconds between 2 polls
of the directory|
+|`sling.fileinstall.writeback`|true|If the file provider supports writeback of
changed artifacts, e.g. if a configuration is changed through Config Admin the
change is written back to the file system.|
+
+## Bundles
+
+Bundles are supported by the OSGi installer. If a bundle jar is added to a
scanned directory, this bundle is installed. If the file is updated/changed,
the bundle is updated. If the file is removed, the bundle gets removed.
+Of course, these are the simple rules. The actual action depends by the
overall state of the system and is controlled by the OSGi installer. For
example if already the same bundle with a higher version is installed, when a
bundle is dropped into the install folder, the OSGi installer will perform no
operation.
+
+Start levels are supported as well by creating a directory with the name of
the start level within the scan directory and putting the bundles within this
directory. For example, if the 'install' folder is scanned, the bundle
'install/3/mybundle.jar' will be installed with start level 3. Without such a
directory the default start level is used.
+
+## Configurations
+
+Configurations are handled by the [Configuration Installer Factory]({{
refs.configuration-installer-factory.path }}). The different formats are
described there.
+
+## Custom Artifacts
+
+Custom artifacts are handled by the OSGi installer depending on the installed
plugins. Have a look at the OSGi installer and it's plugins for more
information.
+
+## Runmode Support
+
+The file installer supports run modes for installing artifacts. Within the
scanned directory, a folder named with the run mode will only provisioning
these artifacts if the respective run mode is active. If an artifact is
associated with several run modes, the name of the directory contains all of
them separated by a dot, for example *a1.dev*.
+
+# Project Info
+
+* File installer provider
([org.apache.sling.installer.provider.file](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/file))
Modified:
sling/site/trunk/content/documentation/bundles/jcr-installer-provider.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/jcr-installer-provider.mdtext?rev=1648494&r1=1648493&r2=1648494&view=diff
==============================================================================
---
sling/site/trunk/content/documentation/bundles/jcr-installer-provider.mdtext
(original)
+++
sling/site/trunk/content/documentation/bundles/jcr-installer-provider.mdtext
Tue Dec 30 09:45:30 2014
@@ -1,4 +1,3 @@
-translation_pending: true
Title: JCR Installer Provider
The JCR installer provider scans the JCR repository for artifacts and provides
them to the [OSGI installer]({{ refs.osgi-installer.path }}).
@@ -21,10 +20,10 @@ Artifacts from folders with a run mode g
Here's a quick walkthrough of the JCR installer functionality.
## Installation
-Start the Sling
[launchpad/app](http://svn.apache.org/repos/asf/sling/trunk/launchpad/app) and
install and start the following additional bundles:
+Start the Sling
[launchpad/app](http://svn.apache.org/repos/asf/sling/trunk/launchpad/app) and
make sure that the following bundles are present and started:
* [RunMode service]({{ refs.run-modes-org-apache-sling-runmode.path }})
-* OSGi installer service
([org.apache.sling.osgi.installer](http://svn.apache.org/repos/asf/sling/trunk/installer/core))
-* JCR installer provider
([org.apache.sling.jcr.jcrinstall](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr))
+* OSGi installer service
([org.apache.sling.installer.core](http://svn.apache.org/repos/asf/sling/trunk/installer/core))
+* JCR installer provider
([org.apache.sling.installer.provider.jcr](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr))
To watch the logs produced by these modules, you can filter
`sling/logs/error.log` using `egrep 'jcrinstall|osgi.installer'`.
@@ -135,3 +134,7 @@ The following modules contain lots of au
* JCR installer service
([org.apache.sling.installer.providers.jcr](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr))
Many of these tests are fairly readable, and can be used to find out in more
detail how these modules work.
+
+# Project Info
+
+* JCR installer provider
([org.apache.sling.installer.provider.jcr](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr))
Modified: sling/site/trunk/content/documentation/bundles/osgi-installer.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/osgi-installer.mdtext?rev=1648494&r1=1648493&r2=1648494&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/osgi-installer.mdtext
(original)
+++ sling/site/trunk/content/documentation/bundles/osgi-installer.mdtext Tue
Dec 30 09:45:30 2014
@@ -47,9 +47,18 @@ The OSGi installer asumes that a symboli
During development, SNAPSHOT versions should be used, like 1.0.0-SNAPSHOT
(using the Maven convention). If a bundle with a snapshot version is changed,
it gets updated by the OSGI installer.
-## Configuration Handling
+## Plugins
-In general the OSGi installer installs the configuration with the highest
priority. For example in combination with the JCR installer provider, a
configuration from */apps* is preferred over a configuration for the same
service from */libs*.
+### Factories
+An installer factory provides support for a specific artifact type, like a
configuration or a deployment package etc.
- [1]: http://svn.apache.org/repos/asf/sling/trunk/installer/it/
\ No newline at end of file
+* [Configuration Installer Factory]({{
refs.configuration-installer-factory.path }})
+* [Subsystem Installer Factory]({{ refs.subsystem-installer-factory.path }})
+
+### Providers
+
+A provider provides artifacts, e.g. by scanning a directory or a database etc.
+
+* [File Installer Provider]({{ refs.file-installer-provider.path }})
+* [JCR Installer Provider]({{ refs.jcr-installer-provider.path }})
Added:
sling/site/trunk/content/documentation/bundles/subsystem-installer-factory.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/subsystem-installer-factory.mdtext?rev=1648494&view=auto
==============================================================================
---
sling/site/trunk/content/documentation/bundles/subsystem-installer-factory.mdtext
(added)
+++
sling/site/trunk/content/documentation/bundles/subsystem-installer-factory.mdtext
Tue Dec 30 09:45:30 2014
@@ -0,0 +1,12 @@
+Title: Subsystems Installer Factory
+
+The subsystems installer factory provides support for subsystems to the [OSGI
installer]({{ refs.osgi-installer.path }}). The provisioning of artifacts is
handled by installer providers like the file installer or the JCR installer.
+
+
+## Subsystems
+
+The subsystem file must end with ".esa" and the manifest must at least contain
the subsystem symbolic name "Subsystem-SymbolicName" header.
+
+# Project Info
+
+* Subsystems installer factory
([org.apache.sling.installer.factory.subsystems](http://svn.apache.org/repos/asf/sling/trunk/installer/factories/subsystems))
Modified: sling/site/trunk/content/site/.htaccess
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/site/.htaccess?rev=1648494&r1=1648493&r2=1648494&view=diff
==============================================================================
--- sling/site/trunk/content/site/.htaccess (original)
+++ sling/site/trunk/content/site/.htaccess Tue Dec 30 09:45:30 2014
@@ -78,3 +78,4 @@ Redirect Permanent /site/dependency-mana
Redirect Permanent /site/issue-tracker.html
/documentation/development/issue-tracker.html
Redirect Permanent /site/osgi-installer.html
/documentation/bundles/osgi-installer.html
Redirect Permanent /site/mime-type-support-commonsmime.html
/documentation/bundles/mime-type-support-commons-mime.html
+Redirect Permanent /site/jcr-installer-provider.html
documentation/bundles/jcr-installer-provider.html
\ No newline at end of file
