9.4 Configuring the Local Provisioning Repository
Prev | 9. Configuring the Virgo Web Server | Next

## 9.4 Configuring the Local Provisioning Repository

You configure the locations that Virgo Web Server includes in its provisioning repository by editing the `com.springsource.repository.properties` file in the `$SERVER_HOME/config` directory.

When you specify a property in the file, use the format `repository-name.property=value`, where:

- `repository-name` refers to the name of the local repository.
- `property` refers to the name of a particular property.
- `value` refers to the value of the property.

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

For each specific repository, you configure a number of properties, such as its type (external, watched, or remote) and its searchpath, watched directory, or URI that specifies the actual location of the artifacts (OSGi bundles, libraries, PARs, plans, or configuration files.) The particular properties that configure these options are listed in the table after the example.

The `chain` property specifies the order in which Virgo Web Server searches the searchpaths when it looks for dependencies; the first path listed specifies the first actual directory that Virgo Web Server searches, until the last listed path. The `chain` property uses the names of the searchpaths 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 Web Server 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 VWS: `ext` and `usr`. Virgo Web Server searches each of these searchpaths when locating entries for inclusion in the repository.

The `chain` property shows the order in which Virgo Web Server searches the searchpaths: first `ext` and then `usr`.

The following table lists all the available properties that you can use to describe a named path and the repository search chain in the `com.springsource.repository.properties` file.

Table 9.6. Repository Properties in repository.properties

Property | Description
--- | ---
`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 Web Server 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 Web Server instance. Virgo Web Server 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 watched directory and the `watchInterval` property to specify how often VWS checks the directory. `remote`: Specifies that the path points to a remotely-hosted repository, hosted by a remote instance of Virgo Web Server. 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.
`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.
`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 VWS installation (`SERVER_HOME`). Use this property together with `repository-name.type=watched`.
`repository-name.watchInterval` | Specifies the interval in seconds between checks of a watched directory by a watched repository. This property is optional, if it is not specified the default interval of 5 seconds is used. Use this property together with `repository-name.type=watched`.
`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.server.repository/remote-repository-name` where: `host` refers to the computer on which the remote VWS instance hosts the remote repository. `port` refers to Tomcat listen port of the remote VWS instance which hosts the remote repository. `remote-repository-name` refers to the name of the remote repository, as specified in the `hostedRepository.properties` file of the remote VWS instance. Use this property together with `repository-name.type=remote`.
`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). This property is optional, if it is not specified the default interval of 5 seconds is used. Use this property together with `repository-name.type=remote`.

### Should I Configure a Watched or External Repository?

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

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 VWS 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 VWS 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 Web Server 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 Web Server 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 directly 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 Web Server.

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

    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.

    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 `com.springsource.repository.properties` file from a freshly-installed VWS, 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.server.repository/my-hosted-repo`; this means that there is a VWS 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 `hostedRepository.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 VWS 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.server.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

Prev | Up | Next
9.3 Configuring the Embedded Tomcat Servlet Container | Home | 9.5 Configuring a Hosted Repository