Merge branch 'master' of ssh://git.eclipse.org/gitroot/virgo/org.eclipse.virgo.documentation
diff --git a/.gitignore b/.gitignore
index be8893a..0f23b36 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,9 @@
target
+build/
integration-repo
ivy-cache
spring-build/lib/findbugs
spring-build/lib/docbook
+.gradle
+.idea/
+
diff --git a/build-documentation/build.xml b/build-documentation/build.xml
index 1721bb0..c0b1a7e 100644
--- a/build-documentation/build.xml
+++ b/build-documentation/build.xml
@@ -2,8 +2,6 @@
<project name="build-documentation" default="doc-html">
<path id="bundles">
- <pathelement location="${basedir}/../user-guide"/>
- <pathelement location="${basedir}/../programmer-guide"/>
<pathelement location="${basedir}/../tooling-guide"/>
</path>
diff --git a/build.gradle b/build.gradle
new file mode 100644
index 0000000..02d776a
--- /dev/null
+++ b/build.gradle
@@ -0,0 +1,32 @@
+buildscript {
+ repositories {
+ mavenCentral()
+ maven {
+ url "https://plugins.gradle.org/m2/"
+ }
+ }
+ dependencies {
+ classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
+ }
+}
+
+ext.docProjects = [
+ project(':programmer-guide'),
+ project(':user-guide'),
+]
+
+configure(docProjects) {
+ apply plugin: 'org.asciidoctor.convert'
+
+ asciidoctor {
+ resources {
+ from('src/docs/asciidoc') {
+ include 'assets/images/**/*.png'
+ }
+ }
+ }
+}
+
+task wrapper(type: Wrapper) {
+ gradleVersion = '3.1'
+}
diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar
new file mode 100644
index 0000000..6ffa237
--- /dev/null
+++ b/gradle/wrapper/gradle-wrapper.jar
Binary files differ
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
new file mode 100644
index 0000000..88d6b62
--- /dev/null
+++ b/gradle/wrapper/gradle-wrapper.properties
@@ -0,0 +1,6 @@
+#Sat Feb 04 18:08:13 CET 2017
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-3.1-bin.zip
diff --git a/gradlew b/gradlew
new file mode 100755
index 0000000..9aa616c
--- /dev/null
+++ b/gradlew
@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+
+##############################################################################
+##
+## Gradle start up script for UN*X
+##
+##############################################################################
+
+# Attempt to set APP_HOME
+# Resolve links: $0 may be a link
+PRG="$0"
+# Need this for relative symlinks.
+while [ -h "$PRG" ] ; do
+ ls=`ls -ld "$PRG"`
+ link=`expr "$ls" : '.*-> \(.*\)$'`
+ if expr "$link" : '/.*' > /dev/null; then
+ PRG="$link"
+ else
+ PRG=`dirname "$PRG"`"/$link"
+ fi
+done
+SAVED="`pwd`"
+cd "`dirname \"$PRG\"`/" >/dev/null
+APP_HOME="`pwd -P`"
+cd "$SAVED" >/dev/null
+
+APP_NAME="Gradle"
+APP_BASE_NAME=`basename "$0"`
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS=""
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD="maximum"
+
+warn ( ) {
+ echo "$*"
+}
+
+die ( ) {
+ echo
+ echo "$*"
+ echo
+ exit 1
+}
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "`uname`" in
+ CYGWIN* )
+ cygwin=true
+ ;;
+ Darwin* )
+ darwin=true
+ ;;
+ MINGW* )
+ msys=true
+ ;;
+ NONSTOP* )
+ nonstop=true
+ ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+ if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+ # IBM's JDK on AIX uses strange locations for the executables
+ JAVACMD="$JAVA_HOME/jre/sh/java"
+ else
+ JAVACMD="$JAVA_HOME/bin/java"
+ fi
+ if [ ! -x "$JAVACMD" ] ; then
+ die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+ fi
+else
+ JAVACMD="java"
+ which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
+ MAX_FD_LIMIT=`ulimit -H -n`
+ if [ $? -eq 0 ] ; then
+ if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
+ MAX_FD="$MAX_FD_LIMIT"
+ fi
+ ulimit -n $MAX_FD
+ if [ $? -ne 0 ] ; then
+ warn "Could not set maximum file descriptor limit: $MAX_FD"
+ fi
+ else
+ warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
+ fi
+fi
+
+# For Darwin, add options to specify how the application appears in the dock
+if $darwin; then
+ GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
+fi
+
+# For Cygwin, switch paths to Windows format before running java
+if $cygwin ; then
+ APP_HOME=`cygpath --path --mixed "$APP_HOME"`
+ CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+ JAVACMD=`cygpath --unix "$JAVACMD"`
+
+ # We build the pattern for arguments to be converted via cygpath
+ ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
+ SEP=""
+ for dir in $ROOTDIRSRAW ; do
+ ROOTDIRS="$ROOTDIRS$SEP$dir"
+ SEP="|"
+ done
+ OURCYGPATTERN="(^($ROOTDIRS))"
+ # Add a user-defined pattern to the cygpath arguments
+ if [ "$GRADLE_CYGPATTERN" != "" ] ; then
+ OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
+ fi
+ # Now convert the arguments - kludge to limit ourselves to /bin/sh
+ i=0
+ for arg in "$@" ; do
+ CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
+ CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option
+
+ if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition
+ eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
+ else
+ eval `echo args$i`="\"$arg\""
+ fi
+ i=$((i+1))
+ done
+ case $i in
+ (0) set -- ;;
+ (1) set -- "$args0" ;;
+ (2) set -- "$args0" "$args1" ;;
+ (3) set -- "$args0" "$args1" "$args2" ;;
+ (4) set -- "$args0" "$args1" "$args2" "$args3" ;;
+ (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
+ (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
+ (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
+ (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
+ (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
+ esac
+fi
+
+# Split up the JVM_OPTS And GRADLE_OPTS values into an array, following the shell quoting and substitution rules
+function splitJvmOpts() {
+ JVM_OPTS=("$@")
+}
+eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS
+JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME"
+
+# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
+if [[ "$(uname)" == "Darwin" ]] && [[ "$HOME" == "$PWD" ]]; then
+ cd "$(dirname "$0")"
+fi
+
+exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"
diff --git a/gradlew.bat b/gradlew.bat
new file mode 100644
index 0000000..e95643d
--- /dev/null
+++ b/gradlew.bat
@@ -0,0 +1,84 @@
+@if "%DEBUG%" == "" @echo off
+@rem ##########################################################################
+@rem
+@rem Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%" == "" set DIRNAME=.
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if "%ERRORLEVEL%" == "0" goto init
+
+echo.
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto init
+
+echo.
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:init
+@rem Get command-line arguments, handling Windows variants
+
+if not "%OS%" == "Windows_NT" goto win9xME_args
+
+:win9xME_args
+@rem Slurp the command line arguments.
+set CMD_LINE_ARGS=
+set _SKIP=2
+
+:win9xME_args_slurp
+if "x%~1" == "x" goto execute
+
+set CMD_LINE_ARGS=%*
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+
+:end
+@rem End local scope for the variables with windows NT shell
+if "%ERRORLEVEL%"=="0" goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
+exit /b 1
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega
diff --git a/programmer-guide/build.xml b/programmer-guide/build.xml
deleted file mode 100644
index 7200327..0000000
--- a/programmer-guide/build.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="virgo-programmer-guide">
-
- <property file="${basedir}/../build.properties"/>
- <property file="${basedir}/../build.versions"/>
- <import file="${basedir}/../virgo-build/docbook/default.xml"/>
-
- <filterset id="docbook.filters">
- <filter token="bundle.version" value="${bundle.version}"/>
- <filtersfile file="${basedir}/filters.properties"/>
- </filterset>
-
-</project>
diff --git a/programmer-guide/ivy.xml b/programmer-guide/ivy.xml
deleted file mode 100644
index fecb32f..0000000
--- a/programmer-guide/ivy.xml
+++ /dev/null
@@ -1,23 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>
-<ivy-module
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd"
- version="1.3">
-
- <info organisation="${project.organisation}" module="${ant.project.name}"/>
-
- <configurations>
- <include file="${virgo.build.dir}/common/default-ivy-configurations.xml"/>
- <conf name="doc" visibility="public" description="Documentation"/>
- </configurations>
-
- <publications>
- <!-- <artifact name="${ant.project.name}" ext="pdf" type="pdf"/> -->
- <artifact name="${ant.project.name}" ext="zip" type="zip"/>
- <artifact name="${ant.project.name}-single" ext="zip" type="zip"/>
- </publications>
-
- <dependencies/>
-
-</ivy-module>
diff --git a/programmer-guide/src/architecture.xml b/programmer-guide/src/architecture.xml
deleted file mode 100644
index 3ba9c5a..0000000
--- a/programmer-guide/src/architecture.xml
+++ /dev/null
@@ -1,476 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="architecture">
- <title>Deployment Architecture</title>
- <para> The @tomcat.product.name@ offers several choices when it comes to deploying applications. Each
- choice offers certain advantages, and it is important to understand those in order to make
- the right choice for your application. In this chapter, we take a closer look at the choices
- offered, compare them, and provide guidelines in choosing the right one based on your
- specific needs. </para>
- <para> The @tomcat.product.name.short@ supports standard self-contained WAR files thus allowing you to
- use the @tomcat.product.name@ as an enhanced web server. The @tomcat.product.name.short@ also supports the
- <emphasis>Shared Libraries</emphasis> WAR format which allows for slimmer WAR files that
- depend on OSGi bundles instead of including JAR files inside the WAR. The <emphasis>Shared
- Services</emphasis> WAR format allows developers to further reduce the complexity of
- standard WARs by deploying services and infrastructure bundles alongside the WAR. A shared
- services WAR will then consume the services published by those bundles. To complete the
- picture, the @tomcat.product.name.short@ supports the new OSGi-standard <emphasis>Web Application
- Bundle</emphasis> deployment format for web applications that builds on the benefits
- provided by a shared services WAR. In addition to this, @tomcat.product.name.short@ provides
- additional conveniences for developing and deploying Spring MVC-based web applications. </para>
- <para>For applications consisting of multiple bundles and web applications, plans and the PAR
- format are the primary deployment models that take advantage of OSGi capabilities. We will
- explore all of these formats and their suitability later in this guide.</para>
- <!-- ======================================================================= -->
- <!-- ======================================================================= -->
- <section id="architecture-deployment-formats">
- <title>Supported Deployment Formats</title>
- <para> The @tomcat.product.name@ supports applications packaged in the following formats: </para>
- <orderedlist>
- <listitem>
- <para><link linkend="architecture-raw-osgi-bundles">Raw OSGi Bundles</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-wars">Java EE WAR</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-war-gemini">Web Application Bundles</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-pars">PARs</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-plans">Plans</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-configurations">Configurations</link></para>
- </listitem>
- </orderedlist>
- <para> When you deploy an application to the @tomcat.product.name.short@, each deployment artifact
- (e.g., a single bundle, WAR, PAR, or plan) passes through a deployment pipeline. This
- deployment pipeline is responsible for processing applications of certain types (i.e.,
- application type). The @bundle.version@ release of the @tomcat.product.name.short@ natively
- supports deployers analogous to each of the aforementioned packaging options. </para>
- <para> Let’s take a closer look now at each of the supported deployment and packaging
- options to explore which one is best suited to your application.</para>
- <section id="architecture-raw-osgi-bundles">
- <title>Raw OSGi Bundles</title>
- <para> At its core, the @tomcat.product.name@ is an OSGi container. Thus any OSGi-compliant
- bundle can be deployed directly on the @tomcat.product.name.short@ unmodified. You’ll
- typically deploy an application as a single bundle or a set of stand-alone bundles
- if you’d like to publish or consume services globally within the container via
- the OSGi Service Registry. </para>
- </section>
- <section id="architecture-wars">
- <title>WAR Deployment Formats</title>
- <para> For Web Application Archives (WAR), the @tomcat.product.name@ provides support for the
- following three formats. </para>
- <orderedlist>
- <listitem>
- <para><link linkend="architecture-standard-war">Standard WAR</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-shared-libraries-war">Shared Libraries
- WAR</link></para>
- </listitem>
- <listitem>
- <para><link linkend="architecture-shared-services-war">Shared Services
- WAR</link></para>
- </listitem>
- </orderedlist>
- <para> Each of these formats plays a distinct role in the incremental migration path
- from a standard Java EE WAR to an OSGi-ified web application.</para>
- <section id="architecture-standard-war">
- <title>Standard WAR</title>
- <para> Standard WAR files are supported directly in the @tomcat.product.name.short@. At
- deployment time, the WAR file is transformed into an OSGi bundle and installed
- into Tomcat. All the standard WAR contracts are honoured, and your existing WAR
- files should just drop in and deploy without change. Support for standard,
- unmodified WAR files allows you to try out the @tomcat.product.name@ on your existing
- web applications and then gradually migrate toward the <emphasis>Shared
- Libraries WAR</emphasis> and <emphasis>Shared Services WAR</emphasis>
- formats. </para>
- <para> In addition to the standard support for WARs that you would expect from
- Tomcat, the @tomcat.product.name.short@ also enables the following features:</para>
- <orderedlist>
- <listitem>
- <para>Spring-driven load-time weaving (see Section 6.8.4, “Load-time weaving
- with AspectJ in the Spring Framework").</para>
- </listitem>
- <listitem>
- <para>Diagnostic information such as FFDC (first failure data
- capture)</para>
- </listitem>
- </orderedlist>
- <para> The main benefit of this application style is familiarity -- developers know
- how to create a WAR file! You can take advantage of the
- @tomcat.product.name.short@’s added feature set without modifying the
- application. The application can also be deployed on other Servlet containers or
- Java EE application servers.</para>
- <para> You may choose this application style if the application is fairly simple and
- small. You may also prefer this style even for large and complex applications as
- a starting point and migrate to the other styles over time as discussed in <xref
- linkend="migrating-to-osgi"/> . </para>
- </section>
- <section id="architecture-shared-libraries-war">
- <title>Shared Libraries WAR</title>
- <para> If you have experience with developing and packaging web applications using
- the standard WAR format, you’re certainly familiar with the pains of
- library bloat. So, unless you’re installing shared libraries in a common
- library folder for your Servlet container, you have to pack all JARs required by
- your web application in <literal>/WEB-INF/lib</literal>. Prior to the release of
- the @tomcat.product.name@, such library bloat has essentially been the norm for web
- applications, but now there is a better solution! The Shared Libraries WAR
- format reduces your application’s deployment footprint and eradicates
- library bloat by allowing you to declare dependencies on libraries via standard
- OSGi manifest headers such as <literal>Import-Package</literal> and <literal
- >Require-Bundle</literal> . The @tomcat.product.name.short@ provides additional
- support for simplifying dependency management via the <literal
- >Import-Library</literal> and <literal>Import-Bundle</literal> manifest headers
- which are essentially macros that get expanded into OSGi-compliant <literal
- >Import-Package</literal> statements. </para>
- <tip>
- <para> For detailed information on which libraries are already available, check
- out the <ulink url="http://www.springsource.com/repository">@ebr@ </ulink> .
- </para>
- </tip>
- </section>
- <section id="architecture-shared-services-war">
- <title>Shared Services WAR</title>
- <para> Once you’ve begun taking advantage of declarative dependency management
- with a Shared Libraries WAR, you’ll likely find yourself wanting to take
- the next step toward reaping further benefits of an OSGi container: sharing
- services between your OSGi-compliant bundles and your web applications. By
- building on the power and simplicity of Spring-DM, the <emphasis>Shared Services
- WAR</emphasis> format puts the OSGi Service Registry at your finger tips. As
- a best practice you’ll typically publish services from your domain,
- service, and infrastructure bundles via <literal><osgi:service ...
- /></literal> and then consume them in your web application’s
- ApplicationContext via <literal><osgi:reference ... /></literal>. Doing so
- promotes programming to interfaces and allows you to completely decouple your
- web-specific deployment artifacts from your domain model, service layer, etc.,
- and that’s certainly a step in the right direction. Of the three supported
- WAR deployment formats, the Shared Services WAR is by far the most attractive in
- terms of modularity and reduced overall footprint of your web applications.
- </para>
- </section>
- <section id="architecture-war-gemini">
- <title>WARs and the Gemini Web Container</title>
- <para>
- @tomcat.product.name@ fully supports the OSGi Web Applications standard. Using the
- reference implementation from Gemini Web that was developed by SpringSource from
- an offshoot of the original @tomcat.product.name.short@ codebase. This RI is now fully
- integrated in @tomcat.product.name.short@ as the basis of the support for web
- application deployment.
- </para>
- <para>
- The OSGi Web Applications specification introduces the concept of a <emphasis>Web
- Application Bundle</emphasis>, which is a WAR that is also a bundle. The
- specification defines how WAR files are transformed into bundles automatically
- as needed.
- </para>
- <para>
- You can find an introduction to the Web Container in blog entries written by
- the @project.name@ team <ulink
- url="http://blog.springsource.com/2009/05/27/introduction-to-the-osgi-web-container/"
- >here</ulink> and <ulink
- url="http://blog.springsource.com/2009/06/01/what-the-osgi-web-container-means-for-dm-server/"
- >here</ulink>. </para>
- <section id="architecture-war-gemini-extensions">
- <title>Extensions to the Web Container</title>
- <para> @tomcat.product.name@ provides a variety of extensions to the Web Container that
- allow you to construct sophisticated applications. The table below
- summarises the extensions that are available or in development. </para>
- <table colsep="1" rowsep="3">
- <tgroup cols="2">
- <colspec width="1*"/>
- <colspec width="1*"/>
- <thead>
- <row>
- <entry>Feature</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Instrumentable ClassLoaders</entry>
- <entry>All web bundle ClassLoaders are instrumentable by
- Spring’s load-time weaving infrastructure.</entry>
- </row>
- <row>
- <entry>Support for exploded bundles/WARs</entry>
- <entry>Bundles/WARs in directory form can be deployed as Web
- Application Bundles
- </entry>
- </row>
- <row>
- <entry>Support for scanning TLDs in dependencies</entry>
- <entry>As per the Web Application specification, all TLDs located
- inside a web bundle are located using the rules defined in
- the JSP 2.1 specification. In @tomcat.product.name.short@, the
- dependencies of a Web Application Bundle are also scanned for TLDs
- following the rules outlined in JSP 2.1
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
- </section>
- <section id="architecture-pars">
- <title>PAR</title>
- <para> A PAR is a standard JAR which contains all of the modules of your application
- (e.g., service, domain, and infrastructure bundles as well as a WAR or web module
- for web applications) in a single deployment unit. This allows you to deploy,
- refresh, and undeploy your entire application as a single entity. If you are
- familiar with Java EE, it is worth noting that a PAR can be considered a replacement
- for an EAR (Enterprise Archive) within the context of an OSGi container. As an added
- bonus, modules within a PAR can be refreshed independently and on-the-fly, for
- example via the Virgo Eclipse IDE Tooling (see the Virgo Tools Guide). </para>
- <para> Many of the benefits of the PAR format are due to the underlying OSGi
- infrastructure, including: <itemizedlist>
- <listitem>
- <para> Fundamentally modularized applications: instead of relying on fuzzy
- boundaries between logical modules in a monolithic application, this
- style promotes physically separated modules in the form of OSGi bundles.
- Then each module may be developed separately, promoting parallel
- development and loose coupling.</para>
- </listitem>
- <listitem>
- <para> Robust versioning of various modules: the versioning capability
- offered by OSGi is much more comprehensive than alternatives. Each
- module can specify a version range for each of its dependencies. Bundles
- are isolated from each other in such a way that multiple versions of a
- bundle may be used simultaneously in an application.</para>
- </listitem>
- <listitem>
- <para> Improved manageability: each bundle may be deployed or undeployed in
- a running application. This allows modifying the existing application to
- fix bugs, improve performance, and even to add new features without
- having to restart the application.</para>
- </listitem>
- </itemizedlist></para>
- <para> Furthermore, PARs scope the bundles of your application within the
- @tomcat.product.name.short@. Scoping provides both a physical and logical application
- boundary, effectively shielding the internals of your application from other PARs
- deployed within the @tomcat.product.name.short@. This means your application doesn’t
- have to worry about clashing with other running applications (e.g., in the OSGi
- Service Registry). You get support for load-time weaving, classpath scanning,
- context class loading, etc., and the @tomcat.product.name.short@ does the heavy lifting for
- you to make all this work seamlessly in an OSGi environment. If you want to take
- full advantage of all that the @tomcat.product.name@ and OSGi have to offer, packaging and
- deploying your applications as a PAR is a good choice, although plans are an even
- better one, as described in the next section.</para>
- <tip>
- <title>OSGi != multiple JARs</title>
- <para> Note that while physically separated modules can, in theory, be implemented
- simply using multiple JARs, complex versioning requirements often make this
- impractical. For example, consider the situation depicted in the diagram below. <itemizedlist>
- <listitem>
- <para>Bundle A depends on version 1.0.0 of bundle B and version 2.0.0 of
- bundle C.</para>
- </listitem>
- <listitem>
- <para>Bundle B depends on version 1.0.0 of bundle C.</para>
- </listitem>
- </itemizedlist> Suppose that versions 1.0.0 and 2.0.0 of bundle C are neither
- backward nor forward compatible. Traditional monolithic applications cannot
- handle such situations: either bundle A or bundle B would need reworking which
- undermines truly independent development. OSGi’s versioning scheme enables
- this scenario to be implemented in a robust manner. If it is desirable to rework
- the application to share a single version of C, then this can be planned in and
- is not forced. </para>
- <mediaobject>
- <imageobject><imagedata fileref="images/architecture-bundle-versioning.png"
- /></imageobject>
- </mediaobject>
- </tip>
- </section>
- <section id="architecture-plans">
- <title>Plans</title>
- <para> A plan is similar to a PAR in that it encapsulates all of the artifacts of your
- application in a single deployment unit. The main difference, however, is that a
- plan is simply an XML file that lists the artifacts of your application; a PAR, by
- contrast, is an actual JAR file that physically contains the artifacts. Just like a
- PAR, you deploy, refresh, and undeploy a plan as a single entity. We highly
- recommends the use of plans for creating applications. </para>
- <para> When you create a plan, you can specify that the included bundles and services
- are in a scope that isolates them from the rest of @tomcat.product.name@ and its
- deployments. This scoping ensures that the bundles wire to each other and see each
- other’s services in preference to services from outside the scope. Scoping
- also prevents application code from leaking into the global scope or scope of
- another application. In addition, a plan can link the lifecycle of a group of
- bundles together atomically, which ensures that start, stop, and uninstall
- events on a single artifact in the plan are escalated to all artifacts in the plan.
- You can, however, disable both of these features by simply setting an attribute in
- the plan. </para>
- <para> The general benefits of using plans are similar to those of using PARs; see <link
- linkend="architecture-pars">PAR</link> for details. Plans offer added benefits,
- however, such as the ability to control the deployment order of your application:
- the order in which you list artifacts in the plan’s XML file is the order in
- which @tomcat.product.name.short@ deploys them. Additionally, because plans specify the
- artifacts that make up an application by reference, it is easier to share artifacts
- between plans as well as update individual parts of a plan without having to
- physically repackage (re-JAR) it. </para>
- </section>
- <section id="architecture-configurations">
- <title>Configurations</title>
- <para>A Configuration is simply a Java properties file. When deployed it will be
- recognised by the deployer and installed in to <emphasis>Configuration
- Admin</emphasis> for later use by your applications. @tomcat.product.name.short@ supports
- both singleton (ManagedService) and factory (ManagedServiceFactory) configurations.
- (see section 104.6 in the Compendium Specification) </para>
- <para>For a singleton configuration the name that it will be installed under is its filename
- minus the <code>.properties</code> extension. Factory Configuration is supported by
- specifying the <emphasis>service.factoryPid</emphasis> property. In this case the actual PID will
- be created by <emphasis>Configuration Admin</emphasis> (see section 104.6 in the
- Compendium Specification).</para>
- <para>How to consume configuration data is discussed <link
- linkend="developing-applications-configuration-artifacts">later</link>. </para>
- </section>
- </section>
- <!-- ======================================================================= -->
- <!-- ======================================================================= -->
- <section id="architecture-dependency-types">
- <title>Dependency Types</title>
- <para>
- In an OSGi environment, there are two kinds of dependencies between various bundles:
- <emphasis>type</emphasis> dependency and <emphasis>service</emphasis> dependency.
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Type dependency</emphasis>: A bundle may depend on a
- type exported by another bundle thus creating a type dependency. Type
- dependencies are managed through <literal>Import-Package</literal> and
- <literal>Export-Package</literal> directives in the OSGi manifest. This
- kind of dependency is similar to a JAR file using types in other JAR files
- from the classpath. However, as we’ve seen earlier, there are
- significant differences.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Service dependency</emphasis>: A bundle may also
- publish services (preferably using Spring-DM), and other bundles may consume
- those services. If two bundles depend on the same service, both will be
- communicating effectively to the same object. More specifically, any state
- for that service will be shared between all the clients of that service.
- This kind of arrangement is similar to the commonly seen client-server
- interaction through mechanisms such as RMI or Web Services.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <!-- ======================================================================= -->
- <!-- ======================================================================= -->
- <section id="regions">
- <title>Regions</title>
- <para>
- Conceptually, the @umbrella.product.name@ can be divided into two separate subsystems, called Regions. This
- provides a way to keep the @kernel.product.name@ separate from user applications. Read more about Regions
- and the two in @project.name@ in the <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink>
- concepts section.
- </para>
- </section>
-
- <!-- ======================================================================= -->
- <!-- ======================================================================= -->
- <section id="architecture-forming-bundles">
- <title>A Guide to Forming Bundles</title>
- <para>
- So what makes an application suitable for deployment on the @tomcat.product.name@? Since
- OSGi is at the heart of the @tomcat.product.name.short@, modular applications consisting of
- bundles, which each represent distinct functionality and well-defined boundaries, can
- take maximum advantage of the OSGi container’s capabilities. The core ideas behind
- forming bundles require following good software engineering practices: separation of
- concerns, loose coupling, and communication through clear interfaces. In this section,
- we look at a few approaches that you may use to create modular applications for
- @tomcat.product.name@ deployment. Please consider the following discussion as guidelines and
- not as rules.
- </para>
- <para>
- Bundles can be formed along horizontal slices of layering and vertical slices of
- function. The objective is to enable independent development of each bundle and minimize
- the skills required to develop each bundle.
- </para>
- <para> For example, an application could have the following bundles:
- <emphasis>infrastructure</emphasis>, <emphasis>domain</emphasis>,
- <emphasis>repository</emphasis>, <emphasis>service</emphasis>, and
- <emphasis>web</emphasis> as shown in the following diagram.</para>
- <para><mediaobject>
- <imageobject><imagedata fileref="images/bundle-dependencies-layers.png"
- /></imageobject>
- </mediaobject> Each bundle consists of types appropriate for that layer and exports
- packages and services to be used by other layers. Let’s examine each bundle in
- more detail: <table id="architecture-forming-bundles-across-layers-table" colsep="1"
- frame="all" rowsep="1">
- <title>Bundles across layers</title>
- <tgroup cols="5">
- <colspec colwidth="1*"/>
- <colspec colwidth="2*"/>
- <colspec colwidth="1*"/>
- <colspec colwidth="1*"/>
- <colspec colwidth="1*"/>
- <thead>
- <row>
- <entry>Bundles</entry>
- <entry>Imported Packages</entry>
- <entry>Exported Packages</entry>
- <entry>Consumed Services</entry>
- <entry>Published Services</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Infrastructure</entry>
- <entry>Third-party libraries</entry>
- <entry>Infrastructure interfaces</entry>
- <entry>None</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry>Domain</entry>
- <entry>Depends: for example, if JPA is used to annotate persistent
- types, then JPA packages.</entry>
- <entry>Public domain types</entry>
- <entry>None</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry>Web</entry>
- <entry>Domain, Service</entry>
- <entry>None</entry>
- <entry>Service beans</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry>Service</entry>
- <entry>Domain, Infrastructure, Repository</entry>
- <entry>Service interfaces</entry>
- <entry>Repository beans</entry>
- <entry>Service beans</entry>
- </row>
- <row>
- <entry>Repository</entry>
- <entry>Domain, Third-party libraries, ORM bundles, etc.</entry>
- <entry>Repository interfaces</entry>
- <entry>DataSources, ORM session/entity managers, etc.</entry>
- <entry>Repository beans</entry>
- </row>
- </tbody>
- </tgroup>
- </table></para>
- <para> Within each layer, you may create bundles for each subsystem representing a vertical
- slice of business functionality. For example, as shown in the following figure, the
- service layer is divided into two bundles each representing separate business
- functions. <mediaobject>
- <imageobject><imagedata fileref="images/bundle-dependencies-verticals.png"
- /></imageobject>
- </mediaobject></para>
- <para> You can similarly separate the repositories, domain classes, and web controllers
- based on the business role they play.</para>
- </section>
-</chapter>
diff --git a/programmer-guide/src/common-libraries.xml b/programmer-guide/src/common-libraries.xml
deleted file mode 100644
index cc5cbea..0000000
--- a/programmer-guide/src/common-libraries.xml
+++ /dev/null
@@ -1,82 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="common-libraries">
- <title>Working with Common Enterprise Libraries</title>
- <titleabbrev>Common Libraries</titleabbrev>
- <section id="common-libraries-hibernate">
- <title>Working with Hibernate</title>
- <section id="common-libraries-hibernate-import">
- <title>Importing Hibernate</title>
- <para>
- Hibernate uses CGLIB to dynamically create subclasses of your entity types at
- runtime. To guarantee that Hibernate and CGLIB can correctly see the types,
- you must add an <literal>Import-Library</literal> or <literal>Import-Bundle</literal> for the Hibernate library or bundle
- into any bundle that uses Hibernate directly.
- </para>
- <para>
- Additionally, if other bundles in your application contain types to be persisted by Hibernate, then be sure to specify the <code>import-scope</code> directive of the <literal>Import-Bundle</literal> header in the bundle that uses Hibernate directly. The <literal>import-scope</literal> directive tells @tomcat.product.name@ to implicitly import the bundle into all other bundles that make up the application; this ensures that bundles that indirectly depend on the generated Hibernate classes have access to them, but you do not have to explicitly update their <code>Import-Bundle</code> header, ensuring modularity. For example:
- </para>
- <programlisting>
-Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";<emphasis role="bold">import-scope:=application</emphasis></programlisting>
- <para>
- The <code>import-scope</code> directive works only for the bundles in a scoped application (PARs or plans.)
- </para>
-
- </section>
- </section>
- <section id="common-libraries-datasources">
- <title>Working with DataSources</title>
- <para>
- Many <literal>DataSource</literal> implementations use the <literal>DriverManager</literal>
- class which is incompatible with typical OSGi class loading semantics. To get around this,
- use a <literal>DataSource</literal> implementation that does not rely on
- <literal>DriverManager</literal>. Versions of the following
- <literal>DataSources</literal> that are known to work in an OSGi environment are available in the
- <ulink url="http://www.springsource.com/repository">@ebr@</ulink>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <ulink url="http://www.springsource.com/repository/app/bundle/detail?name=com.springsource.org.apache.commons.dbcp">Apache Commons DBCP</ulink>
- </para>
- </listitem>
- <listitem>
- <para>SimpleDriverDataSource available in
- <ulink url="http://www.springsource.com/repository/app/bundle/detail?name=org.springframework.jdbc">Spring JDBC</ulink>
- 2.5.5 and later
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="common-libraries-weaving-instrumentation">
- <title>Weaving and Instrumentation</title>
- <para>
- When using a library that performs bytecode weaving or instrumentation, such as AspectJ,
- OpenJPA or EclipseLink, any types that are woven must be able to see the library doing
- the weaving. This is accomplished by adding an <literal>Import-Library</literal> for the
- weaving library into all bundles that are to be woven.
- </para>
- <para>
- Weaving is often used by JPA implementations to transform persisted types. When using a
- JPA provider that uses load-time weaving, an <literal>Import-Library</literal> for the
- provider is needed in the bundles containing the persisted types.
- </para>
- </section>
- <section id="common-libraries-tld">
- <title>JSP Tag Libraries</title>
- <para>
- When using tag libraries within a WAR or WAB, be sure to include an <literal>Import-Bundle</literal>
- or <literal>Import-Library</literal> for the tag library bundle(s). This will ensure that your WAR or WAB
- can see the TLD definition and implementing types. For example, to use the Apache implementation of JSTL,
- add the following to your bundle’s <literal>/META-INF/MANIFEST.MF</literal>:
- </para>
-<programlisting>
-<emphasis role="bold">Import-Bundle</emphasis>: com.springsource.org.apache.taglibs.standard;version="1.1.2"
-</programlisting>
- <para>
- <literal>Import-Package</literal> can also be used but it is tedious to add all the imports as there are
- typically lots of tld definitions in a bundle providing them.
- </para>
- </section>
-</chapter>
diff --git a/programmer-guide/src/developing-applications.xml b/programmer-guide/src/developing-applications.xml
deleted file mode 100644
index 89c2fa1..0000000
--- a/programmer-guide/src/developing-applications.xml
+++ /dev/null
@@ -1,1115 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="developing-applications">
- <title>Developing Applications</title>
- <para>
- Applications that take advantage of the OSGi capabilities of @project.name@
- are typically comprised of multiple bundles. Each bundle may have dependencies on
- other bundles. Furthermore, each bundle exposes only certain packages and
- services. In this chapter, we look at how to create bundles, import and export
- appropriate functionality, and create artifacts to deploy web applications on the @tomcat.product.name@.
- </para>
- <section id="developing-applications-bundle">
- <title>Anatomy of a Bundle</title>
- <tip>
- <para>
- This is an abbreviated introduction to OSGi bundles. Please refer to the
- <ulink url="http://static.springframework.org/osgi/docs/current/reference/html/">
- Spring Dynamic Modules for OSGi documentation</ulink> for full details.
- </para>
- </tip>
- <para>
- An OSGi bundle is simply a jar file with metadata that describe
- additional characteristics such as version and imported and exported packages.
- </para>
- <para>
- A bundle exports types and publishes services to be used by other bundles:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Types</emphasis>:
- via the OSGi <code>Export-Package</code> directive,
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Services</emphasis>:
- via Spring-DM’s <code><service ... /></code> XML namespace element.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- A bundle may import types and services exported by other bundles:
- </para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Types</emphasis>:
- via the OSGi <code>Import-Package</code> directive,</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Services</emphasis>:
- via Spring-DM’s <code><reference ... /></code> XML namespace element.</para>
- </listitem>
- </itemizedlist>
-
- <para>
- Let’s see an example from the PetClinic sample application. The following listing shows the
- <filename>MANIFEST.MF</filename> file for the <code>org.springframework.petclinic.infrastructure.hsqldb</code> bundle.
- </para>
- <programlisting>
-Manifest-Version: 1.0
-<emphasis role="bold">Bundle-ManifestVersion</emphasis>: 2
-<emphasis role="bold">Bundle-Name</emphasis>: PetClinic HSQL Database Infrastructure
-<emphasis role="bold">Bundle-SymbolicName</emphasis>: org.springframework.petclinic.infrastructure.hsqldb
-<emphasis role="bold">Bundle-Version</emphasis>: 1.0
-<emphasis role="bold">Import-Library</emphasis>: org.springframework.spring;version="[2.5,2.6]"
-<emphasis role="bold">Import-Bundle</emphasis>: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi,1.2.2.osgi]",
- com.springsource.org.hsqldb;version="[1.8.0.9,1.8.0.9]"
-<emphasis role="bold">Import-Package</emphasis>: javax.sql
-<emphasis role="bold">Export-Package</emphasis>: org.springframework.petclinic.infrastructure
- </programlisting>
- <para>
- The <code>org.springframework.petclinic.infrastructure.hsqldb</code> bundle expresses its dependencies on
- the <code>javax.sql</code> package, the Commons DBCP and HSQLDB bundles, and the Spring library (we will examine
- the details of the library artifact in <xref linkend="developing-applications-defining-libraries"/>). The Commons DBCP
- bundle is imported at a version of exactly 1.2.2.osgi and the HSQLDB bundle is imported at a version of exactly
- 1.8.0.9. The Spring library is imported at a version between 2.5 inclusive and 2.6 exclusive.
- </para>
-
- <para>
- Note that you do not specify the bundle that will provide the imported packages.
- @project.name@ will examine the available bundles and satisfy the required dependencies.
- </para>
- <para>
- The following <filename>osgi-context.xml</filename> file from the PetClinic sample’s
- <code>org.springframework.petclinic.repository.jdbc</code> bundle declares a service published by the bundle and
- references a service published by another bundle.
- </para>
- <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<beans:beans xmlns="http://www.springframework.org/schema/osgi"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:beans="http://www.springframework.org/schema/beans"
- xsi:schemaLocation="http://www.springframework.org/schema/osgi
- http://www.springframework.org/schema/osgi/spring-osgi.xsd
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans.xsd">
-
- <service id="osgiClinic" ref="clinic" interface="org.springframework.petclinic.repository.Clinic" />
- <reference id="dataSource" interface="javax.sql.DataSource"/>
-
-</beans:beans>]]></programlisting>
- <para>
- The <code>service</code> element publishes the <code>clinic</code> bean
- (a regular Spring bean declared in the <filename>module-context.xml</filename> file) and specifies
- <code>org.springframework.petclinic.repository.Clinic</code> as the type
- of the published service.
- </para>
- <para>The <code>reference</code> elements define a <code>dataSource</code> bean that references
- a service published by another bundle with a an interface type of <code>javax.sql.DataSource</code>.
- </para>
- </section>
-
- <section id="developing-applications-packaging">
- <title>Creating PARs and Web Applications</title>
- <para>
- @project.name@ supports two OSGi-oriented ways of packaging applications: the PAR format
- and application bundles (including web bundles). The @tomcat.product.name.short@ also supports three
- distinct WAR deployment and packaging formats: standard Java EE WAR, Shared Libraries WAR, Shared Services WAR.
- </para>
- <para>
- @project.name@ also supports plans as a way to describe an application. This method is similar to a PAR
- in that it encapsulates all the artifacts of an application as a single unit, but differs in that a plan simply
- lists the bundles in an XML file rather than packaging all the bundles in a single JAR file. The use of plans
- offers additional benefits to using PARs; for this reason, we recommend their use. For details, see
- <link linkend="developing-applications-plans">Creating Plans</link>.
- </para>
- <section id="developing-applications-packaging-par">
- <title>PARs</title>
- <para>
- An OSGi application is packaged as a JAR file, with extension <literal>.par</literal>. A PAR artifact offers several benefits:
- <itemizedlist>
- <listitem>A PAR file has an application name, version, symbolic name, and description.</listitem>
- <listitem>The artifacts of a PAR file are scoped so that they cannot
- be shared accidentally by other applications. The scope forms a boundary for automatic
- propagation of load time weaving and bundle refresh.
- See <link linkend="developing-applications-plans-scoping">Plans and Scoping</link> for more on scoping.
- </listitem>
- <listitem>Since a PAR is scoped, its artifacts have their exported packages imported by the
- synthetic context bundle which is used for thread context class loading. So,
- for example, hibernate will be able to load classes of any of the exported
- packages of the bundles in a PAR file using the thread context class loader.</listitem>
- <listitem>A PAR file is visible to management interfaces.</listitem>
- <listitem>A PAR file can be undeployed and redeployed as a unit.</listitem>
- <listitem>
- A PAR file is <emphasis>atomic</emphasis> in that it ties together the lifecycle of its artifacts. If you start, stop, or uninstall
- one of a PAR's artifacts, @project.name@ escalates the operation to the whole PAR file.
- So @project.name@ prevents artifacts of a PAR from being in inconsistent states.
- For example, if one artifact should fail to start, then @project.name@ stops all artifacts in the PAR.
- </listitem>
- </itemizedlist>
- See <link linkend="developing-applications-plans-scoping">Plans and Scoping</link> for more information on scoping.
- </para>
- <para>
- A PAR includes one or more application bundles and its manifest specifies the following
- manifest headers:
- <table id="developing-applications-packaging-par-headers-table" colsep="1" frame="all" rowsep="1">
- <title>PAR file headers</title>
- <tgroup cols="2">
- <colspec colwidth="2*" />
- <colspec colwidth="3*" />
- <thead>
- <row>
- <entry>Header</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>Application-SymbolicName</literal></entry>
- <entry>Identifier for the application which, in combination with Application-Version, uniquely identifies an application</entry>
- </row>
- <row>
- <entry><literal>Application-Name</literal></entry>
- <entry>Human readable name of the application</entry>
- </row>
- <row>
- <entry><literal>Application-Version</literal></entry>
- <entry>Version of the application</entry>
- </row>
- <row>
- <entry><literal>Application-Description</literal></entry>
- <entry>Short description of the application</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- The following code shows an example MANIFEST.MF in a PAR file:
- <programlisting><emphasis role="bold">Application-SymbolicName</emphasis>: com.example.shop
-<emphasis role="bold">Application-Version</emphasis>: 1.0
-<emphasis role="bold">Application-Name</emphasis>: Online Shop
-<emphasis role="bold">Application-Description</emphasis>: Example.com’s Online Shopping Application</programlisting>
- </para>
- </section>
- <section id="developing-applications-web-application-bundles">
- <title>Web Application Bundles</title>
- <para>
- @tomcat.product.name@ supports Web Application Bundles that are compliant with the OSGi Web Applications specification.
- The defining property of a Bundle that makes it a Web Application Bundle is a manifest header, <literal>Web-ContextPath</literal>.
- This defines the context path the web application will be registered under.
- </para>
- <para>
- See <link linkend="using-spring">Using Spring and Spring DM</link> for information on using Spring or Spring DM in a Web Application Bundle.
- </para>
- </section>
-
- </section><!-- end packaging -->
-
- <section id="developing-applications-plans">
- <title>Creating Plans</title>
- <para>
- Plans are similar to PARs in that they encapsulate the artifacts of an application as a single unit.
- However plans are XML files that refer to their artifacts, whereas PARs are JAR files that physically contain their artifacts.
- Plans, known as <emphasis>parent</emphasis> plans may refer to other plans, known as <emphasis>child</emphasis> plans.
- </para>
- <para>
- Plans share several benefits with PARs:
- <itemizedlist>
- <listitem>A plan has a (symbolic) name and a version.</listitem>
- <listitem>A plan may be scoped, although this is optional.
- See <link linkend="developing-applications-plans-scoping">Plans and Scoping</link> for more on scoping.
- </listitem>
- <listitem>A plan is visible to management interfaces.</listitem>
- <listitem>A plan can be undeployed and redeployed as a unit.</listitem>
- <listitem>A plan may be atomic, although this is optional.</listitem>
- </itemizedlist>
- </para>
- <para>
- Plans have the following additional benefits compared to PARs:
- <itemizedlist>
- <listitem>
- @project.name@ deploys the artifacts in the plan in the order in which they are listed in the XML file, which gives you
- complete control over deployment order.
- With a PAR, the order of deployment of the included artifacts is not guaranteed.
- </listitem>
- <listitem>Since plans refer to their artifacts, it is easier to share content between plans as well as update individual
- parts of a plan without having to physically repackage (re-JAR) it.
- </listitem>
- <listitem>
- Plans may contain child plans, but PARs cannot contain other PARs.
- </listitem>
- <listitem>
- You can make certain plans deploy faster by disabling the provisioning of bundles to satisfy missing dependencies,
- but you cannot disable provisioning for PARs.
- </listitem>
- <listitem>
- You can specify whether a plan is scoped or unscoped and atomic or non-atomic; PARs are always scoped and atomic.
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- The artifacts of a plan are usually stored in @project.name@'s repository. This means, for example, that if you drop one of the plan’s artifacts in the <code>pickup</code> directory rather than adding it to the repository, the plan will fail to deploy because it will not find the artifact.
- </para>
- <para>
- The artifacts of a plan may also be stored outside @project.name@'s repository, somewhere else on the file system and referenced from the plan using URIs.
- Such artifacts must be available on the file system when the plan is deployed and when @project.name@ restarts while the plan is deployed.
- If you delete any of these artifacts, deployment of the plan may fail, either when it is initially deployed or when @project.name@ restarts.
- </para>
-
- <section id="developing-applications-plans-create">
- <title>Creating the Plan XML File</title>
- <para>
- Plans are XML files that have a <code>.plan</code> file extension, such as <code>multi-artifact.plan</code>.
- The structure of the XML file is simple:
- the root element is <code><plan></code> with attributes specifying the name of the plan, the version, atomicity, and scoping.
- Then, for each artifact that makes up your application,
- you add a <code><artifact></code> element, using its attributes to specify the type of artifact and its name and version.
- The following is a simple example of a plan’s XML file:
- </para>
- <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true"
- xmlns="http://www.eclipse.org/virgo/schema/plan"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.eclipse.org/virgo/schema/plan
- http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
-
- <artifact type="configuration" name="app-properties" version="1.0.0"/>
- <artifact type="bundle" name="com.springsource.exciting.app" version="[2.0.0, 3.1.0)"/>
-
-</plan>]]></programlisting>
- <para>
- In the preceding example, the name of the plan is <code>multi-artifact.plan</code> and its version is <code>1.0.0</code>.
- The plan is both scoped and atomic. The plan contains two artifacts: one is a bundle called <code>com.springsource.exciting.app</code> and the other is a configuration file called <code>app-properties</code>.
- </para>
- <para>
- The following table describes the attributes of the <code><plan></code> element.
- </para>
-
- <table id="developing-applications-plans-create-plan-attributes" colsep="1" frame="all" rowsep="1">
- <title>Attributes of the <plan> Element</title>
- <tgroup cols="3">
- <colspec colwidth="1*" />
- <colspec colwidth="3*" />
- <colspec colwidth="1*" />
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- <entry>Required?</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>name</literal></entry>
- <entry>Specifies the name of this plan. @project.name@ uses the name as one component of the unique identifier of this plan. </entry>
- <entry>Yes.</entry>
- </row>
- <row>
- <entry><literal>version</literal></entry>
- <entry>Specifies the version of this plan. You must use OSGi version specification syntax, such as <code>2.1.0</code>. @project.name@ uses the version as one component of the unique identifier of this plan. </entry>
- <entry>Yes.</entry>
- </row>
- <row>
- <entry><literal>scoped</literal></entry>
- <entry>Specifies whether @project.name@ should install the artifacts into plan-specific scope so that only the application described by this plan has access to the artifacts. If you disable scoping, then @project.name@ installs the artifacts into the global scope, which means they are then available for access by all other deployed artifacts. Set the attribute to <code>true</code> to enable scoping or <code>false</code> to disable it.</entry>
- <entry>Yes.</entry>
- </row>
- <row>
- <entry><literal>atomic</literal></entry>
- <entry>Specifies whether you want to tie together the lifecycle of the artifacts in this plan.
- Making a plan atomic means that if you start, stop, or uninstall a single artifact in the plan, @project.name@ escalates the operation to
- the whole plan. Also @project.name@ prevents artifacts of an atomic plan from being in inconsistent states.
- For example, if one artifact should fail to start, then @project.name@ stops all artifacts in the plan.
- Set this attribute to <code>true</code> to enable atomicity or <code>false</code> to disable it. </entry>
- <entry>Yes.</entry>
- </row>
- <row>
- <entry><literal>provisioning</literal></entry>
- <entry>
- <para>
- Specifies whether @project.name@ installs bundles from the repository to attempt to satisfy any missing dependencies in the plan.
- Missing dependencies prevent one or more bundles in the plan from resolving.
- For example, a bundle which imports a package cannot resolve if the package is missing, that is, not exported by another bundle.
- </para>
- <para>
- A value of <code>auto</code> instructs @project.name@ to install bundles from the repository
- to attempt to satisfy any missing dependencies in the plan. This is known as <emphasis>auto-provisioning</emphasis>.
- </para>
- <para>
- A value of <code>disabled</code> prevents @project.name@ from installing bundles from the repository to attempt to
- satisfy any missing dependencies in the plan.
- This value can make the plan deploy faster, although if there are missing dependencies, deployment will fail.
- </para>
- <para>
- A value of <code>inherit</code>, which is the default if no value is specified, inherits the parent plan's provisioning behaviour.
- If the plan does not have a parent, it inherits @project.name@'s auto-provisioning behaviour.
- </para>
- </entry>
- <entry>No. If not specified, defaults to <code>inherit</code>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- The following table describes the attributes of the <code><artifact></code> element. Note that you must either specify <literal>type</literal>, <literal>name</literal>, and (optionally) <literal>version</literal>,
- in which case @project.name@'s repository is searched for the artifact, or <literal>uri</literal> in which case the artifact is obtained directly from the file system.
- If you specify <literal>uri</literal>, you must not specify <literal>type</literal>, <literal>name</literal>, or <literal>version</literal>.
- </para>
- <table id="developing-applications-plans-create-artifact-attributes" colsep="1" frame="all" rowsep="1">
- <title>Attributes of the <artifact> Element</title>
- <tgroup cols="3">
- <colspec colwidth="1*" />
- <colspec colwidth="3*" />
- <colspec colwidth="1*" />
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- <entry>Required?</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>type</literal></entry>
- <entry>Specifies the type of the artifact. Valid values are:
- <itemizedlist>
- <listitem><code>bundle</code>: Specifies an OSGi bundle. Use this artifact type for WAR files and Web application bundles. </listitem>
- <listitem><code>configuration</code>: Specifies that the artifact is a configuration file. Configuration files contain name/value pairs that set initial values for configuration properties of a bundle. </listitem>
- <listitem><code>plan</code>: Specifies that the artifact is a plan. </listitem>
- <listitem><code>par</code>: Specifies that the artifact is a PAR. </listitem>
- </itemizedlist>
- </entry>
-
- <entry>Yes, unless <literal>uri</literal> is specified in which case <literal>type</literal> must not be specified and is automatically determined from the artifact.</entry>
- </row>
- <row>
- <entry><literal>name</literal></entry>
- <entry>Specifies the name of the artifact.
- <para>See <link linkend="artifact-names">Artifact Names</link> for guidelines for determining the name of an artifact.</para>
- </entry>
- <entry>Yes, unless <literal>uri</literal> is specified in which case <literal>name</literal> must not be specified and is automatically determined from the artifact.</entry>
- </row>
- <row>
- <entry><literal>version</literal></entry>
- <entry>Specifies the range of versions of this artifact that @project.name@ should look up in its repositories and then install and deploy.
- You must use OSGi version specification syntax, such as <code>[1.0.0, 2.0.0)</code>.
- Note that a single version number represents the range from that version number upwards.
- For example, <code>1.3</code> represents the range of versions greater than or equal to <code>1.3</code>.
- </entry>
- <entry>No. If <literal>uri</literal> is specified, <literal>version</literal> must not be specified.
- If neither <literal>uri</literal> nor <literal>version</literal> are specified, <literal>version</literal> defaults to <code>0</code>, which in OSGi means 0 to infinity, or any version.</entry>
- </row>
- <row>
- <entry><literal>uri</literal></entry>
- <entry>
- Specifies an optional, absolute URI string beginning with <code>file:</code> that refers to the artifact on the file system.
- Such an artifact must be available on the file system when the plan is deployed and when @project.name@ restarts while the plan is deployed.
- If you delete such an artifact, deployment of the plan may fail, either when it is initially deployed or when @project.name@ restarts.
- This attribute is normally omitted so that the artifact is searched for in @project.name@'s repository.
- </entry>
- <entry>No. If not specified, @project.name@ searches for the artifact in its repository.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="names-of-artifacts">
- <title>Artifact Names</title>
-
- <para>When you create a plan, you use the <code>name</code> attribute of the <code><artifact></code> element to specify the name of all the plan’s dependencies. This section describes how to determine the name of an artifact, which is not always obvious.</para>
- <para>Use the following guidelines to determine the name of an artifact:</para>
- <itemizedlist>
- <listitem><para><emphasis role="bold">Bundle</emphasis>: In this context, a <emphasis>bundle</emphasis> refers to a standard OSGi bundle as well as a Web Application Bundle and a WAR file. The name of a bundle is the value of the <code>Bundle-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.jar</code>.
- If a WAR file has <code>Bundle-SymbolicName</code> header then it will be treated as a Web Application Bundle. The following <code>MANIFEST.MF</code> snippet shows a bundle with name <code>com.springsource.exciting.app</code>:</para>
- <screen>Bundle-SymbolicName: org.eclispe.virgo.exciting.app</screen>
- <para>If the bundle does not contain a <code>META-INF/MANIFEST.MF</code> file or the <literal>MANIFEST.MF</literal> doesn't contain a <code>Bundle-SymbolicName</code> header, then the name of the bundle is its filename minus the <code>.jar</code> or <code>.war</code> extension.</para>
- </listitem>
- <listitem><para><emphasis role="bold">Configuration File</emphasis>: The name of a configuration or PID (Persistent Identity) is its filename minus the <code>.properties</code> extension. The PID can also be specified within the properties file with the
- <emphasis>service.pid</emphasis> property.
- </para>
- </listitem>
- <listitem><para><emphasis role="bold">Plan</emphasis>: The name of a plan is the value of the required <code>name</code> attribute of the <code><plan></code> element in the plan’s XML file. In the following XML snippet, the plan name is <code>multi-artifact.plan</code>:</para>
- <screen><?xml version="1.0" encoding="UTF-8"?>
-<plan name="<emphasis role="bold">multi-artifact.plan</emphasis>" version="1.0.0" scoped="true" atomic="true"
- xmlns="http://www.eclipse.org/virgo/schema/plan"
-...</screen>
- </listitem>
- <listitem><para><emphasis role="bold">PAR</emphasis>: The name of a PAR is the value of the <code>Application-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.par</code> file. The following <code>MANIFEST.MF</code> snippet shows a PAR with name <code>com.springsource.my.par</code>:</para>
- <screen>Application-SymbolicName: org.eclipse.virgo.my.par</screen>
- <para>If the PAR does not contain a <code>META-INF/MANIFEST.MF</code> file, then the name of the PAR is its filename minus the <code>.par</code> extension.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="passing-properties">
- <title>Supplying Properties to Artifacts</title>
- <para>
- It is possible to pass properties to an artifact specified in a plan. An example of this can be seen in the Admin Console plan where the context path to be used in the Admin console is passed from the plan.
- </para>
- <programlisting>
- <artifact type="bundle" name="org.eclipse.virgo.apps.admin.web" version="[3.0, 4.0)">
- <property name="header:Web-ContextPath" value="/admin" />
- </artifact>
- </programlisting>
- <para>
- The only supported property is <literal>header</literal> which will overwrite the given manifest header with the supplied value. This should be used with care!
- </para>
- </section>
-
- <section id="developing-applications-plans-use">
- <title>Using the Plan</title>
- <para>
- Because a plan is a list of artifacts, rather than a physical file that contains the artifacts, there are a few additional steps you must perform before you deploy it to @project.name@.
- </para>
- <orderedlist>
- <listitem><para>Copy the artifacts that make up the plan to the <code>usr</code> repository, which by default is the <code>$SERVER_HOME/repository/usr</code> directory, where <code>$SERVER_HOME</code> refers to the top-level installation directory of @project.name@. Note that you might have configured the server differently; in which case, copy the artifacts to your custom repository directory.</para></listitem>
- <listitem><para>Restart @project.name@ if the repository used is not a <emphasis>watched</emphasis> repository.</para></listitem>
- <listitem><para>After the server has started, either use the Admin Console to deploy the plan, or manually deploy it by copying the plan’s XML file into the <code>$SERVER_HOME/pickup</code> directory. </para>
- <para>This results in @project.name@ deploying the plan.</para></listitem>
- <listitem><para>To undeploy the plan, use the Admin Console, or simply delete it from the <code>$SERVER_HOME/pickup</code> directory.</para></listitem>
- </orderedlist>
- </section>
-
- <section id="developing-applications-plans-scoping">
- <title>Plans and Scoping</title>
- <para>As described in previous sections, you can specify that a plan be <emphasis>scoped</emphasis>. This means that @project.name@ installs the artifacts that make up the plan into a plan-specific scope so that only the application described by the plan has access to the artifacts. If you disable scoping, then @project.name@ installs the artifacts into the global scope, which means they are available for access by all other deployed artifacts. This section describes scoping in a bit more detail. It also describes how you can change the default behavior of scoping, with respect to services, so that a service that is in a scope can be made globally available. </para>
-
- <para>If a bundle in a given scope imports a package and a bundle in the same scope exports the package, then the import may only be satisfied by the bundle in the scope, and not by any bundles outside the scope, including the global scope. Similarly, package exports from bundles in a scope are not visible to bundles in the global scope.</para>
-
- <para>If a bundle in a scope uses Spring DM (or the blueprint service) to obtain a service reference and a bundle in the same scope uses Spring DM (or the blueprint service) to publish a matching service, then the service reference may only bind to the service published in the scope (and not to any services outside the scope). Services published by bundles in a scope are not visible to bundles in the global scope. </para>
-
- <para>However, sometimes it is useful to make a service in a scope globally available to artifacts outside the scope. To do this, publish the service with the <literal>org.eclipse.virgo.service.scope</literal> service property set to <literal>global</literal>. Use the <literal><service-properties></literal> child element of <literal><service></literal>, as shown in the following example: </para>
-
- <programlisting><service id="publishIntoGlobal" interface="java.lang.CharSequence">
- <emphasis role="bold"><service-properties>
- <beans:entry key="org.eclipse.virgo.service.scope" value="global" />
- </service-properties></emphasis>
- <beans:bean class="java.lang.String">
- <beans:constructor-arg value="foo"/>
- </beans:bean>
-</service></programlisting>
-
- <para>
- A scope forms a boundary for automatic propagation of load time weaving and bundle refresh.
- Additionally, a synthetic context bundle is generated for each scope. This bundle imports all the packages exported by other bundles in the scope.
- The class loader of the synthetic context bundle is used for thread context class loading. So,
- for example, hibernate will be able to load classes of any of the exported
- packages of the bundles in a scope using the thread context class loader.
- </para>
- <para>
- To ensure predictable class loading behaviour and avoid other issues associated with <emphasis>split packages</emphasis> (packages whose classes
- are split across more than one bundle), the synthetic context bundle has a restriction:
- <emphasis role="bold">no package may be exported by more than one
- bundle in the scope</emphasis>.
- If this restriction is broken, the scoped application will fail to deploy.
- This restriction can cause problems for <link linkend="scoping-and-substitutable-exports">substitutable exports</link>.
- </para>
- <section id="developing-applications-plans-scoping-webapps">
- <title>Web Applications and Scoping</title>
- <para>
- A Web Application Bundle (WAB) or WAR has its bundle class loader set as the TCCL, even when the WAB or WAR belongs to
- a PAR or scoped plan.
- To enable the TCCL to load classes of other bundles in the same scope as a WAB or WAR, use a WAB which imports the necessary packages.
- </para>
- <para>
- Also a WAB or WAR has its own per-application trace, independent of the per-application trace of any PAR or scoped plan to which the
- WAB or WAR belongs.
- </para>
- </section>
- </section>
-
- </section><!-- end plans -->
-
-<!-- ======================================================================= -->
-<!-- ======================================================================= -->
-
- <section id="developing-applications-configuration-artifacts">
- <title>Creating and Using Configuration Artifacts</title>
- <para>
- Applications typically include some sort of configuration data
- that might change depending on the environment in which the
- application is deployed. For example, if an application connects to a
- database server using JDBC, the configuration data would include the
- JDBC URL of the database server, the JDBC drvier, and the username and
- password that the application uses to connect to the database server.
- This information often changes as the application is deployed to
- different computers or the application moves from the testing phase to
- the production phase.
- </para>
-
- <para>
- @project.name@ provides a feature called
- <emphasis>configuration artifacts</emphasis>
- that makes it very easy for you to manage this configuration data. A
- configuration artifact is simply a properties file that is made
- available at runtime using the OSGi
- <literal>ConfigurationAdmin</literal>
- service. When you create this properties file, you set the values of
- the properties for the specific environment in which you are going to
- deploy your application, and then update the metadata of your Spring
- application to use the properties file. You then deploy the
- application and properties file together, typically as a
- <link linkend="developing-applications-plans">plan</link>
- . @project.name@ automatically creates a configuration artifact from
- the properties file, and you can manage the lifecycle of this
- configuration artifact in the same way you manage the lifecycle of
- PARs, bundles, and plans, using the Admin
- Console. Additionally, @project.name@ subscribes your
- application for notification of any refresh of the configuration
- artifact and the application can then adapt accordingly, which means
- you can easily
- <emphasis>change</emphasis>
- the configuration of your application without redeploying it.
- </para>
- <para>In sum, configuration artifacts, especially when combined with
- plans, provide an excellent mechanism for managing external
- configuration data for your applications.</para>
-
- <para>The following sections describe the format of the configuration
- artifact, how to update the Spring application context file of your
- application so that it knows about the configuration artifact, and
- finally how to include it in a plan alongside your application. </para>
-
- <para>
- As an example to illustrate the configuration artifact feature, assume
- that you have a Spring bean called
- <literal>PropertiesController</literal>
- whose constructor requires that four property values be passed to it,
- as shown in the following snippet of Java code:
- </para>
- <programlisting>@Controller
-public class PropertiesController {
-
- private final String driverClassName;
- private final String url;
- private final String username;
- private final String password;
-
- public PropertiesController(String driverClassName, String url, String username, String password) {
- this.driverClassName = driverClassName;
- this.url = url;
- this.username = username;
- this.password = password;
-}</programlisting>
-
- <para>In the preceding example, the <literal>PropertiesController</literal> constructor requires four property values: <literal>driverClassName</literal>, <literal>url</literal>, <literal>username</literal>, and <literal>password</literal>. Note that the example shows just one way that a class might require property values; your application may code it another way.</para>
-
- <para>Additionally, assume that the following snippet of the associated Spring application context XML file shows how the <literal>PropertiesController</literal> bean is configured:</para>
-
- <programlisting><bean class="com.springsource.configuration.properties.PropertiesController">
- <constructor-arg value="${driverClassName}"/>
- <constructor-arg value="${url}"/>
- <constructor-arg value="${username}"/>
- <constructor-arg value="${password}"/>
-</bean></programlisting>
-
- <para>The rest of this section describes how the bean can get these property values using a configuration artifact.</para>
-
- <section id="developing-applications-configuration-artifacts-propfile">
- <title>Creating the Properties File</title>
-
- <para>To create a properties file that in turn will become a configuration artifact when deployed to @project.name@ from which a Spring bean, such as the <literal>PropertiesController</literal> bean, will get the actual property values, follow these guidelines:</para>
- <itemizedlist>
- <listitem><para>Create a text file in which each property is listed as a name/value pair, one pair per line. Precede comments with a <literal>#</literal>. For example:</para>
- <screen># Properties for the com.springsource.configuration.properties sample
-
-driverClassName = org.w3.Driver
-url = http://www.springsource.com
-username = joe
-password = secret</screen>
- <para>The example shows four properties whose name correspond to the constructor arguments of the <literal>PropertiesController</literal> Spring bean.</para></listitem>
- <listitem><para>Name the file anything you want, as long as it has a <literal>.properties</literal> extension, such as <literal>app-properties.properties</literal>.</para></listitem>
- </itemizedlist>
- </section>
-
- <section id="developing-applications-configuration-artifacts-app">
- <title>Updating Your Application</title>
- <para>To update your application so that it "knows" about the configuration artifact, you update the application's Spring application context XML file, typically located in the <literal>WEB-INF</literal> or <literal>META-INF/spring</literal> directories (read <link linkend="using-spring">Using Spring and Spring DM</link>
- to understand which directory to use).</para>
-
- <para>You use the <literal><context:property-placeholder></literal> element to specify that you want to use the @project.name@ mechanism for substituting values into bean properties. The <literal>properties-ref</literal> attribute of this element points to a <literal><osgi-compendium:cm-properties></literal> element which you use to specify the configuration artifact that contains the property values. You set the value of the <literal>persistent-id</literal> attribute of this element equal to the name of the configuration artifact, which is the name of the properties file <emphasis>minus</emphasis> the <literal>.properties</literal> extension. </para>
- <para>The following sample Spring application context XMl file shows everything wired together; only relevant parts of the file are shown:</para>
-
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:context="http://www.springframework.org/schema/context"
- xmlns:osgi-compendium="http://www.springframework.org/schema/osgi-compendium"
- xsi:schemaLocation="http://www.springframework.org/schema/osgi
- http://www.springframework.org/schema/osgi/spring-osgi-1.2.xsd
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
- http://www.springframework.org/schema/context
- http://www.springframework.org/schema/context/spring-context-2.5.xsd
- http://www.springframework.org/schema/osgi-compendium
- http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium-1.2.xsd">
-
-...
-
- <bean class="com.springsource.configuration.properties.PropertiesController">
- <constructor-arg value="${driverClassName}"/>
- <constructor-arg value="${url}"/>
- <constructor-arg value="${username}"/>
- <constructor-arg value="${password}"/>
- </bean>
-
- <context:property-placeholder properties-ref="configAdminProperties"/>
-
- <osgi-compendium:cm-properties id="configAdminProperties" persistent-id="app-properties"/>
-
-...
-
-</beans> </programlisting>
-
- </section>
-
- <para>The preceding example shows how the id <literal>configAdminProperites</literal> wires the <literal><context:property-placeholder></literal> and <literal><osgi-compendium:cm-properties></literal> elements together. Based on the value of the <literal>persistent-id</literal> attribute, you must also deploy a properties file called <literal>app-properties.properties</literal> which @project.name@ installs as a configuration artifact.</para>
-
- <section id="developing-applications-configuration-artifacts-plan">
- <title>Adding the Configuration Artifact to a Plan</title>
- <para>Although you can always deploy your application and associated configuration artifact using the <literal>pickup</literal> directory, we recommends that you group the two together in a plan, add the two artifacts to the repository, and then deploy the plan using the <literal>pickup</literal> directory. The following sample plan includes the two artifacts:</para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-<plan name="multi-artifact.plan" version="1.0.0"
- scoped="false" atomic="false"
- xmlns="http://www.eclipse.org/virgo/schema/plan"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.eclipse.org/virgo/schema/plan
- http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
-
- <artifact type="configuration" name="app-properties" version="0"/>
- <artifact type="bundle" name="org.eclipse.virgo.configuration.properties" version="1.0.0"/>
-</plan></programlisting>
-
- <para>For additional information about plans, see <link linkend="developing-applications-plans">Creating Plans</link>.</para>
-
- </section>
-
- </section> <!-- end of configuration artifacts -->
-
-<!-- ======================================================================= -->
-<!-- ======================================================================= -->
-
- <section id="using-spring">
- <title>Using Spring, Spring DM, and Blueprint</title>
- <para>
- @project.name@ supports the use of Spring framework and Spring DM (as supported by Gemini Blueprint) by application bundles.
- </para>
- <para>
- Spring (and Spring DM) application context XML files should generally be placed in a bundle's <literal>META-INF/spring</literal> directory, but
- for a web application, these files must be placed in the <literal>WEB-INF</literal> directory.
- </para>
- <tip>
- <title>
- A common mistake
- </title>
- <para>
- Placing a web application's Spring application context XML files in the <literal>META-INF/spring</literal> directory produces
- unpredictable results since Spring DM will attempt to build an application context independently of, and asynchronously from,
- the web application.
- </para>
- </tip>
- <para>
- To use Spring DM from a web application, the <literal>contextClass</literal> servlet parameter and the servlet context listener
- should be configured (in <literal>WEB-INF/web.xml</literal>) like this:
-<programlisting language="xml"><![CDATA[
- <context-param>
- <param-name>contextClass</param-name>
- <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
- </context-param>
-
- <listener>
- <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
- </listener>
-]]></programlisting>
- </para>
- <para>
- @project.name@ has Gemini Blueprint built-in and thereby supports the OSGi Blueprint standard in addition to Spring DM.
- </para>
- <para>
- For detailed information on Spring Framework, Spring DM, and Blueprint, please see <xref linkend="prerequisites-references"/>.
- </para>
- </section> <!-- end of using Spring and Spring DM -->
-
-<!-- ======================================================================= -->
-<!-- ======================================================================= -->
-
- <section id="developing-applications-programmatic-access">
- <title>Programmatic Access to the Servlet Context</title>
- <para>
- This section describes how to programmatically access the servlet context to obtain the WebApplicationContext or the BundleContext.
- </para>
- <section id="developing-applications-programmatic-access-web">
- <title>Programmatic Access to Web Features</title>
-
- <section id="developing-applications-programmatic-access-web-application-context">
- <title>Programmatic Access to the WebApplicationContext</title>
- <para>
- The @tomcat.product.name@ automatically creates a <literal>WebApplicationContext</literal>
- for Web Application Bundles and WAR files. When used in conjunction with an
- an auto-configured Spring MVC <literal>DispatcherServlet</literal>,
- there is generally no need to access the <literal>WebApplicationContext</literal>
- programmatically, since all components of the web application are configured
- within the scope of the <literal>WebApplicationContext</literal>
- itself. However, if you wish to access the <literal>WebApplicationContext</literal>
- you can do so via the web application’s <literal>ServletContext</literal>.
- @project.name@ stores the bundle’s
- <literal>WebApplicationContext</literal> in the ServletContext under
- the attribute name "<literal>BSN-ApplicationContext</literal>", where
- <literal>BSN</literal> is the <literal>Bundle-SymbolicName</literal>
- of your WAR or Web Application Bundle.
- </para>
- <para>
- Alternatively, since @project.name@ also stores the
- <literal>WebApplicationContext</literal> under the attribute name
- with the value of the <literal>WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE</literal>
- constant, you may choose to use Spring MVC’s WebApplicationContextUtils’
- <literal>getWebApplicationContext(servletContext)</literal>
- or
- <literal>getRequiredWebApplicationContext(servletContext)</literal>
- methods to access the <literal>WebApplicationContext</literal> without providing
- an explicit attribute name.
- </para>
- </section>
-
- <section id="developing-applications-programmatic-access-web-bundle-context">
- <title>Programmatic Access to the BundleContext</title>
- <para>
- As required by the OSGi Web Applications specification, you can access the
- <literal>BundleContext</literal> of your WAR or Web Application Bundle via the web application’s
- <literal>ServletContext</literal>. The bundle context is stored in the
- <literal>ServletContext</literal> under the attribute name <literal>osgi-bundlecontext</literal>.
- </para>
- </section>
-
- </section>
- </section>
-
-
- <section id="developing-applications-automatic-imports-web">
- <title>Web Application Manifest Processing</title>
- <para>
- @tomcat.product.name@ generates automatic package imports (i.e., via the
- <literal>Import-Package</literal> manifest header) for certain web applications.
- This section lists which packages are automatically generated.
- </para>
- <para>
- @tomcat.product.name.short@ supports Web Application Bundles (WABs) as defined by the OSGi Web Applications Specification and WAR files.
- A WAR will typically not contain any OSGi defined manifest headers.
- A WAB is distinguished from a WAR by the presence of one or more of the following OSGi defined headers:
- <itemizedlist>
- <listitem>
- <literal>Bundle-SymbolicName</literal>
- </listitem>
- <listitem>
- <literal>Bundle-Version</literal>
- </listitem>
- <listitem>
- <literal>Bundle-ManifestVersion</literal>
- </listitem>
- <listitem>
- <literal>Import-Package</literal>
- </listitem>
- <listitem>
- <literal>Web-ContextPath</literal>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- As required by the OSGi Web Applications specification, the following defaults are applied to a WAR:
- <itemizedlist>
- <listitem>
- <literal>Bundle-ManifestVersion</literal> is set to <literal>2</literal>
- </listitem>
- <listitem>
- <literal>Bundle-SymbolicName</literal> is generated from the path from which the bundle was installed
- </listitem>
- <listitem>
- <literal>Bundle-ClassPath</literal> is set to <literal>WEB-INF/classes</literal> followed by the JARs in
- <literal>WEB-INF/lib</literal> in an unspecified order, followed by any transitive dependencies declared
- by the JARs in <literal>WEB-INF/lib</literal>
- </listitem>
- <listitem>
- <literal>Import-Package</literal> is extended in an implementation defined way, as described below
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The following packages are automatically imported into WARs:
- <itemizedlist>
- <listitem>
- <literal>javax.servlet;version="2.5"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.http;version="2.5"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.jsp;version="2.1"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.jsp.el;version="2.1"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.jsp.tagext;version="2.1"</literal>
- </listitem>
- <listitem>
- <literal>javax.el;version="1.0"</literal>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- In addition to the above-described imports, @tomcat.product.name.short@ will also
- generate automatic imports for all of the packages that are exported by the system
- bundle, unless an import for the package already exists in the WAR’s manifest,
- or the WAR contains the package, i.e. within <literal>WEB-INF/classes</literal>,
- or in a jar file in <literal>WEB-INF/lib</literal>. When an import is generated, it
- is versioned such that it exactly matches the version or versions of the package that
- are exported from the system bundle. For example, a package that’s exported only at
- version <literal>1.0.0</literal> will generate an import with a version of
- <literal>[1.0.0,1.0.0]</literal>, and a package that’s exported at version
- <literal>1.0.0</literal> and version <literal>2.0.0</literal> will generate an import
- with a version of <literal>[1.0.0,2.0.0]</literal>.
- </para>
-
- <para>
- Web Application Bundles are not subject to the above manifest processing.
- This is a change of behaviour compared to Virgo Web Server 2.1.x.
- See (see <link linkend="known-issues-web-bundle-default-headers">Default Web
- Application Bundle Headers</link>) if you need the old behaviour until you
- have changed your WABs to match the new behaviour.
- </para>
-
- <para>
- @tomcat.product.name.short@ supports ROOT.war as a default web application. The <literal>Web-ContextPath</literal>
- of the deployed ROOT.war is set to the default web context path - <literal>/</literal>.
- </para>
-
- <tip>
- <title>System Bundle Package Exports</title>
- <para>
- For further details on which packages are exported by the
- OSGi system bundle, consult the <filename>java6-server.profile</filename>
- file located in the <literal>SERVER_HOME/lib</literal> directory.
- </para>
- </tip>
-
- </section>
-
- <section id="developing-applications-dependencies">
- <title>Working with Dependencies</title>
- <para>Complex enterprise frameworks such a Spring and Hibernate are typically divided into many, many different
- packages. Traditionally, if an OSGi bundle wished to make extensive use of such a framework its manifest would
- have to import a huge number of different packages. This can be an error-prone and tedious process. Furthermore,
- application developers are used to thinking in terms of their application using a framework, such as Spring, as a
- whole, rather than a long list of all the different packages that comprise the framework.
- </para>
- <para>The following figure provides a simple illustration of the complexity of only using <code>Import-Package</code>:
- </para>
- <para>
- <imagedata fileref="images/import-package.png"/>
- </para>
- <para>@project.name@ reduces the need for long lists of imported packages by introducing two new manifest
- headers; <code>Import-Bundle</code> and <code>Import-Library</code>. The following figure provides an
- illustration of the simplification that these new headers offer:
- </para>
- <para>
- <imagedata fileref="images/import-bundle_import-library.png"/>
- </para>
- <para>
- As you can see, use of <code>Import-Bundle</code> and <code>Import-Library</code> can lead to a dramatic reduction
- in the number of imports that you need to include in an application bundle’s manifest. Furthermore, <code>Import-Bundle</code>
- and <code>Import-Library</code> are simply aliases for <code>Import-Package</code>; at deployment time <code>Import-Bundle</code>
- and <code>Import-Library</code> header entries are automatically expanded into numerous <code>Import-Package</code> entries. This
- means that you retain the exact same semantics of using <code>Import-Package</code>, without having to go through the labourious
- process of doing so.
- </para>
- <section id="developing-applications-importing-libraries">
- <title>Importing Libraries</title>
- <para>A bundle in an application can declare a dependency on a library by using the
- @umbrella.product.name@ specific <code>Import-Library</code> header. This header specifies a
- comma-separated list of library symbolic names and version ranges that determine which libraries
- are imported. By default a dependency on a library is mandatory but this can be
- controlled through use of the resolution directive in exactly the same way as
- it can with <code>Import-Package</code>.
- </para>
- <programlisting>
-<emphasis role="bold">Import-Library</emphasis>: org.springframework.spring;version="[2.5.4, 3.0)",
- org.aspectj;version="[1.6.0,1.6.0]";resolution:="optional"
- </programlisting>
- <para>
- This example <code>Import-Library</code> header declares a mandatory dependency on the Spring
- library at a version from 2.5.4 inclusive to 3.0 exclusive. It also declares an
- optional dependency on the AspectJ library at exactly 1.6.0.
- </para>
- </section>
- <section id="developing-applications-importing-bundles">
- <title>Importing Bundles</title>
- <para>A bundle in an application can declare a dependency on a bundle by using the
- @umbrella.product.name@ specific <code>Import-Bundle</code> header. The header specifies a comma-separated
- list of bundle symbolic names, version ranges, and scope declarmations that determine which bundles are imported and the scope of their dependency. By default a dependency
- on a bundle is mandatory but this can be controlled through use of the resolution directive in exactly
- the same way as it can with <code>Import-Package</code>.
- </para>
- <programlisting>
-<emphasis role="bold">Import-Bundle</emphasis>: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi, 1.2.2.osgi]"
- </programlisting>
- <para>
- This example <code>Import-Bundle</code> header declares a mandatory dependency on the Apache Commons
- DBCP bundle at exactly 1.2.2.osgi.
- </para>
- <section id="developing-applications-importing-bundles-disadvantages">
- <title>Disadvantages</title>
- <para>
- A disadvantage of using <code>Import-Bundle</code> or especially <code>Import-Library</code>, is that the application
- bundle has a greater apparent fan-out than it strictly needs. An Alternative is to use a tool such as bnd or Bundlor
- to generate the package imports of the bundle.
- </para>
- </section>
- </section>
-
- <section id="developing-applications-scoping-libraries-bundles">
- <title>Scoping Bundles in an Application</title>
- <para>
- When working with a scoped application, such as a PAR file or a plan, you might run into a situation where one of the bundles in the application (call it <code>bundleA</code>) depends on another bundle (<code>bundleB</code>) that performs a runtime task (such as class generation) that a third bundle (<code>bundleC</code>) might need to know about, although <code>bundleC</code> does not explicitly depend on <code>bundleB</code>.
- </para>
- <para>
- For example, Hibernate uses CGLIB (code generation library) at runtime to generate proxies for persistent classes. Assume that a domain bundle in your application uses Hibernate for its persistent objects, and thus its <code>Import-Bundle</code> manifest header includes the Hibernate bundle. Further assume that a separate Web bundle uses reflection in its data-binding code, and thus needs to reflect on the persistent classes generated by Hibernate at runtime. The Web bundle now has an indirect dependency on the Hibernate bundle because of these dynamically generated classes, although the Web bundle does not typically care about the details of how these classes are persisted. One way to solve this dependency problem is to explicitly add the Hibernate bundle to the <code>Import-Bundle</code> header of the Web bundle; however, this type of explicit-specified dependency breaks the modularity of the application and is not a programming best practice.
- </para>
- <para>
- A better way to solve this problem is to specify that @project.name@ itself dynamically import
- the bundle (Hibernate in the example above) to all bundles in the application at runtime.
- You do this by adding the <code>import-scope:=application</code> directive to the <code>Import-Bundle</code> header
- of the bundle that has the direct dependency (the domain bundle in our example). At runtime, although the Web bundle
- does not explicitly import the Hibernate bundle, @project.name@ implicitly imports it and thus its classes are available
- to the Web bundle. This mechanism allows you to declare the dependencies you need to make your application run,
- without having to make changes to your application that might limit its flexibility.
- </para>
- <para>
- The following example shows how to use the <code>import-scope</code> directive with the <code>Import-Bundle</code> header:
- </para>
- <programlisting>
-Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";<emphasis role="bold">import-scope:=application</emphasis></programlisting>
- <para>
- You can also set the <code>import-scope</code> directive to the (default) value <code>bundle</code>; in this case, the scope of the bundle is just the bundle itself and thus @project.name@ does not perform any implicit importing into other bundles of the application.
- </para>
- <para>
- Note that use of the <code>import-scope:=application</code> directive of the <code>Import-Bundle</code> header only makes sense when the bundle is part of a scoped application (PAR or plan); if the bundle is not part of a scoped application, then this directive has no effect.
- </para>
- <para>
- Finally, because <code>import-scope:=application</code> implicitly adds a bundle import to each bundle of the PAR or plan, the impact of subsequently refreshing the imported bundle is, in general, broader than it would have been if you had not used <code>import-scope:=application</code>. This may well affect the performance of refresh.
- </para>
- </section>
-
- <section id="developing-applications-defining-libraries">
- <title>Defining Libraries</title>
- <para>
- Libraries are defined in a simple text file, typically with a <code>.libd</code> suffix. This file identifies the
- library and lists all of its constituent bundles. For example, the following is the library definition for
- Spring 2.5.4:
- <programlisting><emphasis role="bold">Library-SymbolicName</emphasis>: org.springframework.spring
-<emphasis role="bold">Library-Version</emphasis>: 2.5.4
-<emphasis role="bold">Library-Name</emphasis>: Spring Framework
-<emphasis role="bold">Import-Bundle</emphasis>: org.springframework.core;version="[2.5.4,2.5.5)",
- org.springframework.beans;version="[2.5.4,2.5.5)",
- org.springframework.context;version="[2.5.4,2.5.5)",
- org.springframework.aop;version="[2.5.4,2.5.5)",
- org.springframework.web;version="[2.5.4,2.5.5)",
- org.springframework.web.servlet;version="[2.5.4,2.5.5)",
- org.springframework.jdbc;version="[2.5.4,2.5.5)",
- org.springframework.orm;version="[2.5.4,2.5.5)",
- org.springframework.transaction;version="[2.5.4,2.5.5)",
- org.springframework.context.support;version="[2.5.4,2.5.5)",
- org.springframework.aspects;version="[2.5.4,2.5.5)",
- com.springsource.org.aopalliance;version="1.0"</programlisting>
- </para>
- <para>
- The following table lists all of the headers that may be used in a library definition:
- </para>
- <table id="developing-applications-defining-libraries-library-headers-table" colsep="1" frame="all" rowsep="1">
- <title>Library definition headers</title>
- <tgroup cols="2">
- <colspec colwidth="2*" />
- <colspec colwidth="5*" />
- <thead>
- <row>
- <entry>Header</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Library-SymbolicName</entry>
- <entry>Identifier for the library</entry>
- </row>
- <row>
- <entry>Library-Version</entry>
- <entry>Version number for the library</entry>
- </row>
- <row>
- <entry>Import-Bundle</entry>
- <entry>A comma separated list of bundle symbolic names.
- Each entry may optionally specify a version (using the <code>version=</code> directive)
- and the scope of the import (using the <code>import-scope</code> directive).</entry>
- </row>
- <row>
- <entry>Library-Name</entry>
- <entry>Optional. The human-readable name of the library</entry>
- </row>
- <row>
- <entry>Library-Description</entry>
- <entry>Optional. A human-readable description of the library</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="developing-applications-installing-dependencies">
- <title>Installing Dependencies</title>
- <para>
- Rather than encouraging the packaging of all an application’s dependencies within the application itself, @project.name@
- uses a local provisioning repository of bundles and libraries upon which an application can depend. When the @project.name@
- encounters an application with a particular dependency, it will automatically provide, from its provisioning repository,
- the appropriate bundle or library.
- </para>
- <para>
- Making a dependency available for provisioning is simply a matter of copying it to the appropriate location in the
- @project.name@’s local provisioning repository. By default this is
- <literal>SERVER_HOME/repository/usr</literal>. A more detailed discussion of the provisioning
- repository can be found in the <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink>.
- </para>
- </section>
- </section>
- <section id="developing-applications-application-trace">
- <title>Application Trace</title>
- <para>
- As described in the <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink> @project.name@ provides support for
- per-application trace for PARs, scoped Plans and WABs. @project.name@ provides SLF4J with Logback logging for Event Logging and Tracing.
- Application trace is configured in the <literal>serviceability.xml</literal> file.
- See the <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink> for more details.
- </para>
- </section>
- <section id="developing-applications-versioning">
- <title>Application Versioning</title>
- <para>
- In much the same way that individual OSGi bundles can be versioned, @project.name@ allows applications to be versioned. How exactly you do this depends on how you have packaged the application:
- <itemizedlist>
- <listitem>If you package your application using a PAR, you version the application by using the <literal>Application-Version</literal> header in the <code>MANIFEST.MF</code> file of the PAR file.</listitem>
- <listitem>If you use a plan to describe the artifacts that make up your application, you version it by using the <code>version</code> attribute of the <code><plan></code> root element of the plan’s XML file.</listitem>
- <listitem>If your application consists of a single bundle, you version it in the standard OSGi way: by using the <literal>Bundle-Version</literal> header of the <code>MANIFEST.MF</code> file of the bundle.</listitem>
- </itemizedlist>
- </para>
- <para>@project.name@ uses an application’s version to prevent clashes when multiple versions of the same application are deployed at
- the same time. For example, the application trace support described in <xref linkend="developing-applications-application-trace"/>,
- includes the application’s name and version in the file path. This ensures that each version of the same application has its
- own trace or logging file.
- </para>
- </section>
-</chapter>
diff --git a/programmer-guide/src/docs/asciidoc/architecture.adoc b/programmer-guide/src/docs/asciidoc/architecture.adoc
new file mode 100644
index 0000000..a73e950
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/architecture.adoc
@@ -0,0 +1,411 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-{version}/docs/virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:architecture[Deployment Architecture]
+
+== Deployment Architecture
+
+The {tomcat-product-name} offers several choices when it comes to deploying applications. Each
+choice offers certain advantages, and it is important to understand those in order to make
+the right choice for your application. In this chapter, we take a closer look at the choices
+offered, compare them, and provide guidelines in choosing the right one based on your
+specific needs.
+
+The {tomcat-product-name-short} supports standard self-contained WAR files thus allowing you to
+use the {tomcat-product-name} as an enhanced web server. The {tomcat-product-name-short} also supports the
+ *Shared Libraries* WAR format which allows for slimmer WAR files that
+depend on OSGi bundles instead of including JAR files inside the WAR. The *Shared
+ Services* WAR format allows developers to further reduce the complexity of
+standard WARs by deploying services and infrastructure bundles alongside the WAR. A shared
+services WAR will then consume the services published by those bundles. To complete the
+picture, the {tomcat-product-name-short} supports the new OSGi-standard *Web Application
+Bundle* deployment format for web applications that builds on the benefits
+provided by a shared services WAR. In addition to this, {tomcat-product-name-short} provides
+additional conveniences for developing and deploying Spring MVC-based web applications.
+
+For applications consisting of multiple bundles and web applications, plans and the PAR
+format are the primary deployment models that take advantage of OSGi capabilities. We will
+explore all of these formats and their suitability later in this guide.
+
+anchor:architecture-deployment-formats[]
+
+=== Supported Deployment Formats
+
+The {tomcat-product-name} supports applications packaged in the following formats:
+
+. xref:architecture-raw-osgi-bundles[Raw OSGi Bundles]
+. xref:architecture-wars[Java EE WAR]
+. xref:architecture-war-gemini[Web Application Bundles]
+. xref:architecture-pars[PARs]
+. xref:architecture-plans[Plans]
+. xref:architecture-configurations[Configurations]
+
+When you deploy an application to the {tomcat-product-name-short}, each deployment artifact
+(e.g., a single bundle, WAR, PAR, or plan) passes through a deployment pipeline. This
+deployment pipeline is responsible for processing applications of certain types (i.e.,
+application type). The {version} release of the {tomcat-product-name-short} natively
+supports deployers analogous to each of the aforementioned packaging options.
+
+Let's take a closer look now at each of the supported deployment and packaging
+options to explore which one is best suited to your application.
+
+anchor:architecture-raw-osgi-bundles[]
+
+==== Raw OSGi Bundles
+
+At its core, the {tomcat-product-name} is an OSGi container. Thus any OSGi-compliant
+bundle can be deployed directly on the {tomcat-product-name-short} unmodified. You'll
+typically deploy an application as a single bundle or a set of stand-alone bundles
+if you'd like to publish or consume services globally within the container via
+the OSGi Service Registry.
+
+anchor:architecture-wars[]
+
+==== WAR Deployment Formats
+
+For Web Application Archives (WAR), the {tomcat-product-name} provides support for the
+following three formats.
+
+. xref:architecture-standard-war[Standard WAR]
+. xref:architecture-shared-libraries-war[Shared Libraries WAR]
+. xref:architecture-shared-services-war[Shared Services WAR]
+
+Each of these formats plays a distinct role in the incremental migration path
+from a standard Java EE WAR to an OSGi-ified web application.
+
+anchor:architecture-standard-war[]
+
+==== Standard WAR
+
+Standard WAR files are supported directly in the {tomcat-product-name-short}. At
+deployment time, the WAR file is transformed into an OSGi bundle and installed
+into Tomcat. All the standard WAR contracts are honoured, and your existing WAR
+files should just drop in and deploy without change. Support for standard,
+unmodified WAR files allows you to try out the {tomcat-product-name} on your existing
+web applications and then gradually migrate toward the *Shared
+Libraries WAR* and *Shared Services WAR* formats.
+
+In addition to the standard support for WARs that you would expect from
+Tomcat, the {tomcat-product-name-short} also enables the following features:
+
+. Spring-driven load-time weaving (see Section 6.8.4, “Load-time weaving
+with AspectJ in the Spring Framework").
+Diagnostic information such as FFDC (first failure data capture)
+. The main benefit of this application style is familiarity -- developers know
+how to create a WAR file! You can take advantage of the
+{tomcat-product-name-short}'s added feature set without modifying the
+application. The application can also be deployed on other Servlet containers or
+Java EE application servers.
+
+You may choose this application style if the application is fairly simple and
+small. You may also prefer this style even for large and complex applications as
+a starting point and migrate to the other styles over time as discussed in xref:migrating-to-osgi[].
+
+anchor:architecture-shared-libraries-war[]
+
+==== Shared Libraries WAR
+
+If you have experience with developing and packaging web applications using
+the standard WAR format, you're certainly familiar with the pains of
+library bloat. So, unless you're installing shared libraries in a common
+library folder for your Servlet container, you have to pack all JARs required by
+your web application in `/WEB-INF/lib`. Prior to the release of
+the {tomcat-product-name}, such library bloat has essentially been the norm for web
+applications, but now there is a better solution! The Shared Libraries WAR
+format reduces your application's deployment footprint and eradicates
+library bloat by allowing you to declare dependencies on libraries via standard
+OSGi manifest headers such as `Import-Package` and `Require-Bundle` . The {tomcat-product-name-short} provides additional
+support for simplifying dependency management via the `Import-Library` and `Import-Bundle` manifest headers
+which are essentially macros that get expanded into OSGi-compliant `Import-Package` statements.
+
+[TIP]
+--
+For detailed information on which libraries are already available, check
+out the {ebr}.
+--
+
+anchor:architecture-shared-services-war[]
+
+==== Shared Services WAR
+
+Once you've begun taking advantage of declarative dependency management
+with a Shared Libraries WAR, you'll likely find yourself wanting to take
+the next step toward reaping further benefits of an OSGi container: sharing
+services between your OSGi-compliant bundles and your web applications. By
+building on the power and simplicity of Gemini Blueprint, the *Shared Services
+WAR* format puts the OSGi Service Registry at your finger tips. As
+a best practice you'll typically publish services from your domain,
+service, and infrastructure bundles via `<osgi:service ...>` and then consume them in your web application's
+ApplicationContext via `<osgi:reference ... >`. Doing so
+promotes programming to interfaces and allows you to completely decouple your
+web-specific deployment artifacts from your domain model, service layer, etc.,
+and that's certainly a step in the right direction. Of the three supported
+WAR deployment formats, the Shared Services WAR is by far the most attractive in
+terms of modularity and reduced overall footprint of your web applications.
+
+anchor:architecture-war-gemini[]
+
+==== WARs and the Gemini Web Container
+
+{tomcat-product-name} fully supports the OSGi Web Applications standard. Using the
+reference implementation from Gemini Web that was developed by SpringSource from
+an offshoot of the original {tomcat-product-name-short} codebase. This RI is now fully
+integrated in {tomcat-product-name-short} as the basis of the support for web
+application deployment.
+
+The OSGi Web Applications specification introduces the concept of a *Web
+Application Bundle*, which is a WAR that is also a bundle. The
+specification defines how WAR files are transformed into bundles automatically
+as needed.
+
+You can find an introduction to the Web Container in blog entries written by
+the {virgo-name} team http://blog.springsource.com/2009/05/27/introduction-to-the-osgi-web-container/[here]
+and http://blog.springsource.com/2009/06/01/what-the-osgi-web-container-means-for-dm-server/[here].
+
+anchor:architecture-war-gemini-extensions[]
+
+==== Extensions to the Web Container
+
+{tomcat-product-name} provides a variety of extensions to the Web Container that
+allow you to construct sophisticated applications. The table below
+summarises the extensions that are available or in development.
+
+[cols=",",options="header",]
+|=======================================================================
+| Feature | Description
+| Instrumentable ClassLoaders | All web bundle ClassLoaders are
+instrumentable by Spring's load-time weaving infrastructure.
+
+| Support for exploded bundles/WARs | Bundles/WARs in directory form can
+be deployed as Web Application Bundles
+
+| Support for scanning TLDs in dependencies | As per the Web Application
+specification, all TLDs located inside a web bundle are located using
+the rules defined in the JSP 2.1 specification. In
+{tomcat-product-name-short}, the dependencies of a Web Application
+Bundle are also scanned for TLDs following the rules outlined in JSP 2.1
+|=======================================================================
+
+anchor:architecture-pars[]
+
+==== PAR
+
+A PAR is a standard JAR which contains all of the modules of your application
+(e.g., service, domain, and infrastructure bundles as well as a WAR or web module
+for web applications) in a single deployment unit. This allows you to deploy,
+refresh, and undeploy your entire application as a single entity. If you are
+familiar with Java EE, it is worth noting that a PAR can be considered a replacement
+for an EAR (Enterprise Archive) within the context of an OSGi container. As an added
+bonus, modules within a PAR can be refreshed independently and on-the-fly, for
+example via the Virgo Eclipse IDE Tooling (see the Virgo Tools Guide).
+
+Many of the benefits of the PAR format are due to the underlying OSGi
+infrastructure, including:
+
+* Fundamentally modularized applications: instead of relying on fuzzy
+boundaries between logical modules in a monolithic application, this
+style promotes physically separated modules in the form of OSGi bundles.
+Then each module may be developed separately, promoting parallel
+development and loose coupling.
+
+* Robust versioning of various modules: the versioning capability
+offered by OSGi is much more comprehensive than alternatives. Each
+module can specify a version range for each of its dependencies. Bundles
+are isolated from each other in such a way that multiple versions of a
+bundle may be used simultaneously in an application.
+
+* Improved manageability: each bundle may be deployed or undeployed in
+a running application. This allows modifying the existing application to
+fix bugs, improve performance, and even to add new features without
+having to restart the application.
+
+Furthermore, PARs scope the bundles of your application within the
+{tomcat-product-name-short}. Scoping provides both a physical and logical application
+boundary, effectively shielding the internals of your application from other PARs
+deployed within the {tomcat-product-name-short}. This means your application doesn't
+have to worry about clashing with other running applications (e.g., in the OSGi
+Service Registry). You get support for load-time weaving, classpath scanning,
+context class loading, etc., and the {tomcat-product-name-short} does the heavy lifting for
+you to make all this work seamlessly in an OSGi environment. If you want to take
+full advantage of all that the {tomcat-product-name} and OSGi have to offer, packaging and
+deploying your applications as a PAR is a good choice, although plans are an even
+better one, as described in the next section.
+
+.OSGi != multiple JARs
+[TIP]
+--
+Note that while physically separated modules can, in theory, be implemented
+simply using multiple JARs, complex versioning requirements often make this
+impractical. For example, consider the situation depicted in the diagram below.
+
+* Bundle A depends on version `1.0.0` of bundle `B` and version `2.0.0` of bundle `C`.
+* Bundle B depends on version `1.0.0` of bundle `C`.
+
+Suppose that versions `1.0.0` and `2.0.0` of bundle `C` are neither
+backward nor forward compatible. Traditional monolithic applications cannot
+handle such situations: either bundle `A` or bundle `B` would need reworking which
+undermines truly independent development. OSGi's versioning scheme enables
+this scenario to be implemented in a robust manner. If it is desirable to rework
+the application to share a single version of `C`, then this can be planned in and
+is not forced.
+
+image::architecture-bundle-versioning.png[]
+--
+
+anchor:architecture-plans[]
+
+==== Plans
+
+A plan is similar to a PAR in that it encapsulates all of the artifacts of your
+application in a single deployment unit. The main difference, however, is that a
+plan is simply an XML file that lists the artifacts of your application; a PAR, by
+contrast, is an actual JAR file that physically contains the artifacts. Just like a
+PAR, you deploy, refresh, and undeploy a plan as a single entity. We highly
+recommends the use of plans for creating applications.
+
+When you create a plan, you can specify that the included bundles and services
+are in a scope that isolates them from the rest of {tomcat-product-name} and its
+deployments. This scoping ensures that the bundles wire to each other and see each
+other's services in preference to services from outside the scope. Scoping
+also prevents application code from leaking into the global scope or scope of
+another application. In addition, a plan can link the lifecycle of a group of
+bundles together atomically, which ensures that start, stop, and uninstall
+events on a single artifact in the plan are escalated to all artifacts in the plan.
+You can, however, disable both of these features by simply setting an attribute in
+the plan.
+
+The general benefits of using plans are similar to those of using PARs; see xref:architecture-pars[PAR] for details. Plans offer added benefits,
+however, such as the ability to control the deployment order of your application:
+the order in which you list artifacts in the plan's XML file is the order in
+which {tomcat-product-name-short} deploys them. Additionally, because plans specify the
+artifacts that make up an application by reference, it is easier to share artifacts
+between plans as well as update individual parts of a plan without having to
+physically repackage (re-JAR) it.
+
+anchor:architecture-configurations[]
+
+==== Configurations
+
+A Configuration is simply a Java properties file. When deployed it will be
+recognised by the deployer and installed in to *Configuration
+Admin* for later use by your applications. {tomcat-product-name-short} supports
+both singleton (ManagedService) and factory (ManagedServiceFactory) configurations.
+(see section 104.6 in the Compendium Specification)
+
+For a singleton configuration the name that it will be installed under is its filename
+minus the `.properties` extension. Factory Configuration is supported by
+specifying the *service.factoryPid* property. In this case the actual PID will
+be created by *Configuration Admin* (see section 104.6 in the
+Compendium Specification).
+
+How to consume configuration data is discussed xref:developing-applications-configuration-artifacts[later].
+
+anchor:architecture-dependency-types[]
+
+=== Dependency Types
+
+In an OSGi environment, there are two kinds of dependencies between various bundles:
+*type* dependency and *service* dependency.
+
+* *Type dependency*: A bundle may depend on a
+type exported by another bundle thus creating a type dependency. Type
+dependencies are managed through `Import-Package` and
+`Export-Package` directives in the OSGi manifest. This
+kind of dependency is similar to a JAR file using types in other JAR files
+from the classpath. However, as we've seen earlier, there are
+significant differences.
+* *Service dependency*: A bundle may also
+publish services (preferably using Gemini Blueprint), and other bundles may consume
+those services. If two bundles depend on the same service, both will be
+communicating effectively to the same object. More specifically, any state
+for that service will be shared between all the clients of that service.
+This kind of arrangement is similar to the commonly seen client-server
+interaction through mechanisms such as RMI or Web Services.
+
+=== Regions
+
+Conceptually, the {umbrella-virgo-name} can be divided into two separate subsystems, called Regions. This
+provides a way to keep the {kernel-product-name} separate from user applications. Read more about Regions
+and the two in {virgo-name} in the {user-guide}
+concepts section.
+
+anchor:architecture-forming-bundles[A Guide to Forming Bundles]
+
+=== A Guide to Forming Bundles
+
+So what makes an application suitable for deployment on the {tomcat-product-name}? Since
+OSGi is at the heart of the {tomcat-product-name-short}, modular applications consisting of
+bundles, which each represent distinct functionality and well-defined boundaries, can
+take maximum advantage of the OSGi container's capabilities. The core ideas behind
+forming bundles require following good software engineering practices: separation of
+concerns, loose coupling, and communication through clear interfaces. In this section,
+we look at a few approaches that you may use to create modular applications for
+{tomcat-product-name} deployment. Please consider the following discussion as guidelines and
+not as rules.
+
+Bundles can be formed along horizontal slices of layering and vertical slices of
+function. The objective is to enable independent development of each bundle and minimize
+the skills required to develop each bundle.
+
+For example, an application could have the following bundles:
+*infrastructure*, *domain*,
+*repository*, *service*, and
+*web* as shown in the following diagram.
+
+image::bundle-dependencies-layers.png[]
+
+Each bundle consists of types appropriate for that layer and exports
+packages and services to be used by other layers. Let's examine each bundle in
+more detail:
+
+[options="header",cols="<,<,<,^,^"]
+.Bundles across layers
+|=======================================================================
+| Bundles | Imported Packages | Exported Packages | Consumed Services | Published Services
+| Infrastructure | Third-party libraries | Infrastructure interfaces | None | None
+| Domain | Depends: for example,
+ if JPA is used to
+ annotate persistent
+ types, then JPA
+ packages. | Public domain types | None | None
+| Web | Domain, Service | None | Service beans | None
+| Service | Domain,
+ Infrastructure,
+ Repository | Service interfaces | Repository beans | Service beans
+| Repository | Domain,
+ Third-party libraries,
+ ORM bundles, etc. | Repository interfaces | DataSources,
+ ORM session/entity managers,
+ etc. | Repository beans
+|=======================================================================
+
+Within each layer, you may create bundles for each subsystem representing a vertical
+slice of business functionality. For example, as shown in the following figure, the
+service layer is divided into two bundles each representing separate business
+functions.
+image:bundle-dependencies-verticals.png[]
+
+You can similarly separate the repositories, domain classes, and web controllers
+based on the business role they play.
+
diff --git a/programmer-guide/images/architecture-bundle-versioning.graffle b/programmer-guide/src/docs/asciidoc/assets/images/architecture-bundle-versioning.graffle
similarity index 100%
rename from programmer-guide/images/architecture-bundle-versioning.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/architecture-bundle-versioning.graffle
Binary files differ
diff --git a/programmer-guide/images/architecture-bundle-versioning.png b/programmer-guide/src/docs/asciidoc/assets/images/architecture-bundle-versioning.png
similarity index 100%
rename from programmer-guide/images/architecture-bundle-versioning.png
rename to programmer-guide/src/docs/asciidoc/assets/images/architecture-bundle-versioning.png
Binary files differ
diff --git a/programmer-guide/images/bundle-dependencies-layers.graffle b/programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-layers.graffle
similarity index 100%
rename from programmer-guide/images/bundle-dependencies-layers.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-layers.graffle
Binary files differ
diff --git a/programmer-guide/images/bundle-dependencies-layers.png b/programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-layers.png
similarity index 100%
rename from programmer-guide/images/bundle-dependencies-layers.png
rename to programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-layers.png
Binary files differ
diff --git a/programmer-guide/images/bundle-dependencies-verticals.graffle b/programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-verticals.graffle
similarity index 100%
rename from programmer-guide/images/bundle-dependencies-verticals.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-verticals.graffle
Binary files differ
diff --git a/programmer-guide/images/bundle-dependencies-verticals.png b/programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-verticals.png
similarity index 100%
rename from programmer-guide/images/bundle-dependencies-verticals.png
rename to programmer-guide/src/docs/asciidoc/assets/images/bundle-dependencies-verticals.png
Binary files differ
diff --git a/programmer-guide/images/bundle-references.png b/programmer-guide/src/docs/asciidoc/assets/images/bundle-references.png
similarity index 100%
rename from programmer-guide/images/bundle-references.png
rename to programmer-guide/src/docs/asciidoc/assets/images/bundle-references.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-complexDomain-skeleton-bundles.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-complexDomain-skeleton-bundles.png
similarity index 100%
rename from programmer-guide/images/create-new-par-complexDomain-skeleton-bundles.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-complexDomain-skeleton-bundles.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-complexDomain-web-page.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-complexDomain-web-page.png
similarity index 100%
rename from programmer-guide/images/create-new-par-complexDomain-web-page.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-complexDomain-web-page.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-dataSource-classNotFound-eclipse.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-dataSource-classNotFound-eclipse.png
similarity index 100%
rename from programmer-guide/images/create-new-par-dataSource-classNotFound-eclipse.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-dataSource-classNotFound-eclipse.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-add-infrastructure-to-par.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-add-infrastructure-to-par.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-add-infrastructure-to-par.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-add-infrastructure-to-par.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-created-eclipse.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-created-eclipse.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-created-eclipse.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-created-eclipse.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-databasepopulator-before-manifest.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-databasepopulator-before-manifest.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-databasepopulator-before-manifest.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-databasepopulator-before-manifest.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-dbcp-manifest.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-dbcp-manifest.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-dbcp-manifest.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-dbcp-manifest.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-empty-nested-bundles-eclipse.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-empty-nested-bundles-eclipse.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-empty-nested-bundles-eclipse.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-empty-nested-bundles-eclipse.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-server-with-par-project-deployed.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-server-with-par-project-deployed.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-server-with-par-project-deployed.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-server-with-par-project-deployed.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-wizard-step1.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-wizard-step1.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-wizard-step1.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-wizard-step1.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-infrastructure-wizard-step2.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-wizard-step2.png
similarity index 100%
rename from programmer-guide/images/create-new-par-infrastructure-wizard-step2.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-infrastructure-wizard-step2.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-par-created-eclipse.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-par-created-eclipse.png
similarity index 100%
rename from programmer-guide/images/create-new-par-par-created-eclipse.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-par-created-eclipse.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-par-wizard-step1.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-par-wizard-step1.png
similarity index 100%
rename from programmer-guide/images/create-new-par-par-wizard-step1.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-par-wizard-step1.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-par-wizard-step2.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-par-wizard-step2.png
similarity index 100%
rename from programmer-guide/images/create-new-par-par-wizard-step2.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-par-wizard-step2.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-repo-hsqldb-dependencies.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb-dependencies.png
similarity index 100%
rename from programmer-guide/images/create-new-par-repo-hsqldb-dependencies.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb-dependencies.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-repo-hsqldb-search-results.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb-search-results.png
similarity index 100%
rename from programmer-guide/images/create-new-par-repo-hsqldb-search-results.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb-search-results.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-repo-hsqldb-start.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb-start.png
similarity index 100%
rename from programmer-guide/images/create-new-par-repo-hsqldb-start.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb-start.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-repo-hsqldb.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb.png
similarity index 100%
rename from programmer-guide/images/create-new-par-repo-hsqldb.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-repo-hsqldb.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-simpleDomain-eclipse-full.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-eclipse-full.png
similarity index 100%
rename from programmer-guide/images/create-new-par-simpleDomain-eclipse-full.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-eclipse-full.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-simpleDomain-eclipse.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-eclipse.png
similarity index 100%
rename from programmer-guide/images/create-new-par-simpleDomain-eclipse.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-eclipse.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-simpleDomain-server.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-server.png
similarity index 100%
rename from programmer-guide/images/create-new-par-simpleDomain-server.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-server.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-simpleDomain-web-eclipse-complete.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-web-eclipse-complete.png
similarity index 100%
rename from programmer-guide/images/create-new-par-simpleDomain-web-eclipse-complete.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-web-eclipse-complete.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-simpleDomain-web-page.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-web-page.png
similarity index 100%
rename from programmer-guide/images/create-new-par-simpleDomain-web-page.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-simpleDomain-web-page.png
Binary files differ
diff --git a/programmer-guide/images/create-new-par-user-repository.png b/programmer-guide/src/docs/asciidoc/assets/images/create-new-par-user-repository.png
similarity index 100%
rename from programmer-guide/images/create-new-par-user-repository.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-new-par-user-repository.png
Binary files differ
diff --git a/programmer-guide/images/create-par-project.png b/programmer-guide/src/docs/asciidoc/assets/images/create-par-project.png
similarity index 100%
rename from programmer-guide/images/create-par-project.png
rename to programmer-guide/src/docs/asciidoc/assets/images/create-par-project.png
Binary files differ
diff --git a/programmer-guide/images/developing-applications-web-module-format.png b/programmer-guide/src/docs/asciidoc/assets/images/developing-applications-web-module-format.png
similarity index 100%
rename from programmer-guide/images/developing-applications-web-module-format.png
rename to programmer-guide/src/docs/asciidoc/assets/images/developing-applications-web-module-format.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-exploded-war.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-exploded-war.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-exploded-war.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-exploded-war.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-par-exploded-web.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-par-exploded-web.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-par-exploded-web.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-par-exploded-web.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-par-exploded.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-par-exploded.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-par-exploded.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-par-exploded.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-par-sample.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-par-sample.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-par-sample.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-par-sample.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-sample-layout.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-sample-layout.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-sample-layout.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-sample-layout.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-shared-services-eclipse.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-shared-services-eclipse.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-shared-services-eclipse.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-shared-services-eclipse.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-shared-services-service-resources.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-shared-services-service-resources.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-shared-services-service-resources.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-shared-services-service-resources.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-shared-services-war-resources.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-shared-services-war-resources.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-shared-services-war-resources.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-shared-services-war-resources.png
Binary files differ
diff --git a/programmer-guide/images/formtags-case-study-war-webpage.png b/programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-war-webpage.png
similarity index 100%
rename from programmer-guide/images/formtags-case-study-war-webpage.png
rename to programmer-guide/src/docs/asciidoc/assets/images/formtags-case-study-war-webpage.png
Binary files differ
diff --git a/programmer-guide/images/import-bundle_import-library.graffle b/programmer-guide/src/docs/asciidoc/assets/images/import-bundle_import-library.graffle
similarity index 100%
rename from programmer-guide/images/import-bundle_import-library.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/import-bundle_import-library.graffle
Binary files differ
diff --git a/programmer-guide/images/import-bundle_import-library.png b/programmer-guide/src/docs/asciidoc/assets/images/import-bundle_import-library.png
similarity index 100%
rename from programmer-guide/images/import-bundle_import-library.png
rename to programmer-guide/src/docs/asciidoc/assets/images/import-bundle_import-library.png
Binary files differ
diff --git a/programmer-guide/images/import-package.graffle b/programmer-guide/src/docs/asciidoc/assets/images/import-package.graffle
similarity index 100%
rename from programmer-guide/images/import-package.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/import-package.graffle
Binary files differ
diff --git a/programmer-guide/images/import-package.png b/programmer-guide/src/docs/asciidoc/assets/images/import-package.png
similarity index 100%
rename from programmer-guide/images/import-package.png
rename to programmer-guide/src/docs/asciidoc/assets/images/import-package.png
Binary files differ
diff --git a/programmer-guide/images/introduction-architecture.graffle b/programmer-guide/src/docs/asciidoc/assets/images/introduction-architecture.graffle
similarity index 100%
rename from programmer-guide/images/introduction-architecture.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/introduction-architecture.graffle
Binary files differ
diff --git a/programmer-guide/images/introduction-architecture.png b/programmer-guide/src/docs/asciidoc/assets/images/introduction-architecture.png
similarity index 100%
rename from programmer-guide/images/introduction-architecture.png
rename to programmer-guide/src/docs/asciidoc/assets/images/introduction-architecture.png
Binary files differ
diff --git a/programmer-guide/images/migrating-to-osgi-par-structure.graffle b/programmer-guide/src/docs/asciidoc/assets/images/migrating-to-osgi-par-structure.graffle
similarity index 100%
rename from programmer-guide/images/migrating-to-osgi-par-structure.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/migrating-to-osgi-par-structure.graffle
Binary files differ
diff --git a/programmer-guide/images/migrating-to-osgi-par-structure.png b/programmer-guide/src/docs/asciidoc/assets/images/migrating-to-osgi-par-structure.png
similarity index 100%
rename from programmer-guide/images/migrating-to-osgi-par-structure.png
rename to programmer-guide/src/docs/asciidoc/assets/images/migrating-to-osgi-par-structure.png
Binary files differ
diff --git a/programmer-guide/images/migration-path-war-to-shsrv.graffle b/programmer-guide/src/docs/asciidoc/assets/images/migration-path-war-to-shsrv.graffle
similarity index 100%
rename from programmer-guide/images/migration-path-war-to-shsrv.graffle
rename to programmer-guide/src/docs/asciidoc/assets/images/migration-path-war-to-shsrv.graffle
Binary files differ
diff --git a/programmer-guide/images/migration-path-war-to-shsrv.png b/programmer-guide/src/docs/asciidoc/assets/images/migration-path-war-to-shsrv.png
similarity index 100%
rename from programmer-guide/images/migration-path-war-to-shsrv.png
rename to programmer-guide/src/docs/asciidoc/assets/images/migration-path-war-to-shsrv.png
Binary files differ
diff --git a/programmer-guide/images/new-par-project.png b/programmer-guide/src/docs/asciidoc/assets/images/new-par-project.png
similarity index 100%
rename from programmer-guide/images/new-par-project.png
rename to programmer-guide/src/docs/asciidoc/assets/images/new-par-project.png
Binary files differ
diff --git a/programmer-guide/images/par-content.png b/programmer-guide/src/docs/asciidoc/assets/images/par-content.png
similarity index 100%
rename from programmer-guide/images/par-content.png
rename to programmer-guide/src/docs/asciidoc/assets/images/par-content.png
Binary files differ
diff --git a/programmer-guide/images/s2-logo.png b/programmer-guide/src/docs/asciidoc/assets/images/s2-logo.png
similarity index 100%
rename from programmer-guide/images/s2-logo.png
rename to programmer-guide/src/docs/asciidoc/assets/images/s2-logo.png
Binary files differ
diff --git a/programmer-guide/images/start.png b/programmer-guide/src/docs/asciidoc/assets/images/start.png
similarity index 100%
rename from programmer-guide/images/start.png
rename to programmer-guide/src/docs/asciidoc/assets/images/start.png
Binary files differ
diff --git a/programmer-guide/images/virgo-logo-large.png b/programmer-guide/src/docs/asciidoc/assets/images/virgo-logo-large.png
similarity index 100%
rename from programmer-guide/images/virgo-logo-large.png
rename to programmer-guide/src/docs/asciidoc/assets/images/virgo-logo-large.png
Binary files differ
diff --git a/programmer-guide/images/virgo-logo-small.png b/programmer-guide/src/docs/asciidoc/assets/images/virgo-logo-small.png
similarity index 100%
rename from programmer-guide/images/virgo-logo-small.png
rename to programmer-guide/src/docs/asciidoc/assets/images/virgo-logo-small.png
Binary files differ
diff --git a/programmer-guide/images/welcome.png b/programmer-guide/src/docs/asciidoc/assets/images/welcome.png
similarity index 100%
rename from programmer-guide/images/welcome.png
rename to programmer-guide/src/docs/asciidoc/assets/images/welcome.png
Binary files differ
diff --git a/programmer-guide/src/docs/asciidoc/common-libraries.adoc b/programmer-guide/src/docs/asciidoc/common-libraries.adoc
new file mode 100644
index 0000000..8c13f9f
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/common-libraries.adoc
@@ -0,0 +1,96 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:common-libraries[]
+
+== Working with Common Enterprise Libraries
+
+Common Libraries
+
+anchor:common-libraries-hibernate[]
+
+=== Working with Hibernate
+
+anchor:common-libraries-hibernate-import[]
+
+==== Importing Hibernate
+
+Hibernate uses CGLIB to dynamically create subclasses of your entity types at
+runtime. To guarantee that Hibernate and CGLIB can correctly see the types,
+you must add an `Import-Library` or `Import-Bundle` for the Hibernate library or bundle
+into any bundle that uses Hibernate directly.
+
+Additionally, if other bundles in your application contain types to be persisted by Hibernate, then be sure to specify the `import-scope` directive of the `Import-Bundle` header in the bundle that uses Hibernate directly. The `import-scope` directive tells {tomcat-product-name} to implicitly import the bundle into all other bundles that make up the application; this ensures that bundles that indirectly depend on the generated Hibernate classes have access to them, but you do not have to explicitly update their `Import-Bundle` header, ensuring modularity. For example:
+
+[source,txt]
+----
+Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";import-scope:=application
+----
+
+The `import-scope` directive works only for the bundles in a scoped application (PARs or plans.)
+
+anchor:common-libraries-datasources[]
+
+=== Working with DataSources
+
+Many `DataSource` implementations use the `DriverManager`
+class which is incompatible with typical OSGi class loading semantics. To get around this,
+use a `DataSource` implementation that does not rely on
+`DriverManager`. Versions of the following
+`DataSources` that are known to work in an OSGi environment are available in the
+{ebr}.
+
+* http://build.eclipse.org/rt/virgo/ivy/bundles/release/org.eclipse.virgo.mirrored/org.apache.commons.dbcp/[Apache Commons DBCP]
+* SimpleDriverDataSource available in http://build.eclipse.org/rt/virgo/ivy/bundles/release/org.eclipse.virgo.mirrored/org.springframework.jdbc/[Spring JDBC] 2.5.5 and later
+
+anchor:common-libraries-weaving-instrumentation[]
+
+=== Weaving and Instrumentation
+
+When using a library that performs bytecode weaving or instrumentation, such as AspectJ,
+OpenJPA or EclipseLink, any types that are woven must be able to see the library doing
+the weaving. This is accomplished by adding an `Import-Library` for the
+weaving library into all bundles that are to be woven.
+
+Weaving is often used by JPA implementations to transform persisted types. When using a
+JPA provider that uses load-time weaving, an `Import-Library` for the
+provider is needed in the bundles containing the persisted types.
+
+anchor:common-libraries-tld[]
+
+=== JSP Tag Libraries
+
+When using tag libraries within a WAR or WAB, be sure to include an `Import-Bundle`
+or `Import-Library` for the tag library bundle(s). This will ensure that your WAR or WAB
+can see the TLD definition and implementing types. For example, to use the Apache implementation of JSTL,
+add the following to your bundle's `/META-INF/MANIFEST.MF`:
+
+[source,txt]
+----
+Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1.1.2"
+----
+
+`Import-Package` can also be used but it is tedious to add all the imports as there are
+typically lots of tld definitions in a bundle providing them.
+
diff --git a/programmer-guide/src/docs/asciidoc/developing-applications.adoc b/programmer-guide/src/docs/asciidoc/developing-applications.adoc
new file mode 100644
index 0000000..491a434
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/developing-applications.adoc
@@ -0,0 +1,967 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-{version}/docs/virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:developing-applications[Developing Applications]
+
+== Developing Applications
+
+Applications that take advantage of the OSGi capabilities of {virgo-name}
+are typically comprised of multiple bundles. Each bundle may have dependencies on
+other bundles. Furthermore, each bundle exposes only certain packages and
+services. In this chapter, we look at how to create bundles, import and export
+appropriate functionality, and create artifacts to deploy web applications on the {tomcat-product-name}.
+
+anchor:developing-applications-bundle[]
+
+=== Anatomy of a Bundle
+
+[TIP]
+--
+This is an abbreviated introduction to OSGi bundles. Please refer to the {gemini-blueprint-guide} for full details.
+--
+
+An OSGi bundle is simply a jar file with metadata that describe
+additional characteristics such as version and imported and exported packages.
+
+A bundle exports types and publishes services to be used by other bundles:
+
+* *Types*: via the OSGi `Export-Package` directive,
+* *Services*: via Gemini Blueprint's `<service ... >` XML namespace element.
+
+A bundle may import types and services exported by other bundles:
+
+* *Types*: via the OSGi `Import-Package` directive,
+* *Services*: via Gemini Blueprint's `<reference ... >` XML namespace element.
+
+Let's see an example from the PetClinic sample application. The following listing shows the
+`MANIFEST.MF` file for the `org.springframework.petclinic.infrastructure.hsqldb` bundle.
+
+.MANIFEST.MF
+[source,txt]
+----
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: PetClinic HSQL Database Infrastructure
+Bundle-SymbolicName: org.springframework.petclinic.infrastructure.hsqldb
+Bundle-Version: 1.0
+Import-Library: org.springframework.spring;version="[2.5,2.6]"
+Import-Bundle: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi,1.2.2.osgi]",
+ com.springsource.org.hsqldb;version="[1.8.0.9,1.8.0.9]"
+Import-Package: javax.sql
+Export-Package: org.springframework.petclinic.infrastructure
+----
+
+The `org.springframework.petclinic.infrastructure.hsqldb` bundle expresses its dependencies on
+the `javax.sql` package, the Commons DBCP and HSQLDB bundles, and the Spring library (we will examine
+the details of the library artifact in xref:developing-applications-defining-libraries[]. The Commons DBCP
+bundle is imported at a version of exactly `1.2.2.osgi` and the HSQLDB bundle is imported at a version of exactly
+`1.8.0.9`. The Spring library is imported at a version between `2.5` inclusive and `2.6` exclusive.
+
+Note that you do not specify the bundle that will provide the imported packages.
+{virgo-name} will examine the available bundles and satisfy the required dependencies.
+
+The following `osgi-context.xml` file from the PetClinic sample's
+`org.springframework.petclinic.repository.jdbc` bundle declares a service published by the bundle and
+references a service published by another bundle.
+
+.osgi-context.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<beans:beans xmlns="http://www.springframework.org/schema/osgi"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:beans="http://www.springframework.org/schema/beans"
+ xsi:schemaLocation="http://www.springframework.org/schema/osgi
+ http://www.springframework.org/schema/osgi/spring-osgi.xsd
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans.xsd">
+
+ <service id="osgiClinic" ref="clinic" interface="org.springframework.petclinic.repository.Clinic" />
+ <reference id="dataSource" interface="javax.sql.DataSource"/>
+
+</beans:beans>
+----
+
+The `service` element publishes the `clinic` bean
+(a regular Spring bean declared in the `module-context.xml` file) and specifies
+`org.springframework.petclinic.repository.Clinic` as the type
+of the published service.
+
+The `reference` elements define a `dataSource` bean that references
+a service published by another bundle with a an interface type of `javax.sql.DataSource`.
+
+anchor:developing-applications-packaging[Creating PARs and Web Applications]
+
+=== Creating PARs and Web Applications
+
+{virgo-name} supports two OSGi-oriented ways of packaging applications: the PAR format
+and application bundles (including web bundles). The {tomcat-product-name-short} also supports three
+distinct WAR deployment and packaging formats: standard Java EE WAR, Shared Libraries WAR, Shared Services WAR.
+
+{virgo-name} also supports plans as a way to describe an application. This method is similar to a PAR
+in that it encapsulates all the artifacts of an application as a single unit, but differs in that a plan simply
+lists the bundles in an XML file rather than packaging all the bundles in a single JAR file. The use of plans
+offers additional benefits to using PARs; for this reason, we recommend their use. For details, see
+xref:developing-applications-plans[].
+
+anchor:developing-applications-packaging-par[]
+
+==== PARs
+
+An OSGi application is packaged as a JAR file, with extension `.par`. A PAR artifact offers several benefits:
+
+* A PAR file has an application name, version, symbolic name, and description.
+* The artifacts of a PAR file are scoped so that they cannot
+be shared accidentally by other applications. The scope forms a boundary for automatic
+propagation of load time weaving and bundle refresh.
+See xref:developing-applications-plans-scoping[Plans and Scoping] for more on scoping.
+* Since a PAR is scoped, its artifacts have their exported packages imported by the
+synthetic context bundle which is used for thread context class loading. So,
+for example, hibernate will be able to load classes of any of the exported
+packages of the bundles in a PAR file using the thread context class loader.
+* A PAR file is visible to management interfaces.
+* A PAR file can be undeployed and redeployed as a unit.
+* A PAR file is *atomic* in that it ties together the lifecycle of its artifacts. If you start, stop, or uninstall
+one of a PAR's artifacts, {virgo-name} escalates the operation to the whole PAR file.
+So {virgo-name} prevents artifacts of a PAR from being in inconsistent states.
+For example, if one artifact should fail to start, then {virgo-name} stops all artifacts in the PAR.
+
+See xref:developing-applications-plans-scoping[Plans and Scoping] for more information on scoping.
+
+A PAR includes one or more application bundles and its manifest specifies the following
+manifest headers:
+
+anchor:developing-applications-packaging-par-headers-table[]
+
+[options="header",cols=","]
+.PAR file headers
+|=======================================================================
+| Header | Description
+| `Application-SymbolicName` | Identifier for the application which, in combination with Application-Version, uniquely identifies an application
+| `Application-Name` | Human readable name of the application
+| `Application-Version` | Version of the application
+| `Application-Description` | Short description of the application
+|=======================================================================
+
+The following code shows an example MANIFEST.MF in a PAR file:
+
+.MANIFEST.MF
+[source]
+----
+Application-SymbolicName: com.example.shop
+Application-Version: 1.0
+Application-Name: Online Shop
+Application-Description: Example.com's Online Shopping Application
+----
+
+anchor:developing-applications-web-application-bundles
+
+==== Web Application Bundles
+
+{tomcat-product-name} supports Web Application Bundles that are compliant with the OSGi Web Applications specification.
+The defining property of a Bundle that makes it a Web Application Bundle is a manifest header, `Web-ContextPath`.
+This defines the context path the web application will be registered under.
+
+See xref:using-spring[Using Spring and Gemini Blueprint] for information on using Spring or Gemini Blueprint in a Web Application Bundle.
+
+anchor:developing-applications-plans[Creating Plans]
+
+=== Creating Plans
+
+Plans are similar to PARs in that they encapsulate the artifacts of an application as a single unit.
+However plans are XML files that refer to their artifacts, whereas PARs are JAR files that physically contain their artifacts.
+Plans, known as *parent* plans may refer to other plans, known as *child* plans.
+
+Plans share several benefits with PARs:
+
+* A plan has a (symbolic) name and a version.
+* A plan may be *scoped*, although this is optional.
+See xref:developing-applications-plans-scoping[Plans and Scoping] for more on scoping.
+* A plan is visible to management interfaces.
+* A plan can be undeployed and redeployed as a unit.
+* A plan may be *atomic*, although this is optional.
+
+Plans have the following additional benefits compared to PARs:
+
+* {virgo-name} deploys the artifacts in the plan in the order in which they are listed in the XML file, which gives you
+complete control over deployment order.
+With a PAR, the order of deployment of the included artifacts is not guaranteed.
+* Since plans refer to their artifacts, it is easier to share content between plans as well as update individual
+parts of a plan without having to physically repackage (re-JAR) it.
+* Plans may contain child plans, but PARs cannot contain other PARs.
+* You can make certain plans deploy faster by disabling the provisioning of bundles to satisfy missing dependencies,
+but you cannot disable provisioning for PARs.
+* You can specify whether a plan is scoped or unscoped and atomic or non-atomic; PARs are always scoped and atomic.
+
+The artifacts of a plan are usually stored in {virgo-name}'s repository. This means, for example, that if you drop one of the plan's artifacts in the `pickup` directory rather than adding it to the repository, the plan will fail to deploy because it will not find the artifact.
+
+The artifacts of a plan may also be stored outside {virgo-name}'s repository, somewhere else on the file system and referenced from the plan using URIs.
+Such artifacts must be available on the file system when the plan is deployed and when {virgo-name} restarts while the plan is deployed.
+If you delete any of these artifacts, deployment of the plan may fail, either when it is initially deployed or when {virgo-name} restarts.
+
+anchor:developing-applications-plans-create[]
+
+==== Creating the Plan XML File
+
+Plans are XML files that have a `.plan` file extension, such as `multi-artifact.plan`.
+The structure of the XML file is simple:
+the root element is `<plan>` with attributes specifying the name of the plan, the version, atomicity, and scoping.
+Then, for each artifact that makes up your application,
+you add a `<artifact>` element, using its attributes to specify the type of artifact and its name and version.
+The following is a simple example of a plan's XML file:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true"
+ xmlns="http://www.eclipse.org/virgo/schema/plan"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.eclipse.org/virgo/schema/plan
+ http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
+
+ <artifact type="configuration" name="app-properties" version="1.0.0"/>
+ <artifact type="bundle" name="com.springsource.exciting.app" version="[2.0.0, 3.1.0)"/>
+
+</plan>
+----
+
+In the preceding example, the name of the plan is `multi-artifact.plan` and its version is `1.0.0`.
+The plan is both scoped and atomic. The plan contains two artifacts: one is a bundle called `com.springsource.exciting.app` and the other is a configuration file called `app-properties`.
+
+The following table describes the attributes of the `<plan>` element.
+
+[options="header",cols="1,3,1"]
+.PAR file headers
+|=======================================================================
+| Attribute | Description | Required?
+| `name` | Specifies the name of this plan.
+ {virgo-name} uses the name as one component of the unique
+ identifier of this plan. | Yes.
+| `version` | Specifies the version of this plan.
+ You must use OSGi version specification syntax,
+ such as `2.1.0`.
+ {virgo-name} uses the version as one component of
+ the unique identifier of this plan. | Yes.
+| `scoped` | Specifies whether {virgo-name} should install the
+ artifacts into plan-specific scope so that only the
+ application described by this plan has access to the artifacts.
+ If you disable scoping, then {virgo-name} installs
+ the artifacts into the global scope, which means they
+ are then available for access by all other deployed artifacts.
+ Set the attribute to `true` to enable scoping or
+ `false` to disable it. | Yes.
+| `atomic` | Specifies whether you want to tie together the lifecycle
+ of the artifacts in this plan.
+ Making a plan atomic means that if you start, stop, or
+ uninstall a single artifact in the plan, {virgo-name}
+ escalates the operation to the whole plan.
+ Also {virgo-name} prevents artifacts of an atomic plan
+ from being in inconsistent states.
+ For example, if one artifact should fail to start,
+ then {virgo-name} stops all artifacts in the plan.
+ Set this attribute to `true` to enable atomicity or
+ `false` to disable it. | Yes.
+| `provisioning`
+ | Specifies whether {virgo-name} installs bundles from
+ the repository to attempt to satisfy any missing
+ dependencies in the plan.
+ Missing dependencies prevent one or more bundles in
+ the plan from resolving.
+ For example, a bundle which imports a package cannot
+ resolve if the package is missing, that is, not
+ exported by another bundle. A value of
+ `auto` instructs {virgo-name} to install bundles from the repository
+ to attempt to satisfy any missing dependencies in the plan.
+ This is known as *auto-provisioning*.
+ A value of `disabled` prevents {virgo-name} from
+ installing bundles from the repository to attempt to
+ satisfy any missing dependencies in the plan.
+ This value can make the plan deploy faster, although if
+ there are missing dependencies, deployment will fail.
+ A value of `inherit`, which is the default if no value is specified, inherits the parent plan's provisioning behaviour.
+ If the plan does not have a parent, it inherits {virgo-name}'s
+ auto-provisioning behaviour. |No. If not specified, defaults to `inherit`.
+|=======================================================================
+
+
+The following table describes the attributes of the `<artifact>` element. Note that you must either specify `type`, `name`, and (optionally) `version`,
+in which case {virgo-name}'s repository is searched for the artifact, or `uri` in which case the artifact is obtained directly from the file system.
+If you specify `uri`, you must not specify `type`, `name`, or `version`.
+
+anchor:developing-applications-plans-create-artifact-attributes[]
+
+[options="header",cols="1,3,1"]
+.PAR file headers
+|=======================================================================
+| Attribute | Description | Required?
+| `type` | Specifies the type of the artifact. Valid values are:
+
+`bundle`: Specifies an OSGi bundle. Use this artifact type for WAR files and Web application bundles.
+`configuration`: Specifies that the artifact is a configuration file. Configuration files contain name/value pairs that set initial values for configuration properties of a bundle.
+`plan`: Specifies that the artifact is a plan.
+`par`: Specifies that the artifact is a PAR. | Yes, unless `uri` is specified in which case `type` must not be specified and is automatically determined from the artifact.
+| `name` | Specifies the name of the artifact.
+See xref:artifact-names[Artifact Names] for guidelines for determining
+the name of an artifact. | Yes, unless `uri` is specified in which case `name` must not be specified and is automatically determined from the artifact.
+| `version` | Specifies the range of versions of this artifact that
+ {virgo-name} should look up in its repositories and
+ then install and deploy.
+ You must use OSGi version specification syntax,
+ such as `[1.0.0, 2.0.0)`.
+ Note that a single version number represents the range
+ from that version number upwards.
+ For example, `1.3` represents the range of versions
+ greater than or equal to `1.3`. | No. If `uri` is specified, `version` must not be specified.
+ If neither `uri` nor `version` are specified, `version` defaults to `0`, which in OSGi means 0 to infinity, or any version.
+| `uri` | Specifies an optional, absolute URI string beginning
+ with `file:` that refers to the artifact on the file system.
+ Such an artifact must be available on the file system
+ when the plan is deployed and when {virgo-name} restarts
+ while the plan is deployed.
+ If you delete such an artifact, deployment of the plan may fail,
+ either when it is initially deployed or when {virgo-name} restarts.
+ This attribute is normally omitted so that the artifact
+ is searched for in {virgo-name}'s repository. | No. If not specified, {virgo-name} searches for the artifact in its repository.
+|=======================================================================
+
+anchor:artifact-names[]
+
+==== Artifact Names
+
+When you create a plan, you use the `name` attribute of the `<artifact>` element to specify the name of all the plan's dependencies. This section describes how to determine the name of an artifact, which is not always obvious.
+
+Use the following guidelines to determine the name of an artifact:
+
+* *Bundle*: In this context, a *bundle* refers to a standard OSGi bundle as well as a Web Application Bundle and a WAR file. The name of a bundle is the value of the `Bundle-SymbolicName` header in the `META-INF/MANIFEST.MF` file of the `*.jar`.
+If a WAR file has `Bundle-SymbolicName` header then it will be treated as a Web Application Bundle. The following `MANIFEST.MF` snippet shows a bundle with name `com.springsource.exciting.app`:
+
+....
+Bundle-SymbolicName: org.eclispe.virgo.exciting.app
+....
+
+If the bundle does not contain a `META-INF/MANIFEST.MF` file or the `MANIFEST.MF` doesn't contain a `Bundle-SymbolicName` header, then the name of the bundle is its filename minus the `.jar` or `.war` extension.
+
+* *Configuration File*: The name of a configuration or PID (Persistent Identity) is its filename minus the `.properties` extension. The PID can also be specified within the properties file with the
+ *service.pid* property.
+* *Plan*: The name of a plan is the value of the required `name` attribute of the `<plan>` element in the plan's XML file. In the following XML snippet, the plan name is `multi-artifact.plan`:
+
+....
+<?xml version="1.0" encoding="UTF-8"?>
+<plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true"
+ xmlns="http://www.eclipse.org/virgo/schema/plan">
+....
+* *PAR*: The name of a PAR is the value of the `Application-SymbolicName` header in the `META-INF/MANIFEST.MF` file of the `*.par` file. The following `MANIFEST.MF` snippet shows a PAR with name `com.springsource.my.par`:
+
+....
+Application-SymbolicName: org.eclipse.virgo.my.par
+....
+
+If the PAR does not contain a `META-INF/MANIFEST.MF` file, then the name of the PAR is its filename minus the `.par` extension.
+
+anchor:passing-properties[]
+
+==== Supplying Properties to Artifacts
+
+It is possible to pass properties to an artifact specified in a plan. An example of this can be seen in the Admin Console plan where the context path to be used in the Admin console is passed from the plan.
+
+[source,xml]
+----
+<artifact type="bundle" name="org.eclipse.virgo.apps.admin.web" version="[3.0, 4.0)">
+ <property name="header:Web-ContextPath" value="/admin" />
+</artifact>
+----
+
+The only supported property is `header` which will overwrite the given manifest header with the supplied value. This should be used with care!
+
+anchor:developing-applications-plans-use[]
+
+==== Using the Plan
+
+Because a plan is a list of artifacts, rather than a physical file that contains the artifacts, there are a few additional steps you must perform before you deploy it to {virgo-name}.
+
+. Copy the artifacts that make up the plan to the `usr` repository, which by default is the `$SERVER_HOME/repository/usr` directory, where `$SERVER_HOME` refers to the top-level installation directory of {virgo-name}. Note that you might have configured the server differently; in which case, copy the artifacts to your custom repository directory.
+. Restart {virgo-name} if the repository used is not a *watched* repository.
+. After the server has started, either use the Admin Console to deploy the plan, or manually deploy it by copying the plan's XML file into the `$SERVER_HOME/pickup` directory.
+. This results in {virgo-name} deploying the plan.
+. To undeploy the plan, use the Admin Console, or simply delete it from the `$SERVER_HOME/pickup` directory.
+
+anchor:developing-applications-plans-scoping[]
+
+==== Plans and Scoping
+
+As described in previous sections, you can specify that a plan be *scoped*. This means that {virgo-name} installs the artifacts that make up the plan into a plan-specific scope so that only the application described by the plan has access to the artifacts. If you disable scoping, then {virgo-name} installs the artifacts into the global scope, which means they are available for access by all other deployed artifacts. This section describes scoping in a bit more detail. It also describes how you can change the default behavior of scoping, with respect to services, so that a service that is in a scope can be made globally available.
+
+If a bundle in a given scope imports a package and a bundle in the same scope exports the package, then the import may only be satisfied by the bundle in the scope, and not by any bundles outside the scope, including the global scope. Similarly, package exports from bundles in a scope are not visible to bundles in the global scope.
+
+If a bundle in a scope uses Spring DM (or the blueprint service) to obtain a service reference and a bundle in the same scope uses Spring DM (or the blueprint service) to publish a matching service, then the service reference may only bind to the service published in the scope (and not to any services outside the scope). Services published by bundles in a scope are not visible to bundles in the global scope.
+
+However, sometimes it is useful to make a service in a scope globally available to artifacts outside the scope. To do this, publish the service with the `org.eclipse.virgo.service.scope` service property set to `global`. Use the `<service-properties>` child element of `<service>`, as shown in the following example:
+
+[source,xml]
+----
+<service id="publishIntoGlobal" interface="java.lang.CharSequence">
+ <service-properties>
+ <beans:entry key="org.eclipse.virgo.service.scope" value="global" />
+ </service-properties>
+ <beans:bean class="java.lang.String">
+ <beans:constructor-arg value="foo"/>
+ </beans:bean>
+</service>
+----
+
+A scope forms a boundary for automatic propagation of load time weaving and bundle refresh.
+Additionally, a synthetic context bundle is generated for each scope. This bundle imports all the packages exported by other bundles in the scope.
+The class loader of the synthetic context bundle is used for thread context class loading. So,
+for example, hibernate will be able to load classes of any of the exported
+packages of the bundles in a scope using the thread context class loader.
+
+To ensure predictable class loading behaviour and avoid other issues associated with *split packages* (packages whose classes
+are split across more than one bundle), the synthetic context bundle has a restriction:
+no package may be exported by more than one
+bundle in the scope*.
+If this restriction is broken, the scoped application will fail to deploy.
+This restriction can cause problems for xref:scoping-and-substitutable-exports[substitutable exports].
+
+anchor:developing-applications-plans-scoping-webapps[]
+
+==== Web Applications and Scoping
+
+A Web Application Bundle (WAB) or WAR has its bundle class loader set as the TCCL, even when the WAB or WAR belongs to
+a PAR or scoped plan.
+To enable the TCCL to load classes of other bundles in the same scope as a WAB or WAR, use a WAB which imports the necessary packages.
+
+Also a WAB or WAR has its own per-application trace, independent of the per-application trace of any PAR or scoped plan to which the
+WAB or WAR belongs.
+
+
+anchor:developing-applications-configuration-artifacts[]
+
+=== Creating and Using Configuration Artifacts
+
+Applications typically include some sort of configuration data
+that might change depending on the environment in which the
+application is deployed. For example, if an application connects to a
+database server using JDBC, the configuration data would include the
+JDBC URL of the database server, the JDBC drvier, and the username and
+password that the application uses to connect to the database server.
+This information often changes as the application is deployed to
+different computers or the application moves from the testing phase to
+the production phase.
+
+{virgo-name} provides a feature called
+*configuration artifacts*
+that makes it very easy for you to manage this configuration data. A
+configuration artifact is simply a properties file that is made
+available at runtime using the OSGi
+`ConfigurationAdmin`
+service. When you create this properties file, you set the values of
+the properties for the specific environment in which you are going to
+deploy your application, and then update the metadata of your Spring
+application to use the properties file. You then deploy the
+application and properties file together, typically as a
+xref:developing-applications-plans[plan]. {virgo-name} automatically creates a configuration artifact from
+the properties file, and you can manage the lifecycle of this
+configuration artifact in the same way you manage the lifecycle of
+PARs, bundles, and plans, using the Admin
+Console. Additionally, {virgo-name} subscribes your
+application for notification of any refresh of the configuration
+artifact and the application can then adapt accordingly, which means
+you can easily
+*change*
+the configuration of your application without redeploying it.
+
+In sum, configuration artifacts, especially when combined with
+plans, provide an excellent mechanism for managing external
+configuration data for your applications.
+
+The following sections describe the format of the configuration
+artifact, how to update the Spring application context file of your
+application so that it knows about the configuration artifact, and
+finally how to include it in a plan alongside your application.
+
+As an example to illustrate the configuration artifact feature, assume
+that you have a Spring bean called
+`PropertiesController`
+whose constructor requires that four property values be passed to it,
+as shown in the following snippet of Java code:
+
+[source,java]
+----
+@Controller
+public class PropertiesController {
+
+ private final String driverClassName;
+ private final String url;
+ private final String username;
+ private final String password;
+
+ public PropertiesController(String driverClassName, String url, String username, String password) {
+ this.driverClassName = driverClassName;
+ this.url = url;
+ this.username = username;
+ this.password = password;
+}
+----
+
+In the preceding example, the `PropertiesController` constructor requires four property values: `driverClassName`, `url`, `username`, and `password`. Note that the example shows just one way that a class might require property values; your application may code it another way.
+
+Additionally, assume that the following snippet of the associated Spring application context XML file shows how the `PropertiesController` bean is configured:
+
+[source,xml]
+----
+<bean class="com.springsource.configuration.properties.PropertiesController">
+ <constructor-arg value="${driverClassName}"/>
+ <constructor-arg value="${url}"/>
+ <constructor-arg value="${username}"/>
+ <constructor-arg value="${password}"/>
+</bean>
+----
+
+The rest of this section describes how the bean can get these property values using a configuration artifact.
+
+anchor:developing-applications-configuration-artifacts-propfile[]
+
+==== Creating the Properties File
+
+To create a properties file that in turn will become a configuration artifact when deployed to {virgo-name} from which a Spring bean, such as the `PropertiesController` bean, will get the actual property values, follow these guidelines:
+
+* Create a text file in which each property is listed as a name/value pair, one pair per line. Precede comments with a `#`. For example:
+....
+# Properties for the com.springsource.configuration.properties sample
+
+driverClassName = org.w3.Driver
+url = http://www.springsource.com
+username = joe
+password = secret
+....
+
+The example shows four properties whose name correspond to the constructor arguments of the `PropertiesController` Spring bean.
+
+* Name the file anything you want, as long as it has a `.properties` extension, such as `app-properties.properties`.
+
+anchor:developing-applications-configuration-artifacts-app[]
+
+==== Updating Your Application
+
+To update your application so that it "knows" about the configuration artifact, you update the application's Spring application context XML file, typically located in the `WEB-INF` or `META-INF/spring` directories (read xref:using-spring[Using Spring and Gemini Blueprint]
+to understand which directory to use).
+
+You use the `<context:property-placeholder>` element to specify that you want to use the {virgo-name} mechanism for substituting values into bean properties. The `properties-ref` attribute of this element points to a `<osgi-compendium:cm-properties>` element which you use to specify the configuration artifact that contains the property values. You set the value of the `persistent-id` attribute of this element equal to the name of the configuration artifact, which is the name of the properties file *minus* the `.properties` extension.
+
+The following sample Spring application context XMl file shows everything wired together; only relevant parts of the file are shown:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:context="http://www.springframework.org/schema/context"
+ xmlns:osgi-compendium="http://www.springframework.org/schema/osgi-compendium"
+ xsi:schemaLocation="http://www.springframework.org/schema/osgi
+ http://www.springframework.org/schema/osgi/spring-osgi-1.2.xsd
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+ http://www.springframework.org/schema/context
+ http://www.springframework.org/schema/context/spring-context-2.5.xsd
+ http://www.springframework.org/schema/osgi-compendium
+ http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium-1.2.xsd">
+
+...
+
+ <bean class="com.springsource.configuration.properties.PropertiesController">
+ <constructor-arg value="${driverClassName}"/>
+ <constructor-arg value="${url}"/>
+ <constructor-arg value="${username}"/>
+ <constructor-arg value="${password}"/>
+ </bean>
+
+ <context:property-placeholder properties-ref="configAdminProperties"/>
+
+ <osgi-compendium:cm-properties id="configAdminProperties" persistent-id="app-properties"/>
+
+...
+
+</beans>
+----
+
+The preceding example shows how the id `configAdminProperites` wires the `<context:property-placeholder>` and `<osgi-compendium:cm-properties>` elements together. Based on the value of the `persistent-id` attribute, you must also deploy a properties file called `app-properties.properties` which {virgo-name} installs as a configuration artifact.
+
+anchor:developing-applications-configuration-artifacts-plan[]
+
+==== Adding the Configuration Artifact to a Plan
+
+Although you can always deploy your application and associated configuration artifact using the `pickup` directory, we recommends that you group the two together in a plan, add the two artifacts to the repository, and then deploy the plan using the `pickup` directory. The following sample plan includes the two artifacts:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<plan name="multi-artifact.plan" version="1.0.0"
+ scoped="false" atomic="false"
+ xmlns="http://www.eclipse.org/virgo/schema/plan"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.eclipse.org/virgo/schema/plan
+ http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
+
+ <artifact type="configuration" name="app-properties" version="0"/>
+ <artifact type="bundle" name="org.eclipse.virgo.configuration.properties" version="1.0.0"/>
+</plan>
+----
+
+For additional information about plans, see xref:developing-applications-plans[Creating Plans].
+
+anchor:using-spring[]
+
+=== Using Spring and Gemini Blueprint
+
+{virgo-name} supports the use of Spring framework and Gemini Blueprint by application bundles.
+
+Spring (and Gemini Blueprint) application context XML files should generally be placed in a bundle's `META-INF/spring` directory, but
+for a web application, these files must be placed in the `WEB-INF` directory.
+
+
+.A common mistake
+[TIP]
+--
+Placing a web application's Spring application context XML files in the `META-INF/spring` directory produces
+unpredictable results since Spring DM will attempt to build an application context independently of, and asynchronously from,
+the web application.
+--
+
+To use Gemini Blueprint from a web application, the `contextClass` servlet parameter and the servlet context listener
+should be configured (in `WEB-INF/web.xml`) like this:
+
+[source,xml]
+----
+<context-param>
+ <param-name>contextClass</param-name>
+ <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
+</context-param>
+
+<listener>
+ <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
+</listener>
+----
+
+{virgo-name} has Gemini Blueprint built-in and thereby supports the OSGi Blueprint standard in addition to Spring DM.
+
+For detailed information on Spring Framework and Blueprint, please see xref:prerequisites-references[].
+
+anchor:developing-applications-programmatic-access[]
+
+=== Programmatic Access to the Servlet Context
+
+This section describes how to programmatically access the servlet context to obtain the WebApplicationContext or the BundleContext.
+
+anchor:developing-applications-programmatic-access-web[]
+
+==== Programmatic Access to Web Features
+
+anchor:developing-applications-programmatic-access-web-application-context[]
+
+==== Programmatic Access to the WebApplicationContext
+
+The {tomcat-product-name} automatically creates a `WebApplicationContext`
+for Web Application Bundles and WAR files. When used in conjunction with an
+an auto-configured Spring MVC `DispatcherServlet`,
+there is generally no need to access the `WebApplicationContext`
+programmatically, since all components of the web application are configured
+within the scope of the `WebApplicationContext`
+itself. However, if you wish to access the `WebApplicationContext`
+you can do so via the web application's `ServletContext`.
+{virgo-name} stores the bundle's
+`WebApplicationContext` in the ServletContext under
+the attribute name "`BSN-ApplicationContext`", where
+`BSN` is the `Bundle-SymbolicName`
+of your WAR or Web Application Bundle.
+
+Alternatively, since {virgo-name} also stores the
+`WebApplicationContext` under the attribute name
+with the value of the `WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE`
+constant, you may choose to use Spring MVC's WebApplicationContextUtils'
+`getWebApplicationContext(servletContext)`
+or
+`getRequiredWebApplicationContext(servletContext)`
+methods to access the `WebApplicationContext` without providing
+an explicit attribute name.
+
+anchor:developing-applications-programmatic-access-web-bundle-context[]
+
+==== Programmatic Access to the BundleContext
+
+As required by the OSGi Web Applications specification, you can access the
+`BundleContext` of your WAR or Web Application Bundle via the web application's
+`ServletContext`. The bundle context is stored in the
+`ServletContext` under the attribute name `osgi-bundlecontext`.
+
+anchor:developing-applications-automatic-imports-web[]
+
+=== Web Application Manifest Processing
+{tomcat-product-name} generates automatic package imports (i.e., via the
+`Import-Package` manifest header) for certain web applications.
+This section lists which packages are automatically generated.
+
+{tomcat-product-name-short} supports Web Application Bundles (WABs) as defined by the OSGi Web Applications Specification and WAR files.
+A WAR will typically not contain any OSGi defined manifest headers.
+A WAB is distinguished from a WAR by the presence of one or more of the following OSGi defined headers:
+
+* `Bundle-SymbolicName`
+* `Bundle-Version`
+* `Bundle-ManifestVersion`
+* `Import-Package`
+* `Web-ContextPath`
+
+As required by the OSGi Web Applications specification, the following defaults are applied to a WAR:
+
+* `Bundle-ManifestVersion` is set to `2`
+* `Bundle-SymbolicName` is generated from the path from which the bundle was installed
+* `Bundle-ClassPath` is set to `WEB-INF/classes` followed by the JARs in
+`WEB-INF/lib` in an unspecified order, followed by any transitive dependencies declared
+by the JARs in `WEB-INF/lib`
+* `Import-Package` is extended in an implementation defined way, as described below
+
+The following packages are automatically imported into WARs:
+
+* `javax.servlet;version="2.5"`
+* `javax.servlet.http;version="2.5"`
+* `javax.servlet.jsp;version="2.1"`
+* `javax.servlet.jsp.el;version="2.1"`
+* `javax.servlet.jsp.tagext;version="2.1"`
+* `javax.el;version="1.0"`
+
+In addition to the above-described imports, {tomcat-product-name-short} will also
+generate automatic imports for all of the packages that are exported by the system
+bundle, unless an import for the package already exists in the WAR's manifest,
+or the WAR contains the package, i.e. within `WEB-INF/classes`,
+or in a jar file in `WEB-INF/lib`. When an import is generated, it
+is versioned such that it exactly matches the version or versions of the package that
+are exported from the system bundle. For example, a package that's exported only at
+version `1.0.0` will generate an import with a version of
+`[1.0.0,1.0.0]`, and a package that's exported at version
+`1.0.0` and version `2.0.0` will generate an import
+with a version of `[1.0.0,2.0.0]`.
+
+Web Application Bundles are not subject to the above manifest processing.
+This is a change of behaviour compared to Virgo Web Server 2.1.x.
+See (see xref:known-issues-web-bundle-default-headers[Default Web
+Application Bundle Headers]) if you need the old behaviour until you
+have changed your WABs to match the new behaviour.
+
+{tomcat-product-name-short} supports ROOT.war as a default web application. The `Web-ContextPath`
+of the deployed ROOT.war is set to the default web context path - `/`.
+
+.System Bundle Package Exports
+[TIP]
+--
+For further details on which packages are exported by the
+OSGi system bundle, consult the <filename>java-server.profile</filename>
+file located in the `SERVER_HOME/configuration` directory.
+--
+
+anchor:developing-applications-dependencies[]
+
+=== Working with Dependencies
+
+Complex enterprise frameworks such a Spring and Hibernate are typically divided into many, many different
+packages. Traditionally, if an OSGi bundle wished to make extensive use of such a framework its manifest would
+have to import a huge number of different packages. This can be an error-prone and tedious process. Furthermore,
+application developers are used to thinking in terms of their application using a framework, such as Spring, as a
+whole, rather than a long list of all the different packages that comprise the framework.
+
+The following figure provides a simple illustration of the complexity of only using `Import-Package`:
+
+image:import-package.png[]
+
+{virgo-name} reduces the need for long lists of imported packages by introducing two new manifest
+headers; `Import-Bundle` and `Import-Library`. The following figure provides an
+illustration of the simplification that these new headers offer:
+
+image:import-bundle_import-library.png[]
+
+As you can see, use of `Import-Bundle` and `Import-Library` can lead to a dramatic reduction
+in the number of imports that you need to include in an application bundle's manifest. Furthermore, `Import-Bundle`
+and `Import-Library` are simply aliases for `Import-Package`; at deployment time `Import-Bundle`
+and `Import-Library` header entries are automatically expanded into numerous `Import-Package` entries. This
+means that you retain the exact same semantics of using `Import-Package`, without having to go through the labourious
+process of doing so.
+
+anchor:developing-applications-importing-libraries[Importing Libraries]
+
+==== Importing Libraries
+
+A bundle in an application can declare a dependency on a library by using the
+{umbrella-virgo-name} specific `Import-Library` header. This header specifies a
+comma-separated list of library symbolic names and version ranges that determine which libraries
+are imported. By default a dependency on a library is mandatory but this can be
+controlled through use of the resolution directive in exactly the same way as
+it can with `Import-Package`.
+
+[source,txt]
+----
+Import-Library: org.springframework.spring;version="[2.5.4, 3.0)",
+ org.aspectj;version="[1.6.0,1.6.0]";resolution:="optional"
+----
+
+This example `Import-Library` header declares a mandatory dependency on the Spring
+library at a version from 2.5.4 inclusive to 3.0 exclusive. It also declares an
+optional dependency on the AspectJ library at exactly 1.6.0.
+
+anchor:developing-applications-importing-bundles
+
+==== Importing Bundles
+
+A bundle in an application can declare a dependency on a bundle by using the
+{umbrella-virgo-name} specific `Import-Bundle` header. The header specifies a comma-separated
+list of bundle symbolic names, version ranges, and scope declarmations that determine which bundles are imported and the scope of their dependency. By default a dependency
+on a bundle is mandatory but this can be controlled through use of the resolution directive in exactly
+the same way as it can with `Import-Package`.
+
+[source,txt]
+----
+Import-Bundle: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi, 1.2.2.osgi]"
+----
+
+This example `Import-Bundle` header declares a mandatory dependency on the Apache Commons
+DBCP bundle at exactly 1.2.2.osgi.
+
+anchor:developing-applications-importing-bundles-disadvantages[]
+
+===== Disadvantages
+
+A disadvantage of using `Import-Bundle` or especially `Import-Library`, is that the application
+bundle has a greater apparent fan-out than it strictly needs. An Alternative is to use a tool such as bnd or Bundlor
+to generate the package imports of the bundle.
+
+anchor:developing-applications-scoping-libraries-bundles[]
+
+==== Scoping Bundles in an Application
+
+When working with a scoped application, such as a PAR file or a plan, you might run into a situation where one of the bundles in the application (call it `bundleA`) depends on another bundle (`bundleB`) that performs a runtime task (such as class generation) that a third bundle (`bundleC`) might need to know about, although `bundleC` does not explicitly depend on `bundleB`.
+
+For example, Hibernate uses CGLIB (code generation library) at runtime to generate proxies for persistent classes. Assume that a domain bundle in your application uses Hibernate for its persistent objects, and thus its `Import-Bundle` manifest header includes the Hibernate bundle. Further assume that a separate Web bundle uses reflection in its data-binding code, and thus needs to reflect on the persistent classes generated by Hibernate at runtime. The Web bundle now has an indirect dependency on the Hibernate bundle because of these dynamically generated classes, although the Web bundle does not typically care about the details of how these classes are persisted. One way to solve this dependency problem is to explicitly add the Hibernate bundle to the `Import-Bundle` header of the Web bundle; however, this type of explicit-specified dependency breaks the modularity of the application and is not a programming best practice.
+
+A better way to solve this problem is to specify that {virgo-name} itself dynamically import
+the bundle (Hibernate in the example above) to all bundles in the application at runtime.
+You do this by adding the `import-scope:=application` directive to the `Import-Bundle` header
+of the bundle that has the direct dependency (the domain bundle in our example). At runtime, although the Web bundle
+does not explicitly import the Hibernate bundle, {virgo-name} implicitly imports it and thus its classes are available
+to the Web bundle. This mechanism allows you to declare the dependencies you need to make your application run,
+without having to make changes to your application that might limit its flexibility.
+
+The following example shows how to use the `import-scope` directive with the `Import-Bundle` header:
+
+[source,txt]
+----
+Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";import-scope:=application
+----
+
+You can also set the `import-scope` directive to the (default) value `bundle`; in this case, the scope of the bundle is just the bundle itself and thus {virgo-name} does not perform any implicit importing into other bundles of the application.
+
+Note that use of the `import-scope:=application` directive of the `Import-Bundle` header only makes sense when the bundle is part of a scoped application (PAR or plan); if the bundle is not part of a scoped application, then this directive has no effect.
+
+Finally, because `import-scope:=application` implicitly adds a bundle import to each bundle of the PAR or plan, the impact of subsequently refreshing the imported bundle is, in general, broader than it would have been if you had not used `import-scope:=application`. This may well affect the performance of refresh.
+
+anchor:developing-applications-defining-libraries[Defining Libraries]
+
+==== Defining Libraries
+
+Libraries are defined in a simple text file, typically with a `.libd` suffix. This file identifies the
+library and lists all of its constituent bundles. For example, the following is the library definition for
+Spring 2.5.4:
+
+[source,txt]
+----
+Library-SymbolicName: org.springframework.spring
+Library-Version: 2.5.4
+Library-Name: Spring Framework
+Import-Bundle: org.springframework.core;version="[2.5.4,2.5.5)",
+ org.springframework.beans;version="[2.5.4,2.5.5)",
+ org.springframework.context;version="[2.5.4,2.5.5)",
+ org.springframework.aop;version="[2.5.4,2.5.5)",
+ org.springframework.web;version="[2.5.4,2.5.5)",
+ org.springframework.web.servlet;version="[2.5.4,2.5.5)",
+ org.springframework.jdbc;version="[2.5.4,2.5.5)",
+ org.springframework.orm;version="[2.5.4,2.5.5)",
+ org.springframework.transaction;version="[2.5.4,2.5.5)",
+ org.springframework.context.support;version="[2.5.4,2.5.5)",
+ org.springframework.aspects;version="[2.5.4,2.5.5)",
+ com.springsource.org.aopalliance;version="1.0"
+----
+
+The following table lists all of the headers that may be used in a library definition:
+
+anchor:developing-applications-defining-libraries-library-headers-table[]
+
+[options="header",cols="2,5"]
+.Library definition headers
+|=======================================================================
+| Header | Description
+| Library-SymbolicName | Identifier for the library
+| Library-Version | Version number for the library
+| Import-Bundle | A comma separated list of bundle symbolic names.
+ Each entry may optionally specify a version (using the `version=` directive)
+ and the scope of the import (using the `import-scope` directive).
+| Library-Name | Optional. The human-readable name of the library
+| Library-Description | Optional. A human-readable description of the library
+|=======================================================================
+
+anchor:developing-applications-installing-dependencies[]
+
+==== Installing Dependencies
+
+Rather than encouraging the packaging of all an application's dependencies within the application itself, {virgo-name}
+uses a local provisioning repository of bundles and libraries upon which an application can depend. When the {virgo-name}
+encounters an application with a particular dependency, it will automatically provide, from its provisioning repository,
+the appropriate bundle or library.
+
+Making a dependency available for provisioning is simply a matter of copying it to the appropriate location in the
+{virgo-name}'s local provisioning repository. By default this is
+`SERVER_HOME/repository/usr`. A more detailed discussion of the provisioning
+repository can be found in the {user-guide}.
+
+anchor:developing-applications-application-trace[]
+
+=== Application Trace
+
+As described in the {user-guide} {virgo-name} provides support for
+per-application trace for PARs, scoped Plans and WABs. {virgo-name} provides SLF4J with Logback logging for Event Logging and Tracing.
+Application trace is configured in the `serviceability.xml` file.
+See the {user-guide} for more details.
+
+anchor:developing-applications-versioning[]
+
+=== Application Versioning
+
+In much the same way that individual OSGi bundles can be versioned, {virgo-name} allows applications to be versioned. How exactly you do this depends on how you have packaged the application:
+
+* If you package your application using a PAR, you version the application by using the `Application-Version` header in the `MANIFEST.MF` file of the PAR file.
+* If you use a plan to describe the artifacts that make up your application, you version it by using the `version` attribute of the `<plan>` root element of the plan's XML file.
+* If your application consists of a single bundle, you version it in the standard OSGi way: by using the `Bundle-Version` header of the `MANIFEST.MF` file of the bundle.
+
+{virgo-name} uses an application's version to prevent clashes when multiple versions of the same application are deployed at
+the same time. For example, the application trace support described in xref:developing-applications-application-trace[Application Trace],
+includes the application's name and version in the file path. This ensures that each version of the same application has its
+own trace or logging file.
+
diff --git a/programmer-guide/src/docs/asciidoc/formtags-case-study.adoc b/programmer-guide/src/docs/asciidoc/formtags-case-study.adoc
new file mode 100644
index 0000000..b2313f3
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/formtags-case-study.adoc
@@ -0,0 +1,985 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:formtags-case-study[Case Study: Migrating the Form Tags Sample Application]
+
+== Case Study: Migrating the Form Tags Sample Application
+
+Migrating Form Tags
+
+In this chapter we will walk through the steps needed to migrate the
+Form Tags sample application from a standard Java EE WAR to a fully
+OSGi compliant *Shared Services WAR* within a PAR.
+The migration involves four packaging and deployment formats:
+
+. xref:formtags-case-study-war[Standard WAR]
+. xref:formtags-case-study-war-shared-libs[Shared Libraries WAR]
+. xref:formtags-case-study-war-shared-services[Shared Services WAR]
+. xref:formtags-case-study-par[PAR with a shared services WAR]
+
+Each of these migration steps will produce a web application
+that can be deployed and run on the {tomcat-product-name-short}.
+
+After summarising the process, an example `plan`
+is shown which is another way of packaging and deploying the application.
+
+The following image displays the directory structure you should have
+after installing the Form Tags sample. Note however that the release
+tag will typically resemble `3.0.0.RELEASE`.
+
+image:formtags-case-study-sample-layout.png[]
+
+The `dist` directory contains the distributables,
+and the `projects` directory contains the source code and build scripts.
+
+For simplicity, this chapter will focus on the distributables—which
+are built using Virgo-Build rather than on configuring a project in an IDE.
+
+[TIP]
+--
+Pre-packaged distributables are made available in the `dist` directory;
+however, if you would like to modify the samples or build
+them from scratch, you may do so using Virgo-Build. Take a look at
+the `README.TXT` file in each of the folders under the `projects`
+directory in the Form Tags sample for instructions.
+--
+
+anchor:formtags-case-study-introduction[]
+
+=== Overview of the Form Tags Sample Application
+
+The sample that we will be using is the Form Tags show case
+sample
+which was provided with Spring 2.0. The Form Tags application
+has
+been removed from the official Spring 2.5.x distributions;
+however,
+since it is relatively simple but still contains enough
+ingredients
+to demonstrate the various considerations required during
+a migration,
+we have chosen to use it for these examples.
+
+The purpose of the Form Tags show case sample was to demonstrate how
+the Spring specific
+`form:`
+tags, released
+in Spring 2.0, make view development with JSPs and tag
+libraries easier.
+The Form Tags application consists of a single
+`UserService`
+which returns a list
+of
+`Users`
+. Furthermore, the application demonstrates how to list, view,
+and
+edit
+`Users`
+in a simple Spring MVC based web application using JSP
+and JSTL.
+
+anchor:formtags-case-study-war[]
+
+=== Form Tags WAR
+
+We begin with a standard WAR deployment.
+
+[NOTE]
+--
+The {tomcat-product-name-short} supports the standard Java EE WAR
+packaging
+and deployment format as a first-class citizen, and there
+are many
+benefits to deploying a standard WAR file on the
+{tomcat-product-name-short} including,
+but not limited to: tooling
+support, runtime error diagnostics, FFDC
+(first failure data
+capture), etc.
+In addition, support for standard WAR deployment
+provides an easy on-ramp
+for trying out the
+{tomcat-product-name-short} with existing web applications.
+--
+
+The following screen shot displays the directory structure of the
+Form Tags application using the standard WAR format. As you can see,
+there is no deviation from the standard structure and layout, and as
+you would expect, all of the web application's third-party
+dependencies
+(for example: Spring, Commons Logging) are packaged as
+JARs in
+`WEB-INF/lib`
+.
+
+image:formtags-case-study-exploded-war.png[]
+
+To deploy this application, simply copy
+`dist/formtags-war-3.0.0.*.war`
+to
+the
+`SERVER_HOME/pickup`
+directory for hot deployment.
+
+You should then see the {tomcat-product-name-short} produce
+console output similar to the following:
+
+[NOTE]
+--
+The console output has been reformatted to fit this document.
+--
+
+[source,txt]
+----
+[2009-07-01 14:54:45.135] fs-watcher
+ <SPDE0048I> Processing 'CREATED' event for file 'formtags-war-3.0.0.RELEASE.war'.
+[2009-07-01 14:54:45.797] fs-watcher
+ <SPDE0010I> Deployment of 'formtags-war-3.0.0.RELEASE.war' version '0' completed.
+[2009-07-01 14:54:45.797] Thread-20
+ <SPWE0000I> Starting web bundle '/formtags-war-3.0.0.RELEASE'.
+[2009-07-01 14:54:46.380] Thread-20
+ <SPWE0001I> Started web bundle '/formtags-war-3.0.0.RELEASE'.
+----
+
+Navigate to
+`http://localhost:8080/`
+plus the web application context path,
+which in the above case is
+`formtags-war-3.0.0.RELEASE`
+. Thus navigating to
+`http://localhost:8080/formtags-war-3.0.0.RELEASE`
+should render the sample application's welcome page, as
+displayed in the screen
+shot below.
+
+[TIP]
+--
+For WARs, the default web context path is the name of the WAR file
+without the
+`.war`
+extension. You can optionally
+specify a context path using the
+`Web-ContextPath`
+bundle
+manifest header, which will be described in further detail
+later.
+--
+
+image:formtags-case-study-war-webpage.png[]
+
+anchor:formtags-case-study-war-shared-libs[]
+
+=== Form Tags Shared Libraries WAR
+
+As mentioned above, a standard WAR file typically packages of all its
+required
+dependencies in
+`WEB-INF/lib`
+. The servlet container will
+then add all of the JARs in
+`WEB-INF/lib`
+to the application's
+classpath.
+
+The first step of the migration towards benefiting from an OSGi
+container is to retrieve the dependencies from the
+{tomcat-product-name-short}'s bundle
+repository at runtime. This
+can significantly reduce the time it takes to build
+and deploy the
+application. It also enables the enforcement of policies
+regarding the
+use of third-party libraries.
+
+The way in which dependencies are declared in an OSGi environment is
+via manifest headers in a bundle's
+`/META-INF/MANIFEST.MF`
+.
+As mentioned in xref:developing-applications[], there are
+three ways of expressing dependencies:
+`Import-Package`,
+`Import-Bundle` and
+`Import-Library`.
+
+The Form Tags application uses JSTL standard tag libraries.
+Thus, you
+need to choose a JSTL provider, for example the
+Apache implementation
+which comes with the {tomcat-product-name-short}. To use the
+Apache
+implementation of JSTL, you need to express your dependency
+as
+outlined in the following manifest listing.
+Because it is a single
+bundle,
+`Import-Bundle`
+is
+the simplest and therefore preferred manifest header to use.
+
+The Form Tags application requires commons-logging and Spring.
+It
+would be very painful to have to list all the Spring packages one by
+one.
+Equally, considering the number of bundles that make up the
+Spring framework, it would be verbose to list each bundle. Therefore
+`Import-Library`
+is the preferred approach
+for expressing the dependency on the Spring
+framework.
+
+[TIP]
+--
+How do you determine the name of a library definition provided
+by the {tomcat-product-name}? Use the {ebr}.
+--
+
+Examine the
+`/META-INF/MANIFEST.MF`
+in
+`/dist/formtags-shared-libs-*.war`:
+
+[source,txt]
+----
+Manifest-Version: 1.0
+Ant-Version: Apache Ant 1.7.0
+Created-By: 1.5.0_13-119 (Apple Inc.)
+Bundle-ManifestVersion: 2
+Bundle-SymbolicName: org.springframework.showcase.formtags-shared-libs
+Import-Library: org.springframework.spring;version="[3.0.0,4.0.0)"
+Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1
+ .1.2"
+----
+
+You can see the
+`Import-Library`
+and
+`Import-Bundle`
+directives that instruct the {tomcat-product-name-short} to add the
+appropriate package imports to the bundle
+classpath used by this WAR file.
+
+Deploying the shared libraries WAR onto the
+{tomcat-product-name-short} should result
+in console output similar to
+the following:
+
+[NOTE]
+--
+The console output has been reformatted to fit this document.
+--
+
+[source,txt]
+----
+[2009-07-01 15:00:14.953] fs-watcher
+ <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-libs-3.0.0.RELEASE.war'.
+[2009-07-01 15:00:15.363] fs-watcher
+ <SPDE0010I> Deployment of 'org.springframework.showcase.formtags_shared_libs' version '2' completed.
+[2009-07-01 15:00:15.364] Thread-20
+ <SPWE0000I> Starting web bundle '/formtags-shared-libs-3.0.0.RELEASE'.
+[2009-07-01 15:00:15.816] Thread-20
+ <SPWE0001I> Started web bundle '/formtags-shared-libs-3.0.0.RELEASE'.
+----
+
+Navigating to
+`http://localhost:8080/formtags-shared-libs-BUILDTAG
+`
+should render the welcome page. Note that for the pre-packaged
+distributable,
+the
+`BUILDTAG`
+should be similar to
+`3.0.0.RELEASE`
+;
+whereas, for a local build the
+`-BUILDTAG`
+may be completely
+omitted. Please consult the console output,
+web-based admin console, or log
+to determine the exact context path
+under which the web application has been deployed.
+
+anchor:formtags-case-study-war-shared-services[]
+
+=== Form Tags Shared Services WAR
+
+The next step in the migration is to deploy the services as a
+separate
+OSGi bundle which the WAR then references.
+The Form Tags
+sample has a single service
+`UserManager`.
+
+This scenario has two separate deployables, the
+`service`
+bundle and the WAR file.
+The following image shows the two separate
+source trees:
+
+image:formtags-case-study-shared-services-eclipse.png[]
+
+[NOTE]
+--
+Note that the WAR does not contain the
+`.domain`
+or
+`.service`
+packages as these will be imported from the separate service bundle.
+--
+
+anchor:formtags-case-study-war-shared-services-service[]
+
+==== The Service Bundle
+
+The responsibility of the first bundle (
+`formtags-shared-services-service`
+)
+is to provide the API of the formtags service. This includes both
+the
+domain and the service API. In the same way that imports are
+defined
+in the
+`/META-INF/MANIFEST.MF`
+, so are exports.
+The following is the
+`/META-INF/MANIFEST.MF`
+listing from the service bundle.
+
+[source,txt]
+----
+Manifest-Version: 1.0
+Ant-Version: Apache Ant 1.7.0
+Created-By: 1.5.0_13-119 (Apple Inc.)
+Bundle-ManifestVersion: 2
+Bundle-Name: FormTags Service (and implementation)
+Bundle-SymbolicName: org.springframework.showcase.formtags.service-shared-services
+Export-Package: org.springframework.showcase.formtags.service,org.spri
+ ngframework.showcase.formtags.domain
+Import-Library: org.springframework.spring;version="[3.0.0,4.0.0)"
+----
+
+The symbolic name of this bundle is
+`org.springframework.showcase.formtags.service-shared-services`.
+Note that the name of the bundle typically describes the package that the bundle primarily exports.
+If you take a look at the `repository/bundles/ext` in the {tomcat-product-name-short}
+directory, you'll see that
+names are almost always indicative of the contents of the bundle.
+For this example, however, we have also appended
+"`-shared-services`"
+in order to avoid possible clashes with other bundle symbolic
+names.
+You will see later that the PAR also contains a service
+bundle.
+
+[NOTE]
+--
+In OSGi, the combination of
+`Bundle-SymbolicName`
+and
+`Bundle-Version`
+is used to uniquely identify
+a bundle within the OSGi container.
+Furthermore, when you deploy
+a bundle to the {tomcat-product-name},
+for example via the
+`pickup`
+directory, a bundle's filename is also used to uniquely
+identify it for
+the purpose of supporting
+*hot deployment*
+via
+the file system.
+--
+
+As well as exporting types (i.e. the domain classes and service
+API), the service bundle also publishes an implementation of the
+`UserManager`
+. The actual implementation is
+`StubUserManager`
+; however, that should remain an
+implementation detail of this
+bundle.
+
+The fact that this bundle publishes a service is not captured in
+the
+`/META-INF/MANIFEST.MF`
+, as it is a Gemini Blueprint concept.
+The following image is of
+`src/main/resources/spring`.
+
+image:formtags-case-study-shared-services-service-resources.png[]
+
+As you can see there are two Spring configuration files:
+`module-context.xml`
+and
+`osgi-context.xml`.
+
+[TIP]
+--
+These names are abitrary; however, they follow an informal
+convention:
+`module-context.xml`
+typically bootstraps the Spring context
+(usually delegating to
+smaller fine grained context files inside another directory),
+whilst
+`osgi-context.xml`
+contains all the OSGi service exports and references.
+--
+
+The following is a listing of
+`module-context.xml`
+.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
+
+ <bean id="userManager"
+ class="org.springframework.showcase.formtags.service.internal.StubUserManager"/>
+
+</beans>
+----
+
+As you can see, this simply defines a bean called
+`userManager`
+.
+The following is a listing of
+`osgi-context.xml`.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<beans:beans
+ xmlns="http://www.springframework.org/schema/osgi"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:beans="http://www.springframework.org/schema/beans"
+ xsi:schemaLocation="http://www.springframework.org/schema/osgi
+ http://www.springframework.org/schema/osgi/spring-osgi.xsd
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans.xsd">
+
+ <service ref="userManager"
+ interface="org.springframework.showcase.formtags.service.UserManager"/>
+
+</beans:beans>
+----
+
+This single bean definition exports the
+`userManager`
+defined in
+`module-context.xml`
+to the
+OSGi service registry and makes it available under the public
+`org.springframework.showcase.formtags.service.UserManager
+`
+API.
+
+The service bundle should now be ready to deploy on the
+{tomcat-product-name-short}.
+So copy
+`/dist/formtags-shared-services-services*`
+to the
+`SERVER_HOME/pickup`
+directory.
+Output similar to the following should appear in the
+{tomcat-product-name-short}'s console:
+
+[NOTE]
+--
+The console output has been reformatted to fit this document.
+--
+
+[source,txt]
+----
+[2009-07-01 15:05:03.511] fs-watcher
+ <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-services-service-2.0.0.RELEASE.jar'.
+[2009-07-01 15:05:03.688] fs-watcher
+ <SPDE0010I> Deployment of 'org.springframework.showcase.formtags.service_shared_services' version '2.0.0.RELEASE' completed.
+----
+
+anchor:formtags-case-study-war-shared-services-war[]
+
+==== Accessing the Service and Types from the WAR
+
+The WAR file now needs to access the types and service exported
+by
+the service bundle. The following listing is the WAR's
+`/META-INF/MANIFEST.MF`
+which imports the types
+exported by the service bundle. The
+`Import-Bundle`
+statement has also been extended to import
+`org.springframework.osgi.core`
+,
+which is necessary in order to load an OSGi-enabled
+`WebApplicationContext`
+.
+
+[source,txt]
+----
+Manifest-Version: 1.0
+Ant-Version: Apache Ant 1.7.0
+Created-By: 1.5.0_13-119 (Apple Inc.)
+Bundle-ManifestVersion: 2
+Bundle-SymbolicName: org.springframework.showcase.formtags.web-shared-
+ services
+Import-Package: org.springframework.showcase.formtags.domain,org.sprin
+ gframework.showcase.formtags.service, org.eclipse.virgo.web.dm;version="[1.0,2.1)"
+Import-Library: org.springframework.spring;version="[2.5.4,3.1.0)"
+Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1
+ .1.2",org.springframework.osgi.core
+----
+
+In addition to importing the exported types of the service bundle,
+the WAR must also obtain a reference to the
+`UserManager`
+published by the service bundle. The following image shows the
+directory
+structure of the Shared Services WAR.
+
+image:formtags-case-study-shared-services-war-resources.png[]
+
+As you can see in the above image, the Form Tags Shared Services
+WAR's
+`/WEB-INF/web.xml`
+directory contains a standard
+`web.xml`
+deployment descriptor,
+`applicationContext.xml`
+which defines the configuration
+for the
+*root*
+`WebApplicationContext`
+, and
+`formtags-servlet.xml`
+which defines the configuration specific to the
+configured
+*formtags*
+`DispatcherServlet`
+.
+
+As is typical for Spring MVC based web applications, you configure a
+`ContextLoaderListener`
+in
+`web.xml`
+to load your root
+`WebApplicationContext`
+; however, to enable your
+`WebApplicationContext`
+to be able to reference services from the OSGi Service Registry,
+you
+must explicitly set the
+`contextClass`
+Servlet context parameter to the fully qualified
+class name of a
+`ConfigurableWebApplicationContext`
+which is OSGi-enabled. When deploying
+Shared Services WARs to the
+{tomcat-product-name}, you should use
+`org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext`.
+This will then enable the use of Gemini Blueprint's `<reference ... />`
+within your root `WebApplicationContext` (i.e., in `applicationContext.xml`).
+The following listing is an excerpt from `/WEB-INF/web.xml`.
+
+[source,xml]
+----
+<context-param>
+ <param-name>contextClass</param-name>
+ <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
+</context-param>
+
+<listener>
+ <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
+</listener>
+----
+
+The Form Tags Shared Services WAR contains a
+`/WEB-INF/applicationContext.xml`
+file which is the default configuration location used to create the
+*root*
+`WebApplicationContext`
+for Spring MVC's
+`ContextLoaderListener`.
+
+[NOTE]
+--
+As already mentioned, in the OSGi world, bundle configuration
+takes
+place in the root
+`/META-INF/`
+directory.
+Typically Gemini Blueprint powered configuration files will live
+there as well (e.g., in
+`/META-INF/spring/*.xml`
+).
+In a WAR, however, the root
+`WebApplicationContext`
+loaded by
+`ContextLoaderListener`
+and the
+`DispatcherServlet's`
+application context typically live in
+`/WEB-INF/`.
+--
+
+The following is the listing of the WAR's
+`/WEB-INF/applicationContext.xml`.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<beans:beans
+ xmlns="http://www.springframework.org/schema/osgi"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:beans="http://www.springframework.org/schema/beans"
+ xsi:schemaLocation="http://www.springframework.org/schema/osgi
+ http://www.springframework.org/schema/osgi/spring-osgi.xsd
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans.xsd">
+
+ <reference id="userManager"
+ interface="org.springframework.showcase.formtags.service.UserManager"/>
+
+</beans:beans>
+----
+
+The single bean declaration is retrieving a service that implements
+the
+`org.springframework.showcase.formtags.service.UserManager
+`
+API from the OSGi Service Registry.
+
+[TIP]
+--
+You might have been expecting a reference to the service bundle,
+but that isn't how OSGi works. OSGi provides a service
+registry, and this bean definition is accessing a service in that
+registry that meets the specified restriction (i.e. implements
+the
+specified interface). This leads to a very loosely coupled
+programming model: the WAR really doesn't care where the
+implementation
+comes from.
+--
+
+[TIP]
+--
+What happens if there is no service at runtime?
+What if there are
+multiple services that match the criteria?
+Gemini Blueprint provides a lot
+of configuration options, including
+whether or not the reference is
+*mandatory*
+,
+how long to wait for a service reference, etc. Please consult the
+{gemini-blueprint-guide} for further information.
+--
+
+One of the benefits of programming to interfaces is that you
+are
+decoupled from the actual implementation; Gemini Blueprint provides a
+proxy. This
+has enormous benefits including the ability to
+dynamically refresh individual bundles without
+cascading that
+refresh to unrelated bundles.
+
+To deploy the WAR, copy
+`/dist/formtags-shared-services-war*`
+to the
+`SERVER_HOME/pickup`
+directory.
+You should then see console output similar to the
+following:
+
+[NOTE]
+--
+The console output has been reformatted to fit this document.
+--
+
+[source,txt]
+[2009-07-01 15:09:19.819] fs-watcher
+ <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-services-war-3.0.0.RELEASE.war'.
+[2009-07-01 15:09:20.167] fs-watcher
+ <SPDE0010I> Deployment of 'org.springframework.showcase.formtags.web_shared_services' version '3' completed.
+[2009-07-01 15:09:20.168] Thread-20
+ <SPWE0000I> Starting web bundle '/formtags-shared-services-war-3.0.0.RELEASE'.
+[2009-07-01 15:09:20.647] Thread-20
+ <SPWE0001I> Started web bundle '/formtags-shared-services-war-3.0.0.RELEASE'.
+----
+
+Navigating to the appropriate link should render the welcome page.
+
+anchor:formtags-case-study-par[]
+
+=== Form Tags PAR
+
+The final step in the migration is that of a full blown
+OSGi
+application with web support. The {tomcat-product-name} introduces a
+new packaging and deployment format: the PAR.
+
+A PAR is a standard JAR with a "`.par`"
+file extension which contains all of the modules of your
+application (e.g., service, domain, and infrastructure bundles
+as well
+as a WAR for web applications) in a single deployment unit.
+Moreover,
+a PAR defines both a physical and logical application boundary.
+
+The PAR sample is comprised of four directories, as shown below.
+
+image:formtags-case-study-par-sample.png[]
+
+
+The
+`formtags-par`
+directory is a build project that
+understands how to create the PAR
+from its constituent bundles.
+
+anchor:formtags-case-study-par-granularity[]
+
+==== Granularity of the PAR
+
+Achieving the appropriate level of granularity for your OSGi
+application is more of an art than a science. It helps to look
+at the
+different requirements:
+
+[options="header",cols="2,3"]
+.Granularity drivers
+|=======================================================================
+| Requirement | Description
+| Domain/Technical Layering | Applications can be split either by domain (i.e.,
+ by use case or
+ *vertically*
+ ) or
+ by their technical layers (i.e.,
+ *horizontally*
+ ).
+ Since the Form Tags application essentially has only
+ a single
+ use case, the bundles are split by technical layering
+ (i.e.,
+ domain, service, and web).
+| Refreshability | A major benefit of OSGi is that of refreshability: if one
+ bundle
+ is changed, only bundles that have a dependency upon
+ the
+ exported types need to be refreshed. This has a high impact
+ on
+ development time costs as well as production
+ costs. However,
+ this can lead to lots of smaller, fine grained
+ bundles. An
+ example of this granularity would be to
+ separate out the service
+ API and implementation into two different
+ bundles. This means
+ that a change in the implementation
+ wouldn't require any
+ other bundles to be refreshed.
+|=======================================================================
+
+Ultimately the right level of granularity will depend upon your
+particular application and team.
+
+anchor:formtags-case-study-par-domain-and-service[]
+
+==== Domain and Service Bundles
+
+The service bundle is identical (except for the
+`Bundle-SymbolicName`
+) to that
+in the shared-services variation of the sample.
+The PAR has
+also separated out the domain classes into their own bundle.
+When
+layering by technical considerations, it is again
+somewhat of an
+unofficial convention to have a
+`.domain`
+bundle.
+
+anchor:formtags-case-study-par-par[]
+
+=== Constructing the PAR
+
+Finally we need to construct the PAR itself.
+The following are
+the contents of the exploded PAR.
+
+image:formtags-case-study-par-exploded.png[]
+
+You can see that the PAR itself doesn't contain any
+resources or
+Java classes: it simply packages together a related set
+of bundles
+as a single, logical unit.
+
+The PAR does however, contain its own
+`/META-INF/MANIFEST.MF`.
+
+[source,txt]
+----
+Manifest-Version: 1.0
+Application-SymbolicName: org.springframework.showcase.formtags-par
+Application-Version: 3.0.0
+Application-Name: FormTags Showcase Application (PAR)
+----
+
+For more information on the contents of the PAR's
+`/META-INF/MANIFEST.MF`
+, please consult xref:developing-applications[].
+
+You can now deploy the PAR on the {tomcat-product-name-short}, for
+example by copying
+`/dist/formtags-par*.par`
+to the {tomcat-product-name-short}'s
+`pickup`
+directory.
+You should then see console output similar to the
+following:
+
+[NOTE]
+--
+The console output has been reformatted to fit this document.
+--
+
+[source,txt]
+----
+[2009-07-01 15:13:43.306] fs-watcher
+ <SPDE0048I> Processing 'CREATED' event for file 'formtags-par-2.0.0.RELEASE.par'.
+[2009-07-01 15:13:44.060] fs-watcher
+ <SPDE0010I> Deployment of 'formtags-par' version '2.0.0.RELEASE' completed.
+[2009-07-01 15:13:44.068] Thread-20
+ <SPWE0000I> Starting web bundle '/formtags-par'.
+[2009-07-01 15:13:45.212] Thread-20
+ <SPWE0001I> Started web bundle '/formtags-par'.
+----
+
+Navigate to http://localhost:8080/formtags-par to see the welcome page.
+
+[TIP]
+--
+Note that the web application's context path is explicitly
+defined via the
+`Web-ContextPath`
+manifest header in
+`/META-INF/MANIFEST.MF`
+of the Web application bundle within the PAR.
+--
+
+anchor:formtags-case-study-summary[]
+
+=== Summary of the Form Tags Migration
+
+The {tomcat-product-name} provides out-of-the-box support for
+deploying
+standard Java EE WAR files. In addition support for
+*Shared Libraries*
+and
+*Shared Services*
+WAR formats provides a logical migration path away from standard,
+monolithic WARs toward OSGi-enable Web applications. The PAR
+packaging
+and deployment format enables truly fine-grained,
+loosely-coupled, and
+efficient application development. In general,
+the migration steps
+presented in this chapter are fairly
+straightforward, but developers
+should set aside time for some
+up-front design of the bundles themselves.
+
+It is recommended that you take another sample application or
+indeed your own small application and go through this migration
+process yourself. This will help you better understand the concepts
+and
+principles at work. In addition, it is highly recommended that you
+familiarize yourself with the extensive Eclipse IDE support provided
+by the Virgo Tools. See the Virgo Tools Guide for more on that.
+
+anchor:formtags-case-study-as-plan[]
+
+=== Form Tags as a Plan
+
+Plans (see xref:developing-applications-plans[])
+allow us to package and deploy the Form Tags application in a more
+flexible way.
+Instead of packaging all the bundles of the application
+into a single PAR file, each bundle can be placed in the repository
+and referred to in a *plan*.
+
+The bundles to be placed in a repository in the chain (for example,
+`repository/usr`) are:
+
+[source,txt]
+----
+org.springframework.showcase.formtags.domain-2.0.0.RELEASE.jar
+org.springframework.showcase.formtags.service-2.0.0.RELEASE.jar
+org.springframework.showcase.formtags.web-2.0.0.RELEASE.war
+----
+
+which are just those files which were part of the PAR.
+
+Here is the contents of a suitable plan file for the Form Tags
+example:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<plan name="formtags.plan" version="2.0.0" scoped="true" atomic="true"
+ xmlns="http://www.eclipse.org/virgo/schema/plan"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.eclipse.org/virgo/schema/plan
+ http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
+
+ <artifact type="bundle" name="org.springframework.showcase.formtags.domain_par" version="[3.0,3.1)"/>
+ <artifact type="bundle" name="org.springframework.showcase.formtags.service_par" version="[3.0,3.1)"/>
+ <artifact type="bundle" name="org.springframework.showcase.formtags.web_par" version="[3.0,3.1)"/>
+
+</plan>
+----
+
+where we have chosen to use any of the artifacts in the version range [2.0,2.1).
+This plan (as a file called, for example, `formtags.plan`)
+can be deployed in any of the normal ways (for example, dropped in the `pickup` directory).
+
+When the plan is deployed, the artifacts it references are
+installed from the repository and deployed in the order given in the
+plan file.
+Because this plan is scoped and atomic, the collection is
+given an application scope and is started and stopped as a single
+unit.
+
diff --git a/programmer-guide/src/docs/asciidoc/introduction.adoc b/programmer-guide/src/docs/asciidoc/introduction.adoc
new file mode 100644
index 0000000..2d57c11
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/introduction.adoc
@@ -0,0 +1,198 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-${version}/docs/virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+== Introduction to the {tomcat-product-name}
+
+=== Overview
+
+In this chapter, we provide an overview of the {tomcat-product-name} focusing
+on what it is, what benefits it provides to developers and administrators,
+and why you should use it.
+
+anchor:introduction-what[]
+
+=== What is the {tomcat-product-name}?
+
+The {tomcat-product-name}, or {tomcat-product-name-short} for short, is the runtime portion of the {umbrella-virgo-name}.
+It is a lightweight, modular, OSGi-based runtime that provides a complete packaged solution for developing,
+deploying, and managing enterprise applications.
+By leveraging several best-of-breed technologies and improving upon
+them, the {tomcat-product-name-short} offers a compelling solution to develop and deploy
+enterprise applications.
+
+anchor:introduction-constituents[]
+
+==== What Makes up the {tomcat-product-name}?
+
+The {tomcat-product-name} is built on top of the following core technologies:
+
+* https://projects.spring.io/spring-framework/[Spring Framework], obviously!
+* http://tomcat.apache.org/[Tomcat] as the web container.
+* http://www.osgi.org/Specifications/HomePage[OSGi R4.3].
+* http://www.eclipse.org/equinox/[Equinox] as the OSGi implementation.
+* https://eclipse.org/gemini/blueprint/[Gemini Blueprint] for working with OSGi in a Spring application.
+* {tooling-guide} for developing applications.
+
+Note, however, that the {tomcat-product-name} isn't just a combination
+of these technologies. Rather, it integrates and extends these
+technologies to provide many features essential for developing,
+deploying, and managing today's enterprise Java applications.
+
+The following diagram presents a high-level overview of the {tomcat-product-name-short}'s architecture.
+
+image:introduction-architecture.png[]
+
+At the heart of the {tomcat-product-name} is the {kernel-product-name} or {kernel-product-name-short}.
+The {kernel-product-name-short} is an OSGi-based kernel that takes full advantage of the modularity
+and versioning of the OSGi platform. The {kernel-product-name-short} builds on a base version of {nano-product-name} or {nano-product-name-short} and extends its capabilities for
+provisioning and library management, as well as providing core functionality for the {tomcat-product-name-short}. The {nano-product-name-short} maintains a minimal
+runtime footprint and startup time. It builds on top of a pure Equinox, extending it with more sophisticated diagnostics and supportability functionality.
+The {nano-product-name-short} supports full p2 provisioning. This feature is not included in the Virgo Nano Base that the {kernel-product-name-short} is built on.
+
+To maintain a minimal runtime footprint, OSGi bundles are installed on demand by the
+{nano-product-name-short}. On subsequent restarts these core bundles are warm-started thus reducing the startup time. This allows for an application to be installed
+into a running {tomcat-product-name-short} and for its dependencies to be satisfied from an external repository. Not only
+does this remove the need to manually install all your application dependencies, which would be tedious, but it also keeps memory usage to a minimum.
+
+As shown in the figure, {kernel-product-name-short} runs on top of {nano-product-name-short} that extends Equinox within a standard Java
+Virtual Machine. Above the {kernel-product-name-short} further layers contribute functionality
+to the {tomcat-product-name-short}. Such as management and web application support.
+
+Version {version} of the {tomcat-product-name} supports *bundle*,
+*plan*, *PAR*, *configuration*,
+*Web Application Bundle (WAB)*, and *WAR* artifacts, which enable
+you to build sophisticated web applications. This includes support for
+standard Java EE WARs, "shared library" WARs, and "shared services" WARs, each of
+which will be covered in greater detail in xref:architecture[].
+
+[IMPORTANT]
+--
+The {nano-product-name} has a different provisioning system which isn't included in the Virgo Nano Base on which the
+{kernel-product-name-short} and the {tomcat-product-name-short} are built.
+--
+
+Version {version} of the {nano-product-name} supports *bundle*,
+*p2 feature*, *Web Application Bundle (WAB)*, and *WAR* artifacts, which enable
+you to build sophisticated web applications too, taking full advantage of p2's dependency resolution, automated download and fail-early mechanics.
+The {nano-product-name} does NOT support *plan*, *PAR* or *configuration* artifacts.
+New *features* are provisioned via *update sites* or *p2 repositories*.
+Brief overview of p2 and it's mechanics is available on http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/[this blog].
+The {nano-product-name-short}'s default web container implementation is Gemini Web.
+
+anchor:introduction-why[]
+
+=== Why the {tomcat-product-name}?
+
+You could deploy a web application in a stand-alone servlet engine or application server.
+Or you could even deploy directly in an OSGi container such as Equinox. However,
+deploying in the {tomcat-product-name} offers a number of key benefits that make it both more
+appealing and more suitable for enterprise application development.
+
+anchor:introduction-unified-deployment[]
+
+==== Deployment Options and Migration Paths
+
+While many applications deployed in the {tomcat-product-name} will take advantage
+of OSGi capabilities, not all applications need such sophistication.
+For example, development teams may initially choose to continue packaging
+existing web applications as standard WAR files and then gradually migrate
+toward a fully OSGi-based packaging and deployment model. The {tomcat-product-name}
+makes such migrations easy for developers by supporting multiple packaging
+and deployment formats. These formats and migration strategies are discussed
+in greater detail in xref:migrating-to-osgi[] and
+xref:formtags-case-study[].
+
+anchor:introduction-simplified-deployment[]
+
+==== Simplified Development and Deployment of OSGi-based Applications
+
+Prior to the release of the {tomcat-product-name}, developing and deploying OSGi
+applications involved inherent complexity such as:
+
+* *Obtaining OSGi bundles for popular Java libraries:*
+For optimal benefits, every technology you use in an OSGi application must
+be packaged as OSGi bundles. Sometimes, this involves manually converting
+JAR files into bundles and making sure that any libraries needed by those
+bundles are also available as OSGi bundles. The {ebr} is a good source of
+popular pre-bundled libraries.
+
+* *Package management complexity:*
+OSGi bundles use other bundles through `Import-Package` manifest headers.
+Many applications use a set of common technologies (e.g., an ORM solution,
+a web framework, etc.). Combining these two characteristics leads to duplicated
+configuration in the form of repeated and verbose `Import-Package` statements.
+
+* *Lack of application-level isolation:*
+In OSGi everything is a bundle, and all bundles share the same OSGi Service Registry.
+To highlight how conflicts can arise between applications and their services in this
+shared service registry, consider the following scenarios.
+
+** Application `A` is comprised of bundles `B` and `C`.
+In a standard OSGi environment, if you attempt to install two instances of the same
+version of application `A` (i.e., two sets of bundles `B` and
+`C`), a clash will occur, because you cannot deploy multiple bundles with
+the same `Bundle-SymbolicName` and `Bundle-Version` combination.
+
+** Application `A1` is comprised of bundles `B1` and `C1`.
+Similarly, application `A2` is comprised of bundles `B2` and `C2`.
+Each bundle has a unique combination of `Bundle-SymbolicName` and `Bundle-Version`.
+Bundles `B1` and `B2` both export service `S` which
+is imported by both `C1` and `C2`. In contrast to the previous
+example, there is no conflict resulting from duplicate
+`Bundle-SymbolicName`/`Bundle-Version` combinations; however,
+there is a clash for the exported service `S`.
+Which service `S` will bundles `C1` and `C2` end up
+using once they are installed?
+Assuming bundles `B1` and `C1` are intended to work together,
+you would not want bundle `C1` to get a reference to service `S`
+from bundle `B2`, because it is installed in a different logical application.
+On the contrary, you typically want bundle `C1` to get a reference to
+service `S` exported by bundle `B1`, but in a standard OSGi environment
+this may not be the case.
+
+Furthermore, since standard OSGi does not define a notion of an application as a set of bundles,
+you cannot deploy or undeploy an application and its constituent bundles as a single unit.
+
+The {tomcat-product-name} introduces a number of features to solve these issues:
+
+* A full set of OSGi bundles for many popular Java libraries to get you
+started quickly with creating OSGi applications.
+* An OSGi library concept that obviates the need to
+duplicate verbose `Import-Package` statements.
+* The PAR packaging format which offers
+application-level isolation and deployment.
+* The concept of a plan, which is an XML file that lists a collection of bundles that {tomcat-product-name} should load together as a single application. Conceptually, plans are very like PARs, except that a plan describes the contents of the application rather than a PAR that actually contains them.
+
+anchor:introduction-diagnostics[]
+
+==== Enhanced Diagnostics During Deployment and in Production
+
+Identifying why an application won't deploy or which particular library
+dependencies are unsatisfied is the cause of many headaches!
+Similarly, production time errors that don't identify the root cause are
+all too familiar to Java developers. The {tomcat-product-name-short} was designed from the
+ground up to enable tracing and First Failure Data Capture (FFDC) that
+empower developers with precise information at the point of failure to
+fix the problem quickly.
+
diff --git a/programmer-guide/src/docs/asciidoc/known-issues.adoc b/programmer-guide/src/docs/asciidoc/known-issues.adoc
new file mode 100644
index 0000000..ba37069
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/known-issues.adoc
@@ -0,0 +1,139 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:known-issues[]
+
+== Known Issues
+
+anchor:known-issues-jpa[]
+
+=== JPA Entity Scanning
+
+Classpath scanning for JPA entities annotated with `@Entity` does
+not work. Describing entities with `@Entity` will work, but the
+entities need to be listed explicitly.
+
+anchor:known.issues.proxy[]
+
+=== `ClassNotFoundError` When Creating a Proxy
+
+When creating proxies at runtime, there are circumstances where `ClassNotFoundErrors`
+can be generated. These errors happen because the proxy creating bundle does not have visibility into every
+type on the interface of the proxy. You can either put in import statements for all the relevant types or
+add use a service (with visibility of all pertinent types) to create the proxy. Please see
+http://www.osgi.org/blog/2008/08/classy-solutions-to-tricky-proxies.html[this blog entry]
+for more details.
+
+anchor:known.issues.cglib[]
+
+=== Creating proxies with CGLIB for Package Protected Types
+
+In traditional Java EE applications user types are loaded by the same `ClassLoader` as
+CGLIB. This allows CGLIB to proxy package-protected types. In OSGi environments, user types and CGLIB will
+most likely be packaged in separate bundles. This results in the user types and CGLIB being loaded by
+different `ClassLoaders`. This prevents CGLIB from proxying any package-protected types.
+
+The workaround for this issue is to make all types that require proxying public.
+
+anchor:known-issues-jetty-restrictions[]
+
+=== {jetty-product-name} Restrictions
+
+The following Jetty features are not supported.
+
+* Tag Libraries other than the standard Apache Tag Library.
+
+anchor:known-issues-web-bundle-default-headers[]
+
+=== Default Web Application Bundle Headers
+
+The Gemini Web container conforms to the OSGi Web Applications specification and does not apply default values
+to the headers of a Web Application Bundle. However, SpringSource dm Server 2.0.x applies default values
+to certain headers (see xref:developing-applications-automatic-imports-web[Web Application Manifest
+Processing] for details) and so Virgo Web Server 2.1.x modified the behaviour of Gemini Web so that it applied default
+values consistently with dm Server 2.0.x.
+
+This behaviour is changed as of {tomcat-product-name} 3.0. {tomcat-product-name-short} now conforms strictly to the
+OSGi Web Applications specification.
+
+As a migration aid, *which may not be supported in a future release*, users may configure the {tomcat-product-name-short} Web Integration
+Layer to apply default values to the headers of a Web Application Bundle.
+See "Configuring the Web Integration Layer" in the {user-guide} for details.
+
+anchor:hibernate-resolution-issue[]
+
+=== Hibernate Resolution Issue
+
+Applications using Hibernate 3.4.0.GA need to upgrade the JBoss Hibernate Entity manager fragment bundle to version 3.4.0.GA-A.
+The symptoms are that the application will fail to resolve due to missing imports of packages such as `org.hibernate.ejb.transaction`
+and JBoss Hibernate Annotations `com.springsource.org.hibernate.annotations`.
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=335174[bug 335174] for details.
+
+The JBoss Hibernate Entity manager fragment bundle `com.springsource.org.hibernate.ejb` v3.4.0.GA in the
+http://ebr.springsource.com/repository/app/[SpringSource Enterprise Bundle Repository]
+depends on the package `org.slf4j` with a version range that excludes the version of the
+package provided with Virgo. The net effect is that Hibernate EJB fragment bundle fails to attach to its host
+`com.springsource.org.hibernate` and the host then does not export the packages the application
+may need, such as `org.hibernate.ejb.transaction`.
+
+An updated JBoss Hibernate Entity manager fragment and JBoss Hibernate Annotations with versions 3.4.0.GA-A which fixes this
+problem is available from the http://ebr.springsource.com/repository/app/[SpringSource Enterprise Bundle Repository].
+
+anchor:scoping-and-substitutable-exports[]
+
+=== Scoping and Substitutable Exports
+
+The restriction described in xref:developing-applications-plans-scoping[Plans and Scoping] that
+no package may be exported by more than one bundle in a given scope can cause problems for bundles with
+*substitutable exports*. A substitutable export is a package which is exported and imported
+by the same bundle. The OSGi framework will discard either the import or the export of the package when the
+bundle is resolved.
+
+However, if more than one bundle in a scope has a substitutable export of the same package, then Virgo will fail
+to deploy the scoped application because the above restriction appears to be broken. Virgo could only spot that
+the restriction was not actually being broken by second guessing the resolution behaviour of the OSGi framework,
+something that Virgo generally avoids because of the fragility of that approach.
+
+It may be possible to work around this issue by omitting one of the bundles containing the substitutable export
+from the scoped application.
+
+It may also be possible to work around this issue by moving the bundles containing the substitutable exports outside the scope,
+although this will not give correct behaviour if the bundles' exported packages need to be available for thread
+context class loading.
+
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=330643[bug 330643] for an example of this issue.
+
+anchor:eclipselink-resolution-issue[]
+
+=== EclipseLink Resolution Issue
+
+Applications using EclipseLink may fail to resolve if the `osgi.enterprise` bundle is allowed to
+wire its `javax.persistence` package import to other than the EclipseLink `javax.persistence` bundle.
+
+To avoid this, install EclipseLink's `javax.persistence` bundle early. To install this bundle before
+any applications are deployed, list the bundle in the `initialArtifacts` property described in the
+{user-guide}.
+
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=337826[bug 337826] for details.
+
diff --git a/programmer-guide/src/docs/asciidoc/migrating-to-osgi.adoc b/programmer-guide/src/docs/asciidoc/migrating-to-osgi.adoc
new file mode 100644
index 0000000..c26c20d
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/migrating-to-osgi.adoc
@@ -0,0 +1,146 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:migrating-to-osgi[Migrating to OSGi]
+
+== Migrating to OSGi
+
+Taking on a new technology such as OSGi may seem a bit daunting at first,
+but a proven set of migration steps can help ease the journey. Teams
+wishing to migrate existing applications to run on the {tomcat-product-name}
+will find that their applications typically fall into one of the following
+categories.
+
+* *Web Application*: for web applications,
+this chapter provides an overview of the steps required to migrate
+from a Standard WAR to a Shared Services WAR. Furthermore, the following
+chapter provides a detailed case study involving the migration
+of the Spring 3.0 Form Tags show case application.
+* *Anything else*: for any other type
+of application, you will typically either deploy your application
+as multiple individual bundles, as a single PAR file, or as a plan,
+which is the recommended approach for deploying applications on
+the {tomcat-product-name}. See xref:migrating-to-osgi-par-plan[Migrating to a Plan or a PAR] for details.
+
+anchor:migrating-to-osgi-web[]
+
+=== Migrating Web Applications
+
+Many applications may start with the standard WAR format for web applications and
+gradually migrate to a more OSGi-oriented architecture. Since the {tomcat-product-name}
+offers several benefits to all supported deployment formats, it provides a smooth
+migration path. Of course, depending on your application's complexity and your
+experience with OSGi, you may choose to start immediately with an OSGi-based
+architecture.
+
+
+anchor:migrating-to-osgi-web-standard-war[]
+
+==== Standard WAR
+
+If you are not yet familiar with OSGi or simply want to deploy an existing web application on the {tomcat-product-name},
+you can deploy a standard WAR and leverage the {tomcat-product-name-short} with a minimal learning curve. In fact reading the
+{user-guide}
+is pretty much all that you need to do to get started. Furthermore, you will gain
+familiarity with the {tomcat-product-name}, while preparing to take advantage of the other formats.
+
+anchor:migrating-to-osgi-web-shared-libraries-war[]
+
+==== Shared Libraries WAR
+
+The *Shared Libraries WAR*
+format is the first step to reaping the benefits of OSGi. In this phase, you dip your toes into OSGi-based dependency
+management by removing JAR files from the WAR and declaring dependencies on corresponding OSGi bundles.
+
+anchor:migrating-to-osgi-web-shared-services-war[]
+
+==== Shared Services WAR
+
+In this phase, you take the next step toward a fully OSGi-based architecture by separating your web artifacts
+(e.g., Servlets, Controllers, etc.) from the services they depend on.
+
+anchor:migrating-to-osgi-web-summary[]
+
+==== Web Migration Summary
+
+The following diagram graphically depicts the migration path from a Standard WAR to a Shared Services WAR.
+As you can see, the libraries (*libs*) move from within the deployment artifact
+to the Bundle Repository.
+Similarly, the services move from within the WAR to external bundles and are accessed via the
+OSGi Service Registry. In addition, the overall footprint of the deployment artifact decreases
+as you move towards a Shared Services WAR.
+image:migration-path-war-to-shsrv.png[]
+
+anchor:migrating-to-osgi-par-plan[]
+
+=== Migrating to a Plan or a PAR
+
+The first steps to migrating an existing application to a plan or a PAR are the same: deciding on the bundles that make up the application and ensuring that their `Import-Package`, `Import-Library`, and `Import-Bundle` manifest headers are correct. Once you have the list of bundles that make up your application, you then decide whether you want to JAR them all into a single application file (PAR) or create a plan that simply lists the bundles by reference. Creating a plan is the recommend way to create an application, although PARs also have benefits that might suit your needs better, as described in xref:migrating-to-osgi-parplan-decide[].
+
+anchor:migrating-to-osgi-parplan-bundles[]
+
+==== Creating the Application Bundles
+
+When migrating an existing application to the PAR packaging and deployment format or a plan,
+you consider modularity as the prime objective. Following the ideas discussed in
+xref:architecture-forming-bundles[], you refactor the application into multiple bundles.
+You may start conservatively with a small number of bundles and then further refactor those bundles.
+
+If the original code is crafted following good software practices such as separation of concerns and use of
+well-defined interfaces, migration may involve modifying only configuration and packaging. In other words,
+your Java sources will remain unchanged. Even configuration is likely to change only slightly.
+
+For example, the following diagram depicts a typical web application that has been refactored and
+packaged as a PAR. The blue elements within the *Application* box constitute
+the bundles of the application. Each of these bundles imports types from other bundles within
+the PAR using `Import-Package`. The green elements in the left column represent
+*libraries* installed on the {tomcat-product-name-short}. The PAR's bundles reference these
+libraries using `Import-Library`. The purple element in the left column
+represents a bundle within the {tomcat-product-name-short}'s bundle repository which is imported by the DAO
+bundle using `Import-Bundle`. In contrast to a traditional, monolithic
+WAR deployment, the PAR format provides both a logical and physical application boundary
+and simultaneously allows the application to benefit from both the OSGi container and the {tomcat-product-name}.
+image:migrating-to-osgi-par-structure.png[]
+
+anchor:migrating-to-osgi-parplan-decide[Plan or PAR?]
+
+==== Plan or PAR?
+
+Once you have refactored your existing application into separate OSGi bundles, you then must decide whether to package the bundles into a single PAR file or create a plan that lists the bundles by reference. As described in more detail in preceding sections of this guides, PARs and plans have similar benefits, such as:
+
+* Scoping
+* Atomicity, or the ability to deploy and control the bundles as a single unit
+* Versioning
+* Improved serviceability
+
+Plans, the method most recommended by us to create your application, has the following added benefits:
+
+* Guaranteed order of deployment, based on the order in which they are listed in the plan's XML file
+* Ease of sharing content between plans and updating individual plans without having to physically repackage, due to the artifacts being listed by reference.
+* Ability to disable scoping and atomicity, if desired.
+
+The main benefit of PARS is that, because they physically contain all the required artifacts, you know exactly what bundles are deployed when you deploy the PAR file, in contrast to plans that allow content to be substituted or lost.
+
+For details about creating plans and PARs, see xref:developing-applications-plans[] and xref:developing-applications-packaging[], respectively.
+
diff --git a/programmer-guide/src/docs/asciidoc/preface.adoc b/programmer-guide/src/docs/asciidoc/preface.adoc
new file mode 100644
index 0000000..cb83177
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/preface.adoc
@@ -0,0 +1,61 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-${version}/docs/virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+== Preface
+
+Increasing complexity in modern enterprise applications is a fact of life.
+Developers not only have to deal with complex business logic, but also a myriad
+of other concerns such as security, auditing, exposing business
+functionality to external applications, and managing the evolution of
+these concerns. The Spring Framework addresses these
+needs by offering a Plain-Old Java Object (POJO) based solution that
+lets you focus on your business logic.
+
+Complex applications pose problems that go beyond using the right set of
+technologies. You need to take into account other considerations such as
+a simplified development process, easy deployment, monitoring deployed
+applications, and managing changes in response to changing business needs.
+This is where the {umbrella-virgo-name} comes into play. It offers a simple yet
+comprehensive platform to develop, deploy, and service enterprise
+applications. In this Programmer Guide, we explore the runtime portions of the
+{umbrella-virgo-name}, the {tomcat-product-name}, {jetty-product-name} and the
+{kernel-product-name}, and learn how to develop applications to benefit from their
+capabilities.
+
+.For {kernel-product-name} Programmers
+[NOTE]
+--
+Although this guide is written primarily for {tomcat-product-name} programmers, much of it is also useful for
+{kernel-product-name} programmers who should simply ignore the web-related sections.
+--
+
+.For {nano-product-name} Programmers
+[NOTE]
+--
+This guide is written primarily for {tomcat-product-name} programmers. Although a base version of {nano-product-name}, without the new provisioning
+system, is used to build the {tomcat-product-name}, much of this guide does not apply to {nano-product-name}. The {nano-product-name-short} lacks regions support but has much
+improved runtime footprint and startup time and also provides support for p2 provisioning. The {nano-product-name} features are covered better in the
+{user-guide}.
+--
+
diff --git a/programmer-guide/src/docs/asciidoc/prerequisites.adoc b/programmer-guide/src/docs/asciidoc/prerequisites.adoc
new file mode 100644
index 0000000..ddfab4b
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/prerequisites.adoc
@@ -0,0 +1,41 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-{version}/docs/virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:prerequisites-references[Prerequisites]
+
+== Prerequisites
+
+=== Runtime Environment
+{virgo-name} requires Java SE 7 or later to be installed. Java is available from
+http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle] and elsewhere.
+
+=== References
+
+To make effective use of the {tomcat-product-name}, you should also refer to the following:
+
+* {user-guide}
+* {tooling-guide}
+* https://www.osgi.org/developer/specifications/[Blueprint Container Specification](in the OSGi 4.2 and 5.0 Enterprise Specifications)
+* https://docs.spring.io/spring/docs/{spring-framework-version}/spring-framework-reference/[Spring Framework {spring-framework-version} Reference Documentation]
+
diff --git a/programmer-guide/src/docs/asciidoc/virgo-programmer-guide.adoc b/programmer-guide/src/docs/asciidoc/virgo-programmer-guide.adoc
new file mode 100644
index 0000000..555436e
--- /dev/null
+++ b/programmer-guide/src/docs/asciidoc/virgo-programmer-guide.adoc
@@ -0,0 +1,61 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-{version}/docs/virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+:experimental: true
+:toc-placement: manual
+:toc:
+
+= {virgo-name} Programmer Guide
+
+[%hardbreaks]
+Ramnivas Laddad
+Colin Yates
+Sam Brannen
+Rob Harrop
+Christian Dupuis
+Andy Wilkinson
+Glyn Normington
+Steve Powell
+Christopher Frost
+Florian Waibel
+
+image::virgo-logo-small.png[Eclipse Virgo,float="right"]
+
+[%hardbreaks]
+{umbrella-virgo-name}
+{version}
+Copyright (C) 2009, 2011 VMware Inc. and others
+
+'''
+
+toc::[]
+
+include::preface.adoc[]
+include::prerequisites.adoc[]
+include::introduction.adoc[]
+include::architecture.adoc[]
+include::developing-applications.adoc[]
+include::migrating-to-osgi.adoc[]
+include::formtags-case-study.adoc[]
+include::common-libraries.adoc[]
+include::known-issues.adoc[]
diff --git a/programmer-guide/src/formtags-case-study.xml b/programmer-guide/src/formtags-case-study.xml
deleted file mode 100644
index d387c69..0000000
--- a/programmer-guide/src/formtags-case-study.xml
+++ /dev/null
@@ -1,1069 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="formtags-case-study">
- <title>Case Study: Migrating the Form Tags Sample Application</title>
- <titleabbrev>Migrating Form Tags</titleabbrev>
- <para>
- In this chapter we will walk through the steps needed to migrate the
- Form Tags sample application from a standard Java EE WAR to a fully
- OSGi
- compliant
- <emphasis>Shared Services WAR</emphasis>
- within a PAR.
- The migration involves four packaging and deployment
- formats:
- <orderedlist>
- <listitem>
- <para>
- <link linkend="formtags-case-study-war">Standard WAR</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="formtags-case-study-war-shared-libs">Shared Libraries WAR</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="formtags-case-study-war-shared-services">Shared Services WAR</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="formtags-case-study-par">PAR with a shared services WAR</link>
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- Each of these migration steps will produce a web application
- that
- can be deployed and run on the @tomcat.product.name.short@.
- </para>
- <para>
- After summarising the process, an example
- <literal>plan</literal>
- is shown which is another way of
- packaging and deploying the application.
- </para>
- <para>
- The following image displays the directory structure you should have
- after installing the Form Tags sample. Note however that the release
- tag
- will typically resemble
- <literal>3.0.0.RELEASE</literal>
- .
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-sample-layout.png"
- format="PNG" />
- </para>
- <para>
- The
- <literal>dist</literal>
- directory contains the distributables,
- and the
- <literal>projects</literal>
- directory contains the source code
- and build scripts.
- </para>
- <para>
- For simplicity, this chapter will focus on the distributables—which
- are built using Virgo-Build
- rather than on configuring a project in an
- IDE.
- <tip>
- Pre-packaged distributables are made available in the
- <literal>dist</literal>
- directory;
- however, if you would like to modify the samples or build
- them from scratch, you may
- do so using Virgo-Build. Take a look at
- the
- <literal>README.TXT</literal>
- file in each of the folders under
- the
- <literal>projects</literal>
- directory in the
- Form Tags sample for instructions.
- </tip>
- </para>
- <section id="formtags-case-study-introduction">
- <title>Overview of the Form Tags Sample Application</title>
- <para>
- The sample that we will be using is the Form Tags show case
- sample
- which was provided with Spring 2.0. The Form Tags application
- has
- been removed from the official Spring 2.5.x distributions;
- however,
- since it is relatively simple but still contains enough
- ingredients
- to demonstrate the various considerations required during
- a migration,
- we have chosen to use it for these examples.
- </para>
- <para>
- The purpose of the Form Tags show case sample was to demonstrate how
- the Spring specific
- <literal>form:</literal>
- tags, released
- in Spring 2.0, make view development with JSPs and tag
- libraries easier.
- The Form Tags application consists of a single
- <literal>UserService</literal>
- which returns a list
- of
- <literal>Users</literal>
- . Furthermore, the application demonstrates how to list, view,
- and
- edit
- <literal>Users</literal>
- in a simple Spring MVC based web application using JSP
- and JSTL.
- </para>
- </section>
-
- <section id="formtags-case-study-war">
- <title>Form Tags WAR</title>
- <para>
- We begin with a standard WAR deployment.
- <note>
- The @tomcat.product.name.short@ supports the standard Java EE WAR
- packaging
- and deployment format as a first-class citizen, and there
- are many
- benefits to deploying a standard WAR file on the
- @tomcat.product.name.short@ including,
- but not limited to: tooling
- support, runtime error diagnostics, FFDC
- (first failure data
- capture), etc.
- In addition, support for standard WAR deployment
- provides an easy on-ramp
- for trying out the
- @tomcat.product.name.short@ with existing web applications.
- </note>
- </para>
- <para>
- The following screen shot displays the directory structure of the
- Form Tags application using the standard WAR format. As you can see,
- there is no deviation from the standard structure and layout, and as
- you would expect, all of the web application’s third-party
- dependencies
- (for example: Spring, Commons Logging) are packaged as
- JARs in
- <literal>WEB-INF/lib</literal>
- .
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-exploded-war.png"
- format="PNG" />
- </para>
- <para>
- To deploy this application, simply copy
- <literal>dist/formtags-war-3.0.0.*.war</literal>
- to
- the
- <literal>SERVER_HOME/pickup</literal>
- directory for hot deployment.
- </para>
- <para>
- You should then see the @tomcat.product.name.short@ produce
- console output similar to the following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.
- </para>
- </note>
- <programlisting>
-[2009-07-01 14:54:45.135] fs-watcher
- <SPDE0048I> Processing 'CREATED' event for file 'formtags-war-3.0.0.RELEASE.war'.
-[2009-07-01 14:54:45.797] fs-watcher
- <SPDE0010I> Deployment of 'formtags-war-3.0.0.RELEASE.war' version '0' completed.
-[2009-07-01 14:54:45.797] Thread-20
- <SPWE0000I> Starting web bundle '/formtags-war-3.0.0.RELEASE'.
-[2009-07-01 14:54:46.380] Thread-20
- <SPWE0001I> Started web bundle '/formtags-war-3.0.0.RELEASE'.
-</programlisting>
- <para>
- Navigate to
- <literal>http://localhost:8080/</literal>
- plus the web application context path,
- which in the above case is
- <literal>formtags-war-3.0.0.RELEASE</literal>
- . Thus navigating to
- <literal>http://localhost:8080/formtags-war-3.0.0.RELEASE</literal>
- should render the sample application’s welcome page, as
- displayed in the screen
- shot below.
- <tip>
- For WARs, the default web context path is the name of the WAR file
- without the
- <literal>.war</literal>
- extension. You can optionally
- specify a context path using the
- <literal>Web-ContextPath</literal>
- bundle
- manifest header, which will be described in further detail
- later.
- </tip>
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-war-webpage.png"
- format="PNG" />
- </para>
- </section>
-
- <section id="formtags-case-study-war-shared-libs">
- <title>Form Tags Shared Libraries WAR</title>
- <para>
- As mentioned above, a standard WAR file typically packages of all its
- required
- dependencies in
- <literal>WEB-INF/lib</literal>
- . The servlet container will
- then add all of the JARs in
- <literal>WEB-INF/lib</literal>
- to the application’s
- classpath.
- </para>
- <para>
- The first step of the migration towards benefiting from an OSGi
- container is to retrieve the dependencies from the
- @tomcat.product.name.short@’s bundle
- repository at runtime. This
- can significantly reduce the time it takes to build
- and deploy the
- application. It also enables the enforcement of policies
- regarding the
- use of third-party libraries.
- </para>
- <para>
- The way in which dependencies are declared in an OSGi environment is
- via manifest headers in a bundle’s
- <literal>/META-INF/MANIFEST.MF</literal>
- .
- As mentioned in
- <xref linkend="developing-applications" />
- , there are
- three ways of expressing dependencies:
- <literal>Import-Package</literal>
- ,
- <literal>Import-Bundle</literal>
- and
- <literal>Import-Library</literal>
- .
- </para>
- <para>
- The Form Tags application uses JSTL standard tag libraries.
- Thus, you
- need to choose a JSTL provider, for example the
- Apache implementation
- which comes with the @tomcat.product.name.short@. To use the
- Apache
- implementation of JSTL, you need to express your dependency
- as
- outlined in the following manifest listing.
- Because it is a single
- bundle,
- <literal>Import-Bundle</literal>
- is
- the simplest and therefore preferred manifest header to use.
- </para>
- <para>
- The Form Tags application requires commons-logging and Spring.
- It
- would be very painful to have to list all the Spring packages one by
- one.
- Equally, considering the number of bundles that make up the
- Spring framework, it would be verbose to list each bundle. Therefore
- <literal>Import-Library</literal>
- is the preferred approach
- for expressing the dependency on the Spring
- framework.
- </para>
- <tip>
- <para>
- How do you determine the name of a library definition provided
- by the
- @tomcat.product.name@?
- Use the
- <ulink url="http://www.springsource.com/repository">@ebr@</ulink>
- .
- </para>
- </tip>
- <para>
- Examine the
- <literal>/META-INF/MANIFEST.MF</literal>
- in
- <literal>/dist/formtags-shared-libs-*.war</literal>
- :
- <programlisting>
-Manifest-Version: 1.0
-Ant-Version: Apache Ant 1.7.0
-Created-By: 1.5.0_13-119 (Apple Inc.)
-Bundle-ManifestVersion: 2
-Bundle-SymbolicName: org.springframework.showcase.formtags-shared-libs
-<emphasis role="bold">Import-Library</emphasis>: org.springframework.spring;version="[3.0.0,4.0.0)"
-<emphasis role="bold">Import-Bundle</emphasis>: com.springsource.org.apache.taglibs.standard;version="1
- .1.2"
-</programlisting>
- You can see the
- <literal>Import-Library</literal>
- and
- <literal>Import-Bundle</literal>
- directives that instruct the @tomcat.product.name.short@ to add the
- appropriate package imports to the bundle
- classpath used by this WAR file.
- </para>
- <para>
- Deploying the shared libraries WAR onto the
- @tomcat.product.name.short@ should result
- in console output similar to
- the following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.
- </para>
- </note>
- <programlisting>
-[2009-07-01 15:00:14.953] fs-watcher
- <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-libs-3.0.0.RELEASE.war'.
-[2009-07-01 15:00:15.363] fs-watcher
- <SPDE0010I> Deployment of 'org.springframework.showcase.formtags_shared_libs' version '2' completed.
-[2009-07-01 15:00:15.364] Thread-20
- <SPWE0000I> Starting web bundle '/formtags-shared-libs-3.0.0.RELEASE'.
-[2009-07-01 15:00:15.816] Thread-20
- <SPWE0001I> Started web bundle '/formtags-shared-libs-3.0.0.RELEASE'.
-</programlisting>
- <para>
- Navigating to
- <literal>http://localhost:8080/formtags-shared-libs-BUILDTAG
- </literal>
- should render the welcome page. Note that for the pre-packaged
- distributable,
- the
- <literal>BUILDTAG</literal>
- should be similar to
- <literal>3.0.0.RELEASE</literal>
- ;
- whereas, for a local build the
- <literal>-BUILDTAG</literal>
- may be completely
- omitted. Please consult the console output,
- web-based admin console, or log
- to determine the exact context path
- under which the web application has been deployed.
- </para>
- </section>
-
- <section id="formtags-case-study-war-shared-services">
- <title>Form Tags Shared Services WAR</title>
- <para>
- The next step in the migration is to deploy the services as a
- separate
- OSGi bundle which the WAR then references.
- The Form Tags
- sample has a single service
- <literal>UserManager</literal>
- .
- </para>
- <para>
- This scenario has two separate deployables, the
- <literal>service</literal>
- bundle and the WAR file.
- The following image shows the two separate
- source trees:
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-shared-services-eclipse.png"
- format="PNG" />
- <note>
- Note that the WAR does not contain the
- <literal>.domain</literal>
- or
- <literal>.service</literal>
- packages as these will be imported from the separate service bundle.
- </note>
- </para>
- <section id="formtags-case-study-war-shared-services-service">
- <title>The Service Bundle</title>
- <para>
- The responsibility of the first bundle (
- <literal>formtags-shared-services-service</literal>
- )
- is to provide the API of the formtags service. This includes both
- the
- domain and the service API. In the same way that imports are
- defined
- in the
- <literal>/META-INF/MANIFEST.MF</literal>
- , so are exports.
- The following is the
- <literal>/META-INF/MANIFEST.MF</literal>
- listing from the service bundle.
- <programlisting>
-Manifest-Version: 1.0
-Ant-Version: Apache Ant 1.7.0
-Created-By: 1.5.0_13-119 (Apple Inc.)
-Bundle-ManifestVersion: 2
-Bundle-Name: FormTags Service (and implementation)
-Bundle-SymbolicName: org.springframework.showcase.formtags.service-shared-services
-<emphasis role="bold">Export-Package</emphasis>: org.springframework.showcase.formtags.service,org.spri
- ngframework.showcase.formtags.domain
-Import-Library: org.springframework.spring;version="[3.0.0,4.0.0)"
-</programlisting>
- </para>
- <para>
- The symbolic name of this bundle is
- <literal>org.springframework.showcase.formtags.service-shared-services
- </literal>
- .
- Note that the name of the bundle typically describes the package
- that the bundle primarily exports.
- If you take a look at the
- <literal>repository/bundles/ext</literal>
- in the @tomcat.product.name.short@
- directory, you’ll see that
- names are almost always indicative of the contents of the bundle.
- For this example, however, we have also appended
- "
- <literal>-shared-services</literal>
- "
- in order to avoid possible clashes with other bundle symbolic
- names.
- You will see later that the PAR also contains a service
- bundle.
- <note>
- In OSGi, the combination of
- <literal>Bundle-SymbolicName</literal>
- and
- <literal>Bundle-Version</literal>
- is used to uniquely identify
- a bundle within the OSGi container.
- Furthermore, when you deploy
- a bundle to the @tomcat.product.name@,
- for example via the
- <literal>pickup</literal>
- directory, a bundle’s filename is also used to uniquely
- identify it for
- the purpose of supporting
- <emphasis>hot deployment</emphasis>
- via
- the file system.
- </note>
- </para>
- <para>
- As well as exporting types (i.e. the domain classes and service
- API), the service bundle also publishes an implementation of the
- <literal>UserManager</literal>
- . The actual implementation is
- <literal>StubUserManager</literal>
- ; however, that should remain an
- implementation detail of this
- bundle.
- </para>
- <para>
- The fact that this bundle publishes a service is not captured in
- the
- <literal>/META-INF/MANIFEST.MF</literal>
- , as it is a Spring-DM concept.
- The following image is of
- <literal>src/main/resources/spring</literal>
- .
- </para>
- <para>
- <imagedata
- fileref="images/formtags-case-study-shared-services-service-resources.png"
- format="PNG" />
- </para>
- <para>
- As you can see there are two Spring configuration files:
- <literal>module-context.xml</literal>
- and
- <literal>osgi-context.xml</literal>
- .
- <tip>
- These names are abitrary; however, they follow an informal
- convention:
- <literal>module-context.xml</literal>
- typically bootstraps the Spring context
- (usually delegating to
- smaller fine grained context files inside another directory),
- whilst
- <literal>osgi-context.xml</literal>
- contains all the OSGi service exports and references.
- </tip>
- The following is a listing of
- <literal>module-context.xml</literal>
- .
- <programlisting language="xml">
-<?xml version="1.0" encoding="UTF-8"?>
-
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
-
- <bean id="userManager"
- class="org.springframework.showcase.formtags.service.internal.StubUserManager"/>
-
-</beans> </programlisting>
- As you can see, this simply defines a bean called
- <literal>userManager</literal>
- .
- The following is a listing of
- <literal>osgi-context.xml</literal>
- .
- <programlisting language="xml">
-<?xml version="1.0" encoding="UTF-8"?>
-<beans:beans
- xmlns="http://www.springframework.org/schema/osgi"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:beans="http://www.springframework.org/schema/beans"
- xsi:schemaLocation="http://www.springframework.org/schema/osgi
- http://www.springframework.org/schema/osgi/spring-osgi.xsd
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans.xsd">
-
- <service ref="userManager"
- interface="org.springframework.showcase.formtags.service.UserManager"/>
-
-</beans:beans> </programlisting>
- This single bean definition exports the
- <literal>userManager</literal>
- defined in
- <literal>module-context.xml</literal>
- to the
- OSGi service registry and makes it available under the public
- <literal>org.springframework.showcase.formtags.service.UserManager
- </literal>
- API.
- </para>
- <para>
- The service bundle should now be ready to deploy on the
- @tomcat.product.name.short@.
- So copy
- <literal>/dist/formtags-shared-services-services*</literal>
- to the
- <literal>SERVER_HOME/pickup</literal>
- directory.
- Output similar to the following should appear in the
- @tomcat.product.name.short@’s console:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.
- </para>
- </note>
- <programlisting>
-[2009-07-01 15:05:03.511] fs-watcher
- <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-services-service-2.0.0.RELEASE.jar'.
-[2009-07-01 15:05:03.688] fs-watcher
- <SPDE0010I> Deployment of 'org.springframework.showcase.formtags.service_shared_services' version '2.0.0.RELEASE' completed.
-</programlisting>
- </section>
- <section id="formtags-case-study-war-shared-services-war">
- <title>Accessing the Service and Types from the WAR</title>
- <para>
- The WAR file now needs to access the types and service exported
- by
- the service bundle. The following listing is the WAR’s
- <literal>/META-INF/MANIFEST.MF</literal>
- which imports the types
- exported by the service bundle. The
- <literal>Import-Bundle</literal>
- statement has also been extended to import
- <literal>org.springframework.osgi.core</literal>
- ,
- which is necessary in order to load an OSGi-enabled
- <literal>WebApplicationContext</literal>
- .
- <programlisting>
-Manifest-Version: 1.0
-Ant-Version: Apache Ant 1.7.0
-Created-By: 1.5.0_13-119 (Apple Inc.)
-Bundle-ManifestVersion: 2
-Bundle-SymbolicName: org.springframework.showcase.formtags.web-shared-
- services
-<emphasis role="bold">Import-Package</emphasis>: org.springframework.showcase.formtags.domain,org.sprin
- gframework.showcase.formtags.service, org.eclipse.virgo.web.dm;version="[1.0,2.1)"
-Import-Library: org.springframework.spring;version="[2.5.4,3.1.0)"
-Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1
- .1.2",<emphasis role="bold">org.springframework.osgi.core</emphasis>
-</programlisting>
- </para>
- <para>
- In addition to importing the exported types of the service bundle,
- the WAR must also obtain a reference to the
- <literal>UserManager</literal>
- published by the service bundle. The following image shows the
- directory
- structure of the Shared Services WAR.
- </para>
- <para>
- <imagedata
- fileref="images/formtags-case-study-shared-services-war-resources.png"
- format="PNG" />
- </para>
- <para>
- As you can see in the above image, the Form Tags Shared Services
- WAR’s
- <literal>/WEB-INF/web.xml</literal>
- directory contains a standard
- <literal>web.xml</literal>
- deployment descriptor,
- <literal>applicationContext.xml</literal>
- which defines the configuration
- for the
- <emphasis>root</emphasis>
- <literal>WebApplicationContext</literal>
- , and
- <literal>formtags-servlet.xml</literal>
- which defines the configuration specific to the
- configured
- <emphasis>formtags</emphasis>
- <literal>DispatcherServlet</literal>
- .
- </para>
- <para>
- As is typical for Spring MVC based web applications, you configure a
- <literal>ContextLoaderListener</literal>
- in
- <literal>web.xml</literal>
- to load your root
- <literal>WebApplicationContext</literal>
- ; however, to enable your
- <literal>WebApplicationContext</literal>
- to be able to reference services from the OSGi Service Registry,
- you
- must explicitly set the
- <literal>contextClass</literal>
- Servlet context parameter to the fully qualified
- class name of a
- <literal>ConfigurableWebApplicationContext</literal>
- which is OSGi-enabled. When deploying
- Shared Services WARs to the
- @tomcat.product.name@, you should use
- <literal>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext
- </literal>.
- This will
- then enable the use of Spring-DM’s
- <literal><reference ... /></literal>
- within your root
- <literal>WebApplicationContext</literal>
- (i.e., in
- <literal>applicationContext.xml</literal>
- ).
- The following listing is an excerpt from
- <literal>/WEB-INF/web.xml</literal>
- .
- </para>
- <programlisting language="xml"><![CDATA[
- <context-param>
- <param-name>contextClass</param-name>
- <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
- </context-param>
-
- <listener>
- <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
- </listener>
-]]></programlisting>
- <para>
- The Form Tags Shared Services WAR contains a
- <literal>/WEB-INF/applicationContext.xml</literal>
- file which is the default configuration location used to create the
- <emphasis>root</emphasis>
- <literal>WebApplicationContext</literal>
- for Spring MVC’s
- <literal>ContextLoaderListener</literal>
- .
- <note>
- As already mentioned, in the OSGi world, bundle configuration
- takes
- place in the root
- <literal>/META-INF/</literal>
- directory.
- Typically Spring-DM powered configuration files will live
- there as well (e.g., in
- <literal>/META-INF/spring/*.xml</literal>
- ).
- In a WAR, however, the root
- <literal>WebApplicationContext</literal>
- loaded by
- <literal>ContextLoaderListener</literal>
- and the
- <literal>DispatcherServlet’s</literal>
- application context typically live in
- <literal>/WEB-INF/</literal>
- .
- </note>
- The following is the listing of the WAR’s
- <literal>/WEB-INF/applicationContext.xml</literal>
- .
- <programlisting language="xml">
-<?xml version="1.0" encoding="UTF-8"?>
-<beans:beans
- xmlns="http://www.springframework.org/schema/osgi"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:beans="http://www.springframework.org/schema/beans"
- xsi:schemaLocation="http://www.springframework.org/schema/osgi
- http://www.springframework.org/schema/osgi/spring-osgi.xsd
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans.xsd">
-
- <reference id="userManager"
- interface="org.springframework.showcase.formtags.service.UserManager"/>
-
-</beans:beans> </programlisting>
- The single bean declaration is retrieving a service that implements
- the
- <literal>org.springframework.showcase.formtags.service.UserManager
- </literal>
- API from the OSGi Service Registry.
- <tip>
- You might have been expecting a reference to the service bundle,
- but that isn’t how OSGi works. OSGi provides a service
- registry, and this bean definition is accessing a service in that
- registry that meets the specified restriction (i.e. implements
- the
- specified interface). This leads to a very loosely coupled
- programming model: the WAR really doesn’t care where the
- implementation
- comes from.
- </tip>
- <tip>
- What happens if there is no service at runtime?
- What if there are
- multiple services that match the criteria?
- Spring-DM provides a lot
- of configuration options, including
- whether or not the reference is
- <emphasis>mandatory</emphasis>
- ,
- how long to wait for a service reference, etc. Please consult the
- <ulink url="http://www.springframework.org/osgi/">Spring Dynamic Modules for OSGi</ulink>
- home page for further information.
- </tip>
- <para>
- One of the benefits of programming to interfaces is that you
- are
- decoupled from the actual implementation; Spring-DM provides a
- proxy. This
- has enormous benefits including the ability to
- dynamically refresh individual bundles without
- cascading that
- refresh to unrelated bundles.
- </para>
- </para>
- <para>
- To deploy the WAR, copy
- <literal>/dist/formtags-shared-services-war*</literal>
- to the
- <literal>SERVER_HOME/pickup</literal>
- directory.
- You should then see console output similar to the
- following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.
- </para>
- </note>
- <programlisting>
-[2009-07-01 15:09:19.819] fs-watcher
- <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-services-war-3.0.0.RELEASE.war'.
-[2009-07-01 15:09:20.167] fs-watcher
- <SPDE0010I> Deployment of 'org.springframework.showcase.formtags.web_shared_services' version '3' completed.
-[2009-07-01 15:09:20.168] Thread-20
- <SPWE0000I> Starting web bundle '/formtags-shared-services-war-3.0.0.RELEASE'.
-[2009-07-01 15:09:20.647] Thread-20
- <SPWE0001I> Started web bundle '/formtags-shared-services-war-3.0.0.RELEASE'.
-</programlisting>
- Navigating to the appropriate link should render the welcome page.
- </section>
- </section>
-
- <section id="formtags-case-study-par">
- <title>Form Tags PAR</title>
- <para>
- The final step in the migration is that of a full blown
- OSGi
- application with web support. The @tomcat.product.name@ introduces a
- new packaging and deployment format: the PAR.
-
- A PAR is a standard JAR
- with a "
- <literal>.par</literal>
- "
- file extension which contains all of the modules of your
- application (e.g., service, domain, and infrastructure bundles
- as well
- as a WAR for web applications) in a single deployment unit.
- Moreover,
- a PAR defines both a physical and logical application boundary.
- </para>
- <para>
- The PAR sample is comprised of four directories, as shown below.
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-par-sample.png"
- format="PNG" />
- </para>
- <para>
- The
- <literal>formtags-par</literal>
- directory is a build project that
- understands how to create the PAR
- from its constituent bundles.
- </para>
- <section id="formtags-case-study-par-granularity">
- <title>Granularity of the PAR</title>
- <para>
- Achieving the appropriate level of granularity for your OSGi
- application is more of an art than a science. It helps to look
- at the
- different requirements:
- <table id="formtags-case-study-par-granularity-drivers-table"
- colsep="1" frame="all" rowsep="1">
- <title>Granularity drivers</title>
- <tgroup cols="2">
- <colspec colwidth="2*" />
- <colspec colwidth="3*" />
- <thead>
- <row>
- <entry>Requirement</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Domain/Technical Layering</entry>
- <entry>
- Applications can be split either by domain (i.e.,
- by use case or
- <emphasis>vertically</emphasis>
- ) or
- by their technical layers (i.e.,
- <emphasis>horizontally</emphasis>
- ).
- Since the Form Tags application essentially has only
- a single
- use case, the bundles are split by technical layering
- (i.e.,
- domain, service, and web).
- </entry>
- </row>
- <row>
- <entry>Refreshability</entry>
- <entry>
- A major benefit of OSGi is that of refreshability: if one
- bundle
- is changed, only bundles that have a dependency upon
- the
- exported types need to be refreshed. This has a high impact
- on
- development time costs as well as production
- costs. However,
- this can lead to lots of smaller, fine grained
- bundles. An
- example of this granularity would be to
- separate out the service
- API and implementation into two different
- bundles. This means
- that a change in the implementation
- wouldn’t require any
- other bundles to be refreshed.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- Ultimately the right level of granularity will depend upon your
- particular application and team.
- </para>
- </section>
- <section id="formtags-case-study-par-domain-and-service">
- <title>Domain and Service Bundles</title>
- <para>
- The service bundle is identical (except for the
- <literal>Bundle-SymbolicName</literal>
- ) to that
- in the shared-services variation of the sample.
- The PAR has
- also separated out the domain classes into their own bundle.
- When
- layering by technical considerations, it is again
- somewhat of an
- unofficial convention to have a
- <literal>.domain</literal>
- bundle.
- </para>
- </section>
- <section id="formtags-case-study-par-par">
- <title>Constructing the PAR</title>
- <para>
- Finally we need to construct the PAR itself.
- The following are
- the contents of the exploded PAR.
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-par-exploded.png"
- format="PNG" />
- </para>
- <para>
- You can see that the PAR itself doesn’t contain any
- resources or
- Java classes: it simply packages together a related set
- of bundles
- as a single, logical unit.
- </para>
- <para>
- The PAR does however, contain its own
- <literal>/META-INF/MANIFEST.MF</literal>
- .
- <programlisting>
-Manifest-Version: 1.0
-Application-SymbolicName: org.springframework.showcase.formtags-par
-Application-Version: 3.0.0
-Application-Name: FormTags Showcase Application (PAR)
-</programlisting>
- For more information on the contents of the PAR’s
- <literal>/META-INF/MANIFEST.MF</literal>
- , please consult
- <xref linkend="developing-applications" />
- .
- </para>
- <para>
- You can now deploy the PAR on the @tomcat.product.name.short@, for
- example by copying
- <literal>/dist/formtags-par*.par</literal>
- to the @tomcat.product.name.short@’s
- <literal>pickup</literal>
- directory.
- You should then see console output similar to the
- following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.
- </para>
- </note>
- <programlisting>
-[2009-07-01 15:13:43.306] fs-watcher
- <SPDE0048I> Processing 'CREATED' event for file 'formtags-par-2.0.0.RELEASE.par'.
-[2009-07-01 15:13:44.060] fs-watcher
- <SPDE0010I> Deployment of 'formtags-par' version '2.0.0.RELEASE' completed.
-[2009-07-01 15:13:44.068] Thread-20
- <SPWE0000I> Starting web bundle '/formtags-par'.
-[2009-07-01 15:13:45.212] Thread-20
- <SPWE0001I> Started web bundle '/formtags-par'.
-</programlisting>
- <para>
- Navigate to
- <ulink url="http://localhost:8080/formtags-par" />
- to see the welcome page.
- </para>
- <tip>
- Note that the web application’s context path is explicitly
- defined via the
- <literal>Web-ContextPath</literal>
- manifest header in
- <literal>/META-INF/MANIFEST.MF</literal>
- of the Web application bundle within the PAR.
- </tip>
- </section>
- </section>
- <section id="formtags-case-study-summary">
- <title>Summary of the Form Tags Migration</title>
- <para>
- The @tomcat.product.name@ provides out-of-the-box support for
- deploying
- standard Java EE WAR files. In addition support for
- <emphasis>Shared Libraries</emphasis>
- and
- <emphasis>Shared Services</emphasis>
- WAR formats provides a logical migration path away from standard,
- monolithic WARs toward OSGi-enable Web applications. The PAR
- packaging
- and deployment format enables truly fine-grained,
- loosely-coupled, and
- efficient application development. In general,
- the migration steps
- presented in this chapter are fairly
- straightforward, but developers
- should set aside time for some
- up-front design of the bundles themselves.
- </para>
- <para>
- It is recommended that you take another sample application or
- indeed your own small application and go through this migration
- process yourself. This will help you better understand the concepts
- and
- principles at work. In addition, it is highly recommended that you
- familiarize yourself with the extensive Eclipse IDE support provided
- by the Virgo Tools. See the Virgo Tools Guide for more on that.
- </para>
- </section>
-
- <section id="formtags-case-study-as-plan">
- <title>Form Tags as a Plan</title>
- <para>
- Plans (see
- <xref linkend="developing-applications-plans" />
- )
- allow us to package and deploy the Form Tags application in a more
- flexible way.
- Instead of packaging all the bundles of the application
- into a single PAR file, each bundle can be placed in the repository
- and referred to in a
- <emphasis>plan</emphasis>
- .
- </para>
- <para>
- The bundles to be placed in a repository in the chain (for example,
- <literal>repository/usr</literal>
- ) are:
- <programlisting>org.springframework.showcase.formtags.domain-2.0.0.RELEASE.jar
-org.springframework.showcase.formtags.service-2.0.0.RELEASE.jar
-org.springframework.showcase.formtags.web-2.0.0.RELEASE.war
-</programlisting>
- which are just those files which were part of the PAR.
- </para>
- <para>
- Here is the contents of a suitable plan file for the Form Tags
- example:
- <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<plan name="formtags.plan" version="2.0.0" scoped="true" atomic="true"
- xmlns="http://www.eclipse.org/virgo/schema/plan"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.eclipse.org/virgo/schema/plan
- http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
-
- <artifact type="bundle" name="org.springframework.showcase.formtags.domain_par" version="[3.0,3.1)"/>
- <artifact type="bundle" name="org.springframework.showcase.formtags.service_par" version="[3.0,3.1)"/>
- <artifact type="bundle" name="org.springframework.showcase.formtags.web_par" version="[3.0,3.1)"/>
-
-</plan>]]></programlisting>
- where we have chosen to use any of the artifacts in the version range
- [2.0,2.1).
- This plan (as a file called, for example,
- <literal>formtags.plan</literal>
- )
- can be deployed in any of the normal ways (for example, dropped in
- the
- <literal>pickup</literal>
- directory).
- </para>
- <para>
- When the plan is deployed, the artifacts it references are
- installed from the repository and deployed in the order given in the
- plan file.
- Because this plan is scoped and atomic, the collection is
- given an application scope and is started and stopped as a single
- unit.
- </para>
- </section>
-
-</chapter>
diff --git a/programmer-guide/src/introduction.xml b/programmer-guide/src/introduction.xml
deleted file mode 100644
index 747b60c..0000000
--- a/programmer-guide/src/introduction.xml
+++ /dev/null
@@ -1,214 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="introduction">
- <title>Introduction to the @tomcat.product.name@</title>
- <section id="introduction-preface">
- <title>Overview</title>
- <para>
- In this chapter, we provide an overview of the @tomcat.product.name@ focusing
- on what it is, what benefits it provides to developers and administrators,
- and why you should use it.
- </para>
- </section>
- <section id="introduction-what">
- <title>What is the @tomcat.product.name@?</title>
- <para>
- The @tomcat.product.name@, or @tomcat.product.name.short@ for short, is the runtime portion of the @umbrella.product.name@.
- It is a lightweight, modular, OSGi-based runtime that provides a complete packaged solution for developing,
- deploying, and managing enterprise applications.
- By leveraging several best-of-breed technologies and improving upon
- them, the @tomcat.product.name.short@ offers a compelling solution to develop and deploy
- enterprise applications.
- </para>
- <section id="introduction-constituents">
- <title>What Makes up the @tomcat.product.name@?</title>
- <para>
- The @tomcat.product.name@ is built on top of the following core technologies:
- </para>
- <itemizedlist>
- <listitem><ulink url="http://www.springframework.org/">Spring Framework</ulink>, obviously!</listitem>
- <listitem><ulink url="http://tomcat.apache.org/">Tomcat</ulink> as the web container.</listitem>
- <listitem><ulink url="http://www.osgi.org/Specifications/HomePage">OSGi R4.3</ulink>.</listitem>
- <listitem><ulink url="http://www.eclipse.org/equinox/">Equinox</ulink> as the OSGi implementation.</listitem>
- <listitem><ulink url="http://www.springframework.org/osgi/">Spring Dynamic Modules for OSGi</ulink> for working with OSGi in a Spring application.</listitem>
- <listitem><ulink url="http://www.springsource.com/products/sts">SpringSource Tool Suite</ulink> for developing applications.</listitem>
- </itemizedlist>
- <para>
- Note, however, that the @tomcat.product.name@ isn’t just a combination
- of these technologies. Rather, it integrates and extends these
- technologies to provide many features essential for developing,
- deploying, and managing today’s enterprise Java applications.
- </para>
- </section>
- <para>
- The following diagram presents a high-level overview of the @tomcat.product.name.short@’s architecture.
- </para>
- <para>
- <imagedata fileref="images/introduction-architecture.png"/>
- </para>
- <para>
- At the heart of the @tomcat.product.name@ is the @kernel.product.name@ or @kernel.product.name.short@.
- The @kernel.product.name.short@ is an OSGi-based kernel that takes full advantage of the modularity
- and versioning of the OSGi platform. The @kernel.product.name.short@ builds on a base version of @nano.product.name@ or @nano.product.name.short@ and extends its capabilities for
- provisioning and library management, as well as providing core functionality for the @tomcat.product.name.short@. The @nano.product.name.short@ maintains a minimal
- runtime footprint and startup time. It builds on top of a pure Equinox, extending it with more sophisticated diagnostics and supportability functionality.
- The @nano.product.name.short@ supports full p2 provisioning. This feature is not included in the Virgo Nano Base that the @kernel.product.name.short@ is built on.
- </para>
- <para>
- To maintain a minimal runtime footprint, OSGi bundles are installed on demand by the
- @nano.product.name.short@. On subsequent restarts these core bundles are warm-started thus reducing the startup time. This allows for an application to be installed
- into a running @tomcat.product.name.short@ and for its dependencies to be satisfied from an external repository. Not only
- does this remove the need to manually install all your application dependencies, which would be tedious, but it also keeps memory usage to a minimum.
- </para>
- <para>
- As shown in the figure, @kernel.product.name.short@ runs on top of @nano.product.name.short@ that extends Equinox within a standard Java
- Virtual Machine. Above the @kernel.product.name.short@ further layers contribute functionality
- to the @tomcat.product.name.short@. Such as management and web application support.
- </para>
- <para>
- Version @bundle.version@ of the @tomcat.product.name@ supports <emphasis>bundle</emphasis>,
- <emphasis>plan</emphasis>, <emphasis>PAR</emphasis>, <emphasis>configuration</emphasis>,
- <emphasis>Web Application Bundle (WAB)</emphasis>, and <emphasis>WAR</emphasis> artifacts, which enable
- you to build sophisticated web applications. This includes support for
- standard Java EE WARs, "shared library" WARs, and "shared services" WARs, each of
- which will be covered in greater detail in <xref linkend="architecture" />.
- </para>
- <important>
- <para>
- The @nano.product.name@ has a different provisioning system which isn't included in the Virgo Nano Base on which the
- @kernel.product.name.short@ and the @tomcat.product.name.short@ are built.
- </para>
- <para>
- Version @bundle.version@ of the @nano.product.name@ supports <emphasis>bundle</emphasis>,
- <emphasis>p2 feature</emphasis>, <emphasis>Web Application Bundle (WAB)</emphasis>, and <emphasis>WAR</emphasis> artifacts, which enable
- you to build sophisticated web applications too, taking full advantage of p2's dependency resolution, automated download and fail-early mechanics.
- The @nano.product.name@ does NOT support <emphasis>plan</emphasis>, <emphasis>PAR</emphasis> or <emphasis>configuration</emphasis> artifacts.
- New <emphasis>features</emphasis> are provisioned via <emphasis>update sites</emphasis> or <emphasis>p2 repositories</emphasis>.
- Brief overview of p2 and it's mechanics is available on <ulink url="http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/">this blog</ulink>.
- The @nano.product.name.short@'s default web container implementation is Gemini Web.
- </para>
- </important>
- </section>
-
- <section id="introduction-why">
- <title>Why the @tomcat.product.name@?</title>
- <para>
- You could deploy a web application in a stand-alone servlet engine or application server.
- Or you could even deploy directly in an OSGi container such as Equinox. However,
- deploying in the @tomcat.product.name@ offers a number of key benefits that make it both more
- appealing and more suitable for enterprise application development.
- </para>
-
- <section id="introduction-unified-deployment">
- <title>Deployment Options and Migration Paths</title>
- <para>
- While many applications deployed in the @tomcat.product.name@ will take advantage
- of OSGi capabilities, not all applications need such sophistication.
- For example, development teams may initially choose to continue packaging
- existing web applications as standard WAR files and then gradually migrate
- toward a fully OSGi-based packaging and deployment model. The @tomcat.product.name@
- makes such migrations easy for developers by supporting multiple packaging
- and deployment formats. These formats and migration strategies are discussed
- in greater detail in <xref linkend="migrating-to-osgi" /> and
- <xref linkend="formtags-case-study" />.
- </para>
- </section>
-
- <section id="introduction-simplified-deployment">
- <title>Simplified Development and Deployment of OSGi-based Applications</title>
- <para>
- Prior to the release of the @tomcat.product.name@, developing and deploying OSGi
- applications involved inherent complexity such as:
- </para>
- <itemizedlist>
- <listitem>
- <emphasis>Obtaining OSGi bundles for popular Java libraries:</emphasis>
- For optimal benefits, every technology you use in an OSGi application must
- be packaged as OSGi bundles. Currently, this involves manually converting
- JAR files into bundles and making sure that any libraries needed by those
- bundles are also available as OSGi bundles. The @ebr@ is a good source of
- popular pre-bundled libraries.
- </listitem>
- <listitem>
- <emphasis>Package management complexity:</emphasis>
- OSGi bundles use other bundles through <code>Import-Package</code> manifest headers.
- Many applications use a set of common technologies (e.g., an ORM solution,
- a web framework, etc.). Combining these two characteristics leads to duplicated
- configuration in the form of repeated and verbose <code>Import-Package</code> statements.
- </listitem>
- <listitem>
- <emphasis>Lack of application-level isolation:</emphasis>
- In OSGi everything is a bundle, and all bundles share the same OSGi Service Registry.
- To highlight how conflicts can arise between applications and their services in this
- shared service registry, consider the following scenarios.
- <itemizedlist>
- <listitem>
- Application <code>A</code> is comprised of bundles <code>B</code> and <code>C</code>.
- In a standard OSGi environment, if you attempt to install two instances of the same
- version of application <code>A</code> (i.e., two sets of bundles <code>B</code> and
- <code>C</code>), a clash will occur, because you cannot deploy multiple bundles with
- the same <code>Bundle-SymbolicName</code> and <code>Bundle-Version</code> combination.
- </listitem>
- <listitem>
- Application <code>A1</code> is comprised of bundles <code>B1</code> and <code>C1</code>.
- Similarly, application <code>A2</code> is comprised of bundles <code>B2</code> and <code>C2</code>.
- Each bundle has a unique combination of <code>Bundle-SymbolicName</code> and <code>Bundle-Version</code>.
- Bundles <code>B1</code> and <code>B2</code> both export service <code>S</code> which
- is imported by both <code>C1</code> and <code>C2</code>. In contrast to the previous
- example, there is no conflict resulting from duplicate
- <code>Bundle-SymbolicName</code>/<code>Bundle-Version</code> combinations; however,
- there is a clash for the exported service <code>S</code>.
- Which service <code>S</code> will bundles <code>C1</code> and <code>C2</code> end up
- using once they are installed?
- Assuming bundles <code>B1</code> and <code>C1</code> are intended to work together,
- you would not want bundle <code>C1</code> to get a reference to service <code>S</code>
- from bundle <code>B2</code>, because it is installed in a different logical application.
- On the contrary, you typically want bundle <code>C1</code> to get a reference to
- service <code>S</code> exported by bundle <code>B1</code>, but in a standard OSGi environment
- this may not be the case.
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>
- Furthermore, since standard OSGi does not define a notion of an application as a set of bundles,
- you cannot deploy or undeploy an application and its constituent bundles as a single unit.
- </para>
- <para>
- The @tomcat.product.name@ introduces a number of features to solve these issues:
- </para>
- <itemizedlist>
- <listitem>
- A full set of OSGi bundles for many popular Java libraries to get you
- started quickly with creating OSGi applications.
- </listitem>
- <listitem>
- An OSGi library concept that obviates the need to
- duplicate verbose <code>Import-Package</code> statements.
- </listitem>
- <listitem>
- The PAR packaging format which offers
- application-level isolation and deployment.
- </listitem>
- <listitem>
- The concept of a plan, which is an XML file that lists a collection of bundles that @tomcat.product.name@ should load together as a single application. Conceptually, plans are very like PARs, except that a plan describes the contents of the application rather than a PAR that actually contains them.
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="introduction-diagnostics">
- <title>Enhanced Diagnostics During Deployment and in Production</title>
- <para>
- Identifying why an application won’t deploy or which particular library
- dependencies are unsatisfied is the cause of many headaches!
- Similarly, production time errors that don’t identify the root cause are
- all too familiar to Java developers. The @tomcat.product.name.short@ was designed from the
- ground up to enable tracing and First Failure Data Capture (FFDC) that
- empower developers with precise information at the point of failure to
- fix the problem quickly.
- </para>
- </section>
-
- </section>
-</chapter>
diff --git a/programmer-guide/src/known-issues.xml b/programmer-guide/src/known-issues.xml
deleted file mode 100644
index 3919d4b..0000000
--- a/programmer-guide/src/known-issues.xml
+++ /dev/null
@@ -1,135 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="known-issues">
- <title>Known Issues</title>
- <section id="known-issues-jpa">
- <title>JPA Entity Scanning</title>
- <para>
- Classpath scanning for JPA entities annotated with <literal>@Entity</literal> does
- not work. Describing entities with <literal>@Entity</literal> will work, but the
- entities need to be listed explicitly.
- </para>
- </section>
- <section id="known.issues.proxy">
- <title><classname>ClassNotFoundError</classname> When Creating a Proxy</title>
- <para>
- When creating proxies at runtime, there are circumstances where <classname>ClassNotFoundErrors</classname>
- can be generated. These errors happen because the proxy creating bundle does not have visibility into every
- type on the interface of the proxy. You can either put in import statements for all the relevant types or
- add use a service (with visibility of all pertinent types) to create the proxy. Please see
- <ulink url="http://www.osgi.org/blog/2008/08/classy-solutions-to-tricky-proxies.html">this blog entry</ulink>
- for more details.
- </para>
- </section>
- <section id="known.issues.cglib">
- <title>Creating proxies with CGLIB for Package Protected Types</title>
- <para>
- In traditional Java EE applications user types are loaded by the same <classname>ClassLoader</classname> as
- CGLIB. This allows CGLIB to proxy package-protected types. In OSGi environments, user types and CGLIB will
- most likely be packaged in separate bundles. This results in the user types and CGLIB being loaded by
- different <classname>ClassLoaders</classname>. This prevents CGLIB from proxying any package-protected types.
- </para>
- <para>
- The workaround for this issue is to make all types that require proxying public.
- </para>
- </section>
- <section id="known-issues-jetty-restrictions">
- <title>@jetty.product.name@ Restrictions</title>
- <para>
- The following Jetty features are not supported.
- <itemizedlist>
- <listitem>
- Tag Libraries other than the standard Apache Tag Library.
- </listitem>
- <listitem>
- Jetty 7 does not support the Servlet 3.0 spec. When Jetty 8.0 is released the Virgo Jetty Server will
- move up in a later release.
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="known-issues-web-bundle-default-headers">
- <title>Default Web Application Bundle Headers</title>
- <para>
- The Gemini Web container conforms to the OSGi Web Applications specification and does not apply default values
- to the headers of a Web Application Bundle. However, SpringSource dm Server 2.0.x applies default values
- to certain headers (see <link linkend="developing-applications-automatic-imports-web">Web Application Manifest
- Processing</link> for details) and so Virgo Web Server 2.1.x modified the behaviour of Gemini Web so that it applied default
- values consistently with dm Server 2.0.x.
- </para>
- <para>
- This behaviour is changed as of @tomcat.product.name@ 3.0. @tomcat.product.name.short@ now conforms strictly to the
- OSGi Web Applications specification.
- </para>
- <para>
- As a migration aid, <emphasis>which may not be supported in a future release</emphasis>, users may configure the @tomcat.product.name.short@ Web Integration
- Layer to apply default values to the headers of a Web Application Bundle.
- See "Configuring the Web Integration Layer" in the <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink> for details.
- </para>
- </section>
- <section id="hibernate-resolution-issue">
- <title>Hibernate Resolution Issue</title>
- <para>
- Applications using Hibernate 3.4.0.GA need to upgrade the JBoss Hibernate Entity manager fragment bundle to version 3.4.0.GA-A.
- The symptoms are that the application will fail to resolve due to missing imports of packages such as <literal>org.hibernate.ejb.transaction</literal>
- and JBoss Hibernate Annotations <literal>com.springsource.org.hibernate.annotations</literal>.
- See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=335174">bug 335174</ulink> for details.
- </para>
- <para>
- The JBoss Hibernate Entity manager fragment bundle <literal>com.springsource.org.hibernate.ejb</literal> v3.4.0.GA in the
- <ulink url="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</ulink>
- depends on the package <literal>org.slf4j</literal> with a version range that excludes the version of the
- package provided with Virgo. The net effect is that Hibernate EJB fragment bundle fails to attach to its host
- <literal>com.springsource.org.hibernate</literal> and the host then does not export the packages the application
- may need, such as <literal>org.hibernate.ejb.transaction</literal>.
- </para>
- <para>
- An updated JBoss Hibernate Entity manager fragment and JBoss Hibernate Annotations with versions 3.4.0.GA-A which fixes this
- problem is available from the <ulink url="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</ulink>.
- </para>
- </section>
- <section id="scoping-and-substitutable-exports">
- <title>Scoping and Substitutable Exports</title>
- <para>
- The restriction described in <link linkend="developing-applications-plans-scoping">Plans and Scoping</link> that
- no package may be exported by more than one bundle in a given scope can cause problems for bundles with
- <emphasis>substitutable exports</emphasis>. A substitutable export is a package which is exported and imported
- by the same bundle. The OSGi framework will discard either the import or the export of the package when the
- bundle is resolved.
- </para>
- <para>
- However, if more than one bundle in a scope has a substitutable export of the same package, then Virgo will fail
- to deploy the scoped application because the above restriction appears to be broken. Virgo could only spot that
- the restriction was not actually being broken by second guessing the resolution behaviour of the OSGi framework,
- something that Virgo generally avoids because of the fragility of that approach.
- </para>
- <para>
- It may be possible to work around this issue by omitting one of the bundles containing the substitutable export
- from the scoped application.
- </para>
- <para>
- It may also be possible to work around this issue by moving the bundles containing the substitutable exports outside the scope,
- although this will not give correct behaviour if the bundles' exported packages need to be available for thread
- context class loading.
- </para>
- <para>
- See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=330643">bug 330643</ulink> for an example of this issue.
- </para>
- </section>
- <section id="eclipselink-resolution-issue">
- <title>EclipseLink Resolution Issue</title>
- <para>
- Applications using EclipseLink may fail to resolve if the <literal>osgi.enterprise</literal> bundle is allowed to
- wire its <literal>javax.persistence</literal> package import to other than the EclipseLink <literal>javax.persistence</literal> bundle.
- </para>
- <para>
- To avoid this, install EclipseLink's <literal>javax.persistence</literal> bundle early. To install this bundle before
- any applications are deployed, list the bundle in the <literal>initialArtifacts</literal> property described in the
- <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink>.
- </para>
- <para>
- See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=337826">bug 337826</ulink> for details.
- </para>
- </section>
-</chapter>
diff --git a/programmer-guide/src/migrating-to-osgi.xml b/programmer-guide/src/migrating-to-osgi.xml
deleted file mode 100644
index ed9601f..0000000
--- a/programmer-guide/src/migrating-to-osgi.xml
+++ /dev/null
@@ -1,149 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="migrating-to-osgi">
- <title>Migrating to OSGi</title>
- <para>
- Taking on a new technology such as OSGi may seem a bit daunting at first,
- but a proven set of migration steps can help ease the journey. Teams
- wishing to migrate existing applications to run on the @tomcat.product.name@
- will find that their applications typically fall into one of the following
- categories.
-
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Web Application</emphasis>: for web applications,
- this chapter provides an overview of the steps required to migrate
- from a Standard WAR to a Shared Services WAR. Furthermore, the following
- chapter provides a detailed case study involving the migration
- of the Spring 3.0 Form Tags show case application.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Anything else</emphasis>: for any other type
- of application, you will typically either deploy your application
- as multiple individual bundles, as a single PAR file, or as a plan,
- which is the recommended approach for deploying applications on
- the @tomcat.product.name@. See <xref linkend="migrating-to-osgi-par-plan" /> for details.
- </para>
- </listitem>
- </itemizedlist>
-
- </para>
-
- <section id="migrating-to-osgi-web">
- <title>Migrating Web Applications</title>
- <para>
- Many applications may start with the standard WAR format for web applications and
- gradually migrate to a more OSGi-oriented architecture. Since the @tomcat.product.name@
- offers several benefits to all supported deployment formats, it provides a smooth
- migration path. Of course, depending on your application’s complexity and your
- experience with OSGi, you may choose to start immediately with an OSGi-based
- architecture.
- </para>
-
- <section id="migrating-to-osgi-web-standard-war">
- <title>Standard WAR</title>
- <para>
- If you are not yet familiar with OSGi or simply want to deploy an existing web application on the @tomcat.product.name@,
- you can deploy a standard WAR and leverage the @tomcat.product.name.short@ with a minimal learning curve. In fact reading the
- <ulink url="../../virgo-user-guide/html/index.html">@tomcat.product.name@ User Guide</ulink>
- is pretty much all that you need to do to get started. Furthermore, you will gain
- familiarity with the @tomcat.product.name@, while preparing to take advantage of the other formats.
- </para>
- </section>
- <section id="migrating-to-osgi-web-shared-libraries-war">
- <title>Shared Libraries WAR</title>
- <para>
- The <emphasis>Shared Libraries WAR</emphasis>
- format is the first step to reaping the benefits of OSGi. In this phase, you dip your toes into OSGi-based dependency
- management by removing JAR files from the WAR and declaring dependencies on corresponding OSGi bundles.
- </para>
- </section>
- <section id="migrating-to-osgi-web-shared-services-war">
- <title>Shared Services WAR</title>
- <para> In this phase, you take the next step toward a fully OSGi-based architecture by separating your web artifacts
- (e.g., Servlets, Controllers, etc.) from the services they depend on.</para>
- </section>
- <section id="migrating-to-osgi-web-summary">
- <title>Web Migration Summary</title>
- <para>
- The following diagram graphically depicts the migration path from a Standard WAR to a Shared Services WAR.
- As you can see, the libraries (<emphasis>libs</emphasis>) move from within the deployment artifact
- to the Bundle Repository.
- Similarly, the services move from within the WAR to external bundles and are accessed via the
- OSGi Service Registry. In addition, the overall footprint of the deployment artifact decreases
- as you move towards a Shared Services WAR.
- <mediaobject><imageobject><imagedata fileref="images/migration-path-war-to-shsrv.png" /></imageobject></mediaobject>
- </para>
- </section>
-
- </section>
-
-<!-- ======================================================================= -->
-<!-- ======================================================================= -->
-
- <section id="migrating-to-osgi-par-plan">
- <title>Migrating to a Plan or a PAR</title>
- <para>
- The first steps to migrating an existing application to a plan or a PAR are the same: deciding on the bundles that make up the application and ensuring that their <code>Import-Package</code>, <code>Import-Library</code>, and <code>Import-Bundle</code> manifest headers are correct. Once you have the list of bundles that make up your application, you then decide whether you want to JAR them all into a single application file (PAR) or create a plan that simply lists the bundles by reference. Creating a plan is the recommend way to create an application, although PARs also have benefits that might suit your needs better, as described in <xref linkend="migrating-to-osgi-parplan-decide" />.
- </para>
-
- <section id="migrating-to-osgi-parplan-bundles">
- <title>Creating the Application Bundles</title>
- <para>
- When migrating an existing application to the PAR packaging and deployment format or a plan,
- you consider modularity as the prime objective. Following the ideas discussed in
- <xref linkend="architecture-forming-bundles" />, you refactor the application into multiple bundles.
- You may start conservatively with a small number of bundles and then further refactor those bundles.
- </para>
- <para>
- If the original code is crafted following good software practices such as separation of concerns and use of
- well-defined interfaces, migration may involve modifying only configuration and packaging. In other words,
- your Java sources will remain unchanged. Even configuration is likely to change only slightly.
- </para>
- <para>
- For example, the following diagram depicts a typical web application that has been refactored and
- packaged as a PAR. The blue elements within the <emphasis>Application</emphasis> box constitute
- the bundles of the application. Each of these bundles imports types from other bundles within
- the PAR using <literal>Import-Package</literal>. The green elements in the left column represent
- <emphasis>libraries</emphasis> installed on the @tomcat.product.name.short@. The PAR’s bundles reference these
- libraries using <literal>Import-Library</literal>. The purple element in the left column
- represents a bundle within the @tomcat.product.name.short@’s bundle repository which is imported by the DAO
- bundle using <literal>Import-Bundle</literal>. In contrast to a traditional, monolithic
- WAR deployment, the PAR format provides both a logical and physical application boundary
- and simultaneously allows the application to benefit from both the OSGi container and the @tomcat.product.name@.
- <mediaobject><imageobject><imagedata fileref="images/migrating-to-osgi-par-structure.png" /></imageobject></mediaobject>
- </para>
- </section>
-
- <section id="migrating-to-osgi-parplan-decide">
- <title>Plan or PAR?</title>
- <para>
- Once you have refactored your existing application into separate OSGi bundles, you then must decide whether to package the bundles into a single PAR file or create a plan that lists the bundles by reference. As described in more detail in preceding sections of this guides, PARs and plans have similar benefits, such as:
- </para>
- <itemizedlist>
- <listitem>Scoping</listitem>
- <listitem>Atomicity, or the ability to deploy and control the bundles as a single unit</listitem>
- <listitem>Versioning</listitem>
- <listitem>Improved serviceability</listitem>
- </itemizedlist>
- <para>
- Plans, the method most recommended by us to create your application, has the following added benefits:
- </para>
- <itemizedlist>
- <listitem>Guaranteed order of deployment, based on the order in which they are listed in the plan’s XML file</listitem>
- <listitem>Ease of sharing content between plans and updating individual plans without having to physically repackage, due to the artifacts being listed by reference.</listitem>
- <listitem>Ability to disable scoping and atomicity, if desired.</listitem>
- </itemizedlist>
- <para>
- The main benefit of PARS is that, because they physically contain all the required artifacts, you know exactly what bundles are deployed when you deploy the PAR file, in contrast to plans that allow content to be substituted or lost.
- </para>
- <para>
- For details about creating plans and PARs, see <xref linkend="developing-applications-plans" /> and <xref linkend="developing-applications-packaging" />, respectively.
- </para>
- </section>
- </section>
-</chapter>
diff --git a/programmer-guide/src/preface.xml b/programmer-guide/src/preface.xml
deleted file mode 100644
index 72a44af..0000000
--- a/programmer-guide/src/preface.xml
+++ /dev/null
@@ -1,43 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<preface id="preface">
- <title>Preface</title>
- <para>
- Increasing complexity in modern enterprise applications is a fact of life.
- Developers not only have to deal with complex business logic, but also a myriad
- of other concerns such as security, auditing, exposing business
- functionality to external applications, and managing the evolution of
- these concerns. The Spring Framework addresses these
- needs by offering a Plain-Old Java Object (POJO) based solution that
- lets you focus on your business logic.
- </para>
- <para>
- Complex applications pose problems that go beyond using the right set of
- technologies. You need to take into account other considerations such as
- a simplified development process, easy deployment, monitoring deployed
- applications, and managing changes in response to changing business needs.
- This is where the @umbrella.product.name@ comes into play. It offers a simple yet
- comprehensive platform to develop, deploy, and service enterprise
- applications. In this Programmer Guide, we explore the runtime portions of the
- @umbrella.product.name@, the @tomcat.product.name@, @jetty.product.name@ and the
- @kernel.product.name@, and learn how to develop applications to benefit from their
- capabilities.
- </para>
- <simplesect>
- <title>A Note to @kernel.product.name@ Programmers</title>
- <para>
- Although this guide is written primarily for @tomcat.product.name@ programmers, much of it is also useful for
- @kernel.product.name@ programmers who should simply ignore the web-related sections.
- </para>
- </simplesect>
- <simplesect>
- <title>A Note to @nano.product.name@ Programmers</title>
- <para>
- This guide is written primarily for @tomcat.product.name@ programmers. Although a base version of @nano.product.name@, without the new provisioning
- system, is used to build the @tomcat.product.name@, much of this guide does not apply to @nano.product.name@. The @nano.product.name.short@ lacks regions support but has much
- improved runtime footprint and startup time and also provides support for p2 provisioning. The @nano.product.name@ features are covered better in the
- <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink>.
- </para>
- </simplesect>
-</preface>
diff --git a/programmer-guide/src/prerequisites.xml b/programmer-guide/src/prerequisites.xml
deleted file mode 100644
index 05f8d42..0000000
--- a/programmer-guide/src/prerequisites.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="prerequisites">
- <title>Prerequisites</title>
-
- <section id="prerequisites-environment">
- <title>Runtime Environment</title>
- <para>
- @project.name@ requires Java SE 6 or later to be installed. Java is available from
- <ulink url="http://java.sun.com/javase/downloads/index.jsp">Sun</ulink> and elsewhere.
- </para>
- </section>
-
- <section id="prerequisites-references">
- <title>References</title>
- <para>
- To make effective use of the @tomcat.product.name@, you should also refer to the following:
- </para>
- <itemizedlist>
- <listitem><ulink url="../../virgo-user-guide/html/index.html">@project.name@ User Guide</ulink></listitem>
- <listitem><ulink url="../../virgo-tooling-guide/html/index.html">@project.name@ Tooling Guide</ulink></listitem>
- <listitem><ulink url="http://static.springframework.org/osgi/docs/current/reference/html/">Spring Dynamic Modules Reference</ulink></listitem>
- <listitem><ulink url="http://www.osgi.org/Specifications/HomePage">Blueprint Container Specification</ulink>
- (in the OSGi 4.2 and 5.0 Enterprise Specifications)</listitem>
- <listitem><ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/index.html">Spring Framework Reference</ulink></listitem>
- </itemizedlist>
- </section>
-
-</chapter>
diff --git a/programmer-guide/src/virgo-programmer-guide.xml b/programmer-guide/src/virgo-programmer-guide.xml
deleted file mode 100644
index 5ce89c8..0000000
--- a/programmer-guide/src/virgo-programmer-guide.xml
+++ /dev/null
@@ -1,73 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<book xmlns:xi="http://www.w3.org/2001/XInclude">
- <bookinfo>
- <title>@project.name@ Programmer Guide</title>
- <titleabbrev>Programmer Guide</titleabbrev>
- <productname>@project.name@</productname>
- <releaseinfo>@bundle.version@</releaseinfo>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata align="center" fileref="images/virgo-logo-small.png" format="PNG" />
- </imageobject>
- <imageobject role="html">
- <imagedata align="right" fileref="images/virgo-logo-small.png" format="PNG" />
- </imageobject>
- </mediaobject>
-
- <authorgroup>
- <author>
- <firstname>Ramnivas</firstname>
- <surname>Laddad</surname>
- </author>
- <author>
- <firstname>Colin</firstname>
- <surname>Yates</surname>
- </author>
- <author>
- <firstname>Sam</firstname>
- <surname>Brannen</surname>
- </author>
- <author>
- <firstname>Rob</firstname>
- <surname>Harrop</surname>
- </author>
- <author>
- <firstname>Christian</firstname>
- <surname>Dupuis</surname>
- </author>
- <author>
- <firstname>Andy</firstname>
- <surname>Wilkinson</surname>
- </author>
- <author>
- <firstname>Glyn</firstname>
- <surname>Normington</surname>
- </author>
- <author>
- <firstname>Steve</firstname>
- <surname>Powell</surname>
- </author>
- <author>
- <firstname>Christopher</firstname>
- <surname>Frost</surname>
- </author>
- </authorgroup>
-
- <legalnotice><para>Copyright © 2011 VMware Inc.</para></legalnotice>
- </bookinfo>
-
- <toc />
- <xi:include href="preface.xml"/>
- <xi:include href="prerequisites.xml"/>
- <xi:include href="introduction.xml"/>
- <xi:include href="architecture.xml"/>
- <xi:include href="developing-applications.xml"/>
- <xi:include href="migrating-to-osgi.xml"/>
- <xi:include href="formtags-case-study.xml"/>
- <xi:include href="common-libraries.xml"/>
- <xi:include href="known-issues.xml"/>
-
-</book>
diff --git a/settings.gradle b/settings.gradle
new file mode 100644
index 0000000..e581f23
--- /dev/null
+++ b/settings.gradle
@@ -0,0 +1,2 @@
+include 'programmer-guide'
+include 'user-guide'
diff --git a/user-guide/build.xml b/user-guide/build.xml
deleted file mode 100644
index 4a405c1..0000000
--- a/user-guide/build.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="virgo-user-guide">
-
- <property file="${basedir}/../build.properties"/>
- <property file="${basedir}/../build.versions"/>
- <import file="${basedir}/../virgo-build/docbook/default.xml"/>
-
- <filterset id="docbook.filters">
- <filter token="bundle.version" value="${bundle.version}"/>
- <filtersfile file="${basedir}/filters.properties"/>
- </filterset>
-
-</project>
diff --git a/user-guide/ivy.xml b/user-guide/ivy.xml
deleted file mode 100644
index 0db77be..0000000
--- a/user-guide/ivy.xml
+++ /dev/null
@@ -1,23 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>
-<ivy-module
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd"
- version="1.3">
-
- <info organisation="${project.organisation}" module="${ant.project.name}"/>
-
- <configurations>
- <include file="${virgo.build.dir}/common/default-ivy-configurations.xml"/>
- <conf name="doc" visibility="public" description="Documentation"/>
- </configurations>
-
- <publications>
- <!-- <artifact name="${ant.project.name}" ext="pdf" type="pdf"/> -->
- <artifact name="${ant.project.name}" ext="zip" type="zip"/>
- <artifact name="${ant.project.name}-single" ext="zip" type="zip"/>
- </publications>
-
- <dependencies/>
-
-</ivy-module>
diff --git a/user-guide/src/admin-console.xml b/user-guide/src/admin-console.xml
deleted file mode 100644
index a816dfc..0000000
--- a/user-guide/src/admin-console.xml
+++ /dev/null
@@ -1,248 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="admin-console">
- <title>The Web Admin Console</title>
- <titleabbrev>The Admin Console</titleabbrev>
- <para>The Web Server Admin Console is a Web application for managing a single instance of @tomcat.product.name@ or @jetty.product.name@
- (referred to, generically, as "Web Server" below). Using the Admin Console, you can:</para>
- <itemizedlist>
- <listitem><para><link linkend="admin-console-login">View an overview of the Web Server properties</link>.</para></listitem>
- <listitem><para><link linkend="admin-console-manage-artifacts">View and manage the lifecycle</link> of artifacts already deployed to the Web Server instance. Artifacts include bundles, configuration files, PARs, and plans. Lifecycle management tasks include starting, stopping, refreshing, and uninstalling the artifacts.</para></listitem>
- <listitem><para><link linkend="admin-console-install-artifacts">Install new artifacts to Web Server</link>.</para></listitem>
- <listitem><para><link linkend="admin-console-view-properties">View the properties of the configuration artifacts</link> deployed to Web Server.</para></listitem>
- <listitem><para><link linkend="admin-console-view-dumps">View details of dump files</link> that Web Server might have generated after encountering a problem. This feature is particularly valuable if Web Server fails to install a new artifact due to resolution failures; the OSGi state inspector can help you discover the exact artifact causing the resolution failure.</para></listitem>
- <listitem><para><link linkend="admin-console-view-osgi-state">View an overview and details of the OSGi State</link> of Web Server, or in other words, a list of all bundles currently installed in Web Server and their state. You can then drill down into the details of each bundle, such as its symbolic name, packages it imports and exports, services it provides and consumes, and so on. You can also view the bundles that were deployed when an exception that generated a dump occurred.</para></listitem>
- </itemizedlist>
- <note>
- This section is not applicable to @nano.product.name@.
- </note>
- <section id="admin-console-login">
- <title>Invoking the Admin Console</title>
- <para>
- To use the Admin Console, start the
- @tomcat.product.name@ and then enter the following URL in your
- browser of choice.
- </para>
- <screen>http://localhost:8080/admin</screen>
- <para>
- Replace <literal>localhost</literal> with the hostname of the computer on which the @tomcat.product.name@ is running if it is not the same as the computer on which you are running your browser. </para>
- <para>The Admin Console uses basic authentication, therefore you will need to enter the default administration ID and password.
- </para>
- <screen>ID: admin
-Password: admin</screen>
-
- <para>The following graphic shows the main page of the Admin Console.
- <mediaobject>
- <imageobject role="fo">
- <imagedata align="center" valign="bottom" fileref="images/console-main-page.png" format="PNG"/>
- </imageobject>
- <imageobject role="html">
- <imagedata align="right" valign="bottom" fileref="images/console-main-page.png" format="PNG"/>
- </imageobject>
- </mediaobject>
-
- </para>
-
- <para>Use the links at the top of the console to perform various tasks, such as viewing and managing artifacts (<emphasis role="bold">Artifacts</emphasis>), viewing the properties of deployed configuration artifacts (<emphasis role="bold">Configuration</emphasis>), viewing details of dumps (<emphasis role="bold">Dump Inspector</emphasis>), and viewing the OSGi state of the Web Server instance (<emphasis role="bold">OSGi State</emphasis>).</para>
-
- <para>You can always return to the main Admin Console page by clicking <emphasis role="bold">Information</emphasis> in the top right-hand corner.</para>
-
- <para>The <literal>Server Properties</literal> section provides information about Web Server itself, such as details about the Java Virtual Machine (JVM), the operating system on which Web Server is installed, the time zone configured for the computer, and the complete version of Web Server.</para>
-
- <section id="admin-console-auth">
- <title>Changing the Admin User</title>
- <para>
- To change the ID and password for the Admin Console, update the <literal>SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</literal> file. First specify the administration username by changing the value of the <literal>role.admin</literal> property. Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user. Finally, restart Web Server for the changes to take effect.</para>
- <para>For example, if you want change the administration username to <literal>juliet</literal> with password <literal>capulet</literal>, change the file as follows:
- </para>
- <programlisting>##################
-# User definitions
-##################
-user.juliet=capulet
-
-
-##################
-# Role definitions
-##################
-role.admin=juliet</programlisting>
- <para>
- The Admin Console always runs against the <literal>admin</literal> role.
- </para>
- </section>
-
- </section>
-
- <section id="admin-console-tasks">
- <title>Typical Admin Console Use Cases</title>
- <para>The following use cases describe the typical tasks that you can perform with the Admin Console:</para>
- <itemizedlist>
- <listitem><link linkend="admin-console-manage-artifacts">View and Manage the Lifecycle of Deployed Artifacts</link></listitem>
- <listitem><link linkend="admin-console-install-artifacts">Install a New Artifact</link></listitem>
- <listitem><link linkend="admin-console-view-properties">View the Properties of Deployed Configuration Artifacts</link></listitem>
- <listitem><link linkend="admin-console-view-dumps">View Details of Dump Files</link></listitem>
- <listitem><link linkend="admin-console-view-osgi-state">View Overview and Details of the OSGi State</link></listitem>
- </itemizedlist>
-
- <section id="admin-console-manage-artifacts">
- <title>Viewing and Managing the Lifecycle of Deployed Artifacts</title>
- <para>The following procedure describes how to view the list of artifacts that are currently deployed in the user region of Web Server. It then describes how to stop, start, refresh, and uninstall the deployed artifacts.</para>
- <orderedlist numeration="arabic">
- <listitem>
- <para>From the main Admin Console page, click the <emphasis role="bold">Artifacts</emphasis> link at the top.</para>
- <para>In the lower part of the page, the console displays a tree structure that displays the four kinds of artifacts that you can deploy to the user region of Web Server: bundles, configuration files, PARs, and plans. When you first install Web Server, there will already be a number of artifacts deployed related to the Admin console itself, the main splash screen, the repository, and so on. </para>
- <para>The following graphic shows an expanded tree that displays a few of the deployed artifacts:</para>
-
- <para><imagedata fileref="images/console-artifacts.png" /></para>
-
- </listitem>
-
- <listitem>
- <para>To view details of a particular artifact, click the "+" to the left of the artifact to expand the tree. The following graphic shows an expanded <literal>org.eclipse.virgo.apps.admin.web</literal> bundle:</para>
-
- <para><imagedata fileref="images/console-bundle-details.png" /></para>
-
- <para>The particular details that the Admin Console displays depends on the artifact. For example, for all artifacts you can view their state and how it was installed (such as by a user using the Admin Console or programmatically). The two most common states are Active (running and ready to be used) and Resolved (all dependencies resolved but you must start it before you can use it). An artifact can also be in one of the transition states, such as Starting and Stopping. </para>
- <para>As shown in the preceding graphic, the Admin Console provides a link for Web modules that you can click on to actually invoke the application (<literal>org.eclipse.virgo.web.contextPath:/admin</literal> in the example above).</para>
- <para>For PARs and plans, the Admin Console also displays whether the artifact is:</para>
- <itemizedlist>
- <listitem><emphasis role="bold">Scoped</emphasis>. Scoping specifies whether Web Server should deploy the members of the PAR/plan in their own scope; when scoping is disabled, Web Server deploys the artifacts into the global scope and they are accessible by all other artifacts.</listitem>
- <listitem><emphasis role="bold">Atomic</emphasis>. When a PAR/plan is atomic, Web Server manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Web Server starts all the PAR/plan artifacts. If one artifact fails to start, then Web Server stops all other artifacts in the PAR/plan.</listitem>
- </itemizedlist>
- <para>The following graphic shows details of a PAR, in particular that it is both scoped and atomic:</para>
-
- <para><imagedata fileref="images/console-par-details.png" /></para>
-
- <para>Finally, for bundles, PARs, and plans, you can see the list of bundles that they depend on; this typically means the bundles that export the packages that they import.</para>
- </listitem>
- <listitem>
- <para>To manage the lifecycle of an artifact, click on its name in the expanded tree to enable the lifecycle buttons. Then, depending on the current state of the artifact, you can: </para>
- <itemizedlist>
- <listitem>Start the artifact. All dependencies of the artifact must have been resolved for you to start it. After successfully starting the artifact, it is in the Active state and you can use the application associated with the artifact.</listitem>
- <listitem>Stop the artifact. This moves the artifact from an Active to Resolved state, and you cannot use the application associated with the artifact. </listitem>
- <listitem>Refresh the artifact. This action updates the physical contents of the artifact; use this button when you have changed the artifact in some way and you want your changes to take effect.</listitem>
- <listitem>Uninstall the artifact. This action removes the artifact from Web Server and it does not show up in the Admin Console any more. To use the application associated with this artifact, you must re-install the artifact.</listitem>
- </itemizedlist>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="admin-console-install-artifacts">
- <title>Installing a New Artifact</title>
- <para>The following procedure describes how to install a new artifact (bundle, PAR, plan, or configuration file.) The procedure is similar for all types of artifacts; the procedure uses a WAR file as an example.</para>
- <orderedlist>
- <listitem>
- <para>From the main Admin Console page, click the <emphasis role="bold">Artifacts</emphasis> link at the top.</para>
- </listitem>
- <listitem>
- <para>Click the <emphasis role="bold">Browse</emphasis> button to invoke the file loader application for your platform. Note that the Browse button searches the computer that is running the browser in which you invoked the Admin Console and <emphasis>not</emphasis> the computer on which Web Server is running, in the case where they are different.</para>
- <para>Use the file loader to find the artifact. This can be a WAR or JAR file bundle, a configuration artifact that contains properties, an XML file that corresponds to a plan, or a PAR file.</para>
- </listitem>
- <listitem>
- <para>Click <emphasis role="bold">Upload</emphasis> to actually upload the artifact to Web Server. </para>
- <para>Web Server automatically attempts to resolve all dependencies, and then puts the artifact in an Active state if possible. If all is successful, the message <literal>Artifact Deployed</literal> appears next to the <emphasis role="bold">Artifact Console</emphasis> header. If there is an error, a message to that effect is displayed; to get more details about the error, see the terminal window from which you started Web Server.</para>
- </listitem>
- <listitem>
- <para>Expand the artifact tree to view your newly deployed artifact. If Web Server installed it without errors, it should show up in the appropriate section and be in an Active state.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="admin-console-view-properties">
- <title>Viewing Properties of Deployed Configuration Artifacts</title>
- <para>The following procedure describes how you can view the list of configuration artifacts that are currently deployed to Web Server, and then view the specific properties that are defined for a particular configuration artifact. </para>
- <orderedlist>
- <listitem>
- <para>From the main Admin Console page, click the <emphasis role="bold">Configuration</emphasis> link at the top.</para>
- <para>The Admin Console displays all the configuration artifacts that are currently deployed, as shown in the following graphic:</para>
-
- <para><imagedata fileref="images/console-configuration-details.png" /></para>
- </listitem>
- <listitem>
- <para>To view the properties defined for a particular configuration artifact click the arrow to the left of its name. </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="admin-console-view-dumps">
- <title>Viewing the Details of Dump Files</title>
- <para>The following procedure describes how to view the details of any service dumps that have occurred in Web Server. Each time a dump is triggered for Web Server, the server creates a directory in <literal>$SERVER_HOME/serviceability/dump</literal> with a name corresponding to the time the dump occurred, and then the server populates the directory with detailed information. Using the Admin Console, you can easily view this information.</para>
- <para> A service dump is triggered when there is either a failure in the Web Server code or Web Server detects a thread deadlock in either its own code or a user application. The service dump contains a snapshot of all the important state from the running Web Server instance. <emphasis role="bold">NOTE:</emphasis> This snapshot is not intended for end user consumption but is useful for service personnel.</para>
-
- <orderedlist>
- <listitem>
- <para>From the main Admin Console page, click the <emphasis role="bold">Dump Inspector</emphasis> link at the top.</para>
- </listitem>
- <listitem>
- <para>In the drop-down box on the left, select the dump you want to inspect based on its timestamp.</para>
- </listitem>
- <listitem>
- <para>Click <emphasis role="bold">Select Dump</emphasis>.</para>
- </listitem>
- <listitem>
- <para>In the right drop-down box, select the type of dump information you want to view.</para>
- <para>For example, <literal>summary.txt</literal> provides a short summary of why the dump might have occurred. The <literal>thread.txt</literal> option provides information about the state of the Web Server threads at the time of the dump, including any that were deadlocked. The <literal>repository</literal> options provide information about what was in the external and user repositories at the time of the dump. The <literal>configurationAdmin.properties</literal> option provides a snapshot of the complete configuration of Web Server, including the kernel and repositories.</para>
- </listitem>
- <listitem>
- <para>Click <emphasis role="bold">Select Entry</emphasis>.</para>
- <para>The Admin Console displays the information in the Dump Entry Viewer, as shown in the following graphic:</para>
- <para><imagedata fileref="images/console-dump-details.png" /></para>
- </listitem>
- </orderedlist>
-
- <para>
- Note that the dump entry <literal>osgi.zip</literal> is a binary OSGi state dump which should be viewed as described in
- <link linkend="admin-console-view-osgi-state">Viewing Overview and Details of the OSGi State</link>.
- Dumps may contain other binary entries which are not intended for viewing via the dump inspector.
- For example, <literal>heap.out</literal> contains a dump of the Java heap and <literal>region.digraph</literal>
- contains a dump of the sharing policy between kernel and use region (this is used by the OSGi state dump inspector).
- </para>
-
- </section>
-
- <section id="admin-console-view-osgi-state">
- <title>Viewing Overview and Details of the OSGi State</title>
- <para>
- The following procedure describes how you can view the OSGi state of the Web Server, either currently or at the time that a particular service dump
- occurred.
- </para>
- <para>
- The OSGi state is a list of bundles that are currently installed. When viewing the current state, additional information is available
- such as whether each bundle is Spring powered and a list of services in the OSGi service registry. This additional information is not available
- when viewing a state dump.
- </para>
- <orderedlist>
- <listitem>
- <para>From the main Admin Console page, click the <emphasis role="bold">OSGi State</emphasis> link at the top.</para>
- <para>By default, the Admin Console displays the complete list of bundles that are currently installed in Web Server.</para>
- <para>For each bundle, the console displays its internal ID, its symbolic name, its version, and its current state (usually either Active or Resolved.)</para>
- </listitem>
- <listitem>
- <para>To view the bundles that were installed at the time of a service dump, select the service dump based on its timestamp from the drop-down box on the
- right and click <emphasis role="bold">Go</emphasis>. </para>
- </listitem>
- <listitem>
- <para>To view details about a particular bundle, click on its bundle ID. A full description of the bundle is displayed, as shown in the following graphic:</para>
- <para><imagedata fileref="images/console-osgi-state.png" /></para>
- <para>The console displays again the symbolic name, version, and internal ID of the bundle. It then displays whether the bundle is Spring powered and the exact physical location of the bundle JAR file on the computer that hosts Web Server.</para>
- <para>The console then displays the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. The console also displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages. For each package, you can drill down and view details of the corresponding bundle.</para>
- <para>Similarly, the console displays the consumed and provided OSGi services. </para>
- <para>Finally, the console also displays information about the Spring context, if the bundle is Spring powered. </para>
- </listitem>
- <listitem>
- <para>To view the full list of OSGi services, click the <literal>Services Overview</literal> link from the main OSGi state page</para>
- </listitem>
- <listitem>
- <para>Typically, the list of bundles and services can be very long, making it difficult to find a particular bundle. Use the <emphasis role="bold">Search</emphasis> box at the top right corner to narrow down the list of displayed bundles.</para>
- <para>
- Enter a package name with wildcards '<literal>*</literal>' representing part of a package name (excluding periods) and
- '<literal>**</literal>' representing one or more components of a package name separated by periods.
- For example, '<literal>**.virgo.**</literal>' displays @project.name@ packages.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- </section>
-
-</chapter>
diff --git a/user-guide/src/admin-shell.xml b/user-guide/src/admin-shell.xml
deleted file mode 100644
index 434bca8..0000000
--- a/user-guide/src/admin-shell.xml
+++ /dev/null
@@ -1,1120 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="admin-shell">
- <title>Equinox Console</title>
-
- <section id="admin-shell-enable" xreftext="Enabling the Equinox Console">
- <title>Enabling the Equinox Console</title>
-
- <para>
- Shells are provided for both user region and kernel, although they are disabled by default and need enabling before
- they can be used.
- </para>
- <para>
- The user region shell ports may be reconfigured by editing the file
- <literal>osgi.console.properties</literal> in the <literal>repository/ext</literal> directory, and
- then restarting Virgo. The telnet properties in the file are prefixed with <emphasis>telnet.</emphasis>, and the ssh properties are prefixed with <emphasis>ssh.</emphasis>.
- The kernel shell ports may be reconfigured by editing the file <literal>osgi.console.properties</literal> in the <literal>configuration</literal> directory, and then restarting Virgo.
- </para>
- <para>
- To enable any of these shell ports, change the <literal>enabled</literal> setting from <literal>false</literal> to <literal>true</literal>
- <programlisting><![CDATA[enabled=true]]></programlisting>
- in the corresponding properties files.
- </para>
- <para>
- If you wish to change a port, any free port can be used, but the usual defaults are, for telnet, 2501 for the user region and 2401 for the kernel, and
- for ssh, 2502 for the user region and 2402 for the kernel.
- </para>
- <para>
- Access is via ssh or telnet.
- The simplest way to access the shell is via telnet to port 2501 or 2401 for user region or kernel, respectively.
-<programlisting><![CDATA[prompt$ telnet localhost 2501
-Trying ::1...
-Connected to localhost.
-Escape character is '^]'.
-
-osgi> ]]></programlisting>
- </para>
- <para>
- Alternatively, you can ssh to port 2502 or 2402 for user region or kernel, respectively.
- The users and passwords for ssh are configured in <literal>configuration/org.eclipse.virgo.kernel.users.properties</literal> as described
- in <link linkend="configuring-authentication">Configuring Authentication</link>. The default user and password are <literal>admin</literal>
- and <literal>admin</literal>.
- </para>
-
- <note>
- Currently the @nano.product.name@ Equinox Console is enabled by default. Telnet is accesible on <emphasis>2401</emphasis> and SSH on <emphasis>2402</emphasis>. In future these will be configurable.
- </note>
-
- <para>
- <note>
- If you use the <literal>shutdown</literal> shell command to stop Virgo Server for Apache Tomcat, the shutdown messages appear in the shell terminal instead of in the terminal in which Virgo runs. This is due to the
- mechanisms which the shell implementation uses to redirect standard output.
- </note>
- </para>
- </section>
-
- <section id="admin-shell-using-vsh">
- <title>Using Virgo Shell Commands</title>
- <note>
- This section is not applicable to @nano.product.name@.
- </note>
- <para>Virgo provides shell commands
- that allow you to examine artifacts
- currently installed in a particular @kernel.product.name@ instance, manage the lifecycle of the installed artifacts, install new artifacts, and shut down
- the @kernel.product.name@. You can install, examine, and manage the lifecycle of the following artifacts:
- <itemizedlist>
- <listitem><para>Bundles</para></listitem>
- <listitem><para>Configuration Artifacts</para></listitem>
- <listitem><para>PARs</para></listitem>
- <listitem><para>Plans</para></listitem>
- </itemizedlist>
- </para>
- <para>
- and can examine:
- <itemizedlist>
- <listitem><para>Exported packages</para></listitem>
- <listitem><para>Services in the OSGi service registry</para></listitem>
- </itemizedlist>
- </para>
- <para>
- Virgo also provides shell commands to list all bundles that contain, export, or load a particular class.
- </para>
- <para>
- These commands are provided <emphasis>for the user region shells only</emphasis> and are grouped together in
- the <literal>vsh</literal> <emphasis>scope</emphasis>.
- </para>
- <para>You invoke commands using the <literal>vsh:</literal> scope. For example:</para>
- <programlisting><![CDATA[
-osgi> vsh:plan list
-
-Name Version State
-org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE
-org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE
-org.eclipse.virgo.web 2.1.0 ACTIVE
-
-osgi> ]]></programlisting>
-
- <section id="admin-shell-vsh-using-command-list">
- <title>Virgo Shell Commands</title>
-
- <para>The following table lists the Virgo shell commands; each command in turn has a variety of options that you can specify, depending on what you want to do, such as start a bundle or refresh a plan. The reference documentation about each command provides the full list of available options. </para>
-
- <table id="admin-shell-vsh-commands-table" colsep="1" frame="all" rowsep="1">
- <title>Virgo Shell Commands</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Command </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><link linkend="admin-shell-vsh-bundle-command">bundle</link></entry>
- <entry>Manages and displays information about bundle artifacts.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-cl-clhas">clhas</link></entry>
- <entry>Lists all bundles that <emphasis role="bold">contain</emphasis> a class or resource.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-cl-clexport">clexport</link></entry>
- <entry>Lists all bundles that <emphasis role="bold">export</emphasis> a class or package.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-cl-clload">clload</link></entry>
- <entry>Lists all bundles that can <emphasis role="bold">load</emphasis> a class.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-config-command">config</link></entry>
- <entry>Manages and displays information about configuration artifacts.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-package-command">packages</link></entry>
- <entry>Displays information about exported packages.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-par-command">par</link></entry>
- <entry>Manages and displays information about PAR artifacts.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-plan-command">plan</link></entry>
- <entry>Manages and displays information about plan artifacts.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-service-command">service</link></entry>
- <entry>Displays information about services in the OSGi service registry.</entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-install-command">install</link></entry>
- <entry>Installs an artifact to @kernel.product.name@. </entry>
- </row>
- <row>
- <entry><link linkend="admin-shell-vsh-shutdown-command">shutdown</link></entry>
- <entry>Shuts down the @kernel.product.name@ instance to which the Equinox Console is connected.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- </section>
-
- <section id="admin-shell-vsh-command-reference">
- <title>Virgo Shell Command Reference</title>
-
- <para>
- This section contains reference information about the Virgo shell commands
- <link linkend="admin-shell-vsh-bundle-command">bundle</link>,
- <link linkend="admin-shell-cl-clhas">clhas</link>,
- <link linkend="admin-shell-cl-clexport">clexport</link>,
- <link linkend="admin-shell-cl-clload">clload</link>,
- <link linkend="admin-shell-vsh-config-command">config</link>,
- <link linkend="admin-shell-vsh-package-command">packages</link>,
- <link linkend="admin-shell-vsh-par-command">par</link>,
- <link linkend="admin-shell-vsh-plan-command">plan</link>,
- <link linkend="admin-shell-vsh-service-command">service</link>,
- <link linkend="admin-shell-vsh-install-command">install</link>,
- <link linkend="admin-shell-vsh-shutdown-command">shutdown</link>,
- <link linkend="admin-shell-vsh-help-command">help</link>, and
- <link linkend="admin-shell-vsh-exit-command">exit</link>.
- </para>
-
-
- <section id="admin-shell-vsh-bundle-command">
- <title>bundle Command</title>
-
- <para>Use the <literal>bundle</literal> command to manage the lifecycle of bundles deployed in @kernel.product.name@ and to gather information about deployed bundles, such as diagnostic information, header information, and so on. </para>
- <para>The following table lists the options you can specify for this command.</para>
-
- <table id="admin-shell-vsh-bundle-command-table" colsep="1" frame="all" rowsep="1">
- <title>Options of the bundle Command</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>list</entry>
- <entry>Displays the list of bundles that are currently installed in the current @kernel.product.name@ instance. With the exception of a few kernel bundles and their services, which @kernel.product.name@ uses to administer the user region, none of the kernel is visible to user installed artifacts; rather, only the bundles installed in the user region are visible.
- <para>Each bundle is identified by an internal <literal>ID</literal> which you can then use with the other <literal>bundle</literal> commands that manage a particular bundle, such as <literal>start </literal><emphasis><literal>id</literal></emphasis>. The <literal>list</literal> command also displays the version of the bundle, along with its state, which is one of the following standard OSGi lifecycle states:</para>
- <itemizedlist>
- <listitem><para><emphasis role="bold">Installed</emphasis>: The bundle is installed but its dependencies have not yet been resolved.</para></listitem>
- <listitem><para><emphasis role="bold">Resolved</emphasis>: The bundle is resolved and you can now start it.</para></listitem>
- <listitem><para><emphasis role="bold">Uninstalled</emphasis>: The bundle is uninstalled and you cannot use it.</para></listitem>
- <listitem><para><emphasis role="bold">Starting</emphasis>: The bundle is in the process of starting.</para></listitem>
- <listitem><para><emphasis role="bold">Active</emphasis>: The bundle is running and you can now use it.</para></listitem>
- <listitem><para><emphasis role="bold">Stopping</emphasis>: The bundle is in the process of stopping.</para></listitem>
- </itemizedlist>
- <para>Use one of the other <literal>bundle</literal> commands to change the state of a bundle. For example, use the <literal>bundle start </literal><emphasis><literal>id</literal></emphasis> command to change the state of a bundle from <literal>Installed</literal> to <literal>Active</literal>.</para>
- </entry>
- </row>
- <row>
- <entry>examine <emphasis>id</emphasis></entry>
- <entry>Displays detailed information about the specified bundle. Use the <literal>bundle list</literal> command to get the internal id of a particular bundle.
- <para>In addition to the information provided by the <literal>bundle list</literal> command (id, full name, version, and state), the <literal>examine</literal> command specifies whether the bundle includes a Spring application context (or is <emphasis>Spring Powered</emphasis>) and the exact physical location of the bundle JAR file. </para>
- <para>The <literal>examine</literal> also provides the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. Finally, the command displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages. </para>
- </entry>
- </row>
- <row>
- <entry>start <emphasis>id</emphasis></entry>
- <entry>Starts the specified bundle. Use the <literal>bundle list</literal> command to get the internal id of a particular bundle.
- <para>After @kernel.product.name@ successfully starts the bundle, it is listed in the <literal>Active</literal> state. </para>
- </entry>
- </row>
- <row>
- <entry>stop <emphasis>id</emphasis></entry>
- <entry>Stops the specified bundle. Use the <literal>bundle list</literal> command to get the internal id of a particular bundle.
- <para>When you stop a bundle, it goes from the <literal>Active</literal> state to the <literal>Resolved</literal> state, and you must re-start it if you want to use the application that the bundle contains.</para> </entry>
- </row>
- <row>
- <entry>refresh <emphasis>id</emphasis></entry>
- <entry>Updates the contents of the specified bundle. Use the <literal>bundle list</literal> command to get the internal id of a particular bundle. Use this command if you have changed the contents of the bundle JAR file and you want to refresh the artifact as installed in the OSGi framework.
- </entry>
- </row>
- <row>
- <entry>uninstall <emphasis>id</emphasis></entry>
- <entry>Uninstalls the specified bundle from @kernel.product.name@. Use the <literal>bundle list</literal> command to get the internal id of a particular bundle.
- <para>When the uninstall process is complete, the bundle does not show up in the list of bundles displayed by the <literal>bundle list</literal> command. If you want to use the application in the bundle, you must re-install it using the <literal>install</literal> command.</para>
- </entry>
- </row>
- <row>
- <entry>diag <emphasis>id</emphasis></entry>
- <entry>
- <para>
- Provides diagnostic information about the specified bundle.
- In particular, this command displays information about the imported packages that @kernel.product.name@ could not resolve.
- Use the <literal>bundle list</literal> command to get the internal id of a particular bundle.
- </para>
- <para>
- Note that @project.name@ does not install unresolvable bundles.
- Instead is takes a state dump (for offline analysis using the web administration console) and fails the deployment.
- So bundles are only likely to become unresolvable in @project.name@ after an update operation.
- </para>
- </entry>
- </row>
- <row>
- <entry>headers <emphasis>id</emphasis></entry>
- <entry>Displays the complete list of manifest headers of the specified bundle. Use the <literal>bundle list</literal> command to get the internal id of a particular bundle.
- <para>The manifest headers include: <literal>Import-Package</literal>, <literal>Export-Package</literal>, <literal>Bundle-SymbolicName</literal>, and so on. </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following examples show how to use this command.</para>
-
- <para>First, use the <literal>bundle list</literal> command to view all the installed bundles:</para>
-
- <programlisting>osgi> vsh:bundle list
-
-Id Name Version State
-40 org.eclipse.virgo.kernel.userregionfactory 3.0.0.RELEASE ACTIVE
-47 org.eclipse.equinox.cm 1.0.300.v20101204 ACTIVE
-48 org.eclipse.virgo.kernel.userregion 3.0.0.RELEASE ACTIVE
-49 org.eclipse.virgo.kernel.osgicommand 3.0.0.RELEASE ACTIVE
-50 org.eclipse.osgi.services 3.3.0.v20110110 ACTIVE
-51 com.springsource.org.apache.mina.core 2.0.2 ACTIVE
-52 org.apache.felix.gogo.command 0.8.0.v201105062003 ACTIVE
-53 org.apache.felix.gogo.runtime 0.8.0.v201105062003 ACTIVE
-54 org.apache.felix.gogo.shell 0.8.0.v201107131313 ACTIVE
-55 org.eclipse.equinox.console.supportability 1.0.0.20110722-2 ACTIVE
-56 com.springsource.org.apache.sshd.core 0.5.0 ACTIVE
-57 org.springframework.osgi.core 1.2.1 ACTIVE
-58 S org.springframework.osgi.extender 1.2.1 ACTIVE
-59 org.springframework.osgi.io 1.2.1 ACTIVE
-60 org.eclipse.virgo.kernel.agent.dm 3.0.0.RELEASE ACTIVE
-61 S org.eclipse.virgo.kernel.deployer.dm 3.0.0.RELEASE ACTIVE
-62 org.eclipse.equinox.ds 1.3.0.v20110124-0830 ACTIVE
-63 org.eclipse.equinox.util 1.0.200.v20100503 ACTIVE
-64 com.springsource.org.aopalliance 1.0.0 ACTIVE
-65 org.eclipse.virgo.kernel.dmfragment 3.0.0.RELEASE RESOLVED
-66 org.springframework.aop 3.0.5.RELEASE ACTIVE
-67 org.springframework.asm 3.0.5.RELEASE ACTIVE
-68 org.springframework.beans 3.0.5.RELEASE ACTIVE
-69 org.springframework.context 3.0.5.RELEASE ACTIVE
-70 org.springframework.core 3.0.5.RELEASE ACTIVE
-71 org.springframework.expression 3.0.5.RELEASE ACTIVE
-osgi> </programlisting>
-
- <para>The following example shows how to view the headers of the <literal>org.springframework.osgi.extender</literal> bundle (only the first few lines are shown):</para>
-
- <programlisting>osgi> vsh:bundle examine 5
-
-Id: 5
-Name: org.springframework.osgi.extender
-Version 1.2.1
-State: ACTIVE
-Spring Powered: true
-Bundle Location: file:<... omitted ...>/org.springframework.osgi.extender-1.2.1.jar/
-
-Imported Packages:
- org.springframework.osgi.context [1.2.1, 1.2.1]
- exported by org.springframework.osgi.core 1.2.1 [4]
- <... remainder omitted ...>
-
-Exported Packages:
- org.springframework.osgi.extender 1.2.1
- <... remainder omitted ...>
-
-Published services:
- 58 org.springframework.beans.factory.xml.NamespaceHandlerResolver
- consumed by org.springframework.osgi.extender 1.2.1 [5]
- consumed by org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE [8]
- <... remainder omitted ...>
-
-Consumed services:
- 1 org.osgi.service.packageadmin.PackageAdmin
- published by org.eclipse.osgi 3.7.0.v20110224 [0]
- <... remainder omitted ...>
-
-Fragments:
- org.eclipse.virgo.kernel.dmfragment 2.1.0.RELEASE [10]
-
-osgi> </programlisting>
-
- </section>
- <section id="admin-shell-vsh-config-command">
- <title>config Command</title>
-
- <para>Use the <literal>config</literal> command to view and manage the configuration artifacts that have been installed in @kernel.product.name@. A <emphasis>configuration artifact</emphasis> is simply a properties file that is associated with a user application that is contained in a bundle. Using configuration artifacts, you can manage the configuration of a user application completely separately from the bundle that contains the application. </para>
- <para>The following table lists the options you can specify for this command.</para>
-
- <table id="admin-shell-vsh-config-command-table" colsep="1" frame="all" rowsep="1">
- <title>Options of the config Command</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>list</entry>
- <entry>Lists the configuration artifacts that are currently installed in @kernel.product.name@.
- <para>The <literal>list</literal> option displays the full name of each installed configuration artifact, its version, and its current state. Configuration artifacts have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a configuration can be in is the same as those of bundles; see <link linkend="admin-shell-bundle-command">the bundle command</link> for the list of possible states. </para>
- </entry>
- </row>
- <row>
- <entry>examine <emphasis>name [version]</emphasis></entry>
- <entry>Displays information about the specified configuration artifact. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the <literal>config list</literal> command to view all configuration artifacts and versions currently installed in @kernel.product.name@.
- <para>A configuration artifact must be active for you to examine it; if it is not currently active, use <literal>config start</literal> to start it and thus change its state to <literal>Active</literal>.</para>
- <para>The command first displays the factory pid of the configuration artifact as well as the complete location of the bundle to which the configuration artifact is associated. The command then lists all the properties that make up the configuration, as well as their current value. </para> </entry>
- </row>
- <row>
- <entry>start <emphasis>name [version]</emphasis></entry>
- <entry>
- <para>
- Starts the specified configuration artifact and makes it visible to @kernel.product.name@.
- Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the
- configuration artifact installed (which @project.name@ does not currently support).
- Use the <literal>config list</literal> command to view all configuration artifacts and versions currently installed in @kernel.product.name@.
- </para>
- <para>
- Starting the configuration sets its state to <literal>Active</literal>.
- </para>
- </entry>
- </row>
- <row>
- <entry>stop <emphasis>name [version]</emphasis></entry>
- <entry>Stops the specified configuration artifact and makes it invisible to @kernel.product.name@. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which @project.name@ does not currently support). Use the <literal>config list</literal> command to view all configuration artifacts and versions currently installed in @kernel.product.name@.
-
- <para>Stopping the configuration sets its state to <literal>Resolved</literal>.</para></entry>
- </row>
- <row>
- <entry>refresh <emphasis>name [version]</emphasis></entry>
- <entry>Updates the contents of the specified configuration artifact to @kernel.product.name@. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which @project.name@ does not currently support). Use the <literal>config list</literal> command to view all configuration artifacts and versions currently installed in @kernel.product.name@.
-
- <para>Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to @kernel.product.name@ and the associated bundle. </para></entry>
- </row>
- <row>
- <entry>uninstall <emphasis>name [version]</emphasis></entry>
- <entry>Uninstalls the specified configuration artifact and make it completely unavailable to @kernel.product.name@. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which @project.name@ does not currently support). Use the <literal>config list</literal> command to view all configuration artifacts and versions currently installed in @kernel.product.name@.
-
- <para>Stopping the configuration removes it from @kernel.product.name@'s list of deployed artifacts and it will not show up when you perform a <literal>config list</literal>.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following example shows how to use this command to list the installed configuration artifacts.</para>
- <programlisting>osgi> vsh:config list
-
-Name Version State
-org.eclipse.virgo.kernel 0.0.0 ACTIVE
-org.eclipse.virgo.kernel.jmxremote.access 0.0.0 ACTIVE
-org.eclipse.virgo.kernel.userregion 0.0.0 ACTIVE
-org.eclipse.virgo.kernel.users 0.0.0 ACTIVE
-org.eclipse.virgo.medic 0.0.0 ACTIVE
-org.eclipse.virgo.repository 0.0.0 ACTIVE
-osgi.console.ssh 0.0.0 ACTIVE
-osgi.console.telnet 0.0.0 ACTIVE
-
-osgi> </programlisting>
-
- <para>To view the properties of a configuration artifact, and their current values, use <literal>config examine</literal>:</para>
-
- <programlisting>osgi> vsh:config examine org.eclipse.virgo.repository
-
-Factory pid:
-Bundle Location: file:plugins/org.eclipse.virgo.kernel.services-@bundle.version@.jar
-
-Properties:
- chain:
- ext,usr
- ext.searchPattern:
- repository/ext/{artifact}
- ext.type:
- external
- service.pid:
- org.eclipse.virgo.repository
- usr.type:
- watched
- usr.watchDirectory:
- repository/usr
-osgi> </programlisting>
-
- </section>
- <section id="admin-shell-vsh-package-command">
- <title>packages Command</title>
-
- <para>Use the <literal>packages</literal> command to view the complete list of packages exported by all bundles installed in @kernel.product.name@, as well as examine a particular exported package in more detail.</para>
-
- <para>The following table lists the options you can specify for this command.</para>
-
- <table id="admin-shell-vsh-package-command-table" colsep="1" frame="all" rowsep="1">
- <title>Options of the packages Command</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>list</entry>
- <entry>Displays all the exported packages for all bundles in the uer region of @kernel.product.name@. In addition to the package name, the command displays the version of the exported package and the <literal>id</literal> of the bundle that contains the exported package. You can examine the bundle by using the command <literal>bundle examine </literal><emphasis><literal>id</literal></emphasis>.</entry>
- </row>
- <row>
- <entry>examine <emphasis>name version</emphasis></entry>
- <entry>Displays details about the exported package. You must specify both the name of the exported package and its version; use <literal>packages list</literal> to view the exact names and version.
- <para>This command provides the following additional information about the exported package:</para>
-
- <itemizedlist>
- <listitem><para>The name and version of the bundle that exports the package. This means that the package name is explicitly listed in the bundle's <literal>MANIFEST.MF</literal> file as part of the <literal>Export-Package</literal> header.</para></listitem>
- <listitem><para>Any attributes that are part of the <literal>Export-Package</literal>, in addition to <literal>version</literal>.</para></listitem>
- <listitem><para>The directives that are part of the <literal>Export-Package</literal> header. A typical directive is <literal>uses</literal>, which declares up-front constraints on a number of other packages.</para></listitem>
- <listitem><para>The list of all bundles that import the package.</para></listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following example shows how to list all the exported packages for all bundles installed:</para>
- <programlisting>osgi> vsh:packages list
-
-Name Version Providing Bundle
-javax.accessibility 0.0.0 0
-javax.activation 0.0.0 0
-javax.activation 1.1.1 0
-<... remainder omitted ...>
-
-osgi> </programlisting>
-
- <para>The following example shows how to examine a particular exported package:</para>
- <programlisting>osgi> vsh:packages examine org.slf4j 1.6.1
-
-Exporter: org.eclipse.virgo.region.user 0.0.0 [1]
-
-Attributes:
- None
-
-Directives:
- uses:
- org.slf4j.spi
- x-equinox-ee:
- -1
- x-internal:
- false
-
-Importer(s):
- org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE [7]
- Import-Package attributes:
- bundle-version:
- 0.0.0
- version:
- [1.6.1,2.0.0)
- Import-Package directives:
- resolution:
- static
- <... remainder omitted ...>
-
-osgi> </programlisting>
-
-
- </section>
- <section id="admin-shell-vsh-par-command">
- <title>par Command</title>
-
- <para>Use the <literal>par</literal> command to view all the PARs currently installed in @kernel.product.name@, view details about a particular PAR and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.</para>
- <para>The following table lists the options you can specify for this command.</para>
-
- <table id="admin-shell-vsh-par-command-table" colsep="1" frame="all" rowsep="1">
- <title>Options of the par Command</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>list</entry>
- <entry>Displays all the PARs that are currently installed in @kernel.product.name@.
- <para>The <literal>list</literal> option displays the full name of each installed PAR, its version, and its current state. PARs have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a PAR can be in is the same as those of bundles; see <link linkend="admin-shell-bundle-command">the bundle command</link> for the list of possible states. </para></entry>
- </row>
- <row>
- <entry>examine <emphasis>name version</emphasis></entry>
- <entry>Displays information about the specified PAR; you are required to identify the PAR with both its name and its version. Use the <literal>par list</literal> command to view all installed PAR files and their versions. The command displays the following information:
- <itemizedlist>
- <listitem><para>The current state of the PAR (see <link linkend="admin-shell-vsh-bundle-command">the bundle command</link> for the full list of possible states).</para></listitem>
- <listitem><para>Whether the PAR is <emphasis>scoped</emphasis>. Scoping specifies whether @kernel.product.name@ should deploy the members of the PAR in their own scope; when scoping is disabled, @kernel.product.name@ deploys the artifacts into the global scope and they are accessible for access by all other artifacts.</para></listitem>
- <listitem><para>Whether the PAR is <emphasis>atomic</emphasis>. When a PAR is atomic, @kernel.product.name@ manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then @kernel.product.name@ starts <emphasis>all</emphasis> the PAR artifacts. If one artifact fails to start, then @kernel.product.name@ stops all other artifacts in the PAR.</para></listitem>
- <listitem><para>The individual members, or children, of the PAR. These could be plans, bundles, configuration artifacts, and so on.</para></listitem>
- </itemizedlist>
- </entry>
- </row>
- <row>
- <entry>start <emphasis>name version</emphasis></entry>
- <entry>Starts the specified PAR. You must specify both the full name of the PAR as well as the version you want to start. Use the <literal>par list</literal> command to get the list of PARs currently installed in @kernel.product.name@.
- <para>To start a PAR, it must have already been resolved by @kernel.product.name@, or in other words, be in the <literal>Resolved</literal> state. After @kernel.product.name@ successfully starts the PAR, it is listed in the <literal>Active</literal> state. </para></entry>
- </row>
- <row>
- <entry>stop <emphasis>name version</emphasis></entry>
- <entry>Stops the specified PAR. You must specify both the full name of the PAR as well as the version you want to stop. Use the <literal>par list</literal> command to get the list of PARs currently installed in @kernel.product.name@.
- <para>When you stop a PAR, it goes from the <literal>Active</literal> state to the <literal>Resolved</literal> state, and you must re-start it if you want to use the application that the PAR contains.</para> </entry>
- </row>
- <row>
- <entry>refresh <emphasis>name version</emphasis></entry>
- <entry>Updates the contents of the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the <literal>par list</literal> command to this information.
- <para>Use this command if you have changed the contents of the PAR file and you want to refresh the artifact as installed in the OSGi framework.</para></entry>
- </row>
- <row>
- <entry>uninstall <emphasis>name version</emphasis></entry>
- <entry>Uninstalls the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the <literal>par list</literal> command to this information.
- <para>When the uninstall process is complete, the PAR will not show up in the list of PARs displayed by the <literal>par list</literal> command. If you want to use the application in the PAR, you must re-install it using the <literal>install</literal> command.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following example shows how to list the PARs that have been installed in @kernel.product.name@:</para>
- <programlisting>osgi> vsh:par list
-
-Name Version State
-
-org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE ACTIVE
-
-osgi> </programlisting>
-
- <para>The following example shows how to examine a particular PAR file:</para>
- <programlisting>osgi> vsh:par examine org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE
-
-State: ACTIVE
-Scoped: true
-Atomic: true
-
-Children:
- bundle org.eclipse.virgo.server.repository.hosted.core 2.1.0.RELEASE
- bundle org.eclipse.virgo.server.repository.hosted.web 2.1.0.RELEASE
- bundle org.eclipse.virgo.server.repository.hosted-synthetic.context 2.1.0.RELEASE
-
-osgi> </programlisting>
-
- <para>Finally, the following example shows how to refresh an installed PAR file:</para>
- <programlisting>osgi> vsh:par refresh my.exciting.par 1.2.0
-
-par my.exciting.par 1.2.0 refreshed successfully
-
-osgi> </programlisting>
-
- </section>
- <section id="admin-shell-vsh-plan-command">
- <title>plan Command</title>
-
- <para>Use the <literal>plan</literal> command to view all the plans currently installed in @kernel.product.name@, view details about a particular plan and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.</para>
- <para>The following table lists the options you can specify for this command.</para>
-
- <table id="admin-shell-vsh-plan-command-table" colsep="1" frame="all" rowsep="1">
- <title>Options of the plan Command</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>list</entry>
- <entry>Displays all the plans that are currently installed in @kernel.product.name@.
- <para>The <literal>list</literal> option displays the full name of each installed plan, its version, and its current state. Plans have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a plan can be in is the same as those of bundles; see <link linkend="admin-shell-bundle-command">the bundle command</link> for the list of possible states. </para></entry>
- </row>
- <row>
- <entry>examine <emphasis>name version</emphasis></entry>
- <entry>Displays information about the specified plan; you are required to identify the plan with both its name and its version. Use the <literal>plan list</literal> command to view all installed plans and their versions. The command displays the following information:
- <itemizedlist>
- <listitem><para>The current state of the plan (see <link linkend="admin-shell-vsh-bundle-command">the bundle command</link> for the full list of possible states).</para></listitem>
- <listitem><para>Whether the plan is <emphasis>scoped</emphasis>. Scoping specifies whether @kernel.product.name@ should deploy the members of the plan in their own scope; when scoping is disabled, @kernel.product.name@ deploys the artifacts into the global scope and they are accessible for access by all other artifacts.</para></listitem>
- <listitem><para>Whether the plan is <emphasis>atomic</emphasis>. When a plan is atomic, @kernel.product.name@ manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then @kernel.product.name@ starts <emphasis>all</emphasis> the plan artifacts. If one artifact fails to start, then @kernel.product.name@ stops all other artifacts in the plan.</para></listitem>
- <listitem><para>The individual members, or children, of the plan. These could be other plans, PARs, bundles, configuration artifacts, and so on.</para></listitem>
- </itemizedlist>
- </entry>
- </row>
- <row>
- <entry>start <emphasis>name version</emphasis></entry>
- <entry>Starts the specified plan. You must specify both the full name of the plan as well as the version you want to start. Use the <literal>plan list</literal> command to get the list of plans currently installed in @kernel.product.name@.
- <para>To start a plan, it must have already been resolved by @kernel.product.name@, or in other words, be in the <literal>Resolved</literal> state. After @kernel.product.name@ successfully starts the plan, it is listed in the <literal>Active</literal> state. </para></entry>
- </row>
- <row>
- <entry>stop <emphasis>name version</emphasis></entry>
- <entry>Stops the specified plan. You must specify both the full name of the plan as well as the version you want to stop. Use the <literal>plan list</literal> command to get the list of plans currently installed in @kernel.product.name@.
- <para>When you stop a plan, it goes from the <literal>Active</literal> state to the <literal>Resolved</literal> state, and you must re-start it if you want to use the application that the plan contains.</para> </entry>
- </row>
- <row>
- <entry>refresh <emphasis>name version</emphasis></entry>
- <entry>Updates the contents of the specified plan. You must specify both the name and version of the plan you want to refresh. Use the <literal>plan list</literal> command to this information.
- <para>Use this command if you have changed the contents of the plan file and you want to refresh the artifact as installed in the OSGi framework.</para></entry>
- </row>
- <row>
- <entry>uninstall <emphasis>name version</emphasis></entry>
- <entry>Uninstalls the specified plan. You must specify both the name and version of the plan you want to refresh. Use the <literal>plan list</literal> command to this information.
- <para>When the uninstall process is complete, the plan will not show up in the list of plans displayed by the <literal>plan list</literal> command. If you want to use the application in the plan, you must re-install it using the <literal>install</literal> command.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following example shows how to list the plans that have been installed in @kernel.product.name@:</para>
- <programlisting><![CDATA[
-osgi> vsh:plan list
-
-Name Version State
-org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE
-org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE
-org.eclipse.virgo.web 2.1.0 ACTIVE
-
-osgi> ]]></programlisting>
-
- <para>The following example shows how to examine a particular plan:</para>
- <programlisting>osgi> vsh:plan examine org.eclipse.virgo.kernel.userregion.springdm 2.1.0
-
-State: ACTIVE
-Scoped: false
-Atomic: false
-
-Children:
- bundle org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE
- bundle org.springframework.osgi.io 1.2.1
- bundle org.springframework.osgi.extender 1.2.1
- bundle org.springframework.osgi.core 1.2.1
- bundle org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE
-
-osgi> </programlisting>
-
- <para>The following example shows how to stop a currently Active plan:</para>
- <programlisting>osgi> vsh:plan stop org.eclipse.virgo.web 2.1.0
-
-plan org.eclipse.virgo.web:2.1.0 stopped successfully
-
-osgi> </programlisting>
-
- <para>The following example shows how to start a plan:</para>
-
- <programlisting>osgi> vsh:plan start org.eclipse.virgo.web 2.1.0
-
-plan org.eclipse.virgo.web:2.1.0 started successfully
-
-osgi> </programlisting>
-
- </section>
- <section id="admin-shell-vsh-service-command">
- <title>service Command</title>
-
- <para>Use the <literal>service</literal> command to view all the services that have been registered in the OSGi service registry of @kernel.product.name@. You can also examine a specific service to discover its properties, the bundle that publishes the service, and any bundles that consume the service.</para>
- <para>The following table lists the options you can specify for this command.</para>
-
- <table id="admin-shell-vsh-service-command-table" colsep="1" frame="all" rowsep="1">
- <title>Options of the service Command</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option </entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>list</entry>
- <entry>Displays the list of services that are currently registered in the OSGi service registry of @kernel.product.name@.
- <para>Each service is identified by an internal <literal>ID</literal> which you can then use with the <literal>service examine</literal> command to view the details about a particular service. The <literal>list</literal> option also displays the object class that implements the service and the internal <literal>id</literal> of the bundle that provides the service. </para></entry>
- </row>
- <row>
- <entry>examine <emphasis>id</emphasis></entry>
- <entry>Displays detailed information about the specified service. Use the <literal>service list</literal> command to get the internal id of a particular service.
- <para>This command displays the properties of the service, such as the object class that implements the service, the name of the bundle that publishes the service and any bundles that consume the service. </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following example shows how to list the services currently registered in the OSGi service registry:</para>
- <programlisting>osgi> vsh:service list
-
-Id Object Class(es) Providing Bundle
-
-1 org.osgi.service.packageadmin.PackageAdmin 0
-2 org.osgi.service.permissionadmin.PermissionAdmin, ... 0
-3 org.osgi.service.startlevel.StartLevel 0
-4 org.eclipse.osgi.service.debug.DebugOptions 0
-5 java.lang.ClassLoader 0
-6 org.eclipse.osgi.framework.log.FrameworkLog 0
-7 org.eclipse.osgi.framework.log.FrameworkLog 0
-<... remainder omitted ...>
-
-72 org.eclipse.gemini.web.core.spi.ServletContainer 38
-73 org.eclipse.gemini.web.core.WebContainer 37
-74 org.eclipse.virgo.web.core.WebApplicationRegistry 39
-<... remainder omitted ...>
-
-osgi> </programlisting>
-
- <para>The following example shows how to examine a particular service:</para>
- <programlisting>osgi> vsh:service examine 73
-
- Properties:
- objectClass:
- org.eclipse.gemini.web.core.WebContainer
- service.id:
- 73
-
- Publisher: org.eclipse.gemini.web.core 1.1.0.RELEASE [37]
-
- Consumer(s):
- org.eclipse.virgo.web.core 2.1.0.RELEASE [39]
-
- osgi> </programlisting>
-
- </section>
- <section id="admin-shell-vsh-install-command">
- <title>install Command</title>
-
- <para>Use the <literal>install</literal> command to deploy an artifact to @kernel.product.name@. The artifact can be a bundle, PAR, plan, or configuration artifact.</para>
-
- <para>The <literal>install</literal> command takes a single parameter: the URI of the artifact you want to deploy. For example, to deploy a bundle on the local computer, use the <literal>file</literal> scheme:</para>
-
- <programlisting>file://full-pathname-to-artifact</programlisting>
-
- <para>After you execute the <literal>install</literal> command, @kernel.product.name@ attempts to resolve the artifact's dependencies, and if it is successful, puts it in the <literal>Resolved</literal> state. At that point, you must start the artifact to be able to actually use it. </para>
-
- <para>The following example shows how to install a bundle called <literal>swf-booking-mvc.war</literal> located in the <literal>/home/apps</literal> directory of the computer on which the Equinox Console Extension is being run:</para>
-
- <programlisting>osgi> vsh:install file://home/apps/swf-booking-mvc.war
-...
-Artifact bundle swf-booking-mvc.war 0.0.0 installed</programlisting>
-
- <para>
- This command is particularly useful for installing an artifact from the @project.name@ repository, in which case use the <literal>repository:</literal> scheme:
- <programlisting>repository:artifact-type/bundle-symbolic-name/bundle-version</programlisting>
- For example:
- </para>
- <programlisting>osgi> vsh:install repository:bundle/my.bundle/1.0
-...
-Artifact bundle my.bundle 1.0.0 installed
-osgi></programlisting>
-
- <para>The following example shows how to use the <literal>bundle list</literal> command to ensure that the bundle was indeed installed in @kernel.product.name@; if you had installed a different kind of artifact, for example a plan, then you would use the appropriate command (such as <literal>plan list</literal>):</para>
-
- <programlisting>osgi> vsh:bundle list
-
-Id Name Version State
-
-0 org.eclipse.osgi 3.6.1.R36x_v20100806 ACTIVE
-1 org.eclipse.virgo.region.user 0.0.0 ACTIVE
-<... remainder omitted ...>
-
-59 org.eclipse.virgo.server.splash 2.1.0.RELEASE ACTIVE
-60 swf-booking-mvc.war 0.0.0 RESOLVED
-
-osgi> </programlisting>
-
- <para>Note that the <literal>swf-booking-mvc.war</literal> file is in the <literal>Resolved</literal> state. The following examples start the bundle, and then examine it to ensure that it is in the <literal>Active</literal> state:</para>
- <programlisting>osgi> vsh:bundle start 60
-
-bundle swf-booking-mvc.war:0.0.0 started successfully
-
-
-osgi> vsh:bundle examine 60
-
-Id: 60
-Name: swf-booking-mvc.war
-Version 0.0.0
-State: ACTIVE
-Spring Powered: true
-Bundle Location: file:<... omitted ...>/swf-booking-mvc.war/
-
-Imported Packages:
- javax.crypto.interfaces [0.0.0, 0.0.0]
- exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
- org.omg.CosNaming.NamingContextPackage [0.0.0, 0.0.0]
- exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
- org.omg.DynamicAny.DynAnyFactoryPackage [0.0.0, 0.0.0]
- exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
- <... remainder omitted ...>
-
-osgi> </programlisting>
-
- </section>
- <section id="admin-shell-vsh-shutdown-command">
- <title>shutdown Command</title>
-
- <para>Use the <literal>shutdown</literal> command to shut down the @kernel.product.name@ instance to which you are connected. When @kernel.product.name@ is shut down, the shell returns you to the operating system prompt. </para>
- <para>The <literal>shutdown</literal> command does not have any options.</para>
-
- <para>The following example shows how to use this command.</para>
-
- <programlisting>osgi> vsh:shutdown
-osgi> ...
-Connection closed by foreign host.
-prompt$</programlisting>
-
- </section>
- <section id="admin-shell-cl-clhas">
- <title>clhas command</title>
- <para>Use the <literal>clhas</literal> command to list the entries contained in the bundles deployed in @project.name@ and to solve class loading issues.</para>
- <para>The command accepts as a parameter a search pattern in the form <emphasis>path/resource</emphasis>. The resource part of the pattern can contain wildcards.</para>
- <para>The output contains all bundles that have resources or classes matching the pattern. Since wildcards are allowed, the matching entities are listed as well.</para>
-
- <para>The following examples show how to use this command.</para>
- <para>Use the <literal>clhas</literal> to view all bundles that contain <literal>Servlet</literal> class:</para>
- <programlisting>osgi>clhas /javax/servlet/Servlet.class
-
-Bundles containing [/javax/servlet/Servlet.class]:
- 76 javax.servlet
- /javax/servlet/Servlet.class</programlisting>
-
- <para>Use the wildcard <literal>*</literal> with <literal>clhas</literal> to view all classes starting with <literal>Servlet</literal>:</para>
- <programlisting>osgi> clhas /javax/servlet/Servlet*
-
-Bundles containing [/javax/servlet/Servlet*]:
- 76 javax.servlet
- /javax/servlet/ServletRequestAttributeEvent.class
- /javax/servlet/ServletRequest.class
- <... remainder omitted ...>
- /javax/servlet/Servlet.class
- <... remainder omitted ...></programlisting>
-
- <para>The <literal>clhas</literal> command can also be used with class name instead of resource path:</para>
- <programlisting>osgi> clhas javax.servlet.Servlet
-
-Bundles containing [javax/servlet/Servlet.class]:
- 76 javax.servlet
- /javax/servlet/Servlet.class</programlisting>
- <para>Please note that the command converts the class name to a path and appends <literal>class</literal> extension by default.</para>
- <para>To search for a resource with an extension different than <literal>class</literal> you should use the resource path form:</para>
- <programlisting>osgi> clhas /LocalStrings.properties
-
-Bundles containing [/LocalStrings.properties]:
- 96 com.springsource.org.apache.catalina
- /org/apache/catalina/core/LocalStrings.properties
- /org/apache/tomcat/util/http/mapper/LocalStrings.properties
- /org/apache/catalina/loader/LocalStrings.properties
- <... remainder omitted ...></programlisting>
-
- <para>The following example shows how to identify a possible <literal>ClassCastException</literal> due to wrong packaging:</para>
- <programlisting>osgi>clhas /javax/servlet/Servlet.class
-
-Bundles containing [/javax/servlet/Servlet.class]:
- 76 javax.servlet
- /javax/servlet/Servlet.class
- 107 myapp
- /WEB-INF/classes/javax/servlet/Servlet.class</programlisting>
- <para>It's obvious that the <literal>javax.servlet</literal> package should not be present in <literal>myapp</literal> application and its packaging has to be changed. This problem can often be seen in WAR or web bundles that package Servlet/JSP classes by accident.</para>
- </section>
- <section id="admin-shell-cl-clexport">
- <title>clexport command</title>
- <para>Use the <literal>clexport</literal> command to list the bundles that export a class or package.</para>
- <para>The command accepts as a parameter the fully qualified class name (in the form <emphasis>package.class</emphasis>).</para>
- <para>The command checks to see if the provided class is actually contained in a bundle. If the class is not found in a bundle but its package is exported, then a hint <literal>[class not found, package only]</literal> is displayed.</para>
-
- <para>The following examples show how to use this command.</para>
- <para>Use the <literal>clexport</literal> to view all bundles that contain <literal>Servlet</literal> class:</para>
- <programlisting>osgi> clexport javax.servlet.Servlet
-
-Bundles exporting [javax.servlet.Servlet]:
- 14 com.springsource.javax.servlet</programlisting>
-
- <para>If a bundle exports a package but does not contain the requested class, the output of the command will be similar to this:</para>
- <programlisting>osgi> clexport javax.servlet.ServletX
-
-Bundles exporting [javax.servlet.ServletX]:
- 14 com.springsource.javax.servlet [class not found, package only]</programlisting>
- </section>
- <section id="admin-shell-cl-clload">
- <title>clload command</title>
- <para>Use the <literal>clload</literal> command to list the bundles that can load a class or to check if a specific bundle can load a class.</para>
- <para>The command accepts as parameters either:
- <itemizedlist>
- <listitem><para>the fully qualified class name (in the form <emphasis>package.class</emphasis>)</para></listitem>
- <listitem><para>the fully qualified class name (in the form <emphasis>package.class</emphasis>) and the symbolic name or id of the bundle that is to be tested</para></listitem>
- </itemizedlist>
- </para>
- <para>The command lists not only the bundle that successfully loaded the class, but also the one that actually provides the class. This is visualized with hints like <literal>[exported by 14 com.springsource.javax.servlet]</literal>.</para>
-
- <para>The following examples show how to use this command.</para>
- <para>You can use the <literal>clload</literal> to view all bundles that can load <literal>Servlet</literal> class:</para>
- <programlisting>osgi> clload javax.servlet.Servlet
-
-Successfully loaded [javax.servlet.Servlet] from:
- 56 com.springsource.org.apache.taglibs.standard
- [exported by 14 com.springsource.javax.servlet]
- 54 org.eclipse.virgo.apps.admin.web
- [exported by 14 com.springsource.javax.servlet]
- 19 com.springsource.org.apache.commons.fileupload
- [exported by 14 com.springsource.javax.servlet]
- <... remainder omitted ...></programlisting>
-
- <para>If a bundle is to be tested, then its id can be used as a command parameter:</para>
- <programlisting>osgi> clload javax.servlet.Servlet 19
-
-Successfully loaded [javax.servlet.Servlet] using class loader from:
- 19 com.springsource.org.apache.commons.fileupload
- [exported by 14 com.springsource.javax.servlet]</programlisting>
- <para>Or the same class load test can specify the symbolic name of the bundle:</para>
- <programlisting>osgi> clload javax.servlet.Servlet com.springsource.org.apache.commons.fileupload
-
-Successfully loaded [javax.servlet.Servlet] using class loader from:
- 19 com.springsource.org.apache.commons.fileupload
- [exported by 14 com.springsource.javax.servlet]</programlisting>
- </section>
-
-
- </section>
- <section id="p2-commands">
- <title>Using the p2 for extending your @project.name@ installation</title>
- <section>
- <title>Extending with the p2 director</title>
- <para>
- You can provision new features on top of your @project.name@ installation using the p2 director. It can be used both for initial provisioning and extending an existing installtion.
- </para>
- <para>For extending an existing installation you can use these director arguments:
- <screen>-repository http://download.eclipse.org/rt/ecf/3.5.3/site.p2
--installIU org.eclipse.ecf.remoteservice.feature.feature.group
--destination <your @project.name@ installation folder></screen></para>
- <para>This installs the <emphasis role="bold">latest</emphasis> version of the specified p2 feature in your @project.name@ installation's p2 profile.</para>
- </section>
- <section>
- <title>Extending via the p2 shell commands</title>
- <para>Another way to achieve the same results is to use the p2 commands. The commands are available only in @nano.product.name.short@ as it includes p2 by default.
- <note>For the other distributions only the director is supported and the operation only extends their kernel region.</note>
- </para>
- <para>Here's a list of the most commonly used p2 commands:</para>
- <table id="p2-common-commands-table" colsep="1" frame="all" rowsep="1">
- <title>p2 Common Shell Commands</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Command</entry>
- <entry>Help</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>provaddrepo <repository URI></literal></entry>
- <entry>
- Add specified URI as metadata and artifact repository. Note that if you pass a wrong URL you'll get an error saying:
- <literal>Repository not modifiable: http://wrongURL</literal>. The default behavior of this command is to create an empty repository at the
- specified location if there isn't any. That won't work for remote locations so keep in mind that if you see this you probably passed a wrong URL.
- </entry>
- </row>
- <row>
- <entry><literal>provdelrepo <repository URI></literal></entry>
- <entry>
- Remove specified metadata and artifact repository.
- </entry>
- </row>
- <row>
- <entry><literal>provinstall <InstallableUnit> <version> <profileid></literal></entry>
- <entry>
- Install an IU to the profileid. If no profileid is given, installs into default profile.
- </entry>
- </row>
- <row>
- <entry><literal>provremove <InstallableUnit> <version> <profileid></literal></entry>
- <entry>
- Uninstall an IU from the profileid. If no profileid is given, uninstalls form default profile.
- </entry>
- </row>
- <row>
- <entry><literal>provlg [<repository URI> <iu id | *> <version range | *>]</literal></entry>
- <entry>
- Lists all IUs with group capabilities in the given repo or in all repos if URI is omitted.
- </entry>
- </row>
- <row>
- <entry><literal>provliu [<repository URI | *> <iu id | *> <version range | *>]</literal></entry>
- <entry>
- Lists the IUs that match the pattern in the given repo. * matches all.
- </entry>
- </row>
- <row>
- <entry><literal>confapply</literal></entry>
- <entry>
- This is a Simple Configurator command, not a p2 one. However it is relevant because it applies dynamically, at runtime, the installed p2 features.
- What the command does is to apply to the running OSGi framework the current content in the bundles.info file. When using the provinstall command it takes care of updateing the bundles.info file.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>Here's an example showing how to install the ECF remote services but with the p2 commands this time:</para>
- <screen>osgi> provaddrepo http://download.eclipse.org/rt/ecf/3.5.3/site.p2
-
-osgi> provlg
-
-org.eclipse.ecf.core.feature.group 3.5.3.v20111109-2142
-org.eclipse.ecf.core.featurepatch.feature.group 3.5.3.v20111109-2142
-org.eclipse.ecf.core.featurepatch.source.feature.group 3.5.3.v20111109-2142
-org.eclipse.ecf.core.source.feature.group 3.5.3.v20111109-2142
-org.eclipse.ecf.datashare.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.datashare.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.dnssd.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.dnssd.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.jmdns.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.jmdns.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.slp.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.slp.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.zookeeper.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.discovery.zookeeper.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.eventadmin.examples.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.eventadmin.examples.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.eventadmin.feature.feature.group 2.0.0.v20111109-2142
-org.eclipse.ecf.eventadmin.source.feature.feature.group 2.0.0.v20111109-2142
-org.eclipse.ecf.osgi.services.feature.feature.group 2.0.1.v20111109-2142
-org.eclipse.ecf.osgi.services.source.feature.feature.group 2.0.1.v20111109-2142
-org.eclipse.ecf.remoteservice.examples.feature.feature.group 1.1.0.v20111109-2142
-org.eclipse.ecf.remoteservice.examples.source.feature.feature.group 1.1.0.v20111109-2142
-org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.rest.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.rest.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.rosgi.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.rosgi.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.sdk.feature.feature.group 3.5.3.v20111109-2142
-org.eclipse.ecf.remoteservice.sdk.source.feature.feature.group 3.5.3.v20111109-2142
-org.eclipse.ecf.remoteservice.soap.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.soap.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.remoteservice.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.server.generic.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.server.generic.source.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.xmpp.feature.feature.group 1.0.0.v20111109-2142
-org.eclipse.ecf.xmpp.source.feature.feature.group 1.0.0.v20111109-2142
-
-osgi> provinstall org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
-Installation complete for org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
-
-osgi> confapply
-
-osgi> ss
-
-"Framework is launched."
-
-
-id State Bundle
-0 ACTIVE org.eclipse.osgi_3.7.1.R37x_v20110808-1106
-....
-92 RESOLVED org.springframework.osgi.io_1.2.1
-93 RESOLVED org.eclipse.ecf.console_1.0.0.v20111109-2142
-94 RESOLVED org.eclipse.ecf.discovery_4.0.0.v20111109-2142
-95 RESOLVED org.eclipse.ecf.provider_4.2.100.v20111109-2142
-96 RESOLVED org.eclipse.ecf.provider.discovery_2.1.200.v20111109-2142
-97 RESOLVED org.eclipse.ecf.provider.remoteservice_4.0.0.v20111109-2142
-98 RESOLVED org.eclipse.ecf.remoteservice_6.0.200.v20111109-2142
-99 RESOLVED org.eclipse.ecf.sharedobject_2.2.100.v20111109-2142
-100 RESOLVED org.eclipse.equinox.concurrent_1.0.200.v20110502</screen>
- <para>You can see that after applying the changes with <emphasis>confapply</emphasis> the remote services bundles and their dependencies are installed in @nano.product.name.short@.</para>
- </section>
- </section>
-</chapter>
diff --git a/user-guide/src/applications.xml b/user-guide/src/applications.xml
deleted file mode 100644
index 0d31c73..0000000
--- a/user-guide/src/applications.xml
+++ /dev/null
@@ -1,228 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="deployment">
- <title>Working with Applications</title>
-
- <section id="deployment-deploying">
- <title>Deploying Artifacts</title>
- <para>
- In the context of @tomcat.product.name@, <emphasis>deploying</emphasis> refers to installing an artifact to the server and then starting it to make it available to users. Typically, when you install an artifact, @tomcat.product.name.short@ automatically starts it as long as the server is able to successfully resolve all its dependencies. For this reason, the terms <emphasis>deploying</emphasis> and <emphasis>installing</emphasis> are often used interchangeably.
- </para>
- <para>You deploy artifacts to @tomcat.product.name@ using either the hot-deploy directory on the file system or by using the Admin Console. The artifacts that you can deploy to @tomcat.product.name.short@ are:
- </para>
- <itemizedlist>
- <listitem>Bundles, including Web Application Bundles</listitem>
- <listitem>WARs</listitem>
- <listitem>PARs</listitem>
- <listitem>Plans</listitem>
- <listitem>Configuration Files</listitem>
- </itemizedlist>
- <section id="deployment-deploying-nested-contexts">
- <title>Deploying WARs with nested Web-ContextPaths</title>
- <note>
- This section currently is ONLY relevant for @nano.product.name@.
- </note>
- <para>
- Virgo Nano Web supports deployment of WAR files which are transformed into Web Application Bundles. This process involves automatic creation of an OSGi manifest with all relevant OSGi header plus the very important Web-ContextPath header. Its value defines how the deployed WAR file can be requested. There is a limitation about this process that the automatic generation only creates a flat context path which equals the name of your WAR file. Virgo Nano Web supports generation of a nested one.
- </para>
-
- <para>In order to benefit from this flexibility all you need to do is just to add hashes '#' to your WAR file name in the places where you want to have slashes in your web context path. Here is an example:
- <screen>myWarFile.war would result into "/myWarFile" web context path</screen>
- <screen>my#War#File.war would result into "/my/War/File" web context path</screen>
- The symbolic name of the resulting WAB file is the same as the WAR file name but the hashes '#' are replaced with dots '.'.
- </para>
- </section>
- <section id="initial-deployment-deploying-bulk">
- <title>Initial Bulk Hot Deploy</title>
- <note>
- This section currently is ONLY relevant for @nano.product.name@.
- </note>
- <para>
- To hot deploy an artifact initially in bulk mode, copy it into the pickup directory (by default <literal>$SERVER_HOME/pickup</literal>) and start up the server. Upon this startup all the artifacts in the <literal>pickup</literal> directory will get first installed and resolved and only then they will be started.
- </para>
- <para>
- This solves the problem where artifacts depend on each other and when not in bulk mode the install order is not guaranteed therefore errors could occur.
- </para>
- <para>
- This is only available as part of the initial scan of the <literal>pickup</literal> directory. Subsequently it goes back to the known mode of single file handled at a time.
- </para>
- <programlisting>prompt$ cd /home/applications
-prompt$ cp BundleA.jar $SERVER_HOME/pickup
-prompt$ cp BundleWithDependencyOnA.jar $SERVER_HOME/pickup
-prompt$ cd $SERVER_HOME/bin
-prompt$ ./startup.sh</programlisting>
- <para>
- When the server is started, artifacts are hot deployed and messages similar to the following appear in the log file:
- </para>
- <screen>[2009-12-10 06:41:01.021] fs-watcher <HD0001I> Hot deployer processing 'INITIAL' event for file 'BundleA.jar; BundleWithDependencyOnA.jar; '.
-[2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'BundleA' version '0.0.0'.
-[2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'BundleA' version '0.0.0'.
-[2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'BundleWithDependencyOnA' version '0.0.0'.
-[2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'BundleWithDependencyOnA' version '0.0.0'.
-[2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'BundleA' version '0.0.0'.
-[2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'BundleA' version '0.0.0'.
-[2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'BundleWithDependencyOnA' version '0.0.0'.
-[2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'BundleWithDependencyOnA' version '0.0.0'.</screen>
- <para>
- If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
- </para>
- <para>If there are no problems, @nano.product.name@ automatically starts the artifacts so that they are immediately available to users.
- </para>
- <para>Bulk deployment can be disabled and reverted back to the old one-file-at-a-time processing by removing this line from <literal>$SERVER_HOME/configuration/config.ini</literal>:
- </para>
- <programlisting>org.eclipse.virgo.fschecker.initialEventMode=bulk</programlisting>
- </section>
- <section id="deployment-deploying-hot">
- <title>Hot Deploy</title>
- <para>
- To hot deploy an artifact, copy it into the pickup directory (by default <literal>$SERVER_HOME/pickup</literal>):
- </para>
- <programlisting>prompt$ cd /home/applications
-prompt$ cp helloWorld.war $SERVER_HOME/pickup</programlisting>
- <para>
- When the artifact is hot deployed, messages similar to the following appear in the log file:
- </para>
- <screen>[2009-12-10 06:41:01.021] fs-watcher <HD0001I> Hot deployer processing 'CREATED' event for file 'helloWorld.war'.
-[2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'helloWorld' version '0.0.0'.
-[2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'helloWorld' version '0.0.0'.
-[2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'helloWorld' version '0.0.0'.
-[2009-12-10 06:41:01.414] Thread-3 <WE0000I> Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2009-12-10 06:41:01.537] Thread-3 <WE0001I> Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'helloWorld' version '0.0.0'.</screen>
- <para>
- If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
- </para>
- <para>If there are no problems, @tomcat.product.name.short@ automatically starts the artifact so that it is immediately available to users.
- </para>
- </section>
-
- <section id="deployment-redeploy-hot">
- <title>Hot Redeploy</title>
- <para>
- To hot redeploy an artifact which is already hot deployed, copy the updated artifact into the pickup directory (by default <literal>$SERVER_HOME/pickup</literal>),
- just as for hot deploy. When the artifact is redeployed, messages similar to the following appear in the log file:
- </para>
- <screen>[2013-01-09 14:08:12.422] fs-watcher <HD0001I> Hot deployer processing 'MODIFIED' event for file 'helloWorld.war'.
-[2013-01-09 14:08:12.422] fs-watcher <DE0007I> Refreshing bundle 'helloWorld' version '0.0.0'.
-[2013-01-09 14:08:12.469] fs-watcher <WE0002I> Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2013-01-09 14:08:13.094] fs-watcher <WE0003I> Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2013-01-09 14:08:13.094] fs-watcher <DE0010I> Stopping bundle 'helloWorld' version '0.0.0'.
-[2013-01-09 14:08:13.110] fs-watcher <DE0011I> Stopped bundle 'helloWorld' version '0.0.0'.
-[2013-01-09 14:08:13.250] fs-watcher <DE0004I> Starting bundle 'helloWorld' version '0.0.0'.
-[2013-01-09 14:08:13.250] start-signalling-2 <WE0000I> Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2013-01-09 14:08:13.860] start-signalling-2 <WE0001I> Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2013-01-09 14:08:13.860] start-signalling-2 <DE0005I> Started bundle 'helloWorld' version '0.0.0'.
-[2013-01-09 14:08:13.860] fs-watcher <DE0008I> Refreshed bundle 'helloWorld' version '0.0.0'.</screen>
- <note>
- The following paragraph is ONLY relevant for @nano.product.name@.
- </note>
- <para>
- The redeploy waits for any previous operations on the artifact being redeployed to finish. The wait timeout could be configured through the following property in <literal>$SERVER_HOME/configuration/config.ini</literal>:
- </para>
- <programlisting>org.eclipse.virgo.update.timeout</programlisting>
- </section>
-
- <section id="deployment-deploying-manual">
- <title>Deploying Using the Admin Console</title>
- <para>
- The Admin Console allows you to upload a file, which will be deployed automatically, from your local file system to the @tomcat.product.name@. As soon as @tomcat.product.name@ deploys the artifact, it appears in the list of artifacts in the Admin Console. Note that the GUI for uploading varies according to the browser and operating system you use.
- </para>
-
- <para>See <link linkend="admin-console-install-artifacts">Installing a New Artifact</link> for details about using the Admin Console to install (deploy) an artifact. See <link linkend="admin-console">The Web Admin Console</link> for general information about the Admin Console.</para>
- </section>
-
- <section id="deployment-deploying-happens">
- <title>What Happens When You Deploy</title>
- <para>
- When you deploy an artifact, either using hot-deployment or the Admin Console, Web Server copies the file to its work directory (<literal>SERVER_HOME/work</literal>) and registers it in its internal registry.
- The server then checks any dependencies the artifact might have to see if
- deployment can go ahead, and if all dependencies are resolved, @tomcat.product.name@ starts the artifact.
- Because of all these additional internal activities, you should NOT simply copy the artifact into the <literal>work</literal> directory and assume it will be deployed, because @tomcat.product.name@ will not do so.
- </para>
- </section>
- <section id="deployment-deploying-ordering">
- <title>Deployment Ordering</title>
- <para>
- When deploying bundles that have dependencies, it is important
- that you deploy them in the correct order. @tomcat.product.name@
- honors this ordering when it redeploys the artifacts on startup.
- </para>
- <para>
- If you use hot deployment to deploy your artifacts, be sure to copy the corresponding files into the pickup
- directory one-by-one. Copying the files in one group, for example by using a single <literal>cp</literal> command, provides no guarantee of ordering.
- </para>
- </section>
- <section id="deployment-deploying-shared">
- <title>Deploying Shared Artifacts</title>
- <para>
- Artifacts may be shared by plans.
- Sharing occurs when a plan is deployed which references an artifact that was previously deployed or is a child artifact
- of a plan that was previously deployed.
- Sharing also occurs when an artifact is deployed which is already a child of a deployed plan, but in this case the shared
- artifact may <emphasis>not</emphasis> appear as a top-level artifact, for example, in the Admin Console, in the shell,
- and in JMX.
- </para>
- <para>
- Sharing is taken into account when artifacts are stopped.
- A shared artifact is stopped only when all the artifacts referencing the shared artifact have been stopped
- and, if the shared artifact was deployed in its own right, the artifact itself has been stopped.
- </para>
- </section>
- <section id="deployment-deploying-restrictions">
- <title>Restrictions</title>
- <para>
- @tomcat.product.name@ does not support deploying fragment bundles. Typically, fragment bundles should be placed in <literal>$SERVER_HOME/repository/ext</literal>
- or <literal>$SERVER_HOME/repository/usr</literal> so that they will be installed automatically with their host bundles.
- </para>
- </section>
- </section>
-
- <section id="deployment-undeploy">
- <title>Undeploying Artifacts</title>
- <para>
- You undeploy artifacts from @tomcat.product.name@ by using either the hot-deploy directory on the file system, or the Admin Console.
- </para>
- <para><emphasis role="bold">Note:</emphasis> As with deploying, in this guide the terms <emphasis>undeploying</emphasis> and <emphasis>uninstalling</emphasis> are used interchangeably.</para>
-
- <section id="deployment-undeploy-hot">
- <title>Hot Undeploy</title>
- <para>
- To hot-undeploy an artifact, remove the corresponding file from the pickup directory (by default <literal>$SERVER_HOME/pickup</literal>):
- </para>
- <programlisting>prompt$ cd $SERVER_HOME/pickup
-prompt$ rm helloWorld.war</programlisting>
- <para>
- When @tomcat.product.name@ completes the undeployment of the artifact, messages similar to the following appear in the log:
- </para>
- <screen>[2009-12-10 06:46:33.254] fs-watcher <HD0001I> Hot deployer processing 'DELETED' event for file 'helloWorld.war'.
-[2009-12-10 06:46:33.259] Thread-3 <WE0002I> Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2009-12-10 06:46:33.285] Thread-3 <WE0003I> Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
-[2009-12-10 06:46:33.290] fs-watcher <DE0010I> Stopping bundle 'helloWorld' version '0.0.0'.
-[2009-12-10 06:46:33.295] fs-watcher <DE0011I> Stopped bundle 'helloWorld' version '0.0.0'.
-[2009-12-10 06:46:33.302] fs-watcher <DE0013I> Uninstalling bundle 'helloWorld' version '0.0.0'.
-[2009-12-10 06:46:33.319] fs-watcher <DE0014I> Uninstalled bundle 'helloWorld' version '0.0.0'.</screen>
-
- </section>
-
- <section id="deployment-undeploy-manual">
- <title>Undeploying Using the Admin Console</title>
- <para>
- You can undeploy only whole artifacts from the Admin Console, or in other words, you cannot undeploy the separate modules or bundles that make up an artifact.</para>
- <para>
- The only artifact that you cannot undeploy from the Admin Console is the Admin Console itself. If you need to undeploy this application, you must remove it from the pickup directory (by default <literal>SERVER_HOME/pickup</literal>); the name of the artifact is
- <literal>org.eclipse.virgo.server.admin-2.1.0.RELEASE.plan</literal>.
- </para>
- <para>See <link linkend="admin-console-manage-artifacts">Viewing and Managing the Lifecycle of Deployed Artifacts</link> for details about uninstalling (undeploying) an artifact using the Admin Console. The high-level steps are to highlight the artifact in the artifact tree then click <literal>Uninstall</literal>. </para>
- </section>
- <section id="deployment-undeploying-shared">
- <title>Undeploying Shared Artifacts</title>
- <para>
- Sharing is taken into account when artifacts are undeployed.
- A shared artifact is undeployed only when all the artifacts referencing the shared artifact have been undeployed
- and, if the shared artifact was deployed in its own right, the artifact itself has been undeployed.
- </para>
- </section>
- </section>
-
-</chapter>
diff --git a/user-guide/src/concepts.xml b/user-guide/src/concepts.xml
deleted file mode 100644
index 51e234e..0000000
--- a/user-guide/src/concepts.xml
+++ /dev/null
@@ -1,674 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-
-<!--========================================================================-->
-<chapter id="concepts">
-
-<title>Concepts</title>
-
-<para>This chapter introduces some basic concepts that will help you to use @project.name@.</para>
-
-<!--========================================================================-->
-<section id="concepts.modular">
-
-<title>Modular Runtimes and Applications</title>
-
-<para>
- @tomcat.product.name@, @jetty.product.name@, @kernel.product.name@ and @nano.product.name@ are Java runtimes each composed of
- a collection of modules and supporting applications which are also composed of a
- collection of modules.
- Modules can be shared between applications and multiple versions of modules
- can co-exist.
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section id="concepts.osgi">
-
-<title>OSGi Concepts</title>
-
-<para>Modules in @project.name@ are represented using a standard Java
-module system known as <emphasis>OSGi</emphasis>.
-Modules in OSGi are known as <emphasis>bundles</emphasis>.
-Bundles consist of programs and resources organised by Java package together
-with metadata which declares imported and exported packages.
-A bundle <emphasis>exports</emphasis> a package to make the corresponding programs and resources
-available for use by other bundles.
-A bundle <emphasis>imports</emphasis> a package to use the corresponding programs and resources of
-another bundle.</para>
-
-<para>
- Representing a program as a collection of bundles makes it easier for the
- programmer to manage it and modify it and for teams of programmers to divide
- responsibilities between themselves.
- A bundle is similar to a Java class in this respect. Design principles similar to those for
- organising data and programs into classes can be applied
- to organising applications into bundles.
-</para>
-
-<para>
- An industry consortium known as the
- <emphasis>OSGi Alliance</emphasis> develops OSGi
- specifications, reference implementations, and compliance tests.
- @project.name@ is built on the Equinox OSGi framework which is also
- the reference implementation for the OSGi framework specification.
-</para>
-
-<!--========================================================================-->
-<section>
-
-<title>Bundles</title>
-
-<para>
-Each bundle is stored in a file which conforms to the JAR file format and
-can contain Java classes, a manifest (in <literal>META-INF/MANIFEST.MF</literal>),
-and further resource files.</para>
-
-<para>The OSGi framework enables bundles to be installed and run.</para>
-
-<para>OSGi identifies bundles <quote>by name</quote> and <quote>by identifier</quote> (id).</para>
-
-<para>The <emphasis>symbolic name</emphasis> and
-<emphasis>version</emphasis> of a bundle are attributes of the bundle which identify the bundle.
-A bundle declares its <emphasis>symbolic name</emphasis> and <emphasis>version</emphasis>
-in its manifest (a file called <literal>MANIFEST.MF</literal>) like this:
-<programlisting>Bundle-SymbolicName: org.foo.bundle
-Bundle-Version: 1.2.3.BUILD-2009-06-04
-</programlisting>
-</para>
-
-<para>Additionally, the OSGi framework
-assigns a distinct number, known as a <emphasis>bundle id</emphasis>, to each bundle
-as it is installed. Bundles may be referred to <quote>by identifier</quote> using this number.
-The OSGi framework itself resides in a
-bundle with bundle id <literal>0</literal>.</para>
-
-<para>The
-dependencies between bundles are expressed statically in terms of packages and
-dynamically in terms of services. A package is familiar to Java programmers.
-For example, a Java program may depend on a class <literal>org.foo.X</literal>,
-from package <literal>org.foo</literal>, and a bundle
-containing that program
-would either need to contain <literal>org.foo.X</literal> or depend on the
-package <literal>org.foo</literal>.
-Package dependencies are specified in the bundle manifest, for example:
-<programlisting>Import-Package: org.foo
-</programlisting>
-</para>
-
-<para>A bundle which provides a package for use by other bundles <emphasis>must</emphasis>
-export the package in its manifest. For example:
-<programlisting>Export-Package: org.foo
-</programlisting>
-</para>
-
-<para>The OSGi framework ensures that a given bundle’s package dependencies
-can be <emphasis>satisfied</emphasis> before the bundle runs. This process is known as
-<emphasis>resolution</emphasis>.</para>
-
-<para>After a bundle is resolved, its classes and resources are available for
-loading.
-In OSGi, bundles and their packages do not appear on the application classpath.
-Instead, each bundle has a class loader which loads its own classes and loads classes belonging to each of its
-imported packages by deferring to the bundle class loader that exports the package.</para>
-
-</section>
-
-<!--========================================================================-->
-<section>
-
-<title>Life Cycle</title>
-
-<para>The OSGi framework manages the <emphasis>life cycle</emphasis> of each bundle. A bundle is
-first of all <emphasis>install</emphasis>ed and will be in the INSTALLED state.
-If a request is made to <emphasis>start</emphasis> the bundle, the OSGi framework <emphasis>resolve</emphasis>s the bundle
-and, if resolution was successful, will subsequently move the bundle to the ACTIVE state.
-If a request is made to <emphasis>stop</emphasis> the bundle, the OSGi framework will move the
-bundle back to the RESOLVED state. A request may then be made to <emphasis>uninstall</emphasis>
-the bundle.</para>
-
-<para>While the bundle is INSTALLED, ACTIVE or RESOLVED, it may be <emphasis>updated</emphasis> to pick up
-some changes. These changes are not detected by bundles which were depending
-on the bundle before it was updated.
-A <quote>refresh packages</quote> operation may be performed to ripple the
-changes out to those bundles. (See <xref linkend="concepts.services"/>.)</para>
-<para>The life cycle of a bundle can be summarised by a state transition diagram.
-This diagram shows some more of the intermediate states of a bundle not described in the overview above:
-<figure>
-<title>Bundle life cycle</title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/concepts/bundle-lifecycle.png" format="PNG" align="center" width="120mm"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/concepts/bundle-lifecycle.png" format="PNG" align="center"/>
- </imageobject>
- </mediaobject>
-</figure></para>
-
-</section>
-
-<!--========================================================================-->
-<section id="concepts.services" xreflabel="Services concepts">
-
-<title>Services</title>
-
-<para>Bundles may publish Java objects, known as <emphasis>services</emphasis>,
-to a registry managed by the OSGi framework. Other bundles running in
-the same OSGi framework can then find and use those services. Services
-are typically instances of some shared Java interface. A bundle which
-provides a service need not then export the package containing the
-<emphasis>implementation</emphasis>
-class of the service.
-</para>
-
-<para>For example, a bundle could export a package containing the interface
-<literal>org.bar.SomeInterface</literal>, thus:
-
-<programlisting>Export-Package: org.bar
-</programlisting>
-</para>
-
-<para>…implement the interface with a class <literal>SomeImpl</literal>:
-
-<programlisting>package org.bar.impl;
-
-class SomeImpl implements SomeInterface {
- …
-}
-</programlisting>
-</para>
-
-<para>…create an instance of <literal>SomeImpl</literal> and
-then publish this instance (as an instance of the interface <literal>SomeInterface</literal>).
-</para>
-
-<para>An OSGi framework publishes a number of standard services. For example, the
-<emphasis>Package Admin</emphasis> service provides the <quote>refresh packages</quote> life cycle operation
-mentioned above.</para>
-
-<para>OSGi provides an <glossterm>API</glossterm> which can be used to publish and find services,
-but it is much simpler to use Spring DM or Blueprint to accomplish this. (See <xref linkend="concepts.springdm"/>.)</para>
-
-</section>
-
-<!--========================================================================-->
-<section>
-
-<title>Versioning</title>
-
-<para>
- OSGi allows different versions of bundles, packages, and several
- other entities, to co-exist in the same framework
- and provides some mechanisms for managing these versions.
-</para>
-
-<section>
-
-<title>Version Numbers</title>
-
-<para>An OSGi <emphasis>version number</emphasis> consists of up to three numeric components,
-or exactly three
-numeric components followed by a string component. These components are
-separated by a period (<quote><literal>.</literal></quote>) and
-are called the <emphasis>major</emphasis>, <emphasis>minor</emphasis>, <emphasis>micro</emphasis>,
-and <emphasis>qualifier</emphasis> components, respectively.
-</para>
-<para>For example, the version <literal>2.4.1.ga</literal> has major component <literal>2</literal>, minor component
-<literal>4</literal>, micro component <literal>1</literal>,
-and a qualifier component <literal>ga</literal>. (There are restrictions on the characters that can appear in
-a qualifier. For example: letters, digits, underscores and hyphens are allowed; periods and commas are not.)</para>
-
-<para>Trailing components may be omitted along with their period (<literal>.</literal>). So, for example, the version
-numbers <literal>2</literal>, <literal>2.0</literal>, and <literal>2.0.0</literal>
-all denote the same version. This example demonstrates that <literal>0</literal> is assumed if a numeric component is omitted,
-and the empty string is assumed for an omitted qualifier.</para>
-
-</section>
-
-<section>
-
-<title>Version Ranges</title>
-
-<para>Dependencies on bundles and packages have an associated <emphasis>version range</emphasis>
-which is specified using an interval notation: a square bracket
-<quote><literal>[</literal></quote> or <quote><literal>]</literal></quote> denotes
-an <emphasis>inclusive</emphasis> end of the range and a round bracket
-<quote><literal>(</literal></quote> or <quote><literal>)</literal></quote> denotes
-an <emphasis>exclusive</emphasis> end of the range. Where one end of the range is to be included and the other excluded, it is permitted to
-pair a round bracket with a square bracket.
-The examples below make this clear.</para>
-
-<para>If a single version number is used where a version <emphasis>range</emphasis> is
-required this does <emphasis>not</emphasis> indicate a single version, but the range <emphasis>starting</emphasis> from that version and
-including all higher versions.</para>
-
-<para>There are three common cases:
-
-<itemizedlist>
-<listitem><para>A <quote>strict</quote> version range, such as <literal>[1.2,1.2]</literal>, which
-denotes that version and only that version.</para></listitem>
-<listitem><para>A <quote>half-open</quote> range, such as
-<literal>[1.2,2)</literal>, which has an inclusive lower limit
-and an exclusive upper limit, denoting version <literal>1.2.0</literal> and any version after this, up
-to, <emphasis>but not including</emphasis>, version <literal>2.0.0</literal>.
-</para></listitem>
-<listitem><para>An <quote>unbounded</quote> version range, such as <literal>1.2</literal>, which
-denotes version <literal>1.2</literal> and <emphasis>all</emphasis> later versions.</para></listitem>
-</itemizedlist>
-
-</para>
-
-</section>
-
-<section>
-<title>Versioning Policies</title>
-<para>A <emphasis>versioning policy</emphasis> is a way of using version numbers to indicate compatible
-and incompatible changes.
-OSGi does not mandate a particular versioning policy.
-Instead, a specific versioning policy may be implemented using version ranges.</para>
-<para>Strict and half-open version ranges are most useful in representing versioning
-policies.
-Unbounded version ranges can lead to problems as they (unrealistically) assume that
-compatibility will be preserved indefinitely.</para>
-
-<para>For example, a conservative versioning policy might assume that any change, other than
-in the qualifier component of a version, implies an incompatible
-change to the object.
-Such a policy would employ version ranges such as <literal>[1.2.1.beta,1.2.2)</literal>
-which accept any version from <literal>1.2.1.beta</literal> (inclusive) up to but not including
-<literal>1.2.2</literal> (exclusive).
-</para>
-<para>Alternatively, a relaxed versioning policy might assume that only changes in the major component of
-a version denote an incompatible change.
-Such a policy would employ version ranges such as <literal>[1.2,2)</literal> to capture this.</para>
-
-<para>
- The OSGi Alliance has published a <ulink url="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf">Semantic
- Versioning white paper</ulink> which provides some recommendations and guidance on versioning policies.
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section>
-
-<title>Bundle Version</title>
-
-<para>Each bundle has a version.
-The bundle’s version may be specified in the manifest using a
-<literal>Bundle-Version</literal> header:
-
-<informalexample>
-<programlisting>Bundle-Version: 1.4.3.BUILD-20090302
-</programlisting>
-</informalexample>
-If not specified the bundle version is assumed to be <literal>0</literal>.
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section>
-
-<title>Package Version</title>
-
-<para>Each exported package has a version.
-The exported package’s version may be specified on the Export-Package manifest header. For example
-
-<informalexample>
-<programlisting>Export-Package: org.foo;version="2.9",org.bar;version="1"
-</programlisting>
-</informalexample>
-
-exports two packages: <literal>org.foo</literal>, at version <literal>2.9.0</literal> and
-<literal>org.bar</literal>, at version <literal>1.0.0</literal>.
-</para>
-
-<para>If the version attribute is omitted, the version is assumed to be <literal>0</literal>.</para>
-
-<para>Each package <emphasis>import</emphasis> has a version <emphasis>range</emphasis>.
-The package import version range may be specified on the <literal>Import-Package</literal> manifest header.
-If interval notation is used, the version range must be enclosed in double quotes, for example:
-<informalexample>
-<programlisting>Import-Package: org.foo;version="[2,3)",org.bar;version="[1,1]"</programlisting>
-</informalexample>
-seeks to import a package <literal>org.foo</literal> in the range <literal>[2.0.0,3.0.0)</literal> and a package
-<literal>org.bar</literal> with the (exact) version <literal>1.0.0</literal>.
-</para>
-
-<para>If a version range is not specified on an import, the range <literal>0</literal> is assumed, meaning that
-any version of this package would satisfy the import.</para>
-
-</section>
-
-<!--========================================================================-->
-<section>
-
-<title>Bundle Manifest Version</title>
-
-<para>Bundle manifests have a version which is <literal>1</literal> by default,
-indicating OSGi Release 3 semantics.
-@project.name@ is based on OSGi Release 4 and therefore expects bundle manifests to be
-at version <literal>2</literal>, indicating OSGi Release 4 semantics.
-The bundle manifest’s version should be specified on the Bundle-ManifestVersion manifest header, exactly as follows:
-<informalexample>
-<programlisting>Bundle-ManifestVersion: 2
-</programlisting>
-</informalexample>
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section>
-
-<title>Manifest Version</title>
-
-<para>Manifests themselves also have a version which <emphasis>must</emphasis> be specified as <literal>1.0</literal>.
-This is not an OSGi definition but part of the
-(<ulink url="http://java.sun.com/javase/6/docs/technotes/guides/jar/jar.html">JAR file specification</ulink>).
-
-<informalexample>
-<programlisting>Manifest-Version: 1.0
-</programlisting>
-</informalexample>
-
-</para>
-
-</section>
-
-</section>
-
-</section>
-
-<!--========================================================================-->
-<section id="concepts.springdm" xreflabel="Spring DM concepts">
-
-<title>Spring DM and Blueprint Concepts</title>
-
-<para>Spring DM is a project which enables <emphasis>services</emphasis> to be published and consumed
-using descriptions written in XML.</para>
-
-<para>The XML descriptions reside in files with extension <literal>.xml</literal> in the
-bundle’s <literal>META-INF/spring</literal> sub-directory.</para>
-
-<para>
- To publish a service, an <literal><osgi:service></literal> tag is used, specifying the
- implementation class of the service and the interface class to be used.
- Spring DM constructs an instance of the implementation class and
- publishes that instance in the OSGi service registry under the interface when the bundle is started.
-</para>
-
-<para>To consume a service, an <literal><osgi:reference></literal> tag is used and the
-service may be passed into other Spring beans using Spring’s dependency
-injection facilities.</para>
-
-<para>Spring DM automatically creates proxies for OSGi services so that the actual service
-object may come and go at runtime.
-If a service disappears, any proxies to the service will wait for the service to re-appear.
-This effect is known as <emphasis>damping</emphasis>.</para>
-
-<para>When a bundle is started, Spring DM builds the application contexts
-specified by the XML descriptions, creates proxies for the specified services, and publishes
-the specified services to the OSGi service registry.</para>
-
-<para>When a bundle is stopped, Spring DM retracts any services it published on behalf of the bundle
-and closes the bundle’s application contexts.
-@project.name@ turns off damping of a service proxy while the proxy’s application context
-is being closed.</para>
-
-<para>Spring DM was contributed to Eclipse as the <emphasis>Gemini Blueprint</emphasis> project.
-@project.name@ has Gemini Blueprint built-in.</para>
-
-<para>Gemini Blueprint supports both Spring DM and Blueprint programming models.
-Blueprint, known formally as the "OSGi Blueprint Container", provides some of the basic facilities of Spring DM,
-including all those just mentioned, but in an OSGi standard form.
-See <xref linkend="furtherreading"/> for the Blueprint specification.
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section id="concepts.virgo">
-
-<title>@project.name@ Concepts</title>
-<note>
-This section is not relevant for @nano.product.name@.
-</note>
-
-<!--========================================================================-->
-<section id="concepts.repositories">
-
-<title>The Provisioning Repository</title>
-
-The @project.name@ provisioning repository contains artifacts and metadata indexed by the artifact type, name, and version. There are three kinds of repository: <emphasis>external</emphasis>, <emphasis>watched</emphasis>, and <emphasis>remote</emphasis>. Repositories are passive in the sense that changes to repository content do not cause artifacts to be deployed into @project.name@, refreshed, or undeployed.
-
-<section>
-
-<title>Artifact Types</title>
-
-In addition to the standard OSGi bundle, artifact types in @project.name@ include configuration (properties file), PAR, plan, and library.
-PARs, plans, and libraries are discussed in <xref linkend="concepts.grouping"/>.
-
-</section>
-
-<section>
-
-<title>External Repositories</title>
-
-<para>
- External repositories are created by scanning a directory which contains artifacts, possibly in nested directories. The repository configuration specifies a pattern which
- says which files should be treated as artifacts. After the repository is created, changes to the directory do not affect the repository content.
-</para>
-<para>
- @project.name@'s default repository configuration, in <literal>configuration/org.eclipse.virgo.repository.properties</literal>, specifies an external repository created from the
- <literal>repository/ext</literal> directory.
-</para>
-
-</section>
-
-<section>
-
-<title>Watched Repositories</title>
-
-<para>
- Watched repositories are created by scanning a directory which contains artifacts but no nested directories. All files in the directory are treated as artifacts.
- The directory is re-scanned periodically and the interval between re-scans is specified in the repository configuration.
- The directory is also re-scanned when an artifact is deployed into @project.name@.
- Changes detected by re-scanning are reflected in the repository content. Note that changing the content of a watched repository does not cause artifacts to be deployed
- into @project.name@, refreshed, or undeployed.
-</para>
-<para>
- @project.name@'s default repository configuration specifies a watched repository based on the contents of the <literal>repository/usr</literal> directory.
-</para>
-
-</section>
-
-<section>
-
-<title>Remote Repositories</title>
-
-<para>
- A remote repository refers to a repository hosted by a @project.name@ instance sometimes known as a <emphasis>repository server</emphasis>.
- The hosted repository is configured using the file <literal>configuration/org.eclipse.virgo.apps.repository.properties</literal> and may be either an external or a watched
- repository.
-</para>
-<para>
- The remote repository is accessed by a @project.name@ instance sometimes known as a <emphasis>repository client</emphasis>.
- The repository client is normally a different instance of @project.name@ to the instance hosting the repository, but it can be the same instance (which is handy for
- testing). The remote repository periodically downloads its index from the hosted repository. The period between downloads may be configured in the repository
- configuration. The remote repository also caches artifacts which have secure hashes associated with them in the hosted repository. Only bundles currently have secure
- hashes associated with them. The secure hash is used to determine when a cached artifact is stale and needs to be freshly downloaded.
-</para>
-
-</section>
-
-<section>
-
-<title>Repository Chains</title>
-
-<para>
- The @project.name@ repository is configured as a <emphasis>chain</emphasis> of external, watched, and remote repositories.
- The chain is a list which is searched in the configured order.
- The effect of this search order is that an artifact with a given type, name, and version which appears in more than one repository in the chain is only accessed from the
- first repository in the chain in which it appears. Abstractly, the repository chain behaves as a single repository, but its content may mutate in quite a different way to
- the content of an individual external, watched, or remote repository.
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section id="concepts.grouping" xreflabel="Grouping Bundles">
-
-<title>Grouping Bundles</title>
-
-<para>@project.name@ provides a way of grouping together a collection
-of OSGi bundles and other artifacts which comprise a single application.
-These artifacts are placed in a JAR file with extension <quote><literal>.par</literal></quote>. This is called a PAR file.</para>
-
-<para>All the bundles in a PAR file are resolved together and so mutual dependencies are permitted.</para>
-
-<para>At runtime a PAR file provides a <emphasis>scope</emphasis> in the sense that bundles
-inside the PAR file may depend on packages and services outside the PAR file,
-but bundles outside the PAR file may not depend on packages and services
-provided by the PAR file.</para>
-
-<para>@project.name@ also provides the plan artifact as another way of grouping bundles and other artifacts into an application.
-A <emphasis>plan</emphasis> is a file (in XML format) listing a collection of artifacts.
-The artifacts referred to by a plan reside in the @project.name@ provisioning repository.
-</para>
-
-<para>
- In addition to PARs and plans, which are used for deploying groups of artifacts, @project.name@ provides libraries as a way of grouping together a collection
- of bundles that can then be imported into an application using the @project.name@-specific <literal>Import-Library</literal> manifes header.
-</para>
-
-</section>
-
-<!--========================================================================-->
-<section id="kernel.user.region">
-
-<title>Kernel and User Region</title>
-
- <para>Conceptually, @tomcat.product.name.short@ can be divided into two separate subsystems, one of which actually encompases the other:</para>
- <itemizedlist>
- <listitem>The <emphasis>kernel</emphasis>, which is the heart of @tomcat.product.name.short@. It makes up most of @tomcat.product.name.short@, except for the part that supports Web applications. In other words, the kernel provides full OSGi modular support for your applications, as long as they are not Web-based.
- <para>See <link linkend="kernel-overview">The @kernel.product.name@</link> for additional information.</para>
- </listitem>
- <listitem>The <emphasis>user region</emphasis> is the subsystem that manages user applications. It deliberately isolates the kernel from both your applications and those of the @tomcat.product.name.short@ itself, such as the Admin Console, which protects the kernel from interference by applications.
- <para>See <link linkend="user-region-overview">The User Region</link> for additional information.</para>
- </listitem>
- </itemizedlist>
-
- <para>When you download and install @tomcat.product.name@ you get both the kernel and web server support (configured in the user region). You can also <ulink url="http://www.eclipse.org/virgo/download/">download and use the kernel</ulink> on its own if you do not plan on deploying Web applications or using the
- web-based Admin Console and you'll get the kernel and a minimal user region (with no web support).</para>
-
- <para>The following graphic shows how the kernel and user region make up @tomcat.product.name.short@:</para>
- <imagedata fileref="images/kernel-user-region.png" width="885px" depth="805px" />
-
- <section id="kernel-overview">
- <title>The @kernel.product.name@</title>
- <para>
- The @kernel.product.name@ encapsulates almost all of @tomcat.product.name.short@ except for the deployment of Web applications. In sum, the kernel provides the following @tomcat.product.name.short@ features:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Deployment of non-Web artifacts, such as OSGi bundles, PARs, plans,
- and configuration artifacts.
- </para>
- </listitem>
- <listitem>
- <para>
- Local and hosted repositories
- </para>
- </listitem>
- <listitem>
- <para>
- Scoping
- </para>
- </listitem>
- <listitem>
- <para>
- Hot deployment
- </para>
- </listitem>
- <listitem>
- <para>
- User region
- </para>
- </listitem>
- <listitem>
- <para>
- Auto-provisioning
- </para>
- </listitem>
- <listitem>
- <para>
- System and application tracing and dump support
- </para>
- </listitem>
- <listitem>
- <para>
- Spring beans and Spring DM support
- </para>
- </listitem>
- </itemizedlist>
-
- <para>See <link linkend="configuring">Configuring @tomcat.product.name.short@</link> for details about configuring the kernel to better suit your environment. </para>
- </section>
-
- <section id="user-region-overview">
- <title>The User Region</title>
- <para>
- The user region isolates the kernel from deployed applications,
- including both your own user applications and the user-oriented
- @tomcat.product.name.short@ applications such as the Admin Console. This means
- that the kernel is mostly invisible to applications and to application
- management. This is because most of the kernel bundles are not
- installed in the user region (apart from a few needed for region
- management). The necessary function to support the kernel runs in the
- OSGi framework, but the user region applications cannot see it, except
- for the services that are normally offered.
- </para>
-
- <para>This isolation has many benefits. For example, it is not necessary for the kernel and user applications to use the same version of the Spring Framework. In fact the kernel installs only those parts of the Spring Framework that it needs. If you update the kernel, it is far less likely that you will also need to upgrade or adjust the applications to accomodate a new version of the kernel. The kernel implementation is therefore much more stable and resilient and applications are much more likely to survive kernel upgrades between releases. </para>
- <para>When you install @tomcat.product.name.short@, the kernel creates a single user region.
- The kernel and the user region are configured independently of each other; see <link linkend="configuring">Configuring @tomcat.product.name.short@</link> for details.
- </para>
-
- <para>Finally, the isolation provided by the user region together with scoped applications and plans solve common dependency problems that occur when using OSGi. </para>
- </section>
-
-</section>
-
-</section>
-
-</section>
-
-<!--========================================================================-->
-<section id="concepts.p2">
-<title>p2 Concepts</title>
-<para>
- At EclipseCon 2011 there was a great introductory presentation on p2. It gives a nice overview of the whole provisioning system.
- You can find it recorded <ulink url="http://fosslc.org/drupal/content/gentle-introduction-p2">here(video).</ulink>
-</para>
-<para>
- <ulink url="http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/">This blog post</ulink>
- provides some background on why p2 was created as well as a brief overview of what p2 repositories
- are and how this relates to a runtime.
-</para>
-<para>
- This <ulink url="http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit">presentation(slides only)</ulink>
- sheds light on more advanced p2 features and turns our attention to its extension points.
-</para>
-<para>
- Finally, the <ulink url="http://wiki.eclipse.org/Equinox/p2">p2 wiki</ulink>
- also provides both getting started guides as well as information on more advanced features.
-</para>
-</section>
-
-</chapter>
diff --git a/user-guide/src/configuring.xml b/user-guide/src/configuring.xml
deleted file mode 100644
index 802c5d3..0000000
--- a/user-guide/src/configuring.xml
+++ /dev/null
@@ -1,1840 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="configuring">
- <title>Configuration</title>
- <titleabbrev>Configuration</titleabbrev>
-
- <para>You use configuration files in the <literal>$SERVER_HOME/configuration</literal> directory to configure @project.name@. You can also configure the OSGi framework using files the same <literal>$SERVER_HOME/configuration</literal> directory. This section divides the configuration of the server into the following high-level tasks:</para>
-
- <itemizedlist>
- <listitem><para><link linkend="configuring-osgi-framework">Configuring the OSGi framework</link></para></listitem>
- <listitem><para><link linkend="configuring-framework-extensions">Configuring framework extensions and fragments on the system bundle</link></para></listitem>
- <listitem><para><link linkend="configuring-serviceability">Configuring serviceability</link></para></listitem>
- <listitem><para><link linkend="configuring-provisioning-repository">Configuring the local provisioning repository</link></para></listitem>
- <listitem><para><link linkend="configuring-hosted-repo">Configuring the hosted repository</link></para></listitem>
- <listitem><para><link linkend="configuring-kernel">Configuring the kernel and User Region</link></para></listitem>
- <listitem><para><link linkend="configuring-tomcat">Configuring the embedded Tomcat servlet container</link></para></listitem>
- <listitem><para><link linkend="configuring-web">Configuring the web integration layer</link></para></listitem>
- <listitem><para><link linkend="configuring-jetty">Configuring the embedded Jetty servlet container</link></para></listitem>
- </itemizedlist>
- <note>
- <title>Why is there both a config and a configuration directory?</title>
- <para>The <emphasis>config</emphasis> directory has always contained @project.name@ configuration files. When @nano.product.name@ and its support for p2 provisioning was introduced in @project.name@ 3.5.0, a <emphasis>configuration</emphasis> directory replaced the old <emphasis>config</emphasis> one. Now all @project.name@ configurations are assembled in that directory providing a single point of configuration. The directory name <emphasis>configuration</emphasis> in the installation's root is used by default in p2 to configure the OSGi framework during provisioning.</para>
- <para>This chapter makes it clear which configuration goes in each directory.</para>
- </note>
- <note>Sections 4-6 and 8-9 does not apply for @nano.product.name@.</note>
-
- <section id="configuring-osgi-framework" >
- <title>Configuring the OSGi Framework</title>
-
- <para>
- This section provides information about configuring the OSGi framework by updating the following files in the <literal>$SERVER_HOME/configuration</literal> directory:
- </para>
-
- <table id="configuring-osgi-framework-table" colsep="1" frame="all" rowsep="1">
- <title>OSGi Framework Configuration Files </title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Property File</entry>
- <entry>Description</entry>
- <entry>Location</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>config.ini</literal></entry>
- <entry>Configures <link linkend="configuring-framework-properties">OSGi framework properties</link>.</entry>
- <entry>$SERVER_HOME/configuration</entry>
- </row>
- <row>
- <entry><literal>bundles.info</literal></entry>
- <entry>Configures <link linkend="configuring-framework-bundles">OSGi framework bundles</link>.</entry>
- <entry>$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator</entry>
- </row>
- <row>
- <entry><literal>java6-server.profile</literal></entry>
- <entry>Configures the <link linkend="configuring-framework-profile">OSGi framework profile</link>.</entry>
- <entry>$SERVER_HOME/configuration</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section id="configuring-framework-properties">
- <title>Configuring OSGi Framework Properties</title>
-
- <para>
- You specify the framework properties in the <literal>$SERVER_HOME/configuration/config.ini</literal> file. The
- properties most relevant to users are described in the following table.
- </para>
- <para>
- <emphasis role="bold">WARNING:</emphasis> We strongly recommend that you update only the
- properties below; updating other properties could cause @project.name@
- to fail.
- </para>
-
- <table id="configuring-framework-properties-table" colsep="1" frame="all" rowsep="1">
- <title>Framework Properties</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>org.eclipse.virgo.kernel.startup.wait.limit</literal></entry>
- <entry>
- Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel.
- The default value is 180.
- </entry>
- </row>
- <row>
- <entry><literal>org.eclipse.virgo.suppress.heap.dumps</literal></entry>
- <entry>
- Set to 'false' by default this property will prevent heap dumps being contributed to dumps taken during a
- First Failure Data Capture (FFDC) event. When the heap dumps are produced they will be located along with
- the other dump artifacts in the <literal>$SERVER_HOME/serviceability/dump/</literal> folder.
- </entry>
- </row>
- <row>
- <entry><literal>osgi.java.profile</literal></entry>
- <entry>
- Specifies the profile to use using a <literal>file:</literal> URI with default value
- <literal>file:configuration/java6-server.profile</literal>.
- </entry>
- </row>
- <row>
- <entry><literal>osgi.bundlefile.limit</literal></entry>
- <entry>
- Specifies a limit on the number of jar files the framework will keep open.
- The minimum value allowed is 10. Any value less than 10 will disable the bundle file limit, making the the number of jar files the framework keeps open unlimited.
- By default the value is 100.
- Increase the default value if you have many jar files in the bundle class path, expect a lot of file system operations etc.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="configuring-framework-bundles">
- <title>Configuring OSGi Framework Bundles</title>
-
- <para>
- You specify the framework bundles in the <literal>$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</literal> file. The syntax
- that is accepted for listing bundles there is:
- <screen><bsn>,<version>,<jar-location>,<start-level>,<toStart?>
-bsn - the bundle's symbolic name string
-version - the bundle's version string
-jar-location - relative or absolute path to the jar file
-start-level - a digit indicating the bundle's start level
-toStart? - true or false value indicating whether a bundle should be started or not</screen>
- <para>Here's an example:</para>
- <screen>org.eclipse.virgo.util.osgi,3.1.0.BUILD-20111031165127,plugins/org.eclipse.virgo.util.osgi_3.1.0.BUILD-20111031165127.jar,4,true</screen>
- </para>
- <para>
- <emphasis role="bold">WARNING:</emphasis> We strongly recommend that you don't remove bundles already present in your bundles.info file as that may break your server. Add bundles here only if absolutely necessary.
- </para>
- </section>
-
- <section id="configuring-framework-profile">
- <title>Configuring OSGi Framework Profile</title>
-
- <para>
- You specify the framework profile in the <literal>$SERVER_HOME/configuration/java6-server.profile</literal> file. The
- properties most relevant to users are described in the following table.
- </para>
- <para>
- <emphasis role="bold">WARNING:</emphasis> We advise you not to change the framework profile unless you are sure you know exactly what
- you are doing; updating the profile could cause @project.name@ to fail.
- </para>
-
- <table id="configuring-framework-profile-table" colsep="1" frame="all" rowsep="1">
- <title>Framework Profile Properties</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>org.osgi.framework.bootdelegation</literal></entry>
- <entry>
- <para>
- This property specifies the packages which are loaded by delegation to the application class loader.
- Bundles can load classes belonging to these packages without importing the packages.
- The <literal>.*</literal> wildcard matches any package suffix. <literal>java.*</literal> is always
- boot delegated and must not be specified in this property.
- </para>
- <para>
- A common reason for adding packages to this property is to run @project.name@ under a performance profiler.
- </para>
- </entry>
- </row>
- <row>
- <entry><literal>org.osgi.framework.system.packages</literal></entry>
- <entry>
- <para>
- This property specifies the packages which are exported by the system bundle.
- </para>
- <para>
- Although the system bundle is typically imported into the User Region, any additional packages will not be
- visible in the User Region unless you also import them using the <literal>packagedImports</literal> property.
- See <link linkend="configuring-user-region">Configuring the User Region</link> for instructions.
- </para>
- <para>
- It is very occasionally necessary to extend the set, for example when configuring email logging appenders since the
- implementation of <literal>javax.mail</literal> is intimately related to the implementation of
- <literal>javax.activation</literal>.
- </para>
- <para>
- To make the corresponding classes available for loading, the relevant JAR file(s) should be placed in
- <literal>$SERVER_HOME/lib</literal> so that they will be added to the application class path.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- <section id="configuring-framework-extensions" >
- <title>Configuring Framework Extensions and Fragments on the System Bundle</title>
-
- <para>
- This section provides information about configuring framework extensions and fragments on the system bundle. Deployment of such bundles is not allowed in
- @project.name@. This is because by refreshing or uninstalling them the system.bundle is also refreshed, which causes @project.name@ to crash.
- </para>
- <para>
- <emphasis role="bold">NOTE:</emphasis> This only applies for fragments on the system bundle. All other fragment bundles have no deployment restrictions.
- </para>
- <para>
- Generally it's best to avoid usage of such fragment bundles as they are a common OSGi framework issue and often require restarting the framework.
- However sometimes there are no other options and one has to use framework extensions or fragments on the system bundle.
- </para>
- <para>
- You can configure framework extensions and system bundle fragments as follows:
- </para>
- <para>
- <emphasis role="bold">1.</emphasis> Place your fragment bundle in the <literal>/plugins</literal> directory of your @project.name@ installation.
- <para>
- Lets say we have bundle with
- </para>
- <programlisting>
-symbolic name: <emphasis>testFragment</emphasis>, version: <emphasis>1.0.0</emphasis> and filename: <emphasis>testFragmentBinary_1.0.0.jar</emphasis>
- </programlisting>
- </para>
- <para>
- <emphasis role="bold">2.</emphasis> Configure the <literal>bundles.info</literal> file in <literal>/configuration/org.eclipse.equinox.simpleconfigurator</literal> to include the
- just copied fragment or framework extension bundle.
- <para>
- Add a line at the end of the <literal>bundles.info</literal> file similar to this one:
- </para>
- <programlisting>
-<emphasis>testFragment,1.0.0,plugins/testFragmentBinary_1.0.0.jar,4,false</emphasis>
- </programlisting>
- </para>
- <para>
- <emphasis role="bold">3.</emphasis> Configure the <literal>org.eclipse.virgo.kernel.userregion.properties</literal> file in <literal>/configuration</literal> folder to import the fragment bundle or framework extension in the User Region.
- <para>
- Add to the <literal>bundleImports</literal> property a new line describing the fragment bundle using its symbolic name and version.
- </para>
- <programlisting>
-bundleImports = org.eclipse.osgi;bundle-version="0",<emphasis role="bold">testFragment;bundle-version="0"</emphasis>
- </programlisting>
- </para>
- </section>
-
- <section id="configuring-serviceability">
- <title>Configuring Serviceability and Diagnostics</title>
-
- <para>The serviceability features of @project.name@ allow you to gather and view data and information that you can then use to diagnose problems and failures. Serviceability data includes:</para>
- <itemizedlist>
- <listitem><para>
- Service dumps: Contain a snapshot of all the important state from the running @project.name@ instance when an internal failure or thread deadlock is detected.
- </para>
- <para>You configure service dumps for @project.name@ using the <link linkend="configuring-serviceability-medic">org.eclipse.virgo.medic.properties</link> file in the <literal>$SERVER_HOME/configuration</literal> directory. This file also includes some additional logging configuration.</para>
- </listitem>
- <listitem><para>
- Event logs and server/application (trace) logging: Logging support in @project.name@ is based on <ulink url="http://logback.qos.ch/">Logback</ulink>. This means that you have complete control over the format of log output and have the complete range of Logback's appenders available for your use.
- </para>
- <para>You configure logging for @project.name@ using the <link linkend="configuring-serviceability-logback">serviceability.xml</link> file in the <literal>$SERVER_HOME/configuration</literal> directory. This file is essentially the Logback <literal>logback.xml</literal> (or <literal>logback-test.xml</literal>) configuration file but renamed for @project.name@. </para>
- </listitem>
- </itemizedlist>
-
- <para>For additional conceptual information about the serviceability subsystem, see <xref linkend="serviceability" />. </para>
-
- <section id="configuring-serviceability-medic">
- <title>The org.eclipse.virgo.medic.properties File</title>
-
- <para>The <literal>$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties</literal> file configures @project.name@ service dumps and whether you want to capture <literal>System.out</literal> and <literal>System.err</literal> output to your application's trace file. </para>
- <para>The following table describes the properties you can include in the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties</literal> file. This file configures serviceability properties that @project.name@ includes in addition to those supplied by the Logback, configured in the <literal>serviceability.xml</literal> file.</para>
-
- <table id="medic-properties-table" colsep="1" frame="all" rowsep="1">
- <title>Serviceability Properties</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
-
- <row>
- <entry><literal>dump.root.directory</literal></entry>
- <entry>Specifies the directory to which @project.name@ writes the service dumps. The directory name is relative to <literal>$SERVER_HOME</literal>. </entry>
- </row>
-
- <row>
- <entry><literal>log.wrapSysOut</literal></entry>
- <entry>Specifies whether you want to capture <literal>System.out</literal> output from your applications to the application trace file. The output is logged by @project.name@'s root logger, which captures <literal>INFO</literal> level and above.
- <para>Valid values for this property are <literal>true</literal> to capture <literal>System.out</literal> output, or <literal>false</literal> to disable the capture.</para>
- <para>For more information, see <link linkend="sysout-and-syserr">System.out and System.err</link>.</para>
- </entry>
- </row>
-
- <row>
- <entry><literal>log.wrapSysErr</literal></entry>
- <entry>Specifies whether you want to capture <literal>System.err</literal> output from your applications to the application trace file. The output is logged by @project.name@'s root logger, which captures <literal>INFO</literal> level and above.
- <para>Valid values for this property are <literal>true</literal> to capture <literal>System.err</literal> output, or <literal>false</literal> to disable the capture.</para>
- <para>For more information, see <link linkend="sysout-and-syserr">System.out and System.err</link>.</para>
- </entry>
- </row>
-
- <row>
- <entry><literal>log.jul.consoleHandler</literal></entry>
- <entry>Specifies whether you want to use the <literal>ConsoleHandler</literal> of Java Util Logging. The default JVM configuration uses the handler to write logs to <literal>System.err</literal>.
- <para>Valid values for this property are <literal>true</literal> to enable <literal>ConsoleHandler</literal> output, or <literal>false</literal> to disable it. The default value is <literal>false</literal>.</para>
- <para>For more information, see <ulink url="http://download.oracle.com/javase/6/docs/technotes/guides/logging/overview.html">Java Logging Overview</ulink>.</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
- <section id="configuring-serviceability-logback">
- <title>The serviceability.xml File</title>
- <para>Logging support in @project.name@ is based on <ulink url="http://logback.qos.ch/">Logback</ulink>, which is a successor of the log4j project. The Logback logging framework is faster, more reliable, and easier to use than log4j and certain other logging systems.</para>
- <para>You configure logging for @project.name@ using the <literal>$SERVER_HOME/configuration/serviceability.xml</literal> file. This file is the standard Logback <literal>logback.xml</literal> or <literal>logback-test.xml</literal> configuration file, but renamed for @project.name@. </para>
- <para>The following listing shows the default <literal>serviceability.xml</literal> file in a freshly-installed @project.name@; see the text after the listing for a brief overview of the file:</para>
- <programlisting language="xml"><![CDATA[<configuration>
-
- <jmxConfigurator />
-
- <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
-
- <appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender">
- <discriminator>
- <Key>applicationName</Key>
- <DefaultValue>virgo-server</DefaultValue>
- </discriminator>
- <sift>
- <appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>serviceability/logs/${applicationName}/log.log</file>
- <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
- <FileNamePattern>serviceability/logs/${applicationName}/log_%i.log</FileNamePattern>
- <MinIndex>1</MinIndex>
- <MaxIndex>4</MaxIndex>
- </rollingPolicy>
- <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
- <MaxFileSize>10MB</MaxFileSize>
- </triggeringPolicy>
- <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
- <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
- </encoder>
- </appender>
- </sift>
- </appender>
-
- <appender name="LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>serviceability/logs/log.log</file>
- <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
- <FileNamePattern>serviceability/logs/log_%i.log</FileNamePattern>
- <MinIndex>1</MinIndex>
- <MaxIndex>4</MaxIndex>
- </rollingPolicy>
- <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
- <MaxFileSize>10MB</MaxFileSize>
- </triggeringPolicy>
- <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
- <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
- </encoder>
- </appender>
-
- <appender name="EVENT_LOG_STDOUT" class="org.eclipse.virgo.medic.log.logback.ReroutingAwareConsoleAppender">
- <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
- <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread <%X{medic.eventCode}> %msg %ex%n</Pattern>
- </encoder>
- </appender>
-
- <appender name="EVENT_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>serviceability/eventlogs/eventlog.log</file>
- <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
- <FileNamePattern>serviceability/eventlogs/eventlog_%i.log</FileNamePattern>
- <MinIndex>1</MinIndex>
- <MaxIndex>4</MaxIndex>
- </rollingPolicy>
- <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
- <MaxFileSize>10MB</MaxFileSize>
- </triggeringPolicy>
- <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
- <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread <%X{medic.eventCode}> %msg %ex%n</Pattern>
- </encoder>
- </appender>
-
- <logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.localized">
- <appender-ref ref="EVENT_LOG_STDOUT" />
- <appender-ref ref="EVENT_LOG_FILE" />
- </logger>
-
- <logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.default">
- <appender-ref ref="SIFTED_LOG_FILE" />
- <appender-ref ref="LOG_FILE" />
- </logger>
-
- <root level="INFO">
- <appender-ref ref="SIFTED_LOG_FILE" />
- <appender-ref ref="LOG_FILE" />
- </root>
-
-</configuration>]]></programlisting>
-
- <para>Logback allows @project.name@ to use logger, appender, and encoder (layout) objects to log messages according to message type and level and to format these messages and define where they are written. The default <literal>serviceability.xml</literal> file shown above includes four appenders and three loggers (two user and one root.)</para>
-
- <para>The main information to get from this file is that @project.name@ writes log messages to four different locations that map to the four appenders:</para>
- <itemizedlist>
- <listitem><para>The <literal>jmxConfigurator</literal> provides a possibility to configure logback via JMX. For more information see <ulink url="http://logback.qos.ch/manual/jmxConfig.html">JMX Configurator</ulink> documentation.</para></listitem>
- <listitem><para>The <literal>contextListener</literal> propagates the changes made to the levels of logback loggers to Java Util Logging (JUL). For more information see <ulink url="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator">LevelChangePropagator</ulink> documentation.</para> </listitem>
- <listitem><para>The <literal>SIFTED_LOG_FILE</literal> appender logs both global and application-specific messages to the <literal>$SERVER_HOME/serviceability/logs/</literal><emphasis><literal>applicationName</literal></emphasis><literal>/log.log</literal> file, where <emphasis><literal>applicationName</literal></emphasis> refers to the name of the application. The log messages for @project.name@ itself are logged to the <literal>$SERVER_HOME/serviceability/logs/virgo-server/log.log</literal> file. Because this appender creates different log files for each application, it is called a <emphasis>sifting appender</emphasis>. </para>
- <para>
- The default behaviour of these trace files is that, once <literal>log.log</literal> reaches a 10Mb limit, it rolls into a series of files named
- <literal>log_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and logging continues in
- a new <literal>log.log</literal> file. This is called its <emphasis>rolling policy</emphasis>.
- </para>
- <para>The <literal><Pattern></literal> element defines the format of each log message; messages include the timestamp, the thread that generated the log message, the context-specific event code, and a stack trace of the exception, if any. For example:</para>
- <para><literal>[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080</literal></para>
- </listitem>
- <listitem><para>The <literal>LOG_FILE</literal> appender is very similar to the first one, but it logs <emphasis>all</emphasis> log messages to the <literal>$SERVER_HOME/serviceability/log/log.log</literal> file rather than sifting application-specific messages to their own log file. The rolling policy and message format for this appender is similar to that of the <literal>SIFTED_LOG_FILE</literal> appender.</para></listitem>
- <listitem><para>The <literal>EVENT_LOG_STDOUT</literal> appender does not log messages to a file, but rather to the console window from which you started @project.name@. For example:</para>
- <para><literal>[2010-10-25 16:20:49.367] Thread-3 <WE0000I> Starting web bundle 'org.eclipse.virgo.apps.admin.web' version '2.1.0.RELEASE' with context path '/admin'.</literal></para>
- </listitem>
-
- <listitem><para>The <literal>EVENT_LOG_FILE</literal> appender logs only important events to the <literal>$SERVER_HOME/serviceability/eventlogs/eventlog.log</literal> file, and thus the volume of information is much lower than with the first two appenders. The rolling policy for the event log is the same as with the first two appenders, but the format of the messages is similar to that of the <literal>EVENT_LOG_STDOUT</literal> appender. </para> </listitem>
- </itemizedlist>
-
- <para>The loggers and root logger specify the level of log that is written for each of the referenced appenders.</para>
-
- <para>Typically, the default logging configuration as specified by the <literal>serviceability.xml</literal> file is adequate for all @project.name@ environments. However, if you want to customize logging further, you can edit this file as well as the <literal>org.eclipse.virgo.medic.properties</literal>. See the <ulink url="http://logback.qos.ch/manual/index.html">logback documentation</ulink> for detailed information about the architecture and the configuration of Logback.</para>
- </section>
-
- </section>
-
- <section id="configuring-provisioning-repository">
- <title>Configuring the Local Provisioning Repository</title>
- <para>
- You configure the locations that @project.name@ includes in its provisioning repository
- by editing the <literal>org.eclipse.virgo.repository.properties</literal> file in the <literal>$SERVER_HOME/configuration</literal> directory.
- </para>
- <para>When you specify a property in the file, use the format <literal>repository-name.property=value</literal>, where:
- <itemizedlist>
- <listitem><para><literal>repository-name</literal> refers to the name of the local repository.</para></listitem>
- <listitem><para><literal>property</literal> refers to the name of a particular property.</para></listitem>
- <listitem><para><literal>value</literal> refers to the value of the property.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>For example, <literal>ext.type=external</literal> specifies that the <literal>type</literal> property of the repository
- with name <literal>ext</literal> is <literal>external</literal>.
- </para>
- <para>
- The <literal>chain</literal> property specifies the order in which @project.name@ searches the individual repositories
- when it looks for dependencies.
- The <literal>chain</literal> property uses the names of the individual repositories as specified in the individual repository properties;
- for example, in the property <literal>ext.type=external</literal>, the name of the repository is <literal>ext</literal>.
- </para>
- <para>
- The default repository configuration for a newly installed @project.name@ instance is as follows:
- <programlisting><![CDATA[ext.type=external
-ext.searchPattern=repository/ext/{artifact}
-
-usr.type=watched
-usr.watchDirectory=repository/usr
-
-chain=ext,usr]]></programlisting>
- </para>
-
-
- <para>
- The default configuration shown above has two searchpaths corresponding to the two default sub-directories of the <literal>$SERVER_HOME/repository</literal> directory created when you first install @project.name@: <literal>ext</literal> and <literal>usr</literal>. @project.name@ searches each of these individual repositories when locating entries for inclusion in the repository. </para>
- <para>
- The <literal>chain</literal> property shows the order in which @project.name@ searches the individual repositories: first <literal>ext</literal> and then <literal>usr</literal>.
- </para>
- <para>
- The following table lists all the available properties that you can use to configure an individual repository.
- Individual repositories as well as the repository search chain are configured in the file
- <literal>$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</literal>.
- <table id="repository-options-table" colsep="1" frame="all" rowsep="1">
- <title>Repository Properties</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- Property
- </entry>
- <entry>
- Description
- </entry>
- <entry>
- Default Value
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <emphasis><literal>repository-name</literal></emphasis><literal>.type</literal>
- </entry>
- <entry>
- <para>
- Specifies the type of path. You can set this property to one of the following three valid values:
- <itemizedlist>
- <listitem>
- <para>
- <literal>external</literal>: Specifies that this path points to a number of directories that satisfy a given search pattern
- and are local to the current @project.name@ instance.
- Use the <literal>searchPattern</literal> property to specify the directory search pattern.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>watched</literal>: Specifies that this path points to a single directory, local to the current @project.name@ instance.
- @project.name@ regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
- @project.name@ also scans its local watched repositories when deploying any artifact.
- Use the <literal>watchDirectory</literal> property to specify the watched directory
- and the <literal>watchInterval</literal> property to specify how often @project.name@ checks the directory.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>remote</literal>: Specifies that the path points to a remotely-hosted repository,
- hosted by a remote instance of @tomcat.product.name@.
- Use the <literal>uri</literal> property to specify the full URI of the remote repository.
- You can also specify the optional <literal>indexRefreshInterval</literal> property.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- See <link linkend="configuring-repository-watched-versus-external">Watched or External Repository?</link>
- for additional information about when to configure watched or external repositories for your particular environment.
- </para>
- </entry>
- <entry>
- <emphasis>no default</emphasis>
- </entry>
- </row>
- <row>
- <entry>
- <emphasis><literal>repository-name</literal></emphasis><literal>.searchPattern</literal>
- </entry>
- <entry>
- <para>
- Specifies the pattern that an external repository uses when deciding which local directories it should search
- when identifying artifacts. Use this property together with <emphasis><literal>repository-name</literal></emphasis><literal>.type=external</literal>.
- See <link linkend="configuring-provisioning-repository-search-paths" >Search Paths: Additional Information</link>
- for detailed information about specifying a search pattern.
- </para>
- </entry>
- <entry>
- <emphasis>no default</emphasis>
- </entry>
- </row>
- <row>
- <entry>
- <emphasis><literal>repository-name</literal></emphasis><literal>.watchDirectory</literal>
- </entry>
- <entry>
- <para>
- Specifies the single directory of a watched repository.
- You can specify either an absolute or relative pathname for the directory.
- If you specify a relative pathname, it is relative to the root of the @project.name@ installation (<literal>$SERVER_HOME</literal>).
- Use this property together with <emphasis><literal>repository-name</literal></emphasis><literal>.type=watched</literal>.
- </para>
- </entry>
- <entry>
- <emphasis>no default</emphasis>
- </entry>
- </row>
- <row>
- <entry>
- <emphasis><literal>repository-name</literal></emphasis><literal>.watchInterval</literal>
- </entry>
- <entry>
- <para>
- Specifies the interval in seconds between checks of a watched directory by a watched repository.
- Use this property together with <emphasis><literal>repository-name</literal></emphasis><literal>.type=watched</literal>.
- </para>
- </entry>
- <entry>
- <literal>5</literal>
- </entry>
- </row>
- <row>
- <entry>
- <emphasis><literal>repository-name</literal></emphasis><literal>.uri</literal>
- </entry>
- <entry>
- <para>
- Specifies the URI of the hosted repository to which a remote repository connects.
- The value of this property takes the following format:
- </para>
- <para> <literal>http://</literal><emphasis><literal>host</literal></emphasis><literal>:</literal><emphasis><literal>port</literal></emphasis><literal>/org.eclipse.virgo.apps.repository/</literal><emphasis><literal>remote-repository-name</literal></emphasis>
- </para>
- <para>
- where:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><literal>host</literal></emphasis> refers to the computer on which the remote @tomcat.product.name.short@
- instance hosts the remote repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><literal>port</literal></emphasis> refers to a Tomcat listener port of the remote @tomcat.product.name.short@
- instance which hosts the remote repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><literal>remote-repository-name</literal></emphasis> refers to the name of the remote repository,
- as specified in the <literal>org.eclipse.virgo.apps.repository.properties</literal> file of the remote @tomcat.product.name.short@ instance.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Use this property together with <emphasis><literal>repository-name</literal></emphasis><literal>.type=remote</literal>.
- </para>
- </entry>
- <entry>
- <emphasis>no default</emphasis>
- </entry>
- </row>
- <row>
- <entry>
- <emphasis><literal>repository-name</literal></emphasis><literal>.indexRefreshInterval</literal>
- </entry>
- <entry>
- <para>
- Specifies the interval in seconds between checks by a remote repository that
- its local copy of the hosted repository index is up-to-date
- (a remote repository acts as a proxy for a hosted repository and thus it holds a local copy of the hosted repository’s index).
- </para>
- <para>
- Use this property together with <emphasis><literal>repository-name</literal></emphasis><literal>.type=remote</literal>.
- </para>
- </entry>
- <entry>
- <literal>5</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <section id="configuring-repository-watched-versus-external">
- <title>Should I Configure a Watched or External Repository?</title>
- <para>The main difference between a watched and an external repository is that @project.name@ regularly scans watched directories
- and automatically picks up any changed artifacts,
- while @project.name@ scans external directories only at startup, and then only if there is no cached index available.
- This means that @project.name@ always performs a scan of an external repository when you start the server
- with the <literal>-clean</literal> (as this deletes the index) and only scans during a normal startup if the index isn’t there because,
- for example, this is the first time you start the server.
- </para>
- <para>There is a performance cost associated with using a watched repository due to @project.name@ using resources
- to scan the directory at the configured interval.
- The cost is small if the watched repository contains just a few artifacts; however,
- the performance cost increases as the number of artifacts increases.
- Note that @project.name@ re-scans its local watched repositories when deploying any artifact, so the scanning interval
- can be configured to be relatively long.
- </para>
- <para> For this reason, we recommend that you put most of your dependencies in external repositories,
- even when in development mode.
- If you make any changes to the artifacts in the external repositories,
- remember to restart @project.name@ with the <literal>-clean</literal> option so that the server picks up any changes.
- Use watched directories for artifacts that you are prototyping, actively updating, or when adding new dependencies
- so that @project.name@ quickly and easily picks them up.
- To increase performance even during development, however, you can use an external repository for most of your dependencies,
- in particular the ones that are fairly static.
- </para>
-
- <para>In production environments, where dependencies should not change,
- we recommend that you use <emphasis>only</emphasis> external repositories.
- </para>
- </section>
-
- <section id="configuring-provisioning-repository-search-paths">
- <title>Search Paths: Additional Information</title>
- <para>
- The <emphasis><literal>repository-name</literal></emphasis><literal>.searchPattern</literal> and
- <emphasis><literal>repository-name</literal></emphasis><literal>.watchDirectory</literal> properties specify search paths
- for external and watched repositories, respectively,
- that define a physical location that @project.name@ searches when looking for a library or bundle dependency.
- If a search path is relative, its location is relative to the root of the installation,
- in other words, the <literal>$SERVER_HOME</literal> directory.
- </para>
- <section id="configuring-provisioning-repository-search-paths-wildcards">
- <title>Using Wildcards</title>
- <para>
- Search paths specified with the <emphasis><literal>repository-name</literal></emphasis><literal>.searchPattern</literal> property
- provide support for wildcards.
- In the entries above, the path segments surrounded by curly braces,
- for example <literal>{bundle}</literal> and <literal>{library}</literal>,
- are wildcards entries for a directory with any name.
- Allowing wildcards to be named in this way is intended to improve the readability of search path configuration.
- </para>
- <para>
- In addition to supporting the above-described form of wildcards, @project.name@ also supports Ant-style paths,
- that is <literal>*</literal> and <literal>**</literal> can be used to represent any directory and
- any series of directories, respectively.
- For example, <literal>repository/usr/{bundle}</literal> and <literal>repository/usr/*</literal>
- are equivalent.
- </para>
- <para>
- A common usage of the <literal>**</literal> wildcard is to allow dependencies stored in a directory structure of varying depth,
- such as a local Maven repository, to be provisioned by the @project.name@.
- </para>
- </section>
- </section>
- <section id="configuring-provisioning-repository-using-system-properties">
- <title>Using System Properties</title>
- <para>
- You can use system properties when specifying the values of the <emphasis><literal>repository-name</literal></emphasis><literal>.searchPattern</literal>,
- <emphasis><literal>repository-name</literal></emphasis><literal>.watchDirectory</literal>,
- <emphasis><literal>repository-name</literal></emphasis><literal>.watchInterval</literal>,
- <emphasis><literal>repository-name</literal></emphasis><literal>.uri</literal>,
- and <emphasis><literal>repository-name</literal></emphasis><literal>.indexRefreshInterval</literal>
- properties.
- You reference system properties as <literal>${system.property.name}</literal>;
- for example, a search path of <literal>${user.home}/repository/bundles</literal> references the
- <literal>repository/bundles</literal> directory in the user’s home directory.
- </para>
- </section>
- <section id="configuring-provisioning-repository-examples">
- <title>Example Repository Configurations</title>
- <para>
- The following examples provide sample configuration that could be used for some common use cases.
- </para>
- <section id="configuring-provisioning-repository-examples-ivy">
- <title>Add an Ivy cache repository</title>
- <para>The following example shows how to add an external repository whose location is actually an Ivy cache.</para>
- <para><emphasis>Note that Ivy repositories can contain bundles which will conflict with the normal operation of Virgo, so care should
- be exercised when adding such an external repository.</emphasis></para>
- <programlisting><![CDATA[ext.type=external
-ext.searchPattern=repository/ext/{artifact}
-
-usr.type=watched
-usr.watchDirectory=repository/usr
-
-ivy-repo.type=external
-ivy-repo.searchPattern=${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar
-
-chain=ext,usr,ivy-repo]]></programlisting>
-
- </section>
- <section id="configuring-provisioning-repository-examples-maven">
- <title>Add a Maven local repository</title>
- <para>The following example shows how to add an external repository whose location is actually a Maven repository.</para>
- <para><emphasis>Note that Maven repositories can contain bundles which will conflict with the normal operation of Virgo, so care should
- be exercised when adding such an external repository.</emphasis></para>
- <programlisting><![CDATA[ext.type=external
-ext.searchPattern=repository/ext/{artifact}
-
-usr.type=watched
-usr.watchDirectory=repository/usr
-
-maven-repo.type=external
-maven-repo.searchPattern=${user.home}/.m2/repository/**/{bundle}.jar
-
-chain=ext,usr,maven-repo]]></programlisting>
-
- </section>
- <section id="configuring-repository-examples-remote-watched">
- <title>Add remote and watched repositories</title>
- <para>The following example shows the default <literal>org.eclipse.virgo.repository.properties</literal> file
- from a freshly-installed @project.name@ instance, but then updated to include new remote and watched repositories.
- Both of these repositories are part of the repository chain.
- </para>
- <para>The remote repository is called <literal>remote-repo</literal>.
- The URI of the hosted repository from which <literal>remote-repo</literal> gets its artifacts is
- <literal>http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo</literal>;
- this means that there is a @tomcat.product.name.short@ instance running on host <literal>my-host</literal>
- whose Tomcat server listens at the default port, <literal>8080</literal>,
- and this server instance hosts a repository called <literal>my-hosted-repo</literal>,
- configured in the <literal>org.eclipse.virgo.apps.repository.properties</literal> file of the remote server instance.
- The remote repository checks for changes in the hosted repository every 30 seconds.
- </para>
- <para>The watched repository is called <literal>watched-repo</literal> and the directory that holds the artifacts
- is <literal>repository/watched</literal>,
- relative to the installation directory of the @tomcat.product.name.short@ instance.
- The server checks for changes in this watched repository every 5 seconds.
- </para>
- <programlisting><![CDATA[ext.type=external
-ext.searchPattern=repository/ext/{artifact}
-
-usr.type=watched
-usr.watchDirectory=repository/usr
-
-remote-repo.type=remote
-remote-repo.uri=http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo
-remote-repo.indexRefreshInterval=30
-
-watched-repo.type=watched
-watched-repo.watchedDirectory=repository/watched
-watched-repo.watchedInterval=5
-
-chain=ext,usr,remote-repo,watched-repo]]></programlisting>
- </section>
- </section>
- </section>
-
- <section id="configuring-hosted-repo">
- <title>Configuring a Hosted Repository</title>
- <para>You configure a @tomcat.product.name.short@ instance to host a repository
- by editing the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties</literal> file;
- remote clients can then access the artifacts in this hosted repository and use them locally.
- </para>
- <para>When you specify a property in the file, use the format <literal>repository-name.property=value</literal>, where:
- <itemizedlist>
- <listitem><para><literal>repository-name</literal> refers to the name of the hosted repository.</para></listitem>
- <listitem><para><literal>property</literal> refers to the name of a particular property.</para></listitem>
- <listitem><para><literal>value</literal> refers to the value of the property.</para></listitem>
- </itemizedlist>
- </para>
- <para>For example, <literal>my-hosted-repo.type=external</literal> specifies that the <literal>type</literal> property
- of the <literal>my-hosted-repo</literal> repository is <literal>external</literal>.
- </para>
- <para>The following table lists the properties that you can include in the <literal>org.eclipse.virgo.apps.repository.properties</literal> file.
- </para>
- <table id="hosted-repository-properties-table" colsep="1" frame="all" rowsep="1">
- <title>Hosted Repository Properties</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><emphasis><literal>repository-name</literal></emphasis><literal>.type</literal></entry>
- <entry>Specifies the type of path of the hosted repository.
- All paths are local to the current @tomcat.product.name.short@ instance.
- You can set this property to one of the following valid values:
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>external</literal>: Specifies that this path points to a number of directories that satisfy a given search pattern.
- Use the <literal>searchPattern</literal> property to specify the directory search pattern.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>watched</literal>: Specifies that this path points to a single directory.
- @project.name@ regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
- Use the <literal>watchDirectory</literal> property to specify the actual watched directory and the <literal>watchInterval</literal> property
- to specify how often @tomcat.product.name.short@ checks the directory.
- </para>
- </listitem>
- </itemizedlist>
- <para>See <link linkend="configuring-repository-watched-versus-external">Watched or External Repository?</link>
- for additional information about when to configure watched or external repositories for your particular environment.
- </para>
- </entry>
- </row>
- <row>
- <entry><emphasis><literal>repository-name</literal></emphasis><literal>.searchPattern</literal></entry>
- <entry> <para>Specifies the pattern that an external hosted repository uses when deciding which
- local directories it should search when identifying artifacts.
- Use this property when <literal>repository-name.type=external</literal>.
- See <link linkend="configuring-provisioning-repository-search-paths" >Search Paths: Additional Information</link>
- for detailed information about specifying a search pattern.
- </para> </entry>
- </row>
- <row>
- <entry><emphasis><literal>repository-name</literal></emphasis><literal>.watchDirectory</literal></entry>
- <entry> <para>Specifies the single directory of a watched hosted repository.
- You can specify either an absolute or relative pathname for the directory.
- If you specify a relative pathname, it is relative to the root of the @tomcat.product.name.short@ installation (<literal>$SERVER_HOME</literal>).
- Use this property when <literal>repository-name.type=watched</literal>.
- </para></entry>
- </row>
- <row>
- <entry><emphasis><literal>repository-name</literal></emphasis><literal>.watchInterval</literal></entry>
- <entry> <para>Specifies the interval in seconds between checks of a watched directory by a watched hosted repository.
- This property is optional. Use this property when <literal>repository-name.type=watched</literal>.
- </para> </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The following sample shows a <literal>org.eclipse.virgo.apps.repository.properties</literal> file with a single external repository
- called <literal>my-hosted-repo</literal> with search pattern <literal>$SERVER_HOME/repository/hosted/*</literal>.
- <programlisting><![CDATA[my-hosted-repo.type=external
-my-hosted-repo.searchPattern=repository/hosted/*]]></programlisting>
- </para>
-
- <para>See <link linkend="configuring-repository-examples-remote-watched">Example of watched and remote repositories</link>
- for details on how a local repository can remotely access the artifacts in this hosted repository.
- </para>
- </section>
-
- <section id="configuring-kernel" >
- <title>Configuring the Kernel and User Region</title>
- <para>This section provides information about configuring the @project.name@ kernel and the User Region.</para>
-
- <section id="configuring-kernel-properties">
- <title>Configuring the Kernel</title>
-
- <para>To change any of the kernel properties, provide the new value to the startup script. The following table describes all properties.</para>
- <table id="configuring-kernel-table" colsep="1" frame="all" rowsep="1">
- <title>Kernel Configuration Properties</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- Property (prefixed by <literal>org.eclipse.virgo</literal>)
- </entry>
- <entry>
- Description
- </entry>
- <entry>
- Default Value
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>.kernel.home</literal>
- </entry>
- <entry>
- Specifies the location of the @kernel.product.name@.
- </entry>
- <entry>
- <literal>$SERVER_HOME</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>.kernel.config</literal>
- </entry>
- <entry>
- Specifies the location of the @kernel.product.name@ and User Region <link linkend="configuring-kernel-files">configuration files</link>.
- The location of the configuration files can also be specified using
- <link linkend="starting-stopping-configuration-directory"><literal>-configDir</literal> startup parameter</link>.
- </entry>
- <entry>
- <literal>$SERVER_HOME/configuration</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>.kernel.domain</literal>
- </entry>
- <entry>
- Specifies the <ulink url="http://download.oracle.com/javase/6/docs/api/javax/management/ObjectName.html">JMX domain</ulink> that should be
- used by the @kernel.product.name@.
- </entry>
- <entry>
- <literal>org.eclipse.virgo.kernel</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>.kernel.startup.wait.limit</literal>
- </entry>
- <entry>
- Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel.
- See <link linkend="configuring-framework-properties">Configuring OSGi Framework Properties</link> for the recommended way
- to configure this parameter.
- </entry>
- <entry><literal>180</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="configuring-kernel-files">
- <title>Configuration Files</title>
- <para>The configuration of the @kernel.product.name@ and User Region by default is located in the <literal>$SERVER_HOME/configuration</literal> directory:</para>
- <table id="configuring-kernel-files-table" colsep="1" frame="all" rowsep="1">
- <title>Kernel Configuration Files </title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property File</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>org.eclipse.virgo.kernel.properties</literal></entry>
- <entry>Configures <link linkend="configuring-deployment">deployment</link>. </entry>
- </row>
- <row>
- <entry><literal>org.eclipse.virgo.kernel.userregion.properties</literal></entry>
- <entry>Configures the <link linkend="configuring-user-region">User Region</link> of @project.name@.</entry>
- </row>
- <row>
- <entry><literal>org.eclipse.virgo.kernel.users.properties</literal></entry>
- <entry>Configures the <link linkend="configuring-authentication">users that are allowed to access</link> the Admin Console, and roles to which they map. </entry>
- </row>
- <row>
- <entry><literal>org.eclipse.virgo.kernel.jmxremote.access.properties</literal></entry>
- <entry>Configures the <link linkend="configuring-authentication">permissions for users</link> that are allowed to access the Admin Console. </entry>
- </row>
- <row>
- <entry><literal>org.eclipse.virgo.kernel.authentication.config</literal></entry>
- <entry>Configures the <link linkend="configuring-authentication">Java Authentication and Authorization Service (JAAS)</link> for the Tomcat server users.</entry>
- </row>
- <row>
- <entry><literal>osgi.console.ssh.properties</literal></entry>
- <entry>Configures the kernel SSH console. See <xref linkend="admin-shell-enable"/>.</entry>
- </row>
- <row>
- <entry><literal>osgi.console.telnet.properties</literal></entry>
- <entry>Configures the kernel telnet console. See <xref linkend="admin-shell-enable"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="configuring-deployment">
- <title>Configuring Deployment</title>
-
- <para>
- You can configure various properties of deployment: the pickup directory into which you copy applications for hot-deployment, the deployment timeout,
- and whether or not bundles are unpacked during deployment.
- </para>
- <para>To change any of these properties, edit the <literal>deployer.XXX</literal> properties of the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.properties</literal> file. The following table describes these properties. </para>
- <table id="configuring-deployment-table" colsep="1" frame="all" rowsep="1">
- <title>Deployment Configuration Properties</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- Property
- </entry>
- <entry>
- Description
- </entry>
- <entry>
- Default Value
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>deployer.pickupDirectory</literal>
- </entry>
- <entry>
- Specifies the absolute or relative path to the pickup directory to which you copy applications for hot-deployment.
- Relative paths are relative to <literal>$SERVER_HOME</literal>.
- </entry>
- <entry>
- <literal>./pickup</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>deployer.timeout</literal>
- </entry>
- <entry>
- Specifies the amount of time, in seconds, after which @project.name@ times out while trying to deploy an artifact.
- If you want to disable deployment timeout, specify <literal>0</literal>.
- </entry>
- <entry>
- <literal>300</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>deployer.scanIntervalMillis</literal>
- </entry>
- <entry>
- Specifies the scan interval, in milliseconds, used to survey the pickup directory.
- </entry>
- <entry>
- <literal>1000</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>deployer.unpackBundles</literal>
- </entry>
- <entry>
- Determines whether or not bundles (with file extension <literal>.jar</literal> or <literal>.war</literal>) are unpacked
- during deployment. The value must be either <literal>true</literal> or <literal>false</literal>.
- <para>
- If you want to deploy bundles packed, specify <literal>false</literal>.
- This option can help alleviate a known issue with <link linkend="long-work-paths">long work directory paths under Windows</link>.
- </para>
- <para>
- Note that web applications may behave differently depending on whether they are deployed packed or unpacked.
- Certain servlet API methods return <literal>null</literal> when a web application is deployed packed.
- </para>
- </entry>
- <entry>
- <literal>true</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>WABHeaders</literal>
- </entry>
- <entry>
- <para>
- This kernel property is only relevant for @nanoweb.product.name@. For the corresponding property in @tomcat.product.name@, see <link linkend="configuring-web">Configuring the Web Integration Layer</link>.
- </para>
- <para>
- Specifies how Web Application Bundle manifest headers are processed.
- See "Web Application Manifest Processing" in the
- <ulink url="../../virgo-programmer-guide/html/index.html">Programmer Guide</ulink> for details.
- </para>
- <para>
- A value of <literal>strict</literal> causes @nanoweb.product.name@ to interpret certain headers in strict compliance with
- the OSGi Web Applications specification if they are not specified.
- </para>
- <para>
- A value of <literal>defaulted</literal> causes @nanoweb.product.name@ to set certain headers to default values if they are not specified.
- <emphasis>This value is provided as a migration aid and may not be supported in future releases.</emphasis>
- </para>
- </entry>
- <entry>
- <literal>strict</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The following listing displays the default configuration distributed with @project.name@; only relevant sections of the <literal>org.eclipse.virgo.kernel.properties</literal> file are shown. </para>
-
- <programlisting><![CDATA[deployer.timeout=300
-deployer.pickupDirectory=pickup
-deployer.scanIntervalMillis=1000]]></programlisting>
-
- <para>So the default deployment timeout is 300 seconds, the default pickup directory is <literal>$SERVER_HOME/pickup</literal> and the default scan interval is <literal>1000</literal>.
- </para>
- </section>
-
- <section id="configuring-user-region">
- <title>Configuring the User Region</title>
- <para>
- The User Region is the subsystem of @project.name@ that
- supports deployed applications, both your own user applications and
- those of the server itself, such as the Admin Console. The User Region
- is deliberately isolated from the kernel, which protects the kernel from interference by applications.
- </para>
- <para>
- You configure the User Region by updating properties in the
- <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.userregion.properties</literal>
- file; these properties are described in the following table.
- </para>
- <para>
- <emphasis role="bold">WARNING:</emphasis>
- We strongly recommend that you update only the
- <literal>initialArtifacts</literal>
- property; updating other properties could cause
- @project.name@ to fail. These properties are documented for your
- information.
- </para>
-
- <table id="configuring-user-region-table" colsep="1" frame="all" rowsep="1">
- <title>User Region Configuration Properties</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>baseBundles</literal></entry>
- <entry>Specifies the hard-coded list of bundles that @project.name@ installs directly into the User Region.
- @project.name@ does not perform any automatic dependency satisfaction for these bundles; in other words, you only get the bundles
- in the list and nothing more. </entry>
- </row>
- <row>
- <entry><literal>bundleImports</literal></entry>
- <entry>
- <para>
- Specifies the bundles in the kernel that @project.name@ imports into the User Region so that they are visible to bundles in the User Region.
- This property supports an optional <literal>bundle-version</literal> attribute which specifies a version range.
- By default only the system bundle is imported.
- </para>
- <para>
- Note that packages exported by these bundles are <emphasis>not</emphasis> automatically made available in the User Region: these must be specified using the
- <literal>packageImports</literal> property.
- </para>
- </entry>
- </row>
- <row>
- <entry><literal>packageImports</literal></entry>
- <entry>
- <para>
- Specifies the packages in the kernel that @project.name@ imports into the User Region so that they are in turn available to be
- imported by bundles in the User Region.
- This property supports a <literal>.*</literal> wildcard which is expanded based on the packages available in the kernel
- when the User Region is created.
- For example, <literal>org.eclipse.virgo.util.*</literal> will import all packages that start with
- <literal>org.eclipse.virgo.util.</literal> (but <emphasis>not</emphasis> the package <literal>org.eclipse.virgo.util</literal>
- which would need to be specified separately to be imported).
- </para>
- <para>
- The property also supports matching attributes such as <literal>version</literal>, <literal>bundle-symbolic-name</literal>,
- <literal>bundle-version</literal>, and user-defined attributes. This can be used to import all the packages of a bundle imported using the
- <literal>bundleImports</literal> property.
- For example the following imports all the packages of the system bundle:
- <programlisting><![CDATA[packageImports=*;bundle-symbolic-name="org.eclipse.osgi",\
- ...]]></programlisting>
- Note that if a package is specified more than once in <literal>packageImports</literal>, the last occurrence is used and the earlier
- occurrences are ignored.
- For this reason, it is recommended that imports specifying matching attributes are placed earlier in the list than other imports so that
- if an import is specified with and without matching attributes, the form without the matching attributes is used.
- </para>
- </entry>
- </row>
- <row>
- <entry><literal>serviceImports</literal></entry>
- <entry>Specifies the services in the kernel that are imported into the User Region so they are available to bundles in the User Region. </entry>
- </row>
- <row>
- <entry><literal>serviceExports</literal></entry>
- <entry>Specifies the services in the User Region that are exported to the kernel so they are available to bundles in the kernel. </entry>
- </row>
- <row>
- <entry><literal>initialArtifacts</literal></entry>
- <entry>
- <para>
- Specifies the artifacts that @project.name@ deploys into the User Region when the server starts.
- @project.name@ performs dependency satisfaction when it deploys these artifacts.
- This means that you only need to list the top-level artifacts that you care about; @project.name@ automatically installs,
- from the repository, any other artifacts upon which they depend.
- </para>
- <para>
- The artifacts are specified as a comma separated list of URI strings of the form:
- <programlisting><![CDATA[repository:type/name[/version]]]></programlisting>
- where <literal>type</literal> is the artifact type (e.g. "plan", "par", "bundle",
- "configuration"), <literal>name</literal> is the (symbolic) name of the artifact, and, optionally,
- <literal>version</literal> is the version of the artifact.
- If <literal>version</literal> is omitted and there is at least one artifact in the repository with the given type and name, then the
- artifact with the highest version is selected.
- So, for example, the following entries are valid:
- <programlisting><![CDATA[initialArtifacts=...,\
- repository:plan/APlan,\
- repository:bundle/ABundle/1.0]]></programlisting>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section id="configuring-user-region-consoles">
- <title>Configurating User Region Consoles</title>
- <para>The configuration of the User Region consoles is located by default in the <literal>$SERVER_HOME/repository/ext</literal> directory:</para>
- <table id="configuring-user-region-consoles-table" colsep="1" frame="all" rowsep="1">
- <title>User Region Console Configuration Files </title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property File</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>osgi.console.ssh.properties</literal></entry>
- <entry>Configures the User Region SSH console. See <xref linkend="admin-shell-enable"/>.</entry>
- </row>
- <row>
- <entry><literal>osgi.console.telnet.properties</literal></entry>
- <entry>Configures the User Region telnet console. See <xref linkend="admin-shell-enable"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- </section>
-
- <section id="configuring-authentication">
- <title>Configuring Authentication</title>
- <para>
- @project.name@ uses the
- <ulink
- url="http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">Java Authentication and Authorization Service (JAAS)</ulink>
- framework to authenticate the administration user that connects to Web
- Servers using the Admin Console. This section describes
- how the authentication mechanism is configured by default, and the
- files that you need to update if you want to change the administration
- user, change their password, and so on.
- </para>
- <para>The <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.authentication.config</literal> file configures the underlying authentication technology for @project.name@. The short file consists of the following entries:</para>
-
- <programlisting>virgo-kernel {
- org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
-};
-equinox_console {
- org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
-};</programlisting>
-
- <para>The entry named <literal>virgo-kernel</literal> corresponds to the <literal><Realm></literal> element in the <literal>$SERVER_HOME/configuration/tomcat-server.xml</literal> file that configures the JAAS authentication mechanism for the <literal>Catalina</literal> service of the <link linkend="configuring-tomcat">Tomcat servlet container</link>. The <literal>virgo-kernel</literal> entry specifies that the JAAS LoginModule that @project.name@ uses to authenticate users is <literal>org.eclipse.virgo.kernel.authentication.KernelLoginModule</literal> and that this <literal>KernelLoginModule</literal> is required to "succeed" in order for authentication to be considered successful. The <literal>KernelLoginModule</literal> succeeds only if the name and password supplied by the user are the ones it expects. The default administration username/password pair for @tomcat.product.name.short@ is <literal>admin/springsource</literal>. </para>
- <para>
- The entry named <literal>equinox_console</literal> controls ssh authentication for the Virgo shell. It also uses the <literal>KernelLoginModule</literal>.
- </para>
-
- <para>You configure the administration user in the <literal>org.eclipse.virgo.kernel.users.properties</literal> file. The default file for a freshly installed @project.name@ is as follows:</para>
-
- <programlisting>##################
-# User definitions
-##################
-user.admin=springsource
-
-##################
-# Role definitions
-##################
-role.admin=admin</programlisting>
-
- <para>
- The administration user that connect to the Admin Console must have the
- <literal>admin</literal>
- role. The preceding file shows how, by default, the
- <literal>admin</literal>
- role is assigned the
- <literal>admin</literal>
- user with password
- <literal>springsource</literal>.
- </para>
-
- <para>If you want to change the administration user, update the <literal>org.eclipse.virgo.kernel.users.properties</literal> file. For example, if you want the <literal>juliet</literal> user, with password <literal>supersecret</literal>, to be the new adminstration user, update the file as shown:</para>
-
-
- <programlisting>##################
-# User definitions
-##################
-user.juliet=supersecret
-
-##################
-# Role definitions
-##################
-role.admin=juliet</programlisting>
-
- <para>Be sure to restart @project.name@ after you make this change for it to take effect.</para>
-
- <para>The final file involved in @project.name@ authentication is <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.jmxremote.access.properties</literal>. This file specifies the JMX access privileges that the administration user has; by default they are read and write, as shown in the following listing:</para>
- <programlisting>admin=readwrite</programlisting>
- <para>
- The only other value you can enter is
- <literal>readonly</literal>, which means that the adminstration user would only be able to <emphasis>view</emphasis>
- information using the Admin Console.
- </para>
- </section>
-
-
- </section>
-
- <section id="configuring-tomcat">
- <title>Configuring the Embedded Tomcat Servlet Container</title>
- <note>@nano.product.name@ uses the default Gemini Web configuration. The details described below may still apply.</note>
- <para>
- @project.name@
- embeds an OSGi-enhanced version of the <ulink url="http://tomcat.apache.org/">Tomcat Servlet Container</ulink>
- in order to provide support for deploying Java EE WARs and OSGi <emphasis>Web Application Bundles</emphasis>.
- You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called <filename>tomcat-server.xml</filename> rather than <literal>server.xml</literal>. As with the other @project.name@ configuration files, the <literal>tomcat-server.xml</literal> file is located in the <literal>$SERVER_HOME/configuration</literal> directory.
- Another difference is that not all standard Apache Tomcat configuration is supported in @tomcat.product.name@: the restrictions are described in the
- remainder of this section.
- </para>
- <para>Here's an extract of the default configuration distributed with the @tomcat.product.name.short@.
- </para>
- <programlisting language="xml"><![CDATA[<?xml version='1.0' encoding='utf-8'?>
-<Server port="8005" shutdown="SHUTDOWN">
-
- <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
- <Listener className="org.apache.catalina.core.JasperListener" />
- <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
-
- <Listener className="org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener"/>
-
- <Service name="Catalina">
- <Connector port="8080" protocol="HTTP/1.1"
- connectionTimeout="20000"
- redirectPort="8443" />
-
- <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
- maxThreads="150" scheme="https" secure="true"
- clientAuth="false" sslProtocol="TLS"
- keystoreFile="configuration/keystore"
- keystorePass="changeit"/>
-
- <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
-
- <Engine name="Catalina" defaultHost="localhost">
- <Realm className="org.apache.catalina.realm.JAASRealm" appName="virgo-kernel"
- userClassNames="org.eclipse.virgo.kernel.authentication.User"
- roleClassNames="org.eclipse.virgo.kernel.authentication.Role"/>
-
- <Host name="localhost" appBase="webapps"
- unpackWARs="false" autoDeploy="false"
- deployOnStartup="false" createDirs="false">
-
- <Valve className="org.apache.catalina.valves.AccessLogValve" directory="serviceability/logs/access"
- prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/>
-
- <Valve className="org.eclipse.virgo.web.tomcat.ApplicationNameTrackingValve"/>
- </Host>
- </Engine>
- </Service>
-</Server>]]></programlisting>
-
- <section id="overview-tomcat-servlet-container">
- <title>Description of the Default Apache Tomcat Configuration</title>
- <para>
- The following bullets describe the main elements and attributes in the default <literal>tomcat-server.xml</literal> file; for details about updating this file to further configure the embedded Apache Tomcat server, see the <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html">Apache Tomcat Configuration Reference</ulink>.
- </para>
-
- <tip>
- <title>Relative paths</title>
- <para>If the configured path to a directory or file does not represent an absolute path, @project.name@ typically interprets it as a path relative to the <filename>$SERVER_HOME</filename> directory.</para>
- </tip>
-
- <itemizedlist>
- <listitem><para>The root element of the <literal>tomcat-server.xml</literal> file is <literal><Server></literal>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The <literal>shutdown</literal> attribute specifies the command string that the shutdown port number receives via a TCP/IP connection in order to shut down the servlet container. The <literal>port</literal> attribute specifies the TCP/IP port number that listens for a shutdown message.</para></listitem>
-
- <listitem><para>The <literal><Listener></literal> XML elements specify the list of lifecycle listeners that monitor and manage the embedded Tomcat servlet container. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the servlet container and has been programmed to do something at certain lifecycle events of the component, such as before starting up, after stopping, and so on.</para>
- <para> The first four <literal><Listener></literal> elements configure standard Tomcat lifecycle listeners. The listener implemented by the <literal>org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener</literal> class is specific to @tomcat.product.name@ and manages server lifecycle logging.
- </para> </listitem>
-
- <listitem><para>The <literal><Service></literal> XML element groups together one or more connectors and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to to send and receive messages to and from the associated service. There are many transports that a client can use, which is why a <literal><Service></literal> element can have many <literal><Connector></literal> elements. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the servlet container; you can define only a single <literal><Engine></literal> element for any given <literal><Service></literal> element.</para>
-
- <para> The sample <literal>tomcat-server.xml</literal> file above includes three <literal><Connector></literal> elements: one for the HTTP transport, one for the HTTPS transport, and one for the AJP transport. The file also includes a single <literal><Engine></literal> element, as required.
- </para></listitem>
-
- <listitem><para>The first connector listens for HTTP requests at the <literal>8080</literal> TCP/IP port. The connector, after accepting a connection from a client, waits for a maximum of 20000 milliseconds for a request URI; if it does not receive one from the client by then, the connector times out. If this connector receives a request from the client that requires the SSL transport, the servlet container automatically redirects the request to port <literal>8443</literal>. </para>
- </listitem>
-
- <listitem><para>The second connector is for HTTPS requests. The TCP/IP port that users specify as the secure connection port is <literal>8443</literal>. Be sure that you set the value of the <literal>redirectPort</literal> attribute of your non-SSL connectors to this value to ensure that users that require a secure connection are redirected to the secure port, even if they initially start at the non-secure port. The <literal>SSLEnabled</literal> attribute specifies that SSL is enabled for this connector. The <literal>secure</literal> attribute ensures that a call to <literal>request.isSecure()</literal> from the connecting client always returns <literal>true</literal>. The <literal>scheme</literal> attribute ensures that a call to <literal>request.getScheme()</literal> from the connecting client always returns <literal>https</literal> when clients use this connector. </para>
- <para>The <literal>maxThreads</literal> attribute specifies that the servlet container creates a maximum of 150 request processing threads,
- which determines the maximum number of simultaneous requests that can be handled.
- The <literal>clientAuth</literal> attribute specifies that the servlet container does not require a certificate chain
- unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication.
- </para>
- <para>The <literal>keystoreFile</literal> attribute specifies the name of the file that contains the servlet container’s
- private key and public certificate used in the SSL handshake, encryption, and decryption.
- You use an alias and password to access this information.
- In the example, this file is <literal>$SERVER_HOME/configuration/keystore</literal>.
- The <literal>keystorePass</literal> attributes specify the password used to access the keystore.
- </para></listitem>
-
- <listitem><para>The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.
- </para></listitem>
- <listitem><para>The engine has a logical name of <literal>Catalina</literal>;
- this is the name used in all log and error messages so you can easily identify problems.
- The value of the <literal>defaultHost</literal> attribute refers to the name of a <literal><Host></literal>
- child element of <literal><Engine></literal>;
- this host processes requests directed to host names on this servlet container.
- </para>
- </listitem>
-
- <listitem> <para>The <literal><Realm></literal> child element of <literal><Engine></literal> represents a database of
- users, passwords, and mapped roles used for authentication in this service. Virgo Web Server uses an implementation of the Tomcat 6 Realm interface that authenticates users through the Java Authentication and Authorization Service (JAAS) framework which is provided as part of the standard J2SE API.</para>
- <para>With the JAASRealm, you can combine practically any conceivable security realm with Tomcat's container managed authentication. For details, see <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html">Realm Configuration</ulink>.</para>
-
- </listitem>
- <listitem><para>The <literal><Host></literal> child element represents a virtual host,
- which is an association of a network name for a server (such as <literal>www.mycompany.com</literal>) with the particular
- server on which Catalina is running.
- The servlet container unpacks Web applications into a directory hierarchy if they are deployed as WAR files.
- </para>
- <para>
- Note that multiple <literal><Host></literal> elements are not supported in @tomcat.product.name@.
- </para>
- </listitem>
-
- <listitem><para>Finally, the <literal>org.apache.catalina.valves.AccessLogValve</literal> valve creates log files
- in the same format as those created by standard web servers.
- The servlet container creates the log files in the <literal>$SERVER_HOME/serviceability/logs/access</literal> directory.
- The log files are prefixed with the string <literal>localhost_access_log.</literal>, have a suffix of <literal>.txt</literal>,
- use a standard format for identifying what should be logged, and do not include DNS lookups of the IP address of the remote host.
- </para> </listitem>
-
- </itemizedlist>
- </section>
-
- <section id="configuring-tomcat-connectors">
- <title>Connector Configuration</title>
- <para> The @tomcat.product.name@ supports the configuration of any connector supported by Apache Tomcat.
- See the default configuration above for syntax examples, and for further details of the configuration properties
- supported for various <literal><Connector></literal> implementations,
- consult the official <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/http.html">Tomcat HTTP Connector</ulink> documentation.
- </para>
- <tip>
- <title>Configuring SSL for Tomcat</title>
- <para> The @tomcat.product.name@ distribution includes a preconfigured <filename>$SERVER_HOME/configuration/keystore</filename>
- file that contains a single self-signed SSL Certificate.
- The password for this <filename>keystore</filename> file is <literal>changeit</literal>.
- This <filename>keystore</filename> file is intended for testing purposes only.
- For detailed instructions on how to configure Tomcat’s SSL support,
- consult the official <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html">Tomcat SSL Configuration HOW-TO</ulink>.
- </para>
- </tip>
- </section>
-
- <section id="configuring-tomcat-clustering">
- <title>Cluster Configuration</title>
- <para>
- @tomcat.product.name@ supports standard Apache Tomcat cluster configuration.
- By default, clustering of the embedded servlet container is disabled,
- and the default configuration does not include any clustering information.
- See <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html">Tomcat Clustering/Session Replication HOW-TO</ulink>
- for detailed information about enabling and configuring clustering.
- </para>
- </section>
-
- <section id="configuring-default-web-xml">
- <title>Default web.xml Configuration</title>
- <para>
- Java Servlet specification enables web applications to provide deployment descriptor (<literal>web.xml</literal>) in the <literal>WEB-INF</literal> directory.
- Apache Tomcat introduces a default <literal>web.xml</literal> which is similar to web application's <literal>web.xml</literal>, but provides configurations that are applied to all web applications.
- When deploying a web application, Apache Tomcat uses the default <literal>web.xml</literal> file as a base configuration.
- If the web application provides its own configurations via <literal>web.xml</literal> (the one located in the web application's <literal>WEB-INF</literal>) or annotations, they overwrite the default ones.
- In @tomcat.product.name@ you can also provide default configurations for all web applications.
- If you want to change/extend the default configurations, you can provide the default <literal>web.xml</literal> file located in the <literal>@tomcat.product.name.short@_HOME/configuration</literal> directory.
- </para>
- <para>
- <tip>Be careful when changing/extending the default <literal>web.xml</literal> as this will affect all web applications.</tip>
- </para>
- <para>
- Here's an extract of the default configuration distributed with the @tomcat.product.name.short@.
- </para>
- <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>
-<web-app xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
- version="3.0">
-
- <servlet>
- <servlet-name>default</servlet-name>
- <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
- <init-param>
- <param-name>debug</param-name>
- <param-value>0</param-value>
- </init-param>
- <init-param>
- <param-name>listings</param-name>
- <param-value>false</param-value>
- </init-param>
- <load-on-startup>1</load-on-startup>
- </servlet>
-
- <servlet>
- <servlet-name>jsp</servlet-name>
- <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
- <init-param>
- <param-name>fork</param-name>
- <param-value>false</param-value>
- </init-param>
- <init-param>
- <param-name>xpoweredBy</param-name>
- <param-value>false</param-value>
- </init-param>
- <load-on-startup>3</load-on-startup>
- </servlet>
-
- <servlet-mapping>
- <servlet-name>default</servlet-name>
- <url-pattern>/</url-pattern>
- </servlet-mapping>
-
- <servlet-mapping>
- <servlet-name>jsp</servlet-name>
- <url-pattern>*.jsp</url-pattern>
- </servlet-mapping>
-
- <servlet-mapping>
- <servlet-name>jsp</servlet-name>
- <url-pattern>*.jspx</url-pattern>
- </servlet-mapping>
-
- <session-config>
- <session-timeout>30</session-timeout>
- </session-config>
-
- <mime-mapping>
- <extension>abs</extension>
- <mime-type>audio/x-mpeg</mime-type>
- </mime-mapping>
- ......
- <mime-mapping>
- <extension>ppt</extension>
- <mime-type>application/vnd.ms-powerpoint</mime-type>
- </mime-mapping>
-
- <welcome-file-list>
- <welcome-file>index.html</welcome-file>
- <welcome-file>index.htm</welcome-file>
- <welcome-file>index.jsp</welcome-file>
- </welcome-file-list>
-
-</web-app>
-]]></programlisting>
- <para>
- The following bullets describe the main elements in the default <literal>web.xml</literal> file.
- <itemizedlist>
- <listitem>
- <para>The <literal><Servlet></literal> XML element declares a given servlet and its configurations. The sample <literal>web.xml</literal> file above includes two <Servlet> elements.</para>
- <itemizedlist>
- <listitem>
- <para>
- The default servlet serves static resources and processes the requests that are not mapped to any servlet.
- For details about default servlet configuration, see the <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/default-servlet.html">Apache Tomcat Default Servlet Reference.</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- The jsp servlet serves the requests to JavaServer Pages. It is mapped to the URL pattern "*.jsp" and "*.jspx".
- For details about jsp servlet configuration, see the <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html">Apache Tomcat Jasper 2 JSP Engine.</ulink>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>The <literal><servlet-mapping></literal> XML element specifies the mapping between the servlet and URL pattern.</para>
- </listitem>
- <listitem>
- <para>
- The <literal><session-config></literal> XML element defines the session configuration for one web application.
- The sample <literal>web.xml</literal> file above specifies that the session timeout for all web applications will be 30 minutes by default.
- </para>
- </listitem>
- <listitem>
- <para>
- The <literal><mime-mapping></literal> XML element defines a mapping between a filename extension and a mime type.
- When serving static resources, a "Content-Type" header will be generated based on these mappings.
- </para>
- </listitem>
- <listitem>
- <para>
- The <literal><welcome-file-list></literal> XML element specifies a list of welcome files.
- When a request URI refers to a directory, the default servlet looks for a "welcome file" within that directory.
- If the "welcome file" exists it will be served, otherwise 404 status or directory listing will be returned, depending on the default servlet configuration.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="configuring-tomcat-contexts">
- <title>Context Configuration</title>
- <para>
- @tomcat.product.name@ supports standard Apache Tomcat web application context configuration.
- The <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html">Apache Tomcat Configuration Reference</ulink> has a section on
- <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html">The Context Container</ulink> which describes the mechanism that
- is used in @tomcat.product.name.short@ for searching context configuration files and details the context configuration properties.
- </para>
- <para>
- Context configuration files may be placed in the following locations,
- where <literal>[enginename]</literal> is the name of Tomcat's engine ('Catalina' by default) and <literal>[hostname]</literal> names
- a virtual host ('localhost' by default), both of which are configured in <literal>tomcat-server.xml</literal>:
- <itemizedlist>
- <listitem>
- <para>
- <literal>$SERVER_HOME/configuration/context.xml</literal> provides the default context configuration file for all web applications.
- </para>
- </listitem>
- <listitem>
- <para>
- The <literal>$SERVER_HOME/configuration/[enginename]/[hostname]</literal> directory may contain:
- <itemizedlist>
- <listitem>
- <para>
- The default context configuration for all web applications of a given virtual host in the file <literal>context.xml.default</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference.
- For example, the context for a web application with
- context path <literal>foo</literal> may be configured in <literal>foo.xml</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Note that the following context configuration features are not supported in @tomcat.product.name@:
- <itemizedlist>
- <listitem>
- <para>
- Custom class loaders.
- </para>
- </listitem>
- <listitem>
- <para>
- Specifying the context path. This is specified using the <literal>Web-ContextPath</literal> header in the web application's
- <literal>MANIFEST.MF</literal> file.
- </para>
- </listitem>
- <listitem>
- <para>
- Specifying the document base directory.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="configuring-jsp-compilation">
- <title>JSP Compilation</title>
- <para>
- By default Apache Tomcat compiles JSP files in web applications agains Java 1.6.
- In order to enable JSP compilation against Java 1.7 for your web application,
- additional init parameters (<literal>compilerSourceVM</literal> and <literal>compilerTargetVM</literal>) should be added for the <literal>org.apache.jasper.servlet.JspServlet</literal> configuration.
- For details about <literal>org.apache.jasper.servlet.JspServlet</literal> configuration, see the <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html">Apache Tomcat Jasper 2 JSP Engine</ulink>.
- <literal>org.apache.jasper.servlet.JspServlet</literal> configuration can be provided with the web application's web.xml.
- </para>
- <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>
-<servlet>
- <servlet-name>jsp</servlet-name>
- <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
- <init-param>
- <param-name>compilerSourceVM</param-name>
- <param-value>1.7</param-value>
- </init-param>
- <init-param>
- <param-name>compilerTargetVM</param-name>
- <param-value>1.7</param-value>
- </init-param>
- <init-param>
- <param-name>fork</param-name>
- <param-value>false</param-value>
- </init-param>
- <init-param>
- <param-name>xpoweredBy</param-name>
- <param-value>false</param-value>
- </init-param>
- <load-on-startup>3</load-on-startup>
-</servlet>
-<servlet-mapping>
- <servlet-name>jsp</servlet-name>
- <url-pattern>*.jsp</url-pattern>
- <url-pattern>*.jspx</url-pattern>
- </servlet-mapping>
-]]></programlisting>
- </section>
- </section>
-
- <section id="configuring-web">
- <title>Configuring the Web Integration Layer</title>
- <para>
- @tomcat.product.name@ integrates an OSGi-enhanced version of the <ulink url="http://tomcat.apache.org/">Tomcat Servlet Container</ulink>
- in order to provide support for deploying Java EE WARs and OSGi <emphasis>Web Application Bundles</emphasis>.
- </para>
- <para>
- For @tomcat.product.name@ you
- configure the behaviour of the Web Integration Layer using the properties file called <literal>org.eclipse.virgo.web.properties</literal>.
- The <literal>org.eclipse.virgo.web.properties</literal> file is located in the <literal>$SERVER_HOME/repository/ext</literal> directory.
- </para>
- <para>The following table describes the properties. </para>
- <table id="configuring-web-integration-layer" colsep="1" frame="all" rowsep="1">
- <title>Web Integration Layer Properties</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- Property
- </entry>
- <entry>
- Description
- </entry>
- <entry>
- Default Value
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>WABHeaders</literal>
- </entry>
- <entry>
- <para>
- Specifies how Web Application Bundle manifest headers are processed.
- See "Web Application Manifest Processing" in the
- <ulink url="../../virgo-programmer-guide/html/index.html">Programmer Guide</ulink> for details.
- </para>
- <para>
- A value of <literal>strict</literal> causes @tomcat.product.name.short@ to interpret certain headers in strict compliance with
- the OSGi Web Applications specification if they are not specified.
- </para>
- <para>
- A value of <literal>defaulted</literal> causes @tomcat.product.name.short@ to set certain headers to default values if they are not specified.
- This was how @tomcat.product.name.short@ behaved prior to version 3.
- <emphasis>This value is provided as a migration aid and may not be supported in future releases.</emphasis>
- A warning event log message (WE0006W) is generated if this value is specified.
- </para>
- <para>
- The @jetty.product.name@ will always operate in <literal>strict</literal> mode.
- </para>
- <para>
- @nanoweb.product.name@ does not have a Web Integration Layer, but has a corresponding kernel property.
- See <link linkend="configuring-deployment">Configuring Deployment</link>.
- </para>
- </entry>
- <entry>
- <literal>strict</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- There is no Web Integration Layer in @jetty.product.name@. The relevant configuration is described in
- <link linkend="configuring-jetty">Configuring the Embedded Jetty Servlet Container</link>.
- </para>
- </section>
-
- <section id="configuring-jetty">
- <title>Configuring the Embedded Jetty Servlet Container</title>
- <para>
- @jetty.product.name@ supports <emphasis>Web Application Bundles</emphasis>, but does not provide support for Java EE WARs.
- </para>
- <para>
- The @jetty.product.name@ contains a standard Jetty configuration file at <literal>SERVER_HOME/jetty/etc/jetty.xml</literal>.
- This has been tailored to the @umbrella.product.name@. To make modifications please refer to the
- <ulink url="http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty#Using_Jetty_XML">Jetty documentation</ulink>.
- </para>
- </section>
-
-</chapter>
diff --git a/user-guide/src/docs/asciidoc/admin-console.adoc b/user-guide/src/docs/asciidoc/admin-console.adoc
new file mode 100644
index 0000000..edcee37
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/admin-console.adoc
@@ -0,0 +1,219 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:admin-console[]
+
+== The Web Admin Console
+
+The Admin Console
+
+The Web Server Admin Console is a Web application for managing a single instance of {tomcat-product-name} or {jetty-product-name}
+(referred to, generically, as "Web Server" below). Using the Admin Console, you can:
+
+* xref:admin-console-login[View an overview of the Web Server properties].
+* xref:admin-console-manage-artifacts[View and manage the lifecycle] of artifacts already deployed to the Web Server instance. Artifacts include bundles, configuration files, PARs, and plans. Lifecycle management tasks include starting, stopping, refreshing, and uninstalling the artifacts.
+* xref:admin-console-install-artifacts[Install new artifacts to Web Server].
+* xref:admin-console-view-properties[View the properties of the configuration artifacts] deployed to Web Server.
+* xref:admin-console-view-dumps[View details of dump files] that Web Server might have generated after encountering a problem. This feature is particularly valuable if Web Server fails to install a new artifact due to resolution failures; the OSGi state inspector can help you discover the exact artifact causing the resolution failure.
+* xref:admin-console-view-osgi-state[View an overview and details of the OSGi State] of Web Server, or in other words, a list of all bundles currently installed in Web Server and their state. You can then drill down into the details of each bundle, such as its symbolic name, packages it imports and exports, services it provides and consumes, and so on. You can also view the bundles that were deployed when an exception that generated a dump occurred.
+
+[NOTE]
+--
+This section is not applicable to {nano-product-name}.
+--
+
+ancor:admin-console-login[]
+
+=== Invoking the Admin Console
+
+To use the Admin Console, start the
+{tomcat-product-name} and then enter the following URL in your
+browser of choice.
+
+....
+http://localhost:8080/admin
+....
+
+Replace `localhost` with the hostname of the computer on which the {tomcat-product-name} is running if it is not the same as the computer on which you are running your browser.
+The Admin Console uses basic authentication, therefore you will need to enter the default administration ID and password.
+
+....
+ID: admin
+Password: admin
+....
+
+The following graphic shows the main page of the Admin Console.
+
+image:console-main-page.png"[]
+
+Use the links at the top of the console to perform various tasks, such as viewing and managing artifacts (<emphasis role="bold">Artifacts*), viewing the properties of deployed configuration artifacts (<emphasis role="bold">Configuration*), viewing details of dumps (<emphasis role="bold">Dump Inspector*), and viewing the OSGi state of the Web Server instance (<emphasis role="bold">OSGi State*).
+
+You can always return to the main Admin Console page by clicking <emphasis role="bold">Information* in the top right-hand corner.
+
+ The `Server Properties` section provides information about Web Server itself, such as details about the Java Virtual Machine (JVM), the operating system on which Web Server is installed, the time zone configured for the computer, and the complete version of Web Server.
+
+anchor:admin-console-auth[]
+
+==== Changing the Admin User
+
+To change the ID and password for the Admin Console, update the `SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties` file. First specify the administration username by changing the value of the `role.admin` property. Then set the password of this new user by adding a new property called `user.*username*`, where `*username*` refers to the actual name of the user. Finally, restart Web Server for the changes to take effect.
+For example, if you want change the administration username to `juliet` with password `capulet`, change the file as follows:
+
+[source,txt]
+----
+##################
+# User definitions
+##################
+user.juliet=capulet
+
+
+##################
+# Role definitions
+##################
+role.admin=juliet
+----
+
+The Admin Console always runs against the `admin` role.
+
+anchor:admin-console-tasks[]
+
+=== Typical Admin Console Use Cases
+
+The following use cases describe the typical tasks that you can perform with the Admin Console:
+
+* xref:admin-console-manage-artifacts[View and Manage the Lifecycle of Deployed Artifacts]
+* xref:admin-console-install-artifacts[Install a New Artifact]
+* xref:admin-console-view-properties[View the Properties of Deployed Configuration Artifacts]
+* xref:admin-console-view-dumps[View Details of Dump Files]
+* xref:admin-console-view-osgi-state[View Overview and Details of the OSGi State]
+
+anchor:admin-console-manage-artifacts[]
+
+==== Viewing and Managing the Lifecycle of Deployed Artifacts
+
+The following procedure describes how to view the list of artifacts that are currently deployed in the user region of Web Server. It then describes how to stop, start, refresh, and uninstall the deployed artifacts.
+
+. From the main Admin Console page, click the *Artifacts* link at the top.
+In the lower part of the page, the console displays a tree structure that displays the four kinds of artifacts that you can deploy to the user region of Web Server: bundles, configuration files, PARs, and plans. When you first install Web Server, there will already be a number of artifacts deployed related to the Admin console itself, the main splash screen, the repository, and so on.
+The following graphic shows an expanded tree that displays a few of the deployed artifacts:
+image:console-artifacts.png[]
+
+. To view details of a particular artifact, click the "`" to the left of the artifact to expand the tree. The following graphic shows an expanded `org.eclipse.virgo.apps.admin.web` bundle:
+image:console-bundle-details.png[]
+The particular details that the Admin Console displays depends on the artifact. For example, for all artifacts you can view their state and how it was installed (such as by a user using the Admin Console or programmatically). The two most common states are Active (running and ready to be used) and Resolved (all dependencies resolved but you must start it before you can use it). An artifact can also be in one of the transition states, such as Starting and Stopping.
+As shown in the preceding graphic, the Admin Console provides a link for Web modules that you can click on to actually invoke the application (`org.eclipse.virgo.web.contextPath:/admin` in the example above).
+For PARs and plans, the Admin Console also displays whether the artifact is:
+* *Scoped*. Scoping specifies whether Web Server should deploy the members of the PAR/plan in their own scope; when scoping is disabled, Web Server deploys the artifacts into the global scope and they are accessible by all other artifacts.
+* *Atomic*. When a PAR/plan is atomic, Web Server manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then Web Server starts all the PAR/plan artifacts. If one artifact fails to start, then Web Server stops all other artifacts in the PAR/plan.
+
+The following graphic shows details of a PAR, in particular that it is both scoped and atomic:
+image:console-par-details.png[]
+Finally, for bundles, PARs, and plans, you can see the list of bundles that they depend on; this typically means the bundles that export the packages that they import.
+
+To manage the lifecycle of an artifact, click on its name in the expanded tree to enable the lifecycle buttons. Then, depending on the current state of the artifact, you can:
+
+* Start the artifact. All dependencies of the artifact must have been resolved for you to start it. After successfully starting the artifact, it is in the Active state and you can use the application associated with the artifact.
+* Stop the artifact. This moves the artifact from an Active to Resolved state, and you cannot use the application associated with the artifact.
+* Refresh the artifact. This action updates the physical contents of the artifact; use this button when you have changed the artifact in some way and you want your changes to take effect.
+* Uninstall the artifact. This action removes the artifact from Web Server and it does not show up in the Admin Console any more. To use the application associated with this artifact, you must re-install the artifact.
+
+anchor:admin-console-install-artifacts[]
+
+==== Installing a New Artifact
+
+The following procedure describes how to install a new artifact (bundle, PAR, plan, or configuration file.) The procedure is similar for all types of artifacts; the procedure uses a WAR file as an example.
+
+. From the main Admin Console page, click the *Artifacts* link at the top.
+. Click the *Browse* button to invoke the file loader application for your platform. Note that the Browse button searches the computer that is running the browser in which you invoked the Admin Console and *not* the computer on which Web Server is running, in the case where they are different.
+Use the file loader to find the artifact. This can be a WAR or JAR file bundle, a configuration artifact that contains properties, an XML file that corresponds to a plan, or a PAR file.
+. Click *Upload* to actually upload the artifact to Web Server.
+Web Server automatically attempts to resolve all dependencies, and then puts the artifact in an Active state if possible. If all is successful, the message `Artifact Deployed` appears next to the <emphasis role="bold">Artifact Console* header. If there is an error, a message to that effect is displayed; to get more details about the error, see the terminal window from which you started Web Server.
+. Expand the artifact tree to view your newly deployed artifact. If Web Server installed it without errors, it should show up in the appropriate section and be in an Active state.
+
+anchor:admin-console-view-properties[]
+
+=== Viewing Properties of Deployed Configuration Artifacts
+
+The following procedure describes how you can view the list of configuration artifacts that are currently deployed to Web Server, and then view the specific properties that are defined for a particular configuration artifact.
+
+. From the main Admin Console page, click the <emphasis role="bold">Configuration* link at the top.
+The Admin Console displays all the configuration artifacts that are currently deployed, as shown in the following graphic:
+image:console-configuration-details.png[]
+. To view the properties defined for a particular configuration artifact click the arrow to the left of its name.
+
+anchor:admin-console-view-dumps[]
+
+==== Viewing the Details of Dump Files
+
+The following procedure describes how to view the details of any service dumps that have occurred in Web Server. Each time a dump is triggered for Web Server, the server creates a directory in `$SERVER_HOME/serviceability/dump` with a name corresponding to the time the dump occurred, and then the server populates the directory with detailed information. Using the Admin Console, you can easily view this information.
+A service dump is triggered when there is either a failure in the Web Server code or Web Server detects a thread deadlock in either its own code or a user application. The service dump contains a snapshot of all the important state from the running Web Server instance. <emphasis role="bold">NOTE:* This snapshot is not intended for end user consumption but is useful for service personnel.
+
+. From the main Admin Console page, click the *Dump Inspector* link at the top.
+. In the drop-down box on the left, select the dump you want to inspect based on its timestamp.
+. Click *Select Dump*.
+. In the right drop-down box, select the type of dump information you want to view.
+For example, `summary.txt` provides a short summary of why the dump might have occurred. The `thread.txt` option provides information about the state of the Web Server threads at the time of the dump, including any that were deadlocked. The `repository` options provide information about what was in the external and user repositories at the time of the dump. The `configurationAdmin.properties` option provides a snapshot of the complete configuration of Web Server, including the kernel and repositories.
+. Click *Select Entry*.
+The Admin Console displays the information in the Dump Entry Viewer, as shown in the following graphic:
+image:console-dump-details.png[]
+
+Note that the dump entry `osgi.zip` is a binary OSGi state dump which should be viewed as described in
+xref:admin-console-view-osgi-state[Viewing Overview and Details of the OSGi State].
+Dumps may contain other binary entries which are not intended for viewing via the dump inspector.
+For example, `heap.out` contains a dump of the Java heap and `region.digraph`
+contains a dump of the sharing policy between kernel and use region (this is used by the OSGi state dump inspector).
+
+anchor:admin-console-view-osgi-state[]
+
+==== Viewing Overview and Details of the OSGi State
+
+The following procedure describes how you can view the OSGi state of the Web Server, either currently or at the time that a particular service dump
+occurred.
+
+The OSGi state is a list of bundles that are currently installed. When viewing the current state, additional information is available
+such as whether each bundle is Spring powered and a list of services in the OSGi service registry. This additional information is not available
+when viewing a state dump.
+
+. From the main Admin Console page, click the *OSGi State* link at the top.
+By default, the Admin Console displays the complete list of bundles that are currently installed in Web Server.
+For each bundle, the console displays its internal ID, its symbolic name, its version, and its current state (usually either Active or Resolved.)
+
+. To view the bundles that were installed at the time of a service dump, select the service dump based on its timestamp from the drop-down box on the
+right and click *Go*.
+
+. To view details about a particular bundle, click on its bundle ID. A full description of the bundle is displayed, as shown in the following graphic:
+image:console-osgi-state.png[]
+The console displays again the symbolic name, version, and internal ID of the bundle. It then displays whether the bundle is Spring powered and the exact physical location of the bundle JAR file on the computer that hosts Web Server.
+The console then displays the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. The console also displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages. For each package, you can drill down and view details of the corresponding bundle.
+Similarly, the console displays the consumed and provided OSGi services.
+Finally, the console also displays information about the Spring context, if the bundle is Spring powered.
+
+. To view the full list of OSGi services, click the `Services Overview` link from the main OSGi state page
+
+. Typically, the list of bundles and services can be very long, making it difficult to find a particular bundle. Use the *Search* box at the top right corner to narrow down the list of displayed bundles.
+
+Enter a package name with wildcards '\*' representing part of a package name (excluding periods) and
+'*' representing one or more components of a package name separated by periods.
+For example, `\*.virgo.*` displays {virgo-name} packages.
+
diff --git a/user-guide/src/docs/asciidoc/admin-shell.adoc b/user-guide/src/docs/asciidoc/admin-shell.adoc
new file mode 100644
index 0000000..4e0c280
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/admin-shell.adoc
@@ -0,0 +1,994 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:admin-shell[]
+
+== Equinox Console
+
+anchor:admin-shell-enable[Enabling the Equinox Console]
+
+=== Enabling the Equinox Console
+
+Shells are provided for both user region and kernel, although they are disabled by default and need enabling before
+they can be used.
+
+The user region shell ports may be reconfigured by editing the file
+`osgi.console.properties` in the `repository/ext` directory, and
+then restarting Virgo. The telnet properties in the file are prefixed with *telnet.*, and the ssh properties are prefixed with *ssh.*.
+The kernel shell ports may be reconfigured by editing the file `osgi.console.properties` in the `configuration` directory, and then restarting Virgo.
+
+To enable any of these shell ports, change the `enabled` setting from `false` to `true`
+[source,txt]
+----
+enabled=true
+----
+in the corresponding properties files.
+
+If you wish to change a port, any free port can be used, but the usual defaults are, for telnet, 2501 for the user region and 2401 for the kernel, and
+for ssh, 2502 for the user region and 2402 for the kernel.
+
+Access is via ssh or telnet.
+The simplest way to access the shell is via telnet to port 2501 or 2401 for user region or kernel, respectively.
+
+....
+$ telnet localhost 2501
+Trying ::1...
+Connected to localhost.
+Escape character is '^]'.
+
+osgi>
+....
+
+Alternatively, you can ssh to port 2502 or 2402 for user region or kernel, respectively.
+The users and passwords for ssh are configured in `configuration/org.eclipse.virgo.kernel.users.properties` as described
+in xref:configuring-authentication[Configuring Authentication]. The default user and password are `admin`
+and `admin`.
+
+[NOTE]
+--
+Currently the {nano-product-name} Equinox Console is enabled by default. Telnet is accesible on *2401* and SSH on *2402*. In future these will be configurable.
+--
+
+[NOTE]
+--
+If you use the `shutdown` shell command to stop Virgo Server for Apache Tomcat, the shutdown messages appear in the shell terminal instead of in the terminal in which Virgo runs. This is due to the
+mechanisms which the shell implementation uses to redirect standard output.
+--
+
+anchor:admin-shell-using-vsh[]
+
+=== Using Virgo Shell Commands
+
+[NOTE]
+--
+This section is not applicable to {nano-product-name}.
+--
+
+Virgo provides shell commands
+that allow you to examine artifacts
+currently installed in a particular {kernel-product-name} instance, manage the lifecycle of the installed artifacts, install new artifacts, and shut down
+the {kernel-product-name}. You can install, examine, and manage the lifecycle of the following artifacts:
+
+* Bundles
+* Configuration Artifacts
+* PARs
+* Plans
+
+and can examine:
+
+* Exported packages
+* Services in the OSGi service registry
+
+Virgo also provides shell commands to list all bundles that contain, export, or load a particular class.
+
+These commands are provided *for the user region shells only* and are grouped together in
+the `vsh` *scope*.
+
+You invoke commands using the `vsh:` scope. For example:
+
+....
+osgi> vsh:plan list
+
+Name Version State
+org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE
+org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE
+org.eclipse.virgo.web 2.1.0 ACTIVE
+....
+
+anchor:admin-shell-vsh-using-command-list[]
+
+==== Virgo Shell Commands
+
+The following table lists the Virgo shell commands; each command in turn has a variety of options that you can specify, depending on what you want to do, such as start a bundle or refresh a plan. The reference documentation about each command provides the full list of available options.
+
+anchor:admin-shell-vsh-commands-table[]
+
+[options="header",cols="1,4"]
+.Virgo Shell Commands
+|=======================================================================
+| Command | Description
+| xref:admin-shell-vsh-bundle-command[bundle]
+ | Manages and displays information about bundle artifacts.
+| xref:admin-shell-cl-clhas[clhas]
+ | Lists all bundles that <emphasis role="bold">contain* a class or resource.
+| xref:admin-shell-cl-clexport[clexport]
+ | Lists all bundles that <emphasis role="bold">export* a class or package.
+| xref:admin-shell-cl-clload[clload]
+ | Lists all bundles that can <emphasis role="bold">load* a class.
+| xref:admin-shell-vsh-config-command[config]
+ | Manages and displays information about configuration artifacts.
+| xref:admin-shell-vsh-package-command[packages]
+ | Displays information about exported packages.
+| xref:admin-shell-vsh-par-command[par]
+ | Manages and displays information about PAR artifacts.
+| xref:admin-shell-vsh-plan-command[plan]
+ | Manages and displays information about plan artifacts.
+| xref:admin-shell-vsh-service-command[service]
+ | Displays information about services in the OSGi service registry.
+| xref:admin-shell-vsh-install-command[install]
+ | Installs an artifact to {kernel-product-name}.
+| xref:admin-shell-vsh-shutdown-command[shutdown]
+ | Shuts down the {kernel-product-name} instance to which the Equinox Console is connected.
+|=======================================================================
+
+anchor:admin-shell-vsh-command-reference[]
+
+=== Virgo Shell Command Reference
+
+This section contains reference information about the Virgo shell commands
+
+xref:admin-shell-vsh-bundle-command[bundle],
+xref:admin-shell-cl-clhas[clhas],
+xref:admin-shell-cl-clexport[clexport],
+xref:admin-shell-cl-clload[clload],
+xref:admin-shell-vsh-config-command[config],
+xref:admin-shell-vsh-package-command[packages],
+xref:admin-shell-vsh-par-command[par],
+xref:admin-shell-vsh-plan-command[plan],
+xref:admin-shell-vsh-service-command[service],
+xref:admin-shell-vsh-install-command[install],
+xref:admin-shell-vsh-shutdown-command[shutdown],
+xref:admin-shell-vsh-help-command[help] and
+xref:admin-shell-vsh-exit-command[exit].
+
+anchor:admin-shell-vsh-bundle-command[]
+
+==== bundle Command
+
+Use the `bundle` command to manage the lifecycle of bundles deployed in {kernel-product-name} and to gather information about deployed bundles, such as diagnostic information, header information, and so on.
+The following table lists the options you can specify for this command.
+
+anchor:admin-shell-vsh-bundle-command-table[]
+[options="header",cols="1,5"]
+.Options of the bundle Command
+|=======================================================================
+| Option | Description
+| list | Displays the list of bundles that are currently installed in the current {kernel-product-name} instance. With the exception of a few kernel bundles and their services, which {kernel-product-name} uses to administer the user region, none of the kernel is visible to user installed artifacts; rather, only the bundles installed in the user region are visible.
+ Each bundle is identified by an internal `ID` which you can then use with the other `bundle` commands that manage a particular bundle, such as `start `*`id`*. The `list` command also displays the version of the bundle, along with its state, which is one of the following standard OSGi lifecycle states:
+ *Installed*: The bundle is installed but its dependencies have not yet been resolved.
+ *Resolved*: The bundle is resolved and you can now start it.
+ *Uninstalled*: The bundle is uninstalled and you cannot use it.
+ *Starting*: The bundle is in the process of starting.
+ *Active*: The bundle is running and you can now use it.
+ *Stopping*: The bundle is in the process of stopping.
+ Use one of the other `bundle` commands to change the state of a bundle. For example, use the `bundle start `*`id`* command to change the state of a bundle from `Installed` to `Active`.
+| examine *id* | Displays detailed information about the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle.
+ In addition to the information provided by the `bundle list` command (id, full name, version, and state), the `examine` command specifies whether the bundle includes a Spring application context (or is *Spring Powered*) and the exact physical location of the bundle JAR file.
+ The `examine` also provides the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. Finally, the command displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages.
+| start *id* | Starts the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle.
+ After {kernel-product-name} successfully starts the bundle, it is listed in the `Active` state.
+| stop *id* | Stops the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle.
+ When you stop a bundle, it goes from the `Active` state to the `Resolved` state, and you must re-start it if you want to use the application that the bundle contains.
+| refresh *id* | Updates the contents of the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle. Use this command if you have changed the contents of the bundle JAR file and you want to refresh the artifact as installed in the OSGi framework.
+| uninstall *id*| Uninstalls the specified bundle from {kernel-product-name}. Use the `bundle list` command to get the internal id of a particular bundle.
+ When the uninstall process is complete, the bundle does not show up in the list of bundles displayed by the `bundle list` command. If you want to use the application in the bundle, you must re-install it using the `install` command.
+| diag *id* | Provides diagnostic information about the specified bundle.
+ In particular, this command displays information about the imported packages that {kernel-product-name} could not resolve.
+ Use the `bundle list` command to get the internal id of a particular bundle.
+ Note that {virgo-name} does not install unresolvable bundles.
+ Instead is takes a state dump (for offline analysis using the web administration console) and fails the deployment.
+ So bundles are only likely to become unresolvable in {virgo-name} after an update operation.
+| headers *id* | Displays the complete list of manifest headers of the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle.
+ The manifest headers include: `Import-Package`, `Export-Package`, `Bundle-SymbolicName`, and so on.
+|=======================================================================
+
+The following examples show how to use this command.
+
+First, use the `bundle list` command to view all the installed bundles:
+
+....
+osgi> vsh:bundle list
+
+Id Name Version State
+40 org.eclipse.virgo.kernel.userregionfactory 3.0.0.RELEASE ACTIVE
+47 org.eclipse.equinox.cm 1.0.300.v20101204 ACTIVE
+48 org.eclipse.virgo.kernel.userregion 3.0.0.RELEASE ACTIVE
+49 org.eclipse.virgo.kernel.osgicommand 3.0.0.RELEASE ACTIVE
+50 org.eclipse.osgi.services 3.3.0.v20110110 ACTIVE
+51 com.springsource.org.apache.mina.core 2.0.2 ACTIVE
+52 org.apache.felix.gogo.command 0.8.0.v201105062003 ACTIVE
+53 org.apache.felix.gogo.runtime 0.8.0.v201105062003 ACTIVE
+54 org.apache.felix.gogo.shell 0.8.0.v201107131313 ACTIVE
+55 org.eclipse.equinox.console.supportability 1.0.0.20110722-2 ACTIVE
+56 com.springsource.org.apache.sshd.core 0.5.0 ACTIVE
+57 org.springframework.osgi.core 1.2.1 ACTIVE
+58 S org.springframework.osgi.extender 1.2.1 ACTIVE
+59 org.springframework.osgi.io 1.2.1 ACTIVE
+60 org.eclipse.virgo.kernel.agent.dm 3.0.0.RELEASE ACTIVE
+61 S org.eclipse.virgo.kernel.deployer.dm 3.0.0.RELEASE ACTIVE
+62 org.eclipse.equinox.ds 1.3.0.v20110124-0830 ACTIVE
+63 org.eclipse.equinox.util 1.0.200.v20100503 ACTIVE
+64 com.springsource.org.aopalliance 1.0.0 ACTIVE
+65 org.eclipse.virgo.kernel.dmfragment 3.0.0.RELEASE RESOLVED
+66 org.springframework.aop 3.0.5.RELEASE ACTIVE
+67 org.springframework.asm 3.0.5.RELEASE ACTIVE
+68 org.springframework.beans 3.0.5.RELEASE ACTIVE
+69 org.springframework.context 3.0.5.RELEASE ACTIVE
+70 org.springframework.core 3.0.5.RELEASE ACTIVE
+71 org.springframework.expression 3.0.5.RELEASE ACTIVE
+....
+
+The following example shows how to view the headers of the `org.springframework.osgi.extender` bundle (only the first few lines are shown):
+
+....
+osgi> vsh:bundle examine 5
+
+Id: 5
+Name: org.springframework.osgi.extender
+Version 1.2.1
+State: ACTIVE
+Spring Powered: true
+Bundle Location: file:<... omitted ...>/org.springframework.osgi.extender-1.2.1.jar/
+
+Imported Packages:
+ org.springframework.osgi.context [1.2.1, 1.2.1]
+ exported by org.springframework.osgi.core 1.2.1 [4]
+ <... remainder omitted ...>
+
+Exported Packages:
+ org.springframework.osgi.extender 1.2.1
+ <... remainder omitted ...>
+
+Published services:
+ 58 org.springframework.beans.factory.xml.NamespaceHandlerResolver
+ consumed by org.springframework.osgi.extender 1.2.1 [5]
+ consumed by org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE [8]
+ <... remainder omitted ...>
+
+Consumed services:
+ 1 org.osgi.service.packageadmin.PackageAdmin
+ published by org.eclipse.osgi 3.7.0.v20110224 [0]
+ <... remainder omitted ...>
+
+Fragments:
+ org.eclipse.virgo.kernel.dmfragment 2.1.0.RELEASE [10]
+....
+
+anchor:admin-shell-vsh-config-command[]
+
+==== config Command
+
+Use the `config` command to view and manage the configuration artifacts that have been installed in {kernel-product-name}. A *configuration artifact* is simply a properties file that is associated with a user application that is contained in a bundle. Using configuration artifacts, you can manage the configuration of a user application completely separately from the bundle that contains the application.
+The following table lists the options you can specify for this command.
+
+anchor:admin-shell-vsh-config-command-table[]
+[options="header",cols="1,3"]
+.Options of the config Command
+|=======================================================================
+| Option | Description
+| list | Lists the configuration artifacts that are currently installed in {kernel-product-name}.
+ The `list` option displays the full name of each installed configuration artifact, its version, and its current state. Configuration artifacts have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a configuration can be in is the same as those of bundles; see xref:admin-shell-bundle-command[the bundle command] for the list of possible states.
+| examine *name [version]*
+ | Displays information about the specified configuration artifact. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ A configuration artifact must be active for you to examine it; if it is not currently active, use `config start` to start it and thus change its state to `Active`.
+ The command first displays the factory pid of the configuration artifact as well as the complete location of the bundle to which the configuration artifact is associated. The command then lists all the properties that make up the configuration, as well as their current value.
+| start *name [version]*
+ | Starts the specified configuration artifact and makes it visible to {kernel-product-name}.
+ Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the
+ configuration artifact installed (which {virgo-name} does not currently support).
+ Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ Starting the configuration sets its state to `Active`.
+| stop *name [version]*
+ | Stops the specified configuration artifact and makes it invisible to {kernel-product-name}. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which {virgo-name} does not currently support). Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ Stopping the configuration sets its state to `Resolved`.
+| refresh *name [version]*
+ | Updates the contents of the specified configuration artifact to {kernel-product-name}. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which {virgo-name} does not currently support). Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to {kernel-product-name} and the associated bundle.
+| uninstall *name [version]*
+ | Uninstalls the specified configuration artifact and make it completely unavailable to {kernel-product-name}. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which {virgo-name} does not currently support). Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ Stopping the configuration removes it from {kernel-product-name}'s list of deployed artifacts and it will not show up when you perform a `config list`.
+|=======================================================================
+
+The following example shows how to use this command to list the installed configuration artifacts.
+
+....
+osgi> vsh:config list
+
+Name Version State
+org.eclipse.virgo.kernel 0.0.0 ACTIVE
+org.eclipse.virgo.kernel.jmxremote.access 0.0.0 ACTIVE
+org.eclipse.virgo.kernel.userregion 0.0.0 ACTIVE
+org.eclipse.virgo.kernel.users 0.0.0 ACTIVE
+org.eclipse.virgo.medic 0.0.0 ACTIVE
+org.eclipse.virgo.repository 0.0.0 ACTIVE
+osgi.console.ssh 0.0.0 ACTIVE
+osgi.console.telnet 0.0.0 ACTIVE
+....
+
+To view the properties of a configuration artifact, and their current values, use `config examine`:
+
+....
+osgi> vsh:config examine org.eclipse.virgo.repository
+
+Factory pid:
+Bundle Location: file:plugins/org.eclipse.virgo.kernel.services-{version}.jar
+
+Properties:
+ chain:
+ ext,usr
+ ext.searchPattern:
+ repository/ext/{artifact}
+ ext.type:
+ external
+ service.pid:
+ org.eclipse.virgo.repository
+ usr.type:
+ watched
+ usr.watchDirectory:
+ repository/usr
+....
+
+anchor:admin-shell-vsh-package-command[]
+
+==== packages Command
+
+Use the `packages` command to view the complete list of packages exported by all bundles installed in {kernel-product-name}, as well as examine a particular exported package in more detail.
+
+The following table lists the options you can specify for this command.
+
+anchor:admin-shell-vsh-package-command-table[]
+[options="header",cols="1,3"]
+.Options of the packages Command
+|=======================================================================
+| Option | Description
+| list | Displays all the exported packages for all bundles in the uer region of {kernel-product-name}. In addition to the package name, the command displays the version of the exported package and the `id` of the bundle that contains the exported package. You can examine the bundle by using the command `bundle examine` *id*.
+| examine *name version*
+ | Displays details about the exported package. You must specify both the name of the exported package and its version; use `packages list` to view the exact names and version.
+|=======================================================================
+
+The `examine` command provides the following additional information about the exported package:
+
+* The name and version of the bundle that exports the package. This means that the package name is explicitly listed in the bundle's `MANIFEST.MF` file as part of the `Export-Package` header.
+* Any attributes that are part of the `Export-Package`, in addition to `version`.
+* The directives that are part of the `Export-Package` header. A typical directive is `uses`, which declares up-front constraints on a number of other packages.
+* The list of all bundles that import the package.
+
+The following example shows how to list all the exported packages for all bundles installed:
+....
+osgi> vsh:packages list
+
+Name Version Providing Bundle
+javax.accessibility 0.0.0 0
+javax.activation 0.0.0 0
+javax.activation 1.1.1 0
+<... remainder omitted ...>
+....
+
+The following example shows how to examine a particular exported package:
+
+....
+osgi> vsh:packages examine org.slf4j 1.6.1
+
+Exporter: org.eclipse.virgo.region.user 0.0.0 [1]
+
+Attributes:
+ None
+
+Directives:
+ uses:
+ org.slf4j.spi
+ x-equinox-ee:
+ -1
+ x-internal:
+ false
+
+Importer(s):
+ org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE [7]
+ Import-Package attributes:
+ bundle-version:
+ 0.0.0
+ version:
+ [1.6.1,2.0.0)
+ Import-Package directives:
+ resolution:
+ static
+ <... remainder omitted ...>
+....
+
+anchor:admin-shell-vsh-par-command[]
+
+==== par Command
+
+Use the `par` command to view all the PARs currently installed in {kernel-product-name}, view details about a particular PAR and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.
+The following table lists the options you can specify for this command.
+
+anchor:admin-shell-vsh-par-command-table[]
+[options="header",cols="1,3"]
+.Options of the par Command
+|=======================================================================
+| Option | Description
+| list | Displays all the PARs that are currently installed in {kernel-product-name}.
+ The `list` option displays the full name of each installed PAR, its version, and its current state. PARs have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a PAR can be in is the same as those of bundles; see xref:admin-shell-bundle-command[the bundle command] for the list of possible states.
+| examine *name version*
+ | Displays information about the specified PAR; you are required to identify the PAR with both its name and its version. Use the `par list` command to view all installed PAR files and their versions. The command displays the following information:
+ The current state of the PAR (see xref:admin-shell-vsh-bundle-command[the bundle command] for the full list of possible states).
+ Whether the PAR is *scoped*. Scoping specifies whether {kernel-product-name} should deploy the members of the PAR in their own scope; when scoping is disabled, {kernel-product-name} deploys the artifacts into the global scope and they are accessible for access by all other artifacts.
+ Whether the PAR is *atomic*. When a PAR is atomic, {kernel-product-name} manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then {kernel-product-name} starts *all* the PAR artifacts. If one artifact fails to start, then {kernel-product-name} stops all other artifacts in the PAR.
+ The individual members, or children, of the PAR. These could be plans, bundles, configuration artifacts, and so on.
+| start *name version*
+ | Starts the specified PAR. You must specify both the full name of the PAR as well as the version you want to start. Use the `par list` command to get the list of PARs currently installed in {kernel-product-name}.
+ To start a PAR, it must have already been resolved by {kernel-product-name}, or in other words, be in the `Resolved` state. After {kernel-product-name} successfully starts the PAR, it is listed in the `Active` state.
+| stop *name version*
+ | Stops the specified PAR. You must specify both the full name of the PAR as well as the version you want to stop. Use the `par list` command to get the list of PARs currently installed in {kernel-product-name}.
+ When you stop a PAR, it goes from the `Active` state to the `Resolved` state, and you must re-start it if you want to use the application that the PAR contains.
+| refresh *name version*
+ | Updates the contents of the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the `par list` command to this information.
+ Use this command if you have changed the contents of the PAR file and you want to refresh the artifact as installed in the OSGi framework.
+| uninstall *name version*
+ | Uninstalls the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the `par list` command to this information.
+ When the uninstall process is complete, the PAR will not show up in the list of PARs displayed by the `par list` command. If you want to use the application in the PAR, you must re-install it using the `install` command.
+|=======================================================================
+
+The following example shows how to list the PARs that have been installed in {kernel-product-name}:
+
+....
+osgi> vsh:par list
+
+Name Version State
+
+org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE ACTIVE
+....
+
+The following example shows how to examine a particular PAR file:
+
+....
+osgi> vsh:par examine org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE
+
+State: ACTIVE
+Scoped: true
+Atomic: true
+
+Children:
+ bundle org.eclipse.virgo.server.repository.hosted.core 2.1.0.RELEASE
+ bundle org.eclipse.virgo.server.repository.hosted.web 2.1.0.RELEASE
+ bundle org.eclipse.virgo.server.repository.hosted-synthetic.context 2.1.0.RELEASE
+....
+
+Finally, the following example shows how to refresh an installed PAR file:
+
+....
+osgi> vsh:par refresh my.exciting.par 1.2.0
+
+par my.exciting.par 1.2.0 refreshed successfully
+....
+
+anchor:admin-shell-vsh-plan-command[]
+
+==== plan Command
+
+Use the `plan` command to view all the plans currently installed in {kernel-product-name}, view details about a particular plan and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.
+The following table lists the options you can specify for this command.
+
+anchor:admin-shell-vsh-plan-command-table[]
+[options="header",cols="1,3"]
+.Options of the plan Command
+|=======================================================================
+| Option | Description
+| list | Displays all the plans that are currently installed in {kernel-product-name}.
+ The `list` option displays the full name of each installed plan, its version, and its current state. Plans have similar lifecycles to other artifacts, such as bundles, and so the list of states in which a plan can be in is the same as those of bundles; see xref:admin-shell-bundle-command[the bundle command] for the list of possible states.
+| examine *name version*
+ | Displays information about the specified plan; you are required to identify the plan with both its name and its version. Use the `plan list` command to view all installed plans and their versions. The command displays the following information:
+ The current state of the plan (see xref:admin-shell-vsh-bundle-command[the bundle command] for the full list of possible states).
+ Whether the plan is *scoped*. Scoping specifies whether {kernel-product-name} should deploy the members of the plan in their own scope; when scoping is disabled, {kernel-product-name} deploys the artifacts into the global scope and they are accessible for access by all other artifacts.
+ Whether the plan is *atomic*. When a plan is atomic, {kernel-product-name} manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then {kernel-product-name} starts *all* the plan artifacts. If one artifact fails to start, then {kernel-product-name} stops all other artifacts in the plan.
+ The individual members, or children, of the plan. These could be other plans, PARs, bundles, configuration artifacts, and so on.
+| start *name version*
+ | Starts the specified plan. You must specify both the full name of the plan as well as the version you want to start. Use the `plan list` command to get the list of plans currently installed in {kernel-product-name}.
+ To start a plan, it must have already been resolved by {kernel-product-name}, or in other words, be in the `Resolved` state. After {kernel-product-name} successfully starts the plan, it is listed in the `Active` state.
+| stop *name version*
+ | Stops the specified plan. You must specify both the full name of the plan as well as the version you want to stop. Use the `plan list` command to get the list of plans currently installed in {kernel-product-name}.
+ When you stop a plan, it goes from the `Active` state to the `Resolved` state, and you must re-start it if you want to use the application that the plan contains.
+| refresh *name version*
+ | Updates the contents of the specified plan. You must specify both the name and version of the plan you want to refresh. Use the `plan list` command to this information.
+ Use this command if you have changed the contents of the plan file and you want to refresh the artifact as installed in the OSGi framework.
+| uninstall *name version*
+ | Uninstalls the specified plan. You must specify both the name and version of the plan you want to refresh. Use the `plan list` command to this information.
+ When the uninstall process is complete, the plan will not show up in the list of plans displayed by the `plan list` command. If you want to use the application in the plan, you must re-install it using the `install` command.
+|=======================================================================
+
+The following example shows how to list the plans that have been installed in {kernel-product-name}:
+
+....
+osgi> vsh:plan list
+
+Name Version State
+org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE
+org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE
+org.eclipse.virgo.web 2.1.0 ACTIVE
+....
+
+The following example shows how to examine a particular plan:
+
+....
+osgi> vsh:plan examine org.eclipse.virgo.kernel.userregion.springdm 2.1.0
+
+State: ACTIVE
+Scoped: false
+Atomic: false
+
+Children:
+ bundle org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE
+ bundle org.springframework.osgi.io 1.2.1
+ bundle org.springframework.osgi.extender 1.2.1
+ bundle org.springframework.osgi.core 1.2.1
+ bundle org.eclipse.virgo.kernel.deployer.dm 2.1.0.RELEASE
+....
+
+The following example shows how to stop a currently Active plan:
+
+....
+osgi> vsh:plan stop org.eclipse.virgo.web 2.1.0
+
+plan org.eclipse.virgo.web:2.1.0 stopped successfully
+....
+
+The following example shows how to start a plan:
+
+....
+osgi> vsh:plan start org.eclipse.virgo.web 2.1.0
+
+plan org.eclipse.virgo.web:2.1.0 started successfully
+....
+
+anchor:admin-shell-vsh-service-command[]
+
+==== service Command
+
+Use the `service` command to view all the services that have been registered in the OSGi service registry of {kernel-product-name}. You can also examine a specific service to discover its properties, the bundle that publishes the service, and any bundles that consume the service.
+The following table lists the options you can specify for this command.
+
+anchor:admin-shell-vsh-service-command-table[]
+[options="header",cols="1,3"]
+.Options of the service Command
+|=======================================================================
+| Option | Description
+| list | Displays the list of services that are currently registered in the OSGi service registry of {kernel-product-name}.
+ Each service is identified by an internal `ID` which you can then use with the `service examine` command to view the details about a particular service. The `list` option also displays the object class that implements the service and the internal `id` of the bundle that provides the service.
+| examine *id* | Displays detailed information about the specified service. Use the `service list` command to get the internal id of a particular service.
+ This command displays the properties of the service, such as the object class that implements the service, the name of the bundle that publishes the service and any bundles that consume the service.
+|=======================================================================
+
+The following example shows how to list the services currently registered in the OSGi service registry:
+
+....
+osgi> vsh:service list
+
+Id Object Class(es) Providing Bundle
+
+1 org.osgi.service.packageadmin.PackageAdmin 0
+2 org.osgi.service.permissionadmin.PermissionAdmin, ... 0
+3 org.osgi.service.startlevel.StartLevel 0
+4 org.eclipse.osgi.service.debug.DebugOptions 0
+5 java.lang.ClassLoader 0
+6 org.eclipse.osgi.framework.log.FrameworkLog 0
+7 org.eclipse.osgi.framework.log.FrameworkLog 0
+<... remainder omitted ...>
+
+72 org.eclipse.gemini.web.core.spi.ServletContainer 38
+73 org.eclipse.gemini.web.core.WebContainer 37
+74 org.eclipse.virgo.web.core.WebApplicationRegistry 39
+<... remainder omitted ...>
+....
+
+The following example shows how to examine a particular service:
+
+....
+osgi> vsh:service examine 73
+
+ Properties:
+ objectClass:
+ org.eclipse.gemini.web.core.WebContainer
+ service.id:
+ 73
+
+ Publisher: org.eclipse.gemini.web.core 1.1.0.RELEASE [37]
+
+ Consumer(s):
+ org.eclipse.virgo.web.core 2.1.0.RELEASE [39]
+....
+
+anchor:admin-shell-vsh-install-command[]
+
+==== install Command
+
+Use the `install` command to deploy an artifact to {kernel-product-name}. The artifact can be a bundle, PAR, plan, or configuration artifact.
+
+The `install` command takes a single parameter: the URI of the artifact you want to deploy. For example, to deploy a bundle on the local computer, use the `file` scheme:
+
+....
+file://full-pathname-to-artifact
+....
+
+After you execute the `install` command, {kernel-product-name} attempts to resolve the artifact's dependencies, and if it is successful, puts it in the `Resolved` state. At that point, you must start the artifact to be able to actually use it.
+
+The following example shows how to install a bundle called `swf-booking-mvc.war` located in the `/home/apps` directory of the computer on which the Equinox Console Extension is being run:
+
+....
+osgi> vsh:install file://home/apps/swf-booking-mvc.war
+...
+Artifact bundle swf-booking-mvc.war 0.0.0 installed
+....
+
+This command is particularly useful for installing an artifact from the {virgo-name} repository, in which case use the `repository:` scheme:
+
+....
+repository:artifact-type/bundle-symbolic-name/bundle-version
+....
+
+For example:
+
+....
+osgi> vsh:install repository:bundle/my.bundle/1.0
+...
+Artifact bundle my.bundle 1.0.0 installed
+....
+
+The following example shows how to use the `bundle list` command to ensure that the bundle was indeed installed in {kernel-product-name}; if you had installed a different kind of artifact, for example a plan, then you would use the appropriate command (such as `plan list`):
+
+....
+osgi> vsh:bundle list
+
+Id Name Version State
+
+0 org.eclipse.osgi 3.6.1.R36x_v20100806 ACTIVE
+1 org.eclipse.virgo.region.user 0.0.0 ACTIVE
+<... remainder omitted ...>
+
+59 org.eclipse.virgo.server.splash 2.1.0.RELEASE ACTIVE
+60 swf-booking-mvc.war 0.0.0 RESOLVED
+....
+
+Note that the `swf-booking-mvc.war` file is in the `Resolved` state. The following examples start the bundle, and then examine it to ensure that it is in the `Active` state:
+
+....
+osgi> vsh:bundle start 60
+
+bundle swf-booking-mvc.war:0.0.0 started successfully
+
+
+osgi> vsh:bundle examine 60
+
+Id: 60
+Name: swf-booking-mvc.war
+Version 0.0.0
+State: ACTIVE
+Spring Powered: true
+Bundle Location: file:<... omitted ...>/swf-booking-mvc.war/
+
+Imported Packages:
+ javax.crypto.interfaces [0.0.0, 0.0.0]
+ exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
+ org.omg.CosNaming.NamingContextPackage [0.0.0, 0.0.0]
+ exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
+ org.omg.DynamicAny.DynAnyFactoryPackage [0.0.0, 0.0.0]
+ exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0]
+ <... remainder omitted ...>
+
+osgi>
+....
+
+anchor:admin-shell-vsh-shutdown-command[]
+
+==== shutdown Command
+
+Use the `shutdown` command to shut down the {kernel-product-name} instance to which you are connected. When {kernel-product-name} is shut down, the shell returns you to the operating system prompt.
+The `shutdown` command does not have any options.
+
+The following example shows how to use this command.
+
+....
+osgi> vsh:shutdown
+osgi> ...
+Connection closed by foreign host.
+$
+....
+
+anchor:admin-shell-cl-clhas[]
+
+==== clhas command
+
+Use the `clhas` command to list the entries contained in the bundles deployed in {virgo-name} and to solve class loading issues.
+The command accepts as a parameter a search pattern in the form *path/resource*. The resource part of the pattern can contain wildcards.
+The output contains all bundles that have resources or classes matching the pattern. Since wildcards are allowed, the matching entities are listed as well.
+
+The following examples show how to use this command.
+Use the `clhas` to view all bundles that contain `Servlet` class:
+
+....
+osgi>clhas /javax/servlet/Servlet.class
+
+Bundles containing [/javax/servlet/Servlet.class]:
+ 76 javax.servlet
+ /javax/servlet/Servlet.class
+....
+
+Use the wildcard `*` with `clhas` to view all classes starting with `Servlet`:
+
+....
+osgi> clhas /javax/servlet/Servlet*
+
+Bundles containing [/javax/servlet/Servlet*]:
+ 76 javax.servlet
+ /javax/servlet/ServletRequestAttributeEvent.class
+ /javax/servlet/ServletRequest.class
+ <... remainder omitted ...>
+ /javax/servlet/Servlet.class
+ <... remainder omitted ...>
+....
+
+The `clhas` command can also be used with class name instead of resource path:
+
+....
+osgi> clhas javax.servlet.Servlet
+
+Bundles containing [javax/servlet/Servlet.class]:
+ 76 javax.servlet
+ /javax/servlet/Servlet.class
+....
+
+Please note that the command converts the class name to a path and appends `class` extension by default.
+To search for a resource with an extension different than `class` you should use the resource path form:
+
+....
+osgi> clhas /LocalStrings.properties
+
+Bundles containing [/LocalStrings.properties]:
+ 96 com.springsource.org.apache.catalina
+ /org/apache/catalina/core/LocalStrings.properties
+ /org/apache/tomcat/util/http/mapper/LocalStrings.properties
+ /org/apache/catalina/loader/LocalStrings.properties
+ <... remainder omitted ...>
+....
+
+The following example shows how to identify a possible `ClassCastException` due to wrong packaging:
+
+....
+osgi>clhas /javax/servlet/Servlet.class
+
+Bundles containing [/javax/servlet/Servlet.class]:
+ 76 javax.servlet
+ /javax/servlet/Servlet.class
+ 107 myapp
+ /WEB-INF/classes/javax/servlet/Servlet.class
+....
+
+It's obvious that the `javax.servlet` package should not be present in `myapp` application and its packaging has to be changed. This problem can often be seen in WAR or web bundles that package Servlet/JSP classes by accident.
+
+anchor:admin-shell-cl-clexport[]
+
+==== clexport command
+
+Use the `clexport` command to list the bundles that export a class or package.
+The command accepts as a parameter the fully qualified class name (in the form *package.class*).
+The command checks to see if the provided class is actually contained in a bundle. If the class is not found in a bundle but its package is exported, then a hint `[class not found, package only]` is displayed.
+
+The following examples show how to use this command.
+Use the `clexport` to view all bundles that contain `Servlet` class:
+
+....
+osgi> clexport javax.servlet.Servlet
+
+Bundles exporting [javax.servlet.Servlet]:
+ 14 com.springsource.javax.servlet
+....
+
+If a bundle exports a package but does not contain the requested class, the output of the command will be similar to this:
+
+....
+osgi> clexport javax.servlet.ServletX
+
+Bundles exporting [javax.servlet.ServletX]:
+ 14 com.springsource.javax.servlet [class not found, package only]
+....
+
+anchor:admin-shell-cl-clload[]
+
+==== clload command
+
+Use the `clload` command to list the bundles that can load a class or to check if a specific bundle can load a class.
+The command accepts as parameters either:
+
+* the fully qualified class name (in the form *package.class*)
+* the fully qualified class name (in the form *package.class*) and the symbolic name or id of the bundle that is to be tested
+
+The command lists not only the bundle that successfully loaded the class, but also the one that actually provides the class. This is visualized with hints like `[exported by 14 com.springsource.javax.servlet]`.
+
+The following examples show how to use this command.
+You can use the `clload` to view all bundles that can load `Servlet` class:
+
+....
+osgi> clload javax.servlet.Servlet
+
+Successfully loaded [javax.servlet.Servlet] from:
+ 56 com.springsource.org.apache.taglibs.standard
+ [exported by 14 com.springsource.javax.servlet]
+ 54 org.eclipse.virgo.apps.admin.web
+ [exported by 14 com.springsource.javax.servlet]
+ 19 com.springsource.org.apache.commons.fileupload
+ [exported by 14 com.springsource.javax.servlet]
+ <... remainder omitted ...>
+....
+
+If a bundle is to be tested, then its id can be used as a command parameter:
+
+....
+osgi> clload javax.servlet.Servlet 19
+
+Successfully loaded [javax.servlet.Servlet] using class loader from:
+ 19 com.springsource.org.apache.commons.fileupload
+ [exported by 14 com.springsource.javax.servlet]
+....
+
+Or the same class load test can specify the symbolic name of the bundle:
+
+....
+osgi> clload javax.servlet.Servlet com.springsource.org.apache.commons.fileupload
+
+Successfully loaded [javax.servlet.Servlet] using class loader from:
+ 19 com.springsource.org.apache.commons.fileupload
+ [exported by 14 com.springsource.javax.servlet]
+....
+
+anchor:p2-commands[]
+
+=== Using the p2 for extending your {virgo-name} installation
+
+==== Extending with the p2 director
+
+You can provision new features on top of your {virgo-name} installation using the p2 director. It can be used both for initial provisioning and extending an existing installtion.
+
+For extending an existing installation you can use these director arguments:
+
+....
+-repository http://download.eclipse.org/rt/ecf/3.5.3/site.p2
+-installIU org.eclipse.ecf.remoteservice.feature.feature.group
+-destination <your {virgo-name} installation folder>
+....
+
+This installs the *latest* version of the specified p2 feature in your {virgo-name} installation's p2 profile.
+
+==== Extending via the p2 shell commands
+
+Another way to achieve the same results is to use the p2 commands. The commands are available only in {nano-product-name-short} as it includes p2 by default.
+
+[NOTE]
+--
+For the other distributions only the director is supported and the operation only extends their kernel region.
+--
+
+Here's a list of the most commonly used p2 commands:
+
+anchor:p2-common-commands-table[]
+[options="header",cols="1,3"]
+.p2 Common Shell Commands
+|=======================================================================
+| Command | Help
+| `provaddrepo <repository URI>` | Add specified URI as metadata and artifact repository. Note that if you pass a wrong URL you'll get an error saying:
+ `Repository not modifiable: http://wrongURL`. The default behavior of this command is to create an empty repository at the
+ specified location if there isn't any. That won't work for remote locations so keep in mind that if you see this you probably passed a wrong URL.
+| `provdelrepo <repository URI>` | Remove specified metadata and artifact repository.
+| `provinstall <InstallableUnit> <version> <profileid>`
+ | Install an IU to the profileid. If no profileid is given, installs into default profile.
+| `provremove <InstallableUnit> <version> <profileid>`
+ |Uninstall an IU from the profileid. If no profileid is given, uninstalls form default profile.
+| `provlg [<repository URI \| *> <iu id \| *> <version range \| *>]`
+ | Lists all IUs with group capabilities in the given repo or in all repos if URI is omitted.
+| `provliu [<repository URI \| *> <iu id \| *> <version range \| *>]`
+ | Lists the IUs that match the pattern in the given repo. * matches all.
+| `confapply` | This is a Simple Configurator command, not a p2 one. However it is relevant because it applies dynamically, at runtime, the installed p2 features.
+ What the command does is to apply to the running OSGi framework the current content in the bundles.info file. When using the provinstall command it takes care of updating the bundles.info file.
+|=======================================================================
+
+Here's an example showing how to install the ECF remote services but with the p2 commands this time:
+
+....
+osgi> provaddrepo http://download.eclipse.org/rt/ecf/3.5.3/site.p2
+
+osgi> provlg
+
+org.eclipse.ecf.core.feature.group 3.5.3.v20111109-2142
+org.eclipse.ecf.core.featurepatch.feature.group 3.5.3.v20111109-2142
+org.eclipse.ecf.core.featurepatch.source.feature.group 3.5.3.v20111109-2142
+org.eclipse.ecf.core.source.feature.group 3.5.3.v20111109-2142
+org.eclipse.ecf.datashare.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.datashare.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.dnssd.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.dnssd.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.jmdns.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.jmdns.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.slp.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.slp.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.zookeeper.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.discovery.zookeeper.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.eventadmin.examples.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.eventadmin.examples.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.eventadmin.feature.feature.group 2.0.0.v20111109-2142
+org.eclipse.ecf.eventadmin.source.feature.feature.group 2.0.0.v20111109-2142
+org.eclipse.ecf.osgi.services.feature.feature.group 2.0.1.v20111109-2142
+org.eclipse.ecf.osgi.services.source.feature.feature.group 2.0.1.v20111109-2142
+org.eclipse.ecf.remoteservice.examples.feature.feature.group 1.1.0.v20111109-2142
+org.eclipse.ecf.remoteservice.examples.source.feature.feature.group 1.1.0.v20111109-2142
+org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.rest.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.rest.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.rosgi.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.rosgi.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.sdk.feature.feature.group 3.5.3.v20111109-2142
+org.eclipse.ecf.remoteservice.sdk.source.feature.feature.group 3.5.3.v20111109-2142
+org.eclipse.ecf.remoteservice.soap.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.soap.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.remoteservice.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.server.generic.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.server.generic.source.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.xmpp.feature.feature.group 1.0.0.v20111109-2142
+org.eclipse.ecf.xmpp.source.feature.feature.group 1.0.0.v20111109-2142
+
+osgi> provinstall org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
+Installation complete for org.eclipse.ecf.remoteservice.feature.feature.group 1.0.0.v20111109-2142
+
+osgi> confapply
+
+osgi> ss
+
+"Framework is launched."
+
+
+id State Bundle
+0 ACTIVE org.eclipse.osgi_3.7.1.R37x_v20110808-1106
+...
+92 RESOLVED org.springframework.osgi.io_1.2.1
+93 RESOLVED org.eclipse.ecf.console_1.0.0.v20111109-2142
+94 RESOLVED org.eclipse.ecf.discovery_4.0.0.v20111109-2142
+95 RESOLVED org.eclipse.ecf.provider_4.2.100.v20111109-2142
+96 RESOLVED org.eclipse.ecf.provider.discovery_2.1.200.v20111109-2142
+97 RESOLVED org.eclipse.ecf.provider.remoteservice_4.0.0.v20111109-2142
+98 RESOLVED org.eclipse.ecf.remoteservice_6.0.200.v20111109-2142
+99 RESOLVED org.eclipse.ecf.sharedobject_2.2.100.v20111109-2142
+100 RESOLVED org.eclipse.equinox.concurrent_1.0.200.v20110502
+....
+
+You can see that after applying the changes with *confapply* the remote services bundles and their dependencies are installed in {nano-product-name-short}.
+
diff --git a/user-guide/src/docs/asciidoc/applications.adoc b/user-guide/src/docs/asciidoc/applications.adoc
new file mode 100644
index 0000000..e8727e3
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/applications.adoc
@@ -0,0 +1,275 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:deployment[]
+
+== Working with Applications
+
+anchor:deployment-deploying[]
+
+=== Deploying Artifacts
+
+In the context of {tomcat-product-name}, *deploying* refers to installing an artifact to the server and then starting it to make it available to users. Typically, when you install an artifact, {tomcat-product-name-short} automatically starts it as long as the server is able to successfully resolve all its dependencies. For this reason, the terms *deploying* and *installing* are often used interchangeably.
+
+You deploy artifacts to {tomcat-product-name} using either the hot-deploy directory on the file system or by using the Admin Console. The artifacts that you can deploy to {tomcat-product-name-short} are:
+
+* Bundles, including Web Application Bundles
+* WARs
+* PARs
+* Plans
+* Configuration Files
+
+anchor:deployment-deploying-nested-contexts[]
+
+==== Deploying WARs with nested Web-ContextPaths
+
+[NOTE]
+--
+This section currently is ONLY relevant for {nano-product-name}.
+--
+
+Virgo Nano Web supports deployment of WAR files which are transformed into Web Application Bundles. This process involves automatic creation of an OSGi manifest with all relevant OSGi header plus the very important Web-ContextPath header. Its value defines how the deployed WAR file can be requested. There is a limitation about this process that the automatic generation only creates a flat context path which equals the name of your WAR file. Virgo Nano Web supports generation of a nested one.
+
+In order to benefit from this flexibility all you need to do is just to add hashes '#' to your WAR file name in the places where you want to have slashes in your web context path. Here is an example:
+
+....
+myWarFile.war would result into "/myWarFile" web context path
+....
+
+....
+my#War#File.war would result into "/my/War/File" web context path
+....
+
+The symbolic name of the resulting WAB file is the same as the WAR file name but the hashes '#' are replaced with dots '.'.
+
+anchor:initial-deployment-deploying-bulk[]
+
+==== Initial Bulk Hot Deploy
+
+[NOTE]
+--
+This section currently is ONLY relevant for {nano-product-name}.
+--
+
+To hot deploy an artifact initially in bulk mode, copy it into the pickup directory (by default `$SERVER_HOME/pickup`) and start up the server. Upon this startup all the artifacts in the `pickup` directory will get first installed and resolved and only then they will be started.
+
+This solves the problem where artifacts depend on each other and when not in bulk mode the install order is not guaranteed therefore errors could occur.
+
+This is only available as part of the initial scan of the `pickup` directory. Subsequently it goes back to the known mode of single file handled at a time.
+
+....
+$ cd /home/applications
+$ cp BundleA.jar $SERVER_HOME/pickup
+$ cp BundleWithDependencyOnA.jar $SERVER_HOME/pickup
+$ cd $SERVER_HOME/bin
+$ ./startup.sh
+....
+
+When the server is started, artifacts are hot deployed and messages similar to the following appear in the log file:
+
+....
+[2009-12-10 06:41:01.021] fs-watcher <HD0001I> Hot deployer processing 'INITIAL' event for file 'BundleA.jar; BundleWithDependencyOnA.jar; '.
+[2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'BundleA' version '0.0.0'.
+[2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'BundleA' version '0.0.0'.
+[2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'BundleWithDependencyOnA' version '0.0.0'.
+[2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'BundleWithDependencyOnA' version '0.0.0'.
+[2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'BundleA' version '0.0.0'.
+[2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'BundleA' version '0.0.0'.
+[2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'BundleWithDependencyOnA' version '0.0.0'.
+[2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'BundleWithDependencyOnA' version '0.0.0'.
+....
+
+If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
+
+If there are no problems, {nano-product-name} automatically starts the artifacts so that they are immediately available to users.
+
+Bulk deployment can be disabled and reverted back to the old one-file-at-a-time processing by removing this line from `$SERVER_HOME/configuration/config.ini`:
+
+[source,txt]
+----
+org.eclipse.virgo.fschecker.initialEventMode=bulk
+----
+
+anchor:deployment-deploying-hot[]
+
+==== Hot Deploy
+
+To hot deploy an artifact, copy it into the pickup directory (by default `$SERVER_HOME/pickup`):
+
+....
+$ cd /home/applications
+$ cp helloWorld.war $SERVER_HOME/pickup
+....
+
+When the artifact is hot deployed, messages similar to the following appear in the log file:
+
+....
+[2009-12-10 06:41:01.021] fs-watcher <HD0001I> Hot deployer processing 'CREATED' event for file 'helloWorld.war'.
+[2009-12-10 06:41:01.087] fs-watcher <DE0000I> Installing bundle 'helloWorld' version '0.0.0'.
+[2009-12-10 06:41:01.274] fs-watcher <DE0001I> Installed bundle 'helloWorld' version '0.0.0'.
+[2009-12-10 06:41:01.397] fs-watcher <DE0004I> Starting bundle 'helloWorld' version '0.0.0'.
+[2009-12-10 06:41:01.414] Thread-3 <WE0000I> Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2009-12-10 06:41:01.537] Thread-3 <WE0001I> Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2009-12-10 06:41:01.550] start-signalling-1 <DE0005I> Started bundle 'helloWorld' version '0.0.0'.
+....
+
+If there is a problem with the deployment, such as the server being unable to resolve all dependencies, the console and log both show an error message to help you with troubleshooting.
+
+If there are no problems, {tomcat-product-name-short} automatically starts the artifact so that it is immediately available to users.
+
+anchor:deployment-redeploy-hot[]
+
+==== Hot Redeploy
+
+To hot redeploy an artifact which is already hot deployed, copy the updated artifact into the pickup directory (by default `$SERVER_HOME/pickup`),
+just as for hot deploy. When the artifact is redeployed, messages similar to the following appear in the log file:
+
+....
+[2013-01-09 14:08:12.422] fs-watcher <HD0001I> Hot deployer processing 'MODIFIED' event for file 'helloWorld.war'.
+[2013-01-09 14:08:12.422] fs-watcher <DE0007I> Refreshing bundle 'helloWorld' version '0.0.0'.
+[2013-01-09 14:08:12.469] fs-watcher <WE0002I> Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2013-01-09 14:08:13.094] fs-watcher <WE0003I> Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2013-01-09 14:08:13.094] fs-watcher <DE0010I> Stopping bundle 'helloWorld' version '0.0.0'.
+[2013-01-09 14:08:13.110] fs-watcher <DE0011I> Stopped bundle 'helloWorld' version '0.0.0'.
+[2013-01-09 14:08:13.250] fs-watcher <DE0004I> Starting bundle 'helloWorld' version '0.0.0'.
+[2013-01-09 14:08:13.250] start-signalling-2 <WE0000I> Starting web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2013-01-09 14:08:13.860] start-signalling-2 <WE0001I> Started web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2013-01-09 14:08:13.860] start-signalling-2 <DE0005I> Started bundle 'helloWorld' version '0.0.0'.
+[2013-01-09 14:08:13.860] fs-watcher <DE0008I> Refreshed bundle 'helloWorld' version '0.0.0'.
+....
+
+[NOTE]
+--
+The following paragraph is ONLY relevant for {nano-product-name}.
+--
+
+The redeploy waits for any previous operations on the artifact being redeployed to finish. The wait timeout could be configured through the following property in `$SERVER_HOME/configuration/config.ini`:
+
+....
+org.eclipse.virgo.update.timeout
+....
+
+anchor:deployment-deploying-manual[]
+
+==== Deploying Using the Admin Console
+
+The Admin Console allows you to upload a file, which will be deployed automatically, from your local file system to the {tomcat-product-name}. As soon as {tomcat-product-name} deploys the artifact, it appears in the list of artifacts in the Admin Console. Note that the GUI for uploading varies according to the browser and operating system you use.
+
+See xref:admin-console-install-artifacts[Installing a New Artifact] for details about using the Admin Console to install (deploy) an artifact. See xref:admin-console[The Web Admin Console] for general information about the Admin Console.
+
+anchor:deployment-deploying-happens[]
+
+==== What Happens When You Deploy
+
+When you deploy an artifact, either using hot-deployment or the Admin Console, Web Server copies the file to its work directory (`SERVER_HOME/work`) and registers it in its internal registry.
+The server then checks any dependencies the artifact might have to see if
+deployment can go ahead, and if all dependencies are resolved, {tomcat-product-name} starts the artifact.
+Because of all these additional internal activities, you should NOT simply copy the artifact into the `work` directory and assume it will be deployed, because {tomcat-product-name} will not do so.
+
+anchor:deployment-deploying-ordering[]
+
+==== Deployment Ordering
+
+When deploying bundles that have dependencies, it is important
+that you deploy them in the correct order. {tomcat-product-name}
+honors this ordering when it redeploys the artifacts on startup.
+
+If you use hot deployment to deploy your artifacts, be sure to copy the corresponding files into the pickup
+directory one-by-one. Copying the files in one group, for example by using a single `cp` command, provides no guarantee of ordering.
+
+anchor:deployment-deploying-shared[]
+
+==== Deploying Shared Artifacts
+
+Artifacts may be shared by plans.
+Sharing occurs when a plan is deployed which references an artifact that was previously deployed or is a child artifact
+of a plan that was previously deployed.
+Sharing also occurs when an artifact is deployed which is already a child of a deployed plan, but in this case the shared
+artifact may *not* appear as a top-level artifact, for example, in the Admin Console, in the shell,
+and in JMX.
+
+Sharing is taken into account when artifacts are stopped.
+A shared artifact is stopped only when all the artifacts referencing the shared artifact have been stopped
+and, if the shared artifact was deployed in its own right, the artifact itself has been stopped.
+
+anchor:deployment-deploying-restrictions[]
+
+==== Restrictions
+
+{tomcat-product-name} does not support deploying fragment bundles. Typically, fragment bundles should be placed in `$SERVER_HOME/repository/ext`
+or `$SERVER_HOME/repository/usr` so that they will be installed automatically with their host bundles.
+
+anchor:deployment-undeploy[]
+
+=== Undeploying Artifacts
+
+You undeploy artifacts from {tomcat-product-name} by using either the hot-deploy directory on the file system, or the Admin Console.
+
+[NOTE]
+--
+As with deploying, in this guide the terms *undeploying* and *uninstalling* are used interchangeably.
+--
+
+anchor:deployment-undeploy-hot[]
+
+==== Hot Undeploy
+
+To hot-undeploy an artifact, remove the corresponding file from the pickup directory (by default `$SERVER_HOME/pickup`):
+
+....
+$ cd $SERVER_HOME/pickup
+$ rm helloWorld.war
+....
+
+When {tomcat-product-name} completes the undeployment of the artifact, messages similar to the following appear in the log:
+
+....
+[2009-12-10 06:46:33.254] fs-watcher <HD0001I> Hot deployer processing 'DELETED' event for file 'helloWorld.war'.
+[2009-12-10 06:46:33.259] Thread-3 <WE0002I> Stopping web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2009-12-10 06:46:33.285] Thread-3 <WE0003I> Stopped web bundle 'helloWorld' version '0.0.0' with context path '/helloWorld'.
+[2009-12-10 06:46:33.290] fs-watcher <DE0010I> Stopping bundle 'helloWorld' version '0.0.0'.
+[2009-12-10 06:46:33.295] fs-watcher <DE0011I> Stopped bundle 'helloWorld' version '0.0.0'.
+[2009-12-10 06:46:33.302] fs-watcher <DE0013I> Uninstalling bundle 'helloWorld' version '0.0.0'.
+[2009-12-10 06:46:33.319] fs-watcher <DE0014I> Uninstalled bundle 'helloWorld' version '0.0.0'.
+....
+
+anchor:deployment-undeploy-manual[]
+
+==== Undeploying Using the Admin Console
+
+You can undeploy only whole artifacts from the Admin Console, or in other words, you cannot undeploy the separate modules or bundles that make up an artifact.
+
+The only artifact that you cannot undeploy from the Admin Console is the Admin Console itself. If you need to undeploy this application, you must remove it from the pickup directory (by default `SERVER_HOME/pickup`); the name of the artifact is
+`org.eclipse.virgo.server.admin-{version}.plan`.
+
+See xref:admin-console-manage-artifacts[Viewing and Managing the Lifecycle of Deployed Artifacts] for details about uninstalling (undeploying) an artifact using the Admin Console. The high-level steps are to highlight the artifact in the artifact tree then click `Uninstall`.
+
+anchor:deployment-undeploying-shared[]
+
+==== Undeploying Shared Artifacts
+
+Sharing is taken into account when artifacts are undeployed.
+A shared artifact is undeployed only when all the artifacts referencing the shared artifact have been undeployed
+and, if the shared artifact was deployed in its own right, the artifact itself has been undeployed.
+
diff --git a/user-guide/images/bundle-repository.png b/user-guide/src/docs/asciidoc/assets/images/bundle-repository.png
similarity index 100%
rename from user-guide/images/bundle-repository.png
rename to user-guide/src/docs/asciidoc/assets/images/bundle-repository.png
Binary files differ
diff --git a/user-guide/images/concepts/bundle-lifecycle.graffle b/user-guide/src/docs/asciidoc/assets/images/concepts/bundle-lifecycle.graffle
similarity index 100%
rename from user-guide/images/concepts/bundle-lifecycle.graffle
rename to user-guide/src/docs/asciidoc/assets/images/concepts/bundle-lifecycle.graffle
Binary files differ
diff --git a/user-guide/images/concepts/bundle-lifecycle.png b/user-guide/src/docs/asciidoc/assets/images/concepts/bundle-lifecycle.png
similarity index 100%
rename from user-guide/images/concepts/bundle-lifecycle.png
rename to user-guide/src/docs/asciidoc/assets/images/concepts/bundle-lifecycle.png
Binary files differ
diff --git a/user-guide/images/console-artifact-deployed.png b/user-guide/src/docs/asciidoc/assets/images/console-artifact-deployed.png
similarity index 100%
rename from user-guide/images/console-artifact-deployed.png
rename to user-guide/src/docs/asciidoc/assets/images/console-artifact-deployed.png
Binary files differ
diff --git a/user-guide/images/console-artifact-undeployed.png b/user-guide/src/docs/asciidoc/assets/images/console-artifact-undeployed.png
similarity index 100%
rename from user-guide/images/console-artifact-undeployed.png
rename to user-guide/src/docs/asciidoc/assets/images/console-artifact-undeployed.png
Binary files differ
diff --git a/user-guide/images/console-artifacts.png b/user-guide/src/docs/asciidoc/assets/images/console-artifacts.png
similarity index 100%
rename from user-guide/images/console-artifacts.png
rename to user-guide/src/docs/asciidoc/assets/images/console-artifacts.png
Binary files differ
diff --git a/user-guide/images/console-bundle-details.png b/user-guide/src/docs/asciidoc/assets/images/console-bundle-details.png
similarity index 100%
rename from user-guide/images/console-bundle-details.png
rename to user-guide/src/docs/asciidoc/assets/images/console-bundle-details.png
Binary files differ
diff --git a/user-guide/images/console-configuration-details.png b/user-guide/src/docs/asciidoc/assets/images/console-configuration-details.png
similarity index 100%
rename from user-guide/images/console-configuration-details.png
rename to user-guide/src/docs/asciidoc/assets/images/console-configuration-details.png
Binary files differ
diff --git a/user-guide/images/console-default-artifacts.png b/user-guide/src/docs/asciidoc/assets/images/console-default-artifacts.png
similarity index 100%
rename from user-guide/images/console-default-artifacts.png
rename to user-guide/src/docs/asciidoc/assets/images/console-default-artifacts.png
Binary files differ
diff --git a/user-guide/images/console-deployment-error.png b/user-guide/src/docs/asciidoc/assets/images/console-deployment-error.png
similarity index 100%
rename from user-guide/images/console-deployment-error.png
rename to user-guide/src/docs/asciidoc/assets/images/console-deployment-error.png
Binary files differ
diff --git a/user-guide/images/console-dump-details.png b/user-guide/src/docs/asciidoc/assets/images/console-dump-details.png
similarity index 100%
rename from user-guide/images/console-dump-details.png
rename to user-guide/src/docs/asciidoc/assets/images/console-dump-details.png
Binary files differ
diff --git a/user-guide/images/console-file-upload.png b/user-guide/src/docs/asciidoc/assets/images/console-file-upload.png
similarity index 100%
rename from user-guide/images/console-file-upload.png
rename to user-guide/src/docs/asciidoc/assets/images/console-file-upload.png
Binary files differ
diff --git a/user-guide/images/console-main-page.png b/user-guide/src/docs/asciidoc/assets/images/console-main-page.png
similarity index 100%
rename from user-guide/images/console-main-page.png
rename to user-guide/src/docs/asciidoc/assets/images/console-main-page.png
Binary files differ
diff --git a/user-guide/images/console-osgi-state.png b/user-guide/src/docs/asciidoc/assets/images/console-osgi-state.png
similarity index 100%
rename from user-guide/images/console-osgi-state.png
rename to user-guide/src/docs/asciidoc/assets/images/console-osgi-state.png
Binary files differ
diff --git a/user-guide/images/console-par-details.png b/user-guide/src/docs/asciidoc/assets/images/console-par-details.png
similarity index 100%
rename from user-guide/images/console-par-details.png
rename to user-guide/src/docs/asciidoc/assets/images/console-par-details.png
Binary files differ
diff --git a/user-guide/images/console-server-props.png b/user-guide/src/docs/asciidoc/assets/images/console-server-props.png
similarity index 100%
rename from user-guide/images/console-server-props.png
rename to user-guide/src/docs/asciidoc/assets/images/console-server-props.png
Binary files differ
diff --git a/user-guide/images/default-target-create.png b/user-guide/src/docs/asciidoc/assets/images/default-target-create.png
similarity index 100%
rename from user-guide/images/default-target-create.png
rename to user-guide/src/docs/asciidoc/assets/images/default-target-create.png
Binary files differ
diff --git a/user-guide/images/director_args.png b/user-guide/src/docs/asciidoc/assets/images/director_args.png
similarity index 100%
rename from user-guide/images/director_args.png
rename to user-guide/src/docs/asciidoc/assets/images/director_args.png
Binary files differ
diff --git a/user-guide/images/director_result.png b/user-guide/src/docs/asciidoc/assets/images/director_result.png
similarity index 100%
rename from user-guide/images/director_result.png
rename to user-guide/src/docs/asciidoc/assets/images/director_result.png
Binary files differ
diff --git a/user-guide/images/env-variables.png b/user-guide/src/docs/asciidoc/assets/images/env-variables.png
similarity index 100%
rename from user-guide/images/env-variables.png
rename to user-guide/src/docs/asciidoc/assets/images/env-variables.png
Binary files differ
diff --git a/user-guide/images/install-windows-1-FileListing.png b/user-guide/src/docs/asciidoc/assets/images/install-windows-1-FileListing.png
similarity index 100%
rename from user-guide/images/install-windows-1-FileListing.png
rename to user-guide/src/docs/asciidoc/assets/images/install-windows-1-FileListing.png
Binary files differ
diff --git a/user-guide/images/install-windows-2-SecuritySettings.png b/user-guide/src/docs/asciidoc/assets/images/install-windows-2-SecuritySettings.png
similarity index 100%
rename from user-guide/images/install-windows-2-SecuritySettings.png
rename to user-guide/src/docs/asciidoc/assets/images/install-windows-2-SecuritySettings.png
Binary files differ
diff --git a/user-guide/images/install-windows-3-AdvanceSettingsOwner.png b/user-guide/src/docs/asciidoc/assets/images/install-windows-3-AdvanceSettingsOwner.png
similarity index 100%
rename from user-guide/images/install-windows-3-AdvanceSettingsOwner.png
rename to user-guide/src/docs/asciidoc/assets/images/install-windows-3-AdvanceSettingsOwner.png
Binary files differ
diff --git a/user-guide/images/install-windows-4-AllSetReadAndExecute.png b/user-guide/src/docs/asciidoc/assets/images/install-windows-4-AllSetReadAndExecute.png
similarity index 100%
rename from user-guide/images/install-windows-4-AllSetReadAndExecute.png
rename to user-guide/src/docs/asciidoc/assets/images/install-windows-4-AllSetReadAndExecute.png
Binary files differ
diff --git a/user-guide/images/jmx-local-attach.png b/user-guide/src/docs/asciidoc/assets/images/jmx-local-attach.png
similarity index 100%
rename from user-guide/images/jmx-local-attach.png
rename to user-guide/src/docs/asciidoc/assets/images/jmx-local-attach.png
Binary files differ
diff --git a/user-guide/images/jmx-remote-attach-default.png b/user-guide/src/docs/asciidoc/assets/images/jmx-remote-attach-default.png
similarity index 100%
rename from user-guide/images/jmx-remote-attach-default.png
rename to user-guide/src/docs/asciidoc/assets/images/jmx-remote-attach-default.png
Binary files differ
diff --git a/user-guide/images/jmx-remote-attach-jmxport.png b/user-guide/src/docs/asciidoc/assets/images/jmx-remote-attach-jmxport.png
similarity index 100%
rename from user-guide/images/jmx-remote-attach-jmxport.png
rename to user-guide/src/docs/asciidoc/assets/images/jmx-remote-attach-jmxport.png
Binary files differ
diff --git a/user-guide/images/jmx-remote-attach-jmxusers.png b/user-guide/src/docs/asciidoc/assets/images/jmx-remote-attach-jmxusers.png
similarity index 100%
rename from user-guide/images/jmx-remote-attach-jmxusers.png
rename to user-guide/src/docs/asciidoc/assets/images/jmx-remote-attach-jmxusers.png
Binary files differ
diff --git a/user-guide/images/kernel-user-region.graffle b/user-guide/src/docs/asciidoc/assets/images/kernel-user-region.graffle
similarity index 100%
rename from user-guide/images/kernel-user-region.graffle
rename to user-guide/src/docs/asciidoc/assets/images/kernel-user-region.graffle
Binary files differ
diff --git a/user-guide/images/kernel-user-region.png b/user-guide/src/docs/asciidoc/assets/images/kernel-user-region.png
similarity index 100%
rename from user-guide/images/kernel-user-region.png
rename to user-guide/src/docs/asciidoc/assets/images/kernel-user-region.png
Binary files differ
diff --git a/user-guide/images/management-control-summary.png b/user-guide/src/docs/asciidoc/assets/images/management-control-summary.png
similarity index 100%
rename from user-guide/images/management-control-summary.png
rename to user-guide/src/docs/asciidoc/assets/images/management-control-summary.png
Binary files differ
diff --git a/user-guide/images/management-resource-discovery.png b/user-guide/src/docs/asciidoc/assets/images/management-resource-discovery.png
similarity index 100%
rename from user-guide/images/management-resource-discovery.png
rename to user-guide/src/docs/asciidoc/assets/images/management-resource-discovery.png
Binary files differ
diff --git a/user-guide/images/management-server-controls.png b/user-guide/src/docs/asciidoc/assets/images/management-server-controls.png
similarity index 100%
rename from user-guide/images/management-server-controls.png
rename to user-guide/src/docs/asciidoc/assets/images/management-server-controls.png
Binary files differ
diff --git a/user-guide/images/management-server-main-page.png b/user-guide/src/docs/asciidoc/assets/images/management-server-main-page.png
similarity index 100%
rename from user-guide/images/management-server-main-page.png
rename to user-guide/src/docs/asciidoc/assets/images/management-server-main-page.png
Binary files differ
diff --git a/user-guide/images/management-server-started.png b/user-guide/src/docs/asciidoc/assets/images/management-server-started.png
similarity index 100%
rename from user-guide/images/management-server-started.png
rename to user-guide/src/docs/asciidoc/assets/images/management-server-started.png
Binary files differ
diff --git a/user-guide/images/management-server-stopped.png b/user-guide/src/docs/asciidoc/assets/images/management-server-stopped.png
similarity index 100%
rename from user-guide/images/management-server-stopped.png
rename to user-guide/src/docs/asciidoc/assets/images/management-server-stopped.png
Binary files differ
diff --git a/user-guide/images/management-servers-list.png b/user-guide/src/docs/asciidoc/assets/images/management-servers-list.png
similarity index 100%
rename from user-guide/images/management-servers-list.png
rename to user-guide/src/docs/asciidoc/assets/images/management-servers-list.png
Binary files differ
diff --git a/user-guide/images/repo-structure.png b/user-guide/src/docs/asciidoc/assets/images/repo-structure.png
similarity index 100%
rename from user-guide/images/repo-structure.png
rename to user-guide/src/docs/asciidoc/assets/images/repo-structure.png
Binary files differ
diff --git a/user-guide/images/run_configuration.png b/user-guide/src/docs/asciidoc/assets/images/run_configuration.png
similarity index 100%
rename from user-guide/images/run_configuration.png
rename to user-guide/src/docs/asciidoc/assets/images/run_configuration.png
Binary files differ
diff --git a/user-guide/images/s2-logo.png b/user-guide/src/docs/asciidoc/assets/images/s2-logo.png
similarity index 100%
rename from user-guide/images/s2-logo.png
rename to user-guide/src/docs/asciidoc/assets/images/s2-logo.png
Binary files differ
diff --git a/user-guide/images/system-props.png b/user-guide/src/docs/asciidoc/assets/images/system-props.png
similarity index 100%
rename from user-guide/images/system-props.png
rename to user-guide/src/docs/asciidoc/assets/images/system-props.png
Binary files differ
diff --git a/user-guide/images/system-variable.png b/user-guide/src/docs/asciidoc/assets/images/system-variable.png
similarity index 100%
rename from user-guide/images/system-variable.png
rename to user-guide/src/docs/asciidoc/assets/images/system-variable.png
Binary files differ
diff --git a/user-guide/images/target-platform-view.png b/user-guide/src/docs/asciidoc/assets/images/target-platform-view.png
similarity index 100%
rename from user-guide/images/target-platform-view.png
rename to user-guide/src/docs/asciidoc/assets/images/target-platform-view.png
Binary files differ
diff --git a/user-guide/images/virgo-logo-large.png b/user-guide/src/docs/asciidoc/assets/images/virgo-logo-large.png
similarity index 100%
rename from user-guide/images/virgo-logo-large.png
rename to user-guide/src/docs/asciidoc/assets/images/virgo-logo-large.png
Binary files differ
diff --git a/user-guide/images/virgo-logo-small.png b/user-guide/src/docs/asciidoc/assets/images/virgo-logo-small.png
similarity index 100%
rename from user-guide/images/virgo-logo-small.png
rename to user-guide/src/docs/asciidoc/assets/images/virgo-logo-small.png
Binary files differ
diff --git a/user-guide/images/welcome.png b/user-guide/src/docs/asciidoc/assets/images/welcome.png
similarity index 100%
rename from user-guide/images/welcome.png
rename to user-guide/src/docs/asciidoc/assets/images/welcome.png
Binary files differ
diff --git a/user-guide/src/docs/asciidoc/concepts.adoc b/user-guide/src/docs/asciidoc/concepts.adoc
new file mode 100644
index 0000000..4e31f16
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/concepts.adoc
@@ -0,0 +1,526 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:programmer-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-{version}/docs/virgo-programmer-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:concepts[]
+
+== Concepts
+
+This chapter introduces some basic concepts that will help you to use {virgo-name}.
+
+anchor:concepts.modular[]
+
+=== Modular Runtimes and Applications
+
+{tomcat-product-name}, {jetty-product-name}, {kernel-product-name} and {nano-product-name} are Java runtimes each composed of
+a collection of modules and supporting applications which are also composed of a
+collection of modules.
+Modules can be shared between applications and multiple versions of modules
+can co-exist.
+
+anchor:concepts.osgi[]
+
+=== OSGi Concepts
+
+Modules in {virgo-name} are represented using a standard Java
+module system known as *OSGi*.
+Modules in OSGi are known as *bundles*.
+Bundles consist of programs and resources organised by Java package together
+with metadata which declares imported and exported packages.
+A bundle *exports* a package to make the corresponding programs and resources
+available for use by other bundles.
+A bundle *imports* a package to use the corresponding programs and resources of
+another bundle.
+
+Representing a program as a collection of bundles makes it easier for the
+programmer to manage it and modify it and for teams of programmers to divide
+responsibilities between themselves.
+A bundle is similar to a Java class in this respect. Design principles similar to those for
+organising data and programs into classes can be applied
+to organising applications into bundles.
+
+An industry consortium known as the
+*OSGi Alliance* develops OSGi
+specifications, reference implementations, and compliance tests.
+{virgo-name} is built on the Equinox OSGi framework which is also
+the reference implementation for the OSGi framework specification.
+
+==== Bundles
+
+Each bundle is stored in a file which conforms to the JAR file format and
+can contain Java classes, a manifest (in `META-INF/MANIFEST.MF`),
+and further resource files.
+
+The OSGi framework enables bundles to be installed and run.
+
+OSGi identifies bundles "by name" and "by identifier" (id).
+
+The *symbolic name* and
+*version* of a bundle are attributes of the bundle which identify the bundle.
+A bundle declares its *symbolic name* and *version*
+in its manifest (a file called `MANIFEST.MF`) like this:
+
+[source,txt]
+----
+Bundle-SymbolicName: org.foo.bundle
+Bundle-Version: 1.2.3.BUILD-2009-06-04
+----
+
+Additionally, the OSGi framework
+assigns a distinct number, known as a *bundle id*, to each bundle
+as it is installed. Bundles may be referred to "by identifier" using this number.
+The OSGi framework itself resides in a
+bundle with bundle id `0`.
+
+The dependencies between bundles are expressed statically in terms of packages and
+dynamically in terms of services. A package is familiar to Java programmers.
+For example, a Java program may depend on a class `org.foo.X`,
+from package `org.foo`, and a bundle
+containing that program
+would either need to contain `org.foo.X` or depend on the
+package `org.foo`.
+Package dependencies are specified in the bundle manifest, for example:
+
+[source,txt]
+----
+Import-Package: org.foo
+----
+
+A bundle which provides a package for use by other bundles *must*
+export the package in its manifest. For example:
+
+[source,txt]
+----
+Export-Package: org.foo
+----
+
+The OSGi framework ensures that a given bundle's package dependencies
+can be *satisfied* before the bundle runs. This process is known as
+*resolution*.
+
+After a bundle is resolved, its classes and resources are available for
+loading.
+In OSGi, bundles and their packages do not appear on the application classpath.
+Instead, each bundle has a class loader which loads its own classes and loads classes belonging to each of its
+imported packages by deferring to the bundle class loader that exports the package.
+
+==== Life Cycle
+
+The OSGi framework manages the *life cycle* of each bundle. A bundle is
+first of all *installed* and will be in the INSTALLED state.
+If a request is made to *start* the bundle, the OSGi framework *resolves* the bundle
+and, if resolution was successful, will subsequently move the bundle to the ACTIVE state.
+If a request is made to *stop* the bundle, the OSGi framework will move the
+bundle back to the RESOLVED state. A request may then be made to *uninstall*
+the bundle.
+
+While the bundle is INSTALLED, ACTIVE or RESOLVED, it may be *updated* to pick up
+some changes. These changes are not detected by bundles which were depending
+on the bundle before it was updated.
+A "refresh packages" operation may be performed to ripple the
+changes out to those bundles. (See xref:concepts.services[].)
+The life cycle of a bundle can be summarised by a state transition diagram.
+This diagram shows some more of the intermediate states of a bundle not described in the overview above:
+
+.Bundle life cycle
+image:concepts/bundle-lifecycle.png[role="center"]
+////
+TODO width="120mm"
+////
+
+anchor:concepts.services[Services concepts]
+
+==== Services
+
+Bundles may publish Java objects, known as *services*,
+to a registry managed by the OSGi framework. Other bundles running in
+the same OSGi framework can then find and use those services. Services
+are typically instances of some shared Java interface. A bundle which
+provides a service need not then export the package containing the
+*implementation*
+class of the service.
+
+For example, a bundle could export a package containing the interface
+`org.bar.SomeInterface`, thus:
+
+[source,txt]
+----
+Export-Package: org.bar
+----
+
+…implement the interface with a class `SomeImpl`:
+
+[source,java]
+----
+package org.bar.impl;
+
+class SomeImpl implements SomeInterface {
+ …
+}
+----
+
+…create an instance of `SomeImpl` and
+then publish this instance (as an instance of the interface `SomeInterface`).
+
+An OSGi framework publishes a number of standard services. For example, the
+*Package Admin* service provides the "refresh packages" life cycle operation
+mentioned above.
+
+OSGi provides an *API* which can be used to publish and find services,
+but it is much simpler to use Blueprint to accomplish this. (See xref:concepts.blueprint[].)
+
+==== Versioning
+
+OSGi allows different versions of bundles, packages, and several
+other entities, to co-exist in the same framework
+and provides some mechanisms for managing these versions.
+
+==== Version Numbers
+
+An OSGi *version number* consists of up to three numeric components,
+or exactly three
+numeric components followed by a string component. These components are
+separated by a period ("`.`") and
+are called the *major*, *minor*, *micro*,
+and *qualifier* components, respectively.
+
+For example, the version `2.4.1.ga` has major component `2`, minor component
+`4`, micro component `1`,
+and a qualifier component `ga`. (There are restrictions on the characters that can appear in
+a qualifier. For example: letters, digits, underscores and hyphens are allowed; periods and commas are not.)
+
+Trailing components may be omitted along with their period (`.`). So, for example, the version
+numbers `2`, `2.0`, and `2.0.0`
+all denote the same version. This example demonstrates that `0` is assumed if a numeric component is omitted,
+and the empty string is assumed for an omitted qualifier.
+
+==== Version Ranges
+
+Dependencies on bundles and packages have an associated *version range*
+which is specified using an interval notation: a square bracket
+"`[`" or "`]`" denotes
+an *inclusive* end of the range and a round bracket
+"`(`" or "`)`" denotes
+an *exclusive* end of the range. Where one end of the range is to be included and the other excluded, it is permitted to
+pair a round bracket with a square bracket.
+The examples below make this clear.
+
+If a single version number is used where a version *range* is
+required this does *not* indicate a single version, but the range *starting* from that version and
+including all higher versions.
+
+There are three common cases:
+
+* A "strict" version range, such as `[1.2,1.2]`, which
+denotes that version and only that version.
+* A "half-open" range, such as
+`[1.2,2)`, which has an inclusive lower limit
+and an exclusive upper limit, denoting version `1.2.0` and any version after this, up
+to, *but not including*, version `2.0.0`.
+* An "unbounded" version range, such as `1.2`, which
+denotes version `1.2` and *all* later versions.
+
+==== Versioning Policies
+
+A *versioning policy* is a way of using version numbers to indicate compatible
+and incompatible changes.
+OSGi does not mandate a particular versioning policy.
+Instead, a specific versioning policy may be implemented using version ranges.
+Strict and half-open version ranges are most useful in representing versioning
+policies.
+Unbounded version ranges can lead to problems as they (unrealistically) assume that
+compatibility will be preserved indefinitely.
+
+For example, a conservative versioning policy might assume that any change, other than
+in the qualifier component of a version, implies an incompatible
+change to the object.
+Such a policy would employ version ranges such as `[1.2.1.beta,1.2.2)`
+which accept any version from `1.2.1.beta` (inclusive) up to but not including
+`1.2.2` (exclusive).
+
+Alternatively, a relaxed versioning policy might assume that only changes in the major component of
+a version denote an incompatible change.
+Such a policy would employ version ranges such as `[1.2,2)` to capture this.
+
+The OSGi Alliance has published a http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf[Semantic
+Versioning white paper] which provides some recommendations and guidance on versioning policies.
+
+==== Bundle Version
+
+Each bundle has a version.
+The bundle's version may be specified in the manifest using a
+`Bundle-Version` header:
+
+....
+Bundle-Version: 1.4.3.BUILD-20090302
+....
+
+If not specified the bundle version is assumed to be `0`.
+
+==== Package Version
+
+Each exported package has a version.
+The exported package's version may be specified on the Export-Package manifest header. For example
+
+....
+Export-Package: org.foo;version="2.9",org.bar;version="1"
+....
+
+exports two packages: `org.foo`, at version `2.9.0` and
+`org.bar`, at version `1.0.0`.
+
+If the version attribute is omitted, the version is assumed to be `0`.
+
+Each package *import* has a version *range*.
+The package import version range may be specified on the `Import-Package` manifest header.
+If interval notation is used, the version range must be enclosed in double quotes, for example:
+
+....
+Import-Package: org.foo;version="[2,3)",org.bar;version="[1,1]"</programlisting>
+....
+
+seeks to import a package `org.foo` in the range `[2.0.0,3.0.0)` and a package
+`org.bar` with the (exact) version `1.0.0`.
+
+If a version range is not specified on an import, the range `0` is assumed, meaning that
+any version of this package would satisfy the import.
+
+==== Bundle Manifest Version
+
+Bundle manifests have a version which is `1` by default,
+indicating OSGi Release 3 semantics.
+{virgo-name} is based on OSGi Release 4 and therefore expects bundle manifests to be
+at version `2`, indicating OSGi Release 4 semantics.
+The bundle manifest's version should be specified on the Bundle-ManifestVersion manifest header, exactly as follows:
+
+....
+Bundle-ManifestVersion: 2
+....
+
+==== Manifest Version
+
+Manifests themselves also have a version which *must* be specified as `1.0`.
+This is not an OSGi definition but part of the
+(http://docs.oracle.com/javase/6/docs/technotes/guides/jar/jar.html[JAR file specification]).
+
+....
+Manifest-Version: 1.0
+....
+
+anchor:concepts.blueprint[Gemini Blueprint]
+
+=== Blueprint Concepts
+
+Spring DM (the predecessor of Gemini Bluprint) is a project which enables *services* to be published and consumed
+using descriptions written in XML.
+
+The XML descriptions reside in files with extension `.xml` in the
+bundle's `META-INF/spring` sub-directory.
+
+To publish a service, an `<osgi:service>` tag is used, specifying the
+implementation class of the service and the interface class to be used.
+Spring DM constructs an instance of the implementation class and
+publishes that instance in the OSGi service registry under the interface when the bundle is started.
+
+To consume a service, an `<osgi:reference>` tag is used and the
+service may be passed into other Spring beans using Spring's dependency
+injection facilities.
+
+Spring DM automatically creates proxies for OSGi services so that the actual service
+object may come and go at runtime.
+If a service disappears, any proxies to the service will wait for the service to re-appear.
+This effect is known as *damping*.
+
+When a bundle is started, Spring DM builds the application contexts
+specified by the XML descriptions, creates proxies for the specified services, and publishes
+the specified services to the OSGi service registry.
+
+When a bundle is stopped, Spring DM retracts any services it published on behalf of the bundle
+and closes the bundle's application contexts.
+{virgo-name} turns off damping of a service proxy while the proxy's application context
+is being closed.
+
+Spring DM was contributed to Eclipse as the *Gemini Blueprint* project.
+{virgo-name} has Gemini Blueprint built-in.
+
+Gemini Blueprint supports both Spring DM and Blueprint programming models.
+Blueprint, known formally as the "OSGi Blueprint Container", provides some of the basic facilities of Spring DM,
+including all those just mentioned, but in an OSGi standard form.
+See xref:furtherreading[] for the Blueprint specification.
+
+anchor:concepts.virgo[]
+
+=== {virgo-name} Concepts
+
+[NOTE]
+--
+This section is not relevant for {nano-product-name}.
+--
+
+anchor:concepts.repositories[]
+
+==== The Provisioning Repository
+
+The {virgo-name} provisioning repository contains artifacts and metadata indexed by the artifact type, name, and version. There are three kinds of repository: *external*, *watched*, and *remote*. Repositories are passive in the sense that changes to repository content do not cause artifacts to be deployed into {virgo-name}, refreshed, or undeployed.
+
+==== Artifact Types
+
+In addition to the standard OSGi bundle, artifact types in {virgo-name} include configuration (properties file), PAR, plan, and library.
+PARs, plans, and libraries are discussed in xref:concepts.grouping[].
+
+==== External Repositories
+
+External repositories are created by scanning a directory which contains artifacts, possibly in nested directories. The repository configuration specifies a pattern which
+says which files should be treated as artifacts. After the repository is created, changes to the directory do not affect the repository content.
+
+{virgo-name}'s default repository configuration, in `configuration/org.eclipse.virgo.repository.properties`, specifies an external repository created from the
+`repository/ext` directory.
+
+==== Watched Repositories
+
+Watched repositories are created by scanning a directory which contains artifacts but no nested directories. All files in the directory are treated as artifacts.
+The directory is re-scanned periodically and the interval between re-scans is specified in the repository configuration.
+The directory is also re-scanned when an artifact is deployed into {virgo-name}.
+Changes detected by re-scanning are reflected in the repository content. Note that changing the content of a watched repository does not cause artifacts to be deployed
+into {virgo-name}, refreshed, or undeployed.
+
+{virgo-name}'s default repository configuration specifies a watched repository based on the contents of the `repository/usr` directory.
+
+===== Remote Repositories
+
+A remote repository refers to a repository hosted by a {virgo-name} instance sometimes known as a *repository server*.
+The hosted repository is configured using the file `configuration/org.eclipse.virgo.apps.repository.properties` and may be either an external or a watched
+repository.
+
+The remote repository is accessed by a {virgo-name} instance sometimes known as a *repository client*.
+The repository client is normally a different instance of {virgo-name} to the instance hosting the repository, but it can be the same instance (which is handy for
+testing). The remote repository periodically downloads its index from the hosted repository. The period between downloads may be configured in the repository
+configuration. The remote repository also caches artifacts which have secure hashes associated with them in the hosted repository. Only bundles currently have secure
+hashes associated with them. The secure hash is used to determine when a cached artifact is stale and needs to be freshly downloaded.
+
+==== Repository Chains
+
+The {virgo-name} repository is configured as a *chain* of external, watched, and remote repositories.
+The chain is a list which is searched in the configured order.
+The effect of this search order is that an artifact with a given type, name, and version which appears in more than one repository in the chain is only accessed from the
+first repository in the chain in which it appears. Abstractly, the repository chain behaves as a single repository, but its content may mutate in quite a different way to
+the content of an individual external, watched, or remote repository.
+
+anchor:concepts.grouping[Grouping Bundles]
+
+==== Grouping Bundles
+
+{virgo-name} provides a way of grouping together a collection
+of OSGi bundles and other artifacts which comprise a single application.
+These artifacts are placed in a JAR file with extension "`.par`". This is called a PAR file.
+
+All the bundles in a PAR file are resolved together and so mutual dependencies are permitted.
+
+At runtime a PAR file provides a *scope* in the sense that bundles
+inside the PAR file may depend on packages and services outside the PAR file,
+but bundles outside the PAR file may not depend on packages and services
+provided by the PAR file.
+
+{virgo-name} also provides the plan artifact as another way of grouping bundles and other artifacts into an application.
+A *plan* is a file (in XML format) listing a collection of artifacts.
+The artifacts referred to by a plan reside in the {virgo-name} provisioning repository.
+
+In addition to PARs and plans, which are used for deploying groups of artifacts, {virgo-name} provides libraries as a way of grouping together a collection
+of bundles that can then be imported into an application using the {virgo-name}-specific `Import-Library` manifes header.
+
+anchor:kernel.user.region[]
+
+==== Kernel and User Region
+
+Conceptually, {tomcat-product-name-short} can be divided into two separate subsystems, one of which actually encompases the other:
+
+* The *kernel*, which is the heart of {tomcat-product-name-short}. It makes up most of {tomcat-product-name-short}, except for the part that supports Web applications. In other words, the kernel provides full OSGi modular support for your applications, as long as they are not Web-based.
+See xref:kernel-overview[The {kernel-product-name}] for additional information.
+* The *user region* is the subsystem that manages user applications. It deliberately isolates the kernel from both your applications and those of the {tomcat-product-name-short} itself, such as the Admin Console, which protects the kernel from interference by applications.
+See xref:user-region-overview[The User Region] for additional information.
+
+When you download and install {tomcat-product-name} you get both the kernel and web server support (configured in the user region). You can also http://www.eclipse.org/virgo/download/[download and use the kernel] on its own if you do not plan on deploying Web applications or using the
+web-based Admin Console and you'll get the kernel and a minimal user region (with no web support).
+
+The following graphic shows how the kernel and user region make up {tomcat-product-name-short}:
+
+image:kernel-user-region.png[]
+////
+TODO width="885px" depth="805px" />
+////
+
+anchor:kernel-overview[]
+
+==== The {kernel-product-name}
+
+The {kernel-product-name} encapsulates almost all of {tomcat-product-name-short} except for the deployment of Web applications. In sum, the kernel provides the following {tomcat-product-name-short} features:
+
+* Deployment of non-Web artifacts, such as OSGi bundles, PARs, plans,
+and configuration artifacts.
+* Local and hosted repositories
+* Scoping
+* Hot deployment
+* User region
+* Auto-provisioning
+* System and application tracing and dump support
+* Spring beans and Blueprint support
+
+See xref:configuring[Configuring {tomcat-product-name-short}] for details about configuring the kernel to better suit your environment.
+
+anchor:user-region-overview[]
+
+==== The User Region
+
+The user region isolates the kernel from deployed applications,
+including both your own user applications and the user-oriented
+{tomcat-product-name-short} applications such as the Admin Console. This means
+that the kernel is mostly invisible to applications and to application
+management. This is because most of the kernel bundles are not
+installed in the user region (apart from a few needed for region
+management). The necessary function to support the kernel runs in the
+OSGi framework, but the user region applications cannot see it, except
+for the services that are normally offered.
+
+This isolation has many benefits. For example, it is not necessary for the kernel and user applications to use the same version of the Spring Framework. In fact the kernel installs only those parts of the Spring Framework that it needs. If you update the kernel, it is far less likely that you will also need to upgrade or adjust the applications to accomodate a new version of the kernel. The kernel implementation is therefore much more stable and resilient and applications are much more likely to survive kernel upgrades between releases.
+When you install {tomcat-product-name-short}, the kernel creates a single user region.
+The kernel and the user region are configured independently of each other; see xref:configuring[Configuring {tomcat-product-name-short}] for details.
+
+Finally, the isolation provided by the user region together with scoped applications and plans solve common dependency problems that occur when using OSGi.
+
+anchor:concepts.p2[]
+
+=== p2 Concepts
+
+At EclipseCon 2011 there was a great introductory presentation on p2. It gives a nice overview of the whole provisioning system.
+You can find it recorded http://fosslc.org/drupal/content/gentle-introduction-p2[here(video).]
+
+http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/[This blog post]
+provides some background on why p2 was created as well as a brief overview of what p2 repositories
+are and how this relates to a runtime.
+
+This http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit[presentation(slides only)]
+sheds light on more advanced p2 features and turns our attention to its extension points.
+
+Finally, the http://wiki.eclipse.org/Equinox/p2[p2 wiki]
+also provides both getting started guides as well as information on more advanced features.
+
diff --git a/user-guide/src/docs/asciidoc/configuring.adoc b/user-guide/src/docs/asciidoc/configuring.adoc
new file mode 100644
index 0000000..66aa295
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/configuring.adoc
@@ -0,0 +1,1329 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:nanoweb-product-name: Virgo Nano Full
+:nanoweb-product-name-short: VNF
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:programmer-guide: link:../../virgo-programmer-guide/html/index.html[Programmer Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:configuring[]
+
+== Configuration
+Configuration
+
+You use configuration files in the `$SERVER_HOME/configuration` directory to configure {virgo-name}. You can also configure the OSGi framework using files the same `$SERVER_HOME/configuration` directory. This section divides the configuration of the server into the following high-level tasks:
+
+* xref:configuring-osgi-framework[Configuring the OSGi framework]
+* xref:configuring-framework-extensions[Configuring framework extensions and fragments on the system bundle]
+* xref:configuring-serviceability[Configuring serviceability]
+* xref:configuring-provisioning-repository[Configuring the local provisioning repository]
+* xref:configuring-hosted-repo[Configuring the hosted repository]
+* xref:configuring-kernel[Configuring the kernel and User Region]
+* xref:configuring-tomcat[Configuring the embedded Tomcat servlet container]
+* xref:configuring-web[Configuring the web integration layer]
+* xref:configuring-jetty[Configuring the embedded Jetty servlet container]
+
+[NOTE]
+.Why is there both a config and a configuration directory?
+--
+The *config* directory has always contained {virgo-name} configuration files. When {nano-product-name} and its support for p2 provisioning was introduced in {virgo-name} 3.5.0, a *configuration* directory replaced the old *config* one. Now all {virgo-name} configurations are assembled in that directory providing a single point of configuration. The directory name *configuration* in the installation's root is used by default in p2 to configure the OSGi framework during provisioning.
+This chapter makes it clear which configuration goes in each directory.
+--
+
+[NOTE]
+--
+Sections 4-6 and 8-9 does not apply for {nano-product-name}.
+--
+
+anchor:configuring-osgi-framework[]
+
+=== Configuring the OSGi Framework
+
+This section provides information about configuring the OSGi framework by updating the following files in the `$SERVER_HOME/configuration` directory:
+
+anchor:configuring-osgi-framework-table[]
+[options="header",cols=",,"]
+.OSGi Framework Configuration Files
+|=======================================================================
+| Property File | Description | Location
+| `config.ini` | Configures xref:configuring-framework-properties[OSGi framework properties].
+ | `$SERVER_HOME/configuration`
+| `bundles.info` | Configures xref:configuring-framework-bundles[OSGi framework bundles].
+ | `$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator`
+| `java-server.profile`
+ | Configures the xref:configuring-framework-profile[OSGi framework profile].
+ | `$SERVER_HOME/configuration`
+|=======================================================================
+
+anchor:configuring-framework-properties[]
+
+==== Configuring OSGi Framework Properties
+
+You specify the framework properties in the `$SERVER_HOME/configuration/config.ini` file. The
+properties most relevant to users are described in the following table.
+
+[WARNING]
+--
+We strongly recommend that you update only the
+properties below; updating other properties could cause {virgo-name}
+to fail.
+--
+
+anchor:configuring-framework-properties-table[]
+[options="header",cols=","]
+.Framework Properties
+|=======================================================================
+| Property | Description
+| `org.eclipse.virgo.kernel.startup.wait.limit` | Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel.
+ The default value is 180.
+| `org.eclipse.virgo.suppress.heap.dumps` | Set to 'false' by default this property will prevent heap dumps being contributed to dumps taken during a
+ First Failure Data Capture (FFDC) event. When the heap dumps are produced they will be located along with
+ the other dump artifacts in the `$SERVER_HOME/serviceability/dump/` folder.
+| `osgi.java.profile` | Specifies the profile to use using a `file:` URI with default value
+ `file:configuration/java-server.profile`.
+| `osgi.bundlefile.limit` | Specifies a limit on the number of jar files the framework will keep open.
+ The minimum value allowed is 10. Any value less than 10 will disable the bundle file limit, making the the number of jar files the framework keeps open unlimited.
+ By default the value is 100.
+ Increase the default value if you have many jar files in the bundle class path, expect a lot of file system operations etc.
+|=======================================================================
+
+anchor:configuring-framework-bundles[]
+
+==== Configuring OSGi Framework Bundles
+
+You specify the framework bundles in the `$SERVER_HOME/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info` file. The syntax
+that is accepted for listing bundles there is:
+
+....
+<bsn>,<version>,<jar-location>,<start-level>,<toStart?>
+bsn - the bundle's symbolic name string
+version - the bundle's version string
+jar-location - relative or absolute path to the jar file
+start-level - a digit indicating the bundle's start level
+toStart? - true or false value indicating whether a bundle should be started or not
+....
+
+Here's an example:
+
+....
+org.eclipse.virgo.util.osgi,3.1.0.BUILD-20111031165127,plugins/org.eclipse.virgo.util.osgi_3.1.0.BUILD-20111031165127.jar,4,true
+....
+
+[WARNING]
+--
+We strongly recommend that you don't remove bundles already present in your bundles.info file as that may break your server. Add bundles here only if absolutely necessary.
+--
+
+anchor:configuring-framework-profile[]
+
+==== Configuring OSGi Framework Profile
+
+You specify the framework profile in the `$SERVER_HOME/configuration/java6-server.profile` file. The
+properties most relevant to users are described in the following table.
+
+[WARNING]
+--
+We advise you not to change the framework profile unless you are sure you know exactly what
+you are doing; updating the profile could cause {virgo-name} to fail.
+--
+
+anchor:configuring-framework-profile-table[]
+[options="header",cols=","]
+.Framework Profile Properties
+|=======================================================================
+| Property | Description
+| `org.osgi.framework.bootdelegation` | This property specifies the packages which are loaded by delegation to the application class loader.
+ Bundles can load classes belonging to these packages without importing the packages.
+ The `.*` wildcard matches any package suffix. `java.*` is always
+ boot delegated and must not be specified in this property.
+
+ A common reason for adding packages to this property is to run {virgo-name} under a performance profiler.
+| `org.osgi.framework.system.packages` | This property specifies the packages which are exported by the system bundle.
+ Although the system bundle is typically imported into the User Region, any additional packages will not be
+ visible in the User Region unless you also import them using the `packagedImports` property.
+ See xref:configuring-user-region[Configuring the User Region] for instructions.
+
+ It is very occasionally necessary to extend the set, for example when configuring email logging appenders since the
+ implementation of `javax.mail` is intimately related to the implementation of
+ `javax.activation`.
+
+ To make the corresponding classes available for loading, the relevant JAR file(s) should be placed in
+ `$SERVER_HOME/lib` so that they will be added to the application class path.
+|=======================================================================
+
+anchor:configuring-framework-extensions[]
+
+=== Configuring Framework Extensions and Fragments on the System Bundle
+
+This section provides information about configuring framework extensions and fragments on the system bundle. Deployment of such bundles is not allowed in
+{virgo-name}. This is because by refreshing or uninstalling them the system.bundle is also refreshed, which causes {virgo-name} to crash.
+
+[NOTE]
+--
+This only applies for fragments on the system bundle. All other fragment bundles have no deployment restrictions.
+--
+
+Generally it's best to avoid usage of such fragment bundles as they are a common OSGi framework issue and often require restarting the framework.
+However sometimes there are no other options and one has to use framework extensions or fragments on the system bundle.
+
+You can configure framework extensions and system bundle fragments as follows:
+
+*1.* Place your fragment bundle in the `/plugins` directory of your {virgo-name} installation.
+Lets say we have bundle with
+....
+symbolic name: *testFragment*, version: *1.0.0* and filename: *testFragmentBinary_1.0.0.jar*
+....
+
+*2.* Configure the `bundles.info` file in `/configuration/org.eclipse.equinox.simpleconfigurator` to include the
+just copied fragment or framework extension bundle.
+
+Add a line at the end of the `bundles.info` file similar to this one:
+
+....
+testFragment,1.0.0,plugins/testFragmentBinary_1.0.0.jar,4,false*
+....
+
+*3.* Configure the `org.eclipse.virgo.kernel.userregion.properties` file in `/configuration` folder to import the fragment bundle or framework extension in the User Region.
+
+Add to the `bundleImports` property a new line describing the fragment bundle using its symbolic name and version.
+
+....
+bundleImports = org.eclipse.osgi;bundle-version="0",<emphasis role="bold">testFragment;bundle-version="0"*
+....
+
+anchor:configuring-serviceability[]
+
+=== Configuring Serviceability and Diagnostics
+
+The serviceability features of {virgo-name} allow you to gather and view data and information that you can then use to diagnose problems and failures. Serviceability data includes:
+
+* Service dumps: Contain a snapshot of all the important state from the running {virgo-name} instance when an internal failure or thread deadlock is detected.
+You configure service dumps for {virgo-name} using the xref:configuring-serviceability-medic[org.eclipse.virgo.medic.properties] file in the `$SERVER_HOME/configuration` directory. This file also includes some additional logging configuration.
+
+* Event logs and server/application (trace) logging: Logging support in {virgo-name} is based on http://logback.qos.ch/[Logback]. This means that you have complete control over the format of log output and have the complete range of Logback's appenders available for your use.
+You configure logging for {virgo-name} using the xref:configuring-serviceability-logback[serviceability.xml] file in the `$SERVER_HOME/configuration` directory. This file is essentially the Logback `logback.xml` (or `logback-test.xml`) configuration file but renamed for {virgo-name}.
+
+For additional conceptual information about the serviceability subsystem, see xref:serviceability[]" />.
+
+anchor:configuring-serviceability-medic[]
+
+==== The org.eclipse.virgo.medic.properties File
+
+The `$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties` file configures {virgo-name} service dumps and whether you want to capture `System.out` and `System.err` output to your application's trace file.
+The following table describes the properties you can include in the `$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties` file. This file configures serviceability properties that {virgo-name} includes in addition to those supplied by the Logback, configured in the `serviceability.xml` file.
+
+anchor:medic-properties-table[]
+[options="header",cols=","]
+.Serviceability Properties
+|=======================================================================
+| Property | Description
+| `dump.root.directory` | Specifies the directory to which {virgo-name} writes the service dumps. The directory name is relative to `$SERVER_HOME`.
+| `log.wrapSysOut` | Specifies whether you want to capture `System.out` output from your applications to the application trace file. The output is logged by {virgo-name}'s root logger, which captures `INFO` level and above.
+ Valid values for this property are `true` to capture `System.out` output, or `false` to disable the capture.
+ For more information, see xref:sysout-and-syserr[System.out and System.err].
+| `log.wrapSysErr` | Specifies whether you want to capture `System.err` output from your applications to the application trace file. The output is logged by {virgo-name}'s root logger, which captures `INFO` level and above.
+ Valid values for this property are `true` to capture `System.err` output, or `false` to disable the capture.
+ For more information, see xref:sysout-and-syserr[System.out and System.err].
+| `log.jul.consoleHandler` | Specifies whether you want to use the `ConsoleHandler` of Java Util Logging. The default JVM configuration uses the handler to write logs to `System.err`.
+ Valid values for this property are `true` to enable `ConsoleHandler` output, or `false` to disable it. The default value is `false`.
+ For more information, see http://download.oracle.com/javase/6/docs/technotes/guides/logging/overview.html[Java Logging Overview].
+|=======================================================================
+
+anchor:configuring-serviceability-logback[]
+
+==== The serviceability.xml File
+Logging support in {virgo-name} is based on http://logback.qos.ch/[Logback], which is a successor of the log4j project. The Logback logging framework is faster, more reliable, and easier to use than log4j and certain other logging systems.
+You configure logging for {virgo-name} using the `$SERVER_HOME/configuration/serviceability.xml` file. This file is the standard Logback `logback.xml` or `logback-test.xml` configuration file, but renamed for {virgo-name}.
+The following listing shows the default `serviceability.xml` file in a freshly-installed {virgo-name}; see the text after the listing for a brief overview of the file:
+
+[source,xml]
+----
+<configuration>
+
+ <jmxConfigurator />
+
+ <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
+
+ <appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender">
+ <discriminator>
+ <Key>applicationName</Key>
+ <DefaultValue>virgo-server</DefaultValue>
+ </discriminator>
+ <sift>
+ <appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <file>serviceability/logs/${applicationName}/log.log</file>
+ <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+ <FileNamePattern>serviceability/logs/${applicationName}/log_%i.log</FileNamePattern>
+ <MinIndex>1</MinIndex>
+ <MaxIndex>4</MaxIndex>
+ </rollingPolicy>
+ <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+ <MaxFileSize>10MB</MaxFileSize>
+ </triggeringPolicy>
+ <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
+ <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
+ </encoder>
+ </appender>
+ </sift>
+ </appender>
+
+ <appender name="LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <file>serviceability/logs/log.log</file>
+ <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+ <FileNamePattern>serviceability/logs/log_%i.log</FileNamePattern>
+ <MinIndex>1</MinIndex>
+ <MaxIndex>4</MaxIndex>
+ </rollingPolicy>
+ <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+ <MaxFileSize>10MB</MaxFileSize>
+ </triggeringPolicy>
+ <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
+ <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
+ </encoder>
+ </appender>
+
+ <appender name="EVENT_LOG_STDOUT" class="org.eclipse.virgo.medic.log.logback.ReroutingAwareConsoleAppender">
+ <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
+ <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread <%X{medic.eventCode}> %msg %ex%n</Pattern>
+ </encoder>
+ </appender>
+
+ <appender name="EVENT_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <file>serviceability/eventlogs/eventlog.log</file>
+ <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+ <FileNamePattern>serviceability/eventlogs/eventlog_%i.log</FileNamePattern>
+ <MinIndex>1</MinIndex>
+ <MaxIndex>4</MaxIndex>
+ </rollingPolicy>
+ <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+ <MaxFileSize>10MB</MaxFileSize>
+ </triggeringPolicy>
+ <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
+ <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread <%X{medic.eventCode}> %msg %ex%n</Pattern>
+ </encoder>
+ </appender>
+
+ <logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.localized">
+ <appender-ref ref="EVENT_LOG_STDOUT" />
+ <appender-ref ref="EVENT_LOG_FILE" />
+ </logger>
+
+ <logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.default">
+ <appender-ref ref="SIFTED_LOG_FILE" />
+ <appender-ref ref="LOG_FILE" />
+ </logger>
+
+ <root level="INFO">
+ <appender-ref ref="SIFTED_LOG_FILE" />
+ <appender-ref ref="LOG_FILE" />
+ </root>
+
+</configuration>
+----
+
+Logback allows {virgo-name} to use logger, appender, and encoder (layout) objects to log messages according to message type and level and to format these messages and define where they are written. The default `serviceability.xml` file shown above includes four appenders and three loggers (two user and one root.)
+
+The main information to get from this file is that {virgo-name} writes log messages to four different locations that map to the four appenders:
+
+* The `jmxConfigurator` provides a possibility to configure logback via JMX. For more information see http://logback.qos.ch/manual/jmxConfig.html[JMX Configurator] documentation.
+* The `contextListener` propagates the changes made to the levels of logback loggers to Java Util Logging (JUL). For more information see http://logback.qos.ch/manual/configuration.html#LevelChangePropagator[LevelChangePropagator] documentation.
+* The `SIFTED_LOG_FILE` appender logs both global and application-specific messages to the `$SERVER_HOME/serviceability/logs/`*`applicationName`*`/log.log` file, where *`applicationName`* refers to the name of the application. The log messages for {virgo-name} itself are logged to the `$SERVER_HOME/serviceability/logs/virgo-server/log.log` file. Because this appender creates different log files for each application, it is called a *sifting appender*.
+ The default behaviour of these trace files is that, once `log.log` reaches a 10Mb limit, it rolls into a series of files named
+ `log_`*i*`.log` where *i* ranges from 1 to 4, and logging continues in
+ a new `log.log` file. This is called its *rolling policy*.
+
+ The `<Pattern>` element defines the format of each log message; messages include the timestamp, the thread that generated the log message, the context-specific event code, and a stack trace of the exception, if any. For example:
+ `[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080`
+
+* The `LOG_FILE` appender is very similar to the first one, but it logs *all* log messages to the `$SERVER_HOME/serviceability/log/log.log` file rather than sifting application-specific messages to their own log file. The rolling policy and message format for this appender is similar to that of the `SIFTED_LOG_FILE` appender.
+* The `EVENT_LOG_STDOUT` appender does not log messages to a file, but rather to the console window from which you started {virgo-name}. For example:
+ `[2010-10-25 16:20:49.367] Thread-3 <WE0000I> Starting web bundle 'org.eclipse.virgo.apps.admin.web' version '2.1.0.RELEASE' with context path '/admin'.`
+* The `EVENT_LOG_FILE` appender logs only important events to the `$SERVER_HOME/serviceability/eventlogs/eventlog.log` file, and thus the volume of information is much lower than with the first two appenders. The rolling policy for the event log is the same as with the first two appenders, but the format of the messages is similar to that of the `EVENT_LOG_STDOUT` appender.
+
+The loggers and root logger specify the level of log that is written for each of the referenced appenders.
+
+Typically, the default logging configuration as specified by the `serviceability.xml` file is adequate for all {virgo-name} environments. However, if you want to customize logging further, you can edit this file as well as the `org.eclipse.virgo.medic.properties`. See the http://logback.qos.ch/manual/index.html[logback documentation] for detailed information about the architecture and the configuration of Logback.
+
+anchor:configuring-provisioning-repository[]
+
+=== Configuring the Local Provisioning Repository
+
+You configure the locations that {virgo-name} includes in its provisioning repository
+by editing the `org.eclipse.virgo.repository.properties` file in the `$SERVER_HOME/configuration` directory.
+
+When you specify a property in the file, use the format `repository-name.property=value`, where:
+
+* `repository-name` refers to the name of the local repository.
+* `property` refers to the name of a particular property.
+* `value` refers to the value of the property.
+
+For example, `ext.type=external` specifies that the `type` property of the repository
+with name `ext` is `external`.
+
+The `chain` property specifies the order in which {virgo-name} searches the individual repositories
+when it looks for dependencies.
+The `chain` property uses the names of the individual repositories as specified in the individual repository properties;
+for example, in the property `ext.type=external`, the name of the repository is `ext`.
+
+The default repository configuration for a newly installed {virgo-name} instance is as follows:
+
+[source,txt]
+----
+ext.type=external
+ext.searchPattern=repository/ext/{artifact}
+
+usr.type=watched
+usr.watchDirectory=repository/usr
+
+chain=ext,usr
+----
+
+The default configuration shown above has two searchpaths corresponding to the two default sub-directories of the `$SERVER_HOME/repository` directory created when you first install {virgo-name}: `ext` and `usr`. {virgo-name} searches each of these individual repositories when locating entries for inclusion in the repository.
+
+The `chain` property shows the order in which {virgo-name} searches the individual repositories: first `ext` and then `usr`.
+
+The following table lists all the available properties that you can use to configure an individual repository.
+Individual repositories as well as the repository search chain are configured in the file
+`$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties`.
+
+anchor:repository-options-table[]
+[options="header",cols=",,"]
+.Repository Properties
+|=======================================================================
+| Property | Description | Default Value
+| *`repository-name`*`.type` | Specifies the type of path. You can set this property to one of the following three valid values:
+* `external`: Specifies that this path points to a number of directories that satisfy a given search pattern
+and are local to the current {virgo-name} instance.
+Use the `searchPattern` property to specify the directory search pattern.
+* `watched`: Specifies that this path points to a single directory, local to the current {virgo-name} instance.
+{virgo-name} regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
+{virgo-name} also scans its local watched repositories when deploying any artifact.
+Use the `watchDirectory` property to specify the watched directory
+and the `watchInterval` property to specify how often {virgo-name} checks the directory.
+* `remote`: Specifies that the path points to a remotely-hosted repository,
+hosted by a remote instance of {tomcat-product-name}.
+Use the `uri` property to specify the full URI of the remote repository.
+You can also specify the optional `indexRefreshInterval` property.
+
+See xref:configuring-repository-watched-versus-external[Watched or External Repository?]
+for additional information about when to configure watched or external repositories for your particular environment.
+ | *no default*
+| *`repository-name`*`.searchPattern`
+ | Specifies the pattern that an external repository uses when deciding which local directories it should search
+ when identifying artifacts. Use this property together with *`repository-name`*`.type=external`.
+ See xref:configuring-provisioning-repository-search-paths[Search Paths: Additional Information]
+ for detailed information about specifying a search pattern.
+ | *no default*
+| *`repository-name`*`.watchDirectory`
+ | Specifies the single directory of a watched repository.
+ You can specify either an absolute or relative pathname for the directory.
+ If you specify a relative pathname, it is relative to the root of the {virgo-name} installation (`$SERVER_HOME`).
+ Use this property together with *`repository-name`*`.type=watched`.
+ | *no default*
+| *`repository-name`*`.watchInterval`
+ | Specifies the interval in seconds between checks of a watched directory by a watched repository.
+ Use this property together with *`repository-name`*`.type=watched`.
+ | `5`
+| *`repository-name`*`.uri` | Specifies the URI of the hosted repository to which a remote repository connects.
+ The value of this property takes the following format:
+ `http://`*`host`*`:`*`port`*`/org.eclipse.virgo.apps.repository/`*`remote-repository-name`*
+ where:
+* *`host`* refers to the computer on which the remote {tomcat-product-name-short}
+instance hosts the remote repository.
+* *`port`* refers to a Tomcat listener port of the remote {tomcat-product-name-short}
+instance which hosts the remote repository.
+* *`remote-repository-name`* refers to the name of the remote repository,
+as specified in the `org.eclipse.virgo.apps.repository.properties` file of the remote {tomcat-product-name-short} instance.
+
+Use this property together with *`repository-name`*`.type=remote`. | *no default*
+| *`repository-name`*`.indexRefreshInterval`
+ | Specifies the interval in seconds between checks by a remote repository that
+ its local copy of the hosted repository index is up-to-date
+ (a remote repository acts as a proxy for a hosted repository and thus it holds a local copy of the hosted repository's index).
+
+ Use this property together with *`repository-name`*`.type=remote`.
+ | `5`
+|=======================================================================
+
+anchor:configuring-repository-watched-versus-external[]
+
+==== Should I Configure a Watched or External Repository?
+
+The main difference between a watched and an external repository is that {virgo-name} regularly scans watched directories
+and automatically picks up any changed artifacts,
+while {virgo-name} scans external directories only at startup, and then only if there is no cached index available.
+This means that {virgo-name} always performs a scan of an external repository when you start the server
+with the `-clean` (as this deletes the index) and only scans during a normal startup if the index isn't there because,
+for example, this is the first time you start the server.
+
+There is a performance cost associated with using a watched repository due to {virgo-name} using resources
+to scan the directory at the configured interval.
+The cost is small if the watched repository contains just a few artifacts; however,
+the performance cost increases as the number of artifacts increases.
+Note that {virgo-name} re-scans its local watched repositories when deploying any artifact, so the scanning interval
+can be configured to be relatively long.
+
+ For this reason, we recommend that you put most of your dependencies in external repositories,
+even when in development mode.
+If you make any changes to the artifacts in the external repositories,
+remember to restart {virgo-name} with the `-clean` option so that the server picks up any changes.
+Use watched directories for artifacts that you are prototyping, actively updating, or when adding new dependencies
+so that {virgo-name} quickly and easily picks them up.
+To increase performance even during development, however, you can use an external repository for most of your dependencies,
+in particular the ones that are fairly static.
+
+In production environments, where dependencies should not change,
+we recommend that you use *only* external repositories.
+
+anchor:configuring-provisioning-repository-search-paths[]
+
+==== Search Paths: Additional Information
+
+The *`repository-name`*`.searchPattern` and
+*`repository-name`*`.watchDirectory` properties specify search paths
+for external and watched repositories, respectively,
+that define a physical location that {virgo-name} searches when looking for a library or bundle dependency.
+If a search path is relative, its location is relative to the root of the installation,
+in other words, the `$SERVER_HOME` directory.
+
+anchor:configuring-provisioning-repository-search-paths-wildcards[]
+
+==== Using Wildcards
+
+Search paths specified with the *`repository-name`*`.searchPattern` property
+provide support for wildcards.
+In the entries above, the path segments surrounded by curly braces,
+for example `{bundle}` and `{library}`,
+are wildcards entries for a directory with any name.
+Allowing wildcards to be named in this way is intended to improve the readability of search path configuration.
+
+In addition to supporting the above-described form of wildcards, {virgo-name} also supports Ant-style paths,
+that is `\*` and `**` can be used to represent any directory and
+any series of directories, respectively.
+For example, `repository/usr/{bundle}` and `repository/usr/*`
+are equivalent.
+
+A common usage of the `**` wildcard is to allow dependencies stored in a directory structure of varying depth,
+such as a local Maven repository, to be provisioned by the {virgo-name}.
+
+anchor:configuring-provisioning-repository-using-system-properties[]
+
+==== Using System Properties
+
+You can use system properties when specifying the values of the *`repository-name`*`.searchPattern`,
+*`repository-name`*`.watchDirectory`,
+*`repository-name`*`.watchInterval`,
+*`repository-name`*`.uri`,
+and *`repository-name`*`.indexRefreshInterval`
+properties.
+You reference system properties as `${system.property.name}`;
+for example, a search path of `${user.home}/repository/bundles` references the
+`repository/bundles` directory in the user's home directory.
+
+anchor:configuring-provisioning-repository-examples[]
+
+==== Example Repository Configurations
+
+The following examples provide sample configuration that could be used for some common use cases.
+
+anchor:configuring-provisioning-repository-examples-ivy[]
+
+==== Add an Ivy cache repository
+
+The following example shows how to add an external repository whose location is actually an Ivy cache.
+*Note that Ivy repositories can contain bundles which will conflict with the normal operation of Virgo, so care should
+be exercised when adding such an external repository.*
+
+[source,txt]
+----
+ext.type=external
+ext.searchPattern=repository/ext/{artifact}
+
+usr.type=watched
+usr.watchDirectory=repository/usr
+
+ivy-repo.type=external
+ivy-repo.searchPattern=${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar
+
+chain=ext,usr,ivy-repo
+----
+
+anchor:configuring-provisioning-repository-examples-maven[]
+
+==== Add a Maven local repository
+
+The following example shows how to add an external repository whose location is actually a Maven repository.
+*Note that Maven repositories can contain bundles which will conflict with the normal operation of Virgo, so care should
+be exercised when adding such an external repository.*
+
+[source,txt]
+----
+ext.type=external
+ext.searchPattern=repository/ext/{artifact}
+
+usr.type=watched
+usr.watchDirectory=repository/usr
+
+maven-repo.type=external
+maven-repo.searchPattern=${user.home}/.m2/repository/**/{bundle}.jar
+
+chain=ext,usr,maven-repo
+----
+
+anchor:configuring-repository-examples-remote-watched[]
+
+==== Add remote and watched repositories
+
+The following example shows the default `org.eclipse.virgo.repository.properties` file
+from a freshly-installed {virgo-name} instance, but then updated to include new remote and watched repositories.
+Both of these repositories are part of the repository chain.
+
+The remote repository is called `remote-repo`.
+The URI of the hosted repository from which `remote-repo` gets its artifacts is
+`http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo`;
+this means that there is a {tomcat-product-name-short} instance running on host `my-host`
+whose Tomcat server listens at the default port, `8080`,
+and this server instance hosts a repository called `my-hosted-repo`,
+configured in the `org.eclipse.virgo.apps.repository.properties` file of the remote server instance.
+The remote repository checks for changes in the hosted repository every 30 seconds.
+
+The watched repository is called `watched-repo` and the directory that holds the artifacts
+is `repository/watched`,
+relative to the installation directory of the {tomcat-product-name-short} instance.
+The server checks for changes in this watched repository every 5 seconds.
+
+[source,txt]
+----
+ext.type=external
+ext.searchPattern=repository/ext/{artifact}
+
+usr.type=watched
+usr.watchDirectory=repository/usr
+
+remote-repo.type=remote
+remote-repo.uri=http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo
+remote-repo.indexRefreshInterval=30
+
+watched-repo.type=watched
+watched-repo.watchedDirectory=repository/watched
+watched-repo.watchedInterval=5
+
+chain=ext,usr,remote-repo,watched-repo
+----
+
+anchor:configuring-hosted-repo[]
+
+=== Configuring a Hosted Repository
+
+You configure a {tomcat-product-name-short} instance to host a repository
+by editing the `$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties` file;
+remote clients can then access the artifacts in this hosted repository and use them locally.
+
+When you specify a property in the file, use the format `repository-name.property=value`, where:
+
+* `repository-name` refers to the name of the hosted repository.
+* `property` refers to the name of a particular property.
+* `value` refers to the value of the property.
+
+For example, `my-hosted-repo.type=external` specifies that the `type` property
+of the `my-hosted-repo` repository is `external`.
+
+The following table lists the properties that you can include in the `org.eclipse.virgo.apps.repository.properties` file.
+
+anchor:hosted-repository-properties-table[]
+[options="header",cols=","]
+.Hosted Repository Properties
+|=======================================================================
+| Property | Description
+| *`repository-name`*`.type` | Specifies the type of path of the hosted repository.
+ All paths are local to the current {tomcat-product-name-short} instance.
+ You can set this property to one of the following valid values:
+* `external`: Specifies that this path points to a number of directories that satisfy a given search pattern.
+Use the `searchPattern` property to specify the directory search pattern.
+* `watched`: Specifies that this path points to a single directory.
+{virgo-name} regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
+Use the `watchDirectory` property to specify the actual watched directory and the `watchInterval` property
+to specify how often {tomcat-product-name-short} checks the directory.
+
+See xref:configuring-repository-watched-versus-external[Watched or External Repository?]
+for additional information about when to configure watched or external repositories for your particular environment.
+
+| *`repository-name`*`.searchPattern` | Specifies the pattern that an external hosted repository uses when deciding which
+ local directories it should search when identifying artifacts.
+ Use this property when `repository-name.type=external`.
+ See xref:configuring-provisioning-repository-search-paths[Search Paths: Additional Information]
+ for detailed information about specifying a search pattern.
+| *`repository-name`*`.watchDirectory` | Specifies the single directory of a watched hosted repository.
+ You can specify either an absolute or relative pathname for the directory.
+ If you specify a relative pathname, it is relative to the root of the {tomcat-product-name-short} installation (`$SERVER_HOME`).
+ Use this property when `repository-name.type=watched`.
+| *`repository-name`*`.watchInterval` | Specifies the interval in seconds between checks of a watched directory by a watched hosted repository.
+ This property is optional. Use this property when `repository-name.type=watched`.
+|=======================================================================
+
+The following sample shows a `org.eclipse.virgo.apps.repository.properties` file with a single external repository
+called `my-hosted-repo` with search pattern `$SERVER_HOME/repository/hosted/*`.
+
+....
+my-hosted-repo.type=external
+my-hosted-repo.searchPattern=repository/hosted/*
+....
+
+See xref:configuring-repository-examples-remote-watched[Example of watched and remote repositories]
+for details on how a local repository can remotely access the artifacts in this hosted repository.
+
+anchor:configuring-kernel
+
+=== Configuring the Kernel and User Region
+
+This section provides information about configuring the {virgo-name} kernel and the User Region.
+
+anchor:configuring-kernel-properties[]
+
+==== Configuring the Kernel
+
+To change any of the kernel properties, provide the new value to the startup script. The following table describes all properties.
+
+anchor:configuring-kernel-table[]
+[options="header",cols=",,"]
+.Kernel Configuration Properties
+|=======================================================================
+| Property (prefixed by `org.eclipse.virgo`) | Description | Default Value
+| `.kernel.home` | Specifies the location of the {kernel-product-name}. | `$SERVER_HOME`
+| `.kernel.config` | Specifies the location of the {kernel-product-name} and User Region xref:configuring-kernel-files[configuration files].
+ The location of the configuration files can also be specified using
+ xref:starting-stopping-configuration-directory[] `-configDir` startup parameter].
+ | `$SERVER_HOME/configuration`
+| `.kernel.domain` | Specifies the http://download.oracle.com/javase/6/docs/api/javax/management/ObjectName.html[JMX domain] that should be
+ used by the {kernel-product-name}. | `org.eclipse.virgo.kernel`
+| `.kernel.startup.wait.limit`
+ | Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel.
+ See xref:configuring-framework-properties[Configuring OSGi Framework Properties] for the recommended way
+ to configure this parameter. | `180`
+|=======================================================================
+
+anchor:configuring-kernel-files[]
+
+==== Configuration Files
+
+The configuration of the {kernel-product-name} and User Region by default is located in the `$SERVER_HOME/configuration` directory:
+
+anchor:configuring-kernel-files-table[]
+[options="header",cols=","]
+.Kernel Configuration Files
+|=======================================================================
+| Property File | Description
+| `org.eclipse.virgo.kernel.properties` | Configures xref:configuring-deployment[deployment].
+| `org.eclipse.virgo.kernel.userregion.properties` | Configures the xref:configuring-user-region[User Region] of {virgo-name}.
+| `org.eclipse.virgo.kernel.users.properties` | Configures the xref:configuring-authentication[users that are allowed to access] the Admin Console, and roles to which they map.
+| `org.eclipse.virgo.kernel.jmxremote.access.properties` | Configures the xref:configuring-authentication[permissions for users] that are allowed to access the Admin Console.
+| `org.eclipse.virgo.kernel.authentication.config` | Configures the xref:configuring-authentication[Java Authentication and Authorization Service (JAAS)] for the Tomcat server users.
+| `osgi.console.ssh.properties` | Configures the kernel SSH console. See xref:admin-shell-enable[].
+| `osgi.console.telnet.properties` | Configures the kernel telnet console. See xref:admin-shell-enable[].
+|=======================================================================
+
+anchor:configuring-deployment[]
+
+==== Configuring Deployment
+
+You can configure various properties of deployment: the pickup directory into which you copy applications for hot-deployment, the deployment timeout,
+and whether or not bundles are unpacked during deployment.
+
+To change any of these properties, edit the `deployer.XXX` properties of the `$SERVER_HOME/configuration/org.eclipse.virgo.kernel.properties` file. The following table describes these properties.
+
+anchor:configuring-deployment-table[]
+[options="header",cols=",,"]
+.Deployment Configuration Properties
+|=======================================================================
+| Property | Description | Default Value
+| `deployer.pickupDirectory` | Specifies the absolute or relative path to the pickup directory to which you copy applications for hot-deployment.
+ Relative paths are relative to `$SERVER_HOME`. | `./pickup`
+| `deployer.timeout` | Specifies the amount of time, in seconds, after which {virgo-name} times out while trying to deploy an artifact.
+ If you want to disable deployment timeout, specify `0`.
+ | `300`
+| `deployer.scanIntervalMillis` | Specifies the scan interval, in milliseconds, used to survey the pickup directory.
+ | `1000`
+| `deployer.unpackBundles` | Determines whether or not bundles (with file extension `.jar` or `.war`) are unpacked
+ during deployment. The value must be either `true` or `false`.
+
+ If you want to deploy bundles packed, specify `false`.
+ This option can help alleviate a known issue with xref:long-work-paths[long work directory paths under Windows].
+
+ Note that web applications may behave differently depending on whether they are deployed packed or unpacked.
+ Certain servlet API methods return `null` when a web application is deployed packed.
+ | `true`
+| `WABHeaders` | This kernel property is only relevant for {nanoweb-product-name}. For the corresponding property in {tomcat-product-name}, see xref:configuring-web[Configuring the Web Integration Layer].
+
+ Specifies how Web Application Bundle manifest headers are processed.
+ See "Web Application Manifest Processing" in the
+ {programmer-guide} for details.
+
+ A value of `strict` causes {nanoweb-product-name} to interpret certain headers in strict compliance with
+ the OSGi Web Applications specification if they are not specified.
+
+ A value of `defaulted` causes {nanoweb-product-name} to set certain headers to default values if they are not specified.
+ *This value is provided as a migration aid and may not be supported in future releases.*
+ | `strict`
+|=======================================================================
+
+The following listing displays the default configuration distributed with {virgo-name}; only relevant sections of the `org.eclipse.virgo.kernel.properties` file are shown.
+
+....
+deployer.timeout=300
+deployer.pickupDirectory=pickup
+deployer.scanIntervalMillis=1000
+....
+
+So the default deployment timeout is 300 seconds, the default pickup directory is `$SERVER_HOME/pickup` and the default scan interval is `1000`.
+
+anchor:configuring-user-region[]
+
+==== Configuring the User Region
+
+The User Region is the subsystem of {virgo-name} that
+supports deployed applications, both your own user applications and
+those of the server itself, such as the Admin Console. The User Region
+is deliberately isolated from the kernel, which protects the kernel from interference by applications.
+
+
+You configure the User Region by updating properties in the
+`$SERVER_HOME/configuration/org.eclipse.virgo.kernel.userregion.properties`
+file; these properties are described in the following table.
+
+[WARNING]
+--
+We strongly recommend that you update only the
+`initialArtifacts`
+property; updating other properties could cause
+{virgo-name} to fail. These properties are documented for your
+information.
+--
+
+anchor:configuring-user-region-table[]
+[options="header",cols=","]
+.User Region Configuration Properties
+|=======================================================================
+| Property | Description
+| `baseBundles` | Specifies the hard-coded list of bundles that {virgo-name} installs directly into the User Region.
+ {virgo-name} does not perform any automatic dependency satisfaction for these bundles; in other words, you only get the bundles
+ in the list and nothing more.
+| `bundleImports`
+ | Specifies the bundles in the kernel that {virgo-name} imports into the User Region so that they are visible to bundles in the User Region.
+ This property supports an optional `bundle-version` attribute which specifies a version range.
+ By default only the system bundle is imported.
+
+ Note that packages exported by these bundles are *not* automatically made available in the User Region: these must be specified using the
+ `packageImports` property.
+| `packageImports` | Specifies the packages in the kernel that {virgo-name} imports into the User Region so that they are in turn available to be
+ imported by bundles in the User Region.
+ This property supports a `.*` wildcard which is expanded based on the packages available in the kernel
+ when the User Region is created.
+ For example, `org.eclipse.virgo.util.*` will import all packages that start with
+ `org.eclipse.virgo.util.` (but *not* the package `org.eclipse.virgo.util`
+ which would need to be specified separately to be imported).
+
+ The property also supports matching attributes such as `version`, `bundle-symbolic-name`,
+ `bundle-version`, and user-defined attributes. This can be used to import all the packages of a bundle imported using the
+ `bundleImports` property.
+ For example the following imports all the packages of the system bundle:
+
+....
+packageImports=*;bundle-symbolic-name="org.eclipse.osgi",\
+...
+....
+ Note that if a package is specified more than once in `packageImports`, the last occurrence is used and the earlier
+ occurrences are ignored.
+ For this reason, it is recommended that imports specifying matching attributes are placed earlier in the list than other imports so that
+ if an import is specified with and without matching attributes, the form without the matching attributes is used.
+| `serviceImports` | Specifies the services in the kernel that are imported into the User Region so they are available to bundles in the User Region.
+| `serviceExports` | Specifies the services in the User Region that are exported to the kernel so they are available to bundles in the kernel.
+| `initialArtifacts` | Specifies the artifacts that {virgo-name} deploys into the User Region when the server starts.
+ {virgo-name} performs dependency satisfaction when it deploys these artifacts.
+ This means that you only need to list the top-level artifacts that you care about; {virgo-name} automatically installs,
+ from the repository, any other artifacts upon which they depend.
+
+ The artifacts are specified as a comma separated list of URI strings of the form:
+
+....
+repository:type/name[/version
+....
+
+ where `type` is the artifact type (e.g. "plan", "par", "bundle",
+ "configuration"), `name` is the (symbolic) name of the artifact, and, optionally,
+ `version` is the version of the artifact.
+ If `version` is omitted and there is at least one artifact in the repository with the given type and name, then the
+ artifact with the highest version is selected.
+ So, for example, the following entries are valid:
+....
+initialArtifacts=...,\
+ repository:plan/APlan,\
+ repository:bundle/ABundle/1.0
+....
+|=======================================================================
+
+anchor:configuring-user-region-consoles[]
+
+==== Configurating User Region Consoles
+
+The configuration of the User Region consoles is located by default in the `$SERVER_HOME/repository/ext` directory:
+
+anchor:configuring-user-region-consoles-table[]
+[options="header",cols=","]
+.User Region Console Configuration Files
+|=======================================================================
+| Property | Description
+| `osgi.console.ssh.properties` | Configures the User Region SSH console. See xref:admin-shell-enable[].
+| `osgi.console.telnet.properties` | Configures the User Region telnet console. See xref:admin-shell-enable[].
+|=======================================================================
+
+anchor:configuring-authentication[]
+
+=== Configuring Authentication
+
+{virgo-name} uses the http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html[Java Authentication and Authorization Service (JAAS)]
+framework to authenticate the administration user that connects to Web
+Servers using the Admin Console. This section describes
+how the authentication mechanism is configured by default, and the
+files that you need to update if you want to change the administration
+user, change their password, and so on.
+
+The `$SERVER_HOME/configuration/org.eclipse.virgo.kernel.authentication.config` file configures the underlying authentication technology for {virgo-name}. The short file consists of the following entries:
+
+....
+virgo-kernel {
+ org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
+};
+equinox_console {
+ org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
+};
+....
+
+The entry named `virgo-kernel` corresponds to the `<Realm>` element in the `$SERVER_HOME/configuration/tomcat-server.xml` file that configures the JAAS authentication mechanism for the `Catalina` service of the xref:configuring-tomcat[Tomcat servlet container]. The `virgo-kernel` entry specifies that the JAAS LoginModule that {virgo-name} uses to authenticate users is `org.eclipse.virgo.kernel.authentication.KernelLoginModule` and that this `KernelLoginModule` is required to "succeed" in order for authentication to be considered successful. The `KernelLoginModule` succeeds only if the name and password supplied by the user are the ones it expects. The default administration username/password pair for {tomcat-product-name-short} is `admin/springsource`.
+
+The entry named `equinox_console` controls ssh authentication for the Virgo shell. It also uses the `KernelLoginModule`.
+
+You configure the administration user in the `org.eclipse.virgo.kernel.users.properties` file. The default file for a freshly installed {virgo-name} is as follows:
+
+....
+##################
+# User definitions
+##################
+user.admin=springsource
+
+##################
+# Role definitions
+##################
+role.admin=admin
+....
+
+The administration user that connect to the Admin Console must have the
+`admin`
+role. The preceding file shows how, by default, the
+`admin`
+role is assigned the
+`admin`
+user with password
+`springsource`.
+
+If you want to change the administration user, update the `org.eclipse.virgo.kernel.users.properties` file. For example, if you want the `juliet` user, with password `supersecret`, to be the new adminstration user, update the file as shown:
+
+....
+##################
+# User definitions
+##################
+user.juliet=supersecret
+
+##################
+# Role definitions
+##################
+role.admin=juliet
+....
+
+Be sure to restart {virgo-name} after you make this change for it to take effect.
+
+The final file involved in {virgo-name} authentication is `$SERVER_HOME/configuration/org.eclipse.virgo.kernel.jmxremote.access.properties`. This file specifies the JMX access privileges that the administration user has; by default they are read and write, as shown in the following listing:
+
+....
+admin=readwrite
+....
+
+The only other value you can enter is
+`readonly`, which means that the adminstration user would only be able to *view*
+information using the Admin Console.
+
+anchor:configuring-tomcat[]
+
+=== Configuring the Embedded Tomcat Servlet Container
+
+[NOTE]
+--
+{nano-product-name} uses the default Gemini Web configuration. The details described below may still apply.
+--
+
+{virgo-name}
+embeds an OSGi-enhanced version of the http://tomcat.apache.org[Tomcat Servlet Container]
+in order to provide support for deploying Java EE WARs and OSGi *Web Application Bundles*.
+You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called <filename>tomcat-server.xml</filename> rather than `server.xml`. As with the other {virgo-name} configuration files, the `tomcat-server.xml` file is located in the `$SERVER_HOME/configuration` directory.
+Another difference is that not all standard Apache Tomcat configuration is supported in {tomcat-product-name}: the restrictions are described in the
+remainder of this section.
+
+Here's an extract of the default configuration distributed with the {tomcat-product-name-short}.
+
+[source,xml]
+---
+<?xml version='1.0' encoding='utf-8'?>
+<Server port="8005" shutdown="SHUTDOWN">
+ <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
+ <Listener className="org.apache.catalina.core.JasperListener" />
+ <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
+ <Listener className="org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener"/>
+ <Service name="Catalina">
+ <Connector port="8080" protocol="HTTP/1.1"
+ connectionTimeout="20000"
+ redirectPort="8443" />
+ <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
+ maxThreads="150" scheme="https" secure="true"
+ clientAuth="false" sslProtocol="TLS"
+ keystoreFile="configuration/keystore"
+ keystorePass="changeit"/>
+ <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
+ <Engine name="Catalina" defaultHost="localhost">
+ <Realm className="org.apache.catalina.realm.JAASRealm" appName="virgo-kernel"
+ userClassNames="org.eclipse.virgo.kernel.authentication.User"
+ roleClassNames="org.eclipse.virgo.kernel.authentication.Role"/>
+ <Host name="localhost" appBase="webapps"
+ unpackWARs="false" autoDeploy="false"
+ deployOnStartup="false" createDirs="false">
+ <Valve className="org.apache.catalina.valves.AccessLogValve" directory="serviceability/logs/access"
+ prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/>
+ <Valve className="org.eclipse.virgo.web.tomcat.ApplicationNameTrackingValve"/>
+ </Host>
+ </Engine>
+ </Service>
+</Server>
+----
+
+anchor:overview-tomcat-servlet-container[]
+
+==== Description of the Default Apache Tomcat Configuration
+
+The following bullets describe the main elements and attributes in the default `tomcat-server.xml` file; for details about updating this file to further configure the embedded Apache Tomcat server, see the http://tomcat.apache.org/tomcat-7.0-doc/config/index.html[Apache Tomcat Configuration Reference].
+
+[TIP]
+.Relative paths
+--
+If the configured path to a directory or file does not represent an absolute path, {virgo-name} typically interprets it as a path relative to the <filename>$SERVER_HOME</filename> directory.
+--
+
+* The root element of the `tomcat-server.xml` file is `<Server>`. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The `shutdown` attribute specifies the command string that the shutdown port number receives via a TCP/IP connection in order to shut down the servlet container. The `port` attribute specifies the TCP/IP port number that listens for a shutdown message.
+* The `<Listener>` XML elements specify the list of lifecycle listeners that monitor and manage the embedded Tomcat servlet container. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the servlet container and has been programmed to do something at certain lifecycle events of the component, such as before starting up, after stopping, and so on.
+ The first four `<Listener>` elements configure standard Tomcat lifecycle listeners. The listener implemented by the `org.eclipse.virgo.web.tomcat.ServerLifecycleLoggingListener` class is specific to {tomcat-product-name} and manages server lifecycle logging.
+* The `<Service>` XML element groups together one or more connectors and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to to send and receive messages to and from the associated service. There are many transports that a client can use, which is why a `<Service>` element can have many `<Connector>` elements. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the servlet container; you can define only a single `<Engine>` element for any given `<Service>` element.
+The sample `tomcat-server.xml` file above includes three `<Connector>` elements: one for the HTTP transport, one for the HTTPS transport, and one for the AJP transport. The file also includes a single `<Engine>` element, as required.
+* The first connector listens for HTTP requests at the `8080` TCP/IP port. The connector, after accepting a connection from a client, waits for a maximum of 20000 milliseconds for a request URI; if it does not receive one from the client by then, the connector times out. If this connector receives a request from the client that requires the SSL transport, the servlet container automatically redirects the request to port `8443`.
+* The second connector is for HTTPS requests. The TCP/IP port that users specify as the secure connection port is `8443`. Be sure that you set the value of the `redirectPort` attribute of your non-SSL connectors to this value to ensure that users that require a secure connection are redirected to the secure port, even if they initially start at the non-secure port. The `SSLEnabled` attribute specifies that SSL is enabled for this connector. The `secure` attribute ensures that a call to `request.isSecure()` from the connecting client always returns `true`. The `scheme` attribute ensures that a call to `request.getScheme()` from the connecting client always returns `https` when clients use this connector.
+The `maxThreads` attribute specifies that the servlet container creates a maximum of 150 request processing threads,
+which determines the maximum number of simultaneous requests that can be handled.
+The `clientAuth` attribute specifies that the servlet container does not require a certificate chain
+unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication.
+The `keystoreFile` attribute specifies the name of the file that contains the servlet container's
+private key and public certificate used in the SSL handshake, encryption, and decryption.
+You use an alias and password to access this information.
+In the example, this file is `$SERVER_HOME/configuration/keystore`.
+The `keystorePass` attributes specify the password used to access the keystore.
+* The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.
+* The engine has a logical name of `Catalina`;
+this is the name used in all log and error messages so you can easily identify problems.
+The value of the `defaultHost` attribute refers to the name of a `<Host>`
+child element of `<Engine>`;
+this host processes requests directed to host names on this servlet container.
+* The `<Realm>` child element of `<Engine>` represents a database of
+users, passwords, and mapped roles used for authentication in this service. Virgo Web Server uses an implementation of the Tomcat 6 Realm interface that authenticates users through the Java Authentication and Authorization Service (JAAS) framework which is provided as part of the standard J2SE API.
+With the JAASRealm, you can combine practically any conceivable security realm with Tomcat's container managed authentication. For details, see http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html[Realm Configuration].
+* The `<Host>` child element represents a virtual host,
+which is an association of a network name for a server (such as `www.mycompany.com`) with the particular
+server on which Catalina is running.
+The servlet container unpacks Web applications into a directory hierarchy if they are deployed as WAR files.
+Note that multiple `<Host>` elements are not supported in {tomcat-product-name}.
+* Finally, the `org.apache.catalina.valves.AccessLogValve` valve creates log files
+in the same format as those created by standard web servers.
+The servlet container creates the log files in the `$SERVER_HOME/serviceability/logs/access` directory.
+The log files are prefixed with the string `localhost_access_log.`, have a suffix of `.txt`,
+use a standard format for identifying what should be logged, and do not include DNS lookups of the IP address of the remote host.
+
+anchor:configuring-tomcat-connectors[]
+
+==== Connector Configuration
+The {tomcat-product-name} supports the configuration of any connector supported by Apache Tomcat.
+See the default configuration above for syntax examples, and for further details of the configuration properties
+supported for various `<Connector>` implementations,
+consult the official http://tomcat.apache.org/tomcat-7.0-doc/config/http.html[Tomcat HTTP Connector] documentation.
+
+[TIP]
+.Configuring SSL for Tomcat
+--
+The {tomcat-product-name} distribution includes a preconfigured `$SERVER_HOME/configuration/keystore`
+file that contains a single self-signed SSL Certificate.
+The password for this <filename>keystore</filename> file is `changeit`.
+This <filename>keystore</filename> file is intended for testing purposes only.
+For detailed instructions on how to configure Tomcat's SSL support,
+consult the official http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html[Tomcat SSL Configuration HOW-TO].
+--
+
+anchor:configuring-tomcat-clustering[]
+
+==== Cluster Configuration
+
+{tomcat-product-name} supports standard Apache Tomcat cluster configuration.
+By default, clustering of the embedded servlet container is disabled,
+and the default configuration does not include any clustering information.
+See http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html[Tomcat Clustering/Session Replication HOW-TO]
+for detailed information about enabling and configuring clustering.
+
+anchor:configuring-default-web-xml[]
+
+==== Default web.xml Configuration
+
+Java Servlet specification enables web applications to provide deployment descriptor (`web.xml`) in the `WEB-INF` directory.
+Apache Tomcat introduces a default `web.xml` which is similar to web application's `web.xml`, but provides configurations that are applied to all web applications.
+When deploying a web application, Apache Tomcat uses the default `web.xml` file as a base configuration.
+If the web application provides its own configurations via `web.xml` (the one located in the web application's `WEB-INF`) or annotations, they overwrite the default ones.
+In {tomcat-product-name} you can also provide default configurations for all web applications.
+If you want to change/extend the default configurations, you can provide the default `web.xml` file located in the `{tomcat-product-name-short}_HOME/configuration` directory.
+
+[TIP]
+--
+Be careful when changing/extending the default `web.xml` as this will affect all web applications.
+--
+
+Here's an extract of the default configuration distributed with the {tomcat-product-name-short}.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
+ version="3.0">
+
+ <servlet>
+ <servlet-name>default</servlet-name>
+ <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
+ <init-param>
+ <param-name>debug</param-name>
+ <param-value>0</param-value>
+ </init-param>
+ <init-param>
+ <param-name>listings</param-name>
+ <param-value>false</param-value>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet>
+ <servlet-name>jsp</servlet-name>
+ <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
+ <init-param>
+ <param-name>fork</param-name>
+ <param-value>false</param-value>
+ </init-param>
+ <init-param>
+ <param-name>xpoweredBy</param-name>
+ <param-value>false</param-value>
+ </init-param>
+ <load-on-startup>3</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>default</servlet-name>
+ <url-pattern>/</url-pattern>
+ </servlet-mapping>
+
+ <servlet-mapping>
+ <servlet-name>jsp</servlet-name>
+ <url-pattern>*.jsp</url-pattern>
+ </servlet-mapping>
+
+ <servlet-mapping>
+ <servlet-name>jsp</servlet-name>
+ <url-pattern>*.jspx</url-pattern>
+ </servlet-mapping>
+
+ <session-config>
+ <session-timeout>30</session-timeout>
+ </session-config>
+
+ <mime-mapping>
+ <extension>abs</extension>
+ <mime-type>audio/x-mpeg</mime-type>
+ </mime-mapping>
+ ......
+ <mime-mapping>
+ <extension>ppt</extension>
+ <mime-type>application/vnd.ms-powerpoint</mime-type>
+ </mime-mapping>
+
+ <welcome-file-list>
+ <welcome-file>index.html</welcome-file>
+ <welcome-file>index.htm</welcome-file>
+ <welcome-file>index.jsp</welcome-file>
+ </welcome-file-list>
+
+</web-app>
+----
+
+The following bullets describe the main elements in the default `web.xml` file.
+
+* The `<Servlet>` XML element declares a given servlet and its configurations. The sample `web.xml` file above includes two <Servlet> elements.
+The default servlet serves static resources and processes the requests that are not mapped to any servlet.
+For details about default servlet configuration, see the http://tomcat.apache.org/tomcat-7.0-doc/default-servlet.html[Apache Tomcat Default Servlet Reference.].
+
+* The jsp servlet serves the requests to JavaServer Pages. It is mapped to the URL pattern "*.jsp" and "*.jspx".
+For details about jsp servlet configuration, see the http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html[Apache Tomcat Jasper 2 JSP Engine.].
+* The `<servlet-mapping>` XML element specifies the mapping between the servlet and URL pattern.
+* The `<session-config>` XML element defines the session configuration for one web application.
+The sample `web.xml` file above specifies that the session timeout for all web applications will be 30 minutes by default.
+* The `<mime-mapping>` XML element defines a mapping between a filename extension and a mime type.
+When serving static resources, a "Content-Type" header will be generated based on these mappings.
+* The `<welcome-file-list>` XML element specifies a list of welcome files.
+When a request URI refers to a directory, the default servlet looks for a "welcome file" within that directory.
+If the "welcome file" exists it will be served, otherwise 404 status or directory listing will be returned, depending on the default servlet configuration.
+
+anchor:configuring-tomcat-contexts[]
+
+==== Context Configuration
+
+{tomcat-product-name} supports standard Apache Tomcat web application context configuration.
+The http://tomcat.apache.org/tomcat-7.0-doc/config/index.html[Apache Tomcat Configuration Reference] has a section on
+http://tomcat.apache.org/tomcat-7.0-doc/config/context.html[The Context Container] which describes the mechanism that
+is used in {tomcat-product-name-short} for searching context configuration files and details the context configuration properties.
+
+Context configuration files may be placed in the following locations,
+where `[enginename]` is the name of Tomcat's engine ('Catalina' by default) and `[hostname]` names
+a virtual host ('localhost' by default), both of which are configured in `tomcat-server.xml`:
+
+* `$SERVER_HOME/configuration/context.xml` provides the default context configuration file for all web applications.
+* The `$SERVER_HOME/configuration/[enginename]/[hostname]` directory may contain:
+** The default context configuration for all web applications of a given virtual host in the file `context.xml.default`.
+** Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference.
+For example, the context for a web application with
+context path `foo` may be configured in `foo.xml`.
+
+Note that the following context configuration features are not supported in {tomcat-product-name}:
+
+* Custom class loaders.
+* Specifying the context path. This is specified using the `Web-ContextPath` header in the web application's
+`MANIFEST.MF` file.
+* Specifying the document base directory.
+
+anchor:configuring-jsp-compilation[]
+
+==== JSP Compilation
+
+By default Apache Tomcat compiles JSP files in web applications agains Java 1.6.
+In order to enable JSP compilation against Java 1.7 for your web application,
+additional init parameters (`compilerSourceVM` and `compilerTargetVM`) should be added for the `org.apache.jasper.servlet.JspServlet` configuration.
+For details about `org.apache.jasper.servlet.JspServlet` configuration, see the http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html[Apache Tomcat Jasper 2 JSP Engine].
+`org.apache.jasper.servlet.JspServlet` configuration can be provided with the web application's web.xml.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<servlet>
+ <servlet-name>jsp</servlet-name>
+ <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
+ <init-param>
+ <param-name>compilerSourceVM</param-name>
+ <param-value>1.7</param-value>
+ </init-param>
+ <init-param>
+ <param-name>compilerTargetVM</param-name>
+ <param-value>1.7</param-value>
+ </init-param>
+ <init-param>
+ <param-name>fork</param-name>
+ <param-value>false</param-value>
+ </init-param>
+ <init-param>
+ <param-name>xpoweredBy</param-name>
+ <param-value>false</param-value>
+ </init-param>
+ <load-on-startup>3</load-on-startup>
+</servlet>
+<servlet-mapping>
+ <servlet-name>jsp</servlet-name>
+ <url-pattern>*.jsp</url-pattern>
+ <url-pattern>*.jspx</url-pattern>
+ </servlet-mapping>
+----
+
+anchor:configuring-web[]
+
+=== Configuring the Web Integration Layer
+
+{tomcat-product-name} integrates an OSGi-enhanced version of the http://tomcat.apache.org/[Tomcat Servlet Container]
+in order to provide support for deploying Java EE WARs and OSGi *Web Application Bundles*.
+
+For {tomcat-product-name} you
+configure the behaviour of the Web Integration Layer using the properties file called `org.eclipse.virgo.web.properties`.
+The `org.eclipse.virgo.web.properties` file is located in the `$SERVER_HOME/repository/ext` directory.
+
+The following table describes the properties.
+
+anchor:configuring-web-integration-layer[]
+[options="header",cols="1,3,1"]
+.Web Integration Layer Properties
+|=======================================================================
+| Property | Description | Default Value
+| `WABHeaders` | Specifies how Web Application Bundle manifest headers are processed.
+ See "Web Application Manifest Processing" in the
+ {programmer-guide} for details.
+
+ A value of `strict` causes {tomcat-product-name-short} to interpret certain headers in strict compliance with
+ the OSGi Web Applications specification if they are not specified.
+
+ A value of `defaulted` causes {tomcat-product-name-short} to set certain headers to default values if they are not specified.
+ This was how {tomcat-product-name-short} behaved prior to version 3.
+ *This value is provided as a migration aid and may not be supported in future releases.*
+ A warning event log message (WE0006W) is generated if this value is specified.
+
+ The {jetty-product-name} will always operate in `strict` mode.
+
+ {nanoweb-product-name} does not have a Web Integration Layer, but has a corresponding kernel property.
+ See xref:configuring-deployment[Configuring Deployment].
+ | `strict`
+|=======================================================================
+
+There is no Web Integration Layer in {jetty-product-name}. The relevant configuration is described in
+xref:configuring-jetty[Configuring the Embedded Jetty Servlet Container].
+
+anchor:configuring-jetty[]
+
+=== Configuring the Embedded Jetty Servlet Container
+
+{jetty-product-name} supports *Web Application Bundles*, but does not provide support for Java EE WARs.
+
+
+The {jetty-product-name} contains a standard Jetty configuration file at `SERVER_HOME/jetty/etc/jetty.xml`.
+This has been tailored to the {umbrella-virgo-name}. To make modifications please refer to the
+http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty#Using_Jetty_XML[Jetty documentation].
+
diff --git a/user-guide/src/docs/asciidoc/further-reading.adoc b/user-guide/src/docs/asciidoc/further-reading.adoc
new file mode 100644
index 0000000..74a7d91
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/further-reading.adoc
@@ -0,0 +1,37 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:programmer-guide: link:../../virgo-programmer-guide/html/index.html[Programmer Guide]
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:furtherreading[Further Reading]
+
+== Further Reading
+
+{programmer-guide}
+
+http://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/[Spring Framework Reference Documentation]
+
+http://www.osgi.org/Specifications/HomePage[Blueprint Container Specification](in the OSGi 4.2 and 5.0 Enterprise Specifications)
+
+http://logback.qos.ch/manual[The Logback Manual]
+
diff --git a/user-guide/src/docs/asciidoc/installing-kernel.adoc b/user-guide/src/docs/asciidoc/installing-kernel.adoc
new file mode 100644
index 0000000..0ebf78e
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/installing-kernel.adoc
@@ -0,0 +1,94 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:kernel-installation[]
+
+== Installing {kernel-product-name}
+
+anchor:kernel-installation-prereqs[]
+
+=== Prerequisites
+
+The {kernel-product-name}, or {kernel-product-name-short} for short, requires Java SE 6 or later to be installed. Java is available from
+http://www.java.com/[http://www.java.com/] and elsewhere.
+
+anchor:kernel-installation-zip
+
+=== Installing from the ZIP Download
+
+==== Downloading the ZIP file
+
+{kernel-product-name} is distributed as a ZIP file. This can be downloaded from
+http://www.eclipse.org/virgo/download/[here].
+
+anchor:kernel-installation-zip-installing
+
+==== Installing
+
+anchor:kernel-installation-zip-installing-linux[]
+
+===== Linux
+
+To install the {kernel-product-name} on Linux, unzip the distribution package to the desired installation directory.
+For example, to install into `/opt`:
+
+....
+$ unzip virgo-kernel-{version}.zip -d /opt
+....
+
+This creates a directory called `virgo-kernel-{version}` under `/opt`.
+
+{kernel-product-name} requires write access to the installation directory, in this case `/opt/virgo-kernel-{version}`.
+Typically this means it must be run as the user that installed it, or the installation directory's ownership must be changed.
+
+anchor:kernel-installation-zip-installing-win[]
+
+===== Microsoft Windows
+
+To install the {kernel-product-name} on Windows, unzip the distribution package to the desired installation directory.
+You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
+Java have some issues with long file names and file paths, so we recommend installing to the root directory of
+your chosen drive.
+
+anchor:kernel-installation-updatesite[]
+
+=== Installing from an update site
+
+==== The repository location
+
+Virgo has a single p2 repository that contains all Virgo distributions. The repository for version {version} can be found {p2repo}[here].
+There is a repository for each released version.
+
+==== Using the p2 director
+
+As shown in xref:using-director[] you can easily install {kernel-product-name-short} in a desired destination.
+The only director argument that needs to be adjusted is *-installIU*.
+
+For {kernel-product-name-short} the right value is *kernel.product*.
+
+anchor:kernel-installation-post[]
+
+=== Post-installation steps
+Follow the same xref:installation-post[Post-installation steps] as for {tomcat-product-name}.
+
diff --git a/user-guide/src/docs/asciidoc/installing-nano.adoc b/user-guide/src/docs/asciidoc/installing-nano.adoc
new file mode 100644
index 0000000..f75c918
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/installing-nano.adoc
@@ -0,0 +1,94 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:nano-installation[]
+
+== Installing {nano-product-name}
+
+anchor:nano-installation-prereqs[]
+
+=== Prerequisites
+
+The {nano-product-name}, or {nano-product-name-short} for short, requires Java SE 6 or later to be installed. Java is available from
+http://www.java.com/[http://www.java.com/] and elsewhere.
+
+anchor:nano-installation-zip[]
+
+=== Installing from the ZIP Download
+
+==== Downloading the ZIP file
+
+{nano-product-name} is distributed as a ZIP file. This can be downloaded from
+http://www.eclipse.org/virgo/download/[here].
+
+anchor:nano-installation-zip-installing[]
+
+==== Installing
+
+anchor:nano-installation-zip-installing-linux[]
+
+===== Linux
+
+To install the {nano-product-name} on Linux, unzip the distribution package to the desired installation directory.
+For example, to install into `/opt`:
+
+....
+$ unzip virgo-nano-{version}.zip -d /opt
+....
+
+This creates a directory called `virgo-nano-{version}` under `/opt`.
+
+{nano-product-name} requires write access to the installation directory, in this case `/opt/virgo-nano-{version}`.
+Typically this means it must be run as the user that installed it, or the installation directory's ownership must be changed.
+
+anchor:nano-installation-zip-installing-win[]
+
+===== Microsoft Windows
+
+To install the {nano-product-name} on Windows, unzip the distribution package to the desired installation directory.
+You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
+Java have some issues with long file names and file paths, so we recommend installing to the root directory of
+your chosen drive.
+
+anchor:nano-installation-updatesite[]
+
+=== Installing from an update site
+
+==== The repository location
+
+Virgo has a single p2 repository that contains all Virgo distributions. The repository for version {version} can be found {p2repo}[here].
+There is a repository for each released version.
+
+==== Using the p2 director
+
+As shown in xref:using-director[] you can easily install {nano-product-name-short} in a desired destination.
+The only director argument that needs to be adjusted is *-installIU*.
+
+For {nano-product-name-short} the right value is *nano.product*.
+
+anchor:nano-installation-post[]
+
+=== Post-installation steps
+Follow the same xref:installation-post[Post-installation steps] as for {tomcat-product-name}.
+
diff --git a/user-guide/src/docs/asciidoc/installing.adoc b/user-guide/src/docs/asciidoc/installing.adoc
new file mode 100644
index 0000000..0ef7898
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/installing.adoc
@@ -0,0 +1,199 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:installation[]
+
+== Installing {tomcat-product-name}
+
+anchor:installation-prereqs[]
+
+=== Prerequisites
+
+The {tomcat-product-name}, or {tomcat-product-name-short} for short, requires Java SE 6 or later to be installed. Java is available from
+http://www.java.com/[http://www.java.com/] and elsewhere.
+
+In case you are installing via a p2 director you'll need to get it. The easiest way is to download Eclipse from http://www.eclipse.org/downloads/[here].
+It has built-in p2 director and other p2 applications.
+
+anchor:installation-zip[]
+
+=== Installing from the ZIP Download
+
+==== Downloading the ZIP file
+
+{tomcat-product-name} is distributed as a ZIP file. This can be downloaded from
+http://www.eclipse.org/virgo/download/[here].
+
+anchor:installation-zip-installing[]
+
+==== Installing
+
+anchor:installation-zip-installing-linux[]
+
+===== Linux
+
+To install {tomcat-product-name} on Linux, unzip the distribution package to the desired installation directory.
+For example, to install into `/opt`:
+
+....
+$ unzip virgo-web-server-{version}.zip -d /opt
+....
+
+This creates a directory called `virgo-web-server-{version}` under `/opt`.
+
+{tomcat-product-name} requires write access to the installation directory, in this case `/opt/virgo-web-server-{version}`.
+Typically this means it must be run as the user that installed it, or the installation directory's ownership must be changed.
+
+anchor:installation-zip-installing-win[]
+
+===== Microsoft Windows
+
+To install the {tomcat-product-name} on Windows, unzip the distribution package to the desired installation directory.
+You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
+Java have some issues with long file names and file paths, so we recommend installing to the root directory of
+your chosen drive.
+
+anchor:installation-updatesite[]
+
+=== Installing from an update site
+
+==== The repository location
+
+Virgo has a single p2 repository that contains all Virgo distributions. The repository for version {version} can be found {p2repo}[here].
+There is a repository for each released version.
+
+==== Using the p2 director
+
+As shown in xref:using-director[] you can easily install {tomcat-product-name-short} in a desired destination.
+The only director argument that needs to be adjusted is *-installIU*.
+
+For {tomcat-product-name-short} the right value is *tomcat-server.product*.
+
+anchor:installation-post[]
+
+=== Post-installation steps
+
+anchor:installation-post-env[]
+
+==== Set environment variable variables
+
+anchor:installation-post-env-java[]
+
+===== JAVA_HOME
+
+{tomcat-product-name} uses the `JAVA_HOME` environment variable to locate the `java`
+executable. Configure this environment variable to point to the home directory of the Java 6 installation on your computer.
+
+anchor:installation-post-env-server[]
+
+===== SERVER_HOME
+
+As a convenience it is recommended that you create an environment variable that points
+to the {tomcat-product-name} installation directory. Note that the {tomcat-product-name} does not require that
+such an environment variable has been set. This variable may have any name of your
+choosing. The {tomcat-product-name}'s documentation assumes that the variable is named
+`SERVER_HOME`.
+
+anchor:installation-post-env-server-linux[]
+
+==== Linux
+
+Edit the `.profile` file in your home directory to
+add the `SERVER_HOME` and `JAVA_HOME` environment variables. For
+example, if you installed into `/opt`:
+
+....
+$ export SERVER_HOME=/opt/virgo-web-server-{version}/
+$ export JAVA_HOME=/user/java/jdk1.6.0_17
+$ export PATH=$JAVA_HOME/bin:$PATH
+....
+
+To verify the setting of `JAVA_HOME`, issue the command `$JAVA_HOME/bin/java -version` from a new terminal window
+and ensure that the command completes successfully and reports
+a Java version `1.6.`*x* (denoting Java 6) or greater.
+
+anchor:installation-post-env-server-win[]
+
+==== Microsoft Windows
+
+This section shows how to add `SERVER_HOME` as a system variable on Windows. Follow the same procedure to add or update the `JAVA_HOME` environment variable.
+
+From the Start menu, open the Control Panel and double-click on ‘System'.
+
+image:system-props.png[]
+
+Click the 'Advanced' tab and select 'Environment Variables'. Next,
+click the 'New' button in the 'System Variables' section.
+
+image:env-variables.png[]
+
+This will display the ‘New System Variable' window. Enter
+`SERVER_HOME` as the ‘Variable name' and
+the installation directory as the ‘Variable value'. Click OK.
+
+image:system-variable.png[]
+
+To verify the setting of `JAVA_HOME`, issue the command `"%JAVA_HOME%"\bin\java -version` from
+a new command prompt and ensure that the command completes successfully and reports
+a Java version `1.6.`*x* (denoting Java 6) or greater.
+
+anchor:installation-post-env-server-win-troubleshooting[]
+
+===== Microsoft Windows - Troubleshooting Security Permissions
+
+When starting {tomcat-product-name} on some variants of Windows you might encounter a problem with file permissions.
+The error looks like this.
+
+....
+WARNING: jmxPermissions.vbs did not update the permissions of C:\virgo\configuration\org.eclipse.virgo.kernel.jmxremote.access.properties. Check the file has the correct permissions.</screen>
+....
+
+If {tomcat-product-name-short} starts correctly (see xref:starting-stopping[]) you can skip this section and carry on. However to secure your
+installation you have to set correct permissions. To do so, go to the ‘configuration' directory of the installation
+in Windows Explorer.
+
+image:install-windows-1-FileListing.png[]
+
+Right click on the 'org.eclipse.virgo.kernel.jmxremote.access.properties' file and view its properties,
+then select the 'Security' tab. Remove all groups and users from the list and select 'Apply'.
+
+image:install-windows-2-SecuritySettings.png[]
+
+Within the security page select the ‘Advanced' options. On the ‘Owner' tab, choose the owner
+that you are trying to run the {tomcat-product-name-short} as and select ‘Apply'.
+
+image:install-windows-3-AdvanceSettingsOwner.png[]
+
+Once this is done select ‘OK' to return to the ‘Security' tab
+and now add the owner to the list of groups and users that have permission to access the file.
+
+image:install-windows-4-AllSetReadAndExecute.png[]
+
+Once all these steps are complete you can proceed to start the {tomcat-product-name-short}.
+
+....
+C:\dev\virgo-web-server-{version}>bin\startup.bat
+[2009-12-08 13:09:09.545] startup-tracker <KE0001I> Kernel starting.
+....
+
diff --git a/user-guide/src/docs/asciidoc/introduction.adoc b/user-guide/src/docs/asciidoc/introduction.adoc
new file mode 100644
index 0000000..a1020c6
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/introduction.adoc
@@ -0,0 +1,53 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:introduction[]
+
+== Introduction
+
+This User Guide covers the {tomcat-product-name} ({tomcat-product-name-short}), the {jetty-product-name}
+({jetty-product-name-short}) and the {kernel-product-name} ({kernel-product-name-short}), although it emphasises the
+{tomcat-product-name-short} since that is likely to apply to more users.
+
+
+=== A Note for {kernel-product-name} Users
+
+{kernel-product-name} users can be reassured that the majority of the information
+in this Guide is directly applicable to the {kernel-product-name} and they can simply ignore the web-related sections.
+
+=== A Note for {jetty-product-name} Users
+
+{jetty-product-name} users can be reassured that the majority of the information
+in this Guide is directly applicable to the {jetty-product-name} and they can simply ignore the {tomcat-product-name} specific sections.
+
+=== A Note for {nano-product-name} Users
+
+{nano-product-name} is a bit different than {kernel-product-name-short} and {tomcat-product-name-short}.
+It is the smallest Virgo offering and takes performance to its limits, almost instantly booting up.
+{nano-product-name} users will find a number of sections in this guide useful but sections that refer to
+*plans, PARs and configuration deployment, regions, application scoping and libraries support*
+are NOT relevant for {nano-product-name} or {nano-product-name-short} and should be ignored.
+This Virgo distribution relies on p2 for its provisioning, therefore is bound to p2 concepts such as *p2 features and update sites*.
+Note also that {nano-product-name} includes Gemini.Web as its default web container implementation and uses its default configuration.
+
diff --git a/user-guide/src/docs/asciidoc/known-issues.adoc b/user-guide/src/docs/asciidoc/known-issues.adoc
new file mode 100644
index 0000000..432fb55
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/known-issues.adoc
@@ -0,0 +1,105 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:known-issues[]
+
+== Known Issues
+
+This section describes known issues that you might run into, along with corresponding workarounds.
+
+For the full list of known issues, see https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;order=Importance;classification=RT;product=Virgo[Virgo bugs in Eclipse Bugzilla].
+The bugs are organised by component as well as by release.
+You can also use bugzilla to enter a new issue if you cannot find an existing issue that describes the problem you are running into, but it's probably worth asking on the http://www.eclipse.org/forums/index.php?t=thread&frm_id=159[Virgo community forum] first.
+
+anchor:known-issues-firewall-timeout[]
+
+=== Timeout During Startup Due to Firewall Settings
+
+{virgo-name} will fail to start correctly if it is prevented from
+connecting to needed ports by the firewall. Typically this manifests
+as error `SPPM0003E` . Configuring the firewall to
+allow {virgo-name} process to bind to the necessary ports will prevent
+this error from occurring.
+
+anchor:known-issues-startup-timeout[]
+
+=== Timeout During Startup Due to Insufficient Resources
+
+{virgo-name} will fail to start correctly if it is running on slow hardware or
+on a system with insufficient resources. Typically this manifests as error `KE0004E` .
+Configuring the xref:configuring-kernel-properties[startup wait limit] will provide
+{virgo-name} with more time for initialisation.
+
+anchor:known-issues-perm-gen-sun-vm[]
+
+=== OutOfMemoryError: PermGen Space Running on Sun JVM
+
+As a result of Sun Java bug
+http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4957990[4957990],
+the {virgo-name} may consume more PermGen space than expected when running with the
+server HotSpot compiler. This problem may be resolved by configuring the
+`JAVA_OPTS` environment variable to specify an increased
+`MaxPermSize`, for example `-XX:MaxPermSize=128M`.
+
+anchor:alternate-serviceability-work[]
+
+=== Alternate `serviceability` and `work` Directories
+
+Although an alternate `configuration` directory may be specified on startup, there is no way to specify
+alternate `serviceability` or `work` directories. This is covered by
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=307737[bug 307737] which also describes a workaround.
+
+anchor:windows-deletion[]
+
+=== Problem Deleting Installation Directory under Windows
+
+Sometimes Microsoft Windows won't let you delete the {virgo-name} Server installation directory, typically because of long paths
+inside the `work` directory.
+
+You can return the {virgo-name} instance to a clean state by stopping {virgo-name} if necessary and then running the startup script with the options
+`-clean -noStart`, after which you should be able to delete the installation directory.
+See xref:cleaning-without-starting[Cleaning {tomcat-product-name} without Starting it] for more information.
+
+anchor:long-work-paths[]
+
+=== Long Work Directory Paths under Windows
+
+Problems can arise under Windows when long paths are created in the `work` directory as artefacts are deployed.
+
+You can shorten some of these paths by preventing bundles from being unpacked during deployment.
+See xref:configuring-deployment[Configuring Deployment] for more information.
+
+anchor:known-issues-jetty-restrictions[]
+
+=== {jetty-product-name} Restrictions
+
+When using the {jetty-product-name} the Hosted Repository application and the Snaps modular web technology are not supported.
+
+anchor:known-issues-shutdown-logs-shell[]
+
+=== Shutdown Log Messages in Telnet Shell
+
+When you use the `shutdown` shell command to stop Virgo Server for Apache Tomcat, the shutdown log messages appear in the shell terminal instead of in the terminal in which Virgo runs.
+See xref:admin-shell-enable[Enabling Equinox Console] for more information. This is covered also by https://bugs.eclipse.org/bugs/show_bug.cgi?id=351533[bug 351533].
+
diff --git a/user-guide/src/docs/asciidoc/log-codes.adoc b/user-guide/src/docs/asciidoc/log-codes.adoc
new file mode 100644
index 0000000..7004eba
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/log-codes.adoc
@@ -0,0 +1,75 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:log-codes[]
+
+== Event log codes
+
+anchor:event-log-codes-format[]
+
+=== Format of the event log codes
+
+Event log codes issued by {virgo-name} have the general syntax
+`<XXnnnnL>` where:
+
+[cols="1,6"]
+|=======================================================================
+| `XX` | is a two-letter code (upper-case) identifying the area of the {virgo-name} code which issued the log message;
+| `nnnn` | is a four-digit message number; and
+| `L` | is a single-letter (upper-case) code identifying the level of the message.
+|=======================================================================
+
+The two-letter codes are (this list is not complete):
+
+[cols="1,6"]
+|=======================================================================
+| `AG` | `org.eclipse.virgo.kernel.agent.dm`
+| `DE` | `org.eclipse.virgo.kernel.deployer.core`
+| `HD` | `org.eclipse.virgo.kernel.deployer.hot`
+| `HR` | `org.eclipse.virgo.apps.repository.core`
+| `KE` | `org.eclipse.virgo.kernel.core`
+| `KS` | `org.eclipse.virgo.kernel.services`
+| `OF` | `org.eclipse.virgo.kernel.osgi`
+| `RP` | `org.eclipse.virgo.repository`
+| `TC` | `org.eclipse.virgo.web.tomcat`
+| `UR` | `org.eclipse.virgo.kernel.userregion`
+| `WE` | `org.eclipse.virgo.web.core`
+|=======================================================================
+
+The four-digit numbers identify the message text (with placeholders for inserted values). These are not listed here, but can be discovered by examining the files called
+`EventLogMessages.properties`, found in the relevant packages.
+
+The single-digit level code is one of:
+
+[cols="1,6"]
+|=======================================================================
+| `E` | Error level: enabled if level is `ERROR`.
+| `W` | Warning level: enabled if level is `WARNING` or above.
+| `I` | Info level: enabled if level is `INFO` or above.
+| `D` | Debug level: enabled if level is `DEBUG` or above.
+| `T` | Trace level: always enabled.
+|=======================================================================
+
+There are never two messages with the same prefix and number, but with different levels.
+
diff --git a/user-guide/src/docs/asciidoc/repository.adoc b/user-guide/src/docs/asciidoc/repository.adoc
new file mode 100644
index 0000000..86782fa
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/repository.adoc
@@ -0,0 +1,114 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:repository[]
+
+== The Provisioning Repository
+
+anchor:repository-introduction[]
+
+=== Overview of the Provisioning Repository
+
+This section describes the provisioning repository feature of {virgo-name}, the reasons for using it, and how to configure it.
+
+[NOTE]
+--
+This section is not applicable to {nano-product-name}. The provisioning mechanism used there is p2.
+--
+
+In most use cases, your application has a dependency on one or more separate artifacts; these artifacts might include OSGi bundles, configuration artifacts, third-party libraries, PARs or plans. A typical example is a Spring application that depends on a third-party library such as Spring Framework or Hibernate.
+
+The way you express this dependency depends on the artifact. For example, a plan is by definition a list of dependent bundles.
+
+Libraries are another example. Some third-party dependencies consist of multiple bundles but are logically one unit. To support this, {virgo-name} has a concept of a library. A library is a collection of related bundles that can be referenced as a whole. You typically express the dependencies between your application and third-party libraries using the `Import-Package`, `Import-Bundle`, or `Import-Library` manifest header in the `MANIFEST.MF` file of your application. The `Import-Package` header is standard to OSGi; `Import-Bundle` and `Import-Library`, however, are specific to {virgo-name}.
+
+For additional details about the creation and usage of libraries, as well as general information about dependencies, see {programer-guide}.
+
+In {virgo-name}, you store all third-party dependencies required by your applications, such as Spring Framework and Hibernate, as artifacts in the provisioning repository. As mentioned above, you can store the following types of artifacts in the repository:
+
+* OSGi bundles
+* Libraries
+* PARs
+* Plans
+* Configuration Artifacts
+
+When you deploy your application, {virgo-name} installs the bundle(s) comprising the application to the {virgo-name} runtime; part of this internal installation procedure is to satisfy all the application's dependencies. If your application has a dependency that cannot be satisfied from the bundles that you have already deployed (and {virgo-name} has thus installed), then {virgo-name} searches the provisioning repository for an artifact that can satisfy that dependency.
+
+The provisioning repository for a particular instance of {virgo-name} can include artifacts in the following general locations:
+
+* Local: This means that artifacts have been physically installed in the provisioning repository directory structure of the local {virgo-name} instance. The artifacts in a local repository include installed third-party libraries, bundles supplied by {virgo-name}, bundles supplied by an end user, and internal bundles used only by {virgo-name}. You can further categorize this location into `external` directories that adhere to a specified search pattern and are scanned by {virgo-name} just on a clean startup, or `watched` directories that point to a single directory location and which {virgo-name} scans on a regular basis.
+* Remote: This means that a local instance of {virgo-name} gets the artifact from a remotely-hosted repository that is physically located on a remote {tomcat-product-name} instance.
+
+You configure the provisioning repository using the `$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties` file.
+
+As previously described, a particular instance of {tomcat-product-name} can itself also act as a repository host for remote server instances to use when satisfying the dependencies of the applications deployed to it. In this case, you configure a hosted repository using the `$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties` file. Typically, only remote clients use hosted repositories and their contents; the {tomcat-product-name} instance that actually hosts the repository does not typically use the artifacts in it. Rather, it uses artifacts in its local repository.
+
+Making a third-party dependency available to your application is simply a matter of adding its artifact to the appropriate location in the provisioning repository. This could be either in the local directories or the remote ones if you are getting artifacts from a remotely-hosted repository.
+
+anchor:repository-structure[]
+
+==== Local Repository Structure
+
+When you first install {virgo-name}, the local provisioning repository is located at `$SERVER_HOME/repository` by default and consists of two main directories: `ext` and `usr`. The `ext` directory contains artifacts supplied with the {virgo-name} and `usr` contains artifacts supplied by the user and is initially empty.
+
+anchor:repository-installing-bundles[]
+
+==== Installing Artifacts to a Repository
+
+To install an artifact into the default repository, simply copy it into the `$SERVER_HOME/repository/usr` directory.
+
+If you have configured additional watched or external repositories (additional, that is, to the default ones already configured in a freshly-installed {virgo-name} instance), you install the artifacts in the same way: simply copy the files to the configured directories. You configure additional watched or external repositories in the same file as the default repositories: `$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties`.
+
+When you install a plan or a library into the repository, you must ensure that all referenced artifacts within the plan or library have been installed as well.
+
+Artifacts must have unique names so it is considered best practice to include the version number in the file name,
+allowing for multiple versions of the artifact to be installed at the same time. For example, a bundle file name might be `my-exciting-bundle.2.1.0.jar`.
+
+For watched repositories, such as `$SERVER_HOME/repository/usr`, {virgo-name} automatically detects changes
+at runtime, thereby avoiding the need to restart {virgo-name}.
+
+Of specific relevance during development is picking up changes to an application's direct dependencies during deployment of the application. For example, if you deploy an application and receive a message that a dependency is missing, you can simply add the dependency to the repository and then redeploy the application. The redeploy will cause the new dependency to be picked up, allowing progress to be made without restarting {virgo-name}. For other changes such as addition of optional dependencies, {virgo-name} must be restarted to pick up any changes to the provisioning repository.
+
+anchor:repository-brits[]
+
+=== Downloading Bundles from the EBR
+
+The {ebr} is a public collection of open source libraries commonly used for developing enterprise Java applications with the Spring Framework and {virgo-name}. It contains hundreds of the most popular enterprise Java libraries made available for general use in an OSGi-ready format. You can browse the collection and then download the bundles that you need into your own local repository.
+
+The {ebr} is located http://www.springsource.com/repository[here].
+
+image:bundle-repository.png[]
+
+You can find bundles in the repository using a number of options. You use the ‘Search' facility by typing in a keyword. The matching criteria returned can be explored by name, symbolic name, class, package or resource.
+
+There is also the option of clicking on ‘Browse by Bundle'. This gives an alphabetical list of bundles. You can select the desired bundle to see details and find the download link. Finally, you can also choose to ‘Browse by Library', which allows you to browse the alphabetical list of libraries in the repository.
+
+anchor:repository-configuration[]
+
+=== Configuring the Repository
+
+Details of how to configure a {virgo-name} installation's provisioning repository can be found in xref:configuring-provisioning-repository[Configuring the Provisioning Repository]. See xref:configuring-hosted-repo[Configuring a Hosted Repository] for details of how to configure a repository that remote clients can access, also called a hosted repository.
+
+The two configuration sections describe the format of the repository properties files of {virgo-name}, how to add new directories to the local repository, how to configure the repository to get artifacts from a remote repository hosted on a remote {tomcat-product-name-short} instance, and how to configure the local {tomcat-product-name-short} instance to host a repository that other remote servers access.
+
diff --git a/user-guide/src/docs/asciidoc/serviceability.adoc b/user-guide/src/docs/asciidoc/serviceability.adoc
new file mode 100644
index 0000000..770b9c1
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/serviceability.adoc
@@ -0,0 +1,214 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:serviceability[Serviceability and Diagnostics]
+
+== Serviceability and Diagnostics
+
+{virgo-name} supports two kinds of logging: *Event Logging* and *Trace logging* which is usually referred
+to simply as *Logging*. The difference between Event Logging and Logging is explained below, but both are configured in the
+`serviceability.xml` file in the `configuration` directory. This file takes the form of a Logback configuration, {virgo-name}
+uses a Logback implementation behind the SLF4J logging interface.
+
+For a description of the syntax and facilities provided by `serviceability.xml`
+see the *Logback* documentation (referenced in xref:furtherreading[]).
+
+anchor:serviceability-info-log[]
+
+=== Event Logging
+
+Event logging records important events in {virgo-name}. Each event is logged to
+an event log file and is accompanied by a code enclosed in angle brackets.
+An example is shown below:
+
+....
+[2010-10-25 16:20:45.897] system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme http on port 8080.
+....
+
+(For a description of the log code syntax, see xref:log-codes[].)
+The format of event log messages is fully configurable.
+
+By default, event log messages are stored in `$SERVER_HOME/serviceability/eventlogs/eventlog.log`.
+
+The default behaviour is that, once `eventlog.log` reaches a 10Mb limit, it rolls into a series of files named
+`eventlog_`*i*`.log` where *i* ranges from 1 to 4, and event logging continues in
+a new `eventlog.log` file.
+
+anchor:serviceability-info-trace[]
+
+=== (Trace) Logging
+
+The {virgo-name}'s (trace) logging support serves two main purposes:
+
+* It provides global trace files that capture high-volume information regarding the {virgo-name}'s internal events.
+The files are intended for use by support personnel to diagnose runtime problems.
+* It provides application trace files that contain application-generated output. This includes output generated using popular logging and
+tracing APIs including the OSGi LogService, as well as output generated by calls to `System.out` and `System.err`.
+These files are intended for use by application developers and system administrators. An application is defined as a scope so a single bundle will
+not get its own log file unless it is a Web application Bundle or is included in a scoped plan or a par file.
+
+By default, the {virgo-name} trace file is called `$SERVER_HOME/serviceability/logs/log.log`,
+and, again by default, the application trace files are called `$SERVER_HOME/serviceability/logs/`*application_name*
+`/log.log`, where *application_name* is automatically set by {virgo-name} for each application artifact
+installed and run (it is a combination of the artifact name and the version).
+
+The default behaviour of these trace files is that, once `log.log` reaches a 10Mb limit, it rolls into a series of files named
+`log_`*i*`.log` where *i* ranges from 1 to 4, and logging continues in
+a new `log.log` file.
+
+Entries in trace files are by default of the form <timestamp> <thread-name> <source> <level> <entry-text>. For example:
+
+....
+[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080
+....
+
+although this format is completely determined by the Logback configuration file `serviceability.xml`.
+
+anchor:serviceability-info-trace-app[]
+
+==== Application Output
+
+{virgo-name} provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a
+per-application basis and will also capture any `System.out` and `System.err` output.
+
+anchor:per-application-trace[]
+
+==== Per-application trace
+
+{virgo-name} uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output
+and appends it to the application-specific trace files as described above.
+To modify this, define application-specific loggers in the `serviceability.xml` file in the normal way.
+
+anchor:sysout-and-syserr[]
+
+=== System.out and System.err
+
+`System.out` and `System.err` output from applications is, by default, captured in the
+application's trace file.
+This happens because the output streams are intercepted and written to the loggers named
+`System.out` and `System.err` respectively.
+Since there are no explicit loggers defined with these names in the `serviceability.xml` file,
+this output is logged by the root logger (which captures `INFO` level and above).
+
+
+The capture of `System.out` and `System.err` output is configured in the
+`configuration/org.eclipse.virgo.medic.properties` file by the `log.wrapSysOut` and
+`log.wrapSysErr` properties. By default the properties have a value of `true`
+and capture is enabled. Capture can be disabled by configuring the properties with a value of `false`.
+The third and last accepted value is `tee` which captures the System streams output in the logs
+while at the same time allows printing output to the System streams. Thus this output will appear both in the logs
+and in the System stream output - an example could be the Equinox console, launched with `-console` startup argument.
+
+[IMPORTANT]
+--
+If you provide value different than 'true | tee | false' then the server will default to 'tee' and print out a warning.
+--
+
+The trace entries for `System.out` and `System.err`
+output are of the form:
+
+....
+[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out Hello world!
+[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err Hello world!
+....
+
+The third column indicates where the output came from (`System.out` or `System.err`).
+
+To over-ride this behaviour, simply define explicit loggers named `System.out`
+and/or `System.err` in the configuration file to send this output to an appender of your choice.
+Be aware that all applications' output streams will be caught by these loggers, and that a sifting appender might be useful to separate them.
+
+anchor:janino[]
+
+==== Janino
+
+Janino can be used to define trace filters as Java expressions. This adds a significant overhead to tracing, so should be used with care.
+
+For example, the addition of the following filter element to the sifting appender in `serviceability.xml`
+suppresses per-application trace output that is not associated with a particular application and is normally written to
+`serviceability/logs/virgo-kernel/log.log`.
+
+[source,xml]
+----
+<appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender">
+ <discriminator>
+ <Key>applicationName</Key>
+ <DefaultValue>virgo-kernel</DefaultValue>
+ </discriminator>
+ <sift>
+ <appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <filter class="ch.qos.logback.core.filter.EvaluatorFilter">
+ <evaluator class="ch.qos.logback.classic.boolex.JaninoEventEvaluator">
+ <expression>
+ (mdc == null) || (mdc.get("applicationName") == null)
+ </expression>
+ </evaluator>
+ <OnMismatch>NEUTRAL</OnMismatch>
+ <OnMatch>DENY</OnMatch>
+ </filter>
+ <file>serviceability/logs/${applicationName}/log.log</file>
+ ...
+ </appender>
+ </sift>
+</appender>
+----
+
+To enable Janino in {virgo-name}, place the Janino and commons compiler JARs, converted to OSGi bundles, in `plugins`.
+For example these bundles are available at v2.6.1 from the SpringSource Enterprise Bundle Repository.
+Then add the following lines to
+`configuration/org.eclipse.equinox.simpleconfigurator/bundles.info`
+(as described in xref:configuring-framework-bundles[Configuring OSGi Framework Bundles]):
+
+[source,txt]
+----
+com.springsource.org.codehaus.janino,2.6.1,plugins/com.springsource.org.codehaus.janino-2.6.1.jar,4,false
+com.springsource.org.codehaus.commons.compiler,2.6.1,plugins/com.springsource.org.codehaus.commons.compiler-2.6.1.jar,4,false]]></programlisting>
+----
+
+[IMPORTANT]
+--
+Current versions of Logback, including 0.9.28 to 1.0, do not set Janino's "parent" class loader correctly.
+This bug is covered by the Logback issue http://jira.qos.ch/browse/LBCORE-244[LBCORE-244].
+With such versions, it is necessary to attach a fragment bundle to Janino. Place the fragment bundle in `plugins` and list it in
+`configuration/org.eclipse.equinox.simpleconfigurator/bundles.info`.
+The fragment's contents are described in https://bugs.eclipse.org/bugs/show_bug.cgi?id=333920#c15[bug 333920].
+--
+
+anchor:serviceability-info-dump[]
+
+=== Service Dumps
+
+A service dump is triggered when one of the following events
+occurs:
+
+. A failure is detected in the {virgo-name} code, or
+. a thread deadlock is detected.
+
+A service dump contains a snapshot of all the important state from
+the running {virgo-name} instance. This snapshot is not intended
+for end user consumption but is useful for service personnel.
+
+
+By default, service dumps are created in `$SERVER_HOME/serviceability/dump`.
+
diff --git a/user-guide/src/docs/asciidoc/starting-stopping.adoc b/user-guide/src/docs/asciidoc/starting-stopping.adoc
new file mode 100644
index 0000000..2e87fe9
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/starting-stopping.adoc
@@ -0,0 +1,474 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:starting-stopping"[Starting and Stopping {tomcat-product-name}]
+
+== Starting and Stopping {tomcat-product-name}
+
+Starting and Stopping {tomcat-product-name-short}
+
+=== Starting {tomcat-product-name}
+
+To start {tomcat-product-name} run the `startup.sh` (Linux) or `startup.bat` (Windows) script.
+For both platforms, the script is located in the `SERVER_HOME/bin` directory.
+
+[NOTE]
+--
+This chapter applies to {nano-product-name} too. Note that since {nano-product-name-short}
+has a single region you can ignore the console output from the user region and focus on the instructions.
+A successful startup of {nano-product-name-short} is as simple as that:
+....
+[2011-12-28 11:41:31.528] startup-tracker <KE0001I> Kernel starting.
+[2011-12-28 11:41:31.602] startup-tracker <KE0002I> Kernel started.
+....
+--
+
+==== Linux
+
+To start {tomcat-product-name}, open a terminal window and run `startup.sh`:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh</screen>
+....
+
+Once {tomcat-product-name} has started, the console will display a log message
+similar to the one shown below, along with other status messages:
+
+....
+[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.
+....
+
+The preceding message indicates that you can start using {tomcat-product-name-short}.
+
+==== Microsoft Windows
+
+To start {tomcat-product-name}, open a command-window and run `startup.bat`:
+
+....
+c:> cd %SERVER_HOME%
+c:> bin\startup.bat</screen>
+....
+
+Once {tomcat-product-name} has started, the console will display a log message
+similar to the one shown below, along with other status messages:
+
+....
+[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.
+....
+
+The preceding message indicates that you can start using {tomcat-product-name-short}.
+
+=== Starting in Clean Mode
+
+When you start {tomcat-product-name} in clean mode, the startup script removes the `SERVER_HOME/work` directory (and hence all
+running applications) as well as all trace, log and dump files. It leaves the
+`SERVER_HOME/repository` and `SERVER_HOME/pickup` directories untouched,
+which means that any applications previously hot deployed will be automatically reinstalled.
+
+==== Linux
+
+To start {tomcat-product-name} in clean mode, open a terminal window and run `startup.sh -clean`:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -clean
+....
+
+==== Microsoft Windows
+
+To start {tomcat-product-name} in clean mode, open a command window and run `startup.bat -clean`:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -clean
+....
+
+=== Starting in Debug Mode
+
+==== Linux
+
+To start {tomcat-product-name} in debug mode, run
+`startup.sh` passing in the
+`-debug` argument:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -debug
+....
+
+This will start the debug agent listening on port
+`8000` which is the default remote debug port used
+by Eclipse. To start in debug mode with a specific port number, pass
+this in as the value for the `-debug` argument:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -debug 8001
+....
+
+This will start the debug agent listening on port
+`8001`. To start in debug mode and suspend the VM
+until a debugger attaches, pass in the `-suspend`
+argument along with the `-debug` argument:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -debug -suspend
+....
+
+This starts the debug agent, but prevents {tomcat-product-name} from actually
+starting until a debugger attaches to the agent. This can be useful
+when trying to diagnose problems that occur during startup.
+
+==== Microsoft Windows
+
+To start {tomcat-product-name} in debug mode, run
+`startup.bat` passing in the
+`-debug` argument:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -debug
+....
+
+This will start the debug agent listening on port
+`8000` which is the default remote debug port used
+by Eclipse. To start in debug mode with a specific port number, pass
+this in as the value for the `-debug` argument:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -debug 8001
+....
+
+This will start the debug agent listening on port
+`8001`. To start in debug mode and suspend the VM
+until a debugger attaches, pass in the `-suspend`
+argument along with the `-debug` argument:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -debug -suspend
+....
+
+This starts the debug agent, but prevents {tomcat-product-name} from actually
+starting until a debugger attaches to the agent. This can be useful
+when trying to diagnose problems that occur during startup.
+
+=== Starting with JMX Access Modifications
+
+The {tomcat-product-name} always starts with JMX access enabled, allowing you to use a management tool such as JConsole
+to attach to the Web Server instance.
+By default both local access and remote access over SSL with username and password
+authentication are provided. The default port for secure JMX access is `9875`
+and the default username and password are `admin` and `springsource`.
+
+==== Linux
+
+To start {tomcat-product-name} with default JMX access enabled, run `startup.sh` passing
+in no arguments:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh
+....
+
+To start JConsole, run the `jconsole.sh` script, located in the `bin` directory, as shown:
+
+....
+$ cd $SERVER_HOME
+$ bin/jconsole.sh
+....
+
+The following image shows how to specify a local connection using JConsole.
+
+image:jmx-local-attach.png[]
+
+The following image shows how to specify a remote connection in JConsole that uses SSL with the default
+username/password (`admin/springsource` and default secure port of `9875`).
+
+image:jmx-remote-attach-default.png[]
+
+To start with the JMX remote access on a specific port number other than the default `9875`,
+pass this port number in as the value
+of the `-jmxport` argument:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -jmxport 9090
+....
+
+This will start the {tomcat-product-name} with JMX enabled for remote connections on port `9090`.
+
+image:jmx-remote-attach-jmxport.png[]
+
+To start the JMX remote access with a custom username and password, update the `$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties` file. First specify the custom username by changing the value of the `role.admin` property. Then set the password of this new user by adding a new property called `user.*username*`, where `*username*` refers to the actual name of the user. Finally, restart {tomcat-product-name-short} for the changes to take effect.
+ For example, if you want change the JMX remote access username to `zebedee` with password `florence`, change the file as follows:
+
+[source,txt]
+----
+##################
+# User definitions
+##################
+user.zebedee=florence
+
+
+##################
+# Role definitions
+##################
+role.admin=zebedee
+----
+
+Specify the custom username in JConsole as shown.
+
+image:jmx-remote-attach-jmxusers.png[]
+
+To start the JMX remote access using a custom SSL certificate, edit the file located at
+`$SERVER_HOME/configuration/keystore`. If you wish to use a different keystore,
+pass this filename in as the value for the `-keystore` argument and the keystore
+password in as the value for the `-keystorePassword` argument:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword
+....
+
+This will start the {tomcat-product-name} with JMX enabled for remote connections using an SSL certificate from
+`customKeystore` with a password of `customKeystorePassword`.
+
+==== Microsoft Windows
+
+To start {tomcat-product-name} with default JMX access enabled, run `startup.bat` passing
+in no arguments:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat
+....
+
+To start JConsole, run the `jconsole.bat` script, located in the `bin` directory, as shown:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\jconsole.bat
+....
+
+The following image shows how to specify a local connection using JConsole.
+
+image:jmx-local-attach.png[]
+
+The following image shows how to specify a remote connection in JConsole that uses SSL with the default
+username/password (`admin/springsource` and default secure port of `9875`).
+
+image:jmx-remote-attach-default.png[]
+
+To start with the JMX remote access on a specific port number other than the default `9875`,
+pass this port number in as the value of the `-jmxport` argument:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -jmxport 9090
+....
+
+This will start the {tomcat-product-name} with JMX enabled for remote connections on port
+`9090`.
+
+image:jmx-remote-attach-jmxport.png[]
+
+To start the JMX remote access with a custom username and password, update the `%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties` file. First specify the custom username by changing the value of the `role.admin` property. Then set the password of this new user by adding a new property called `user.*username*`, where `*username*` refers to the actual name of the user. Finally, restart {tomcat-product-name-short} for the changes to take effect.
+ For example, if you want change the JMX remote access username to `zebedee` with password `florence`, change the file as follows:
+
+[source,txt]
+----
+##################
+# User definitions
+##################
+user.zebedee=florence
+
+
+##################
+# Role definitions
+##################
+role.admin=zebedee
+----
+
+Specify the custom username in JConsole as shown.
+
+image:jmx-remote-attach-jmxusers.png[]
+
+To start the JMX remote access using a custom SSL certificate, edit the file located at
+`%SERVER_HOME%\configuration\keystore`. If you wish to use a different
+keystore, pass this filename in as the value for the `-keystore` argument and the
+keystore password in as the value for the `-keystorePassword` argument:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword
+....
+
+This will start the {tomcat-product-name} with JMX enabled for remote attach using an SSL certificate from
+`customKeystore` with a password of `customKeystorePassword`.
+
+anchor:starting-stopping-configuration-directory[]
+
+=== Starting with a Custom Configuration Directory
+
+Use the `-configDir` option to specify an alternate `configuration` directory, different from the
+default `SERVER_HOME/configuration` directory. This option allows you to use the same {tomcat-product-name}
+installation to run multiple instances of {tomcat-product-name-short}. Simply create a configuration directory for each
+instance, specify unique port numbers, logging and tracing directories, and so on, and then specify that directory
+when starting {tomcat-product-name-short}.
+
+If you specify a relative path for the `-configDir` parameter,
+the startup script interprets the path as relative to the root of the {tomcat-product-name} installation,
+and not relative to the directory from which you execute the `startup` script.
+
+See xref:alternate-serviceability-work[Alternate `serviceability` and `work`
+Directories] for a known issue related to specifying an alternate `configuration` directory.
+
+==== Linux
+
+To start {tomcat-product-name} using a configuration directory of `/configuration/node1`:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -configDir /configuration/node1
+....
+
+==== Windows
+
+To start {tomcat-product-name} using a configuration directory of `c:\configuration\node1`:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -configDir c:\configuration\node1
+....
+
+=== Stopping {tomcat-product-name}
+
+==== Linux
+
+To stop a running instance of {tomcat-product-name}, start a new terminal window and run the `shutdown.sh` script:
+
+....
+$ cd $SERVER_HOME
+$ bin/shutdown.sh
+....
+
+To stop a running instance of {tomcat-product-name} immediately, bypassing normal shutdown
+processing, run `shutdown.sh` with the `-immediate` option:
+
+....
+$ cd $SERVER_HOME
+$ bin/shutdown.sh -immediate
+....
+
+If, when you started the Web Server instance, you used the `-jmxport` option to specify a non-default JMX port number,
+then you must pass this port number to the `-jmxport` of the `shutdown.sh` script
+to gracefully shut it down.
+For example, if you specified `9090` as the JMX port, use the following to shut down the Web Server instance:
+
+....
+$ cd $SERVER_HOME
+$ bin/shutdown.sh -jmxport 9090
+....
+
+==== Microsoft Windows
+
+To stop a running instance of {tomcat-product-name}, start a new console window and run the `shutdown.bat` script:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\shutdown.bat
+....
+
+To stop a running instance of {tomcat-product-name} immediately, bypassing normal shutdown
+processing, run `shutdown.bat` with the `-immediate` option:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\shutdown.bat -immediate
+....
+
+If, when you started the Web Server instance, you used the `-jmxport` option to specify a non-default JMX port number,
+then you must pass this port number to the `-jmxport` of the `shutdown.bat` script to gracefully shut it down.
+For example, if you specified `9090` as the JMX port, use the following to shut down the Web Server instance:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\shutdown.bat -jmxport 9090
+....
+
+anchor:cleaning-without-starting[]
+
+=== Cleaning {tomcat-product-name} without Starting it
+
+When you clean {tomcat-product-name}, the startup script removes the `SERVER_HOME/work` directory (and hence all
+running applications) as well as all trace, log and dump files. It leaves the
+`SERVER_HOME/repository` and `SERVER_HOME/pickup` directories untouched,
+which means that any applications previously hot deployed will be automatically reinstalled next time the Web Server is started.
+
+Cleaning is useful when you want to start the Web Server from a clean state next time, but you don't want to start the Web Server yet.
+
+Cleaning is also useful for tidying up the directory structure. For example, sometimes Microsoft Windows won't let you delete the Web
+Server installation directory.
+See xref:windows-deletion[Problem Deleting Installation Directory under Windows] for more details.
+
+==== Linux
+
+To clean {tomcat-product-name}, open a terminal window and run `startup.sh -clean -noStart`:
+
+....
+$ cd $SERVER_HOME
+$ bin/startup.sh -clean -noStart
+....
+
+==== Microsoft Windows
+
+To clean {tomcat-product-name}, open a command window and run `startup.bat -clean -noStart`:
+
+....
+C:> cd %SERVER_HOME%
+C:> bin\startup.bat -clean -noStart
+....
+
+anchor:equinox-launcher[]
+
+=== Using Equinox Launcher
+
+Since version 3.5 {virgo-name} uses the standard Equinox Launcher as its default launcher.
+As a result in addition to all the launcher options described so far users can also pass arguments specific to the Equinox launcher.
+
+[IMPORTANT]
+--
+The Equinox Launcher arguments must be placed at the end of the startup call. Here's an example
+....
+$ ./startup.sh "virgo-args" "equinox-launcher-args"
+$ ./startup.sh -clean -console 2222</screen>
+....
+--
+
+A full list of the accepted Equinox Launcher arguments is available at http://help.eclipse.org/[help.eclipse.org].
+
diff --git a/user-guide/src/docs/asciidoc/using-the-p2-director.adoc b/user-guide/src/docs/asciidoc/using-the-p2-director.adoc
new file mode 100644
index 0000000..66d53ff
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/using-the-p2-director.adoc
@@ -0,0 +1,111 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
+:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+
+anchor:using-the-p2-director[]
+
+== Using the p2 director
+
+anchor:prereqs[]
+
+=== Prerequisites
+
+The {tomcat-product-name}, or {tomcat-product-name-short} for short, requires Java SE 6 or later to be installed. Java is available from
+http://www.java.com/[http://www.java.com/] and elsewhere.
+
+Since you're going to use the p2 director you'll need to get it. The easiest way is to download Eclipse from http://www.eclipse.org/downloads/[here].
+It has built-in p2 director and other p2 applications.
+
+[IMPORTANT]
+--
+Setting the Target Platform
+--
+
+Before using the director make sure you have a proper target platform set. Otherwise you may not see the director application. Here's how to do that:
+Go to Eclipse's Preferences->Plug-in Development->Target Platform. Below is shown how the view looks like when a default target platform is set.
+
+image:target-platform-view.png[]
+
+If for some reason you don't have any target platform set or it's not the default one you must set the default target platform from the image above.
+If the default target platform is missing then add a new one via the *Add...* button and select the *Default* radio button as shown below:
+
+image:default-target-create.png[]
+
+You can now click *Next* and then *Finish*.
+
+anchor:using-director[Installing with the p2 director from Eclipse]
+
+=== Installing with the p2 director from Eclipse
+
+This section covers briefly using the p2 director for installing.
+A helpful page is the p2 director's http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html[documentation at help.eclipse.org].
+There you can find more information on the different supported arguments.
+
+Here's how to use the GUI version of the director built-in Eclipse.
+
+. Go to the *Run* context menu and select *Run Configurations*
+. Create a new one and choose the director application as shown below, then switch to the *Arguments* tab
+
+[IMPORTANT]
+--
+In the image below the "Location:" text box's value is managed by your IDE, don't type anything in there.
+--
+
+image:run_configuration.png[]
+
+In the *Program Arguments* section append the director arguments. Here's an example I used:
+
+....
+-repository <yourP2repo>
+-installIU nano.product
+-tag InitialState
+-destination /Users/<youruser>/install/virgo
+-profile VirgoProfile
+-roaming
+-p2.os ${target.os}
+-p2.ws ${target.ws}
+-p2.arch ${target.arch}
+....
+
+[IMPORTANT]
+--
+The *-repository* argument accepts any valid p2 repository.
+The *-destination* argument accepts any valid absolute location. It defines the location where your Virgo installation will be provisioned.
+If the directory does not exist, it will be created by the director.
+--
+
+These arguments produce a {nano-product-name} installation. For the *p2.** arguments use the same properties from the example above. Eclipse will substitute them later with real values.
+
+The passed value for *-installIU* determines which Virgo product is going to be installed. Here's a list of all Virgo product install IUs:
+*nano.product* - {nano-product-name}
+*nano-full.product* - {nano-product-name} Full ({nano-product-name-short} ` p2 ` GW)
+*kernel.product* - {kernel-product-name}
+*tomcat-server.product* - {tomcat-product-name}
+*jetty-server.product* - {jetty-product-name}
+
+image:director_args.png[]
+
+Finally, run the created configuration. You should see the following output in Eclipse's Console
+
+image:director_result.png[]
+
diff --git a/user-guide/src/docs/asciidoc/virgo-user-guide.adoc b/user-guide/src/docs/asciidoc/virgo-user-guide.adoc
new file mode 100644
index 0000000..6e5304c
--- /dev/null
+++ b/user-guide/src/docs/asciidoc/virgo-user-guide.adoc
@@ -0,0 +1,76 @@
+:virgo-name: Virgo
+:version: 3.7.0.RELEASE
+
+:umbrella-virgo-name: Eclipse Virgo
+:tomcat-product-name: Virgo for Apache Tomcat
+:tomcat-product-name-short: VTS
+:jetty-product-name: Virgo Jetty Server
+:jetty-product-name-short: VJS
+:kernel-product-name: Virgo Kernel
+:kernel-product-name-short: VK
+:nano-product-name: Virgo Nano
+:nano-product-name-short: VN
+:programmer-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-{version}/docs/virgo-programmer-guide/html/index.html[User Guide]
+:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]
+
+:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]
+
+:spring-framework-version: 4.2.9.RELEASE
+
+:homepage: https://www.eclipse.org/virgo
+:ebr: http://www.eclipse.org/ebr[EBR]
+
+:imagesdir: assets/images
+:experimental: true
+:toc:
+
+= {virgo-name} User Guide
+
+[%hardbreaks]
+Rob Harrop
+Paul Kuzan
+Sam Brannen
+Paul Harris
+Christopher Frost
+Ben Hale
+Glyn Normington
+Juliet Shackell
+Steve Powell
+Violeta Georgieva
+Hristo Iliev
+Borislav Kapukaranov
+Florian Waibel
+
+image::virgo-logo-small.png[Eclipse Virgo,float="right"]
+
+[%hardbreaks]
+{umbrella-virgo-name}
+{version}
+Copyright (C) 2009, 2011 VMware Inc. and others
+
+[%hardbreaks]
+Contributors:
+
+* VMware Inc. - initial contribution and subsequent updates
+* Violeta Georgieva, SAP AG - Apache Tomcat configuration
+* Hristo Iliev, SAP AG - Setting jmx.properties permissions
+* Borislav Kapukaranov, SAP AG - Configuring framework extensions and fragments on system bundle; Added {nano-product-name} references and tips
+
+'''
+
+include::introduction.adoc[]
+include::concepts.adoc[]
+include::using-the-p2-director.adoc[]
+include::installing.adoc[]
+include::installing-kernel.adoc[]
+include::installing-nano.adoc[]
+include::starting-stopping.adoc[]
+include::admin-shell.adoc[]
+include::admin-console.adoc[]
+include::repository.adoc[]
+include::serviceability.adoc[]
+include::applications.adoc[]
+include::configuring.adoc[]
+include::log-codes.adoc[]
+include::known-issues.adoc[]
+include::further-reading.adoc[]
diff --git a/user-guide/src/further-reading.xml b/user-guide/src/further-reading.xml
deleted file mode 100644
index 307a330..0000000
--- a/user-guide/src/further-reading.xml
+++ /dev/null
@@ -1,39 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<appendix id="furtherreading">
- <title>
- Further Reading
- </title>
-
- <para>
- <ulink url="../../virgo-programmer-guide/html/index.html">
- @tomcat.product.name@ Programmer Guide
- </ulink>
- </para>
-
- <para>
- <ulink url="http://static.springframework.org/spring/docs/2.5.x/reference/index.html">
- Spring Framework Reference Guide
- </ulink>
- </para>
-
- <para>
- <ulink url="http://static.springframework.org/osgi/docs/current/reference/html/">
- Spring Dynamic Modules Reference Guide
- </ulink>
- </para>
-
- <para>
- <ulink url="http://www.osgi.org/Specifications/HomePage">
- Blueprint Container Specification
- </ulink>
- (in the OSGi 4.2 and 5.0 Enterprise Specifications)
- </para>
-
- <para>
- <ulink url="http://logback.qos.ch/manual">
- The Logback Manual
- </ulink>
- </para>
-</appendix>
diff --git a/user-guide/src/installing-kernel.xml b/user-guide/src/installing-kernel.xml
deleted file mode 100644
index d434090..0000000
--- a/user-guide/src/installing-kernel.xml
+++ /dev/null
@@ -1,78 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="kernel-installation">
- <title>Installing @kernel.product.name@</title>
- <section id="kernel-installation-prereqs">
- <title>Prerequisites</title>
- <para>
- The @kernel.product.name@, or @kernel.product.name.short@ for short, requires Java SE 6 or later to be installed. Java is available from
- <ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.
- </para>
- </section>
-
- <section id="kernel-installation-zip">
- <title>Installing from the ZIP Download</title>
- <section>
- <title>Downloading the ZIP file</title>
- <para>
- @kernel.product.name@ is distributed as a ZIP file. This can be downloaded from
- <ulink url="http://www.eclipse.org/virgo/download/">here</ulink>.
- </para>
- </section>
- <section id="kernel-installation-zip-installing">
- <title>Installing</title>
- <section id="kernel-installation-zip-installing-linux">
- <title>Linux</title>
- <para>
- To install the @kernel.product.name@ on Linux, unzip the distribution package to the desired installation directory.
- For example, to install into <literal>/opt</literal>:
- </para>
- <screen>prompt$ unzip virgo-kernel-@bundle.version@.zip -d /opt</screen>
- <para>
- This creates a directory called <literal>virgo-kernel-@bundle.version@</literal> under <literal>/opt</literal>.
- </para>
- <para>
- @kernel.product.name@ requires write access to the installation directory, in this case <literal>/opt/virgo-kernel-@bundle.version@</literal>.
- Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.
- </para>
- </section>
- <section id="kernel-installation-zip-installing-win">
- <title>Microsoft Windows</title>
- <para>
- To install the @kernel.product.name@ on Windows, unzip the distribution package to the desired installation directory.
- You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
- Java have some issues with long file names and file paths, so we recommend installing to the root directory of
- your chosen drive.
- </para>
- </section>
- </section>
- </section>
-
- <section id="kernel-installation-updatesite">
- <title>Installing from an update site</title>
- <section>
- <title>The repository location</title>
- <para>
- Virgo has a single p2 repository that contains all Virgo distributions. The repository for version @bundle.version@ can be found <ulink url="@p2repo@">here</ulink>.
- There is a repository for each released version.
- </para>
- </section>
- <section>
- <title>Using the p2 director</title>
- <para>
- As shown in <xref linkend="using-director"/> you can easily install @kernel.product.name.short@ in a desired destination.
- The only director argument that needs to be adjusted is <emphasis>-installIU</emphasis>.
- </para>
- <para>
- For @kernel.product.name.short@ the right value is <emphasis>kernel.product</emphasis>.
- </para>
- </section>
- </section>
-
- <section id="kernel-installation-post">
- <title>Post-installation steps</title>
- Follow the same <link linkend="installation-post">Post-installation steps</link> as for @tomcat.product.name@.
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/user-guide/src/installing-nano.xml b/user-guide/src/installing-nano.xml
deleted file mode 100644
index 611e753..0000000
--- a/user-guide/src/installing-nano.xml
+++ /dev/null
@@ -1,78 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="nano-installation">
- <title>Installing @nano.product.name@</title>
- <section id="nano-installation-prereqs">
- <title>Prerequisites</title>
- <para>
- The @nano.product.name@, or @nano.product.name.short@ for short, requires Java SE 6 or later to be installed. Java is available from
- <ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.
- </para>
- </section>
-
- <section id="nano-installation-zip">
- <title>Installing from the ZIP Download</title>
- <section>
- <title>Downloading the ZIP file</title>
- <para>
- @nano.product.name@ is distributed as a ZIP file. This can be downloaded from
- <ulink url="http://www.eclipse.org/virgo/download/">here</ulink>.
- </para>
- </section>
- <section id="nano-installation-zip-installing">
- <title>Installing</title>
- <section id="nano-installation-zip-installing-linux">
- <title>Linux</title>
- <para>
- To install the @nano.product.name@ on Linux, unzip the distribution package to the desired installation directory.
- For example, to install into <literal>/opt</literal>:
- </para>
- <screen>prompt$ unzip virgo-nano-@bundle.version@.zip -d /opt</screen>
- <para>
- This creates a directory called <literal>virgo-nano-@bundle.version@</literal> under <literal>/opt</literal>.
- </para>
- <para>
- @nano.product.name@ requires write access to the installation directory, in this case <literal>/opt/virgo-nano-@bundle.version@</literal>.
- Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.
- </para>
- </section>
- <section id="nano-installation-zip-installing-win">
- <title>Microsoft Windows</title>
- <para>
- To install the @nano.product.name@ on Windows, unzip the distribution package to the desired installation directory.
- You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
- Java have some issues with long file names and file paths, so we recommend installing to the root directory of
- your chosen drive.
- </para>
- </section>
- </section>
- </section>
-
- <section id="nano-installation-updatesite">
- <title>Installing from an update site</title>
- <section>
- <title>The repository location</title>
- <para>
- Virgo has a single p2 repository that contains all Virgo distributions. The repository for version @bundle.version@ can be found <ulink url="@p2repo@">here</ulink>.
- There is a repository for each released version.
- </para>
- </section>
- <section>
- <title>Using the p2 director</title>
- <para>
- As shown in <xref linkend="using-director"/> you can easily install @nano.product.name.short@ in a desired destination.
- The only director argument that needs to be adjusted is <emphasis>-installIU</emphasis>.
- </para>
- <para>
- For @nano.product.name.short@ the right value is <emphasis>nano.product</emphasis>.
- </para>
- </section>
- </section>
-
- <section id="nano-installation-post">
- <title>Post-installation steps</title>
- Follow the same <link linkend="installation-post">Post-installation steps</link> as for @tomcat.product.name@.
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/user-guide/src/installing.xml b/user-guide/src/installing.xml
deleted file mode 100644
index 51a562b..0000000
--- a/user-guide/src/installing.xml
+++ /dev/null
@@ -1,189 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="installation">
- <title>Installing @tomcat.product.name@</title>
- <section id="installation-prereqs">
- <title>Prerequisites</title>
- <para>
- The @tomcat.product.name@, or @tomcat.product.name.short@ for short, requires Java SE 6 or later to be installed. Java is available from
- <ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.
- </para>
- <para>
- In case you are installing via a p2 director you'll need to get it. The easiest way is to download Eclipse from <ulink url="http://www.eclipse.org/downloads/">here</ulink>.
- It has built-in p2 director and other p2 applications.
- </para>
- </section>
- <section id="installation-zip">
- <title>Installing from the ZIP Download</title>
- <section>
- <title>Downloading the ZIP file</title>
- <para>
- @tomcat.product.name@ is distributed as a ZIP file. This can be downloaded from
- <ulink url="http://www.eclipse.org/virgo/download/">here</ulink>.
- </para>
- </section>
- <section id="installation-zip-installing">
- <title>Installing</title>
- <section id="installation-zip-installing-linux">
- <title>Linux</title>
- <para>
- To install @tomcat.product.name@ on Linux, unzip the distribution package to the desired installation directory.
- For example, to install into <literal>/opt</literal>:
- </para>
- <screen>prompt$ unzip virgo-web-server-@bundle.version@.zip -d /opt</screen>
- <para>
- This creates a directory called <literal>virgo-web-server-@bundle.version@</literal> under <literal>/opt</literal>.
- </para>
- <para>
- @tomcat.product.name@ requires write access to the installation directory, in this case <literal>/opt/virgo-web-server-@bundle.version@</literal>.
- Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.
- </para>
- </section>
- <section id="installation-zip-installing-win">
- <title>Microsoft Windows</title>
- <para>
- To install the @tomcat.product.name@ on Windows, unzip the distribution package to the desired installation directory.
- You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
- Java have some issues with long file names and file paths, so we recommend installing to the root directory of
- your chosen drive.
- </para>
- </section>
- </section>
- </section>
-
- <section id="installation-updatesite">
- <title>Installing from an update site</title>
- <section>
- <title>The repository location</title>
- <para>
- Virgo has a single p2 repository that contains all Virgo distributions. The repository for version @bundle.version@ can be found <ulink url="@p2repo@">here</ulink>.
- There is a repository for each released version.
- </para>
- </section>
- <section>
- <title>Using the p2 director</title>
- <para>
- As shown in <xref linkend="using-director"/> you can easily install @tomcat.product.name.short@ in a desired destination.
- The only director argument that needs to be adjusted is <emphasis>-installIU</emphasis>.
- </para>
- <para>
- For @tomcat.product.name.short@ the right value is <emphasis>tomcat-server.product</emphasis>.
- </para>
- </section>
- </section>
-
- <section id="installation-post">
- <title>Post-installation steps</title>
- <section id="installation-post-env">
- <title>Set environment variable variables</title>
- <section id="installation-post-env-java">
- <title>JAVA_HOME</title>
- <para>
- @tomcat.product.name@ uses the <literal>JAVA_HOME</literal> environment variable to locate the <literal>java</literal>
- executable. Configure this environment variable to point to the home directory of the Java 6 installation on your computer.
- </para>
- </section>
- <section id="installation-post-env-server">
- <title>SERVER_HOME</title>
- <para>
- As a convenience it is recommended that you create an environment variable that points
- to the @tomcat.product.name@ installation directory. Note that the @tomcat.product.name@ does not require that
- such an environment variable has been set. This variable may have any name of your
- choosing. The @tomcat.product.name@’s documentation assumes that the variable is named
- <literal>SERVER_HOME</literal>.
- </para>
- </section>
- <section id="installation-post-env-server-linux">
- <title>Linux</title>
- <para>
- Edit the <literal>.profile</literal> file in your home directory to
- add the <literal>SERVER_HOME</literal> and <literal>JAVA_HOME</literal> environment variables. For
- example, if you installed into <literal>/opt</literal>:
- </para>
- <screen>export SERVER_HOME=/opt/virgo-web-server-@bundle.version@/
-export JAVA_HOME=/user/java/jdk1.6.0_17
-export PATH=$JAVA_HOME/bin:$PATH</screen>
- <para>
- To verify the setting of <literal>JAVA_HOME</literal>, issue the command <literal>$JAVA_HOME/bin/java -version</literal> from a new terminal window
- and ensure that the command completes successfully and reports
- a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
- </para>
- </section>
- <section id="installation-post-env-server-win">
- <title>Microsoft Windows</title>
- <para>
- This section shows how to add <literal>SERVER_HOME</literal> as a system variable on Windows. Follow the same procedure to add or update the <literal>JAVA_HOME</literal> environment variable.
- </para>
- <para>
- From the Start menu, open the Control Panel and double-click on ‘System’.
- </para>
- <para>
- <imagedata fileref="images/system-props.png"/>
- </para>
- <para>
- Click the ‘Advanced’ tab and select ‘Environment Variables’. Next,
- click the ‘New’ button in the ‘System Variables’ section.
- </para>
- <para>
- <imagedata fileref="images/env-variables.png"/>
- </para>
- <para>
- This will display the ‘New System Variable’ window. Enter
- <literal>SERVER_HOME</literal> as the ‘Variable name’ and
- the installation directory as the ‘Variable value’. Click OK.
- </para>
- <para>
- <imagedata fileref="images/system-variable.png"/>
- </para>
- <para>
- To verify the setting of <literal>JAVA_HOME</literal>, issue the command <literal>"%JAVA_HOME%"\bin\java -version</literal> from
- a new command prompt and ensure that the command completes successfully and reports
- a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
- </para>
- </section>
- </section>
- <section id="installation-post-env-server-win-troubleshooting">
- <title>Microsoft Windows - Troubleshooting Security Permissions</title>
- <para>
- When starting @tomcat.product.name@ on some variants of Windows you might encounter a problem with file permissions.
- The error looks like this.
- </para>
- <screen>WARNING: jmxPermissions.vbs did not update the permissions of C:\virgo\configuration\org.eclipse.virgo.kernel.jmxremote.access.properties. Check the file has the correct permissions.</screen>
- <para>
- If @tomcat.product.name.short@ starts correctly (see <xref linkend="starting-stopping"/>) you can skip this section and carry on. However to secure your
- installation you have to set correct permissions. To do so, go to the ‘configuration’ directory of the installation
- in Windows Explorer.
- </para>
- <para>
- <imagedata fileref="images/install-windows-1-FileListing.png" />
- </para>
- <para>
- Right click on the ‘org.eclipse.virgo.kernel.jmxremote.access.properties’ file and view its properties,
- then select the ‘Security’ tab. Remove all groups and users from the list and select ‘Apply’.
- </para>
- <para>
- <imagedata fileref="images/install-windows-2-SecuritySettings.png" />
- </para>
- <para>
- Within the security page select the ‘Advanced’ options. On the ‘Owner’ tab, choose the owner
- that you are trying to run the @tomcat.product.name.short@ as and select ‘Apply’.
- </para>
- <para>
- <imagedata fileref="images/install-windows-3-AdvanceSettingsOwner.png" />
- </para>
- <para>
- Once this is done select ‘OK’ to return to the ‘Security’ tab
- and now add the owner to the list of groups and users that have permission to access the file.
- </para>
- <para>
- <imagedata fileref="images/install-windows-4-AllSetReadAndExecute.png" />
- </para>
- <para>
- Once all these steps are complete you can proceed to start the @tomcat.product.name.short@.
- </para>
- <screen>C:\dev\virgo-web-server-@bundle.version@>bin\startup.bat
-[2009-12-08 13:09:09.545] startup-tracker <KE0001I> Kernel starting.</screen>
- </section>
- </section>
-</chapter>
diff --git a/user-guide/src/introduction.xml b/user-guide/src/introduction.xml
deleted file mode 100644
index c8b8a75..0000000
--- a/user-guide/src/introduction.xml
+++ /dev/null
@@ -1,44 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="introduction">
-
- <title>Introduction</title>
-
- <para>
- This User Guide covers the @tomcat.product.name@ (@tomcat.product.name.short@), the @jetty.product.name@
- (@jetty.product.name.short@) and the @kernel.product.name@ (@kernel.product.name.short@), although it emphasises the
- @tomcat.product.name.short@ since that is likely to apply to more users.
- </para>
-
- <section>
- <title>A Note for @kernel.product.name@ Users</title>
- <para>
- @kernel.product.name@ users can be reassured that the majority of the information
- in this Guide is directly applicable to the @kernel.product.name@ and they can simply ignore the web-related sections.
- </para>
- </section>
-
-
- <section>
- <title>A Note for @jetty.product.name@ Users</title>
- <para>
- @jetty.product.name@ users can be reassured that the majority of the information
- in this Guide is directly applicable to the @jetty.product.name@ and they can simply ignore the @tomcat.product.name@ specific sections.
- </para>
- </section>
-
- <section>
- <title>A Note for @nano.product.name@ Users</title>
- <para>
- @nano.product.name@ is a bit different than @kernel.product.name.short@ and @tomcat.product.name.short@.
- It is the smallest Virgo offering and takes performance to its limits, almost instantly booting up.
- @nano.product.name@ users will find a number of sections in this guide useful but sections that refer to
- <emphasis>plans, PARs and configuration deployment, regions, application scoping and libraries support</emphasis>
- are NOT relevant for @nano.product.name@ or @nano.product.name.short@ and should be ignored.
- This Virgo distribution relies on p2 for its provisioning, therefore is bound to p2 concepts such as <emphasis>p2 features and update sites</emphasis>.
- Note also that @nano.product.name@ includes Gemini.Web as its default web container implementation and uses its default configuration.
- </para>
- </section>
-
-</chapter>
\ No newline at end of file
diff --git a/user-guide/src/known-issues.xml b/user-guide/src/known-issues.xml
deleted file mode 100644
index 308e9e9..0000000
--- a/user-guide/src/known-issues.xml
+++ /dev/null
@@ -1,84 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<appendix id="known-issues">
- <title>Known Issues</title>
-
- <para>This section describes known issues that you might run into, along with corresponding workarounds. </para>
-
- <para>For the full list of known issues, see <ulink url="https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;order=Importance;classification=RT;product=Virgo">Virgo bugs in Eclipse Bugzilla</ulink>. The bugs are organised by component as well as by release. You can also use bugzilla to enter a new issue if you cannot find an existing issue that describes the problem you are running into, but it's probably worth asking on the <ulink url="http://www.eclipse.org/forums/index.php?t=thread&frm_id=159">Virgo community forum</ulink> first.</para>
-
- <section id="known-issues-firewall-timeout">
- <title>Timeout During Startup Due to Firewall Settings</title>
- <para>
- @project.name@ will fail to start correctly if it is prevented from
- connecting to needed ports by the firewall. Typically this manifests
- as error <literal>SPPM0003E</literal> . Configuring the firewall to
- allow @project.name@ process to bind to the necessary ports will prevent
- this error from occurring.
- </para>
- </section>
- <section id="known-issues-startup-timeout">
- <title>Timeout During Startup Due to Insufficient Resources</title>
- <para>
- @project.name@ will fail to start correctly if it is running on slow hardware or
- on a system with insufficient resources. Typically this manifests as error <literal>KE0004E</literal> .
- Configuring the <link linkend="configuring-kernel-properties">startup wait limit</link> will provide
- @project.name@ with more time for initialisation.
- </para>
- </section>
- <section id="known-issues-perm-gen-sun-vm">
- <title>OutOfMemoryError: PermGen Space Running on Sun JVM</title>
- <para>
- As a result of Sun Java bug
- <ulink url="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4957990">4957990</ulink>,
- the @project.name@ may consume more PermGen space than expected when running with the
- server HotSpot compiler. This problem may be resolved by configuring the
- <literal>JAVA_OPTS</literal> environment variable to specify an increased
- <literal>MaxPermSize</literal>, for example <literal>-XX:MaxPermSize=128M</literal>.
- </para>
- </section>
- <section id="alternate-serviceability-work">
- <title>Alternate <literal>serviceability</literal> and <literal>work</literal> Directories</title>
- <para>
- Although an alternate <literal>configuration</literal> directory may be specified on startup, there is no way to specify
- alternate <literal>serviceability</literal> or <literal>work</literal> directories. This is covered by
- <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=307737">bug 307737</ulink> which also describes a workaround.
- </para>
- </section>
- <section id="windows-deletion">
- <title>Problem Deleting Installation Directory under Windows</title>
- <para>
- Sometimes Microsoft Windows won't let you delete the @project.name@ Server installation directory, typically because of long paths
- inside the <literal>work</literal> directory.
- </para>
- <para>
- You can return the @project.name@ instance to a clean state by stopping @project.name@ if necessary and then running the startup script with the options
- <literal>-clean -noStart</literal>, after which you should be able to delete the installation directory.
- See <link linkend="cleaning-without-starting">Cleaning @tomcat.product.name@ without Starting it</link> for more information.
- </para>
- </section>
- <section id="long-work-paths">
- <title>Long Work Directory Paths under Windows</title>
- <para>
- Problems can arise under Windows when long paths are created in the <literal>work</literal> directory as artefacts are deployed.
- </para>
- <para>
- You can shorten some of these paths by preventing bundles from being unpacked during deployment.
- See <link linkend="configuring-deployment">Configuring Deployment</link> for more information.
- </para>
- </section>
- <section id="known-issues-jetty-restrictions">
- <title>@jetty.product.name@ Restrictions</title>
- <para>
- When using the @jetty.product.name@ the Hosted Repository application and the Snaps modular web technology are not supported.
- </para>
- </section>
- <section id="known-issues-shutdown-logs-shell">
- <title>Shutdown Log Messages in Telnet Shell</title>
- <para>
- When you use the <literal>shutdown</literal> shell command to stop Virgo Server for Apache Tomcat, the shutdown log messages appear in the shell terminal instead of in the terminal in which Virgo runs.
- See <link linkend="admin-shell-enable">Enabling Equinox Console</link> for more information. This is covered also by <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=351533">bug 351533</ulink>.
- </para>
- </section>
-</appendix>
diff --git a/user-guide/src/log-codes.xml b/user-guide/src/log-codes.xml
deleted file mode 100644
index dfe4f46..0000000
--- a/user-guide/src/log-codes.xml
+++ /dev/null
@@ -1,119 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<appendix id="log-codes"> <title>Event log codes</title>
-
-<section id="event-log-codes-format"> <title>Format of the event log codes</title>
-
-<para>
-Event log codes issued by @project.name@ have the general syntax
-<literal><XXnnnnL></literal> where:
-<informaltable frame="none" colsep="0" rowsep="0" pgwide="0">
- <tgroup cols="2">
- <colspec colwidth="1*"/>
- <colspec colwidth="6*"/>
- <tbody>
- <row>
-<entry><literal>XX</literal></entry>
-<entry>
-is a two-letter code (upper-case) identifying the area of the @project.name@ code which issued the log message;
-</entry>
-</row><row>
-<entry><literal>nnnn</literal></entry>
-<entry>
-is a four-digit message number; and
-</entry>
-</row>
-<row>
-<entry><literal>L</literal></entry>
-<entry>
-is a single-letter (upper-case) code identifying the level of the message.
-</entry>
-</row>
-</tbody>
-</tgroup>
-</informaltable>
-</para>
-
-<para>
-The two-letter codes are (this list is not complete):
-<informaltable frame="none" colsep="0" rowsep="0" pgwide="0">
- <tgroup cols="2">
- <colspec colwidth="1*"/>
- <colspec colwidth="6*"/>
- <tbody>
- <row>
-<entry><literal>AG</literal></entry> <entry><literal>org.eclipse.virgo.kernel.agent.dm</literal></entry>
- </row>
- <row>
-<entry><literal>DE</literal></entry> <entry><literal>org.eclipse.virgo.kernel.deployer.core</literal></entry>
- </row>
- <row>
-<entry><literal>HD</literal></entry> <entry><literal>org.eclipse.virgo.kernel.deployer.hot</literal></entry>
- </row>
- <row>
-<entry><literal>HR</literal></entry> <entry><literal>org.eclipse.virgo.apps.repository.core</literal></entry>
- </row>
- <row>
-<entry><literal>KE</literal></entry> <entry><literal>org.eclipse.virgo.kernel.core</literal></entry>
- </row>
- <row>
-<entry><literal>KS</literal></entry> <entry><literal>org.eclipse.virgo.kernel.services</literal></entry>
- </row>
- <row>
-<entry><literal>OF</literal></entry> <entry><literal>org.eclipse.virgo.kernel.osgi</literal></entry>
- </row>
- <row>
-<entry><literal>RP</literal></entry> <entry><literal>org.eclipse.virgo.repository</literal></entry>
- </row>
- <row>
-<entry><literal>TC</literal></entry> <entry><literal>org.eclipse.virgo.web.tomcat</literal></entry>
- </row>
- <row>
-<entry><literal>UR</literal></entry> <entry><literal>org.eclipse.virgo.kernel.userregion</literal></entry>
- </row>
- <row>
-<entry><literal>WE</literal></entry> <entry><literal>org.eclipse.virgo.web.core</literal></entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-</para>
-
-<para>
-The four-digit numbers identify the message text (with placeholders for inserted values). These are not listed here, but can be discovered by examining the files called
-<literal>EventLogMessages.properties</literal>, found in the relevant packages.
-</para>
-
-<para>
-The single-digit level code is one of:
-<informaltable frame="none" colsep="0" rowsep="0" pgwide="0">
- <tgroup cols="2">
- <colspec colwidth="1*"/>
- <colspec colwidth="6*"/>
- <tbody>
- <row>
-<entry><literal>E</literal></entry> <entry>Error level: enabled if level is <literal>ERROR</literal>.</entry>
-</row>
-<row>
-<entry><literal>W</literal></entry> <entry>Warning level: enabled if level is <literal>WARNING</literal> or above.</entry>
-</row>
-<row>
-<entry><literal>I</literal></entry> <entry>Info level: enabled if level is <literal>INFO</literal> or above.</entry>
-</row>
-<row>
-<entry><literal>D</literal></entry> <entry>Debug level: enabled if level is <literal>DEBUG</literal> or above.</entry>
-</row>
-<row>
-<entry><literal>T</literal></entry> <entry>Trace level: always enabled.</entry>
-</row>
-</tbody>
-</tgroup>
-</informaltable>
-There are never two messages with the same prefix and number, but with different levels.
-</para>
-
-</section>
-
-</appendix>
diff --git a/user-guide/src/repository.xml b/user-guide/src/repository.xml
deleted file mode 100644
index 816bb22..0000000
--- a/user-guide/src/repository.xml
+++ /dev/null
@@ -1,105 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="repository">
- <title>The Provisioning Repository</title>
- <section id="repository-introduction">
- <title>Overview of the Provisioning Repository</title>
- <para>
- This section describes the provisioning repository feature of @project.name@, the reasons for using it, and how to configure it.
- <note>
- This section is not applicable to @nano.product.name@. The provisioning mechanism used there is p2.
- </note>
- </para>
- <para>
- In most use cases, your application has a dependency on one or more separate artifacts; these artifacts might include OSGi bundles, configuration artifacts, third-party libraries, PARs or plans. A typical example is a Spring application that depends on a third-party library such as Spring Framework or Hibernate.
- </para>
- <para>
- The way you express this dependency depends on the artifact. For example, a plan is by definition a list of dependent bundles.
- </para>
- <para>
- Libraries are another example. Some third-party dependencies consist of multiple bundles but are logically one unit. To support this, @project.name@ has a concept of a library. A library is a collection of related bundles that can be referenced as a whole. You typically express the dependencies between your application and third-party libraries using the <literal>Import-Package</literal>, <literal>Import-Bundle</literal>, or <literal>Import-Library</literal> manifest header in the <literal>MANIFEST.MF</literal> file of your application. The <literal>Import-Package</literal> header is standard to OSGi; <literal>Import-Bundle</literal> and <literal>Import-Library</literal>, however, are specific to @project.name@.
- </para>
- <para>
- For additional details about the creation and usage of libraries, as well as general information about dependencies, see <ulink url="../../virgo-programmer-guide/html/index.html">Programmer’s Guide</ulink>.
- </para>
- <para>
- In @project.name@, you store all third-party dependencies required by your applications, such as Spring Framework and Hibernate, as artifacts in the provisioning repository. As mentioned above, you can store the following types of artifacts in the repository:
- </para>
- <itemizedlist>
- <listitem>OSGi bundles</listitem>
- <listitem>Libraries</listitem>
- <listitem>PARs</listitem>
- <listitem>Plans</listitem>
- <listitem>Configuration Artifacts</listitem>
- </itemizedlist>
- <para>
- When you deploy your application, @project.name@ installs the bundle(s) comprising the application to the @project.name@ runtime; part of this internal installation procedure is to satisfy all the application’s dependencies. If your application has a dependency that cannot be satisfied from the bundles that you have already deployed (and @project.name@ has thus installed), then @project.name@ searches the provisioning repository for an artifact that can satisfy that dependency.
- </para>
- <para>
- The provisioning repository for a particular instance of @project.name@ can include artifacts in the following general locations:
- <itemizedlist>
- <listitem>Local: This means that artifacts have been physically installed in the provisioning repository directory structure of the local @project.name@ instance. The artifacts in a local repository include installed third-party libraries, bundles supplied by @project.name@, bundles supplied by an end user, and internal bundles used only by @project.name@. You can further categorize this location into <literal>external</literal> directories that adhere to a specified search pattern and are scanned by @project.name@ just on a clean startup, or <literal>watched</literal> directories that point to a single directory location and which @project.name@ scans on a regular basis. </listitem>
- <listitem>Remote: This means that a local instance of @project.name@ gets the artifact from a remotely-hosted repository that is physically located on a remote @tomcat.product.name@ instance. </listitem>
- </itemizedlist>
- You configure the provisioning repository using the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</literal> file.
- </para>
- <para> As previously described, a particular instance of @tomcat.product.name@ can itself also act as a repository host for remote server instances to use when satisfying the dependencies of the applications deployed to it. In this case, you configure a hosted repository using the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties</literal> file. Typically, only remote clients use hosted repositories and their contents; the @tomcat.product.name@ instance that actually hosts the repository does not typically use the artifacts in it. Rather, it uses artifacts in its local repository.
- </para>
- <para>
- Making a third-party dependency available to your application is simply a matter of adding its artifact to the appropriate location in the provisioning repository. This could be either in the local directories or the remote ones if you are getting artifacts from a remotely-hosted repository.
- </para>
- <section id="repository-structure">
- <title>Local Repository Structure</title>
- <para>
- When you first install @project.name@, the local provisioning repository is located at <literal>$SERVER_HOME/repository</literal> by default and consists of two main directories: <literal>ext</literal> and <literal>usr</literal>. The <literal>ext</literal> directory contains artifacts supplied with the @project.name@ and <literal>usr</literal> contains artifacts supplied by the user and is initially empty.
- </para>
- </section>
- <section id="repository-installing-bundles">
- <title>Installing Artifacts to a Repository</title>
- <para>
- To install an artifact into the default repository, simply copy it into the <literal>$SERVER_HOME/repository/usr</literal> directory.
- </para>
- <para>If you have configured additional watched or external repositories (additional, that is, to the default ones already configured in a freshly-installed @project.name@ instance), you install the artifacts in the same way: simply copy the files to the configured directories. You configure additional watched or external repositories in the same file as the default repositories: <literal>$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties</literal>.
- </para>
- <para>When you install a plan or a library into the repository, you must ensure that all referenced artifacts within the plan or library have been installed as well.
- </para>
- <para>Artifacts must have unique names so it is considered best practice to include the version number in the file name,
- allowing for multiple versions of the artifact to be installed at the same time. For example, a bundle file name might be <literal>my-exciting-bundle.2.1.0.jar</literal>.
- </para>
- <para>
- For watched repositories, such as <literal>$SERVER_HOME/repository/usr</literal>, @project.name@ automatically detects changes
- at runtime, thereby avoiding the need to restart @project.name@.
- </para>
- <para>
- Of specific relevance during development is picking up changes to an application’s direct dependencies during deployment of the application. For example, if you deploy an application and receive a message that a dependency is missing, you can simply add the dependency to the repository and then redeploy the application. The redeploy will cause the new dependency to be picked up, allowing progress to be made without restarting @project.name@. For other changes such as addition of optional dependencies, @project.name@ must be restarted to pick up any changes to the provisioning repository.
- </para>
- </section>
- </section>
- <section id="repository-brits">
- <title>Downloading Bundles from the @ebr@</title>
- <para>
- The @ebr@ is a public collection of open source libraries commonly used for developing enterprise Java applications with the Spring Framework and @project.name@. It contains hundreds of the most popular enterprise Java libraries made available for general use in an OSGi-ready format. You can browse the collection and then download the bundles that you need into your own local repository.
- </para>
- <para>
- The @ebr@ is located <ulink url="http://www.springsource.com/repository">here</ulink>.
- </para>
- <para>
- <imagedata fileref="images/bundle-repository.png"/>
- </para>
- <para>
- You can find bundles in the repository using a number of options. You use the ‘Search’ facility by typing in a keyword. The matching criteria returned can be explored by name, symbolic name, class, package or resource.
- </para>
- <para>
- There is also the option of clicking on ‘Browse by Bundle’. This gives an alphabetical list of bundles. You can select the desired bundle to see details and find the download link. Finally, you can also choose to ‘Browse by Library’, which allows you to browse the alphabetical list of libraries in the repository.
- </para>
- </section>
- <section id="repository-configuration">
- <title>Configuring the Repository</title>
- <para>Details of how to configure a @project.name@ installation’s provisioning repository can be found in <link linkend="configuring-provisioning-repository">Configuring the Provisioning Repository</link>. See <link linkend="configuring-hosted-repo">Configuring a Hosted Repository</link> for details of how to configure a repository that remote clients can access, also called a hosted repository.
- </para>
- <para>
- The two configuration sections describe the format of the repository properties files of @project.name@, how to add new directories to the local repository, how to configure the repository to get artifacts from a remote repository hosted on a remote @tomcat.product.name.short@ instance, and how to configure the local @tomcat.product.name.short@ instance to host a repository that other remote servers access.
- </para>
- </section>
-</chapter>
diff --git a/user-guide/src/serviceability.xml b/user-guide/src/serviceability.xml
deleted file mode 100644
index 42aaa1b..0000000
--- a/user-guide/src/serviceability.xml
+++ /dev/null
@@ -1,204 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="serviceability">
- <title>Serviceability and Diagnostics</title>
-
-<para>
- @project.name@ supports two kinds of logging: <emphasis>Event Logging</emphasis> and <emphasis>Trace logging</emphasis> which is usually referred
- to simply as <emphasis>Logging</emphasis>. The difference between Event Logging and Logging is explained below, but both are configured in the
- <literal>serviceability.xml</literal> file in the <literal>configuration</literal> directory. This file takes the form of a Logback configuration, @project.name@
- uses a Logback implementation behind the SLF4J logging interface.
- <para>
- For a description of the syntax and facilities provided by <literal>serviceability.xml</literal>
- see the <emphasis>Logback</emphasis> documentation (referenced in <xref linkend="furtherreading"/>).
- </para>
-</para>
-
- <section id="serviceability-info-log">
- <title>Event Logging</title>
- <para>
- Event logging records important events in @project.name@. Each event is logged to
- an event log file and is accompanied by a code enclosed in angle brackets.
- An example is shown below:
-<screen>
-[2010-10-25 16:20:45.897] system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme http on port 8080.
-</screen>
- (For a description of the log code syntax, see <xref linkend="log-codes"/>.)
- The format of event log messages is fully configurable.
- </para>
- <para>
- By default, event log messages are stored in <literal>$SERVER_HOME/serviceability/eventlogs/eventlog.log</literal>.
- </para>
- <para>
- The default behaviour is that, once <literal>eventlog.log</literal> reaches a 10Mb limit, it rolls into a series of files named
- <literal>eventlog_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and event logging continues in
- a new <literal>eventlog.log</literal> file.
- </para>
- </section>
-
- <section id="serviceability-info-trace">
- <title>(Trace) Logging</title>
- <para>
- The @project.name@’s (trace) logging support serves two main purposes:
- <itemizedlist>
- <listitem>
- It provides global trace files that capture high-volume information regarding the @project.name@’s internal events.
- The files are intended for use by support personnel to diagnose runtime problems.
- </listitem>
- <listitem>
- It provides application trace files that contain application-generated output. This includes output generated using popular logging and
- tracing APIs including the OSGi LogService, as well as output generated by calls to <literal>System.out</literal> and <literal>System.err</literal>.
- These files are intended for use by application developers and system administrators. An application is defined as a scope so a single bundle will
- not get its own log file unless it is a Web application Bundle or is included in a scoped plan or a par file.
- </listitem>
- </itemizedlist>
- </para>
- <para>
- By default, the @project.name@ trace file is called <literal>$SERVER_HOME/serviceability/logs/log.log</literal>,
- and, again by default, the application trace files are called <literal>$SERVER_HOME/serviceability/logs/</literal><emphasis>application_name</emphasis>
- <literal>/log.log</literal>, where <emphasis>application_name</emphasis> is automatically set by @project.name@ for each application artifact
- installed and run (it is a combination of the artifact name and the version).
- </para>
- <para>
- The default behaviour of these trace files is that, once <literal>log.log</literal> reaches a 10Mb limit, it rolls into a series of files named
- <literal>log_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and logging continues in
- a new <literal>log.log</literal> file.
- </para>
- <para>
- Entries in trace files are by default of the form <timestamp> <thread-name> <source> <level> <entry-text>. For example:
- <screen>
-[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080
- </screen>
- although this format is completely determined by the Logback configuration file <literal>serviceability.xml</literal>.
- </para>
- <section id="serviceability-info-trace-app">
- <title>Application Output</title>
- <para>
- @project.name@ provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a
- per-application basis and will also capture any <literal>System.out</literal> and <literal>System.err</literal> output.
- </para>
- <section id="per-application-trace">
- <title>Per-application trace</title>
- <para>
- @project.name@ uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output
- and appends it to the application-specific trace files as described above.
- To modify this, define application-specific loggers in the <literal>serviceability.xml</literal> file in the normal way.
- </para>
- </section>
- <section id="sysout-and-syserr">
- <title>System.out and System.err</title>
- <para>
- <literal>System.out</literal> and <literal>System.err</literal> output from applications is, by default, captured in the
- application’s trace file.
- This happens because the output streams are intercepted and written to the loggers named
- <literal>System.out</literal> and <literal>System.err</literal> respectively.
- Since there are no explicit loggers defined with these names in the <literal>serviceability.xml</literal> file,
- this output is logged by the root logger (which captures <literal>INFO</literal> level and above).
- </para>
- <para>
- The capture of <literal>System.out</literal> and <literal>System.err</literal> output is configured in the
- <literal>configuration/org.eclipse.virgo.medic.properties</literal> file by the <literal>log.wrapSysOut</literal> and
- <literal>log.wrapSysErr</literal> properties. By default the properties have a value of <literal>true</literal>
- and capture is enabled. Capture can be disabled by configuring the properties with a value of <literal>false</literal>.
- The third and last accepted value is <literal>tee</literal> which captures the System streams output in the logs
- while at the same time allows printing output to the System streams. Thus this output will appear both in the logs
- and in the System stream output - an example could be the Equinox console, launched with <literal>-console</literal> startup argument.
- </para>
- <important>
- If you provide value different than 'true | tee | false' then the server will default to 'tee' and print out a warning.
- </important>
- <para>
- The trace entries for <literal>System.out</literal> and <literal>System.err</literal>
- output are of the form:
- <screen>
-[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out Hello world!
-[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err Hello world!
- </screen>
- The third column indicates where the output came from (<literal>System.out</literal> or <literal>System.err</literal>).
- </para>
- <para>
- To over-ride this behaviour, simply define explicit loggers named <literal>System.out</literal>
- and/or <literal>System.err</literal> in the configuration file to send this output to an appender of your choice.
- Be aware that all applications’ output streams will be caught by these loggers, and that a sifting appender might be useful to separate them.
- </para>
- </section>
- <section id="janino">
- <title>Janino</title>
- <para>
- Janino can be used to define trace filters as Java expressions. This adds a significant overhead to tracing, so should be used with care.
- </para>
- <para>
- For example, the addition of the following filter element to the sifting appender in <literal>serviceability.xml</literal>
- suppresses per-application trace output that is not associated with a particular application and is normally written to
- <literal>serviceability/logs/virgo-kernel/log.log</literal>.
- <programlisting language="xml"><![CDATA[<appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender">
- <discriminator>
- <Key>applicationName</Key>
- <DefaultValue>virgo-kernel</DefaultValue>
- </discriminator>
- <sift>
- <appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
- <filter class="ch.qos.logback.core.filter.EvaluatorFilter">
- <evaluator class="ch.qos.logback.classic.boolex.JaninoEventEvaluator">
- <expression>
- (mdc == null) || (mdc.get("applicationName") == null)
- </expression>
- </evaluator>
- <OnMismatch>NEUTRAL</OnMismatch>
- <OnMatch>DENY</OnMatch>
- </filter>
- <file>serviceability/logs/${applicationName}/log.log</file>
- ...
- </appender>
- </sift>
-</appender>]]></programlisting>
- </para>
- <para>
- To enable Janino in @project.name@, place the Janino and commons compiler JARs, converted to OSGi bundles, in <literal>plugins</literal>.
- For example these bundles are available at v2.6.1 from the SpringSource Enterprise Bundle Repository.
- Then add the following lines to
- <literal>configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</literal>
- (as described in <link linkend="configuring-framework-bundles">Configuring OSGi Framework Bundles</link>):
- <programlisting><![CDATA[com.springsource.org.codehaus.janino,2.6.1,plugins/com.springsource.org.codehaus.janino-2.6.1.jar,4,false
-com.springsource.org.codehaus.commons.compiler,2.6.1,plugins/com.springsource.org.codehaus.commons.compiler-2.6.1.jar,4,false]]></programlisting>
- </para>
- <important>
- Current versions of Logback, including 0.9.28 to 1.0, do not set Janino's "parent" class loader correctly.
- This bug is covered by the Logback issue <ulink url="http://jira.qos.ch/browse/LBCORE-244">LBCORE-244</ulink>.
- With such versions, it is necessary to attach a fragment bundle to Janino. Place the fragment bundle in <literal>plugins</literal> and list it in
- <literal>configuration/org.eclipse.equinox.simpleconfigurator/bundles.info</literal>.
- The fragment's contents are described in <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=333920#c15">bug 333920</ulink>.
- </important>
- </section>
- </section>
- </section>
- <section id="serviceability-info-dump">
- <title>Service Dumps</title>
- <para>
- A service dump is triggered when one of the following events
- occurs:
- </para>
- <orderedlist numeration="arabic">
- <listitem>
- <para>
- A failure is detected in the @project.name@ code, or
- </para>
- </listitem>
- <listitem>
- <para>
- a thread deadlock is detected.
- </para>
- </listitem>
- </orderedlist>
- <para>
- A service dump contains a snapshot of all the important state from
- the running @project.name@ instance. This snapshot is not intended
- for end user consumption but is useful for service personnel.
- </para>
- <para>
- By default, service dumps are created in
- <literal>$SERVER_HOME/serviceability/dump</literal>.
- </para>
- </section>
-</chapter>
diff --git a/user-guide/src/starting-stopping.xml b/user-guide/src/starting-stopping.xml
deleted file mode 100644
index 1d64bce..0000000
--- a/user-guide/src/starting-stopping.xml
+++ /dev/null
@@ -1,414 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="starting-stopping" xreflabel="Starting and Stopping @tomcat.product.name@">
- <title>Starting and Stopping @tomcat.product.name@</title>
- <titleabbrev>Starting and Stopping @tomcat.product.name.short@</titleabbrev>
- <section>
- <title>Starting @tomcat.product.name@</title>
- <para>
- To start @tomcat.product.name@ run the <literal>startup.sh</literal> (Linux) or <literal>startup.bat</literal> (Windows) script.
- For both platforms, the script is located in the <literal>SERVER_HOME/bin</literal> directory.
- </para>
- <note>
- This chapter applies to @nano.product.name@ too. Note that since @nano.product.name.short@
- has a single region you can ignore the console output from the user region and focus on the instructions.
- A successful startup of @nano.product.name.short@ is as simple as that:
- <screen>[2011-12-28 11:41:31.528] startup-tracker <KE0001I> Kernel starting.
-[2011-12-28 11:41:31.602] startup-tracker <KE0002I> Kernel started.
- </screen>
- </note>
- <section>
- <title>Linux</title>
- <para>
- To start @tomcat.product.name@, open a terminal window and run <literal>startup.sh</literal>:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh</screen>
- <para>
- Once @tomcat.product.name@ has started, the console will display a log message
- similar to the one shown below, along with other status messages:
- </para>
-
- <screen>[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.</screen>
- <para>The preceding message indicates that you can start using @tomcat.product.name.short@.</para>
- </section>
- <section>
- <title>Microsoft Windows</title>
- <para>
- To start @tomcat.product.name@, open a command-window and run <literal>startup.bat</literal>:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat</screen>
- <para>
- Once @tomcat.product.name@ has started, the console will display a log message
- similar to the one shown below, along with other status messages:
- <screen>[2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready.</screen>
- <para>The preceding message indicates that you can start using @tomcat.product.name.short@.</para>
- </para>
- </section>
- </section>
- <section>
- <title>Starting in Clean Mode</title>
- <para>
- When you start @tomcat.product.name@ in clean mode, the startup script removes the <literal>SERVER_HOME/work</literal> directory (and hence all
- running applications) as well as all trace, log and dump files. It leaves the
- <literal>SERVER_HOME/repository</literal> and <literal>SERVER_HOME/pickup</literal> directories untouched,
- which means that any applications previously hot deployed will be automatically reinstalled.
- </para>
- <section>
- <title>Linux</title>
- <para>
- To start @tomcat.product.name@ in clean mode, open a terminal window and run <literal>startup.sh -clean</literal>:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -clean </screen>
- </section>
- <section>
- <title>Microsoft Windows</title>
- <para>
- To start @tomcat.product.name@ in clean mode, open a command window and run <literal>startup.bat -clean</literal>:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -clean</screen>
- </section>
- </section>
- <section>
- <title>Starting in Debug Mode</title>
- <section>
- <title>Linux</title>
- <para>
- To start @tomcat.product.name@ in debug mode, run
- <literal>startup.sh</literal> passing in the
- <literal>-debug</literal> argument:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -debug</screen>
- <para>
- This will start the debug agent listening on port
- <literal>8000</literal> which is the default remote debug port used
- by Eclipse. To start in debug mode with a specific port number, pass
- this in as the value for the <literal>-debug</literal> argument:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -debug 8001</screen>
- <para>
- This will start the debug agent listening on port
- <literal>8001</literal>. To start in debug mode and suspend the VM
- until a debugger attaches, pass in the <literal>-suspend</literal>
- argument along with the <literal>-debug</literal> argument:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -debug -suspend</screen>
- <para>
- This starts the debug agent, but prevents @tomcat.product.name@ from actually
- starting until a debugger attaches to the agent. This can be useful
- when trying to diagnose problems that occur during startup.
- </para>
- </section>
- <section>
- <title>Microsoft Windows</title>
- <para>
- To start @tomcat.product.name@ in debug mode, run
- <literal>startup.bat</literal> passing in the
- <literal>-debug</literal> argument:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -debug</screen>
- <para>
- This will start the debug agent listening on port
- <literal>8000</literal> which is the default remote debug port used
- by Eclipse. To start in debug mode with a specific port number, pass
- this in as the value for the <literal>-debug</literal> argument:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -debug 8001</screen>
- <para>
- This will start the debug agent listening on port
- <literal>8001</literal>. To start in debug mode and suspend the VM
- until a debugger attaches, pass in the <literal>-suspend</literal>
- argument along with the <literal>-debug</literal> argument:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -debug -suspend</screen>
- <para>
- This starts the debug agent, but prevents @tomcat.product.name@ from actually
- starting until a debugger attaches to the agent. This can be useful
- when trying to diagnose problems that occur during startup.
- </para>
- </section>
- </section>
- <section>
- <title>Starting with JMX Access Modifications</title>
- The @tomcat.product.name@ always starts with JMX access enabled, allowing you to use a management tool such as JConsole
- to attach to the Web Server instance.
- By default both local access and remote access over SSL with username and password
- authentication are provided. The default port for secure JMX access is <literal>9875</literal>
- and the default username and password are <literal>admin</literal> and <literal>springsource</literal>.
- <section>
- <title>Linux</title>
- <para>
- To start @tomcat.product.name@ with default JMX access enabled, run <literal>startup.sh</literal> passing
- in no arguments:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh </screen>
- <para>
- To start JConsole, run the <literal>jconsole.sh</literal> script, located in the <literal>bin</literal> directory, as shown:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/jconsole.sh </screen>
- <para>
- The following image shows how to specify a local connection using JConsole.
- </para>
- <para>
- <imagedata fileref="images/jmx-local-attach.png"/>
- </para>
- <para>
- The following image shows how to specify a remote connection in JConsole that uses SSL with the default
- username/password (<literal>admin/springsource</literal> and default secure port of <literal>9875</literal>).
- </para>
- <para>
- <imagedata fileref="images/jmx-remote-attach-default.png"/>
- </para>
- <para>
- To start with the JMX remote access on a specific port number other than the default <literal>9875</literal>,
- pass this port number in as the value
- of the <literal>-jmxport</literal> argument:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -jmxport 9090</screen>
- <para>
- This will start the @tomcat.product.name@ with JMX enabled for remote connections on port <literal>9090</literal>.
- </para>
- <para>
- <imagedata fileref="images/jmx-remote-attach-jmxport.png"/>
- </para>
-
- <para>To start the JMX remote access with a custom username and password, update the <literal>$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties</literal> file. First specify the custom username by changing the value of the <literal>role.admin</literal> property. Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user. Finally, restart @tomcat.product.name.short@ for the changes to take effect.</para>
- <para>For example, if you want change the JMX remote access username to <literal>zebedee</literal> with password <literal>florence</literal>, change the file as follows:
- </para>
- <programlisting>##################
-# User definitions
-##################
-user.zebedee=florence
-
-
-##################
-# Role definitions
-##################
-role.admin=zebedee</programlisting>
- <para>Specify the custom username in JConsole as shown. </para>
- <para>
- <imagedata fileref="images/jmx-remote-attach-jmxusers.png"/>
- </para>
- <para>
- To start the JMX remote access using a custom SSL certificate, edit the file located at
- <literal>$SERVER_HOME/configuration/keystore</literal>. If you wish to use a different keystore,
- pass this filename in as the value for the <literal>-keystore</literal> argument and the keystore
- password in as the value for the <literal>-keystorePassword</literal> argument:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword</screen>
- <para>
- This will start the @tomcat.product.name@ with JMX enabled for remote connections using an SSL certificate from
- <literal>customKeystore</literal> with a password of <literal>customKeystorePassword</literal>.
- </para>
- </section>
- <section>
- <title>Microsoft Windows</title>
- <para>
- To start @tomcat.product.name@ with default JMX access enabled, run <literal>startup.bat</literal> passing
- in no arguments:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat</screen>
- <para>
- To start JConsole, run the <literal>jconsole.bat</literal> script, located in the <literal>bin</literal> directory, as shown:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\jconsole.bat </screen>
- <para>
- The following image shows how to specify a local connection using JConsole.
- </para>
- <para>
- <imagedata fileref="images/jmx-local-attach.png"/>
- </para>
- <para>
- The following image shows how to specify a remote connection in JConsole that uses SSL with the default
- username/password (<literal>admin/springsource</literal> and default secure port of <literal>9875</literal>).
- </para>
- <para>
- <imagedata fileref="images/jmx-remote-attach-default.png"/>
- </para>
- <para>
- To start with the JMX remote access on a specific port number other than the default <literal>9875</literal>,
- pass this port number in as the value of the <literal>-jmxport</literal> argument:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -jmxport 9090</screen>
- <para>
- This will start the @tomcat.product.name@ with JMX enabled for remote connections on port
- <literal>9090</literal>.
- </para>
- <para>
- <imagedata fileref="images/jmx-remote-attach-jmxport.png"/>
- </para>
- <para>To start the JMX remote access with a custom username and password, update the <literal>%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties</literal> file. First specify the custom username by changing the value of the <literal>role.admin</literal> property. Then set the password of this new user by adding a new property called <literal>user.<emphasis>username</emphasis></literal>, where <literal><emphasis>username</emphasis></literal> refers to the actual name of the user. Finally, restart @tomcat.product.name.short@ for the changes to take effect.</para>
- <para>For example, if you want change the JMX remote access username to <literal>zebedee</literal> with password <literal>florence</literal>, change the file as follows:
- </para>
- <programlisting>##################
-# User definitions
-##################
-user.zebedee=florence
-
-
-##################
-# Role definitions
-##################
-role.admin=zebedee</programlisting>
- <para>Specify the custom username in JConsole as shown. </para>
- <para>
- <imagedata fileref="images/jmx-remote-attach-jmxusers.png"/>
- </para>
- <para>
- To start the JMX remote access using a custom SSL certificate, edit the file located at
- <literal>%SERVER_HOME%\configuration\keystore</literal>. If you wish to use a different
- keystore, pass this filename in as the value for the <literal>-keystore</literal> argument and the
- keystore password in as the value for the <literal>-keystorePassword</literal> argument:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword</screen>
- <para>
- This will start the @tomcat.product.name@ with JMX enabled for remote attach using an SSL certificate from
- <literal>customKeystore</literal> with a password of <literal>customKeystorePassword</literal>.
- </para>
- </section>
- </section>
- <section id="starting-stopping-configuration-directory">
- <title>Starting with a Custom Configuration Directory</title>
- <para>
- Use the <literal>-configDir</literal> option to specify an alternate <literal>configuration</literal> directory, different from the
- default <literal>SERVER_HOME/configuration</literal> directory. This option allows you to use the same @tomcat.product.name@
- installation to run multiple instances of @tomcat.product.name.short@. Simply create a configuration directory for each
- instance, specify unique port numbers, logging and tracing directories, and so on, and then specify that directory
- when starting @tomcat.product.name.short@.
- </para>
- <para>
- If you specify a relative path for the <literal>-configDir</literal> parameter,
- the startup script interprets the path as relative to the root of the @tomcat.product.name@ installation,
- and not relative to the directory from which you execute the <literal>startup</literal> script.
- </para>
- <para>
- See <link linkend="alternate-serviceability-work">Alternate <literal>serviceability</literal> and <literal>work</literal>
- Directories</link> for a known issue related to specifying an alternate <literal>configuration</literal> directory.
- </para>
- <section>
- <title>Linux</title>
- To start @tomcat.product.name@ using a configuration directory of <literal>/configuration/node1</literal>:
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -configDir /configuration/node1</screen>
- </section>
- <section>
- <title>Windows</title>
- To start @tomcat.product.name@ using a configuration directory of <literal>c:\configuration\node1</literal>:
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -configDir c:\configuration\node1</screen>
- </section>
- </section>
- <section>
- <title>Stopping @tomcat.product.name@</title>
- <section>
- <title>Linux</title>
- <para>
- To stop a running instance of @tomcat.product.name@, start a new terminal window and run the <literal>shutdown.sh</literal> script:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/shutdown.sh</screen>
- <para>
- To stop a running instance of @tomcat.product.name@ immediately, bypassing normal shutdown
- processing, run <literal>shutdown.sh</literal> with the <literal>-immediate</literal> option:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/shutdown.sh -immediate</screen>
- <para>
- If, when you started the Web Server instance, you used the <literal>-jmxport</literal> option to specify a non-default JMX port number,
- then you must pass this port number to the <literal>-jmxport</literal> of the <literal>shutdown.sh</literal> script
- to gracefully shut it down.
- For example, if you specified <literal>9090</literal> as the JMX port, use the following to shut down the Web Server instance:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/shutdown.sh -jmxport 9090</screen>
- </section>
- <section>
- <title>Microsoft Windows</title>
- <para>
- To stop a running instance of @tomcat.product.name@, start a new console window and run the <literal>shutdown.bat</literal> script:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\shutdown.bat</screen>
- <para>
- To stop a running instance of @tomcat.product.name@ immediately, bypassing normal shutdown
- processing, run <literal>shutdown.bat</literal> with the <literal>-immediate</literal> option:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\shutdown.bat -immediate</screen>
- <para>
- If, when you started the Web Server instance, you used the <literal>-jmxport</literal> option to specify a non-default JMX port number,
- then you must pass this port number to the <literal>-jmxport</literal> of the <literal>shutdown.bat</literal> script to gracefully shut it down.
- For example, if you specified <literal>9090</literal> as the JMX port, use the following to shut down the Web Server instance:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\shutdown.bat -jmxport 9090</screen>
- </section>
- </section>
- <section id="cleaning-without-starting">
- <title>Cleaning @tomcat.product.name@ without Starting it</title>
- <para>
- When you clean @tomcat.product.name@, the startup script removes the <literal>SERVER_HOME/work</literal> directory (and hence all
- running applications) as well as all trace, log and dump files. It leaves the
- <literal>SERVER_HOME/repository</literal> and <literal>SERVER_HOME/pickup</literal> directories untouched,
- which means that any applications previously hot deployed will be automatically reinstalled next time the Web Server is started.
- </para>
- <para>
- Cleaning is useful when you want to start the Web Server from a clean state next time, but you don't want to start the Web Server yet.
- </para>
- <para>
- Cleaning is also useful for tidying up the directory structure. For example, sometimes Microsoft Windows won't let you delete the Web
- Server installation directory.
- See <link linkend="windows-deletion">Problem Deleting Installation Directory under Windows</link> for more details.
- </para>
- <section>
- <title>Linux</title>
- <para>
- To clean @tomcat.product.name@, open a terminal window and run <literal>startup.sh -clean -noStart</literal>:
- </para>
- <screen>prompt$ cd $SERVER_HOME
-prompt$ bin/startup.sh -clean -noStart</screen>
- </section>
- <section>
- <title>Microsoft Windows</title>
- <para>
- To clean @tomcat.product.name@, open a command window and run <literal>startup.bat -clean -noStart</literal>:
- </para>
- <screen>prompt> cd %SERVER_HOME%
-prompt> bin\startup.bat -clean -noStart</screen>
- </section>
- </section>
- <section id="equinox-launcher">
- <title>Using Equinox Launcher</title>
- <para>
- Since version 3.5 @project.name@ uses the standard Equinox Launcher as its default launcher.
- As a result in addition to all the launcher options described so far users can also pass arguments specific to the Equinox launcher.
- <important>The Equinox Launcher arguments must be placed at the end of the startup call. Here's an example
- <screen>./startup.sh "virgo-args" "equinox-launcher-args"
-./startup.sh -clean -console 2222</screen>
- </important>
- </para>
- <para>
- A full list of the accepted Equinox Launcher arguments is available at <ulink url="http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html">help.eclipse.org</ulink>.
- </para>
- </section>
-
-</chapter>
-
diff --git a/user-guide/src/using-the-p2-director.xml b/user-guide/src/using-the-p2-director.xml
deleted file mode 100644
index a2dc356..0000000
--- a/user-guide/src/using-the-p2-director.xml
+++ /dev/null
@@ -1,88 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="using-the-p2-director">
- <title>Using the p2 director</title>
- <section id="prereqs">
- <title>Prerequisites</title>
- <para>
- The @tomcat.product.name@, or @tomcat.product.name.short@ for short, requires Java SE 6 or later to be installed. Java is available from
- <ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.
- </para>
- <para>
- Since you're going to use the p2 director you'll need to get it. The easiest way is to download Eclipse from <ulink url="http://www.eclipse.org/downloads/">here</ulink>.
- It has built-in p2 director and other p2 applications.
- </para>
- <important>
- <title>Setting the Target Platform</title>
- </important>
- <para>Before using the director make sure you have a proper target platform set. Otherwise you may not see the director application. Here's how to do that:</para>
- <para>Go to Eclipse's Preferences->Plug-in Development->Target Platform. Below is shown how the view looks like when a default target platform is set.</para>
- <para>
- <imagedata fileref="images/target-platform-view.png"/>
- </para>
- <para>If for some reason you don't have any target platform set or it's not the default one you must set the default target platform from the image above.</para>
- <para>If the default target platform is missing then add a new one via the <emphasis>Add...</emphasis> button and select the <emphasis>Default</emphasis> radio button as shown below:</para>
- <para>
- <imagedata fileref="images/default-target-create.png"/>
- </para>
- <para>You can now click <emphasis>Next</emphasis> and then <emphasis>Finish</emphasis>.</para>
- </section>
- <section id="using-director">
- <title>Installing with the p2 director from Eclipse</title>
- <para>
- This section covers briefly using the p2 director for installing.
- A helpful page is the p2 director's <ulink url="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html">documentation at help.eclipse.org</ulink>.
- There you can find more information on the different supported arguments.
- </para>
- <para>
- Here's how to use the GUI version of the director built-in Eclipse.
- </para>
- <para>
- 1. Go to the <emphasis>Run</emphasis> context menu and select <emphasis>Run Configurations</emphasis>
- </para>
- <para>
- 2. Create a new one and choose the director application as shown below, then switch to the <emphasis>Arguments</emphasis> tab
- </para>
- <important>In the image below the "Location:" text box's value is managed by your IDE, don't type anything in there.</important>
- <para>
- <imagedata fileref="images/run_configuration.png"/>
- </para>
- <para>
- In the <emphasis>Program Arguments</emphasis> section append the director arguments. Here's an example I used:
- <screen>-repository @p2repo@
--installIU nano.product
--tag InitialState
--destination <emphasis role="bold">/Users/<youruser>/install/virgo</emphasis>
--profile VirgoProfile
--roaming
--p2.os ${target.os}
--p2.ws ${target.ws}
--p2.arch ${target.arch}
- </screen>
- <important>
- <para>The <emphasis>-repository</emphasis> argument accepts any valid p2 repository.</para>
- <para>The <emphasis>-destination</emphasis> argument accepts any valid absolute location. It defines the location where your Virgo installation will be provisioned.
- If the directory does not exist, it will be created by the director.</para>
- </important>
- These arguments produce a @nano.product.name@ installation. For the <emphasis>p2.*</emphasis> arguments use the same properties from the example above. Eclipse will substitute them later with real values.
- </para>
- <para>
- The passed value for <emphasis>-installIU</emphasis> determines which Virgo product is going to be installed. Here's a list of all Virgo product install IUs:
- <para><emphasis>nano.product</emphasis> - @nano.product.name@</para>
- <para><emphasis>nano-full.product</emphasis> - @nano.product.name@ Full (@nano.product.name.short@ + p2 + GW)</para>
- <para><emphasis>kernel.product</emphasis> - @kernel.product.name@</para>
- <para><emphasis>tomcat-server.product</emphasis> - @tomcat.product.name@</para>
- <para><emphasis>jetty-server.product</emphasis> - @jetty.product.name@</para>
- </para>
- <para>
- <imagedata fileref="images/director_args.png"/>
- </para>
- <para>
- 3. Finally, run the created configuration. You should see the following output in Eclipse's Console
- </para>
- <para>
- <imagedata fileref="images/director_result.png"/>
- </para>
- </section>
-</chapter>
diff --git a/user-guide/src/virgo-user-guide.xml b/user-guide/src/virgo-user-guide.xml
deleted file mode 100644
index 62ac552..0000000
--- a/user-guide/src/virgo-user-guide.xml
+++ /dev/null
@@ -1,121 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<book xmlns:xi="http://www.w3.org/2001/XInclude">
- <bookinfo>
- <title>@project.name@ User Guide</title>
- <titleabbrev>User Guide</titleabbrev>
- <productname>@project.name@</productname>
- <releaseinfo>@bundle.version@</releaseinfo>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata align="center" fileref="images/virgo-logo-small.png" format="PNG" />
- </imageobject>
- <imageobject role="html">
- <imagedata align="right" fileref="images/virgo-logo-small.png" format="PNG" />
- </imageobject>
- </mediaobject>
-
- <authorgroup>
- <author>
- <firstname>Rob</firstname>
- <surname>Harrop</surname>
- </author>
- <author>
- <firstname>Paul</firstname>
- <surname>Kuzan</surname>
- </author>
- <author>
- <firstname>Sam</firstname>
- <surname>Brannen</surname>
- </author>
- <author>
- <firstname>Paul</firstname>
- <surname>Harris</surname>
- </author>
- <author>
- <firstname>Christopher</firstname>
- <surname>Frost</surname>
- </author>
- <author>
- <firstname>Ben</firstname>
- <surname>Hale</surname>
- </author>
- <author>
- <firstname>Glyn</firstname>
- <surname>Normington</surname>
- </author>
- <author>
- <firstname>Juliet</firstname>
- <surname>Shackell</surname>
- </author>
- <author>
- <firstname>Steve</firstname>
- <surname>Powell</surname>
- </author>
- <author>
- <firstname>Violeta</firstname>
- <surname>Georgieva</surname>
- </author>
- <author>
- <firstname>Hristo</firstname>
- <surname>Iliev</surname>
- </author>
- <author>
- <firstname>Borislav</firstname>
- <surname>Kapukaranov</surname>
- </author>
- </authorgroup>
-
- <legalnotice>
- <para>
- Copyright © 2009, 2011 VMware Inc. and others
- </para>
- <para>
- Contributors:
- <itemizedlist>
- <listitem>
- <para>
- VMware Inc. - initial contribution and subsequent updates
- </para>
- </listitem>
- <listitem>
- <para>
- Violeta Georgieva, SAP AG - Apache Tomcat configuration
- </para>
- </listitem>
- <listitem>
- <para>
- Hristo Iliev, SAP AG - Setting jmx.properties permissions
- </para>
- </listitem>
- <listitem>
- <para>
- Borislav Kapukaranov, SAP AG - Configuring framework extensions and fragments on system bundle; Added @nano.product.name@ references and tips
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc />
- <xi:include href="introduction.xml"/>
- <xi:include href="concepts.xml"/>
- <xi:include href="using-the-p2-director.xml"/>
- <xi:include href="installing.xml"/>
- <xi:include href="installing-kernel.xml"/>
- <xi:include href="installing-nano.xml"/>
- <xi:include href="starting-stopping.xml"/>
- <xi:include href="admin-shell.xml"/>
- <xi:include href="admin-console.xml"/>
- <xi:include href="repository.xml"/>
- <xi:include href="serviceability.xml"/>
- <xi:include href="applications.xml"/>
- <xi:include href="configuring.xml"/>
- <xi:include href="log-codes.xml"/>
- <xi:include href="known-issues.xml"/>
- <xi:include href="further-reading.xml"/>
-
-</book>
