~~ Copyright 2006 The Apache Software Foundation.
~~
~~ Licensed under the Apache License, Version 2.0 (the "License");
~~ you may not use this file except in compliance with the License.
~~ You may obtain a copy of the License at
~~
~~      http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/guides/mini/guide-apt-format.html

ProxyManager

  The ProxyManager is designed to be used as a simple object or bean for use by
  a command-line application or web application.

Configuration

  An instance of a ProxyManager requires a configuration object that will
  define its behavior called ProxyConfiguration.  The ProxyConfiguration is a
  plexus component and can be looked up to get an instance of it.  Below is a sample
  plexus lookup statement:

----------
  ProxyConfiguration config = (ProxyConfiguration) container.lookup( ProxyConfiguration.ROLE );
----------

  Currently, a ProxyConfiguration lookup will return an empty instance of the 
  ProxyConfiguration which means it doesn't have any default definitions yet on
  how the ProxyManager should behave.  So the next step is to explicitly define
  its behavior.

----------
  ProxyConfiguration config = (ProxyConfiguration) container.lookup( ProxyConfiguration.ROLE );

  config.setRepositoryCachePath( "/user/proxy-cache" );

  ArtifactRepositoryLayout defLayout = new DefaultRepositoryLayout();

  File repo1File = new File( "src/test/remote-repo1" );

  ProxyRepository repo1 = new ProxyRepository( "central", "http://www.ibiblio.org/maven2", defLayout );

  config.addRepository( repo1 );
----------

  The above statements sets up the ProxyConfiguration to use the directory 
  <<</user/proxy-cache>>> as the location of the proxy's repository cache.
  Then it creates a ProxyRepository instance with an id of <<<central>>> to
  look for remote files in ibiblio.org.

Instantiation

  To create or retrieve an instance of a ProxyManager, one will need to use the
  ProxyManagerFactory.

----------
  ProxyManagerFactory factory = (ProxyManagerFactory) container.lookup( ProxyManagerFactory.ROLE );
  proxy = factory.getProxyManager( "default", config );
----------

  The factory requires two parameters.  The first parameter is the proxy_type
  that you will want to use. And the second parameter is the ProxyConfiguration
  which we already did above.  The proxy_type defines the client that the
  ProxyManager is expected to service.  Currently, only <<<default>>>
  ProxyManager type is available and is defined to be for Maven 2.x clients.

Usage

* The get() method

  The ProxyManager get( target ) method is used to retrieve a path file.  This
  method first looks into the cache if the target exists.  If it does not, then
  the ProxyManager will search all the ProxyRepositories present in its
  ProxyConfiguration.  When the target path is found, the ProxyManager creates
  a copy of it in its cache and returns a File instance of the cached copy.

* The getRemoteFile() method

  The ProxyManager getRemoteFile( path ) method is used to force the
  ProxyManager to ignore the contents of its cache and search all the
  ProxyRepository objects for the specified path and retrieve it when
  available.  When successful, the ProxyManager creates a copy of the remote
  file in its cache and then returns a File instance of the cached copy.