%line | %branch | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
org.apache.commons.net.ntp.TimeInfo |
|
|
1 | package org.apache.commons.net.ntp; |
|
2 | /* |
|
3 | * Copyright 2001-2005 The Apache Software Foundation |
|
4 | * |
|
5 | * Licensed under the Apache License, Version 2.0 (the "License"); |
|
6 | * you may not use this file except in compliance with the License. |
|
7 | * You may obtain a copy of the License at |
|
8 | * |
|
9 | * http://www.apache.org/licenses/LICENSE-2.0 |
|
10 | * |
|
11 | * Unless required by applicable law or agreed to in writing, software |
|
12 | * distributed under the License is distributed on an "AS IS" BASIS, |
|
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
14 | * See the License for the specific language governing permissions and |
|
15 | * limitations under the License. |
|
16 | */ |
|
17 | ||
18 | import java.util.List; |
|
19 | import java.util.ArrayList; |
|
20 | ||
21 | /** |
|
22 | * Wrapper class to network time packet messages (NTP, etc) that computes |
|
23 | * related timing info and stats. |
|
24 | * |
|
25 | * @author Jason Mathews, MITRE Corp |
|
26 | * |
|
27 | * @version $Revision: 165675 $ $Date: 2005-05-02 15:09:55 -0500 (Mon, 02 May 2005) $ |
|
28 | */ |
|
29 | public class TimeInfo { |
|
30 | ||
31 | private NtpV3Packet _message; |
|
32 | private List _comments; |
|
33 | private Long _delay; |
|
34 | private Long _offset; |
|
35 | ||
36 | /** |
|
37 | * time at which time message packet was received by local machine |
|
38 | */ |
|
39 | private long _returnTime; |
|
40 | ||
41 | /** |
|
42 | * flag indicating that the TimeInfo details was processed and delay/offset were computed |
|
43 | */ |
|
44 | private boolean _detailsComputed; |
|
45 | ||
46 | /** |
|
47 | * Create TimeInfo object with raw packet message and destination time received. |
|
48 | * |
|
49 | * @param message NTP message packet |
|
50 | * @param returnTime destination receive time |
|
51 | * @throws IllegalArgumentException if message is null |
|
52 | */ |
|
53 | public TimeInfo(NtpV3Packet message, long returnTime) { |
|
54 | 0 | this(message, returnTime, null, true); |
55 | 0 | } |
56 | ||
57 | /** |
|
58 | * Create TimeInfo object with raw packet message and destination time received. |
|
59 | * |
|
60 | * @param message NTP message packet |
|
61 | * @param returnTime destination receive time |
|
62 | * @param comments List of errors/warnings identified during processing |
|
63 | * @throws IllegalArgumentException if message is null |
|
64 | */ |
|
65 | public TimeInfo(NtpV3Packet message, long returnTime, List comments) |
|
66 | { |
|
67 | 0 | this(message, returnTime, comments, true); |
68 | 0 | } |
69 | ||
70 | /** |
|
71 | * Create TimeInfo object with raw packet message and destination time received. |
|
72 | * Auto-computes details if computeDetails flag set otherwise this is delayed |
|
73 | * until computeDetails() is called. Delayed computation is for fast |
|
74 | * intialization when sub-millisecond timing is needed. |
|
75 | * |
|
76 | * @param msgPacket NTP message packet |
|
77 | * @param returnTime destination receive time |
|
78 | * @param doComputeDetails flag to pre-compute delay/offset values |
|
79 | * @throws IllegalArgumentException if message is null |
|
80 | */ |
|
81 | public TimeInfo(NtpV3Packet msgPacket, long returnTime, boolean doComputeDetails) |
|
82 | { |
|
83 | 0 | this(msgPacket, returnTime, null, doComputeDetails); |
84 | 0 | } |
85 | ||
86 | /** |
|
87 | * Create TimeInfo object with raw packet message and destination time received. |
|
88 | * Auto-computes details if computeDetails flag set otherwise this is delayed |
|
89 | * until computeDetails() is called. Delayed computation is for fast |
|
90 | * intialization when sub-millisecond timing is needed. |
|
91 | * |
|
92 | * @param message NTP message packet |
|
93 | * @param returnTime destination receive time |
|
94 | * @param comments list of comments used to store errors/warnings with message |
|
95 | * @param doComputeDetails flag to pre-compute delay/offset values |
|
96 | * @throws IllegalArgumentException if message is null |
|
97 | */ |
|
98 | public TimeInfo(NtpV3Packet message, long returnTime, List comments, |
|
99 | boolean doComputeDetails) |
|
100 | 0 | { |
101 | 0 | if (message == null) |
102 | 0 | throw new IllegalArgumentException("message cannot be null"); |
103 | 0 | this._returnTime = returnTime; |
104 | 0 | this._message = message; |
105 | 0 | this._comments = comments; |
106 | 0 | if (doComputeDetails) |
107 | 0 | computeDetails(); |
108 | 0 | } |
109 | ||
110 | /** |
|
111 | * Add comment (error/warning) to list of comments associated |
|
112 | * with processing of NTP parameters. If comment list not create |
|
113 | * then one will be created. |
|
114 | * |
|
115 | * @param comment |
|
116 | */ |
|
117 | public void addComment(String comment) |
|
118 | { |
|
119 | 0 | if (_comments == null) { |
120 | 0 | _comments = new ArrayList(); |
121 | } |
|
122 | 0 | _comments.add(comment); |
123 | 0 | } |
124 | ||
125 | /** |
|
126 | * Compute and validate details of the NTP message packet. Computed |
|
127 | * fields include the offset and delay. |
|
128 | */ |
|
129 | public void computeDetails() |
|
130 | { |
|
131 | 0 | if (_detailsComputed) { |
132 | 0 | return; // details already computed - do nothing |
133 | } |
|
134 | 0 | _detailsComputed = true; |
135 | 0 | if (_comments == null) { |
136 | 0 | _comments = new ArrayList(); |
137 | } |
|
138 | ||
139 | 0 | TimeStamp origNtpTime = _message.getOriginateTimeStamp(); |
140 | 0 | long origTime = origNtpTime.getTime(); |
141 | ||
142 | // Receive Time is time request received by server (t2) |
|
143 | 0 | TimeStamp rcvNtpTime = _message.getReceiveTimeStamp(); |
144 | 0 | long rcvTime = rcvNtpTime.getTime(); |
145 | ||
146 | // Transmit time is time reply sent by server (t3) |
|
147 | 0 | TimeStamp xmitNtpTime = _message.getTransmitTimeStamp(); |
148 | 0 | long xmitTime = xmitNtpTime.getTime(); |
149 | ||
150 | /* |
|
151 | * Round-trip network delay and local clock offset (or time drift) is calculated |
|
152 | * according to this standard NTP equation: |
|
153 | * |
|
154 | * LocalClockOffset = ((ReceiveTimestamp - OriginateTimestamp) + |
|
155 | * (TransmitTimestamp - DestinationTimestamp)) / 2 |
|
156 | * |
|
157 | * equations from RFC-1305 (NTPv3) |
|
158 | * roundtrip delay = (t4 - t1) - (t3 - t2) |
|
159 | * local clock offset = ((t2 - t1) + (t3 - t4)) / 2 |
|
160 | * |
|
161 | * It takes into account network delays and assumes that they are symmetrical. |
|
162 | * |
|
163 | * Note the typo in SNTP RFCs 1769/2030 which state that the delay |
|
164 | * is (T4 - T1) - (T2 - T3) with the "T2" and "T3" switched. |
|
165 | */ |
|
166 | 0 | if (origNtpTime.ntpValue() == 0) |
167 | { |
|
168 | // without originate time cannot determine when packet went out |
|
169 | // might be via a broadcast NTP packet... |
|
170 | 0 | if (xmitNtpTime.ntpValue() != 0) |
171 | { |
|
172 | 0 | _offset = new Long(xmitTime - _returnTime); |
173 | 0 | _comments.add("Error: zero orig time -- cannot compute delay"); |
174 | } else |
|
175 | 0 | _comments.add("Error: zero orig time -- cannot compute delay/offset"); |
176 | 0 | } else if (rcvNtpTime.ntpValue() == 0 || xmitNtpTime.ntpValue() == 0) |
177 | { |
|
178 | 0 | _comments.add("Warning: zero rcvNtpTime or xmitNtpTime"); |
179 | // assert destTime >= origTime since network delay cannot be negative |
|
180 | 0 | if (origTime > _returnTime) |
181 | 0 | _comments.add("Error: OrigTime > DestRcvTime"); |
182 | else |
|
183 | { |
|
184 | // without receive or xmit time cannot figure out processing time |
|
185 | // so delay is simply the network travel time |
|
186 | 0 | _delay = new Long(_returnTime - origTime); |
187 | } |
|
188 | // TODO: is offset still valid if rcvNtpTime=0 || xmitNtpTime=0 ??? |
|
189 | // Could always hash origNtpTime (sendTime) but if host doesn't set it |
|
190 | // then it's an malformed ntp host anyway and we don't care? |
|
191 | // If server is in broadcast mode then we never send out a query in first place... |
|
192 | 0 | if (rcvNtpTime.ntpValue() != 0) |
193 | { |
|
194 | // xmitTime is 0 just use rcv time |
|
195 | 0 | _offset = new Long(rcvTime - origTime); |
196 | 0 | } else if (xmitNtpTime.ntpValue() != 0) |
197 | { |
|
198 | // rcvTime is 0 just use xmitTime time |
|
199 | 0 | _offset = new Long(xmitTime - _returnTime); |
200 | } |
|
201 | } else |
|
202 | { |
|
203 | 0 | long delayValue = _returnTime - origTime; |
204 | // assert xmitTime >= rcvTime: difference typically < 1ms |
|
205 | 0 | if (xmitTime < rcvTime) |
206 | { |
|
207 | // server cannot send out a packet before receiving it... |
|
208 | 0 | _comments.add("Error: xmitTime < rcvTime"); // time-travel not allowed |
209 | } else |
|
210 | { |
|
211 | // subtract processing time from round-trip network delay |
|
212 | 0 | long delta = xmitTime - rcvTime; |
213 | // in normal cases the processing delta is less than |
|
214 | // the total roundtrip network travel time. |
|
215 | 0 | if (delta <= delayValue) |
216 | { |
|
217 | 0 | delayValue -= delta; // delay = (t4 - t1) - (t3 - t2) |
218 | } else |
|
219 | { |
|
220 | // if delta - delayValue == 1 ms then it's a round-off error |
|
221 | // e.g. delay=3ms, processing=4ms |
|
222 | 0 | if (delta - delayValue == 1) |
223 | { |
|
224 | // delayValue == 0 -> local clock saw no tick change but destination clock did |
|
225 | 0 | if (delayValue != 0) |
226 | { |
|
227 | 0 | _comments.add("Info: processing time > total network time by 1 ms -> assume zero delay"); |
228 | 0 | delayValue = 0; |
229 | } |
|
230 | } else |
|
231 | 0 | _comments.add("Warning: processing time > total network time"); |
232 | } |
|
233 | } |
|
234 | 0 | _delay = new Long(delayValue); |
235 | 0 | if (origTime > _returnTime) // assert destTime >= origTime |
236 | 0 | _comments.add("Error: OrigTime > DestRcvTime"); |
237 | ||
238 | 0 | _offset = new Long(((rcvTime - origTime) + (xmitTime - _returnTime)) / 2); |
239 | } |
|
240 | 0 | } |
241 | ||
242 | /** |
|
243 | * Return list of comments (if any) during processing of NTP packet. |
|
244 | * |
|
245 | * @return List or null if not yet computed |
|
246 | */ |
|
247 | public List getComments() |
|
248 | { |
|
249 | 0 | return _comments; |
250 | } |
|
251 | ||
252 | /** |
|
253 | * Get round-trip network delay. If null then could not compute the delay. |
|
254 | * |
|
255 | * @return Long or null if delay not available. |
|
256 | */ |
|
257 | public Long getDelay() |
|
258 | { |
|
259 | 0 | return _delay; |
260 | } |
|
261 | ||
262 | /** |
|
263 | * Get clock offset needed to adjust local clock to match remote clock. If null then could not |
|
264 | * compute the offset. |
|
265 | * |
|
266 | * @return Long or null if offset not available. |
|
267 | */ |
|
268 | public Long getOffset() |
|
269 | { |
|
270 | 0 | return _offset; |
271 | } |
|
272 | ||
273 | /** |
|
274 | * Returns NTP message packet. |
|
275 | * |
|
276 | * @return NTP message packet. |
|
277 | */ |
|
278 | public NtpV3Packet getMessage() |
|
279 | { |
|
280 | 0 | return _message; |
281 | } |
|
282 | ||
283 | /** |
|
284 | * Returns time at which time message packet was received by local machine. |
|
285 | * |
|
286 | * @return packet return time. |
|
287 | */ |
|
288 | public long getReturnTime() |
|
289 | { |
|
290 | 0 | return _class="keyword">returnTime; |
291 | } |
|
292 | ||
293 | } |
This report is generated by jcoverage, Maven and Maven JCoverage Plugin. |