3 * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
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
11 * @file IClusterServices.java
13 * @brief : Set of services an application will expect from the
14 * clustering services provider
16 * Contract between the applications and the clustering service
20 package org.opendaylight.controller.clustering.services;
22 import java.net.InetAddress;
23 import java.util.List;
24 import java.util.Properties;
26 import java.util.concurrent.ConcurrentMap;
27 import java.util.concurrent.TimeUnit;
29 import javax.transaction.HeuristicMixedException;
30 import javax.transaction.HeuristicRollbackException;
31 import javax.transaction.NotSupportedException;
32 import javax.transaction.RollbackException;
33 import javax.transaction.SystemException;
34 import javax.transaction.Transaction;
37 * Set of services an application will expect from the
38 * clustering services provider
41 public interface IClusterServices {
44 * Enumeration of the several modality with which a
45 * ConcurrentHashMap cache can be requested to the clustering
46 * services. The property that can be requested can be multiple.
49 public enum cacheMode {
51 * Set for a cache that supports transaction that implies that
52 * is a transaction is open on the current thread the data
53 * will not immediately be reflected in the cache but will be
54 * staged till commit or rollback. If the transaction if NOT
55 * open the data will immediately go in the cache without
60 * Set on a cache that doesn't want to support
61 * transaction, so irrespective of the fact that we are in
62 * the middle of a transaction or no data will be
63 * immediately committed in the cache.
68 * Set on a cache that can transfer the updates asynchronously from the
69 * calling thread. The caller when doing put/clear/remove cannot expect
70 * that the operation has happened clusterwide
74 * Set on a cache that transfer the updates synchronously to the calling
75 * thread so when getting back the operation is supposed to have
76 * completed on all the cluster nodes. Slow but safe.
82 * Enumeration of the several properties that a cache can carry
85 public enum cacheProps {
87 * The property returned describe the characteristics of the
88 * transaction setup for the cache it was retrieved.
92 * The property returned report the clustering
93 * characteristics of the cache for which property was
98 * The property returned reports the locking
99 * characteristics of the cache for which the property was
106 * Method that will create a new named cache per-container. The data
107 * structure if already present will cause an exception to be
108 * thrown to the caller.
110 * @param containerName Container to which the datastructure is associated
111 * @param cacheName Name of the ConcurrentHashMap to create
112 * @param cMode Mode of the cache that need to be retrieved. This
113 * is a set such that more than one property can be provided, of
114 * course contrasting requirements will not be accepted and in
115 * that case an exception is thrown
117 * @return ConcurrentHashMap to be used to modify the data structure
119 ConcurrentMap<?, ?> createCache(String containerName, String cacheName,
120 Set<cacheMode> cMode) throws CacheExistException,
121 CacheConfigException;
124 * Method that will retrieve and return the handle to modify a
125 * data structire distributed via clustering services. The
126 * datastructure shall already have been created else a null
127 * reference will be returned.
129 * @param containerName Container to which the datastructure is associated
130 * @param cacheName Name of the ConcurrentHashMap to retrieve
132 * @return ConcurrentHashMap to be used to modify the data structure
134 ConcurrentMap<? extends Object, ? extends Object> getCache(String containerName, String cacheName);
137 * Destroy a cachename given containerName/cachename, if doesn't exist
138 * the function does nothing. If the datastructure exists, the
139 * whole cluster will destroy the instance
141 * @param containerName Container to which the datastructure is associated
142 * @param cacheName Name of the ConcurrentHashMap to destroy
144 void destroyCache(String containerName, String cacheName);
147 * Function to test the existance of a cache with a given name already
149 * @param containerName Container to which the datastructure is associated
150 * @param cacheName Name of the ConcurrentHashMap to destroy
152 * @return true if exists already, false otherwise
154 boolean existCache(String containerName, String cacheName);
157 * Return the list of all teh caches registered with a container
159 * @param containerName Container for which we want to list all the caches registered
161 * @return The set of names, expressed as strings
163 Set<String> getCacheList(String containerName);
166 * Return a list of properties that caracterize the cache
168 * @param containerName Name of the container where data structure resides
169 * @param cacheName Name of the cache
171 * @return The list of properties related to the cache
173 Properties getCacheProperties(String containerName, String cacheName);
176 * Register an update handler for a given containerName/cacheName
177 * shared data structure. Multiple listeners are possible.
179 * @param containerName Container to which the datastructure is associated
180 * @param cacheName Name of the ConcurrentHashMap for which we
181 * want to register the listener
182 * @param u Interface to invoke when the updates are received
184 void addListener(String containerName, String cacheName, IGetUpdates<?, ?> u)
185 throws CacheListenerAddException;
188 * Return a set of interfaces that are interesteed to listen to
189 * updates coming for a given datastructure shared via clustering
192 * @param containerName Container to which the datastructure is associated
193 * @param cacheName Name of the ConcurrentHashMap for which we
194 * want to retrieve the listener
196 Set<IGetUpdates<?, ?>> getListeners(String containerName, String cacheName);
199 * UN-Register an update handler for a given containerName/cacheName
200 * shared data structure. Multiple listeners are possible.
202 * @param containerName Container to which the datastructure is associated
203 * @param cacheName Name of the ConcurrentHashMap for which we
204 * want to un-register the listener
205 * @param u Interface to un-register
207 void removeListener(String containerName, String cacheName,
208 IGetUpdates<?, ?> u);
211 * Begin a transaction covering with all the data structures/HW
212 * updates. One transaction per-thread can be opened at the
213 * most, that means if multiple thread are available, multiple
214 * transactions can be outstanding.
217 void tbegin() throws NotSupportedException, SystemException;
220 * tbegin with a timeout
221 * @see IClusterServices#tbegin
222 * @param timeout the transaction timeout
223 * @param unit TimeUnit for the timeout
224 * @throws NotSupportedException
225 * @throws SystemException
227 void tbegin(long timeout, TimeUnit unit) throws NotSupportedException, SystemException;
230 * Commit a transaction covering all the data structures/HW updates.
232 void tcommit() throws RollbackException, HeuristicMixedException,
233 HeuristicRollbackException, java.lang.SecurityException,
234 java.lang.IllegalStateException, SystemException;
237 * Rollback a transaction covering all the data structures/HW updates
239 void trollback() throws java.lang.IllegalStateException,
240 java.lang.SecurityException, SystemException;
243 * Return the javax.transaction.Transaction associated with this thread
246 * @return Return the current transaction associated with this thread
248 Transaction tgetTransaction() throws SystemException;
252 * Function that says if we are standby in the 1-1 redundancy with
253 * active/standby model. The API is not encouraged hence is
254 * deprecated. It is supposed to be used as a stop-gap till the
255 * active-standby goal is achieved. The only guys that are
256 * supposed to use are:
257 * - southbound layer, should not listen on the OF port if standby
258 * - jetty configuration, on standby jetty should redirect calls
261 * @return true if the role is the one of standby, else false
264 boolean amIStandby();
268 * Get the InetAddress of the active controller for the
269 * active-standby case, where the standby controller has to
270 * redirect the HTTP requests received from applications layer
272 * @return Address of the active controller
275 InetAddress getActiveAddress();
278 * Get the InetAddress of the all the controllers that make up this
281 * @return List of InetAddress'es of all the controllers
283 List<InetAddress> getClusteredControllers();
286 * Get the InetAddress of this Controller as seen by the Cluster Manager
288 * @return InetAddress of this Controller as seen by the Cluster Manager.
290 InetAddress getMyAddress();
294 * Register a listener to the event of ChangeRole, raised every
295 * time there is a change in the role of active or standby.
297 * @param i Interface that will be called when the Role Change happens
300 void listenRoleChange(IListenRoleChange i)
301 throws ListenRoleChangeAddException;
305 * UN-Register a listener to the event of ChangeRole, raised every
306 * time there is a change in the role of active or standby.
308 * @param i Interface that will be called when the Role Change happens
311 void unlistenRoleChange(IListenRoleChange i);