This section describes the provisioning repository feature of SpringSource dm Server, the reasons for using it, and how to configure it.
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, the SpringSource dm Server introduces the 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 or Import-Library manifest header in the MANIFEST.MF file of your application. The Import-Package header is standard to OSGi; Import-Library, however, is specific to SpringSource dm Server.
For additional details about the creation and usage of libraries, as well as general information about dependencies, see Programmer’s Guide.
In SpringSource dm Server, 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:
When you deploy your application, SpringSource dm Server installs the bundle in which it is packaged to the dm Server 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 dm Server has thus installed), the dm Server searches the provisioning repository for an artifact that can satisfy that dependency.
The provisioning repository for a particular instance of SpringSource dm Server can include artifacts in the following general locations:
external directories that adhere to a specified search pattern and are scanned by dm Server just at startup, or watched directories that point to a single directory location and dm Server scans on a regular basis.
You configure the provisioning repository using the SERVER_HOME/config/com.springsource.repository.properties file.
As previously described, a particular instance of SpringSource dm Server 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/config/com.springsource.repository.hosted.properties file. Typically, only remote clients use hosted repositories and their contents; the SpringSource dm Server 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.
When you first install SpringSource dm Server, the local provisioning repository is located at $SERVER_HOME/repository by default and consists of two main directories: ext and user. The ext directory contains bundles and libraries supplied with the SpringSource dm Server and usr contains bundles and libraries installed by the end user.
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 dm Server 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/config/com.springsource.repository.properties.
When you install a plan or a library, you must ensure that all referenced bundles 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.
In some cases the SpringSource dm Server manages to automatically detect changes in its provisioning repository at runtime, thereby avoiding the need to restart the dm Server.
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 the dm Server. For other changes such as addition of indirect dependencies, the SpringSource dm Server must be restarted to pick up any changes to the provisioning repository.