misc/env/src/main/java/org/onap/aaf/misc/env/LifeCycle.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  *\r
  24  * Created on: Aug 19, 2009\r
  25  * Created by: Jonathan\r
  26  *\r
  27  * (c) 2009 SBC Knowledge Ventures, L.P. All rights reserved.\r
  28  ******************************************************************* \r
  29  * RESTRICTED - PROPRIETARY INFORMATION The Information contained \r
  30  * herein is for use only by authorized employees of AT&T Services, \r
  31  * Inc., and authorized Affiliates of AT&T Services, Inc., and is \r
  32  * not for general distribution within or outside the respective \r
  33  * companies. \r
  34  *******************************************************************\r
  35  */\r
  36 package org.onap.aaf.misc.env;\r
  37 \r
  38 import org.onap.aaf.misc.env.util.RefreshableThreadObject;\r
  39 \r
  40 \r
  41 /**\r
  42  * @author Jonathan\r
  43  * \r
  44  */\r
  45 public interface LifeCycle {\r
  46     /**\r
  47      * The Service using LifeCycle Elements is required to call this method at\r
  48      * the appropriate startup time. This is better for services than a simple\r
  49      * static call, because the exact moment of starting can be determined\r
  50      * programatically.\r
  51      * <p>\r
  52      * \r
  53      * An excellent use is to establish security credentials with a backend\r
  54      * after appropriate configurations have been read and available as part of\r
  55      * the {@link Env} Object.\r
  56      * \r
  57      * @param env\r
  58      * @throws APIException\r
  59      */\r
  60     public abstract void servicePrestart(Env env) throws APIException;\r
  61 \r
  62     /**\r
  63      * Many cases of implementations are not thread safe, and mechanisms must be\r
  64      * derived to accomodate them by holding per Thread.\r
  65      * <p>\r
  66      * \r
  67      * {@link ThreadLocal} is a valuable resource, but start up times within the\r
  68      * thread, depending on what it is, can be substantial.\r
  69      * <p>\r
  70      * \r
  71      * Use ThreadPrestart to do all that is possible before actually performing\r
  72      * work, i.e. inside of a client transaction.\r
  73      * \r
  74      * @param env\r
  75      * @throws APIException\r
  76      */\r
  77     public abstract void threadPrestart(Env env) throws APIException;\r
  78 \r
  79     /**\r
  80      * The Service will call this when (service-defined) configurations change.\r
  81      * <p>\r
  82      * \r
  83      * This mechanism allows the Service to recognize events, such as file\r
  84      * changes, and pass on the event to all LifeCycle implementors.\r
  85      * <p>\r
  86      * \r
  87      * The code should take the opportunity to evaluate configuration and change\r
  88      * as necessary.\r
  89      * <p>\r
  90      * \r
  91      * <h2>IMPORTANT:</h2>\r
  92      * The LifeCycle implementor cannot guarantee it will not be in the middle\r
  93      * of a transaction, so it would behoove the implementor to construct\r
  94      * content that does not affect anything until finished, then apply to an\r
  95      * appropriate atomic action (i.e. setting an Object to a field), or even\r
  96      * synchronizing.\r
  97      * \r
  98      * If you are using Java's "ThreadLocal", consider\r
  99      * {@link RefreshableThreadObject}, because it implements LifeCycle, and\r
 100      * responds to the refresh command.\r
 101      * \r
 102      * @param env\r
 103      * @throws APIException\r
 104      */\r
 105     public abstract void refresh(Env env) throws APIException;\r
 106 \r
 107     /**\r
 108      * Parallel to threadPrestart, threadDestroy tells the implementor that the\r
 109      * service is ending this particular thread, and to take this opportunity to\r
 110      * close out any content specific to this thread that can be closed.\r
 111      * \r
 112      * @param env\r
 113      * @throws APIException\r
 114      */\r
 115     public abstract void threadDestroy(Env env) throws APIException;\r
 116 \r
 117     /**\r
 118      * Parallel to servicePrestart, serviceDestroy tells the implementor that\r
 119      * the service is ending, and to take this opportunity to close out any\r
 120      * content under it's control that can or should be closed explicitly.\r
 121      */\r
 122     public abstract void serviceDestroy(Env env) throws APIException;\r
 123 }\r