:virgo-name: Virgo
:version: 3.7.0.RELEASE

:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
:jetty-product-name-short: VJS
:kernel-product-name: Virgo Kernel
:kernel-product-name-short: VK
:nano-product-name: Virgo Nano
:nano-product-name-short: VN
:user-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-${version}/docs/virgo-user-guide/html/index.html[User Guide]
:tooling-guide: http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html[Tooling Guide]

:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]

:spring-framework-version: 4.2.9.RELEASE

:homepage: https://www.eclipse.org/virgo
:ebr: http://www.eclipse.org/ebr[EBR]

:imagesdir: assets/images

== Introduction to the {tomcat-product-name}

=== Overview

In this chapter, we provide an overview of the {tomcat-product-name} focusing
on what it is, what benefits it provides to developers and administrators,
and why you should use it.

anchor:introduction-what[]

=== What is the {tomcat-product-name}?

The {tomcat-product-name}, or {tomcat-product-name-short} for short, is the runtime portion of the {umbrella-virgo-name}.
It is a lightweight, modular, OSGi-based runtime that provides a complete packaged solution for developing,
deploying, and managing enterprise applications.
By leveraging several best-of-breed technologies and improving upon
them, the {tomcat-product-name-short} offers a compelling solution to develop and deploy
enterprise applications.

anchor:introduction-constituents[]

==== What Makes up the {tomcat-product-name}?

The {tomcat-product-name} is built on top of the following core technologies:

* https://projects.spring.io/spring-framework/[Spring Framework], obviously!
* http://tomcat.apache.org/[Tomcat] as the web container.
* http://www.osgi.org/Specifications/HomePage[OSGi R4.3].
* http://www.eclipse.org/equinox/[Equinox] as the OSGi implementation.
* https://eclipse.org/gemini/blueprint/[Gemini Blueprint] for working with OSGi in a Spring application.
* {tooling-guide} for developing applications.

Note, however, that the {tomcat-product-name} isn't just a combination
of these technologies. Rather, it integrates and extends these
technologies to provide many features essential for developing,
deploying, and managing today's enterprise Java applications.

The following diagram presents a high-level overview of the {tomcat-product-name-short}'s architecture.

image:introduction-architecture.png[]

At the heart of the {tomcat-product-name} is the {kernel-product-name} or {kernel-product-name-short}.
The {kernel-product-name-short} is an OSGi-based kernel that takes full advantage of the modularity
and versioning of the OSGi platform. The {kernel-product-name-short} builds on a base version of {nano-product-name} or {nano-product-name-short} and extends its capabilities for
provisioning and library management, as well as providing core functionality for the {tomcat-product-name-short}. The {nano-product-name-short} maintains a minimal
runtime footprint and startup time. It builds on top of a pure Equinox, extending it with more sophisticated diagnostics and supportability functionality.
The {nano-product-name-short} supports full p2 provisioning. This feature is not included in the Virgo Nano Base that the {kernel-product-name-short} is built on.

To maintain a minimal runtime footprint, OSGi bundles are installed on demand by the
{nano-product-name-short}. On subsequent restarts these core bundles are warm-started thus reducing the startup time. This allows for an application to be installed
into a running {tomcat-product-name-short} and for its dependencies to be satisfied from an external repository. Not only
does this remove the need to manually install all your application dependencies, which would be tedious, but it also keeps memory usage to a minimum.

As shown in the figure, {kernel-product-name-short} runs on top of {nano-product-name-short} that extends Equinox within a standard Java
Virtual Machine. Above the {kernel-product-name-short} further layers contribute functionality
to the {tomcat-product-name-short}. Such as management and web application support.

Version {version} of the {tomcat-product-name} supports *bundle*,
*plan*, *PAR*, *configuration*,
*Web Application Bundle (WAB)*, and *WAR* artifacts, which enable
you to build sophisticated web applications. This includes support for
standard Java EE WARs, "shared library" WARs, and "shared services" WARs, each of
which will be covered in greater detail in xref:architecture[].

[IMPORTANT]
--
The {nano-product-name} has a different provisioning system which isn't included in the Virgo Nano Base on which the
{kernel-product-name-short} and the {tomcat-product-name-short} are built.
--

Version {version} of the {nano-product-name} supports *bundle*,
*p2 feature*, *Web Application Bundle (WAB)*, and *WAR* artifacts, which enable
you to build sophisticated web applications too, taking full advantage of p2's dependency resolution, automated download and fail-early mechanics.
The {nano-product-name} does NOT support *plan*, *PAR* or *configuration* artifacts.
New *features* are provisioned via *update sites* or *p2 repositories*.
Brief overview of p2 and it's mechanics is available on http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/[this blog].
The {nano-product-name-short}'s default web container implementation is Gemini Web.

