site work
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/proxy/branches/version-2.0-work@1524473 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/pom.xml b/pom.xml
index 5a71852..0beff6c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -153,6 +153,18 @@
</dependency>
</dependencies>
</plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>3.3</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-module-markdown</artifactId>
+ <version>1.3</version>
+ </dependency>
+ </dependencies>
+ </plugin>
</plugins>
</build>
@@ -177,9 +189,7 @@
<link>http://ws.apache.org/xmlrpc/apidocs/</link>
<link>http://www.csg.is.titech.ac.jp/~chiba/javassist/html</link>
</links>
- <aggregate>true</aggregate>
</configuration>
-
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..040dfe7
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,145 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you 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.
+-->
+
+## Commons Proxy: Dynamic Proxies Made Easy
+
+ The *Proxy* design pattern ([GoF][]) allows you to provide
+ "a surrogate or placeholder for another object to control access to it".
+ Proxies can be used in many ways, some of which are:
+
+ * **Deferred Initialization** -
+ the proxy acts as a "stand-in" for the actual implementation allowing
+ it to be instantiated only when absolutely necessary.
+ * **Security** -
+ the proxy object can verify that the user actually has the permission to
+ execute the method (a la EJB).
+ * **Logging** -
+ the proxy can log evey method invocation, providing valuable debugging
+ information.
+ * **Performance Monitoring** -
+ the proxy can log each method invocation to a performance monitor allowing
+ system administrators to see what parts of the system are potentially
+ bogged down.
+
+ *Commons Proxy* supports dynamic proxy generation using proxy factories,
+ object providers, invokers, and interceptors.
+
+## Proxy Factories
+ A [ProxyFactory][] encapsulates all necessary proxying logic away from your
+ code. Switching proxying techniques/technologies is as simple as using a
+ different proxy factory implementation class.
+ *Commons Proxy* provides several proxy factory implementation modules:
+
+ * [commons-proxy2-jdk][]
+ * [commons-proxy2-cglib][]
+ * [commons-proxy2-javassist][]
+ * [commons-proxy2-asm4][]
+
+ Additionally, the core library provides a proxy factory
+ [implementation][defaultPF] that delegates to instances discoverable using
+ the Java [ServiceLoader][] mechanism (including those provided by the listed
+ modules).
+
+ Proxy factories allow you to create three different types of proxy objects:
+
+ * **Delegator Proxy** - delegates each method invocation to an object
+ provided by an [ObjectProvider][].
+ * **Interceptor Proxy** - allows an [Interceptor][] to intercept each
+ method invocation as it makes its way to the target of the invocation.
+ * **Invoker Proxy** - uses an [Invoker][] to handle all method invocations.
+
+## Object Providers
+ [Object providers][providers] provide the objects which will be the
+ "target" of a proxy. There are two types of object providers:
+
+### Core Object Providers
+ A core object provider provides a core implementation object.
+ *Commons Proxy* supports many different implementations including:
+
+ * **Constant** - Always returns a specific object
+ * **Bean** - Instantiates an object of a specified class each time
+ * **Cloning** - Reflectively calls the public `clone()` method
+ on a `Cloneable` object
+
+### Decorating Object Providers
+ A decorating object provider decorates the object returned by another
+ provider. *Commons Proxy* provides a few implementations including:
+
+ * **Singleton** - Calls a nested provider at most once, returning that
+ original value on all subsequent invocations
+
+## Invokers
+ An [Invoker][] handles all method invocations using a single method.
+ *Commons Proxy* provides a few invoker implementations:
+
+ * **Null** - Always returns a `null` (useful for the "Null Object" pattern)
+ * **Duck Typing** - Supports so-called "duck typing" by adapting a class to
+ an interface it does not implement.
+ * **Invocation Handler Adapter** - Adapts an implementation of the JDK
+[InvocationHandler][] interface as a *Commons Proxy* [Invoker][].
+
+## Interceptors
+ *Commons Proxy* allows you to "intercept" a method invocation using
+ an [Interceptor][]. Interceptors provide *rudimentary* aspect-oriented
+ programming (AOP) support, allowing you to alter the parameters/results
+ of a method invocation without actually changing the implementation of
+ the method itself. *Commons Proxy* provides a few interceptor
+ implementations including:
+
+ * **ObjectProvider** - returns the value from an [ObjectProvider][]
+ * **Throwing** - throws an exception
+ * **Switch** - provides a fluent API to configure the handling
+ of invoked methods
+
+## Releases
+ The latest version is v1.0. - [Download now!][download]
+
+ For previous releases, see the [Apache archive][archive].
+
+ _**Note:** The 1.x releases are compatible with JDK1.4+._
+
+## Support
+ The [Commons mailing lists][mailing-lists] act as the main support forum.
+ The `user` list is suitable for most library usage queries.
+ The `dev` list is intended for the development discussion.
+ Please remember that the lists are shared between all Commons components,
+ so prefix your email subject with `[proxy]`.
+
+ Issues may be reported via [ASF JIRA][issue-tracking]. Please read the
+ instructions carefully to submit a useful bug report or enhancement request.
+
+[download]: http://commons.apache.org/downloads/download_proxy.cgi
+[archive]: http://archive.apache.org/dist/commons/proxy/
+[mailing-lists]: mail-lists.html
+[issue-tracking]: issue-tracking.html
+
+[commons-proxy2-jdk]: commons-proxy2-jdk/index.html
+[commons-proxy2-cglib]: commons-proxy2-cglib/index.html
+[commons-proxy2-javassist]: commons-proxy2-javassist/index.html
+[commons-proxy2-asm4]: commons-proxy2-asm4/index.html
+[ProxyFactory]: apidocs/org/apache/commons/proxy2/ProxyFactory.html
+[ObjectProvider]: apidocs/org/apache/commons/proxy2/ObjectProvider.html
+[Interceptor]: apidocs/org/apache/commons/proxy2/Interceptor.html
+[Invoker]: apidocs/org/apache/commons/proxy2/Invoker.html
+[defaultPF]: apidocs/org/apache/commons/proxy2/ProxyUtils.html#proxyFactory\(\)
+[providers]: apidocs/org/apache/commons/proxy2/provider/package-summary.html
+
+[ServiceLoader]: http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html
+[InvocationHandler]: http://docs.oracle.com/javase/6/docs/api/java/lang/reflect/InvocationHandler.html
+[GoF]: http://www.amazon.com/exec/obidos/tg/detail/-/0201633612/qid=1125413337/sr=1-1/ref=sr_1_1/104-0714405-6441551?v=glance&s=books
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
deleted file mode 100644
index 2b8b47d..0000000
--- a/src/site/xdoc/index.xml
+++ /dev/null
@@ -1,161 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one or more
- ~ contributor license agreements. See the NOTICE file distributed with
- ~ this work for additional information regarding copyright ownership.
- ~ The ASF licenses this file to You 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.
- -->
-
-<document>
- <properties>
- <title>Overview</title>
- <author email="dev AT commons DOT apache DOT org">Apache Commons Development Team</author>
- <author email="jcarman AT apache DOT org">James Carman</author>
- </properties>
-
- <body>
- <section name="Commons Proxy: Dynamic Proxies Made Easy">
- <p>
- The <em>Proxy</em> design pattern (<a href="http://www.amazon.com/exec/obidos/tg/detail/-/0201633612/qid=1125413337/sr=1-1/ref=sr_1_1/104-0714405-6441551?v=glance&s=books">GoF</a>)
- allows you to provide "a surrogate or placeholder for another object to control access to it".
- Proxies can be used in many ways. Some of which are:
- </p>
- <ul>
- <li><b>Deferred Initialization</b> - the proxy acts as a "stand-in" for the actual implementation allowing
- it to be instantiated only when absolutely necessary.</li>
- <li><b>Security</b> - the proxy object can verify that the user actually has the permission to execute
- the method (a la EJB).</li>
- <li><b>Logging</b> - the proxy can log evey method invocation, providing valuable debugging information.</li>
- <li><b>Performance Monitoring</b> - the proxy can log each method invocation to a performance monitor
- allowing system administrators to see what parts of the system are potentially bogged down.</li>
- </ul>
- <p>
- <em>Commons Proxy</em> supports dynamic proxy generation using proxy factories, object providers, invokers, and
- interceptors.
- </p>
- <section name="Proxy Factories">
- <p>
- <a href="apidocs/org/apache/commons/proxy/ProxyFactory.html">Proxy factories</a>
- encapsulate all necessary proxying logic away from your code. Switching proxying
- techniques/technologies is as simple as using a different proxy factory implementation class.
- Currently, <em>Commons Proxy</em> provides proxy factory implementations using JDK proxies,
- <a href="http://cglib.sourceforge.net">CGLIB</a>, and
- <a href="http://www.jboss.org/products/javassist">Javassist</a>. Proxy factories allow you to create
- three different types of proxy objects:
- </p>
- <ul>
- <li><b>Delegator Proxies</b> - a proxy that merely delegates each method invocation to an
- object provided by an <a href="apidocs/org/apache/commons/proxy/ObjectProvider.html">object provider</a>.</li>
- <li><b>Interceptor Proxies</b> - a proxy that allows an <a href="apidocs/org/apache/commons/proxy/Interceptor.html">Interceptor</a> to intercept each
- method invocation as it makes its way to the target of the invocation.</li>
- <li><b>Invoker Proxies</b> - a proxy that uses an
- <a href="apidocs/org/apache/commons/proxy/Invoker.html">invoker</a> to handle all method
- invocations.</li>
- </ul>
- </section>
- <section name="Object Providers">
- <p>
- <a href="apidocs/org/apache/commons/proxy/provider/package-summary.html">Object providers</a>
- provide the
- objects which will be the "target" of a proxy. There are two types of object providers:
- <subsection name="Core Object Providers">
- <p>
- A core object provider provides a core implementation object. <em>Commons Proxy</em> supports
- many different implementations including:
- </p>
- <table border="0">
- <tr><td><b>Constant</b></td><td>Always returns a specific object</td></tr>
- <tr><td><b>Bean</b></td><td>Merely instantiates an object of a specified class each time</td></tr>
- <tr><td><b>Cloning</b></td><td>Reflectively calls the public clone() method on a Cloneable object</td></tr>
- <tr><td><b>Hessian</b></td><td>Returns a <a href="http://www.caucho.com/hessian/index.xtp">Hessian</a>-based service object</td></tr>
- <tr><td><b>Burlap</b></td><td>Returns a <a href="http://www.caucho.com/burlap/index.xtp">Burlap</a>-based service object</td></tr>
- <tr><td><b>JAX-RPC</b></td><td>Returns a <a href="http://java.sun.com/webservices/jaxrpc/index.jsp">JAX-RPC</a>-based service object</td></tr>
- <tr><td><b>Session Bean</b></td><td>Returns a reference to a Session EJB (stateless session beans only)</td></tr>
- </table>
- </subsection>
- <subsection name="Decorating Object Providers">
- <p>
- A decorating object provider decorates the object returned by another provider.
- <em>Commons Proxy</em> provides a few implementations including:
- </p>
- <table border="0">
- <tr><td><b>Singleton</b></td><td>Calls a nested provider at most once, returning that original value on all subsequent invocations</td></tr>
- </table>
-
- </subsection>
-
- </p>
- </section>
- <section name="Invokers">
- <p>
- An <a href="apidocs/org/apache/commons/proxy/Invoker.html">invoker</a> handles all
- method invocations using a single method. <em>Commons Proxy</em> provides a few invoker implementations:
- </p>
- <table border="0">
- <tr><td><b>Null</b></td><td>Always returns a null (useful for the "Null Object" pattern)</td></tr>
- <tr><td><b>Apache XML-RPC</b></td><td>Uses <a href="http://ws.apache.org/xmlrpc/">Apache XML-RPC</a> to fulfill the method invocation</td></tr>
- <tr><td><b>Duck Typing</b></td><td>Supports "duck typing" by adapting a class to an interface it does not implement.</td></tr>
- <tr><td><b>Invocation Handler Adapter</b></td><td>Adapts the JDK <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/reflect/InvocationHandler.html">InvocationHandler</a> interface
- to the <em>Commons Proxy</em> <a href="apidocs/org/apache/commons/proxy/Invoker.html">Invoker</a> interface.</td></tr>
- </table>
-
- </section>
- <section name="Interceptors">
- <p>
- <em>Commons Proxy</em> allows you to "intercept" a method invocation using <a href="apidocs/org/apache/commons/proxy/Interceptor.html">Interceptors</a>.
- Interceptors provide <em>rudimentary</em> aspect-oriented
- programming support, allowing you to alter the results/effects of a method invocation without actually
- changing the implementation of the method itself. <em>Commons Proxy</em> provides a few interceptor
- implementations including:
- </p>
- <table border="0">
- <tr><td><b>Executor</b></td><td>Uses an
- <a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/Executor.html">Executor</a> to execute the method in possibly another thread (only void methods are supported).</td></tr>
- <tr><td><b>Logging</b></td><td>Logs all method invocations using the
- <a href="http://commons.apache.org/logging/">Apache Commons Logging</a> API</td></tr>
- <tr><td><b>Filtered</b></td><td>Optionally intercepts a method invocation based on a
- <a href="apidocs/org/apache/commons/proxy/interceptor/MethodFilter.html">method filter</a></td></tr>
- <tr><td><b>Method Interceptor Adapter</b></td><td>Adapts the AOP Alliance <a href="http://aopalliance.sourceforge.net/doc/org/aopalliance/intercept/MethodInterceptor.html">MethodInterceptor</a> interface to the
- <em>Commons Proxy</em> <a href="apidocs/org/apache/commons/proxy/Interceptor.html">Interceptor</a> interface.</td></tr>
-
- </table>
- </section>
- </section>
- <section name="Releases">
- <p>
- The latest version is v1.0. -
- <a href="http://commons.apache.org/downloads/download_proxy.cgi">Download now!</a><br />
- </p>
- <p>
- For previous releases, see the <a href="http://archive.apache.org/dist/commons/proxy/">Apache Archive</a>
- </p>
- <p>
- <i><b>Note:</b> The 1.x releases are compatible with JDK1.4+.</i>
- </p>
- </section>
- <section name="Support">
- <p>
- The <a href="mail-lists.html">commons mailing lists</a> act as the main support forum.
- The user list is suitable for most library usage queries.
- The dev list is intended for the development discussion.
- Please remember that the lists are shared between all commons components,
- so prefix your email subject with [proxy].
- </p>
- <p>
- Issues may be reported via <a href="issue-tracking.html">ASF JIRA</a>.
- Please read the instructions carefully to submit a useful bug report or enhancement request.
- </p>
- </section>
- </body>
-</document>