Author: mbenson
Date: Wed Sep 18 16:07:28 2013
New Revision: 1524473
URL: http://svn.apache.org/r1524473
Log:
site work
Added:
commons/proper/proxy/branches/version-2.0-work/src/site/markdown/
commons/proper/proxy/branches/version-2.0-work/src/site/markdown/index.md
- copied, changed from r1524467,
commons/proper/proxy/branches/version-2.0-work/src/site/xdoc/index.xml
Removed:
commons/proper/proxy/branches/version-2.0-work/src/site/xdoc/index.xml
Modified:
commons/proper/proxy/branches/version-2.0-work/pom.xml
Modified: commons/proper/proxy/branches/version-2.0-work/pom.xml
URL:
http://svn.apache.org/viewvc/commons/proper/proxy/branches/version-2.0-work/pom.xml?rev=1524473&r1=1524472&r2=1524473&view=diff
==============================================================================
--- commons/proper/proxy/branches/version-2.0-work/pom.xml (original)
+++ commons/proper/proxy/branches/version-2.0-work/pom.xml Wed Sep 18 16:07:28
2013
@@ -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>
Copied:
commons/proper/proxy/branches/version-2.0-work/src/site/markdown/index.md (from
r1524467,
commons/proper/proxy/branches/version-2.0-work/src/site/xdoc/index.xml)
URL:
http://svn.apache.org/viewvc/commons/proper/proxy/branches/version-2.0-work/src/site/markdown/index.md?p2=commons/proper/proxy/branches/version-2.0-work/src/site/markdown/index.md&p1=commons/proper/proxy/branches/version-2.0-work/src/site/xdoc/index.xml&r1=1524467&r2=1524473&rev=1524473&view=diff
==============================================================================
--- commons/proper/proxy/branches/version-2.0-work/src/site/xdoc/index.xml
(original)
+++ commons/proper/proxy/branches/version-2.0-work/src/site/markdown/index.md
Wed Sep 18 16:07:28 2013
@@ -1,161 +1,145 @@
-<?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>
+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
