7.5 Configuring the Provisioning Repository

You configure the locations that SpringSource dm Server includes in its provisioning repository by editing the 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:

For example, bundles-usr.type=external specifies that the type property of the repository with name bundles-usr 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 bundles and libraries. The particular properties that configure these options are listed in the table after the example.

The chain property specifies the order in which SpringSource dm Server searches the searchpaths when it looks for dependencies; the first path listed specifies the first actual directory that SpringSource dm 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 bundles-usr.type=external, the name of the repository is bundles-usr.

The default repository configuration for a newly installed SpringSource dm Server is as follows:

bundles-subsystems.type=external
bundles-subsystems.searchPattern=repository/bundles/subsystems/{subsystem}/{component}

bundles-ext.type=external
bundles-ext.searchPattern=repository/bundles/ext/{bundle}

bundles-usr.type=external
bundles-usr.searchPattern=repository/bundles/usr/{bundle}

libraries-ext.type=external
libraries-ext.searchPattern=repository/libraries/ext/{library}

libraries-usr.type=external
libraries-usr.searchPattern=repository/libraries/usr/{library}

chain=bundles-subsystems,bundles-ext,bundles-usr,libraries-ext,libraries-usr

The default configuration shown above has five searchpaths, each of which SpringSource dm Server searches when locating entries for inclusion in the repository. The chain property shows the order in which SpringSource dm Server searches the searchpaths.

SpringSource dm Server requires that you always include the bundles-subsystem, bundles-ext, and libraries-ext searchpaths, as shown above, in your repository configuration. You can configure the user-related searchpaths as you wish.

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

Table 7.5. Repository Properties in repository.properties

PropertyDescription
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 SpringSource dm 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 SpringSource dm Server instance. SpringSource dm Server regularly scans watched repositories so it automatically picks up any changes to the bundles in the directory at runtime. Use the watchDirectory property to specify the watched directory and the watchInterval property to specify how often dm Server checks the directory.
  • remote: Specifies that the path points to a remotely-hosted repository, hosted by a remote instance of SpringSource dm 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 dm Server installation (SERVER_HOME). Use this property together with "repository-name.type=watched. See Using System Properties for information about using system properties as part of the directory name.

repository-name.watchInterval

Specifies the interval in seconds between checks of a watched directory by a watched repository. This property is optional. 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/com.springsource.server.repository/remote-repository-name

where:

  • host refers to the computer on which the remote dm Server instance hosts the remote repository.
  • port refers to Tomcat listen port of the remote dm Server 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 dm Server 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.)

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 SpringSource dm Server regularly scans watched directories and automatically picks up any changed bundles or libraries, while dm Server scans external directories only at startup, and then only if there is no cached index available. This means that dm Server 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 dm Server 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, SpringSource recommends 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 dm Server 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 dm Server 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, SpringSource recommends 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 SpringSource dm 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, e.g. {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, SpringSource dm Server also supports Ant-style paths, i.e. * and ** can be used to represent any directory and any series of directories respectively. For example, repository/bundles/usr/{bundle} and repository/bundles/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 SpringSource dm Server.

Using System properties

You can use system properties within the search directory path specified by both the repository-name.searchPattern and repository-name.watchDirectory 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.

Replace bundles-usr with an Ivy cache

bundles-subsystems.type=external
bundles-subsystems.searchPattern=repository/bundles/subsystems/{subsystem}/{component}

bundles-ext.type=external
bundles-ext.searchPattern=repository/bundles/ext/{bundle}

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

libraries-ext.type=external
libraries-ext.searchPattern=repository/libraries/ext/{library}

libraries-usr.type=external
libraries-usr.searchPattern=repository/libraries/usr/{library}

chain=bundles-subsystems,bundles-ext,bundles-usr,libraries-ext,libraries-usr

Replace bundles-usr with a Maven local repository

bundles-subsystems.type=external
bundles-subsystems.searchPattern=repository/bundles/subsystems/{subsystem}/{component}

bundles-ext.type=external
bundles-ext.searchPattern=repository/bundles/ext/{bundle}

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

libraries-ext.type=external
libraries-ext.searchPattern=repository/libraries/ext/{library}

libraries-usr.type=external
libraries-usr.searchPattern=repository/libraries/usr/{library}

chain=bundles-subsystems,bundles-ext,bundles-usr,libraries-ext,libraries-usr

Add remote and watched repositories

The following example shows the default repository.properties file from a freshly-installed dm Server, 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/com.springsource.server.repository/my-hosted-repo; this means that there is a dm Server 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 dm Server instance. The server checks for changes in this watched repository every 5 seconds.

bundles-subsystems.type=external
bundles-subsystems.searchPattern=repository/bundles/subsystems/{subsystem}/{component}

bundles-ext.type=external
bundles-ext.searchPattern=repository/bundles/ext/{bundle}

bundles-usr.type=external
bundles-usr.searchPattern=repository/bundles/usr/{bundle}

libraries-ext.type=external
libraries-ext.searchPattern=repository/libraries/ext/{library}

libraries-usr.type=external
libraries-usr.searchPattern=repository/libraries/usr/{library}

remote-repo.type=remote
remote-repo.uri=http://my-host:8080/com.springsource.server.repository/my-hosted-repo
remote-repo.indexRefreshInterval=30

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

chain=bundles-subsystems,bundles-ext,bundles-usr,libraries-ext,libraries-usr,remote-repo,watched-repo