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;
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;
36 * Set of services an application will expect from the
37 * clustering services provider
40 public interface IClusterServices {
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.
48 public enum cacheMode {
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
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.
69 * Enumeration of the several properties that a cache can carry
72 public enum cacheProps {
74 * The property returned describe the characteristics of the
75 * transaction setup for the cache it was retrieved.
79 * The property returned report the clustering
80 * characteristics of the cache for which property was
85 * The property returned reports the locking
86 * characteristics of the cache for which the property was
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.
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
104 * @return ConcurrentHashMap to be used to modify the data structure
106 ConcurrentMap<?, ?> createCache(String containerName, String cacheName,
107 Set<cacheMode> cMode) throws CacheExistException,
108 CacheConfigException;
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.
116 * @param containerName Container to which the datastructure is associated
117 * @param cacheName Name of the ConcurrentHashMap to retrieve
119 * @return ConcurrentHashMap to be used to modify the data structure
121 ConcurrentMap<? extends Object, ? extends Object> getCache(String containerName, String cacheName);
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
128 * @param containerName Container to which the datastructure is associated
129 * @param cacheName Name of the ConcurrentHashMap to destroy
131 void destroyCache(String containerName, String cacheName);
134 * Function to test the existance of a cache with a given name already
136 * @param containerName Container to which the datastructure is associated
137 * @param cacheName Name of the ConcurrentHashMap to destroy
139 * @return true if exists already, false otherwise
141 boolean existCache(String containerName, String cacheName);
144 * Return the list of all teh caches registered with a container
146 * @param containerName Container for which we want to list all the caches registered
148 * @return The set of names, expressed as strings
150 Set<String> getCacheList(String containerName);
153 * Return a list of properties that caracterize the cache
155 * @param containerName Name of the container where data structure resides
156 * @param cacheName Name of the cache
158 * @return The list of properties related to the cache
160 Properties getCacheProperties(String containerName, String cacheName);
163 * Register an update handler for a given containerName/cacheName
164 * shared data structure. Multiple listeners are possible.
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
171 void addListener(String containerName, String cacheName, IGetUpdates<?, ?> u)
172 throws CacheListenerAddException;
175 * Return a set of interfaces that are interesteed to listen to
176 * updates coming for a given datastructure shared via clustering
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
183 Set<IGetUpdates<?, ?>> getListeners(String containerName, String cacheName);
186 * UN-Register an update handler for a given containerName/cacheName
187 * shared data structure. Multiple listeners are possible.
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
194 void removeListener(String containerName, String cacheName,
195 IGetUpdates<?, ?> u);
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.
204 void tbegin() throws NotSupportedException, SystemException;
207 * Commit a transaction covering all the data structures/HW updates.
209 void tcommit() throws RollbackException, HeuristicMixedException,
210 HeuristicRollbackException, java.lang.SecurityException,
211 java.lang.IllegalStateException, SystemException;
214 * Rollback a transaction covering all the data structures/HW updates
216 void trollback() throws java.lang.IllegalStateException,
217 java.lang.SecurityException, SystemException;
220 * Return the javax.transaction.Transaction associated with this thread
223 * @return Return the current transaction associated with this thread
225 Transaction tgetTransaction() throws SystemException;
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
238 * @return true if the role is the one of standby, else false
240 boolean amIStandby();
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
248 * @return Address of the active controller
250 InetAddress getActiveAddress();
253 * Get the InetAddress of the all the controllers that make up this
256 * @return List of InetAddress'es of all the controllers
258 List<InetAddress> getClusteredControllers();
261 * Get the InetAddress of this Controller as seen by the Cluster Manager
263 * @return InetAddress of this Controller as seen by the Cluster Manager.
265 InetAddress getMyAddress();
269 * Register a listener to the event of ChangeRole, raised every
270 * time there is a change in the role of active or standby.
272 * @param i Interface that will be called when the Role Change happens
274 void listenRoleChange(IListenRoleChange i)
275 throws ListenRoleChangeAddException;
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.
282 * @param i Interface that will be called when the Role Change happens
284 void unlistenRoleChange(IListenRoleChange i);