jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/impl/duration/DurationFormatter.java

   1 /*\r
   2 ******************************************************************************\r
   3 * Copyright (C) 2007, International Business Machines Corporation and   *\r
   4 * others. All Rights Reserved.                                               *\r
   5 ******************************************************************************\r
   6 */\r
   7 \r
   8 package com.ibm.icu.impl.duration;\r
   9 \r
  10 import java.util.Date;\r
  11 import java.util.TimeZone;\r
  12 \r
  13 /**\r
  14  * Formatter for durations in milliseconds.\r
  15  */\r
  16 public interface DurationFormatter {\r
  17 \r
  18   /**\r
  19    * Formats the duration between now and a target date.\r
  20    * <p>\r
  21    * This is a convenience method that calls\r
  22    * formatDurationFrom(long, long) using now\r
  23    * as the reference date, and the difference between now and\r
  24    * <code>targetDate.getTime()</code> as the duration.\r
  25    * \r
  26    * @param targetDate the ending date\r
  27    * @return the formatted time\r
  28    */\r
  29   String formatDurationFromNowTo(Date targetDate);\r
  30 \r
  31   /**\r
  32    * Formats a duration expressed in milliseconds.\r
  33    * <p>\r
  34    * This is a convenience method that calls formatDurationFrom\r
  35    * using the current system time as the reference date.\r
  36    * \r
  37    * @param duration the duration in milliseconds\r
  38    * @param tz the time zone\r
  39    * @return the formatted time\r
  40    */\r
  41   String formatDurationFromNow(long duration);\r
  42 \r
  43   /**\r
  44    * Formats a duration expressed in milliseconds from a reference date.\r
  45    * <p>\r
  46    * The reference date allows formatters to use actual durations of\r
  47    * variable-length periods (like months) if they wish.\r
  48    * <p>\r
  49    * The duration is expressed as the number of milliseconds in the\r
  50    * past (negative values) or future (positive values) with respect\r
  51    * to a reference date (expressed as milliseconds in epoch).\r
  52    * \r
  53    * @param duration the duration in milliseconds\r
  54    * @param referenceDate the date from which to compute the duration\r
  55    * @return the formatted time\r
  56    */\r
  57   String formatDurationFrom(long duration, long referenceDate);\r
  58 \r
  59   /**\r
  60    * Returns a new DurationFormatter that's the same as this one \r
  61    * but formats for a new locale.\r
  62    *\r
  63    * @param localeName the name of the new locale\r
  64    * @return a new formatter for the given locale\r
  65    */\r
  66   DurationFormatter withLocale(String localeName);\r
  67 \r
  68   /**\r
  69    * Returns a new DurationFormatter that's the same as this one but\r
  70    * uses a different time zone.\r
  71    *\r
  72    * @param tz the time zone in which to compute durations.\r
  73    * @return a new formatter for the given locale\r
  74    */\r
  75   DurationFormatter withTimeZone(TimeZone tz);\r
  76 }\r