|
|
|
Dependencies
Project Zero provides tools to help you manage your application’s dependencies and share your applications and libraries with others.
Dependency management
Zero uses a dependency management utility called Ivy to ensure that your application 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 Zero ZIP file. You declare the modules your application needs to run in an XML file called an Ivy file. Zero then uses Ivy to resolve your application’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 Zero creates on your system, or it can search remote repositories such as the Project Zero 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 application’s classpath to include the dependency.
 Note: It's up to you to make sure you are following the license agreement for any dependencies you specify in the development of your applications, and that Zero 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.
When you first install Zero, a local repository is created on your system to store artifacts. All downloaded artifacts are placed into your local repository. Zero looks in your local repository for matching dependencies first. If a dependency can not be found locally, you have the option of telling Zero to look for it in remote repositories.
Note: Applications within the same directory are checked before looking in the local repository. In Eclipse, this means that Zero projects within the same workspace are checked first.
The local repository is created in your <user.home> directory by default.
On Windows, the local repository can typically be found at
<root>:\Documents and Settings\<username>\zero
On Linux, the local repository is typically at
/home/<username>/zero
The location of the local repository can be changed by configuring the file <zerohome>/config/ivy/local.properties when using the Command Line Interface, or through the Window > Preferences > Zero Repositories page in Eclipse. If you are using the command-line, then change the local.root property to a new path.
To manage the artifacts stored in your local repository in Eclipse, go to the menu Zero > Manage Repository. From this screen (shown below), you can remove modules from the local repository or search for new modules in your remote Ivy repositories. See Remote Repositories, below, for more information on searching remote repositories.
To manage your local repository from the Command Line Interface, you can use the following commands:
| Command | Example | Description |
|---|
zero get org:module[:revision] | zero get zero:zero.core | Downloads the latest Zero core into your local repository |
zero delete org:module:revision | zero delete zero:zero.TestSvc:1.0.0 | Removes TestSvc 1.0.0 from your local repository |
zero list [-remote true] | zero list | Lists the modules in your local (or remote) repository |
For more details, see the Command Line Interface reference.
Zero 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. Zero repositories use an Ivy format. Maven is a build utility that has similar dependency management capabilities to Ivy.
Zero is configured to look for dependencies in two remote locations by default:
| Repository | Format | Location | Contents |
|---|
| Zero Latest Package Repository | Ivy | http://www.projectzero.org/repo/zero.repo.latest/ | Zero packages |
| Maven | Maven | http://repo1.maven.org/maven2/ | A large open source repository, containing many open source artifacts, such as those from Apache |
You can configure Zero to look in additional or different remote repositories.
If you are using the Command Line Interface, edit the file
<zerohome>/config/ivy/remote.properties
zero.1=http://www.projectzero.org/repo/zero.repo.latest/
maven.2=http://repo1.maven.org/maven2/
The repositories will be searched in the numerical order listed. Ivy repositories must be labeled as zero.#, while Maven repositories must be labeled as maven.#. No two repositories should use the same number.
To configure the remote repository chain from Eclipse, go to Window > Preferences > Project Zero. You can also search remote Ivy repositories for new artifacts through the local repository management screen, accessible through the menu Zero > Manage Repository.
 Note: Searching Maven repositories using the Eclipse Zero Repositories interface is not supported at this time. To locate artifacts in a Maven repository such as http://repo1.maven.org/maven2/, try browsing using the Java package name as the directory structure, e.g. org/apache/... Keep drilling down until you get into a specific version of the package with a .pom file. Open the .pom file and extract the following information:
