opendaylight/config/config-api/src/main/java/org/opendaylight/controller/config/spi/AbstractModule.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8
   9 package org.opendaylight.controller.config.spi;
  10
  11 import org.opendaylight.controller.config.api.DependencyResolver;
  12 import org.opendaylight.controller.config.api.ModuleIdentifier;
  13 import org.slf4j.Logger;
  14 import org.slf4j.LoggerFactory;
  15
  16 /**
  17  * Base implementation of Module. This implementation contains base logic for Module reconfiguration with associated fields.
  18  * @param <M> Type of module implementation. Enables easier implementation for the {@link #isSame} method
  19  */
  20 public abstract class AbstractModule<M extends AbstractModule<M>> implements org.opendaylight.controller.config.spi.Module {
  21
  22     private static final Logger LOG = LoggerFactory.getLogger(AbstractModule.class);
  23
  24     protected final DependencyResolver dependencyResolver;
  25     protected final ModuleIdentifier identifier;
  26
  27     private AutoCloseable oldInstance;
  28     private M oldModule;
  29     private AutoCloseable instance;
  30
  31     /**
  32      * Called when module is configured.
  33      *
  34      * @param identifier id of current instance.
  35      * @param dependencyResolver resolver used in dependency injection and validation.
  36      */
  37     public AbstractModule(final ModuleIdentifier identifier, final DependencyResolver dependencyResolver) {
  38         this(identifier, dependencyResolver, null, null);
  39     }
  40
  41     /**
  42      * Called when module is reconfigured.
  43      *
  44      * @param identifier id of current instance.
  45      * @param dependencyResolver resolver used in dependency injection and validation.
  46      * @param oldModule old instance of module that is being reconfigred(replaced) by current instance. The old instance can be examined for reuse.
  47      * @param oldInstance old instance wrapped by the old module. This is the resource that is actually being reused if possible or closed otherwise.
  48      */
  49     public AbstractModule(final ModuleIdentifier identifier, final DependencyResolver dependencyResolver, final M oldModule, final AutoCloseable oldInstance) {
  50         this.identifier = identifier;
  51         this.dependencyResolver = dependencyResolver;
  52         this.oldModule = oldModule;
  53         this.oldInstance = oldInstance;
  54     }
  55
  56     @Override
  57     public ModuleIdentifier getIdentifier() {
  58         return identifier;
  59     }
  60
  61     /**
  62      *
  63      * General algorithm for spawning/closing and reusing wrapped instances.
  64      *
  65      * @return current instance of wrapped resource either by reusing the old one (if present) or constructing a brand new.
  66      */
  67     @Override
  68     public final AutoCloseable getInstance() {
  69         if (instance == null) {
  70             if (oldInstance != null && canReuseInstance(oldModule)) {
  71                 resolveDependencies();
  72                 instance = reuseInstance(oldInstance);
  73             } else {
  74                 if (oldInstance != null) {
  75                     try {
  76                         oldInstance.close();
  77                     } catch (Exception e) {
  78                         LOG.error("An error occurred while closing old instance {} for module {}", oldInstance, getIdentifier(), e);
  79                     }
  80                 }
  81                 resolveDependencies();
  82                 instance = createInstance();
  83                 if (instance == null) {
  84                     throw new IllegalStateException("Error in createInstance - null is not allowed as return value. Module: " + getIdentifier());
  85                 }
  86             }
  87
  88             // Prevent serial memory leak: clear these references as we will not use them again.
  89             oldInstance = null;
  90             oldModule = null;
  91         }
  92
  93         return instance;
  94     }
  95
  96     /**
  97      * @return Brand new instance of wrapped class in case no previous instance is present or reconfiguration is impossible.
  98      */
  99     protected abstract AutoCloseable createInstance();
 100
 101     @Override
 102     public final boolean canReuse(final Module oldModule) {
 103         // Just cast into a specific instance
 104         // TODO unify this method with canReuseInstance (required Module interface to be generic which requires quite a lot of changes)
 105         return getClass().isInstance(oldModule) ? canReuseInstance((M) oldModule) : false;
 106     }
 107
 108     /**
 109      *
 110      * Users are welcome to override this method to provide custom logic for advanced reusability detection.
 111      *
 112      * @param oldModule old instance of a Module
 113      * @return true if the old instance is reusable false if a new one should be spawned
 114      */
 115     protected abstract boolean canReuseInstance(final M oldModule);
 116
 117     /**
 118      * By default the oldInstance is returned since this method is by default called only if the oldModule had the same configuration and dependencies configured.
 119      * Users are welcome to override this method to provide custom logic for advanced reusability.
 120      *
 121      * @param oldInstance old instance of a class wrapped by the module
 122      * @return reused instance
 123      */
 124     protected AutoCloseable reuseInstance(final AutoCloseable oldInstance) {
 125         // implement if instance reuse should be supported. Override canReuseInstance to change the criteria.
 126         return oldInstance;
 127     }
 128
 129     /**
 130      * Inject all the dependencies using dependency resolver instance.
 131      */
 132     protected abstract void resolveDependencies();
 133 }