Mechanical code cleanup (sal-dom-api)
[controller.git] / opendaylight / md-sal / sal-dom-api / src / main / java / org / opendaylight / controller / sal / core / api / Broker.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.sal.core.api;
9
10 import org.osgi.framework.BundleContext;
11
12 /**
13  * Core component of the SAL layer responsible for wiring the SAL consumers.
14  *
15  * The responsibility of the broker is to maintain registration of SAL
16  * functionality {@link Consumer}s and {@link Provider}s, store provider and
17  * consumer specific context and functionality registration via
18  * {@link ConsumerSession} and provide access to infrastructure services, which
19  * removes direct dependencies between providers and consumers.
20  *
21  *
22  * The services are exposed via session.
23  *
24  * <h3>Session-based access</h3>
25  *
26  * The providers and consumers needs to register in order to use the
27  * binding-independent SAL layer and to expose functionality via SAL layer.
28  *
29  * For more information about session-based access see {@link ConsumerSession}
30  * and {@link ProviderSession}
31  *
32  *
33  *
34  */
35 public interface Broker {
36
37     /**
38      * Registers the {@link Consumer}, which will use the SAL layer.
39      *
40      * <p>
41      * During the registration, the broker obtains the initial functionality
42      * from consumer, using the {@link Consumer#getConsumerFunctionality()}, and
43      * register that functionality into system and concrete infrastructure
44      * services.
45      *
46      * <p>
47      * Note that consumer could register additional functionality at later point
48      * by using service and functionality specific APIs.
49      *
50      * <p>
51      * The consumer is required to use returned session for all communication
52      * with broker or one of the broker services. The session is announced to
53      * the consumer by invoking
54      * {@link Consumer#onSessionInitiated(ConsumerSession)}.
55      *
56      * @param cons
57      *            Consumer to be registered.
58      * @return a session specific to consumer registration
59      * @throws IllegalArgumentException
60      *             If the consumer is <code>null</code>.
61      * @throws IllegalStateException
62      *             If the consumer is already registered.
63      */
64     ConsumerSession registerConsumer(Consumer cons);
65
66     /*
67      * @deprecated Use registerConsumer(Consumer cons) instead (BundleContext is no longer used)
68      */
69     @Deprecated
70     ConsumerSession registerConsumer(Consumer cons, BundleContext context);
71
72     /**
73      * Registers the {@link Provider}, which will use the SAL layer.
74      *
75      * <p>
76      * During the registration, the broker obtains the initial functionality
77      * from consumer, using the {@link Provider#getProviderFunctionality()}, and
78      * register that functionality into system and concrete infrastructure
79      * services.
80      * <p>
81      * The consumer is <b>required to use</b> returned session for all
82      * communication with broker or one of the broker services. The session is
83      * announced to the consumer by invoking
84      * {@link Provider#onSessionInitiated(ProviderSession)}.
85      *
86      *
87      * @param prov
88      *            Provider to be registered.
89      * @return a session unique to the provider registration.
90      * @throws IllegalArgumentException
91      *             If the provider is <code>null</code>.
92      * @throws IllegalStateException
93      *             If the consumer is already registered.
94      */
95     ProviderSession registerProvider(Provider prov);
96
97     /*
98      * @deprecated Use registerProvider(Provider cons) instead (BundleContext is no longer used)
99      */
100     @Deprecated
101     ProviderSession registerProvider(Provider prov, BundleContext context);
102
103     /**
104      * {@link Consumer} specific access to the SAL functionality.
105      *
106      * <p>
107      * ConsumerSession is {@link Consumer}-specific access to the SAL
108      * functionality and infrastructure services.
109      *
110      * <p>
111      * The session serves to store SAL context (e.g. registration of
112      * functionality) for the consumer and provides access to the SAL
113      * infrastructure services and other functionality provided by
114      * {@link Provider}s.
115      *
116      *
117      *
118      */
119     interface ConsumerSession {
120
121         boolean isClosed();
122
123         /**
124          * Returns a session specific instance (implementation) of requested
125          * service
126          *
127          * @param service
128          *            Broker service
129          * @return Session specific implementation of service
130          */
131         <T extends BrokerService> T getService(Class<T> service);
132
133         /**
134          * Closes a session between consumer and broker.
135          *
136          * <p>
137          * The close operation unregisters a consumer and remove all registered
138          * functionality of the consumer from the system.
139          *
140          */
141         void close();
142     }
143
144     /**
145      * {@link Provider} specific access to the SAL functionality.
146      *
147      * <p>
148      * ProviderSession is {@link Provider}-specific access to the SAL
149      * functionality and infrastructure services, which also allows for exposing
150      * the provider's functionality to the other {@link Consumer}s.
151      *
152      * <p>
153      * The session serves to store SAL context (e.g. registration of
154      * functionality) for the providers and exposes access to the SAL
155      * infrastructure services, dynamic functionality registration and any other
156      * functionality provided by other {@link Provider}s.
157      *
158      */
159     interface ProviderSession extends ConsumerSession {
160         /**
161          * Closes a session between provider and SAL.
162          *
163          * <p>
164          * The close operation unregisters a provider and remove all registered
165          * functionality of the provider from the system.
166          */
167         @Override
168         void close();
169
170         @Override
171         boolean isClosed();
172     }
173 }

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