env/src/main/java/org/onap/aaf/inno/env/LifeCycle.java

   1 /*******************************************************************************\r
   2  * ============LICENSE_START====================================================\r
   3  * * org.onap.aaf\r
   4  * * ===========================================================================\r
   5  * * Copyright © 2017 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  * * ECOMP is a trademark and service mark of AT&T Intellectual Property.\r
  21  * *\r
  22  ******************************************************************************/\r
  23 /**\r
  24  *\r
  25  * Created on: Aug 19, 2009\r
  26  * Created by:\r
  27  *\r
  28  * (c) 2009 SBC Knowledge Ventures, L.P. All rights reserved.\r
  29  ******************************************************************* \r
  30  * RESTRICTED - PROPRIETARY INFORMATION The Information contained \r
  31  * herein is for use only by authorized employees of AT&T Services, \r
  32  * Inc., and authorized Affiliates of AT&T Services, Inc., and is \r
  33  * not for general distribution within or outside the respective \r
  34  * companies. \r
  35  *******************************************************************\r
  36  */\r
  37 package org.onap.aaf.inno.env;\r
  38 \r
  39 import org.onap.aaf.inno.env.util.RefreshableThreadObject;\r
  40 \r
  41 \r
  42 /**\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