This Guide is work in progress.
Proximity is some kind of extensible proactive-mirror. The Core of Proximity is transport, container (as Spring and as webapp container) and Maven independent. The WAR package is specialized instance of Proximity created to be a Maven Proxy. The key feature in this customization is extensibility of Proximity, thus all Maven "awareness" is provided by four (4) Java class file.
Proximity's local storages are able to be "metadata"-aware. What does it mean? It simply changes the behaviour of local storage a little bit: the storage root, you have configured are split in two subdirectory. One of its serve as "real" storage (default name is "storage" altough it is configurable) containing the remote (proxied) content in unmodified directory hierarchy and originial file contents. The other directory (default name is "metadata" altough it is configurable too) shares the same structure at a first glance. Browsing this directory, you will see the same subdirectories and same file names, but with special contents! These file are regular Java java.util.Properties files, and they contains the "metadata" about their "storage" file counterparts. The amount of metadatas and their content is completely extensible, this is how "Maven Proxy" builds upon Proximity Core.
Proximity itself (since it's Core is a simple multi homed HTTP Proxy) maintains some default properties of "item" (Proximity notation for a file) like name, path, size, etc. In Proximity Maven Proxy, a special class, called MavenItemPropertiesConstructor is responsible for "filling" up all the "extra" (Maven) properties of the file.
The Maven specific things are all extending the core functionalities of Proximity, enabling this web application you are using.
The repository browsing is the same surface that uses Maven itself. All the HTML gimmicks there are for human users, since Maven issues absolute HTTP GET commands to retrieve artifacts. It is the same action when You click on some JAR or XML file and the "Save as..." dialog opens in your browser.
This view completely relies on the underlying localStorage. Listing items are actually like issuing "ls/dir" commands on the file system. When you request an item (or directory) that not exists in this view, Proximity will try to fetch it from all available remote peers. If you requested a locally non-existent but remotely existent file, it appears in this view as soon it is served to You.
An alternative view of the repository browsing is the artifact browsing. Here, you can browse the "namespace" of groupId's, artifactId's and versions.
This view completely relies on the Indexer and Proximity Maven extension! It just demonstrates the extensibility of the Proximity itself. Look at the responsible controller Java class: ArtifactsController.java and you will in the moment get the picture.
This view actually "tricks" the Proximity and uses it's powerful Lucene based search engine.
Proximity became WebDAV capable!.
Proximity offers a DAV view on it's repositories on "/dav/" path. You can use Maven2 to deploy artifacts directly onto Proximity. This way, there is no need for "deployment circumvention" (publishing the underlying file system for deployment) and the index will be up-to-date. Just set up the Proximity URL of the given repository group as target repository (for example URL http://localhost:8080/px-webapp/dav/inhouse). The WebDAV feature has been tested with Wagon WebDAV provider 1.0-beta-2.
All you have to do is decleare the Proximity as repository (a WebDAV one) and voila! (Also, you have to setup Maven with WebDAV Wagon as build extension). See [where?].
This paragraph will give brief instructions on using Proximity with Maven1 and Maven2.
Install it as it should with distribution you downloaded. WAR file should be deployed on a J2EE servlet container. Bundled releases should be installed as described in README file.
For WAR distribution: All you have to do is install Proximity WAR on some Servlet container that has access to outer world (for reaching central, codehaus, etc. This is NOT mandatory since you can use Proximity to serve only your own artifacts!).
The examples assumes that Proximity runs on a localhost and at HTTP port 8080 (as wih default Apache Tomcat deployment). Follows a few simple scenarios for using Proximity server:
See a Quick Start for Proximity!
With installed Proximity You have to create settings.xml in your local M2 repo that defines mirror with id "central" and point it to Proximity instance. You can use the default file that comes with Maven2 as template at $M2_HOME/conf/settings.xml. Example:
<mirrors>
<mirror>
<id>myProximity</id>
<mirrorOf>central</mirrorOf>
<name>Proximity mirrored central repos.</name>
<url>http://localhost:8080/px-webapp/repository</url>
</mirror>
</mirrors>
This file should be placed in your $HOME/.m2 directory.
The repository URL depends on emergeGroups setting, so better take the repo URL from the Proximity "Repositories" page.
If you have installed and working Proximity, you have to configure Maven1 to use Proximity as his repository instead the default at central:
maven -Dmaven.repo.remote=http://localhost:8080/px-webapp/repository clean jar
Alternatively, you can place the following line in build.properties of project, or better, in your home (on Unix /home/_USERNAME_, on Windows C:\Documents And Settings\_USERNAME_):
maven.repo.remote=http://localhost:8080/px-webapp/repository
Proximity is general Proxy like application, it is NOT just Maven proxy. Proximity have pluggable proxying logic, and the main reason for creating Proximity was to solve Maven proxying on our intranet. But Proximity became a little bit more, than "just" a Maven proxy.
The Maven1/2 awareness comes from pluggable proxy logic and Maven binding, that is independently configurable on repository level. No other Maven dependency exists!
Have fun!