opendaylight/clustering/services/src/main/java/org/opendaylight/controller/clustering/services/IClusterServicesCommon.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   IClusterServicesCommon.java
  12  *
  13  * @brief  : Set of services an application will expect from the
  14  * clustering services provider. This interface is going to be the
  15  * base for per-container and Global services and so the container
  16  * parameter is omitted but who uses knows about it
  17  *
  18  * Contract between the applications and the clustering service
  19  * providers. Common version
  20  */
  21
  22 package org.opendaylight.controller.clustering.services;
  23
  24 import java.net.InetAddress;
  25 import java.util.List;
  26 import java.util.Properties;
  27 import java.util.Set;
  28 import java.util.concurrent.ConcurrentMap;
  29 import java.util.concurrent.TimeUnit;
  30
  31 import javax.transaction.HeuristicMixedException;
  32 import javax.transaction.HeuristicRollbackException;
  33 import javax.transaction.NotSupportedException;
  34 import javax.transaction.RollbackException;
  35 import javax.transaction.SystemException;
  36 import javax.transaction.Transaction;
  37
  38 /**
  39  * This WILL NOT BE USED DIRECTLY, but VIA SUBCLASS
  40  *
  41  * Set of services and application will expect from the clustering services
  42  * provider. This interface is going to be the base for per-container and Global
  43  * services and so the container parameter is omitted but who uses knows about
  44  * it
  45  *
  46  */
  47 public interface IClusterServicesCommon {
  48     /**
  49      * Method that will create a new named cache. The data
  50      * structure if already present will cause an exception to be
  51      * thrown to the caller.
  52      *
  53      * @param cacheName Name of the ConcurrentHashMap to create
  54      * @param cMode Mode of the cache that need to be retrieved. This
  55      * is a set such that more than one property can be provided, of
  56      * course contrasting requirements will not be accepted and in
  57      * that case an exception is thrown
  58      *
  59      * @return ConcurrentHashMap to be used to modify the data structure
  60      */
  61     ConcurrentMap<?, ?> createCache(String cacheName,
  62             Set<IClusterServices.cacheMode> cMode) throws CacheExistException,
  63             CacheConfigException;
  64
  65     /**
  66      * Method that will retrieve and return the handle to modify a
  67      * data structire distributed via clustering services. The
  68      * datastructure shall already have been created else a null
  69      * reference will be returned.
  70      *
  71      * @param cacheName Name of the ConcurrentHashMap to retrieve
  72      *
  73      * @return ConcurrentHashMap to be used to modify the data structure
  74      */
  75     ConcurrentMap<?, ?> getCache(String cacheName);
  76
  77     /**
  78      * Destroy a cachename given cachename, if doesn't exist
  79      * the function does nothing. If the datastructure exists, the
  80      * whole cluster will destroy the instance
  81      *
  82      * @param cacheName Name of the ConcurrentHashMap to destroy
  83      */
  84     void destroyCache(String cacheName);
  85
  86     /**
  87      * Function to test the existance of a cache with a given name already
  88      *
  89      * @param cacheName Name of the ConcurrentHashMap to destroy
  90      *
  91      * @return true if exists already, false otherwise
  92      */
  93     boolean existCache(String cacheName);
  94
  95     /**
  96      * Return the list of all teh caches registered in the context of
  97      * the called
  98      *
  99      *
 100      * @return The set of names, expressed as strings
 101      */
 102     Set<String> getCacheList();
 103
 104     /**
 105      * Return a list of properties that caracterize the cache
 106      *
 107      * @param cacheName Name of the cache
 108      *
 109      * @return The list of properties related to the cache
 110      */
 111     Properties getCacheProperties(String cacheName);
 112
 113     /**
 114      * Begin a transaction covering with all the data structures/HW
 115      * updates. One transaction per-thread can be opened at the
 116      * most, that means if multiple thread are available, multiple
 117      * transactions can be outstanding.
 118      *
 119      */
 120     void tbegin() throws NotSupportedException, SystemException;
 121
 122     /**
 123      * tbegin with a timeout
 124      * @see IClusterServicesCommon#tbegin
 125      * @param timeout the transaction timeout
 126      * @param unit TimeUnit for the timeout
 127      * @throws NotSupportedException
 128      * @throws SystemException
 129      */
 130     void tbegin(long timeout, TimeUnit unit) throws NotSupportedException, SystemException;
 131
 132     /**
 133      * Commit a transaction covering all the data structures/HW updates.
 134      */
 135     void tcommit() throws RollbackException, HeuristicMixedException,
 136             HeuristicRollbackException, java.lang.SecurityException,
 137             java.lang.IllegalStateException, SystemException;
 138
 139     /**
 140      * Rollback a transaction covering all the data structures/HW updates
 141      */
 142     void trollback() throws java.lang.IllegalStateException,
 143             java.lang.SecurityException, SystemException;
 144
 145     /**
 146      * Return the javax.transaction.Transaction associated with this thread
 147      *
 148      *
 149      * @return Return the current transaction associated with this thread
 150      */
 151     Transaction tgetTransaction() throws SystemException;
 152
 153     /**
 154      *
 155      * Get the InetAddress of the coordinator controller in the cluster
 156      *
 157      * @return Address of the coordinator controller
 158      */
 159     InetAddress getCoordinatorAddress();
 160
 161     /**
 162      * Get the InetAddress of the all the controllers that make up this
 163      * Cluster
 164      *
 165      * @return List of InetAddress'es of all the controllers
 166      */
 167     List<InetAddress> getClusteredControllers();
 168
 169     /**
 170      * Get the InetAddress of this Controller as seen by the Cluster Manager
 171      *
 172      * @return InetAddress of this Controller as seen by the Cluster Manager.
 173      */
 174     InetAddress getMyAddress();
 175
 176     /**
 177      * Function that is used to know if the node on which is called is
 178      * the cluster coordinator. The API is useful in scenario where
 179      * the same logic is not worthed to be replicated on multiple
 180      * nodes in the cluster and one can cook it up for all the
 181      * others. In this scenario running the logic on the coordinator
 182      * make sense, this of course implies logics that are not heavy
 183      * and don't need to be scaled out linearly with the size of the
 184      * cluster.
 185      *
 186      * @return true if the node on which the API is called is the
 187      * coordinator for the cluster
 188      */
 189     boolean amICoordinator();
 190 }