001: /**
002: * Copyright 2003-2007 Luck Consulting Pty Ltd
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */package net.sf.ehcache.distribution;
016:
017: import net.sf.ehcache.Element;
018:
019: import java.io.Serializable;
020: import java.rmi.Remote;
021: import java.rmi.RemoteException;
022: import java.util.List;
023:
024: /**
025: * An interface for a cache peer to which updates are made remotely. The distribution mechanism
026: * is meant to be pluggable. The requirements of RMI force this interface to exten Remote and
027: * throw RemoteException.
028: * <p/>
029: * It is acknowledged that not all implementations will use Remote. Remote is just a marker interface like Serializable,
030: * so nothing specific is required.
031: * <p/>
032: * Non-RMI implementations should be able to use this interface.
033: * Implementations not using RMI should
034: *
035: * @author Greg Luck
036: * @version $Id: CachePeer.java 519 2007-07-27 07:11:45Z gregluck $
037: */
038: public interface CachePeer extends Remote {
039:
040: /**
041: * Put an element in the cache.
042: * <p/>
043: * Resets the access statistics on the element, which would be the case if it has previously been
044: * gotten from a cache, and is now being put back.
045: *
046: * @param element
047: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
048: * @throws IllegalArgumentException if the element is null
049: */
050: void put(Element element) throws IllegalArgumentException,
051: IllegalStateException, RemoteException;
052:
053: /**
054: * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
055: * stores it may be in.
056: *
057: * @param key
058: * @return true if the element was removed, false if it was not found in the cache
059: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
060: * @noinspection UnneededThrows,UnusedReturnValue
061: */
062: boolean remove(Serializable key) throws IllegalStateException,
063: RemoteException;
064:
065: /**
066: * Removes all cached items.
067: *
068: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
069: */
070: void removeAll() throws RemoteException, IllegalStateException;
071:
072: /**
073: * Send the cache peer with an ordered list of {@link EventMessage}s.
074: * <p/>
075: * This enables multiple messages to be delivered in one network invocation.
076: * @param eventMessages a list of type {@link EventMessage}
077: */
078: void send(List eventMessages) throws RemoteException;
079:
080: /**
081: * Gets the cache name.
082: * @noinspection UnneededThrows
083: */
084: String getName() throws RemoteException;
085:
086: /**
087: * Gets the globally unique id for the underlying <code>Cache</code> instance.
088: * @return a String representation of the GUID
089: * @throws RemoteException
090: * @noinspection UnneededThrows
091: */
092: String getGuid() throws RemoteException;
093:
094: /**
095: * The URL for the remote replicator to connect. The value will only have meaning
096: * for a specific implementation of replicator and remote peer.
097: * <p/>
098: * This method is not meant to be used remotely. The replicator already needs to know this. It has
099: * to throw RemoteException to comply with RMI requirements
100: * @return the URL as a string
101: * @noinspection UnneededThrows
102: */
103: String getUrl() throws RemoteException;
104:
105: /**
106: * The URL base for the remote replicator to connect. The value will have meaning
107: * only to a specific implementation of replicator and remote peer.
108: * @noinspection UnneededThrows
109: */
110: String getUrlBase() throws RemoteException;
111:
112: /**
113: * Returns a list of all elements in the cache, whether or not they are expired.
114: * <p/>
115: * The returned keys are unique and can be considered a set.
116: * <p/>
117: * The List returned is not live. It is a copy.
118: * <p/>
119: * The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required
120: * for each 1000 entries.
121: *
122: * @return a list of {@link Object} keys
123: */
124: List getKeys() throws RemoteException;
125:
126: /**
127: * Gets an element from the cache, without updating Element statistics. Cache statistics are
128: * still updated.
129: * @param key a serializable value
130: * @return the element, or null, if it does not exist.
131: */
132: Element getQuiet(Serializable key) throws RemoteException;
133:
134: /**
135: * Gets a list of elements from the cache, for a list of keys, without updating Element statistics. Time to
136: * idle lifetimes are therefore not affected.
137: * <p/>
138: * Cache statistics are still updated.
139: * @param keys a list of serializable values which represent keys
140: * @return a list of Elements. If an element was not found or null, it will not be in the list.
141: */
142: List getElements(List keys) throws RemoteException;
143:
144: }
|