Author: cziegeler
Date: Fri Sep 19 10:30:46 2014
New Revision: 1626173
URL: http://svn.apache.org/r1626173
Log:
Add initial slingstart docs
Added:
sling/site/trunk/content/documentation/development/slingstart.mdtext
Added: sling/site/trunk/content/documentation/development/slingstart.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/slingstart.mdtext?rev=1626173&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/development/slingstart.mdtext (added)
+++ sling/site/trunk/content/documentation/development/slingstart.mdtext Fri
Sep 19 10:30:46 2014
@@ -0,0 +1,96 @@
+Title: Apache SlingStart
+
+SlingStart defines a model to provision an OSGi based application. It can also
be used to define a partial application aka feature or subsystem.#
+
+The model is used by tooling, e.g. the slingstart-maven-plugin to build an
executable application or web application.
+
+## The Model
+
+The model is a simple API consisting of data objects:
+
+ * Subsystem : this is the central object holding all the definitions. A
subsystem consists of properties and run modes.
+ * Subsystem properties: These properties can be used as variables for version
definitions of artifacts.
+ * Run Mode : A run mode contains artifacts, configurations, and settings. The
artifacts are divided into start levels.
+ * Start Level: A start level contains a set of artifacts (usually bundles)
+ * Artifact: A deployable artifact
+ * Configuration: A OSGi configuration
+ * Settings : Framework settings for the OSGi framework
+
+### Run Modes
+
+The default run mode is always active, and all information provided there will
be used/started.
+Custom run modes can be used to configure for different situations. Depending
on which run mode is used to start the instance a different set of artifacts or
configurations is used.
+Each run mode is associated with a set of run mode names. Only if all listed
run modes are active, the definition is used.
+
+The model also supports special run modes, which are have special meaning. By
default, these pre defined special run modes are available:
+
+ * :base This run mode contains the dependency to Sling's launchpad artifact
to be used. This mode is required if Apache Sling Launchpad should be used to
start the application.
+ * :boot The artifacts that are installed before the framework is started.
They're used to bootstrap the system.
+ * :standalone Artifacts for the standalone application - in contrast to a war.
+ * :webapp Artifacts for the webapp only
+
+Other special run modes can be defined by using a single run mode name which
starts with a colon, like :test. These run modes can be used by special tooling.
+
+### Start Levels
+
+Each run mode has start levels. These start levels correspond to OSGi start
levels. The default start level has the level 0 and should be used for all non
bundle artifacts. If a non bundle artifact is configured with a start level,
it's still provisioned, however the start level information might not have any
meaning.
+
+### Artifacts
+
+An artifact is defined by maven coordinates, that is group id, artifact id and
version. Type and classifier can be specified, too. Type defaults to "jar".
Although the maven way of referring to an artifact is used, the model is in no
way tied to Maven and can be used with any tooling.
+
+### Configurations
+
+A configuration has a pid, or a factory pid and an alias and of course the
properties of the configuration object.
+Special configurations can be marked with a leading ":" of the pid. Special
configurations are not added to the OSGi config admin. There are some
predefined special configurations
+
+ * :web.xml This configuration must be part of the :webapp runmode and
contains a complete web.xml for the web application
+ * :bootstrap This configuration must be part of either the :boot, :base,
:standalone, or :webapp run mode and define the contents for bootstrap command
file executed by Launchpad.
+
+### Settings
+
+Settings are key value pairs that are added to the framework properties. For
now, only settings for the run modes :boot, :base, :standalone, or :webapp are
supported.
+
+## XML Configuration
+
+The XML format to define a subsystem is not as strict as the model itself,
e.g. it allows to directly specify artifacts and configurations on the
subsystem level. These are added to the default run mode.
+This makes the XML more compact as usually subsystems do not use specific
start levels.
+
+A subsystem can be configured through an XML file:
+
+ <?xml version="1.0"?>
+ <subsystem>
+ <properties>
+ eventadmin.version=1.0.0
+ metatype.version=1.2.0
+ </properties>
+ <runMode/>
+
+ <artifact groupId="org.apache.sling" artifactId="eventadmin"
version="${eventadmin.version}"/>
+ <artifact groupId="org.apache.sling" artifactId="metatype"
version="${metatype.version}"/>
+ <artifact groupId="org.apache.sling" artifactId="coordinator"
version="3.0.0"/>
+
+ <configuration pid="org.apache.sling.eventadmin">
+ useQueue=true
+ ignoreTopics=["myTopic"]
+ </configuration>
+ </subsystem>
+
+A configuration for a run mode looks like this:
+
+ <subsystem>
+ <runMode modes="mymode">
+
+ <artifact groupId="org.apache.sling" artifactId="metatype"
version="${metatype.version}"/>
+ <artifact groupId="org.apache.sling" artifactId="coordinator"
version="3.0.0"/>
+
+ <configuration pid="org.apache.sling.eventadmin">
+ useQueue=true
+ ignoreTopics=["myTopic"]
+ </configuration>
+
+ <startLevel level="5">
+ <artifact groupId="org.apache.sling" artifactId="eventadmin"
version="${eventadmin.version}"/>
+ </startLevel>
+ </runMode>
+ </subsystem>
