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.util.EventListener;
22 import net.jini.core.lease.Lease;
23
24 /**
25 * The interface that receivers of <code>LeaseRenewalEvent</code>
26 * instances must implement.
27 * <p>
28 * With respect to an entity that uses the
29 * <code>LeaseRenewalManager</code> to manage leases granted to the
30 * entity, this interface defines the mechanism through which an entity
31 * receives notification that the <code>LeaseRenewalManager</code> has
32 * failed to renew one of the leases the
33 * <code>LeaseRenewalManager</code> is managing for the entity. Such
34 * renewal failures typically occur because of one of the following
35 * conditions is met:
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 bad object, bad invocation, or <code>LeaseException</code>
47 * occurs during a lease renewal attempt (collectively referred
48 * to as definite exceptions).
49 * </ul>
50 * It is the responsibility of the entity to register with the
51 * <code>LeaseRenewalManager</code>. The object that implements this
52 * interface should define the actions to take upon receipt of such
53 * notifications. Then, when one of the above conditions occurs, the
54 * <code>LeaseRenewalManager</code> will send an instance of the
55 * <code>LeaseRenewalEvent</code> class to that listener object. Note
56 * that, prior to sending the event, the
57 * <code>LeaseRenewalManager</code> will remove the affected lease from
58 * its managed set of leases.
59 *
60 * @author Sun Microsystems, Inc.
61 * @see Lease
62 * @see LeaseRenewalManager
63 * @see LeaseRenewalEvent
64 */
65 public interface LeaseListener extends EventListener {
66 /**
67 * Called by the <code>LeaseRenewalManager</code> when it cannot
68 * renew a lease that it is managing, and the lease's desired
69 * expiration time has not yet been reached.
70 * <p>
71 * Note that, prior to invoking this method, the
72 * <code>LeaseRenewalManager</code> removes the affected lease from
73 * the managed set of leases. Note also that, because of the
74 * reentrancy guarantee made by the
75 * <code>LeaseRenewalManager</code>, new leases can be safely added
76 * by this method.
77 *
78 * @param e instance of <code>LeaseRenewalEvent</code> containing
79 * information about the lease that the
80 * <code>LeaseRenewalManager</code> was unable to renew, as
81 * well as information about the condition that made the
82 * <code>LeaseRenewalManager</code> fail to renew the lease
83 */
84 void notify(LeaseRenewalEvent e);
85 }