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 }