Merge "Update devices page"
[controller.git] / opendaylight / clustering / services / src / main / java / org / opendaylight / controller / clustering / services / IClusterServices.java
1
2 /*
3  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
4  *
5  * This program and the accompanying materials are made available under the
6  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
7  * and is available at http://www.eclipse.org/legal/epl-v10.html
8  */
9
10 /**
11  * @file   IClusterServices.java
12  *
13  * @brief  : Set of services an application will expect from the
14  * clustering services provider
15  *
16  * Contract between the applications and the clustering service
17  * providers.
18  */
19
20 package org.opendaylight.controller.clustering.services;
21
22 import java.net.InetAddress;
23 import java.util.List;
24 import java.util.Properties;
25 import java.util.Set;
26 import java.util.concurrent.ConcurrentMap;
27
28 import javax.transaction.HeuristicMixedException;
29 import javax.transaction.HeuristicRollbackException;
30 import javax.transaction.NotSupportedException;
31 import javax.transaction.RollbackException;
32 import javax.transaction.SystemException;
33 import javax.transaction.Transaction;
34
35 /**
36  * Set of services an application will expect from the
37  * clustering services provider
38  *
39  */
40 public interface IClusterServices {
41
42     /**
43      * Enumeration of the several modality with which a
44      * ConcurrentHashMap cache can be requested to the clustering
45      * services. The property that can be requested can be multiple.
46      *
47      */
48     public enum cacheMode {
49         /**
50          * Set for a cache that supports transaction that implies that
51          * is a transaction is open on the current thread the data
52          * will not immediately be reflected in the cache but will be
53          * staged till commit or rollback. If the transaction if NOT
54          * open the data will immediately go in the cache without
55          * staging.
56          */
57         TRANSACTIONAL,
58         /**
59          * Set on a cache that doesn't want to support
60          * transaction, so irrespective of the fact that we are in
61          * the middle of a transaction or no data will be
62          * immediately committed in the cache.
63          *
64          */
65         NON_TRANSACTIONAL;
66     }
67
68     /**
69      * Enumeration of the several properties that a cache can carry
70      *
71      */
72     public enum cacheProps {
73         /**
74          * The property returned describe the characteristics of the
75          * transaction setup for the cache it was retrieved.
76          */
77         TRANSACTION_PROP,
78         /**
79          * The property returned report the clustering
80          * characteristics of the cache for which property was
81          * queried.
82          */
83         CLUSTERING_PROP,
84         /**
85          * The property returned reports the locking
86          * characteristics of the cache for which the property was
87          * queried
88          */
89         LOCKING_PROP;
90     }
91
92     /**
93      * Method that will create a new named cache per-container. The data
94      * structure if already present will cause an exception to be
95      * thrown to the caller.
96      *
97      * @param containerName Container to which the datastructure is associated
98      * @param cacheName Name of the ConcurrentHashMap to create
99      * @param cMode Mode of the cache that need to be retrieved. This
100      * is a set such that more than one property can be provided, of
101      * course contrasting requirements will not be accepted and in
102      * that case an exception is thrown
103      *
104      * @return ConcurrentHashMap to be used to modify the data structure
105      */
106     ConcurrentMap<?, ?> createCache(String containerName, String cacheName,
107             Set<cacheMode> cMode) throws CacheExistException,
108             CacheConfigException;
109
110     /**
111      * Method that will retrieve and return the handle to modify a
112      * data structire distributed via clustering services. The
113      * datastructure shall already have been created else a null
114      * reference will be returned.
115      *
116      * @param containerName Container to which the datastructure is associated
117      * @param cacheName Name of the ConcurrentHashMap to retrieve
118      *
119      * @return ConcurrentHashMap to be used to modify the data structure
120      */
121     ConcurrentMap<? extends Object, ? extends Object> getCache(String containerName, String cacheName);
122
123     /**
124      * Destroy a cachename given containerName/cachename, if doesn't exist
125      * the function does nothing. If the datastructure exists, the
126      * whole cluster will destroy the instance
127      *
128      * @param containerName Container to which the datastructure is associated
129      * @param cacheName Name of the ConcurrentHashMap to destroy
130      */
131     void destroyCache(String containerName, String cacheName);
132
133     /**
134      * Function to test the existance of a cache with a given name already
135      *
136      * @param containerName Container to which the datastructure is associated
137      * @param cacheName Name of the ConcurrentHashMap to destroy
138      *
139      * @return true if exists already, false otherwise
140      */
141     boolean existCache(String containerName, String cacheName);
142
143     /**
144      * Return the list of all teh caches registered with a container
145      *
146      * @param containerName Container for which we want to list all the caches registered
147      *
148      * @return The set of names, expressed as strings
149      */
150     Set<String> getCacheList(String containerName);
151
152     /**
153      * Return a list of properties that caracterize the cache
154      *
155      * @param containerName Name of the container where data structure resides
156      * @param cacheName Name of the cache
157      *
158      * @return The list of properties related to the cache
159      */
160     Properties getCacheProperties(String containerName, String cacheName);
161
162     /**
163      * Register an update handler for a given containerName/cacheName
164      * shared data structure. Multiple listeners are possible.
165      *
166      * @param containerName Container to which the datastructure is associated
167      * @param cacheName Name of the ConcurrentHashMap for which we
168      * want to register the listener
169      * @param u Interface to invoke when the updates are received
170      */
171     void addListener(String containerName, String cacheName, IGetUpdates<?, ?> u)
172             throws CacheListenerAddException;
173
174     /**
175      * Return a set of interfaces that are interesteed to listen to
176      * updates coming for a given datastructure shared via clustering
177      * services.
178      *
179      * @param containerName Container to which the datastructure is associated
180      * @param cacheName Name of the ConcurrentHashMap for which we
181      * want to retrieve the listener
182      */
183     Set<IGetUpdates<?, ?>> getListeners(String containerName, String cacheName);
184
185     /**
186      * UN-Register an update handler for a given containerName/cacheName
187      * shared data structure. Multiple listeners are possible.
188      *
189      * @param containerName Container to which the datastructure is associated
190      * @param cacheName Name of the ConcurrentHashMap for which we
191      * want to un-register the listener
192      * @param u Interface to un-register
193      */
194     void removeListener(String containerName, String cacheName,
195             IGetUpdates<?, ?> u);
196
197     /**
198      * Begin a transaction covering with all the data structures/HW
199      * updates. One transaction per-thread can be opened at the
200      * most, that means if multiple thread are available, multiple
201      * transactions can be outstanding.
202      *
203      */
204     void tbegin() throws NotSupportedException, SystemException;
205
206     /**
207      * Commit a transaction covering all the data structures/HW updates.
208      */
209     void tcommit() throws RollbackException, HeuristicMixedException,
210             HeuristicRollbackException, java.lang.SecurityException,
211             java.lang.IllegalStateException, SystemException;
212
213     /**
214      * Rollback a transaction covering all the data structures/HW updates
215      */
216     void trollback() throws java.lang.IllegalStateException,
217             java.lang.SecurityException, SystemException;
218
219     /**
220      * Return the javax.transaction.Transaction associated with this thread
221      *
222      *
223      * @return Return the current transaction associated with this thread
224      */
225     Transaction tgetTransaction() throws SystemException;
226
227     /**
228      * @deprecated
229      * Function that says if we are standby in the 1-1 redundancy with
230      * active/standby model. The API is not encouraged hence is
231      * deprecated. It is supposed to be used as a stop-gap till the
232      * active-standby goal is achieved. The only guys that are
233      * supposed to use are:
234      * - southbound layer, should not listen on the OF port if standby
235      * - jetty configuration, on standby jetty should redirect calls
236      * to the active.
237      *
238      * @return true if the role is the one of standby, else false
239      */
240     boolean amIStandby();
241
242     /**
243      * @deprecated
244      * Get the InetAddress of the active controller for the
245      * active-standby case, where the standby controller has to
246      * redirect the HTTP requests received from applications layer
247      *
248      * @return Address of the active controller
249      */
250     InetAddress getActiveAddress();
251
252     /**
253      * Get the InetAddress of the all the controllers that make up this
254      * Cluster
255      *
256      * @return List of InetAddress'es of all the controllers
257      */
258     List<InetAddress> getClusteredControllers();
259
260     /**
261      * Get the InetAddress of this Controller as seen by the Cluster Manager
262      *
263      * @return InetAddress of this Controller as seen by the Cluster Manager.
264      */
265     InetAddress getMyAddress();
266
267     /**
268      * @deprecated
269      * Register a listener to the event of ChangeRole, raised every
270      * time there is a change in the role of active or standby.
271      *
272      * @param i Interface that will be called when the Role Change happens
273      */
274     void listenRoleChange(IListenRoleChange i)
275             throws ListenRoleChangeAddException;
276
277     /**
278      * @deprecated
279      * UN-Register a listener to the event of ChangeRole, raised every
280      * time there is a change in the role of active or standby.
281      *
282      * @param i Interface that will be called when the Role Change happens
283      */
284     void unlistenRoleChange(IListenRoleChange i);
285 }