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