001: /**
002: * $Revision$
003: * $Date$
004: *
005: * Copyright (C) 1999-2005 Jive Software. All rights reserved.
006: * This software is the proprietary information of Jive Software. Use is subject to license terms.
007: */package org.jivesoftware.util.cache;
008:
009: import org.jivesoftware.openfire.cluster.ClusterNodeInfo;
010:
011: import java.util.Collection;
012: import java.util.Map;
013:
014: /**
015: * Implementation of CacheFactory that relies on the specific clustering solution.
016: *
017: * @author Gaston Dombiak
018: */
019: public interface CacheFactoryStrategy {
020:
021: /**
022: * Returns true if the cluster has been started. When running in local
023: * mode a true value should be returned.<p>
024: *
025: * An error should be logged when the cluster fails to be started.
026: *
027: * @return true if the cluster has been started.
028: */
029: boolean startCluster();
030:
031: /**
032: * Stops the cluster. When not running in a cluster this request will be ignored.
033: */
034: void stopCluster();
035:
036: /**
037: * Creates a new cache for the cache name specified. The created cache is
038: * already configured. Different implementations could store the cache
039: * configuration in different ways. It is recommended to store the cache
040: * configuration in an external file so it is easier for customers to change
041: * the default configuration.
042: *
043: * @param name name of the cache to create.
044: * @return newly created and configured cache.
045: */
046: Cache createCache(String name);
047:
048: /**
049: * Destroys the supplied cache.
050: *
051: * @param cache the cache to destroy.
052: */
053: void destroyCache(Cache cache);
054:
055: /**
056: * Returns true if this node is the maste node of the cluster. When not running
057: * in cluster mode a value of true should be returned.
058: *
059: * @return true if this node is the maste node of the cluster.
060: */
061: boolean isSeniorClusterMember();
062:
063: /**
064: * Returns basic information about the current members of the cluster or an empty
065: * collection if not running in a cluster.
066: *
067: * @return information about the current members of the cluster or an empty
068: * collection if not running in a cluster.
069: */
070: Collection<ClusterNodeInfo> getClusterNodesInfo();
071:
072: /**
073: * Returns the maximum number of cluster members allowed. A value of 0 will
074: * be returned when clustering is not allowed.
075: *
076: * @return the maximum number of cluster members allowed or 0 if clustering is not allowed.
077: */
078: int getMaxClusterNodes();
079:
080: /**
081: * Returns a byte[] that uniquely identifies this senior cluster member or <tt>null</tt>
082: * when not in a cluster.
083: *
084: * @return a byte[] that uniquely identifies this senior cluster member or null when not in a cluster.
085: */
086: byte[] getSeniorClusterMemberID();
087:
088: /**
089: * Returns a byte[] that uniquely identifies this member within the cluster or <tt>null</tt>
090: * when not in a cluster.
091: *
092: * @return a byte[] that uniquely identifies this member within the cluster or null when not in a cluster.
093: */
094: byte[] getClusterMemberID();
095:
096: /**
097: * Invokes a task on other cluster members in an asynchronous fashion. The task will not be
098: * executed on the local cluster member. If clustering is not enabled, this method
099: * will do nothing.
100: *
101: * @param task the task to be invoked on all other cluster members.
102: */
103: void doClusterTask(final ClusterTask task);
104:
105: /**
106: * Invokes a task on other the specified cluster member in an asynchronous fashion. If clustering is not
107: * enabled, this method will do nothing.
108: *
109: * @param task the task to be invoked on the specified cluster member.
110: * @param nodeID the byte array that identifies the target cluster member.
111: * @return false if not in a cluster or specified cluster node was not found.
112: */
113: boolean doClusterTask(ClusterTask task, byte[] nodeID);
114:
115: /**
116: * Invokes a task on other cluster members synchronously and returns the result as a Collection
117: * (method will not return until the task has been executed on each cluster member).
118: * The task will not be executed on the local cluster member. If clustering is not enabled,
119: * this method will return an empty collection.
120: *
121: * @param task the ClusterTask object to be invoked on all other cluster members.
122: * @param includeLocalMember true to run the task on the local member, false otherwise
123: * @return collection with the result of the execution.
124: */
125: Collection<Object> doSynchronousClusterTask(ClusterTask task,
126: boolean includeLocalMember);
127:
128: /**
129: * Invokes a task on a given cluster member synchronously and returns the result of
130: * the remote operation. If clustering is not enabled, this method will return null.
131: *
132: * @param task the ClusterTask object to be invoked on a given cluster member.
133: * @param nodeID the byte array that identifies the target cluster member.
134: * @return result of remote operation or null if operation failed or operation returned null.
135: * @throws IllegalStateException if requested node was not found.
136: */
137: Object doSynchronousClusterTask(ClusterTask task, byte[] nodeID);
138:
139: /**
140: * Updates the statistics of the specified caches and publishes them into
141: * a cache for statistics. The statistics cache is already known to the application
142: * but this could change in the future (?). When not in cluster mode then
143: * do nothing.<p>
144: *
145: * The statistics cache must contain a long array of 5 positions for each cache
146: * with the following content:
147: * <ol>
148: * <li>cache.getCacheSize()</li>
149: * <li>cache.getMaxCacheSize()</li>
150: * <li>cache.size()</li>
151: * <li>cache.getCacheHits()</li>
152: * <li>cache.getCacheMisses()</li>
153: * </ol>
154: *
155: * @param caches caches to get their stats and publish them in a statistics cache.
156: */
157: void updateCacheStats(Map<String, Cache> caches);
158:
159: /**
160: * Locks the specified key in the locking map. The map should be clusterable
161: * thus locking a key is visible to the cluster. When not in cluster mode
162: * the lock is only visible to this JVM.
163: *
164: * @param key the key to lock.
165: * @param timeout number of milliseconds to wait to obtain the lock. -1 means wait forever.
166: */
167: void lockKey(Object key, long timeout);
168:
169: /**
170: * Unlocks the specified key in the locking map. The map should be clusterable
171: * thus locking a key is visible to the cluster. When not in cluster mode
172: * the lock is only visible to this JVM.
173: *
174: * @param key the key to unlock.
175: */
176: void unlockKey(Object key);
177: }
|