misc/env/src/main/java/org/onap/aaf/misc/env/util/Pool.java

   1 /**\r
   2  * ============LICENSE_START====================================================\r
   3  * org.onap.aaf\r
   4  * ===========================================================================\r
   5  * Copyright (c) 2018 AT&T Intellectual Property. All rights reserved.\r
   6  * ===========================================================================\r
   7  * Licensed under the Apache License, Version 2.0 (the "License");\r
   8  * you may not use this file except in compliance with the License.\r
   9  * You may obtain a copy of the License at\r
  10  * \r
  11  *      http://www.apache.org/licenses/LICENSE-2.0\r
  12  * \r
  13  * Unless required by applicable law or agreed to in writing, software\r
  14  * distributed under the License is distributed on an "AS IS" BASIS,\r
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  16  * See the License for the specific language governing permissions and\r
  17  * limitations under the License.\r
  18  * ============LICENSE_END====================================================\r
  19  *\r
  20  */\r
  21 \r
  22 /*\r
  23  * Pool\r
  24  * \r
  25  * Author: Jonathan\r
  26  * 5/27/2011\r
  27  */\r
  28 package org.onap.aaf.misc.env.util;\r
  29 \r
  30 import java.util.LinkedList;\r
  31 \r
  32 import org.onap.aaf.misc.env.APIException;\r
  33 import org.onap.aaf.misc.env.LogTarget;\r
  34 \r
  35 /**\r
  36  * This Class pools on an As-Needed-Basis any particular kind of class, which is\r
  37  * quite suitable for expensive operations.\r
  38  * \r
  39  * The user calls "get" on a Pool, and if a waiting resource (T) is available,\r
  40  * it will be returned. Otherwise, one will be created with the "Creator" class\r
  41  * (must be defined for (T)).\r
  42  * \r
  43  * You can Prime the instances to avoid huge startup costs\r
  44  * \r
  45  * The returned "Pooled" object simply has to call "done()" and the object is\r
  46  * returned to the pool. If the developer does not return the object, a memory\r
  47  * leak does not occur. There are no references to the object once "get" is\r
  48  * called. However, the developer who does not return the object when done\r
  49  * obviates the point of the pool, as new Objects are created in place of the\r
  50  * Object not returned when another call to "get" is made.\r
  51  * \r
  52  * There is a cushion of extra objects, currently defaulted to MAX_RANGE. If the\r
  53  * items returned become higher than the MAX_RANGE, the object is allowed to go\r
  54  * out of scope, and be cleaned up. the default can be changed on a per-pool\r
  55  * basis.\r
  56  * \r
  57  * \r
  58  * @author Jonathan\r
  59  * \r
  60  * @param <T>\r
  61  */\r
  62 public class Pool<T> {\r
  63     /**\r
  64      * This is a constant which specified the default maximum number of unused\r
  65      * objects to be held at any given time.\r
  66      */\r
  67     private static final int MAX_RANGE = 6; // safety\r
  68 \r
  69     /**\r
  70      * only Simple List needed.\r
  71      * \r
  72      * NOTE TO MAINTAINERS: THIS OBJECT DOES IT'S OWN SYNCHRONIZATION. All\r
  73      * changes that touch list must account for correctly synchronizing list.\r
  74      */\r
  75     private LinkedList<Pooled<T>> list;\r
  76 \r
  77     /**\r
  78      * keep track of how many elements exist, to avoid asking list.\r
  79      */\r
  80     private int count;\r
  81 \r
  82     /**\r
  83      * Spares are those Object that are primed and ready to go.\r
  84      */\r
  85     private int spares;\r
  86 \r
  87     /**\r
  88      * Actual MAX number of spares allowed to hang around. Can be set to\r
  89      * something besides the default MAX_RANGE.\r
  90      */\r
  91     private int max_range = MAX_RANGE;\r
  92 \r
  93     /**\r
  94      * The Creator for this particular pool. It must work for type T.\r
  95      */\r
  96     private Creator<T> creator;\r
  97 \r
  98     /**\r
  99      * Create a new Pool, given the implementation of Creator<T>, which must be\r
 100      * able to create/destroy T objects at will.\r
 101      * \r
 102      * @param creator\r
 103      */\r
 104     public Pool(Creator<T> creator) {\r
 105         count = spares = 0;\r
 106         this.creator = creator;\r
 107         list = new LinkedList<>();\r
 108     }\r
 109 \r
 110     /**\r
 111      * Preallocate a certain number of T Objects. Useful for services so that\r
 112      * the first transactions don't get hit with all the Object creation costs\r
 113      * \r
 114      * @param lt\r
 115      * @param prime\r
 116      * @throws APIException\r
 117      */\r
 118     public void prime(LogTarget lt, int prime) throws APIException {\r
 119         for (int i = 0; i < prime; ++i) {\r
 120             Pooled<T> pt = new Pooled<T>(creator.create(), this, lt);\r
 121             synchronized (list) {\r
 122                 list.addFirst(pt);\r
 123                 ++count;\r
 124             }\r
 125         }\r
 126 \r
 127     }\r
 128 \r
 129     /**\r
 130      * Destroy and remove all remaining objects. This is valuable for closing\r
 131      * down all Allocated objects cleanly for exiting. It is also a good method\r
 132      * for removing objects when, for instance, all Objects are invalid because\r
 133      * of broken connections, etc.\r
 134      */\r
 135     public void drain() {\r
 136         synchronized (list) {\r
 137             for (int i = 0; i < list.size(); ++i) {\r
 138                 Pooled<T> pt = list.remove();\r
 139                 creator.destroy(pt.content);\r
 140                 pt.logTarget.log("Pool drained ", creator.toString());\r
 141             }\r
 142             count = spares = 0;\r
 143         }\r
 144 \r
 145     }\r
 146 \r
 147     /**\r
 148      * This is the essential function for Pool. Get an Object "T" inside a\r
 149      * "Pooled<T>" object. If there is a spare Object, then use it. If not, then\r
 150      * create and pass back.\r
 151      * \r
 152      * This one uses a Null LogTarget\r
 153      * \r
 154      * IMPORTANT: When the use of this object is done (and the object is still\r
 155      * in a valid state), then "done()" should be called immediately to allow\r
 156      * the object to be reused. That is the point of the Pool...\r
 157      * \r
 158      * If the Object is in an invalid state, then "toss()" should be used so the\r
 159      * Pool doesn't pass on invalid objects to others.\r
 160      * \r
 161      * @param lt\r
 162      * @return\r
 163      * @throws APIException\r
 164      */\r
 165     public Pooled<T> get() throws APIException {\r
 166         Pooled<T> pt;\r
 167         synchronized (list) {\r
 168             if (list.isEmpty()) {\r
 169                 pt = null;\r
 170             } else {\r
 171                 pt = list.removeLast();\r
 172                 --count;\r
 173                 creator.reuse(pt.content);\r
 174             }\r
 175         }\r
 176         if (pt == null) {\r
 177             if (spares < max_range)\r
 178                 ++spares;\r
 179             pt = new Pooled<T>(creator.create(), this, LogTarget.NULL);\r
 180         } else {\r
 181             if (spares > 1)\r
 182                 --spares;\r
 183         }\r
 184         return pt;\r
 185     }\r
 186 \r
 187     /**\r
 188      * This is the essential function for Pool. Get an Object "T" inside a\r
 189      * "Pooled<T>" object. If there is a spare Object, then use it. If not, then\r
 190      * create and pass back.\r
 191      * \r
 192      * If you don't have access to a LogTarget from Env, use LogTarget.NULL\r
 193      * \r
 194      * IMPORTANT: When the use of this object is done (and the object is still\r
 195      * in a valid state), then "done()" should be called immediately to allow\r
 196      * the object to be reused. That is the point of the Pool...\r
 197      * \r
 198      * If the Object is in an invalid state, then "toss()" should be used so the\r
 199      * Pool doesn't pass on invalid objects to others.\r
 200      * \r
 201      * @param lt\r
 202      * @return\r
 203      * @throws APIException\r
 204      */\r
 205     public Pooled<T> get(LogTarget lt) throws APIException {\r
 206         Pooled<T> pt;\r
 207         synchronized (list) {\r
 208             if (list.isEmpty()) {\r
 209                 pt = null;\r
 210             } else {\r
 211                 pt = list.remove();\r
 212                 --count;\r
 213                 creator.reuse(pt.content);\r
 214             }\r
 215         }\r
 216         if (pt == null) {\r
 217             if (spares < max_range)\r
 218                 ++spares;\r
 219             pt = new Pooled<T>(creator.create(), this, lt);\r
 220             lt.log("Pool created ", creator.toString());\r
 221         } else {\r
 222             if (spares > 1)\r
 223                 --spares;\r
 224         }\r
 225         return pt;\r
 226     }\r
 227 \r
 228     /**\r
 229      * This function will validate whether the Objects are still in a usable\r
 230      * state. If not, they are tossed from the Pool. This is valuable to have\r
 231      * when Remote Connections go down, and there is a question on whether the\r
 232      * Pooled Objects are still functional.\r
 233      * \r
 234      * @return\r
 235      */\r
 236     public boolean validate() {\r
 237         boolean rv = true;\r
 238         synchronized (list) {\r
 239             for (Pooled<T> t : list) {\r
 240                 if (!creator.isValid(t.content)) {\r
 241                     rv = false;\r
 242                     t.toss();\r
 243                     list.remove(t);\r
 244                 }\r
 245             }\r
 246         }\r
 247         return rv;\r
 248     }\r
 249 \r
 250     /**\r
 251      * This is an internal method, used only by the Internal Pooled<T> class.\r
 252      * \r
 253      * The Pooled<T> class "offers" it's Object back after use. It is an\r
 254      * "offer", because Pool will simply destroy and remove the object if it has\r
 255      * more than enough spares.\r
 256      * \r
 257      * @param lt\r
 258      * @param used\r
 259      * @return\r
 260      */\r
 261     // Used only by Pooled<T>\r
 262     private boolean offer(LogTarget lt, Pooled<T> used) {\r
 263         if (count < spares) {\r
 264             synchronized (list) {\r
 265                 list.addFirst(used);\r
 266                 ++count;\r
 267             }\r
 268             lt.log("Pool recovered ", creator.toString());\r
 269         } else {\r
 270             lt.log("Pool destroyed ", creator.toString());\r
 271             creator.destroy(used.content);\r
 272         }\r
 273         return false;\r
 274     }\r
 275 \r
 276     /**\r
 277      * The Creator Interface give the Pool the ability to Create, Destroy and\r
 278      * Validate the Objects it is maintaining. Thus, it is a specially written\r
 279      * Implementation for each type.\r
 280      * \r
 281      * @author Jonathan\r
 282      * \r
 283      * @param <T>\r
 284      */\r
 285     public interface Creator<T> {\r
 286         public T create() throws APIException;\r
 287 \r
 288         public void destroy(T t);\r
 289 \r
 290         public boolean isValid(T t);\r
 291 \r
 292         public void reuse(T t);\r
 293     }\r
 294 \r
 295     /**\r
 296      * The "Pooled<T>" class is the transient class that wraps the actual Object\r
 297      * T for API use/ It gives the ability to return ("done()", or "toss()") the\r
 298      * Object to the Pool when processing is finished.\r
 299      * \r
 300      * For Safety, i.e. to avoid memory leaks and invalid Object States, there\r
 301      * is a "finalize" method. It is strictly for when coder forgets to return\r
 302      * the object, or perhaps hasn't covered the case during Exceptions or\r
 303      * Runtime Exceptions with finally (preferred). This should not be\r
 304      * considered normal procedure, as finalize() is called at an undetermined\r
 305      * time during garbage collection, and is thus rather useless for a Pool.\r
 306      * However, we don't want Coding Mistakes to put the whole program in an\r
 307      * invalid state, so if something happened such that "done()" or "toss()"\r
 308      * were not called, the resource is still cleaned up as well as possible.\r
 309      * \r
 310      * @author Jonathan\r
 311      * \r
 312      * @param <T>\r
 313      */\r
 314     public static class Pooled<T> {\r
 315         public final T content;\r
 316         private Pool<T> pool;\r
 317         protected LogTarget logTarget;\r
 318 \r
 319         /**\r
 320          * Create the Wrapping Object Pooled<T>.\r
 321          * \r
 322          * @param t\r
 323          * @param pool\r
 324          * @param logTarget\r
 325          */\r
 326         public Pooled(T t, Pool<T> pool, LogTarget logTarget) {\r
 327             content = t;\r
 328             this.pool = pool;\r
 329             this.logTarget = logTarget;\r
 330         }\r
 331 \r
 332         /**\r
 333          * This is the key API for the Pool, as calling "done()" offers this\r
 334          * object back to the Pool for reuse.\r
 335          * \r
 336          * Do not use the Pooled<T> object again after calling "done()".\r
 337          */\r
 338         public void done() {\r
 339             if (pool != null) {\r
 340                 pool.offer(logTarget, this);\r
 341             }\r
 342         }\r
 343 \r
 344         /**\r
 345          * The user of the Object may discover that the Object t is no longer in\r
 346          * a valid state. Don't put Garbage back in the Refrigerator... Toss it,\r
 347          * if it's no longer valid.\r
 348          * \r
 349          * toss() is also used for draining the Pool, etc.\r
 350          * \r
 351          * toss() will attempt to destroy the Object by using the Creator\r
 352          * Interface.\r
 353          * \r
 354          */\r
 355         public void toss() {\r
 356             if (pool != null) {\r
 357                 pool.creator.destroy(content);\r
 358             }\r
 359             // Don't allow finalize to put it back in.\r
 360             pool = null;\r
 361         }\r
 362 \r
 363         /**\r
 364          * Just in case someone neglected to offer back object... Do not rely on\r
 365          * this, as there is no specific time when finalize is called, which\r
 366          * rather defeats the purpose of a Pool.\r
 367          */\r
 368         @Override\r
 369         protected void finalize() throws Throwable {\r
 370             if (pool != null) {\r
 371                 done();\r
 372                 pool = null;\r
 373             }\r
 374         }\r
 375     }\r
 376 \r
 377     /**\r
 378      * Get the maximum number of spare objects allowed at any moment\r
 379      * \r
 380      * @return\r
 381      */\r
 382     public int getMaxRange() {\r
 383         return max_range;\r
 384     }\r
 385 \r
 386     /**\r
 387      * Set a Max Range for numbers of spare objects waiting to be used.\r
 388      * \r
 389      * No negative numbers are allowed\r
 390      * \r
 391      * @return\r
 392      */\r
 393     public void setMaxRange(int max_range) {\r
 394         // Do not allow negative numbers\r
 395         this.max_range = Math.max(0, max_range);\r
 396     }\r
 397 \r
 398 }\r