Mechanical code cleanup (config)
[controller.git] / 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     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     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     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     Set<? extends Module> getDefaultModules(DependencyResolverFactory dependencyResolverFactory,
116             BundleContext bundleContext);
117
118 }

©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.