Coverage report

  %line %branch
org.apache.commons.net.ntp.TimeInfo
0% 
0% 

 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.