37dcd65d0afd47d72e678602b53fa509e28cad3f
[controller.git] / 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 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.