13.4 Configuring the Local Provisioning Repository

You configure the locations that Virgo 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:

For example, ext.type=external specifies that the type property of the repository with name ext is external.

The chain property specifies the order in which Virgo searches the individual repositories when it looks for dependencies. The chain property uses the names of the individual repositories as specified in the individual repository properties; for example, in the property ext.type=external, the name of the repository is ext.

The default repository configuration for a newly installed Virgo instance is as follows:

ext.type=external
ext.searchPattern=repository/ext/{artifact}

usr.type=watched
usr.watchDirectory=repository/usr

chain=ext,usr

The default configuration shown above has two searchpaths corresponding to the two default sub-directories of the $SERVER_HOME/repository directory created when you first install Virgo: ext and usr. Virgo searches each of these individual repositories when locating entries for inclusion in the repository.

The chain property shows the order in which Virgo searches the individual repositories: first ext and then usr.

The following table lists all the available properties that you can use to configure an individual repository. Individual repositories as well as the repository search chain are configured in the file $SERVER_HOME/configuration/org.eclipse.virgo.repository.properties.

Table 13.5. Repository Properties

Property Description Default Value
repository-name.type

Specifies the type of path. You can set this property to one of the following three valid values:

  • external: Specifies that this path points to a number of directories that satisfy a given search pattern and are local to the current Virgo instance. Use the searchPattern property to specify the directory search pattern.

  • watched: Specifies that this path points to a single directory, local to the current Virgo instance. Virgo regularly scans watched repositories so it automatically picks up any changes to the artifacts in the directory at runtime. Virgo also scans its local watched repositories when deploying any artifact. Use the watchDirectory property to specify the watched directory and the watchInterval property to specify how often Virgo checks the directory.

  • remote: Specifies that the path points to a remotely-hosted repository, hosted by a remote instance of Virgo Server for Apache Tomcat. Use the uri property to specify the full URI of the remote repository. You can also specify the optional indexRefreshInterval property.

See Watched or External Repository? for additional information about when to configure watched or external repositories for your particular environment.

no default
repository-name.searchPattern

Specifies the pattern that an external repository uses when deciding which local directories it should search when identifying artifacts. Use this property together with repository-name.type=external. See Search Paths: Additional Information for detailed information about specifying a search pattern.

no default
repository-name.watchDirectory

Specifies the single directory of a watched repository. You can specify either an absolute or relative pathname for the directory. If you specify a relative pathname, it is relative to the root of the Virgo installation ($SERVER_HOME). Use this property together with repository-name.type=watched.

no default
repository-name.watchInterval

Specifies the interval in seconds between checks of a watched directory by a watched repository. Use this property together with repository-name.type=watched.

5
repository-name.uri

Specifies the URI of the hosted repository to which a remote repository connects. The value of this property takes the following format:

http://host:port/org.eclipse.virgo.apps.repository/remote-repository-name

where:

  • host refers to the computer on which the remote VTS instance hosts the remote repository.

  • port refers to a Tomcat listener port of the remote VTS instance which hosts the remote repository.

  • remote-repository-name refers to the name of the remote repository, as specified in the org.eclipse.virgo.apps.repository.properties file of the remote VTS instance.

Use this property together with repository-name.type=remote.

no default
repository-name.indexRefreshInterval

Specifies the interval in seconds between checks by a remote repository that its local copy of the hosted repository index is up-to-date (a remote repository acts as a proxy for a hosted repository and thus it holds a local copy of the hosted repository’s index).

Use this property together with repository-name.type=remote.

5


Should I Configure a Watched or External Repository?

The main difference between a watched and an external repository is that Virgo regularly scans watched directories and automatically picks up any changed artifacts, while Virgo scans external directories only at startup, and then only if there is no cached index available. This means that Virgo always performs a scan of an external repository when you start the server with the -clean (as this deletes the index) and only scans during a normal startup if the index isn’t there because, for example, this is the first time you start the server.

There is a performance cost associated with using a watched repository due to Virgo using resources to scan the directory at the configured interval. The cost is small if the watched repository contains just a few artifacts; however, the performance cost increases as the number of artifacts increases. Note that Virgo re-scans its local watched repositories when deploying any artifact, so the scanning interval can be configured to be relatively long.