anchor:introduction-why[]

=== Why the {tomcat-product-name}?

You could deploy a web application in a stand-alone servlet engine or application server.
Or you could even deploy directly in an OSGi container such as Equinox. However,
deploying in the {tomcat-product-name} offers a number of key benefits that make it both more
appealing and more suitable for enterprise application development.

anchor:introduction-unified-deployment[]

==== Deployment Options and Migration Paths

While many applications deployed in the {tomcat-product-name} will take advantage
of OSGi capabilities, not all applications need such sophistication.
For example, development teams may initially choose to continue packaging
existing web applications as standard WAR files and then gradually migrate
toward a fully OSGi-based packaging and deployment model. The {tomcat-product-name}
makes such migrations easy for developers by supporting multiple packaging
and deployment formats. These formats and migration strategies are discussed
in greater detail in xref:migrating-to-osgi[] and
xref:formtags-case-study[].

anchor:introduction-simplified-deployment[]

==== Simplified Development and Deployment of OSGi-based Applications

Prior to the release of the {tomcat-product-name}, developing and deploying OSGi
applications involved inherent complexity such as:

* *Obtaining OSGi bundles for popular Java libraries:*
For optimal benefits, every technology you use in an OSGi application must
be packaged as OSGi bundles. Sometimes, this involves manually converting
JAR files into bundles and making sure that any libraries needed by those
bundles are also available as OSGi bundles. The {ebr} is a good source of
popular pre-bundled libraries.

* *Package management complexity:*
OSGi bundles use other bundles through `Import-Package` manifest headers.
Many applications use a set of common technologies (e.g., an ORM solution,
a web framework, etc.). Combining these two characteristics leads to duplicated
configuration in the form of repeated and verbose `Import-Package` statements.

* *Lack of application-level isolation:*
In OSGi everything is a bundle, and all bundles share the same OSGi Service Registry.
To highlight how conflicts can arise between applications and their services in this
shared service registry, consider the following scenarios.

** Application `A` is comprised of bundles `B` and `C`.
In a standard OSGi environment, if you attempt to install two instances of the same
version of application `A` (i.e., two sets of bundles `B` and
`C`), a clash will occur, because you cannot deploy multiple bundles with
the same `Bundle-SymbolicName` and `Bundle-Version` combination.

** Application `A1` is comprised of bundles `B1` and `C1`.
Similarly, application `A2` is comprised of bundles `B2` and `C2`.
Each bundle has a unique combination of `Bundle-SymbolicName` and `Bundle-Version`.
Bundles `B1` and `B2` both export service `S` which
is imported by both `C1` and `C2`. In contrast to the previous
example, there is no conflict resulting from duplicate
`Bundle-SymbolicName`/`Bundle-Version` combinations; however,
there is a clash for the exported service `S`.
Which service `S` will bundles `C1` and `C2` end up
using once they are installed?
Assuming bundles `B1` and `C1` are intended to work together,
you would not want bundle `C1` to get a reference to service `S`
from bundle `B2`, because it is installed in a different logical application.
On the contrary, you typically want bundle `C1` to get a reference to
service `S` exported by bundle `B1`, but in a standard OSGi environment
this may not be the case.

Furthermore, since standard OSGi does not define a notion of an application as a set of bundles,
you cannot deploy or undeploy an application and its constituent bundles as a single unit.

The {tomcat-product-name} introduces a number of features to solve these issues:

* A full set of OSGi bundles for many popular Java libraries to get you
started quickly with creating OSGi applications.
* An OSGi library concept that obviates the need to
duplicate verbose `Import-Package` statements.
* The PAR packaging format which offers
application-level isolation and deployment.
* The concept of a plan, which is an XML file that lists a collection of bundles that {tomcat-product-name} should load together as a single application.  Conceptually, plans are very like PARs, except that a plan describes the contents of the application rather than a PAR that actually contains them.

anchor:introduction-diagnostics[]

==== Enhanced Diagnostics During Deployment and in Production

Identifying why an application won't deploy or which particular library
dependencies are unsatisfied is the cause of many headaches!
Similarly, production time errors that don't identify the root cause are
all too familiar to Java developers. The {tomcat-product-name-short} was designed from the
ground up to enable tracing and First Failure Data Capture (FFDC) that
empower developers with precise information at the point of failure to
fix the problem quickly.