Virgo User Guide

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:

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:

Import-Package: org.foo

A bundle which provides a package for use by other bundles must export the package in its manifest. For example:

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.

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 Services concepts.)

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 2.1. Bundle life cycle

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:

Export-Package: org.bar

…implement the interface with a class SomeImpl:

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 Spring DM or Blueprint to accomplish this. (See Spring DM concepts.)

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.

Bundle-Version: 1.4.3.BUILD-20090302

Export-Package: org.foo;version="2.9",org.bar;version="1"

Import-Package: org.foo;version="[2,3)",org.bar;version="[1,1]"

Bundle-ManifestVersion: 2

Manifest-Version: 1.0

Virgo Server for Apache Tomcat is distributed as a ZIP file. This can be downloaded from here.

Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.6.4.RELEASE can be found here. There is a repository for each released version.

As shown in Section 3.2, “Installing with the p2 director from Eclipse” you can easily install VTS in a desired destination. The only director argument that needs to be adjusted is -installIU.

For VTS the right value is tomcat-server.product.

When starting Virgo Server for Apache Tomcat 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.

If VTS starts correctly (see Starting and Stopping Virgo Server for Apache Tomcat) 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.

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’.

Within the security page select the ‘Advanced’ options. On the ‘Owner’ tab, choose the owner that you are trying to run the VTS as and select ‘Apply’.

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.

Once all these steps are complete you can proceed to start the VTS.

C:\dev\virgo-web-server-3.6.4.RELEASE>bin\startup.bat
[2009-12-08 13:09:09.545] startup-tracker              <KE0001I> Kernel starting.

Virgo Kernel is distributed as a ZIP file. This can be downloaded from here.

Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.6.4.RELEASE can be found here. There is a repository for each released version.

As shown in Section 3.2, “Installing with the p2 director from Eclipse” you can easily install VK in a desired destination. The only director argument that needs to be adjusted is -installIU.

For VK the right value is kernel.product.

Virgo Nano is distributed as a ZIP file. This can be downloaded from here.

Virgo has a single p2 repository that contains all Virgo distributions. The repository for version 3.6.4.RELEASE can be found here. There is a repository for each released version.

As shown in Section 3.2, “Installing with the p2 director from Eclipse” you can easily install VN in a desired destination. The only director argument that needs to be adjusted is -installIU.

For VN the right value is nano.product.

To start Virgo Server for Apache Tomcat, open a terminal window and run startup.sh:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh

Once Virgo Server for Apache Tomcat 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 VTS.

To start Virgo Server for Apache Tomcat, open a command-window and run startup.bat:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat

Once Virgo Server for Apache Tomcat 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 VTS.

To start Virgo Server for Apache Tomcat in clean mode, open a terminal window and run startup.sh -clean:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -clean 

To start Virgo Server for Apache Tomcat in clean mode, open a command window and run startup.bat -clean:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -clean

To start Virgo Server for Apache Tomcat in debug mode, run startup.sh passing in the -debug argument:

prompt$ cd $SERVER_HOME
prompt$ 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:

prompt$ cd $SERVER_HOME
prompt$ 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:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -debug -suspend

This starts the debug agent, but prevents Virgo Server for Apache Tomcat from actually starting until a debugger attaches to the agent. This can be useful when trying to diagnose problems that occur during startup.

To start Virgo Server for Apache Tomcat in debug mode, run startup.bat passing in the -debug argument:

prompt> cd %SERVER_HOME%
prompt> 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:

prompt> cd %SERVER_HOME%
prompt> 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:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -debug -suspend

This starts the debug agent, but prevents Virgo Server for Apache Tomcat from actually starting until a debugger attaches to the agent. This can be useful when trying to diagnose problems that occur during startup.

To start Virgo Server for Apache Tomcat with default JMX access enabled, run startup.sh passing in no arguments:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh 

To start JConsole, run the jconsole.sh script, located in the bin directory, as shown:

prompt$ cd $SERVER_HOME
prompt$ bin/jconsole.sh 

The following image shows how to specify a local connection using JConsole.

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).

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:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -jmxport 9090

This will start the Virgo Server for Apache Tomcat with JMX enabled for remote connections on port 9090.

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 VTS 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:

##################
# User definitions
##################
user.zebedee=florence


##################
# Role definitions
##################
role.admin=zebedee

Specify the custom username in JConsole as shown.

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:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword

This will start the Virgo Server for Apache Tomcat with JMX enabled for remote connections using an SSL certificate from customKeystore with a password of customKeystorePassword.

To start Virgo Server for Apache Tomcat with default JMX access enabled, run startup.bat passing in no arguments:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat

