opendaylight/config/config-api/src/main/java/org/opendaylight/controller/config/spi/ModuleFactory.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 java.util.Set;
  11 import org.opendaylight.controller.config.api.DependencyResolver;
  12 import org.opendaylight.controller.config.api.DependencyResolverFactory;
  13 import org.opendaylight.controller.config.api.DynamicMBeanWithInstance;
  14 import org.opendaylight.controller.config.api.annotations.AbstractServiceInterface;
  15 import org.osgi.framework.BundleContext;
  16
  17 /**
  18  * Factory which creates {@link Module} instances. An instance of this interface
  19  * needs to be exported into the OSGi Service Registry. Such an instance
  20  * provides metadata describing services which can be published from it.
  21  *
  22  * <p>
  23  * Each {@link Module} can optionally be instantiated with a
  24  * {@link javax.management.DynamicMBean} which represents the configuration of
  25  * the currently running instance.
  26  */
  27 public interface ModuleFactory {
  28
  29     /**
  30      * Returns the human-friendly implementation name. This value needs to be unique
  31      * within all implementations of all interfaces returned by
  32      * getImplementedInterfaces().
  33      *
  34      * @return human-friendly implementation name
  35      */
  36     String getImplementationName();
  37
  38     /**
  39      * Create a new Module instance. The returned object is expected to use the
  40      * dependencyResolver provided when resolving ObjectNames to actual Module
  41      * instances.
  42      *
  43      * @param dependencyResolver
  44      *            This resolver will return actual config mbean based on its
  45      *            ObjectName.
  46      * @param bundleContext
  47      *            Reference to OSGi bundleContext that can be used to acquire OSGi
  48      *            services, startup configuration and other OSGi related
  49      *            information.
  50      *
  51      * @return newly created module
  52      *
  53      */
  54     Module createModule(String instanceName, DependencyResolver dependencyResolver, BundleContext bundleContext);
  55
  56     /**
  57      * Create a new Module instance. The returned object is expected to use the
  58      * dependencyResolver provided when resolving ObjectNames to actual Module
  59      * instances. A reference to an abstract view of the previous configuration is
  60      * also provided in the form of a {@link javax.management.DynamicMBean}.
  61      * Implementations should use the MBeanInfo interface to understand the
  62      * structure of the configuration information.
  63      *
  64      * <p>
  65      * Structural information impacts hot-swap operations in that in order to
  66      * perform such a swap the newly loaded code needs to understand the
  67      * previously-running instance configuration layout and how to map it onto
  68      * itself.
  69      *
  70      * @param dependencyResolver
  71      *            This resolver will return actual config mbean based on its
  72      *            ObjectName.
  73      * @param old
  74      *            existing module from platform MBeanServer that is being
  75      *            reconfigured. Implementations should inspect its attributes using
  76      *            {@link javax.management.DynamicMBean#getAttribute(String)} and set
  77      *            those attributes on newly created module. If reconfiguration of
  78      *            live instances is supported, this live instance can be retreived
  79      *            using
  80      *            {@link org.opendaylight.controller.config.api.DynamicMBeanWithInstance#getInstance()}
  81      *            . It is possible that casting this old instance throws
  82      *            {@link ClassCastException} when OSGi bundle is being updated. In
  83      *            this case, implementation should revert to creating new instance.
  84      * @param bundleContext
  85      *            Reference to OSGi bundleContext that can be used to acquire OSGi
  86      *            services, startup configuration and other OSGi related
  87      *            information.
  88      *
  89      * @return newly created module
  90      * @throws Exception
  91      *             if it is not possible to recover configuration from old. This
  92      *             leaves server in a running state but no configuration transaction
  93      *             can be created.
  94      */
  95     Module createModule(String instanceName, DependencyResolver dependencyResolver, DynamicMBeanWithInstance old,
  96             BundleContext bundleContext) throws Exception;
  97
  98     boolean isModuleImplementingServiceInterface(Class<? extends AbstractServiceInterface> serviceInterface);
  99
 100     Set<Class<? extends AbstractServiceInterface>> getImplementedServiceIntefaces();
 101
 102     /**
 103      * Called when ModuleFactory is registered to config manager. Useful for
 104      * populating the registry with pre-existing state. Since the method is called
 105      * for each ModuleFactory separately and transaction is committed automatically,
 106      * returned modules MUST be valid and commitable without any manual
 107      * intervention.
 108      *
 109      * @param dependencyResolverFactory
 110      *            factory for getting dependency resolvers for each module.
 111      * @param bundleContext
 112      *            Reference to OSGi bundleContext that can be used to acquire OSGi
 113      *            services, startup configuration and other OSGi related
 114      *            information.
 115      *
 116      * @return set of default modules. Null is not allowed.
 117      */
 118     Set<? extends Module> getDefaultModules(DependencyResolverFactory dependencyResolverFactory,
 119             BundleContext bundleContext);
 120 }