511879 - Migrate User Guide and Developer Guide to Asciidoc
Change conflicting variable project-name to virgo-name.
diff --git a/user-guide/src/docs/asciidoc/admin-console.adoc b/user-guide/src/docs/asciidoc/admin-console.adoc
index dc5f144..8507fcc 100644
--- a/user-guide/src/docs/asciidoc/admin-console.adoc
+++ b/user-guide/src/docs/asciidoc/admin-console.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -215,4 +215,4 @@
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 {project-name} packages.
+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
index 05d566f..14d0328 100644
--- a/user-guide/src/docs/asciidoc/admin-shell.adoc
+++ b/user-guide/src/docs/asciidoc/admin-shell.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -206,9 +206,9 @@
| 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 {project-name} does not install unresolvable bundles.
+ 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 {project-name} after an update operation.
+ 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.
|=======================================================================
@@ -306,17 +306,17 @@
| 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 {project-name} does not currently support).
+ 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 {project-name} does not currently support). Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ | 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 {project-name} does not currently support). Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ | 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 {project-name} does not currently support). Use the `config list` command to view all configuration artifacts and versions currently installed in {kernel-product-name}.
+ | 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`.
|=======================================================================
@@ -650,7 +650,7 @@
Artifact bundle swf-booking-mvc.war 0.0.0 installed
....
-This command is particularly useful for installing an artifact from the {project-name} repository, in which case use the `repository:` scheme:
+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
@@ -728,7 +728,7 @@
==== clhas command
-Use the `clhas` command to list the entries contained in the bundles deployed in {project-name} and to solve class loading issues.
+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.
@@ -872,21 +872,21 @@
anchor:p2-commands[]
-=== Using the p2 for extending your {project-name} installation
+=== Using the p2 for extending your {virgo-name} installation
==== Extending with the p2 director
-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.
+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 {project-name} installation folder>
+-destination <your {virgo-name} installation folder>
....
-This installs the *latest* version of the specified p2 feature in your {project-name} installation's p2 profile.
+This installs the *latest* version of the specified p2 feature in your {virgo-name} installation's p2 profile.
==== Extending via the p2 shell commands
diff --git a/user-guide/src/docs/asciidoc/applications.adoc b/user-guide/src/docs/asciidoc/applications.adoc
index f4cc073..c53a4f1 100644
--- a/user-guide/src/docs/asciidoc/applications.adoc
+++ b/user-guide/src/docs/asciidoc/applications.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/concepts.adoc b/user-guide/src/docs/asciidoc/concepts.adoc
index e50a4f3..e0405a1 100644
--- a/user-guide/src/docs/asciidoc/concepts.adoc
+++ b/user-guide/src/docs/asciidoc/concepts.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -26,7 +26,7 @@
== Concepts
-This chapter introduces some basic concepts that will help you to use {project-name}.
+This chapter introduces some basic concepts that will help you to use {virgo-name}.
anchor:concepts.modular[]
@@ -42,7 +42,7 @@
=== OSGi Concepts
-Modules in {project-name} are represented using a standard Java
+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
@@ -62,7 +62,7 @@
An industry consortium known as the
*OSGi Alliance* develops OSGi
specifications, reference implementations, and compliance tests.
-{project-name} is built on the Equinox OSGi framework which is also
+{virgo-name} is built on the Equinox OSGi framework which is also
the reference implementation for the OSGi framework specification.
==== Bundles
@@ -309,7 +309,7 @@
Bundle manifests have a version which is `1` by default,
indicating OSGi Release 3 semantics.
-{project-name} is based on OSGi Release 4 and therefore expects bundle manifests to be
+{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:
@@ -357,11 +357,11 @@
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
+{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.
-{project-name} has Gemini Blueprint built-in.
+{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,
@@ -370,7 +370,7 @@
anchor:concepts.virgo[]
-=== {project-name} Concepts
+=== {virgo-name} Concepts
[NOTE]
--
@@ -381,11 +381,11 @@
==== The Provisioning Repository
-The {project-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 {project-name}, refreshed, or undeployed.
+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 {project-name} include configuration (properties file), PAR, plan, and library.
+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
@@ -393,34 +393,34 @@
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.
-{project-name}'s default repository configuration, in `configuration/org.eclipse.virgo.repository.properties`, specifies an external repository created from the
+{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 {project-name}.
+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 {project-name}, refreshed, or undeployed.
+into {virgo-name}, refreshed, or undeployed.
-{project-name}'s default repository configuration specifies a watched repository based on the contents of the `repository/usr` directory.
+{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 {project-name} instance sometimes known as a *repository server*.
+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 {project-name} instance sometimes known as a *repository client*.
-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
+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 {project-name} repository is configured as a *chain* of external, watched, and remote repositories.
+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
@@ -430,7 +430,7 @@
==== Grouping Bundles
-{project-name} provides a way of grouping together a collection
+{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.
@@ -441,12 +441,12 @@
but bundles outside the PAR file may not depend on packages and services
provided by the PAR file.
-{project-name} also provides the plan artifact as another way of grouping bundles and other artifacts into an application.
+{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 {project-name} provisioning repository.
+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, {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 `Import-Library` manifes header.
+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[]
diff --git a/user-guide/src/docs/asciidoc/configuring.adoc b/user-guide/src/docs/asciidoc/configuring.adoc
index 8afc983..2e3c5e9 100644
--- a/user-guide/src/docs/asciidoc/configuring.adoc
+++ b/user-guide/src/docs/asciidoc/configuring.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -30,7 +30,7 @@
== Configuration
Configuration
-You use configuration files in the `$SERVER_HOME/configuration` directory to configure {project-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:
+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]
@@ -45,7 +45,7 @@
[NOTE]
.Why is there both a config and a configuration directory?
--
-The *config* 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 *configuration* directory replaced the old *config* one. Now all {project-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.
+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.
--
@@ -84,7 +84,7 @@
[WARNING]
--
We strongly recommend that you update only the
-properties below; updating other properties could cause {project-name}
+properties below; updating other properties could cause {virgo-name}
to fail.
--
@@ -143,7 +143,7 @@
[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 {project-name} to fail.
+you are doing; updating the profile could cause {virgo-name} to fail.
--
anchor:configuring-framework-profile-table[]
@@ -156,7 +156,7 @@
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 {project-name} under a performance profiler.
+ 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.
@@ -175,7 +175,7 @@
=== 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
-{project-name}. This is because by refreshing or uninstalling them the system.bundle is also refreshed, which causes {project-name} to crash.
+{virgo-name}. This is because by refreshing or uninstalling them the system.bundle is also refreshed, which causes {virgo-name} to crash.
[NOTE]
--
@@ -187,7 +187,7 @@
You can configure framework extensions and system bundle fragments as follows:
-*1.* Place your fragment bundle in the `/plugins` directory of your {project-name} installation.
+*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*
@@ -214,13 +214,13 @@
=== Configuring Serviceability and Diagnostics
-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:
+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 {project-name} instance when an internal failure or thread deadlock is detected.
-You configure service dumps for {project-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.
+* 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 {project-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 {project-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 {project-name}.
+* 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" />.
@@ -228,19 +228,19 @@
==== The org.eclipse.virgo.medic.properties File
-The `$SERVER_HOME/configuration/org.eclipse.virgo.medic.properties` file configures {project-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 {project-name} includes in addition to those supplied by the Logback, configured in the `serviceability.xml` 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 {project-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 {project-name}'s root logger, which captures `INFO` level and above.
+| `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 {project-name}'s root logger, which captures `INFO` level and above.
+| `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`.
@@ -251,9 +251,9 @@
anchor:configuring-serviceability-logback[]
==== The serviceability.xml File
-Logging support in {project-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 {project-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 {project-name}.
-The following listing shows the default `serviceability.xml` file in a freshly-installed {project-name}; see the text after the listing for a brief overview of the 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]
----
@@ -340,13 +340,13 @@
</configuration>
----
-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 `serviceability.xml` file shown above includes four appenders and three loggers (two user and one root.)
+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 {project-name} writes log messages to four different locations that map to the four appenders:
+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 {project-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 `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*.
@@ -355,19 +355,19 @@
`[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 {project-name}. For example:
+* 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 {project-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.
+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 {project-name} includes in its 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:
@@ -379,12 +379,12 @@
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 {project-name} searches the individual repositories
+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 {project-name} instance is as follows:
+The default repository configuration for a newly installed {virgo-name} instance is as follows:
[source,txt]
----
@@ -397,9 +397,9 @@
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 {project-name}: `ext` and `usr`. {project-name} searches each of these individual repositories when locating entries for inclusion in the repository.
+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 {project-name} searches the individual repositories: first `ext` and then `usr`.
+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
@@ -412,13 +412,13 @@
| 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 {project-name} instance.
+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 {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.
+* `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 {project-name} checks the 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.
@@ -436,7 +436,7 @@
| *`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 {project-name} installation (`$SERVER_HOME`).
+ 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`
@@ -468,26 +468,26 @@
==== Should I Configure a Watched or External Repository?
-The main difference between a watched and an external repository is that {project-name} regularly scans watched directories
+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 {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
+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 {project-name} using resources
+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 {project-name} re-scans its local watched repositories when deploying any artifact, so the scanning interval
+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 {project-name} with the `-clean` option so that the server picks up any changes.
+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 {project-name} quickly and easily picks them up.
+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.
@@ -501,7 +501,7 @@
The *`repository-name`*`.searchPattern` and
*`repository-name`*`.watchDirectory` 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.
+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.
@@ -516,14 +516,14 @@
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, {project-name} also supports Ant-style paths,
+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 {project-name}.
+such as a local Maven repository, to be provisioned by the {virgo-name}.
anchor:configuring-provisioning-repository-using-system-properties[]
@@ -594,7 +594,7 @@
==== Add remote and watched repositories
The following example shows the default `org.eclipse.virgo.repository.properties` file
-from a freshly-installed {project-name} instance, but then updated to include new remote and watched repositories.
+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`.
@@ -660,7 +660,7 @@
* `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.
-{project-name} regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime.
+{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.
@@ -695,7 +695,7 @@
=== Configuring the Kernel and User Region
-This section provides information about configuring the {project-name} kernel and the User Region.
+This section provides information about configuring the {virgo-name} kernel and the User Region.
anchor:configuring-kernel-properties[]
@@ -733,7 +733,7 @@
|=======================================================================
| 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 {project-name}.
+| `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.
@@ -757,7 +757,7 @@
| 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 {project-name} times out while trying to deploy an artifact.
+| `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.
@@ -785,7 +785,7 @@
| `strict`
|=======================================================================
-The following listing displays the default configuration distributed with {project-name}; only relevant sections of the `org.eclipse.virgo.kernel.properties` file are shown.
+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
@@ -799,7 +799,7 @@
==== Configuring the User Region
-The User Region is the subsystem of {project-name} that
+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.
@@ -814,7 +814,7 @@
We strongly recommend that you update only the
`initialArtifacts`
property; updating other properties could cause
-{project-name} to fail. These properties are documented for your
+{virgo-name} to fail. These properties are documented for your
information.
--
@@ -823,17 +823,17 @@
.User Region Configuration Properties
|=======================================================================
| Property | Description
-| `baseBundles` | 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
+| `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 {project-name} imports into the User Region so that they are visible to bundles in the User Region.
+ | 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 {project-name} imports into the User Region so that they are in turn available to be
+| `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.
@@ -856,9 +856,9 @@
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 {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,
+| `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:
@@ -899,14 +899,14 @@
=== Configuring Authentication
-{project-name} uses the http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html[Java Authentication and Authorization Service (JAAS)]
+{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 {project-name}. The short file consists of the following entries:
+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 {
@@ -917,11 +917,11 @@
};
....
-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 {project-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 `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 {project-name} is as follows:
+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:
....
##################
@@ -958,9 +958,9 @@
role.admin=juliet
....
-Be sure to restart {project-name} after you make this change for it to take effect.
+Be sure to restart {virgo-name} after you make this change for it to take effect.
-The final file involved in {project-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:
+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
@@ -979,10 +979,10 @@
{nano-product-name} uses the default Gemini Web configuration. The details described below may still apply.
--
-{project-name}
+{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 {project-name} configuration files, the `tomcat-server.xml` file is located in the `$SERVER_HOME/configuration` directory.
+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.
@@ -1031,7 +1031,7 @@
[TIP]
.Relative paths
--
-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.
+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.
@@ -1324,5 +1324,5 @@
The {jetty-product-name} contains a standard Jetty configuration file at `SERVER_HOME/jetty/etc/jetty.xml`.
-This has been tailored to the {umbrella-project-name}. To make modifications please refer to the
+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
index f561446..099d873 100644
--- a/user-guide/src/docs/asciidoc/further-reading.adoc
+++ b/user-guide/src/docs/asciidoc/further-reading.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/installing-kernel.adoc b/user-guide/src/docs/asciidoc/installing-kernel.adoc
index 08f1df8..8ac00e1 100644
--- a/user-guide/src/docs/asciidoc/installing-kernel.adoc
+++ b/user-guide/src/docs/asciidoc/installing-kernel.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/installing-nano.adoc b/user-guide/src/docs/asciidoc/installing-nano.adoc
index 8ac5cc7..31b7148 100644
--- a/user-guide/src/docs/asciidoc/installing-nano.adoc
+++ b/user-guide/src/docs/asciidoc/installing-nano.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/installing.adoc b/user-guide/src/docs/asciidoc/installing.adoc
index 68da3f0..a6a6d34 100644
--- a/user-guide/src/docs/asciidoc/installing.adoc
+++ b/user-guide/src/docs/asciidoc/installing.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/introduction.adoc b/user-guide/src/docs/asciidoc/introduction.adoc
index eb30010..5571dac 100644
--- a/user-guide/src/docs/asciidoc/introduction.adoc
+++ b/user-guide/src/docs/asciidoc/introduction.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/known-issues.adoc b/user-guide/src/docs/asciidoc/known-issues.adoc
index 69c3a0c..131d528 100644
--- a/user-guide/src/docs/asciidoc/known-issues.adoc
+++ b/user-guide/src/docs/asciidoc/known-issues.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -36,20 +36,20 @@
=== Timeout During Startup Due to Firewall Settings
-{project-name} will fail to start correctly if it is prevented from
+{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 {project-name} process to bind to the necessary ports will prevent
+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
-{project-name} will fail to start correctly if it is running on slow hardware or
+{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
-{project-name} with more time for initialisation.
+{virgo-name} with more time for initialisation.
anchor:known-issues-perm-gen-sun-vm[]
@@ -57,7 +57,7 @@
As a result of Sun Java bug
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4957990[4957990],
-the {project-name} may consume more PermGen space than expected when running with the
+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`.
@@ -74,10 +74,10 @@
=== Problem Deleting Installation Directory under Windows
-Sometimes Microsoft Windows won't let you delete the {project-name} Server installation directory, typically because of long paths
+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 {project-name} instance to a clean state by stopping {project-name} if necessary and then running the startup script with the options
+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.
diff --git a/user-guide/src/docs/asciidoc/log-codes.adoc b/user-guide/src/docs/asciidoc/log-codes.adoc
index 90e7de2..da88edd 100644
--- a/user-guide/src/docs/asciidoc/log-codes.adoc
+++ b/user-guide/src/docs/asciidoc/log-codes.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -30,12 +30,12 @@
=== Format of the event log codes
-Event log codes issued by {project-name} have the general syntax
+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 {project-name} code which issued the log message;
+| `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.
|=======================================================================
diff --git a/user-guide/src/docs/asciidoc/repository.adoc b/user-guide/src/docs/asciidoc/repository.adoc
index bca001b..1ba4b99 100644
--- a/user-guide/src/docs/asciidoc/repository.adoc
+++ b/user-guide/src/docs/asciidoc/repository.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -30,7 +30,7 @@
=== Overview of the Provisioning Repository
-This section describes the provisioning repository feature of {project-name}, the reasons for using it, and how to configure it.
+This section describes the provisioning repository feature of {virgo-name}, the reasons for using it, and how to configure it.
[NOTE]
--
@@ -41,11 +41,11 @@
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, {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 `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 {project-name}.
+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 {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:
+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
@@ -53,12 +53,12 @@
* Plans
* Configuration Artifacts
-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.
+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 {project-name} can include artifacts in the following general locations:
+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 {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 `external` directories that adhere to a specified search pattern and are scanned by {project-name} just on a clean startup, or `watched` directories that point to a single directory location and which {project-name} scans on a regular basis.
-* 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.
+* 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.
@@ -70,7 +70,7 @@
==== Local Repository Structure
-When you first install {project-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 {project-name} and `usr` contains artifacts supplied by the user and is initially empty.
+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[]
@@ -78,23 +78,23 @@
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 {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: `$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties`.
+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`, {project-name} automatically detects changes
-at runtime, thereby avoiding the need to restart {project-name}.
+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 {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.
+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 {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.
+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].
@@ -108,6 +108,6 @@
=== Configuring the Repository
-Details of how to configure a {project-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.
+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 {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.
+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
index b995592..8bfc8e1 100644
--- a/user-guide/src/docs/asciidoc/serviceability.adoc
+++ b/user-guide/src/docs/asciidoc/serviceability.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -26,9 +26,9 @@
== Serviceability and Diagnostics
-{project-name} supports two kinds of logging: *Event Logging* and *Trace logging* which is usually referred
+{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, {project-name}
+`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`
@@ -38,7 +38,7 @@
=== Event Logging
-Event logging records important events in {project-name}. Each event is logged to
+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:
@@ -59,18 +59,18 @@
=== (Trace) Logging
-The {project-name}'s (trace) logging support serves two main purposes:
+The {virgo-name}'s (trace) logging support serves two main purposes:
-* It provides global trace files that capture high-volume information regarding the {project-name}'s internal events.
+* 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 {project-name} trace file is called `$SERVER_HOME/serviceability/logs/log.log`,
+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 {project-name} for each application artifact
+`/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
@@ -89,14 +89,14 @@
==== Application Output
-{project-name} provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a
+{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
-{project-name} uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output
+{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.
@@ -174,7 +174,7 @@
</appender>
----
-To enable Janino in {project-name}, place the Janino and commons compiler JARs, converted to OSGi bundles, in `plugins`.
+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`
@@ -202,11 +202,11 @@
A service dump is triggered when one of the following events
occurs:
-. A failure is detected in the {project-name} code, or
+. 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 {project-name} instance. This snapshot is not intended
+the running {virgo-name} instance. This snapshot is not intended
for end user consumption but is useful for service personnel.
diff --git a/user-guide/src/docs/asciidoc/starting-stopping.adoc b/user-guide/src/docs/asciidoc/starting-stopping.adoc
index 502be22..ce10809 100644
--- a/user-guide/src/docs/asciidoc/starting-stopping.adoc
+++ b/user-guide/src/docs/asciidoc/starting-stopping.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -458,7 +458,7 @@
=== Using Equinox Launcher
-Since version 3.5 {project-name} uses the standard Equinox Launcher as its default 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]
diff --git a/user-guide/src/docs/asciidoc/using-the-p2-director.adoc b/user-guide/src/docs/asciidoc/using-the-p2-director.adoc
index ffb5aec..048aa34 100644
--- a/user-guide/src/docs/asciidoc/using-the-p2-director.adoc
+++ b/user-guide/src/docs/asciidoc/using-the-p2-director.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
diff --git a/user-guide/src/docs/asciidoc/virgo-user-guide.adoc b/user-guide/src/docs/asciidoc/virgo-user-guide.adoc
index 00fff32..e5c4a15 100644
--- a/user-guide/src/docs/asciidoc/virgo-user-guide.adoc
+++ b/user-guide/src/docs/asciidoc/virgo-user-guide.adoc
@@ -1,7 +1,7 @@
-:project-name: Virgo
+:virgo-name: Virgo
:version: 3.7.0.RC01
-:umbrella-project-name: Eclipse Virgo
+:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
@@ -24,7 +24,7 @@
:experimental: true
:toc:
-= {project-name} User Guide
+= {virgo-name} User Guide
[%hardbreaks]
Rob Harrop
@@ -44,7 +44,7 @@
image::virgo-logo-small.png[Eclipse Virgo,float="right"]
[%hardbreaks]
-{umbrella-project-name}
+{umbrella-virgo-name}
{version}
Copyright (C) 2009, 2011 VMware Inc. and others