For this reason, we recommend that you put most of your dependencies in external repositories, even when in development mode. If you make any changes to the artifacts in the external repositories, remember to restart Virgo with the -clean option so that the server picks up any changes. Use watched directories for artifacts that you are prototyping, actively updating, or when adding new dependencies so that Virgo quickly and easily picks them up. To increase performance even during development, however, you can use an external repository for most of your dependencies, in particular the ones that are fairly static.

In production environments, where dependencies should not change, we recommend that you use only external repositories.

Search Paths: Additional Information

The repository-name.searchPattern and repository-name.watchDirectory properties specify search paths for external and watched repositories, respectively, that define a physical location that Virgo 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.

Using Wildcards

Search paths specified with the repository-name.searchPattern property provide support for wildcards. In the entries above, the path segments surrounded by curly braces, for example {bundle} and {library}, are wildcards entries for a directory with any name. Allowing wildcards to be named in this way is intended to improve the readability of search path configuration.

In addition to supporting the above-described form of wildcards, Virgo also supports Ant-style paths, that is * and ** can be used to represent any directory and any series of directories, respectively. For example, repository/usr/{bundle} and repository/usr/* are equivalent.

A common usage of the ** wildcard is to allow dependencies stored in a directory structure of varying depth, such as a local Maven repository, to be provisioned by the Virgo.

Using System Properties

You can use system properties when specifying the values of the repository-name.searchPattern, repository-name.watchDirectory, repository-name.watchInterval, repository-name.uri, and repository-name.indexRefreshInterval properties. You reference system properties as ${system.property.name}; for example, a search path of ${user.home}/repository/bundles references the repository/bundles directory in the user’s home directory.

Example Repository Configurations

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

Add an Ivy cache repository

The following example shows how to add an external repository whose location is actually an Ivy cache.

Note that Ivy repositories can contain bundles which will conflict with the normal operation of Virgo, so care should be exercised when adding such an external repository.

ext.type=external
ext.searchPattern=repository/ext/{artifact}

usr.type=watched
usr.watchDirectory=repository/usr

ivy-repo.type=external
ivy-repo.searchPattern=${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar

chain=ext,usr,ivy-repo

Add a Maven local repository

The following example shows how to add an external repository whose location is actually a Maven repository.

Note that Maven repositories can contain bundles which will conflict with the normal operation of Virgo, so care should be exercised when adding such an external repository.

ext.type=external
ext.searchPattern=repository/ext/{artifact}

usr.type=watched
usr.watchDirectory=repository/usr

maven-repo.type=external
maven-repo.searchPattern=${user.home}/.m2/repository/**/{bundle}.jar

chain=ext,usr,maven-repo

Add remote and watched repositories

The following example shows the default org.eclipse.virgo.repository.properties file from a freshly-installed Virgo instance, but then updated to include new remote and watched repositories. Both of these repositories are part of the repository chain.

The remote repository is called remote-repo. The URI of the hosted repository from which remote-repo gets its artifacts is http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo; this means that there is a VTS instance running on host my-host whose Tomcat server listens at the default port, 8080, and this server instance hosts a repository called my-hosted-repo, configured in the org.eclipse.virgo.apps.repository.properties file of the remote server instance. The remote repository checks for changes in the hosted repository every 30 seconds.

The watched repository is called watched-repo and the directory that holds the artifacts is repository/watched, relative to the installation directory of the VTS instance. The server checks for changes in this watched repository every 5 seconds.

ext.type=external
ext.searchPattern=repository/ext/{artifact}

usr.type=watched
usr.watchDirectory=repository/usr

remote-repo.type=remote
remote-repo.uri=http://my-host:8080/org.eclipse.virgo.apps.repository/my-hosted-repo
remote-repo.indexRefreshInterval=30

watched-repo.type=watched
watched-repo.watchedDirectory=repository/watched
watched-repo.watchedInterval=5

chain=ext,usr,remote-repo,watched-repo