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          * Set on a cache that can transfer the updates asynchronously from the
  68          * calling thread. The caller when doing put/clear/remove cannot expect
  69          * that the operation has happened clusterwide
  70          */
  71         ASYNC,
  72         /**
  73          * Set on a cache that transfer the updates synchronously to the calling
  74          * thread so when getting back the operation is supposed to have
  75          * completed on all the cluster nodes. Slow but safe.
  76          */
  77         SYNC;
  78     }
  79
  80     /**
  81      * Enumeration of the several properties that a cache can carry
  82      *
  83      */
  84     public enum cacheProps {
  85         /**
  86          * The property returned describe the characteristics of the
  87          * transaction setup for the cache it was retrieved.
  88          */
  89         TRANSACTION_PROP,
  90         /**
  91          * The property returned report the clustering
  92          * characteristics of the cache for which property was
  93          * queried.
  94          */
  95         CLUSTERING_PROP,
  96         /**
  97          * The property returned reports the locking
  98          * characteristics of the cache for which the property was
  99          * queried
 100          */
 101         LOCKING_PROP;
 102     }
 103
 104     /**
 105      * Method that will create a new named cache per-container. The data
 106      * structure if already present will cause an exception to be
 107      * thrown to the caller.
 108      *
 109      * @param containerName Container to which the datastructure is associated
 110      * @param cacheName Name of the ConcurrentHashMap to create
 111      * @param cMode Mode of the cache that need to be retrieved. This
 112      * is a set such that more than one property can be provided, of
 113      * course contrasting requirements will not be accepted and in
 114      * that case an exception is thrown
 115      *
 116      * @return ConcurrentHashMap to be used to modify the data structure
 117      */
 118     ConcurrentMap<?, ?> createCache(String containerName, String cacheName,
 119             Set<cacheMode> cMode) throws CacheExistException,
 120             CacheConfigException;
 121
 122     /**
 123      * Method that will retrieve and return the handle to modify a
 124      * data structire distributed via clustering services. The
 125      * datastructure shall already have been created else a null
 126      * reference will be returned.
 127      *
 128      * @param containerName Container to which the datastructure is associated
 129      * @param cacheName Name of the ConcurrentHashMap to retrieve
 130      *
 131      * @return ConcurrentHashMap to be used to modify the data structure
 132      */
 133     ConcurrentMap<? extends Object, ? extends Object> getCache(String containerName, String cacheName);
 134
 135     /**
 136      * Destroy a cachename given containerName/cachename, if doesn't exist
 137      * the function does nothing. If the datastructure exists, the
 138      * whole cluster will destroy the instance
 139      *
 140      * @param containerName Container to which the datastructure is associated
 141      * @param cacheName Name of the ConcurrentHashMap to destroy
 142      */
 143     void destroyCache(String containerName, String cacheName);
 144
 145     /**
 146      * Function to test the existance of a cache with a given name already
 147      *
 148      * @param containerName Container to which the datastructure is associated
 149      * @param cacheName Name of the ConcurrentHashMap to destroy
 150      *
 151      * @return true if exists already, false otherwise
 152      */
 153     boolean existCache(String containerName, String cacheName);
 154
 155     /**
 156      * Return the list of all teh caches registered with a container
 157      *
 158      * @param containerName Container for which we want to list all the caches registered
 159      *
 160      * @return The set of names, expressed as strings
 161      */
 162     Set<String> getCacheList(String containerName);
 163
 164     /**
 165      * Return a list of properties that caracterize the cache
 166      *
 167      * @param containerName Name of the container where data structure resides
 168      * @param cacheName Name of the cache
 169      *
 170      * @return The list of properties related to the cache
 171      */
 172     Properties getCacheProperties(String containerName, String cacheName);
 173
 174     /**
 175      * Register an update handler for a given containerName/cacheName
 176      * shared data structure. Multiple listeners are possible.
 177      *
 178      * @param containerName Container to which the datastructure is associated
 179      * @param cacheName Name of the ConcurrentHashMap for which we
 180      * want to register the listener
 181      * @param u Interface to invoke when the updates are received
 182      */
 183     void addListener(String containerName, String cacheName, IGetUpdates<?, ?> u)
 184             throws CacheListenerAddException;
 185
 186     /**
 187      * Return a set of interfaces that are interesteed to listen to
 188      * updates coming for a given datastructure shared via clustering
 189      * services.
 190      *
 191      * @param containerName Container to which the datastructure is associated
 192      * @param cacheName Name of the ConcurrentHashMap for which we
 193      * want to retrieve the listener
 194      */
 195     Set<IGetUpdates<?, ?>> getListeners(String containerName, String cacheName);
 196
 197     /**
 198      * UN-Register an update handler for a given containerName/cacheName
 199      * shared data structure. Multiple listeners are possible.
 200      *
 201      * @param containerName Container to which the datastructure is associated
 202      * @param cacheName Name of the ConcurrentHashMap for which we
 203      * want to un-register the listener
 204      * @param u Interface to un-register
 205      */
 206     void removeListener(String containerName, String cacheName,
 207             IGetUpdates<?, ?> u);
 208
 209     /**
 210      * Begin a transaction covering with all the data structures/HW
 211      * updates. One transaction per-thread can be opened at the
 212      * most, that means if multiple thread are available, multiple
 213      * transactions can be outstanding.
 214      *
 215      */
 216     void tbegin() throws NotSupportedException, SystemException;
 217
 218     /**
 219      * Commit a transaction covering all the data structures/HW updates.
 220      */
 221     void tcommit() throws RollbackException, HeuristicMixedException,
 222             HeuristicRollbackException, java.lang.SecurityException,
 223             java.lang.IllegalStateException, SystemException;
 224
 225     /**
 226      * Rollback a transaction covering all the data structures/HW updates
 227      */
 228     void trollback() throws java.lang.IllegalStateException,
 229             java.lang.SecurityException, SystemException;
 230
 231     /**
 232      * Return the javax.transaction.Transaction associated with this thread
 233      *
 234      *
 235      * @return Return the current transaction associated with this thread
 236      */
 237     Transaction tgetTransaction() throws SystemException;
 238
 239     /**
 240      * @deprecated
 241      * Function that says if we are standby in the 1-1 redundancy with
 242      * active/standby model. The API is not encouraged hence is
 243      * deprecated. It is supposed to be used as a stop-gap till the
 244      * active-standby goal is achieved. The only guys that are
 245      * supposed to use are:
 246      * - southbound layer, should not listen on the OF port if standby
 247      * - jetty configuration, on standby jetty should redirect calls
 248      * to the active.
 249      *
 250      * @return true if the role is the one of standby, else false
 251      */
 252     @Deprecated
 253     boolean amIStandby();
 254
 255     /**
 256      * @deprecated
 257      * Get the InetAddress of the active controller for the
 258      * active-standby case, where the standby controller has to
 259      * redirect the HTTP requests received from applications layer
 260      *
 261      * @return Address of the active controller
 262      */
 263     @Deprecated
 264     InetAddress getActiveAddress();
 265
 266     /**
 267      * Get the InetAddress of the all the controllers that make up this
 268      * Cluster
 269      *
 270      * @return List of InetAddress'es of all the controllers
 271      */
 272     List<InetAddress> getClusteredControllers();
 273
 274     /**
 275      * Get the InetAddress of this Controller as seen by the Cluster Manager
 276      *
 277      * @return InetAddress of this Controller as seen by the Cluster Manager.
 278      */
 279     InetAddress getMyAddress();
 280
 281     /**
 282      * @deprecated
 283      * Register a listener to the event of ChangeRole, raised every
 284      * time there is a change in the role of active or standby.
 285      *
 286      * @param i Interface that will be called when the Role Change happens
 287      */
 288     @Deprecated
 289     void listenRoleChange(IListenRoleChange i)
 290             throws ListenRoleChangeAddException;
 291
 292     /**
 293      * @deprecated
 294      * UN-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 unlistenRoleChange(IListenRoleChange i);
 301 }