Add a new dependency to your ivy.xml file as described in Declaring Dependencies in ivy.xml, below, and resolve.
Declaring dependencies
You can declare dependencies for your application by configuring your ivy.xml file, which is located in your application’s config directory.
Each dependency declaration is made up of three parts: an organization (org), a module name (name), and a revision matching pattern (rev). For Zero dependencies, org is always “zero”. Module name is usually the same as the application name. Revision is a pattern that specifies the specific version of the artifact that your application needs, or it is a pattern such as “1.0.0+”. “1.0.0+” means match any version from 1.0.0 up to but not including version 1.0.1.
The following is an example of getting Derby from a Maven server and zero.data from the Zero repository server.
<dependencies>
<dependency org="org.apache.derby" name="derbyclient" rev="10.1.1.0"/>
<dependency org="zero" name="zero.data" rev="1.0.0+"/>
</dependencies>
Declaring dependencies in Eclipse
The Zero Eclipse plugin offers several options for configuring dependencies. First, Zero supplies an editor for ivy.xml files that looks like this:
Clicking the “Add…” button will allow you to add dependencies from the local repository to your application. You can also add dependencies manually to the ivy.xml by clicking on the “Source” tab at the bottom of the page. When you close this window, the ivy.xml file will be saved, and your new dependency list will be resolved. If successful, your application’s classpath will be updated with the new list of dependencies.
You can also add dependencies to your project through the project’s Properties page by clicking on Java Build Path > Libraries. Select “Zero Resolved Libraries” and click “Edit” to select additional dependencies from the local repository.
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 course 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.
Note: 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 zero application.
<dependency name="commons-beanutils" org="commons-beanutils" rev="1.7.0">
<exclude module="commons-logging"/>
</dependency>
Course Grained
The course grained solution is to exclude all transistives. 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" />
Resolving dependencies
Resolving dependencies in Eclipse
In Eclipse, Zero will generally resolve the dependencies of your projects automatically any time a change is made to a project’s dependency list, either through editing the ivy.xml or the Zero Resolved Libraries container.
When resolving in Eclipse, Zero searches in the following locations for dependencies, in order:
- Open projects in your workspace, regardless of their revision number
- Your local repository. If a match has not been found yet, Zero will prompt you to see if you want to look in the remote chain for missing dependencies.
- Remote repositories. By default, the remote repositories searched are the Zero package repository and the Maven repository.
You can also force a resolve by right-clicking on your project and selecting Zero Tools > Resolve. If you want to remotely update the versions of all of your dependencies for all of your open projects, you can click on the menu option Zero > Update Dependencies, or the Update Dependencies icon on the toolbar.
Troubleshooting resolves in Eclipse
If you want to see exactly which dependencies your application picked up during a resolve, look in your application’s “reports” folder. Right-click on the XML file in this directory and select “Open with…->System Editor”. Your browser should open a nicely formatted report describing the versions of all the dependencies resolved for your application.
Resolving dependencies with the command line interface
To resolve dependencies from the command line, change into your application’s directory and type
zero resolve
This command will look first in your local repository for dependencies; missing dependencies are sought in the remote repositories; finally, the application’s classpath is updated accordingly.
Troubleshooting resolves from the command line
If you want to see exactly which dependencies your application is using, open the XML file in your application’s “reports” directory with a web browser. Your browser should display a nicely formatted report describing the versions of all the dependencies resolved for your application.
Packaging to publish
Zero uses standard ZIP files for packaging. If you are going to package your application 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 Zero 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.
<info organisation="zero" module="ETestApp2" revision="1.0.0">
<license name="type of license" url="http://license.page"/>
<ivyauthor name="AuthorsName" url="http://authors.home.page"/>
<description homepage="http://module.description.page"/>
</info>
<publications>
<artifact org="zero" name="ETestApp2" type="zip" />
</publications>
To create a Zero package in Eclipse, simply right click on your project and select "Export...->Zero->Project Zero Export Wizard. You can then specify the directory to export to (<apphome>/export by default) and optionally include your source files. Note: you must include source if you plan to import the project back into Eclipse. A ZIP file will be created in that directory with the name module-revision.zip, e.g. ETestApp2-1.0.0.zip.
To create a Zero package with the Command Line Interface, change to your application's directory and type zero package. A file with with the naming pattern module-revision.zip will be created in your application's export directory.
If you want to make your package available for other application'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 applications can declare dependencies on it. To verify that your package has been published, you can use the zero list command to view the local repository.
Sharing and using Zero packages
Zero ZIP files can easily be shared with other developers.
To run an application from a Zero ZIP file with the command-line interface:
- Unzip the file into your <zerohome>/apps directory.
- Change into the application's directory.
- Execute
zero resolve to resolve any dependencies the application has.
- Execute
zero run to run it.
To publish a dependency (Zero ZIP file) with the command-line interface:
- Execute
zero publish -zipfile mydep-1.0.0.zip to publish mydep to your local repository.
To import a Zero ZIP file into Eclipse (note: the ZIP must contain source)
- Select "File->Import->Existing Projects into Workspace.
- Select "Select archive file" and browse to the ZIP's location.
- Select the project and click Finish.
- Right click on the project in the Package Explorer and select Zero->Resolve to resolve the package's dependencies.
Version format of Project Zero libraries
Versions Defined:
The Project Zero libraries use the following version format:
major.minor.revision[.qualifier]
- major - [0-9]+ - denotes potentially breaking changes - libraries with different major version numbers may not be compatible
- minor - [0-9]+ - denotes feature changes - libraries with different minor version numbers are compatible
- revision - [0-9]+ - denotes the Subversion revision number - this number by itself can be used to uniquely identify a library, and thus to rebuild a specific version from source
- qualifier (optional) - [a-zA-Z0-9]* - this part of the version is lexigraphically matched, it has no specific reservation, but it is currently being used to categorize versions into milestones, for example M1. When an official full release is reached the qualifier will be dropped.
Version examples:
- 1.0.3207.M1 - milestone build: major = 1, minor = 0, svn revision = 3207, part of milestone 1
- 1.0.3405 - official release build: major = 1, minor = 0, svn revision = 3405
Resolving against specific milestones is not possible by default. Interim milestone versions are not supported, so it is not intended that applications would be dependent on a specific milestone version. There is no possible dependency requirement that will guarantee a specific milestone as there is with guaranteeing a specific major and minor version. For example, you can declare 1.0+, but you cannot declare 1.0.+.M2. You also cannot reliably declare a dependency on a specific milestone version such as 1.0.3767.M2. Since you cannot control the transitive dependency requirements, you could still end up with transitives from different milestones.
Despite this lack of support, you can carefully set up your own development environment with separate repositories to isolate milestones. This will allow you to use something like 1.0+ without unintentionally moving up to a new milestone. One way to accomplish this is to keep separate Eclipse workspaces (or separate CLI installations) that point to separate milestone-specific local and remote repositories. For example, if you wanted to stay on milestone 2, you would set up a local repository like ${user.home}/zerom2, and point to a remote repository like http://www.projectzero.org/repo/zero.repo.M2. By default, when you download the Eclipse plug-in or CLI from a milestone URL, it will point to the remote repository for that milestone. But, you have to manually set the local repository location. See Local Repositories and Remote Repositories for more information on configuring repository locations.
You can also use standalone packages to ensure that your deployed packages do not unintentionally move up to a new milestone, but this method will not help while applications are under development.
The dependency management resolve may need to access remote repositories to download dependencies. Proxies are supported by defining the necessary properties.
Configuring the proxy support in Eclipse
The Eclipse environment allows configuring the proxy through Network Preferences. To open the Network Preferences dialog, click Window on the main menu bar and select Preferences.... Expand General and select Network Connections. The configured proxy will be used when the zero project is resolved.
Configuring the proxy support through the command line
The proxy can be configured through the following system properties:
- http.proxyHost
- http.proxyPort
- http.proxyUser
- http.proxyPassword
These properties must be set as in the ZERO_OPTS environment variable; the Zero shell script uses that environment variable as JVM arguments.
set ZERO_OPTS=-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8082
zero run
|
