Artifact Repositories

A repository (definition) in Maven is used to hold build artifacts and dependencies of varying types.

There are strictly only two types of repositories: local and remote. The local repository refers to a copy on your own installation that is a cache of the remote downloads, and also contains the temporary build artifacts that you have not yet released.

Remote repositories refer to any other type of repository, accessed by a variety of protocols such as file:// and http://. These repositories might be a truely remote repository set up by a third party to provide their artifacts for downloading (for example, Maven's central repository). Other "remote" repositories may be internal repositories set up on a file or HTTP server within your company, used to share private artifacts between development teams and for releases.

The local and remote repositories are structured the same way so that scripts can easily be run on either side, or they can be synced for offline used. In general use, the layout of the repositories is completely transparent to the Maven user, however.

Why not Store JARs in CVS?

It is not recommended that you store your JARs in CVS. Maven tries to promote the notion of a user local repository where JARs, or any project artifacts, can be stored and used for any number of builds. Many projects have dependencies such as XML parsers and standard utilities that are often replicated in typical builds. With Maven these standard utilities can be stored in your local repository and shared by any number of builds.

This has the following advantages:

  • It uses less storage - while a repository is typically quite large, because each JAR is only kept in the one place it is actually saving space, even though it may not seem that way
  • It makes checking out a project quicker - initial checkout, and to a small degree updating, a project will be faster if there are no large binary files in CVS. While they may need to be downloaded again afterwards anyway, this only happens once and may not be necessary for some common JARs already in place.
  • No need for versioning - CVS and other source control systems are designed for versioning files, but external dependencies typically don't change, or if they do their filename changes anyway to indicate the new version. Storing these in CVS doesn't have any added benefit over keeping them in a local artifact cache.

Using Repositories

In general, you should not need to do anything with the local repository on a regular basis, except clean it out if you are short on disk space (or erase it completely if you are willing to download everything again).

For the remote repositories, they are used for both downloading and uploading (if you have the permission to do so).

Downloading from a Remote Repository

Downloading in Maven is triggered by a project declaring a dependency that is not present in the local repository (or for a SNAPSHOT, when the remote repository contains one that is newer). By default, Maven will download from it's central repository.

To override this, you need to set the property maven.repo.remote as follows: 

maven.repo.remote=http://anothermavenrepository,http://repo1.maven.org/maven/

You can set this in your ~/build.properties file to globally use a certain mirror, however note that it is common for a project to customise the repository in their project.properties and that your setting will take precedence. If you find that dependencies are not being found, check you have not overridden the remote repository.

The protocols that are currently supported for a remote repository are http, https, sftp and file. Note that sftp is only supported since Maven 1.1-beta-3, and you'll have to set the username and password in the url, eg: 

maven.repo.remote=sftp://${myusername}:${mypassword}@localhost/tmp/ble

(Future versions should allow you to use a setting of ${maven.repo.remote},http://anothermavenrepository, but currently this causes an infinite recursion).

For more information on dependencies, see Handling Dependencies.

Building Offline

If you find you need to build your projects offline you can either use the offline switch on the CLI: 

maven -o jar:jar

This is equivalent to: 

maven -Dmaven.mode.online=false jar:jar

Or you can set maven.mode.online to false in your build.properties file to ensure you always work offline.

Note that many plugins will honour the offline setting and not perform any operations that would connect to the internet. Some examples are resolving Javadoc links and link checking the site.

If you would like normal operations to succeed, but for no dependency downloading to occur, set the maven.repo.remote.enabled property to false.

Uploading to a Remote Repository

While this is possible for any type of remote repository, you must have the permission to do so. To have someone upload to the central Maven repository, see Uploading to Maven's central repository.

Usually, you will only be attempting to upload a release of your own application to an internal repository. See internal repositories for more information.