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.core.lease;
20
21 import java.rmi.RemoteException;
22
23 /**
24 * The Lease interface defines a type of object that is returned to the
25 * lease holder and issued by the lease grantor. Particular instances of
26 * the Lease type will be created by the grantors of a lease, and returned
27 * to the holder of the lease as part of the return value from a call that
28 * allocates a leased resource. The call that requests a leased resource
29 * will typically include a requested duration for the lease. If the request
30 * is for a particular duration, the lease grantor is required to grant a
31 * lease of no more than the requested period of time. A lease may be granted
32 * for a period of time shorter than that requested.
33 *
34 * @author Sun Microsystems, Inc.
35 *
36 * @since 1.0
37 */
38 public interface Lease {
39
40 /**
41 * Used to request a lease that never expires.
42 */
43 final long FOREVER = Long.MAX_VALUE;
44
45 /**
46 * Used by the requestor to indicate that there is no particular lease
47 * time desired, and that the grantor of the lease should supply a time
48 * that is most convenient for the grantor.
49 */
50 final long ANY = -1;
51
52 /**
53 * The serialized form of the lease will convert the time of lease
54 * expiration into a duration (in milliseconds) from the time of
55 * serialization. This form is best used when transmitting a Lease
56 * object from one address space to another (via an RMI call) where
57 * it cannot be assumed that the address spaces have synchronized clocks.
58 */
59 final int DURATION = 1;
60
61 /**
62 * The serialized form of the lease will contain the time of expiration
63 * stored as an absolute time, represented in terms of milliseconds since
64 * the beginning of the epoch.
65 */
66 final int ABSOLUTE = 2;
67
68 /**
69 * Returns a <code>long</code> that indicates the time that the
70 * lease will expire. This time is represented as
71 * milliseconds from the beginning of the epoch, relative to the local
72 * clock.
73 *
74 * @return a <code>long</code> that indicates the time that the
75 * lease will expire
76 */
77 long getExpiration();
78
79 /**
80 * Used by the lease holder to indicate that it is no longer interested
81 * in the resource or information held by the lease. If the leased
82 * information or resource could cause a callback to the lease holder
83 * (or some other object on behalf of the lease holder), the lease
84 * grantor should not issue such a callback after the lease has been
85 * cancelled. The overall effect of a cancel call is the same as
86 * lease expiration, but instead of happening at the end of a pre-agreed
87 * duration it happens immediately.
88 *
89 * @throws UnknownLeaseException the lease being cancelled is unknown
90 * to the lease grantor
91 * @throws RemoteException if a connection problem occurs
92 */
93 void cancel() throws UnknownLeaseException, RemoteException;
94
95 /**
96 * Used to renew a lease for an additional period of time, specified in
97 * milliseconds. This duration is not added to the original lease, but
98 * is used to determine a new expiration time for the existing lease.
99 * If the renewal is granted this is reflected in value returned by
100 * getExpiration. If the renewal fails, the lease is left intact for
101 * the same duration that was in force prior to the call to renew.
102 *
103 * @param duration the requested duration in milliseconds
104 *
105 * @throws LeaseDeniedException the lease grantor is unable or
106 * unwilling to renew the lease
107 * @throws UnknownLeaseException the lease being renewed is unknown
108 * to the lease grantor
109 * @throws RemoteException if a connection problem occurs.
110 */
111 void renew(long duration)
112 throws LeaseDeniedException, UnknownLeaseException, RemoteException;
113
114 /**
115 * Sets the format to use when serializing the lease.
116 *
117 * @param format DURATION or ABSOLUTE
118 * @see #getSerialFormat
119 */
120 void setSerialFormat(int format);
121
122 /**
123 * Returns the format that will be used to serialize the lease.
124 *
125 * @return an <tt>int</tt> representing the serial format value
126 * @see #setSerialFormat
127 */
128 int getSerialFormat();
129
130 /**
131 * Creates a Map object that can contain leases whose renewal or
132 * cancellation can be batched, and adds the current lease to that map.
133 * The current lease is put in the map with the duration value given
134 * by the parameter.
135 *
136 * @param duration the duration to put into a Long and use as the
137 * value for the current lease in the created LeaseMap
138 *
139 * @return the created <tt>LeaseMap</tt> object
140 */
141 LeaseMap<? extends Lease, Long> createLeaseMap(long duration);
142
143 /**
144 * Returns a boolean indicating whether or not the lease given as a
145 * parameter can be batched (placed in the same LeaseMap) with the
146 * current lease. Whether or not two Lease objects can be batched
147 * is an implementation detail determined by the objects.
148 *
149 * @param lease the <tt>Lease</tt> to be evaluated
150 * @return a boolean indicating whether or not the lease given as a
151 * parameter can be batched (placed in the same LeaseMap) with
152 * the current lease
153 */
154 boolean canBatch(Lease lease);
155 }