Author: markt
Date: Mon Oct 21 19:01:37 2013
New Revision: 1534324
URL: http://svn.apache.org/r1534324
Log:
More Checkstyle inspired Javadoc fixes
Added:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/package.html
(with props)
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/BaseProxyHandler.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxyHandler.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxySource.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxyHandler.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxySource.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedKeyedObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxySource.java
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/BaseProxyHandler.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/BaseProxyHandler.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/BaseProxyHandler.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/BaseProxyHandler.java
Mon Oct 21 19:01:37 2013
@@ -21,6 +21,11 @@ import java.lang.reflect.Method;
import org.apache.commons.pool2.UsageTracking;
/**
+ * Base implementation for object wrappers when using a
+ * {@link ProxiedObjectPool}.
+ *
+ * @param <T> type of the wrapped pooled object
+ *
* @since 2.0
*/
class BaseProxyHandler<T> {
@@ -29,17 +34,37 @@ class BaseProxyHandler<T> {
private final UsageTracking<T> usageTracking;
+ /**
+ * Create a new wrapper for the given pooled object.
+ *
+ * @param pooledObject The object to wrap
+ * @param usageTracking The instance, if any (usually the object pool) to
+ * be provided with usage tracking information for
this
+ * wrapped object
+ */
BaseProxyHandler(T pooledObject, UsageTracking<T> usageTracking) {
this.pooledObject = pooledObject;
this.usageTracking = usageTracking;
}
+ /**
+ * Obtain the wrapped, pooled object.
+ *
+ * @return the underlying pooled object
+ */
T getPooledObject() {
return pooledObject;
}
+ /**
+ * Disable the proxy wrapper. Called when the object has been returned to
+ * the pool. Further use of the wrapper should result in an
+ * {@link IllegalStateException}.
+ *
+ * @return the object that this proxy was wrapping
+ */
T disableProxy() {
T result = pooledObject;
pooledObject = null;
@@ -47,6 +72,12 @@ class BaseProxyHandler<T> {
}
+ /**
+ * Check that the proxy is still valid (i.e. that {@link #disableProxy()}
+ * has not been called).
+ *
+ * @throws IllegalStateException if {@link #disableProxy()} has been called
+ */
void validateProxiedObject() {
if (pooledObject == null) {
throw new IllegalStateException("This object may no longer be " +
@@ -55,6 +86,14 @@ class BaseProxyHandler<T> {
}
+ /**
+ * Invoke the given method on the wrapped object.
+ *
+ * @param method The method to invoke
+ * @param args The arguments to the method
+ * @return The result of the method call
+ * @throws Throwable If the method invocation fails
+ */
Object doInvoke(Method method, Object[] args) throws Throwable {
validateProxiedObject();
T pooledObject = getPooledObject();
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxyHandler.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxyHandler.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxyHandler.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxyHandler.java
Mon Oct 21 19:01:37 2013
@@ -24,12 +24,24 @@ import net.sf.cglib.proxy.MethodIntercep
import net.sf.cglib.proxy.MethodProxy;
/**
+ * CGLib implementation of the proxy handler.
+ *
+ * @param <T> type of the wrapped pooled object
+ *
* @since 2.0
*/
public class CglibProxyHandler<T> extends BaseProxyHandler<T>
implements MethodInterceptor {
+ /**
+ * Create a CGLib proxy instance.
+ *
+ * @param pooledObject The object to wrap
+ * @param usageTracking The instance, if any (usually the object pool) to
+ * be provided with usage tracking information for
this
+ * wrapped object
+ */
CglibProxyHandler(T pooledObject, UsageTracking<T> usageTracking) {
super(pooledObject, usageTracking);
}
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxySource.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxySource.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxySource.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/CglibProxySource.java
Mon Oct 21 19:01:37 2013
@@ -22,12 +22,21 @@ import net.sf.cglib.proxy.Factory;
import org.apache.commons.pool2.UsageTracking;
/**
+ * Provides proxy objects using CGLib.
+ *
+ * @param <T> type of the pooled object to be proxied
+ *
* @since 2.0
*/
public class CglibProxySource<T> implements ProxySource<T> {
private final Class<? extends T> superclass;
+ /**
+ * Create a new proxy source for the given class.
+ *
+ * @param superclass The class to proxy
+ */
public CglibProxySource(Class<? extends T> superclass) {
this.superclass = superclass;
}
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxyHandler.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxyHandler.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxyHandler.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxyHandler.java
Mon Oct 21 19:01:37 2013
@@ -22,11 +22,23 @@ import java.lang.reflect.Method;
import org.apache.commons.pool2.UsageTracking;
/**
+ * Java reflection implementation of the proxy handler.
+ *
+ * @param <T> type of the wrapped pooled object
+ *
* @since 2.0
*/
class JdkProxyHandler<T> extends BaseProxyHandler<T>
implements InvocationHandler {
+ /**
+ * Create a Java reflection proxy instance.
+ *
+ * @param pooledObject The object to wrap
+ * @param usageTracking The instance, if any (usually the object pool) to
+ * be provided with usage tracking information for
this
+ * wrapped object
+ */
JdkProxyHandler(T pooledObject, UsageTracking<T> usageTracking) {
super(pooledObject, usageTracking);
}
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxySource.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxySource.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxySource.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/JdkProxySource.java
Mon Oct 21 19:01:37 2013
@@ -21,6 +21,10 @@ import java.lang.reflect.Proxy;
import org.apache.commons.pool2.UsageTracking;
/**
+ * Provides proxy objects using Java reflection.
+ *
+ * @param <T> type of the pooled object to be proxied
+ *
* @since 2.0
*/
class JdkProxySource<T> implements ProxySource<T> {
@@ -29,6 +33,12 @@ class JdkProxySource<T> implements Proxy
private final Class<?>[] interfaces;
+ /**
+ * Create a new proxy source for the given interfaces.
+ *
+ * @param classLoader The class loader with which to create the proxy
+ * @param interfaces The interfaces to proxy
+ */
JdkProxySource(ClassLoader classLoader, Class<?>[] interfaces) {
this.classLoader = classLoader;
this.interfaces = interfaces;
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedKeyedObjectPool.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedKeyedObjectPool.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedKeyedObjectPool.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedKeyedObjectPool.java
Mon Oct 21 19:01:37 2013
@@ -22,6 +22,14 @@ import org.apache.commons.pool2.KeyedObj
import org.apache.commons.pool2.UsageTracking;
/**
+ * Create a new keyed object pool where the pooled objects are wrapped in
+ * proxies allowing better control of pooled objects and in particular the
+ * prevention of the continued use of an object by a client after that client
+ * returns the object to the pool.
+ *
+ * @param <K> type of the key
+ * @param <V> type of the pooled object
+ *
* @since 2.0
*/
public class ProxiedKeyedObjectPool<K,V> implements KeyedObjectPool<K,V> {
@@ -30,6 +38,12 @@ public class ProxiedKeyedObjectPool<K,V>
private final ProxySource<V> proxySource;
+ /**
+ * Create a new proxied object pool.
+ *
+ * @param pool The object pool to wrap
+ * @param proxySource The source of the proxy objects
+ */
public ProxiedKeyedObjectPool(KeyedObjectPool<K,V> pool,
ProxySource<V> proxySource) {
this.pool = pool;
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedObjectPool.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedObjectPool.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedObjectPool.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxiedObjectPool.java
Mon Oct 21 19:01:37 2013
@@ -22,6 +22,13 @@ import org.apache.commons.pool2.ObjectPo
import org.apache.commons.pool2.UsageTracking;
/**
+ * Create a new object pool where the pooled objects are wrapped in proxies
+ * allowing better control of pooled objects and in particular the prevention
+ * of the continued use of an object by a client after that client returns the
+ * object to the pool.
+ *
+ * @param <T> type of the pooled object
+ *
* @since 2.0
*/
public class ProxiedObjectPool<T> implements ObjectPool<T> {
@@ -30,6 +37,12 @@ public class ProxiedObjectPool<T> implem
private final ProxySource<T> proxySource;
+ /**
+ * Create a new proxied object pool.
+ *
+ * @param pool The object pool to wrap
+ * @param proxySource The source of the proxy objects
+ */
public ProxiedObjectPool(ObjectPool<T> pool, ProxySource<T> proxySource) {
this.pool = pool;
this.proxySource = proxySource;
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxySource.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxySource.java?rev=1534324&r1=1534323&r2=1534324&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxySource.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/ProxySource.java
Mon Oct 21 19:01:37 2013
@@ -19,9 +19,33 @@ package org.apache.commons.pool2.proxy;
import org.apache.commons.pool2.UsageTracking;
/**
+ * The interface that any provide of proxy instances must implement to allow
the
+ * {@link ProxiedObjectPool} to create proxies as required.
+ *
+ * @param <T> type of the pooled object to be proxied
+ *
* @since 2.0
*/
interface ProxySource<T> {
+
+ /**
+ * Create a new proxy object, wrapping the given pooled object.
+ *
+ * @param pooledObject The object to wrap
+ * @param usageTracking The instance, if any (usually the object pool) to
+ * be provided with usage tracking information for
this
+ * wrapped object
+ *
+ * @return the new proxy object
+ */
T createProxy(T pooledObject, UsageTracking<T> usageTracking);
+
+ /**
+ * Obtain the wrapped object from the given proxy.
+ *
+ * @param proxy The proxy object
+ *
+ * @return The pooled objetc wrapped by the given proxy
+ */
T resolveProxy(T proxy);
}
Added:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/package.html?rev=1534324&view=auto
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/package.html
(added)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/package.html
Mon Oct 21 19:01:37 2013
@@ -0,0 +1,37 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Package Documentation for org.apache.commons.pool2.proxy</title>
+ </head>
+ <body>
+ <p>
+ Object pooling proxy implementation.
+ </p>
+ <p>
+ The <code>org.apache.commons.pool2.proxy</code> package defines a
+ object pool that wraps all objects returned to clients. This allows it
+ to disable those proxies when the objects are returned thereby
enabling
+ the continued use of those objects by clients to be detected..
+ </p>
+ <p>
+ Support is provided for <code>java.lang.reflect.Proxy</code> and for
+ <code>net.sf.cglib.proxy</code> based proxies. The latter, requires
the
+ additional of the optional Code Generation Library (GCLib).
+ </p>
+ </body>
+</html>
Propchange:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/proxy/package.html
------------------------------------------------------------------------------
svn:eol-style = native
