Dependency Management

This topic contains a reference about the dependency management support

Dependency management

IBM® WebSphere® sMash uses a dependency management utility called Ivy to ensure that your module is using the right versions of the libraries you declare as dependencies. In Ivy, these libraries are called modules. A module represents an artifact, which is code packaged as either a JAR file or a ZIP file. You declare the modules your module needs to run in an XML file called an Ivy file. WebSphere sMash then uses Ivy to resolve your module's dependencies. Resolve means that Ivy searches a chain of repositories to find a module that matches the dependency you declared. Ivy can search the local repository that WebSphere sMash creates on your system, or it can search remote repositories such as the WebSphere sMash package repository. When a match is found, Ivy downloads the module's artifact into your local repository (if it isn't already there), and updates your module's classpath to include the dependency.

It's up to you to make sure you are following the license agreement for any dependencies you specify in the development of your modules, and that WebSphere sMash downloads for you.

Repositories

An Ivy repository is simply a collection of artifacts stored in a structured format that Ivy can understand. Repositories are typically accessed through file system or HTTP interfaces. Repositories can store different versions of modules, so you can declare which specific version you need.

Local Repositories

When you first install WebSphere sMash, a local repository is created on your system to store artifacts. All downloaded artifacts are placed into your local repository. WebSphere sMash looks in your local repository for matching dependencies first. If a dependency can not be found locally, you have the option of looking in remote repositories.

Note: Modules within the same directory are checked before looking in the local repository. This is enabled through a workspace resolver.

The local repository is created in your <zerohome> directory by default. The location of the local repository can be changed by configuring the file <zerohome>/config/local.properties when using the Command Line Interface

Remote Repositories

WebSphere sMash can look in remote repositories for dependencies if they can't be found on the local system. Remote repositories are file servers with an HTTP interface. The remote repositories can either use an Ivy format or a Maven format. WebSphere sMash repositories use an Ivy format. Maven is a build utility that has similar dependency management capabilities to Ivy.

Declaring dependencies

You can declare dependencies for your module by configuring your ivy.xml file, which is located in your module's config directory. Note: You should stop your application before changing its configuration. Failure to do so could lead to unexpected behavior in the running application.

Each dependency declaration is made up of three parts: an organization (org), a module name (name), and a revision matching pattern (rev). For WebSphere sMash dependencies, org is always zero. Module name is usually the same as the module name. Revision is a pattern that specifies the specific version of the artifact that your module needs, or it is a pattern such as [1.0.0.0, 2.0.0.0[. This particular pattern means match any version greater than or equal to 1.0.0.0 but less than 2.0.0.0. For more information on Ivy patterns, see the Ivy dependency documentation.

Transitive Dependencies

One of the features of dependency management is the ability for a package to declare their transitive dependencies. When the dependency is included, the transitive dependencies are automatically resolved. There are times, however, where there is the need to have finer control over the artifacts that are included. One such case is when a conflict between two dependencies occurs. Another could just be the desire to exclude a certain jar. Ivy offers two solutions, one that could be viewed as fine-grained and another more coarse-grained. The ivy report is a great source to determine why artifacts are included, but the report is only generated in the case where there are no conflicts.

There is another option to control transitive dependencies and that is through the use of configurations, but this option is not supported at this time.

Fine-Grained

The fine-grained solution allows excluding specific transitive dependencies. This solution allows picking and choosing which artifacts to exclude. The excludes solution is the preferred solution for a WebSphere sMash module.

<dependency name="commons-beanutils" org="commons-beanutils" rev="1.7.0">
  <exclude module="commons-logging"/>
</dependency>

Coarse-Grained

The coarse-grained solution is to exclude all transitives. This solution does require explicit dependency declarations to include the required transitives dependencies, but this solution allows complete control of which artifacts are included.

<dependency name="commons-lang" org="commons-lang" rev="2.3" transitive="false" />

Packaging to publish

WebSphere sMash uses standard ZIP files for packaging. If you are going to package your module to share with others, you should update your ivy.xml file to include information about your package, such as author (ivyauthor), organization (organisation and org), version (revision), license, and description. From a WebSphere sMash perspective, the elements you should be sure to have correct are the organization, module, and revision. These fields are used for naming your package and dependency resolution using Ivy.

To create a WebSphere sMash package with the command line interface, change to your module's directory and type zero package. A file with with the naming pattern module-revision.zip will be created in your module's export directory.

If you want to make your package available for other module's on your system to use, you can publish it to your local repository using zero publish. Once a package has been published to the local repository, other modules can declare dependencies on it. To verify that your package has been published, you can use the zero search command to view the local repository.

Proxy Support

The dependency management resolve may need to access remote repositories to download modules. If a proxy is required for internet access, then the proxy needs to be configured in the appropriate script.

The proxy support can be configured through the following system properties:

Both http and https proxy values should be configured.

The WebSphere sMash command line scripts contain a commented example to help set the proxy properties. For example, in the zero shell script uncomment the following lines and update the proxy values.

ZERO_OPTS="-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=myproxyport -Dhttps.proxyHost=myproxyhost -Dhttps.proxyPort=myproxyport"
export ZERO_OPTS
The proxy support requires the actual proxy host and proxy port, proxy auto configuration files are not supported.

Shared Repositories

Repositories can be used to share modules and artifacts with other developers. The current repositories for zero module and maven artifacts are typically preconfigured in the command line interface. This topic will discuss how to create your own repository of modules in order to share with others.

The command line interface provides zero commands that allow publishing modules to the local repository. The local repository could be hosted using a web server to allow others to resolve modules. The issue with the local repository is the repository also contains modules from the WebSphere sMash. The command line interface also provides zero repository commands that allow publishing to a private local repository that will only contain modules that you want to publish.

The process for publishing the module to the private shared repository is the same process as developing the module for publishing to the local repository. Once the module is completed, package the module using zero package. The publish step however will use zero repository publish <path>. The path is the path on your local file system where you want the private repository to reside. This is similar to publishing to a specific modulegroup, but instead a specific location. Once all the modules have been published to the private local repository, then the private repository can be hosted.

The private local repository needs to be provided through through a web server, and indexing must be enabled. The path specified in the zero repository publish command is the root directory of the repository. If the repository needs to be moved to another machine that is running the web server then copy from the root directory. Once the private shared repository is ready, then set up an alias for the repository and make sure to turn on indexing.

Alias /private_repo /home/shared/repo
<Directory "/home/shared/repo">
  Options Indexes
</Directory>

The repository can then be shared by providing the url to the module group. The new repository should be added using zero modulegroup addurl http://myhost/shared/repo.

Dependency Resolution in PHP

To include files from Ivy dependencies in PHP scripts, see the article on Libraries and Dependency Resolution in the PHP Support section.