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 IClusterServicesCommon.java
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
18 * Contract between the applications and the clustering service
19 * providers. Common version
22 package org.opendaylight.controller.clustering.services;
24 import java.net.InetAddress;
25 import java.util.List;
26 import java.util.Properties;
28 import java.util.concurrent.ConcurrentMap;
29 import java.util.concurrent.TimeUnit;
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;
39 * This WILL NOT BE USED DIRECTLY, but VIA SUBCLASS
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
47 public interface IClusterServicesCommon {
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.
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
59 * @return ConcurrentHashMap to be used to modify the data structure
61 ConcurrentMap<?, ?> createCache(String cacheName,
62 Set<IClusterServices.cacheMode> cMode) throws CacheExistException,
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.
71 * @param cacheName Name of the ConcurrentHashMap to retrieve
73 * @return ConcurrentHashMap to be used to modify the data structure
75 ConcurrentMap<?, ?> getCache(String cacheName);
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
82 * @param cacheName Name of the ConcurrentHashMap to destroy
84 void destroyCache(String cacheName);
87 * Function to test the existance of a cache with a given name already
89 * @param cacheName Name of the ConcurrentHashMap to destroy
91 * @return true if exists already, false otherwise
93 boolean existCache(String cacheName);
96 * Return the list of all teh caches registered in the context of
100 * @return The set of names, expressed as strings
102 Set<String> getCacheList();
105 * Return a list of properties that caracterize the cache
107 * @param cacheName Name of the cache
109 * @return The list of properties related to the cache
111 Properties getCacheProperties(String cacheName);
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.
120 void tbegin() throws NotSupportedException, SystemException;
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
130 void tbegin(long timeout, TimeUnit unit) throws NotSupportedException, SystemException;
133 * Commit a transaction covering all the data structures/HW updates.
135 void tcommit() throws RollbackException, HeuristicMixedException,
136 HeuristicRollbackException, java.lang.SecurityException,
137 java.lang.IllegalStateException, SystemException;
140 * Rollback a transaction covering all the data structures/HW updates
142 void trollback() throws java.lang.IllegalStateException,
143 java.lang.SecurityException, SystemException;
146 * Return the javax.transaction.Transaction associated with this thread
149 * @return Return the current transaction associated with this thread
151 Transaction tgetTransaction() throws SystemException;
155 * Get the InetAddress of the coordinator controller in the cluster
157 * @return Address of the coordinator controller
159 InetAddress getCoordinatorAddress();
162 * Get the InetAddress of the all the controllers that make up this
165 * @return List of InetAddress'es of all the controllers
167 List<InetAddress> getClusteredControllers();
170 * Get the InetAddress of this Controller as seen by the Cluster Manager
172 * @return InetAddress of this Controller as seen by the Cluster Manager.
174 InetAddress getMyAddress();
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
186 * @return true if the node on which the API is called is the
187 * coordinator for the cluster
189 boolean amICoordinator();