To start JConsole, run the jconsole.bat script, located in the bin directory, as shown:

prompt> cd %SERVER_HOME%
prompt> bin\jconsole.bat 

The following image shows how to specify a local connection using JConsole.

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).

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:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -jmxport 9090

This will start the Virgo Server for Apache Tomcat with JMX enabled for remote connections on port 9090.

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 VTS 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:

##################
# User definitions
##################
user.zebedee=florence


##################
# Role definitions
##################
role.admin=zebedee

Specify the custom username in JConsole as shown.

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:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword

This will start the Virgo Server for Apache Tomcat with JMX enabled for remote attach using an SSL certificate from customKeystore with a password of customKeystorePassword.

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -configDir /configuration/node1

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -configDir c:\configuration\node1

To stop a running instance of Virgo Server for Apache Tomcat, start a new terminal window and run the shutdown.sh script:

prompt$ cd $SERVER_HOME
prompt$ bin/shutdown.sh

To stop a running instance of Virgo Server for Apache Tomcat immediately, bypassing normal shutdown processing, run shutdown.sh with the -immediate option:

prompt$ cd $SERVER_HOME
prompt$ 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:

prompt$ cd $SERVER_HOME
prompt$ bin/shutdown.sh -jmxport 9090

To stop a running instance of Virgo Server for Apache Tomcat, start a new console window and run the shutdown.bat script:

prompt> cd %SERVER_HOME%
prompt> bin\shutdown.bat

To stop a running instance of Virgo Server for Apache Tomcat immediately, bypassing normal shutdown processing, run shutdown.bat with the -immediate option:

prompt> cd %SERVER_HOME%
prompt> 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:

prompt> cd %SERVER_HOME%
prompt> bin\shutdown.bat -jmxport 9090

To clean Virgo Server for Apache Tomcat, open a terminal window and run startup.sh -clean -noStart:

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -clean -noStart

To clean Virgo Server for Apache Tomcat, open a command window and run startup.bat -clean -noStart:

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -clean -noStart

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.

Use the bundle command to manage the lifecycle of bundles deployed in Virgo Kernel 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.

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
osgi> 

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]

osgi> 

Use the config command to view and manage the configuration artifacts that have been installed in Virgo Kernel. 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.

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

osgi> 

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-3.6.4.RELEASE.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> 

Use the packages command to view the complete list of packages exported by all bundles installed in Virgo Kernel, as well as examine a particular exported package in more detail.

The following table lists the options you can specify for this command.

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 ...>

osgi> 

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 ...>

osgi> 

Use the par command to view all the PARs currently installed in Virgo Kernel, 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.

The following example shows how to list the PARs that have been installed in Virgo Kernel:

osgi> vsh:par list

Name                                         Version                      State

org.eclipse.virgo.server.repository.hosted    2.1.0.RELEASE              ACTIVE

osgi> 

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

osgi> 

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

osgi> 

Use the plan command to view all the plans currently installed in Virgo Kernel, 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.

The following example shows how to list the plans that have been installed in Virgo Kernel:

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> 

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

osgi> 

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

osgi> 

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

osgi> 

Use the service command to view all the services that have been registered in the OSGi service registry of Virgo Kernel. 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.

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 ...>

osgi> 

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]

		osgi> 

Use the install command to deploy an artifact to Virgo Kernel. 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, Virgo Kernel 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 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
osgi>

The following example shows how to use the bundle list command to ensure that the bundle was indeed installed in Virgo Kernel; 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

osgi> 

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> 

Use the shutdown command to shut down the Virgo Kernel instance to which you are connected. When Virgo Kernel 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.
prompt$

Use the clhas command to list the entries contained in the bundles deployed in Virgo 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.

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]

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 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]

You can provision new features on top of your Virgo 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 installation folder>

This installs the latest version of the specified p2 feature in your Virgo installation's p2 profile.

Another way to achieve the same results is to use the p2 commands. The commands are available only in VN 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:

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 VN.

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:

##################
# User definitions
##################
user.juliet=capulet


##################
# Role definitions
##################
role.admin=juliet

The Admin Console always runs against the admin role.

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.

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.

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.

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. NOTE: This snapshot is not intended for end user consumption but is useful for service personnel.

Note that the dump entry osgi.zip is a binary OSGi state dump which should be viewed as described in 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).

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.

When you first install Virgo, 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 and usr contains artifacts supplied by the user and is initially empty.

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 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 automatically detects changes at runtime, thereby avoiding the need to restart Virgo.

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. For other changes such as addition of optional dependencies, Virgo must be restarted to pick up any changes to the provisioning repository.

