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

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