opendaylight/adsal/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 import java.util.concurrent.TimeUnit;
  28
  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;
  35
  36 /**
  37  * Set of services an application will expect from the
  38  * clustering services provider
  39  *
  40  */
  41 public interface IClusterServices {
  42
  43     /**
  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.
  47      *
  48      */
  49     public enum cacheMode {
  50         /**
  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
  56          * staging.
  57          */
  58         TRANSACTIONAL,
  59         /**
  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.
  64          *
  65          */
  66         NON_TRANSACTIONAL,
  67         /**
  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
  71          */
  72         ASYNC,
  73         /**
  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.
  77          */
  78         SYNC;
  79     }
  80
  81     /**
  82      * Enumeration of the several properties that a cache can carry
  83      *
  84      */
  85     public enum cacheProps {
  86         /**
  87          * The property returned describe the characteristics of the
  88          * transaction setup for the cache it was retrieved.
  89          */
  90         TRANSACTION_PROP,
  91         /**
  92          * The property returned report the clustering
  93          * characteristics of the cache for which property was
  94          * queried.
  95          */
  96         CLUSTERING_PROP,
  97         /**
  98          * The property returned reports the locking
  99          * characteristics of the cache for which the property was
 100          * queried
 101          */
 102         LOCKING_PROP;
 103     }
 104
 105     /**
 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.
 109      *
 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
 116      *
 117      * @return ConcurrentHashMap to be used to modify the data structure
 118      */
 119     ConcurrentMap<?, ?> createCache(String containerName, String cacheName,
 120             Set<cacheMode> cMode) throws CacheExistException,
 121             CacheConfigException;
 122
 123     /**
 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.
 128      *
 129      * @param containerName Container to which the datastructure is associated
 130      * @param cacheName Name of the ConcurrentHashMap to retrieve
 131      *
 132      * @return ConcurrentHashMap to be used to modify the data structure
 133      */
 134     ConcurrentMap<? extends Object, ? extends Object> getCache(String containerName, String cacheName);
 135
 136     /**
 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
 140      *
 141      * @param containerName Container to which the datastructure is associated
 142      * @param cacheName Name of the ConcurrentHashMap to destroy
 143      */
 144     void destroyCache(String containerName, String cacheName);
 145
 146     /**
 147      * Function to test the existance of a cache with a given name already
 148      *
 149      * @param containerName Container to which the datastructure is associated
 150      * @param cacheName Name of the ConcurrentHashMap to destroy
 151      *
 152      * @return true if exists already, false otherwise
 153      */
 154     boolean existCache(String containerName, String cacheName);
 155
 156     /**
 157      * Return the list of all teh caches registered with a container
 158      *
 159      * @param containerName Container for which we want to list all the caches registered
 160      *
 161      * @return The set of names, expressed as strings
 162      */
 163     Set<String> getCacheList(String containerName);
 164
 165     /**
 166      * Return a list of properties that caracterize the cache
 167      *
 168      * @param containerName Name of the container where data structure resides
 169      * @param cacheName Name of the cache
 170      *
 171      * @return The list of properties related to the cache
 172      */
 173     Properties getCacheProperties(String containerName, String cacheName);
 174
 175     /**
 176      * Register an update handler for a given containerName/cacheName
 177      * shared data structure. Multiple listeners are possible.
 178      *
 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
 183      */
 184     void addListener(String containerName, String cacheName, IGetUpdates<?, ?> u)
 185             throws CacheListenerAddException;
 186
 187     /**
 188      * Return a set of interfaces that are interesteed to listen to
 189      * updates coming for a given datastructure shared via clustering
 190      * services.
 191      *
 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
 195      */
 196     Set<IGetUpdates<?, ?>> getListeners(String containerName, String cacheName);
 197
 198     /**
 199      * UN-Register an update handler for a given containerName/cacheName
 200      * shared data structure. Multiple listeners are possible.
 201      *
 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
 206      */
 207     void removeListener(String containerName, String cacheName,
 208             IGetUpdates<?, ?> u);
 209
 210     /**
 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.
 215      *
 216      */
 217     void tbegin() throws NotSupportedException, SystemException;
 218
 219     /**
 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
 226      */
 227     void tbegin(long timeout, TimeUnit unit) throws NotSupportedException, SystemException;
 228
 229     /**
 230      * Commit a transaction covering all the data structures/HW updates.
 231      */
 232     void tcommit() throws RollbackException, HeuristicMixedException,
 233             HeuristicRollbackException, java.lang.SecurityException,
 234             java.lang.IllegalStateException, SystemException;
 235
 236     /**
 237      * Rollback a transaction covering all the data structures/HW updates
 238      */
 239     void trollback() throws java.lang.IllegalStateException,
 240             java.lang.SecurityException, SystemException;
 241
 242     /**
 243      * Return the javax.transaction.Transaction associated with this thread
 244      *
 245      *
 246      * @return Return the current transaction associated with this thread
 247      */
 248     Transaction tgetTransaction() throws SystemException;
 249
 250     /**
 251      * @deprecated
 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
 259      * to the active.
 260      *
 261      * @return true if the role is the one of standby, else false
 262      */
 263     @Deprecated
 264     boolean amIStandby();
 265
 266     /**
 267      * @deprecated
 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
 271      *
 272      * @return Address of the active controller
 273      */
 274     @Deprecated
 275     InetAddress getActiveAddress();
 276
 277     /**
 278      * Get the InetAddress of the all the controllers that make up this
 279      * Cluster
 280      *
 281      * @return List of InetAddress'es of all the controllers
 282      */
 283     List<InetAddress> getClusteredControllers();
 284
 285     /**
 286      * Get the InetAddress of this Controller as seen by the Cluster Manager
 287      *
 288      * @return InetAddress of this Controller as seen by the Cluster Manager.
 289      */
 290     InetAddress getMyAddress();
 291
 292     /**
 293      * @deprecated
 294      * Register a listener to the event of ChangeRole, raised every
 295      * time there is a change in the role of active or standby.
 296      *
 297      * @param i Interface that will be called when the Role Change happens
 298      */
 299     @Deprecated
 300     void listenRoleChange(IListenRoleChange i)
 301             throws ListenRoleChangeAddException;
 302
 303     /**
 304      * @deprecated
 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.
 307      *
 308      * @param i Interface that will be called when the Role Change happens
 309      */
 310     @Deprecated
 311     void unlistenRoleChange(IListenRoleChange i);
 312 }