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

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