1 /***
2 * Copyright 2003-2010 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package net.sf.ehcache.distribution;
18
19 import net.sf.ehcache.Element;
20
21 import java.io.Serializable;
22 import java.rmi.Remote;
23 import java.rmi.RemoteException;
24 import java.util.List;
25
26 /***
27 * An interface for a cache peer to which updates are made remotely. The distribution mechanism
28 * is meant to be pluggable. The requirements of RMI force this interface to exten Remote and
29 * throw RemoteException.
30 * <p/>
31 * It is acknowledged that not all implementations will use Remote. Remote is just a marker interface like Serializable,
32 * so nothing specific is required.
33 * <p/>
34 * Non-RMI implementations should be able to use this interface.
35 * Implementations not using RMI should
36 *
37 * @author Greg Luck
38 * @version $Id: CachePeer.html 13146 2011-08-01 17:12:39Z oletizi $
39 */
40 public interface CachePeer extends Remote {
41
42
43 /***
44 * Put an element in the cache.
45 * <p/>
46 * Resets the access statistics on the element, which would be the case if it has previously been
47 * gotten from a cache, and is now being put back.
48 *
49 * @param element
50 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
51 * @throws IllegalArgumentException if the element is null
52 */
53 void put(Element element) throws IllegalArgumentException, IllegalStateException, RemoteException;
54
55 /***
56 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
57 * stores it may be in.
58 *
59 * @param key
60 * @return true if the element was removed, false if it was not found in the cache
61 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
62 */
63 boolean remove(Serializable key) throws IllegalStateException, RemoteException;
64
65 /***
66 * Removes all cached items.
67 *
68 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
69 */
70 void removeAll() throws RemoteException, IllegalStateException;
71
72
73 /***
74 * Send the cache peer with an ordered list of {@link EventMessage}s.
75 * <p/>
76 * This enables multiple messages to be delivered in one network invocation.
77 * @param eventMessages a list of type {@link EventMessage}
78 */
79 void send(List eventMessages) throws RemoteException;
80
81 /***
82 * Gets the cache name.
83 */
84 String getName() throws RemoteException;
85
86 /***
87 * Gets the globally unique id for the underlying <code>Cache</code> instance.
88 * @return a String representation of the GUID
89 * @throws RemoteException
90 */
91 String getGuid() throws RemoteException;
92
93 /***
94 * The URL for the remote replicator to connect. The value will only have meaning
95 * for a specific implementation of replicator and remote peer.
96 * <p/>
97 * This method is not meant to be used remotely. The replicator already needs to know this. It has
98 * to throw RemoteException to comply with RMI requirements
99 * @return the URL as a string
100 */
101 String getUrl() throws RemoteException;
102
103
104 /***
105 * The URL base for the remote replicator to connect. The value will have meaning
106 * only to a specific implementation of replicator and remote peer.
107 */
108 String getUrlBase() throws RemoteException;
109
110
111 /***
112 * Returns a list of all elements in the cache, whether or not they are expired.
113 * <p/>
114 * The returned keys are unique and can be considered a set.
115 * <p/>
116 * The List returned is not live. It is a copy.
117 * <p/>
118 * The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required
119 * for each 1000 entries.
120 *
121 * @return a list of {@link Object} keys
122 */
123 List getKeys() throws RemoteException;
124
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
145 }