PR: MRM-43

Added how-to apt

git-svn-id: https://svn.apache.org/repos/asf/maven/repository-manager/trunk@376214 13f79535-47bb-0310-9956-ffa450edef68

maven-repository-proxy/src/site/apt/how-to.apt

@@ -0,0 +1,73 @@
+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 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.