1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package net.jini.lease;
20
21 import java.io.IOException;
22 import java.util.EventObject;
23 import net.jini.core.lease.Lease;
24 import net.jini.core.lease.LeaseException;
25 import org.apache.river.api.io.AtomicSerial;
26 import org.apache.river.api.io.AtomicSerial.GetArg;
27
28 /**
29 * Event generated when a <code>LeaseRenewalManager</code> cannot renew
30 * a lease.
31 * <p>
32 * The <code>LeaseRenewalEvent</code> instances are sent to the
33 * <code>LeaseListener</code> (if any) associated with a given lease
34 * when the lease was added to the managed set. These events are
35 * typically generated because one of the following conditions occur:
36 * <ul>
37 * <li> After successfully renewing a lease any number of times and
38 * experiencing no failures, the <code>LeaseRenewalManager</code>
39 * determines, prior to the next renewal attempt, that the actual
40 * expiration time of the lease has passed, implying that any
41 * further attempt to renew the lease would be fruitless.
42 * <li> An indefinite exception occurs during each attempt to renew a
43 * lease, from the point that the first such exception occurs
44 * until the point when the <code>LeaseRenewalManager</code>
45 * determines that lease's actual expiration time has passed.
46 * <li> A definite exception occurs during a lease renewal attempt.
47 * </ul>
48 * <p>
49 * Note that bad object exceptions, bad invocation exceptions, and
50 * <code>LeaseException</code>s are all considered definite
51 * exceptions.
52 * <p>
53 * This class encapsulates information about both the lease for which the
54 * failure occurred, as well as information about the condition that
55 * caused the renewal attempt to fail.
56 * <p>
57 * This class is a subclass of the class <code>EventObject</code>,
58 * adding the following additional items of abstract state:
59 * <ul>
60 * <li> The lease on which the renewal attempt failed, and to which
61 * the event pertains
62 * <li> The desired expiration time of the affected lease
63 * <li> The <code>Throwable</code> associated with the last renewal
64 * attempt (if any)
65 * </ul>
66 * <p>
67 * In addition to the methods of the <code>EventObject</code> class,
68 * this class defines methods through which this additional state may be
69 * retrieved.
70 * <p>
71 * The source associated with a <code>LeaseRenewalEvent</code> will be
72 * the <code>LeaseRenewalManager</code> that generated the event.
73 *
74 * @author Sun Microsystems, Inc.
75 * @see Lease
76 * @see LeaseException
77 * @see LeaseRenewalManager
78 * @see LeaseListener
79 * @see EventObject
80 */
81 @AtomicSerial
82 public class LeaseRenewalEvent extends EventObject {
83 private static final long serialVersionUID = -626399341646348302L;
84
85 /**
86 * The failed lease.
87 *
88 * @serial
89 */
90 private final Lease lease;
91
92 /**
93 * The desired expiration of the failed lease.
94 *
95 * @serial
96 */
97 private final long expiration;
98
99 /**
100 * The exception that caused the failure, if any.
101 *
102 * @serial
103 */
104 private final Throwable ex;
105
106 /**
107 * Constructs an instance of this class with the specified state.
108 *
109 * @param source reference to the instance of the
110 * <code>LeaseRenewalManager</code> that generated the event
111 * @param lease the lease to which the event pertains
112 * @param expiration the desired expiration time for the affected
113 * lease
114 * @param ex the <code>Throwable</code> associated with the last
115 * renewal attempt (if any)
116 * @see Lease
117 * @see LeaseRenewalManager
118 */
119 public LeaseRenewalEvent(LeaseRenewalManager source,
120 Lease lease,
121 long expiration,
122 Throwable ex)
123 {
124 super(source);
125 this.lease = lease;
126 this.expiration = expiration;
127 this.ex = ex;
128 }
129
130 public LeaseRenewalEvent(GetArg arg) throws IOException{
131 this(null,
132 arg.get("lease", null, Lease.class),
133 arg.get("expiration", 0L),
134 arg.get("ex", null, Throwable.class)
135 );
136 }
137
138 /**
139 * Returns a reference to the lease to which the event pertains.
140 *
141 * @return the <code>Lease</code> object corresponding to the lease
142 * on which the renewal attempt failed
143 * @see Lease
144 */
145 public Lease getLease() {
146 return lease;
147 }
148
149 /**
150 * Returns the desired expiration time of the lease to which event
151 * pertains.
152 *
153 * @return a <code>long</code> value that represents the desired
154 * expiration time of the lease on which the renewal attempt
155 * failed
156 */
157 public long getExpiration() {
158 return expiration;
159 }
160
161 /**
162 * Returns the exception (if any) that caused the event to be sent.
163 * The conditions under which the event may be sent, and the related
164 * values returned by this method, are as follows:
165 * <ul>
166 *
167 * <li> When any lease in the managed set has passed its actual
168 * expiration time, and either the most recent renewal attempt
169 * was successful or there have been no renewal attempts, the
170 * <code>LeaseRenewalManager</code> will cease any further
171 * attempts to renew the lease, and will send a
172 * <code>LeaseRenewalEvent</code> with no associated exception.
173 * In this case, invoking this method will return
174 * <code>null</code>.
175 * <li> For any lease from the managed set for which the most recent
176 * renewal attempt was unsuccessful because of the occurrence
177 * of a indefinite exception, the
178 * <code>LeaseRenewalManager</code> will continue to attempt to
179 * renew the affected lease at the appropriate times until: the
180 * renewal succeeds, the lease's expiration time has passed, or
181 * a renewal attempt throws a definite exception. If a definite
182 * exception is thrown or the lease expires, the
183 * <code>LeaseRenewalManager</code> will cease any further
184 * attempts to renew the lease, and will send a
185 * <code>LeaseRenewalEvent</code> containing the exception
186 * associated with the last renewal attempt.
187 * <li> If, while attempting to renew a lease from the managed set,
188 * a definite exception is encountered, the
189 * <code>LeaseRenewalManager</code> will cease any further
190 * attempts to renew the lease, and will send a
191 * <code>LeaseRenewalEvent</code> containing the particular
192 * exception that occurred.
193 * </ul>
194 *
195 * @return an instance of <code>Throwable</code> or
196 * <code>null</code>, indicating the condition that caused
197 * the <code>LeaseRenewalManager</code> to fail to renew the
198 * affected lease
199 */
200 public Throwable getException() {
201 return ex;
202 }
203 }