org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/event/TmfTimestampFormat.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Francois Chouinard - Initial API and implementation
  11  *******************************************************************************/
  12
  13 package org.eclipse.linuxtools.tmf.core.event;
  14
  15 import java.text.DecimalFormat;
  16 import java.text.ParseException;
  17 import java.text.SimpleDateFormat;
  18 import java.util.ArrayList;
  19 import java.util.Calendar;
  20 import java.util.Date;
  21 import java.util.List;
  22 import java.util.TimeZone;
  23 import java.util.regex.Matcher;
  24 import java.util.regex.Pattern;
  25
  26 import org.eclipse.linuxtools.tmf.core.signal.TmfSignalManager;
  27 import org.eclipse.linuxtools.tmf.core.signal.TmfTimestampFormatUpdateSignal;
  28
  29 /**
  30  * A formatting and parsing facility that can handle timestamps that span the
  31  * epoch with a precision down to the nanosecond. It can  be understood as a
  32  * simplified and more constrained version of SimpleDateFormat as it limits the
  33  * number of allowed pattern characters and the acceptable timestamp formats.
  34  * <p>
  35  * The timestamp representation is broken down into a number of optional
  36  * components that can be assembled into a fairly simple way.
  37  *
  38  * <h4>Date Pattern</h4>
  39  * <blockquote>
  40  * <table border=0 cellspacing=3 cellpadding=0 >
  41  *     <tr bgcolor="#ccccff">
  42  *         <th align=left>Format
  43  *         <th align=left>Description
  44  *         <th align=left>Value Range
  45  *         <th align=left>Example
  46  *     <tr>
  47  *         <td><code>yyyy</code>
  48  *         <td>Year
  49  *         <td><code>1970-...</code>
  50  *         <td><code>2012</code>
  51  *     <tr bgcolor="#eeeeff">
  52  *         <td><code>MM</code>
  53  *         <td>Month in year
  54  *         <td><code>01-12</code>
  55  *         <td><code>09</code>
  56  *     <tr>
  57  *         <td><code>dd</code>
  58  *         <td>Day in month
  59  *         <td><code>01-31</code>
  60  *         <td><code>22</code>
  61  * </table>
  62  * </blockquote>
  63  *
  64  * <h4>Time Pattern</h4>
  65  * <blockquote>
  66  * <table border=0 cellspacing=3 cellpadding=0 >
  67  *     <tr bgcolor="#ccccff">
  68  *         <th align=left>Format
  69  *         <th align=left>Description
  70  *         <th align=left>Value Range
  71  *         <th align=left>Example
  72  *     <tr>
  73  *         <td><code>HH</code>
  74  *         <td>Hour in day
  75  *         <td><code>00-23</code>
  76  *         <td><code>07</code>
  77  *     <tr bgcolor="#eeeeff">
  78  *         <td><code>mm</code>
  79  *         <td>Minute in hour
  80  *         <td><code>00-59</code>
  81  *         <td><code>35</code>
  82  *     <tr>
  83  *         <td><code>ss</code>
  84  *         <td>Second in minute
  85  *         <td><code>00-59</code>
  86  *         <td><code>41</code>
  87  *     <tr bgcolor="#eeeeff">
  88  *         <td><code>T</code>
  89  *         <td>The seconds since the epoch
  90  *         <td><code>00-...</code>
  91  *         <td><code>1332170682</code>
  92  * </table>
  93  * </blockquote>
  94  *
  95  * <h4>Sub-Seconds Pattern</h4>
  96  * <blockquote>
  97  * <table border=0 cellspacing=3 cellpadding=0 >
  98  *     <tr bgcolor="#ccccff">
  99  *         <th align=left>Format
 100  *         <th align=left>Description
 101  *         <th align=left>Value Range
 102  *         <th align=left>Example
 103  *     <tr>
 104  *         <td><code>SSS</code>
 105  *         <td>Millisecond in second
 106  *         <td><code>000-999</code>
 107  *         <td><code>123</code>
 108  *     <tr bgcolor="#eeeeff">
 109  *         <td><code>CCC</code>
 110  *         <td>Microseconds in ms
 111  *         <td><code>000-999</code>
 112  *         <td><code>456</code>
 113  *     <tr>
 114  *         <td><code>NNN</code>
 115  *         <td>Nanosecond in &#181s
 116  *         <td><code>000-999</code>
 117  *         <td><code>789</code>
 118  * </table>
 119  * </blockquote>
 120  *
 121  * <strong>Note: </strong>If "T" is used, no other Date or Time pattern
 122  * can be used. Also, "T" should be used for time intervals.
 123  * <p>
 124  * <strong>Note: </strong>Each sub-field can be separated by a single,
 125  * optional character delimiter. However, the between Date/Time and the
 126  * Sub-seconds pattern is mandatory (if there is a fractional part) and
 127  * has to be separated from Date/time by "." (period).
 128  * <p>
 129  * The recognized delimiters are:
 130  * <ul>
 131  * <li>Space ("<code> </code>")
 132  * <li>Period (<code>".</code>")
 133  * <li>Comma ("<code>,</code>")
 134  * <li>Dash ("<code>-</code>")
 135  * <li>Underline ("<code>_</code>")
 136  * <li>Colon ("<code>:</code>")
 137  * <li>Semicolon ("<code>;</code>")
 138  * <li>Slash ("<code>/</code>")
 139  * <li>Double-quote ("<code>"</code>")
 140  * </ul>
 141  *
 142  * <h4>Examples</h4>
 143  * The following examples show how timestamp patterns are interpreted in
 144  * the U.S. locale. The given timestamp is 1332170682539677389L, the number
 145  * of nanoseconds since 1970/01/01.
 146  *
 147  * <blockquote>
 148  * <table border=0 cellspacing=3 cellpadding=0>
 149  *     <tr bgcolor="#ccccff">
 150  *         <th align=left>Date and Time Pattern
 151  *         <th align=left>Result
 152  *     <tr>
 153  *         <td><code>"yyyy-MM-dd HH:mm:ss.SSS.CCC.NNN"</code>
 154  *         <td><code>2012-03-19 11:24:42.539.677.389</code>
 155  *     <tr bgcolor="#eeeeff">
 156  *         <td><code>"yyyy-MM-dd HH:mm:ss.SSS.CCC"</code>
 157  *         <td><code>2012-03-19 11:24:42.539.677</code>
 158  *     <tr>
 159  *         <td><code>"yyyy-D HH:mm:ss.SSS.CCC"</code>
 160  *         <td><code>2012-79 11:24:42.539.677</code>
 161  *     <tr bgcolor="#eeeeff">
 162  *         <td><code>"ss.SSSCCCNNN"</code>
 163  *         <td><code>42.539677389</code>
 164  *     <tr>
 165  *         <td><code>"T.SSS CCC NNN"</code>
 166  *         <td><code>1332170682.539 677 389</code>
 167  *     <tr bgcolor="#eeeeff">
 168  *         <td><code>"T"</code>
 169  *         <td><code>1332170682</code>
 170  * </table>
 171  * </blockquote>
 172  * <p>
 173  * @version 1.0
 174  * @since 2.0
 175  * @author Francois Chouinard
 176  */
 177 public class TmfTimestampFormat extends SimpleDateFormat {
 178
 179     // ------------------------------------------------------------------------
 180     // Constants
 181     // ------------------------------------------------------------------------
 182
 183     /**
 184      * This class' serialization ID
 185      */
 186     private static final long serialVersionUID = 2835829763122454020L;
 187
 188     /**
 189      * The default timestamp pattern
 190      */
 191     public static final String DEFAULT_TIME_PATTERN = "HH:mm:ss.SSS CCC NNN"; //$NON-NLS-1$
 192
 193     /**
 194      * The LTTng 0.x legacy timestamp format
 195      */
 196     public static final String DEFAULT_INTERVAL_PATTERN = "TTT.SSS CCC NNN"; //$NON-NLS-1$
 197
 198     // Fractions of seconds supported patterns
 199     private static final String DOT_RE = "\\.";                 //$NON-NLS-1$
 200     private static final String SEP_RE = "[ \\.,-_:;/\\\"]?";   //$NON-NLS-1$
 201     private static final String DGTS_3_RE  = "(\\d{3})";        //$NON-NLS-1$
 202     private static final String DGTS_13_RE = "(\\d{1,3})";      //$NON-NLS-1$
 203
 204     private static final String MILLISEC_RE = DOT_RE + DGTS_13_RE;
 205     private static final String MICROSEC_RE = DOT_RE + DGTS_3_RE + SEP_RE + DGTS_13_RE;
 206     private static final String NANOSEC_RE  = DOT_RE + DGTS_3_RE + SEP_RE + DGTS_3_RE + SEP_RE + DGTS_13_RE;
 207
 208     private static final Pattern MILLISEC_PAT = Pattern.compile(MILLISEC_RE);
 209     private static final Pattern MICROSEC_PAT = Pattern.compile(MICROSEC_RE);
 210     private static final Pattern NANOSEC_PAT  = Pattern.compile(NANOSEC_RE);
 211
 212     // ------------------------------------------------------------------------
 213     // Attributes
 214     // ------------------------------------------------------------------------
 215
 216     // The default timestamp pattern
 217     private static String fDefaultTimePattern = null;
 218     private static TmfTimestampFormat fDefaultTimeFormat = null;
 219
 220     // The default time interval format
 221     private static String fDefaultIntervalPattern = null;
 222     private static TmfTimestampFormat fDefaultIntervalFormat = null;
 223
 224     // The timestamp pattern
 225     private String fPattern;
 226
 227     // The timestamp pattern
 228     private List<String> fSupplPatterns = new ArrayList<String>();
 229
 230     /**
 231      * The supplementary pattern letters. Can be redefined by sub-classes
 232      * to either override existing letters or augment the letter set.
 233      * If so, the format() method must provide the (re-)implementation of the
 234      * pattern.
 235      */
 236     protected String fSupplPatternLetters = "TSCN"; //$NON-NLS-1$
 237
 238     /*
 239      * The bracketing symbols used to mitigate the risk of a format string
 240      * that contains escaped sequences that would conflict with our format
 241      * extension.
 242      */
 243     /** The open bracket symbol */
 244     protected String fOpenBracket   = "[&"; //$NON-NLS-1$
 245
 246     /** The closing bracket symbol */
 247     protected String fCloseBracket  = "&]"; //$NON-NLS-1$
 248
 249     // ------------------------------------------------------------------------
 250     // Constructors
 251     // ------------------------------------------------------------------------
 252
 253     /**
 254      * The default constructor (uses the default pattern)
 255      */
 256     public TmfTimestampFormat() {
 257         this(fDefaultTimePattern);
 258     }
 259
 260     /**
 261      * The normal constructor
 262      *
 263      * @param pattern the format pattern
 264      */
 265     public TmfTimestampFormat(String pattern) {
 266         applyPattern(pattern);
 267     }
 268
 269     /**
 270      * The copy constructor
 271      *
 272      * @param other the other format pattern
 273      */
 274     public TmfTimestampFormat(TmfTimestampFormat other) {
 275         this(other.fPattern);
 276     }
 277
 278     // ------------------------------------------------------------------------
 279     // Getters/setters
 280     // ------------------------------------------------------------------------
 281
 282     /**
 283      * @param pattern the new default time pattern
 284      */
 285     public static void setDefaultTimeFormat(final String pattern) {
 286         fDefaultTimePattern = pattern;
 287         fDefaultTimeFormat = new TmfTimestampFormat(fDefaultTimePattern);
 288         TmfSignalManager.dispatchSignal(new TmfTimestampFormatUpdateSignal(null));
 289     }
 290
 291     /**
 292      * @return the default time format pattern
 293      */
 294     public static TmfTimestampFormat getDefaulTimeFormat() {
 295         if (fDefaultTimeFormat == null) {
 296             fDefaultTimeFormat = new TmfTimestampFormat(DEFAULT_TIME_PATTERN);
 297         }
 298         return fDefaultTimeFormat;
 299     }
 300
 301     /**
 302      * @param pattern the new default interval pattern
 303      */
 304     public static void setDefaultIntervalFormat(final String pattern) {
 305         fDefaultIntervalPattern = pattern;
 306         fDefaultIntervalFormat = new TmfTimestampFormat(fDefaultIntervalPattern);
 307         TmfSignalManager.dispatchSignal(new TmfTimestampFormatUpdateSignal(null));
 308     }
 309
 310     /**
 311      * @return the default interval format pattern
 312      */
 313     public static TmfTimestampFormat getDefaulIntervalFormat() {
 314         if (fDefaultIntervalFormat == null) {
 315             fDefaultIntervalFormat = new TmfTimestampFormat(DEFAULT_INTERVAL_PATTERN);
 316         }
 317         return fDefaultIntervalFormat;
 318     }
 319
 320     /* (non-Javadoc)
 321      * @see java.text.SimpleDateFormat#applyPattern(java.lang.String)
 322      */
 323     @Override
 324     public void applyPattern(String pattern) {
 325         fPattern = pattern;
 326         String quotedPattern = quoteSpecificTags(pattern);
 327         super.applyPattern(quotedPattern);
 328     }
 329
 330     /* (non-Javadoc)
 331      * @see java.text.SimpleDateFormat#toPattern()
 332      */
 333     @Override
 334     public String toPattern() {
 335         return fPattern;
 336     }
 337
 338     // ------------------------------------------------------------------------
 339     // Operations
 340     // ------------------------------------------------------------------------
 341
 342     /**
 343      * Format the timestamp according to its pattern.
 344      *
 345      * @param value the timestamp value to format (in ns)
 346      * @return the formatted timestamp
 347      */
 348     public synchronized String format(long value) {
 349
 350         // Split the timestamp value into its sub-components
 351         long sec = value / 1000000000;            // seconds
 352         long ms  = value % 1000000000 / 1000000;  // milliseconds
 353         long cs  = value % 1000000    / 1000;     // microseconds
 354         long ns  = value % 1000;                  // nanoseconds
 355
 356         // Let the base class fill the stuff it knows about
 357         StringBuffer result = new StringBuffer(super.format(sec * 1000 + ms));
 358
 359         // In the case where there is no separation between 2 supplementary
 360         // fields, the pattern will have the form "..'[pat-1]''[pat-2]'.." and
 361         // the base class format() will interpret the 2 adjacent quotes as a
 362         // wanted character in the result string as ("..[pat-1]'[pat-2]..").
 363         // Remove these extra quotes before filling the supplementary fields.
 364         int loc = result.indexOf(fCloseBracket + "'" + fOpenBracket); //$NON-NLS-1$
 365         while (loc != -1) {
 366             result.deleteCharAt(loc + fCloseBracket.length());
 367             loc = result.indexOf(fCloseBracket + "'" + fOpenBracket); //$NON-NLS-1$
 368         }
 369
 370         // Fill in our extensions
 371         for (String pattern : fSupplPatterns) {
 372             int length = pattern.length();
 373
 374             // Prepare the format buffer
 375             StringBuffer fmt = new StringBuffer(length);
 376             for (int i = 0; i < length; i++) {
 377                 fmt.append("0"); //$NON-NLS-1$
 378             }
 379             DecimalFormat dfmt = new DecimalFormat(fmt.toString());
 380             String fmtVal = ""; //$NON-NLS-1$;
 381
 382             // Format the proper value as per the pattern
 383             switch (pattern.charAt(0)) {
 384                 case 'T':
 385                     fmtVal = dfmt.format(sec);
 386                     break;
 387                 case 'S':
 388                     fmtVal = dfmt.format(ms);
 389                     break;
 390                 case 'C':
 391                     fmtVal = dfmt.format(cs);
 392                     break;
 393                 case 'N':
 394                     fmtVal = dfmt.format(ns);
 395                     break;
 396                 default:
 397                     break;
 398             }
 399
 400             // Substitute the placeholder with the formatted value
 401             String ph = new StringBuffer(fOpenBracket + pattern + fCloseBracket).toString();
 402             loc = result.indexOf(ph);
 403             result.replace(loc, loc + length + fOpenBracket.length() + fCloseBracket.length(), fmtVal);
 404         }
 405
 406         return result.toString();
 407     }
 408
 409     /**
 410      * Parse a string according to the format pattern
 411      *
 412      * @param string the source string
 413      * @param ref the reference (base) time
 414      * @return the parsed value
 415      * @throws ParseException if the string has an invalid format
 416      */
 417     public synchronized long parseValue(final String string, final long ref) throws ParseException {
 418
 419         // Trivial case
 420         if (string == null || string.length() == 0) {
 421             return 0;
 422         }
 423
 424         // The timestamp sub-components
 425         long seconds  = -1;
 426         long millisec =  0;
 427         long microsec =  0;
 428         long nanosec  =  0;
 429
 430         // Since we are processing the fractional part, substitute it with
 431         // its pattern so the base parser doesn't complain
 432         StringBuilder sb = new StringBuilder(string);
 433         int dot = string.indexOf('.');
 434         if (dot == -1) {
 435             sb.append('.');
 436             dot = string.length();
 437         }
 438         sb = new StringBuilder(string.substring(0, dot));
 439         String basePattern = super.toPattern();
 440         int dot2 = basePattern.indexOf('.');
 441         if (dot2 != -1) {
 442             sb.append(basePattern.substring(dot2));
 443         }
 444
 445         // Fill in our extensions
 446         for (String pattern : fSupplPatterns) {
 447             String pat = fOpenBracket + pattern + fCloseBracket;
 448             Matcher matcher;
 449
 450             // Extract the substring corresponding to the extra pattern letters
 451             // and replace with the pattern so the base parser can do its job.
 452             switch (pattern.charAt(0)) {
 453                 case 'T':
 454                     // Remove everything up to the first "." and  compute the
 455                     // number of seconds since the epoch. If there is no period,
 456                     // assume an integer value and return immediately
 457                     if (dot < 1) {
 458                         return new DecimalFormat("0").parse(string).longValue() * 1000000000; //$NON-NLS-1$
 459                     }
 460                     seconds = new DecimalFormat("0").parse(string.substring(0, dot)).longValue(); //$NON-NLS-1$
 461                     sb.delete(0, dot);
 462                     sb.insert(0, pat);
 463                     break;
 464                 case 'S':
 465                     matcher = MILLISEC_PAT.matcher(string.substring(dot));
 466                     if (matcher.find()) {
 467                         millisec = new Long(matcher.group(1));
 468                         for (int l = matcher.group(1).length(); l < 3; l++) {
 469                             millisec *= 10;
 470                         }
 471                     }
 472                     stripQuotes(sb, pattern);
 473                     break;
 474                 case 'C':
 475                     matcher = MICROSEC_PAT.matcher(string.substring(dot));
 476                     if (matcher.find()) {
 477                         microsec = new Long(matcher.group(2));
 478                         for (int l = matcher.group(2).length(); l < 3; l++) {
 479                             microsec *= 10;
 480                         }
 481                     }
 482                     stripQuotes(sb, pattern);
 483                     break;
 484                 case 'N':
 485                     matcher = NANOSEC_PAT.matcher(string.substring(dot));
 486                     if (matcher.find()) {
 487                         nanosec = new Long(matcher.group(3));
 488                         for (int l = matcher.group(3).length(); l < 3; l++) {
 489                             nanosec *= 10;
 490                         }
 491                     }
 492                     stripQuotes(sb, pattern);
 493                     break;
 494                 default:
 495                     break;
 496             }
 497         }
 498
 499         // If there was no "T" (thus not an interval), parse as a date
 500         if (seconds == -1) {
 501             Date baseDate = super.parse(sb.toString());
 502
 503             Calendar refTime = Calendar.getInstance(getTimeZone());
 504             refTime.setTimeInMillis(ref / 1000000);
 505             Calendar newTime = Calendar.getInstance(getTimeZone());
 506             newTime.setTimeInMillis(baseDate.getTime());
 507
 508             int[] fields = new int[] { Calendar.YEAR, Calendar.MONTH, Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND };
 509             for (int field : fields) {
 510                 int value = newTime.get(field);
 511                 // Do some adjustments...
 512                 if (field == Calendar.YEAR) {
 513                     value -= 1970;
 514                 } else if (field == Calendar.DATE) {
 515                     value -= 1;
 516                 }
 517                 // ... and fill-in the empty fields
 518                 if (value == 0) {
 519                     newTime.set(field, refTime.get(field));
 520                 } else {
 521                     break; // Get out as soon as we have a significant value
 522                 }
 523             }
 524             seconds = newTime.getTimeInMillis() / 1000;
 525         }
 526
 527         // Compute the value in ns
 528         return seconds * 1000000000 +  millisec * 1000000 +  microsec * 1000 +  nanosec;
 529     }
 530
 531     /**
 532      * Parse a string according to the format pattern
 533      *
 534      * @param string the source string
 535      * @return the parsed value
 536      * @throws ParseException if the string has an invalid format
 537      */
 538     public long parseValue(final String string) throws ParseException {
 539         long result = parseValue(string, 0);
 540         return result;
 541
 542     }
 543
 544     // ------------------------------------------------------------------------
 545     // Helper functions
 546     // ------------------------------------------------------------------------
 547
 548     /**
 549      * Copy the pattern but quote (bracket with "[&" and "&]") the
 550      * TmfTimestampFormat specific tags so these fields are treated as
 551      * comments by the base class.
 552      *
 553      * It also keeps track of the corresponding quoted fields so they can be
 554      * properly populated later on (by format()).
 555      *
 556      * @param pattern the 'extended' pattern
 557      * @return the quoted and bracketed pattern
 558      */
 559     private String quoteSpecificTags(final String pattern) {
 560
 561         StringBuffer result = new StringBuffer();
 562
 563         int length = pattern.length();
 564         boolean inQuote = false;
 565
 566         for (int i = 0; i < length; i++) {
 567             char c = pattern.charAt(i);
 568             result.append(c);
 569             if (c == '\'') {
 570                 // '' is treated as a single quote regardless of being
 571                 // in a quoted section.
 572                 if ((i + 1) < length) {
 573                     c = pattern.charAt(i + 1);
 574                     if (c == '\'') {
 575                         i++;
 576                         result.append(c);
 577                         continue;
 578                     }
 579                 }
 580                 inQuote = !inQuote;
 581                 continue;
 582             }
 583             if (!inQuote) {
 584                 if (fSupplPatternLetters.indexOf(c) != -1) {
 585                     StringBuilder pat = new StringBuilder();
 586                     pat.append(c);
 587                     result.insert(result.length() - 1, "'" + fOpenBracket); //$NON-NLS-1$
 588                     while ((i + 1) < length && pattern.charAt(i + 1) == c) {
 589                         result.append(c);
 590                         pat.append(c);
 591                         i++;
 592                     }
 593                     result.append(fCloseBracket + "'"); //$NON-NLS-1$
 594                     fSupplPatterns.add(pat.toString());
 595                 }
 596             }
 597         }
 598         return result.toString();
 599     }
 600
 601     /**
 602      * Remove the quotes from the pattern
 603      *
 604      * @param sb
 605      * @param pattern
 606      */
 607     private void stripQuotes(StringBuilder sb, String pattern) {
 608         String pt = "'" + fOpenBracket + pattern + fCloseBracket + "'";  //$NON-NLS-1$//$NON-NLS-2$
 609         int l = sb.indexOf(pt);
 610         if (l != -1) {
 611             sb.delete(l + pt.length() - 1, l + pt.length());
 612             sb.delete(l, l + 1);
 613         }
 614     }
 615
 616 }