Virgo 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.

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.

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.

<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, 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 Configuring OSGi Framework Bundles):

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

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 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 bug 333920.

	Note
	This section currently is ONLY relevant for Virgo Nano.

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 '.'.

	Note
	This section currently is ONLY relevant for Virgo Nano.

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.

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

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, Virgo Nano 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:

org.eclipse.virgo.fschecker.initialEventMode=bulk

To hot deploy an artifact, copy it into the pickup directory (by default $SERVER_HOME/pickup):

prompt$ cd /home/applications
prompt$ 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, VTS automatically starts the artifact so that it is immediately available to users.

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 Virgo Nano.

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

The Admin Console allows you to upload a file, which will be deployed automatically, from your local file system to the Virgo Server for Apache Tomcat. As soon as Virgo Server for Apache Tomcat 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 Installing a New Artifact for details about using the Admin Console to install (deploy) an artifact. See The Web Admin Console for general information about the Admin Console.

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, Virgo Server for Apache Tomcat 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 Virgo Server for Apache Tomcat will not do so.

When deploying bundles that have dependencies, it is important that you deploy them in the correct order. Virgo Server for Apache Tomcat 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.

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.

Virgo Server for Apache Tomcat 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.

To hot-undeploy an artifact, remove the corresponding file from the pickup directory (by default $SERVER_HOME/pickup):

prompt$ cd $SERVER_HOME/pickup
prompt$ rm helloWorld.war

When Virgo Server for Apache Tomcat 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'.

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-2.1.0.RELEASE.plan.

See 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.

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.

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 to fail.

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.

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 to fail.

The $SERVER_HOME/configuration/org.eclipse.virgo.medic.properties file configures Virgo 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 includes in addition to those supplied by the Logback, configured in the serviceability.xml file.

Logging support in Virgo is based on 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 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.

The following listing shows the default serviceability.xml file in a freshly-installed Virgo; see the text after the listing for a brief overview of the file:

<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 &lt;%X{medic.eventCode}&gt; %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 &lt;%X{medic.eventCode}&gt; %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 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 writes log messages to four different locations that map to the four appenders:

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 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 logback documentation for detailed information about the architecture and the configuration of Logback.

The main difference between a watched and an external repository is that Virgo regularly scans watched directories and automatically picks up any changed artifacts, while Virgo scans external directories only at startup, and then only if there is no cached index available. This means that Virgo 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 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 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 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 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.

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 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.

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.

The following examples provide sample configuration that could be used for some common use cases.

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

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

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

To change any of the kernel properties, provide the new value to the startup script. The following table describes all properties.

The configuration of the Virgo Kernel and User Region by default is located in the $SERVER_HOME/configuration directory:

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.

The following listing displays the default configuration distributed with Virgo; 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.

The User Region is the subsystem of Virgo 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 to fail. These properties are documented for your information.

packageImports=*;bundle-symbolic-name="org.eclipse.osgi",\
 ...

repository:type/name[/version]

initialArtifacts=...,\
 repository:plan/APlan,\
 repository:bundle/ABundle/1.0

Virgo uses the 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. 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 Tomcat servlet container. The virgo-kernel entry specifies that the JAAS LoginModule that Virgo 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 VTS 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 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 after you make this change for it to take effect.

The final file involved in Virgo 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.

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 Apache Tomcat Configuration Reference.

	Relative paths
	If the configured path to a directory or file does not represent an absolute path, Virgo typically interprets it as a path relative to the $SERVER_HOME directory.

The Virgo Server for Apache Tomcat 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 Tomcat HTTP Connector documentation.

	Configuring SSL for Tomcat
	The Virgo Server for Apache Tomcat distribution includes a preconfigured $SERVER_HOME/configuration/keystore file that contains a single self-signed SSL Certificate. The password for this keystore file is changeit. This keystore file is intended for testing purposes only. For detailed instructions on how to configure Tomcat’s SSL support, consult the official Tomcat SSL Configuration HOW-TO.

Virgo Server for Apache Tomcat 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 Tomcat Clustering/Session Replication HOW-TO for detailed information about enabling and configuring clustering.

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 Virgo Server for Apache Tomcat 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 VTS_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 VTS.

<?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.

Virgo Server for Apache Tomcat supports standard Apache Tomcat web application context configuration. The Apache Tomcat Configuration Reference has a section on The Context Container which describes the mechanism that is used in VTS 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:

Note that the following context configuration features are not supported in Virgo Server for Apache Tomcat:

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 Apache Tomcat Jasper 2 JSP Engine. org.apache.jasper.servlet.JspServlet configuration can be provided with the web application's web.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>