+++ /dev/null
-
-/*
- * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
- *
- * This program and the accompanying materials are made available under the
- * terms of the Eclipse Public License v1.0 which accompanies this distribution,
- * and is available at http://www.eclipse.org/legal/epl-v10.html
- */
-
-/**
- * @file IClusterServices.java
- *
- * @brief : Set of services an application will expect from the
- * clustering services provider
- *
- * Contract between the applications and the clustering service
- * providers.
- */
-
-package org.opendaylight.controller.clustering.services;
-
-import java.net.InetAddress;
-import java.util.List;
-import java.util.Properties;
-import java.util.Set;
-import java.util.concurrent.ConcurrentMap;
-import java.util.concurrent.TimeUnit;
-
-import javax.transaction.HeuristicMixedException;
-import javax.transaction.HeuristicRollbackException;
-import javax.transaction.NotSupportedException;
-import javax.transaction.RollbackException;
-import javax.transaction.SystemException;
-import javax.transaction.Transaction;
-
-/**
- * Set of services an application will expect from the
- * clustering services provider
- *
- */
-public interface IClusterServices {
-
- /**
- * Enumeration of the several modality with which a
- * ConcurrentHashMap cache can be requested to the clustering
- * services. The property that can be requested can be multiple.
- *
- */
- public enum cacheMode {
- /**
- * Set for a cache that supports transaction that implies that
- * is a transaction is open on the current thread the data
- * will not immediately be reflected in the cache but will be
- * staged till commit or rollback. If the transaction if NOT
- * open the data will immediately go in the cache without
- * staging.
- */
- TRANSACTIONAL,
- /**
- * Set on a cache that doesn't want to support
- * transaction, so irrespective of the fact that we are in
- * the middle of a transaction or no data will be
- * immediately committed in the cache.
- *
- */
- NON_TRANSACTIONAL,
- /**
- * Set on a cache that can transfer the updates asynchronously from the
- * calling thread. The caller when doing put/clear/remove cannot expect
- * that the operation has happened clusterwide
- */
- ASYNC,
- /**
- * Set on a cache that transfer the updates synchronously to the calling
- * thread so when getting back the operation is supposed to have
- * completed on all the cluster nodes. Slow but safe.
- */
- SYNC;
- }
-
- /**
- * Enumeration of the several properties that a cache can carry
- *
- */
- public enum cacheProps {
- /**
- * The property returned describe the characteristics of the
- * transaction setup for the cache it was retrieved.
- */
- TRANSACTION_PROP,
- /**
- * The property returned report the clustering
- * characteristics of the cache for which property was
- * queried.
- */
- CLUSTERING_PROP,
- /**
- * The property returned reports the locking
- * characteristics of the cache for which the property was
- * queried
- */
- LOCKING_PROP;
- }
-
- /**
- * Method that will create a new named cache per-container. The data
- * structure if already present will cause an exception to be
- * thrown to the caller.
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap to create
- * @param cMode Mode of the cache that need to be retrieved. This
- * is a set such that more than one property can be provided, of
- * course contrasting requirements will not be accepted and in
- * that case an exception is thrown
- *
- * @return ConcurrentHashMap to be used to modify the data structure
- */
- ConcurrentMap<?, ?> createCache(String containerName, String cacheName,
- Set<cacheMode> cMode) throws CacheExistException,
- CacheConfigException;
-
- /**
- * Method that will retrieve and return the handle to modify a
- * data structire distributed via clustering services. The
- * datastructure shall already have been created else a null
- * reference will be returned.
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap to retrieve
- *
- * @return ConcurrentHashMap to be used to modify the data structure
- */
- ConcurrentMap<? extends Object, ? extends Object> getCache(String containerName, String cacheName);
-
- /**
- * Destroy a cachename given containerName/cachename, if doesn't exist
- * the function does nothing. If the datastructure exists, the
- * whole cluster will destroy the instance
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap to destroy
- */
- void destroyCache(String containerName, String cacheName);
-
- /**
- * Function to test the existance of a cache with a given name already
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap to destroy
- *
- * @return true if exists already, false otherwise
- */
- boolean existCache(String containerName, String cacheName);
-
- /**
- * Return the list of all teh caches registered with a container
- *
- * @param containerName Container for which we want to list all the caches registered
- *
- * @return The set of names, expressed as strings
- */
- Set<String> getCacheList(String containerName);
-
- /**
- * Return a list of properties that caracterize the cache
- *
- * @param containerName Name of the container where data structure resides
- * @param cacheName Name of the cache
- *
- * @return The list of properties related to the cache
- */
- Properties getCacheProperties(String containerName, String cacheName);
-
- /**
- * Register an update handler for a given containerName/cacheName
- * shared data structure. Multiple listeners are possible.
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap for which we
- * want to register the listener
- * @param u Interface to invoke when the updates are received
- */
- void addListener(String containerName, String cacheName, IGetUpdates<?, ?> u)
- throws CacheListenerAddException;
-
- /**
- * Return a set of interfaces that are interesteed to listen to
- * updates coming for a given datastructure shared via clustering
- * services.
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap for which we
- * want to retrieve the listener
- */
- Set<IGetUpdates<?, ?>> getListeners(String containerName, String cacheName);
-
- /**
- * UN-Register an update handler for a given containerName/cacheName
- * shared data structure. Multiple listeners are possible.
- *
- * @param containerName Container to which the datastructure is associated
- * @param cacheName Name of the ConcurrentHashMap for which we
- * want to un-register the listener
- * @param u Interface to un-register
- */
- void removeListener(String containerName, String cacheName,
- IGetUpdates<?, ?> u);
-
- /**
- * Begin a transaction covering with all the data structures/HW
- * updates. One transaction per-thread can be opened at the
- * most, that means if multiple thread are available, multiple
- * transactions can be outstanding.
- *
- */
- void tbegin() throws NotSupportedException, SystemException;
-
- /**
- * tbegin with a timeout
- * @see IClusterServices#tbegin
- * @param timeout the transaction timeout
- * @param unit TimeUnit for the timeout
- * @throws NotSupportedException
- * @throws SystemException
- */
- void tbegin(long timeout, TimeUnit unit) throws NotSupportedException, SystemException;
-
- /**
- * Commit a transaction covering all the data structures/HW updates.
- */
- void tcommit() throws RollbackException, HeuristicMixedException,
- HeuristicRollbackException, java.lang.SecurityException,
- java.lang.IllegalStateException, SystemException;
-
- /**
- * Rollback a transaction covering all the data structures/HW updates
- */
- void trollback() throws java.lang.IllegalStateException,
- java.lang.SecurityException, SystemException;
-
- /**
- * Return the javax.transaction.Transaction associated with this thread
- *
- *
- * @return Return the current transaction associated with this thread
- */
- Transaction tgetTransaction() throws SystemException;
-
- /**
- * @deprecated
- * Function that says if we are standby in the 1-1 redundancy with
- * active/standby model. The API is not encouraged hence is
- * deprecated. It is supposed to be used as a stop-gap till the
- * active-standby goal is achieved. The only guys that are
- * supposed to use are:
- * - southbound layer, should not listen on the OF port if standby
- * - jetty configuration, on standby jetty should redirect calls
- * to the active.
- *
- * @return true if the role is the one of standby, else false
- */
- @Deprecated
- boolean amIStandby();
-
- /**
- * @deprecated
- * Get the InetAddress of the active controller for the
- * active-standby case, where the standby controller has to
- * redirect the HTTP requests received from applications layer
- *
- * @return Address of the active controller
- */
- @Deprecated
- InetAddress getActiveAddress();
-
- /**
- * Get the InetAddress of the all the controllers that make up this
- * Cluster
- *
- * @return List of InetAddress'es of all the controllers
- */
- List<InetAddress> getClusteredControllers();
-
- /**
- * Get the InetAddress of this Controller as seen by the Cluster Manager
- *
- * @return InetAddress of this Controller as seen by the Cluster Manager.
- */
- InetAddress getMyAddress();
-
- /**
- * @deprecated
- * Register a listener to the event of ChangeRole, raised every
- * time there is a change in the role of active or standby.
- *
- * @param i Interface that will be called when the Role Change happens
- */
- @Deprecated
- void listenRoleChange(IListenRoleChange i)
- throws ListenRoleChangeAddException;
-
- /**
- * @deprecated
- * UN-Register a listener to the event of ChangeRole, raised every
- * time there is a change in the role of active or standby.
- *
- * @param i Interface that will be called when the Role Change happens
- */
- @Deprecated
- void unlistenRoleChange(IListenRoleChange i);
-}