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 javax.management.DynamicMBean;
  11
  12 import org.opendaylight.controller.config.api.DependencyResolver;
  13 import org.opendaylight.controller.config.api.DynamicMBeanWithInstance;
  14 import org.opendaylight.controller.config.api.annotations.AbstractServiceInterface;
  15
  16 /**
  17  * Factory which creates {@link Module instances. An instance of this interface
  18  * needs to be exported into the OSGi Service Registry. Such an instance
  19  * provides metadata describing services which can be published from it.
  20  *
  21  * Each {@link Module } can optionally be instantiated with a
  22  * {@link DynamicMBean} which represents the configuration of the currently
  23  * running instance.
  24  */
  25 public interface ModuleFactory {
  26
  27     /**
  28      * Returns the human-friendly implementation name. This value needs to be
  29      * unique within all implementations of all interfaces returned by
  30      * getImplementedInterfaces().
  31      *
  32      * @return human-friendly implementation name
  33      */
  34     public String getImplementationName();
  35
  36     /**
  37      * Create a new Module instance. The returned object is expected to use the
  38      * dependencyResolver provided when resolving ObjectNames to actual Module
  39      * instances.
  40      *
  41      * @param dependencyResolver
  42      *            This resolver will return actual config mbean based on its
  43      *            ObjectName.
  44      * @return newly created module
  45      *
  46      */
  47     public Module createModule(String instanceName,
  48             DependencyResolver dependencyResolver);
  49
  50     /**
  51      * Create a new Module instance. The returned object is expected to use the
  52      * dependencyResolver provided when resolving ObjectNames to actual Module
  53      * instances. A reference to an abstract view of the previous configuration
  54      * is also provided in the form of a {@link DynamicMBean}. Implementations
  55      * should use the MBeanInfo interface to understand the structure of the
  56      * configuration information.
  57      *
  58      * Structural information impacts hot-swap operations in that in order to
  59      * perform such a swap the newly loaded code needs to understand the
  60      * previously-running instance configuration layout and how to map it onto
  61      * itself.
  62      *
  63      * @param dependencyResolver
  64      *            This resolver will return actual config mbean based on its
  65      *            ObjectName.
  66      * @param old
  67      *            existing module from platform MBeanServer that is being
  68      *            reconfigured. Implementations should inspect its attributes
  69      *            using {@link DynamicMBean#getAttribute(String)} and set those
  70      *            attributes on newly created module. If reconfiguration of live
  71      *            instances is supported, this live instance can be retreived
  72      *            using
  73      *            {@link org.opendaylight.controller.config.api.DynamicMBeanWithInstance#getInstance()}
  74      *            . It is possible that casting this old instance throws
  75      *            {@link ClassCastException} when OSGi bundle is being updated.
  76      *            In this case, implementation should revert to creating new
  77      *            instance.
  78      * @return newly created module
  79      * @throws Exception
  80      *             if it is not possible to recover configuration from old. This
  81      *             leaves server in a running state but no configuration
  82      *             transaction can be created.
  83      */
  84     public Module createModule(String instanceName,
  85             DependencyResolver dependencyResolver, DynamicMBeanWithInstance old)
  86             throws Exception;
  87
  88     boolean isModuleImplementingServiceInterface(
  89             Class<? extends AbstractServiceInterface> serviceInterface);
  90
  91 }