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

   1 /*
   2  * Copyright (c) 2013, 2017 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 package org.opendaylight.controller.config.spi;
   9
  10 import javax.annotation.concurrent.NotThreadSafe;
  11 import org.opendaylight.controller.config.api.ModuleIdentifier;
  12 import org.opendaylight.yangtools.concepts.Identifiable;
  13
  14 /**
  15  * Represents one service that is to be configured. These methods need to be
  16  * implemented in addition to the usual attribute getters/setters. Dependencies
  17  * should always be injected as ObjectName references to the corresponding
  18  * ConfigBeans.
  19  * <p>
  20  * In order to guide dependency resolution, the setter method should be
  21  * annotated with
  22  * {@link org.opendaylight.controller.config.api.annotations.RequireInterface}.
  23  * </p>
  24  * <p>
  25  * Thread safety note: implementations of this interface are not required to be
  26  * thread safe as thread safety is enforced by configuration manager.
  27  * </p>
  28  */
  29 @NotThreadSafe
  30 public interface Module extends Identifiable<ModuleIdentifier> {
  31     /**
  32      * This method will be called as first phase in two phase commit. Instance can
  33      * check attributes, but is not allowed to do any kind of work that could leave
  34      * any resources open. It is prohibited to call {@link #getInstance()} on
  35      * dependent {@link Module} because it would destroy separation between
  36      * validation and commit phase.
  37      *
  38      */
  39     void validate();
  40
  41     /**
  42      * Returns 'live' object that was configured using this object. It is allowed to
  43      * call this method only after all ConfigBeans were validated. In this method
  44      * new resources might be opened or old instance might be modified. This method
  45      * must be implemented so that it returns same result for a single transaction.
  46      * Since Module is created per transaction this means that it must be safe to
  47      * cache result of first call.
  48      *
  49      *
  50      * @return closeable instance: After bundle update the factory might be able to
  51      *         copy old configuration into new one without being able to cast Module
  52      *         or the instance. Thus to clean up old instance, it will call close().
  53      */
  54     AutoCloseable getInstance();
  55
  56     /**
  57      * Compare current module with oldModule and if the instance/live object
  58      * produced by the old module can be reused in this module as well return true.
  59      * Typically true should be returned if the old module had the same
  60      * configuration.
  61      *
  62      *
  63      * @param oldModule
  64      *            old instance of Module
  65      * @return true if the instance produced by oldModule can be reused with current
  66      *         instance as well.
  67      */
  68     boolean canReuse(Module oldModule);
  69 }