user-guide/src/docs/asciidoc/repository.adoc

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

:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
:jetty-product-name-short: VJS
:kernel-product-name: Virgo Kernel
:kernel-product-name-short: VK
:nano-product-name: Virgo Nano
:nano-product-name-short: VN
:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]

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

:spring-framework-version: 4.2.9.RELEASE

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

:imagesdir: assets/images

anchor:repository[]

== The Provisioning Repository

anchor:repository-introduction[]

=== Overview of the Provisioning Repository

This section describes the provisioning repository feature of {virgo-name}, the reasons for using it, and how to configure it.

[NOTE]
--
This section is not applicable to {nano-product-name}. The provisioning mechanism used there is p2.
--

In most use cases, your application has a dependency on one or more separate artifacts; these artifacts might include OSGi bundles, configuration artifacts, third-party libraries, PARs or plans.  A typical example is a Spring application that depends on a third-party library such as Spring Framework or Hibernate.

The way you express this dependency depends on the artifact.  For example, a plan is by definition a list of dependent bundles.

Libraries are another example.  Some third-party dependencies consist of multiple bundles but are logically one unit.  To support this, {virgo-name} has a concept of a library.  A library is a collection of related bundles that can be referenced as a whole.  You typically express the dependencies between your application and third-party libraries using the `Import-Package`, `Import-Bundle`, or `Import-Library` manifest header in the `MANIFEST.MF` file of your application.  The `Import-Package` header is standard to OSGi; `Import-Bundle` and `Import-Library`, however, are specific to {virgo-name}.

For additional details about the creation and usage of libraries, as well as general information about dependencies, see {programer-guide}.

In {virgo-name}, you store all third-party dependencies required by your applications, such as Spring Framework and Hibernate, as artifacts in the provisioning repository.   As mentioned above, you can store the following types of artifacts in the repository:

* OSGi bundles
* Libraries
* PARs
* Plans
* Configuration Artifacts

When you deploy your application,  {virgo-name} installs the bundle(s) comprising the application to the {virgo-name} runtime; part of this internal installation procedure is to satisfy all the application's dependencies.  If your application has a dependency that cannot be satisfied from the bundles that you have already deployed (and {virgo-name} has thus installed), then {virgo-name} searches the provisioning repository for an artifact that can satisfy that dependency.

The provisioning repository for a particular instance of {virgo-name} can include artifacts in the following general locations:

* Local: This means that artifacts have been physically installed in the provisioning repository directory structure of the local {virgo-name} instance.   The artifacts in a local repository include installed third-party libraries, bundles supplied by {virgo-name}, bundles supplied by an end user, and internal bundles used only by {virgo-name}.  You can further categorize this location into `external` directories that adhere to a specified search pattern and are scanned by {virgo-name} just on a clean startup, or `watched` directories that point to a single directory location and which {virgo-name} scans on a regular basis.
* Remote: This means that a local instance of {virgo-name} gets the artifact from a remotely-hosted repository that is physically located on a remote {tomcat-product-name} instance.

You configure the provisioning repository using the `$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties` file.

As previously described, a particular instance of {tomcat-product-name} can itself also act as a repository host for remote server instances to use when satisfying the dependencies of the applications deployed to it.  In this case, you configure a hosted repository using the `$SERVER_HOME/configuration/org.eclipse.virgo.apps.repository.properties` file.  Typically, only remote clients use hosted repositories and their contents; the {tomcat-product-name} instance that actually hosts the repository does not typically use the artifacts in it.  Rather, it uses artifacts in its local repository.

Making a third-party dependency available to your application is simply a matter of adding its artifact to the appropriate location in the provisioning repository.  This could be either in the local directories or the remote ones if you are getting artifacts from a remotely-hosted repository.

anchor:repository-structure[]

==== Local Repository Structure

When you first install {virgo-name}, the local provisioning repository is located at `$SERVER_HOME/repository` by default and consists of two main directories: `ext` and `usr`.  The `ext` directory contains artifacts supplied with the {virgo-name} and `usr` contains artifacts supplied by the user and is initially empty.

anchor:repository-installing-bundles[]

==== Installing Artifacts to a Repository

To install an artifact into the default repository, simply copy it into the `$SERVER_HOME/repository/usr` directory.

If you have configured additional watched or external repositories (additional, that is, to the default ones already configured in a freshly-installed {virgo-name} instance), you install the artifacts in the same way: simply copy the files to the configured directories.  You configure additional watched or external repositories in the same file as the default repositories: `$SERVER_HOME/configuration/org.eclipse.virgo.repository.properties`.

When you install a plan or a library into the repository, you must ensure that all referenced artifacts within the plan or library have been installed as well.

Artifacts must have unique names so it is considered best practice to include the version number in the file name,
allowing for multiple versions of the artifact to be installed at the same time.   For example, a bundle file name might be `my-exciting-bundle.2.1.0.jar`.

For watched repositories, such as `$SERVER_HOME/repository/usr`, {virgo-name} automatically detects changes
at runtime, thereby avoiding the need to restart {virgo-name}.

Of specific relevance during development is picking up changes to an application's direct dependencies during deployment of the application.  For example, if you deploy an application and receive a message that a dependency is missing, you can simply add the dependency to the repository and then redeploy the application.  The redeploy will cause the new dependency to be picked up, allowing progress to be made without restarting {virgo-name}.  For other changes such as addition of optional dependencies, {virgo-name} must be restarted to pick up any changes to the provisioning repository.

anchor:repository-brits[]

=== Downloading Bundles from the EBR

The {ebr} is a public collection of open source libraries commonly used for developing enterprise Java applications with the Spring Framework and {virgo-name}.  It contains hundreds of the most popular enterprise Java libraries made available for general use in an OSGi-ready format.  You can browse the collection and then download the bundles that you need into your own local repository.

The {ebr} is located http://www.springsource.com/repository[here].

image:bundle-repository.png[]

You can find bundles in the repository using a number of options.  You use the ‘Search' facility by typing in a keyword.  The matching criteria returned can be explored by name, symbolic name, class, package or resource.

There is also the option of clicking on ‘Browse by Bundle'.  This gives an alphabetical list of bundles.  You can select the desired bundle to see details and find the download link.  Finally, you can also choose to ‘Browse by Library', which allows you to browse the alphabetical list of libraries in the repository.

anchor:repository-configuration[]

=== Configuring the Repository

Details of how to configure a {virgo-name} installation's provisioning repository can be found in xref:configuring-provisioning-repository[Configuring the Provisioning Repository].  See xref:configuring-hosted-repo[Configuring a Hosted Repository] for details of how to configure a repository that remote clients can access, also called a hosted repository.

The two configuration sections describe the format of the repository properties files of {virgo-name}, how to add new directories to the local repository, how to configure the repository to get artifacts from a remote repository hosted on a remote {tomcat-product-name-short} instance, and how to configure the local {tomcat-product-name-short} instance to host a repository that other remote servers access.