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.event;
20
21 import java.io.IOException;
22 import java.io.InvalidObjectException;
23 import java.io.ObjectInputStream;
24 import java.io.ObjectOutputStream;
25 import net.jini.core.lease.Lease;
26 import org.apache.river.api.io.AtomicSerial;
27 import org.apache.river.api.io.AtomicSerial.GetArg;
28
29 /**
30 * A utility class for use as a return value for event-interest registration
31 * methods. Objects of this class are meant to encapsulate the information
32 * needed by a client to identify a notification as a response to a
33 * registration request and to maintain that registration request. It is
34 * not mandatory for an event-interest registration method to use this class.
35 * <p>
36 * A registration of interest in some kind of event that occurs within the
37 * scope of a transaction is leased in the same way as other event interest
38 * registrations. However, the duration of the registration is the minimum
39 * of the length of the lease and the duration of the transaction. Simply
40 * put, when the transaction ends (either because of a commit or an abort)
41 * the interest registration also ends. This is true even if the lease for
42 * the event registration has not expired and no call has been made to
43 * cancel the lease.
44 *
45 * @author Sun Microsystems, Inc.
46 *
47 * @since 1.0
48 */
49 @AtomicSerial
50 public final class EventRegistration implements java.io.Serializable {
51
52 private static final long serialVersionUID = 4055207527458053347L;
53
54 /**
55 * The event identifier.
56 *
57 * @serial
58 */
59 private final long eventID;
60
61 /**
62 * The event source.
63 *
64 * @serial
65 */
66 private final Object source;
67
68 /**
69 * The registration lease.
70 *
71 * @serial
72 */
73 private final Lease lease;
74
75 /**
76 * The current sequence number.
77 *
78 * @serial
79 */
80 private final long seqNum;
81
82 private static boolean check(GetArg arg) throws IOException{
83 arg.get("eventID", 0L);
84 Object source = arg.get("source", null);
85 if (source == null) throw new InvalidObjectException("source cannot be null");
86 Object lease = arg.get("lease", null);
87 if (!(lease instanceof Lease)) throw new InvalidObjectException(
88 "lease cannot be null and must be an instance of Lease");
89 long seqNum = arg.get("seqNum", 0L);
90 if (seqNum < 0) throw new InvalidObjectException("seqNum must be greater than zero, possible overflow");
91 return true;
92 }
93
94 private EventRegistration(boolean check, GetArg arg) throws IOException{
95 eventID = arg.get("eventID", 0L);
96 source = arg.get("source", null);
97 lease = (Lease) arg.get("lease", null);
98 seqNum = arg.get("seqNum", 0L);
99 }
100
101 public EventRegistration(GetArg arg) throws IOException{
102 this(check(arg), arg);
103 }
104
105 /**
106 * Constructs an <tt>EventRegistration</tt> object.
107 *
108 * Immutable since 3.0.0
109 *
110 * @param eventID a <tt>long</tt> representing the event identifier
111 * @param source an <tt>Object</tt> representing the event source
112 * @param lease the registration <tt>Lease</tt> object
113 * @param seqNum a <tt>long</tt> representing the current
114 * sequence number
115 */
116 public EventRegistration(long eventID, Object source,
117 Lease lease, long seqNum) {
118 this.eventID = eventID;
119 this.source = source;
120 this.lease = lease;
121 this.seqNum = seqNum;
122 }
123
124 /**
125 * Returns the identifier that will be used in all RemoteEvents generated
126 * for this interest registration.
127 *
128 * @return a long used to identify all RemoteEvents that are generated
129 * for this interest registration.
130 * @see RemoteEvent#getID
131 */
132 public long getID() {
133 return eventID;
134 }
135
136 /**
137 * Returns the source that will be used in all RemoteEvents generated
138 * for this interest registration.
139 *
140 * @return an Object that represents the source of all RemoteEvents
141 * for this interest registration
142 * @see java.util.EventObject#getSource
143 */
144 public Object getSource() {
145 return source;
146 }
147
148 /**
149 * Returns the Lease object for this registration.
150 *
151 * @return the Lease object for this registration.
152 */
153 public Lease getLease() {
154 return lease;
155 }
156
157 /**
158 * Returns the value of the sequence number on the event kind that was
159 * current when the registration was granted, allowing comparison with
160 * the sequence number in any subsequent notifications.
161 *
162 * @return a long representing the value of the sequence number on the
163 * event type that was current when the registration was
164 * granted, allowing comparison with the sequence number in any
165 * subsequent notifications.
166 */
167 public long getSequenceNumber() {
168 return seqNum;
169 }
170
171 private void writeObject(ObjectOutputStream out) throws IOException {
172 out.defaultWriteObject();
173 }
174
175 /**
176 * Default read object, in case of future evolution.
177 * @serial
178 * @param in ObjectInputStream
179 * @throws ClassNotFoundException if class not found.
180 * @throws IOException if a problem occurs during de-serialization.
181 */
182 private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException{
183 in.defaultReadObject();
184 }
185 }