1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of CosyBeans.
5 *
6 * CosyBeans is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * CosyBeans is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with CosyBeans. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.gui.displayers;
21
22 import java.util.EventObject;
23
24
25 /**
26 * <p>
27 * This update request is sent to <code>NumericAsynchonousConsumer</code> to
28 * inform it that the source value has changed. The consumer take appropriate
29 * action, which in the case of Abeans adapter includes notifying the
30 * modeling layer about the change in target value.
31 * </p>
32 */
33 public class UpdateRequest extends EventObject
34 {
35 private static final long serialVersionUID = 1L;
36 protected Object targetValue = null;
37 protected Object newTargetValue = null;
38 protected long timestamp = 0;
39 protected long requestID = 0;
40 protected static long requestCount = 0;
41
42 /**
43 * Constructs a new instance of this event.
44 *
45 * @param source the listener which will receive replay for update request
46 */
47 public UpdateRequest(UpdateRequestListener source)
48 {
49 super(source);
50 }
51
52 /**
53 * Constructs a new instance of this event. The event will contain unique
54 * serial number and other data that allow the event source and target to
55 * track the request. This imposes additional performance overhead.
56 *
57 * @param source setter dispatching the event
58 * @param targetValue Object rendering of the target value
59 *
60 * @throws NullPointerException if target value is <code>null</code>
61 */
62 public UpdateRequest(UpdateRequestListener source, Object targetValue)
63 {
64 super(source);
65
66 if (targetValue == null) {
67 throw new NullPointerException("targetValue");
68 }
69
70 this.targetValue = targetValue;
71 requestID = requestCount;
72 requestCount++;
73 timestamp = System.currentTimeMillis();
74 }
75
76 /**
77 * Returns the timestamp (as in <code>System.currentTimeMillis</code> when
78 * the event was created. Will return 0 if the event was created with
79 * single-paramter constructor.
80 *
81 * @return long timestamp
82 */
83 public long getTimestamp()
84 {
85 return timestamp;
86 }
87
88 /**
89 * Returns the request ID associated with this request. IDs are unique
90 * within the JVM session. Will return 0 if the event was created with
91 * single-parameter constructor.
92 *
93 * @return long UID
94 */
95 public long getRequestID()
96 {
97 return requestID;
98 }
99
100 /**
101 * Signals the source <code>UpdateRequestListener</code> that the request
102 * has been processed. <b>This method may be invoked only by the
103 * asynchronous data consumer.</b> This is a callback and needs to be
104 * called for each asynchronous update request. The event will delegate
105 * the call to the source <code>UpdateRequestListener</code>.
106 *
107 * @param newTargetValue the new value of the dynamic value after the set
108 * operation. If success indicates <code>true</code>, this value
109 * should be the same as the requested value for setting.
110 * Otherwise, this value may be something else (for instance, if
111 * setter wants to set above maximum, the actual value set may be
112 * maximum allowed limit).
113 * @param success <code>true</code> if update process proceeded without
114 * problems, as defined by the asynchonous data consumer
115 * @param exception the exception thrown during unsuccesful update
116 */
117 public void reply(Object newTargetValue, boolean success,
118 Exception exception)
119 {
120 // allow null values for newTargetValue if the remote call fails
121 UpdateRequestListener source = (UpdateRequestListener)getSource();
122 this.newTargetValue = newTargetValue;
123 source.replay(this, success, exception);
124 }
125
126 /**
127 * Returns the value that was actually set as confirmed by the data
128 * consumer. This value may differ from the <code>targetValue</code>
129 * requested by the update requestor because of the possible exceptional
130 * conditions in the modeling layer. This method will return
131 * <code>null</code> if the event was created with the single-parameter
132 * constructor. Note: it is the responsibility of the adapter to
133 * synchronize the target value of the setter with the confirmed value
134 * after the set by calling <code>setTargetValue</code> on the setter.
135 *
136 * @return Object an object rendering of the confirmed target value or
137 * <code>null</code> if single parameter constructor was used.
138 */
139 public Object getNewTargetValue()
140 {
141 return newTargetValue;
142 }
143
144 /**
145 * Returns the target value. Target value is the value requested by update
146 * requestor to be set in the modeling layer by the asynchronous data
147 * consumer. This method will return <code>null</code> if the event was
148 * instantiated with the single parameter constructor.
149 *
150 * @return Object an object rendering of the target value or
151 * <code>null</code> if single parameter constructor was used.
152 */
153 public Object getTargetValue()
154 {
155 return targetValue;
156 }
157 }
158
159 /* __oOo__ */