Platform hardening for common bundle
[appc.git] / appc-common / src / main / java / org / onap / appc / pool / CachedElement.java
1 /*-
2  * ============LICENSE_START=======================================================
3  * ONAP : APPC
4  * ================================================================================
5  * Copyright (C) 2017 AT&T Intellectual Property. All rights reserved.
6  * ================================================================================
7  * Copyright (C) 2017 Amdocs
8  * =============================================================================
9  * Licensed under the Apache License, Version 2.0 (the "License");
10  * you may not use this file except in compliance with the License.
11  * You may obtain a copy of the License at
12  * 
13  *      http://www.apache.org/licenses/LICENSE-2.0
14  * 
15  * Unless required by applicable law or agreed to in writing, software
16  * distributed under the License is distributed on an "AS IS" BASIS,
17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18  * See the License for the specific language governing permissions and
19  * limitations under the License.
20  * 
21  * ECOMP is a trademark and service mark of AT&T Intellectual Property.
22  * ============LICENSE_END=========================================================
23  */
24
25 package org.onap.appc.pool;
26
27 import java.io.Closeable;
28 import java.io.IOException;
29 import java.lang.reflect.InvocationHandler;
30 import java.lang.reflect.Method;
31 import java.lang.reflect.Proxy;
32 import java.util.concurrent.atomic.AtomicBoolean;
33
34 /**
35  * This class is used as a "wrapper" for any closeable elements that are cached in a pool. It is
36  * implemented as a dynamic proxy, so that it appears to be the same class of object to the client
37  * as the interface being cached. The generic type being cached MUST be an interface.
38  * 
39  * @param <T> The generic type that we create a cached element for. This type is used to wrap
40  *        instances of this type and expose access to the {@link java.io.Closeable} interface by
41  *        using a dynamic proxy.
42  */
43
44 public class CachedElement<T extends Closeable>
45         implements Closeable, InvocationHandler, CacheManagement {
46
47     /**
48      * The pool that is managing this cached element
49      */
50     private Pool<T> pool;
51
52     /**
53      * The element that we are caching in the pool
54      */
55     private T element;
56
57     /**
58      * A thread-safe atomic indicator that tells us that the wrapped element has been released to
59      * the pool already, and not to do it again.
60      */
61     private AtomicBoolean released = new AtomicBoolean(false);
62
63     /**
64      * Create a new instance of a cached element dynamic proxy for use in the pool.
65      * <p>
66      * This returns an instance of the proxy to the caller that appears to be the same interface(s)
67      * as the object being cached. The dynamic proxy then intercepts all open and close semantics
68      * and directs that element to the pool.
69      * </p>
70      * <p>
71      * If the object being proxied does not implement the {@link CacheManagement} interface, then
72      * that interface is added to the dynamic proxy being created. This interface is actually
73      * implemented by the invocation handler (this object) for the proxy and allows direct access to
74      * the wrapped object inside the proxy.
75      * </p>
76      *
77      * @param pool The pool that we are caching these elements within
78      * @param element The element actually being cached
79      * @param interfaces The interface list of interfaces the element must implement (usually one)
80      * @return The dynamic proxy
81      */
82     @SuppressWarnings("unchecked")
83     public static <T extends Closeable> T newInstance(Pool<T> pool, T element,
84             Class<?>[] interfaces) {
85         ClassLoader cl = element.getClass().getClassLoader();
86         CachedElement<T> ce = new CachedElement<>(pool, element);
87         boolean found = false;
88         for (Class<?> intf : interfaces) {
89             if (intf.getName().equals(CacheManagement.class.getName())) {
90                 found = true;
91                 break;
92             }
93         }
94
95         int length = found ? interfaces.length : interfaces.length + 1;
96         Class<?>[] proxyInterfaces = new Class[length];
97         System.arraycopy(interfaces, 0, proxyInterfaces, 0, interfaces.length);
98
99         if (!found) {
100             proxyInterfaces[interfaces.length] = CacheManagement.class;
101         }
102
103         return (T) Proxy.newProxyInstance(cl, proxyInterfaces, ce);
104     }
105
106     /**
107      * Construct a cached element and assign it to the pool as a free element
108      *
109      * @param pool The pool that the element will be managed within
110      * @param element The element we are caching
111      */
112     @SuppressWarnings("unchecked")
113     public CachedElement(Pool<T> pool, T element) {
114         this.pool = pool;
115         this.element = element;
116
117         try {
118             pool.release((T) this);
119         } catch (PoolDrainedException e) {
120             e.printStackTrace();
121         }
122     }
123
124     /**
125      * This method delegates the close call to the actual wrapped element.
126      * <p>
127      * NOTE: This is not the same method that is called by the dynamic proxy. This method is in
128      * place to satisfy the signature of the {@link java.io.Closeable} interface. If it were to be
129      * called directly, then we will delegate the close to the underlying context. However, when the
130      * cached element is called as a synamic proxy, entry is in the
131      * {@link #invoke(Object, Method, Object[])} method.
132      * </p>
133      * 
134      * @see java.io.Closeable#close()
135      */
136     @Override
137     public void close() throws IOException {
138         element.close();
139     }
140
141     /**
142      * This method is the magic part of dynamic proxies. When the caller makes a method call based
143      * on the interface being proxied, this method is given control. This informs us of the method
144      * and arguments of the call. The object reference is that of the dynamic proxy itself, which is
145      * us.
146      * <p>
147      * Here we will check to see if the user is trying to close the "element" (the dynamic proxy
148      * acts like the wrapped element). If he is, then we don't really close it, but instead release
149      * the element that we are wrapping back to the free pool. Once this has happened, we mark the
150      * element as "closed" (from the perspective of this dynamic proxy) so that we wont try to
151      * release it again.
152      * </p>
153      * <p>
154      * If the method is the <code>equals</code> method then we assume that we are comparing the
155      * cached element in one dynamic proxy to the cached element in another. We execute the
156      * comparison between the cached elements, and not the dynamic proxies themselves. This
157      * preserves the allusion to the caller that the dynamic proxy is the object being wrapped.
158      * </p>
159      * <p>
160      * For convenience, we also implement the <code>getWrappedObject</code> method so that the
161      * dynamic proxy can be called to obtain the actual wrapped object if desired. Note, to use this
162      * method, the caller would have to invoke it through reflection.
163      * </p>
164      * <p>
165      * If the method being invoked is not one that we intercept, then we simply delegate that method
166      * onto the wrapped object.
167      * </p>
168      * 
169      * @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object, java.lang.reflect.Method,
170      *      java.lang.Object[])
171      */
172     @SuppressWarnings({"unchecked", "nls"})
173     @Override
174     public Object invoke(Object proxy, Method method, Object[] args) throws Exception {
175         Object result = null;
176
177         switch (method.getName()) {
178             case "close":
179                 if (released.compareAndSet(false, true)) {
180                     if (!pool.isDrained()) {
181                         pool.release((T) proxy);
182                     }
183                 }
184                 break;
185             case "equals":
186                 CacheManagement cm = (CacheManagement) proxy;
187                 T other = (T) cm.getWrappedObject();
188                 result = element.equals(other);
189                 break;
190             case "getWrappedObject":
191                 return element;
192             default:
193                 result = method.invoke(element, args);
194                 break;
195         }
196
197         return result;
198     }
199
200     /**
201      * This method is used to be able to access the wrapped object underneath the dynamic proxy
202      * 
203      * @see org.onap.appc.pool.CacheManagement#getWrappedObject()
204      */
205     @Override
206     public T getWrappedObject() {
207         return element;
208     }
209
210     @SuppressWarnings("nls")
211     @Override
212     public String toString() {
213         return element == null ? "null" : element.toString();
214     }
215 }