jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/text/DurationFormat.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 2007-2009, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 package com.ibm.icu.text;\r
   8 \r
   9 import java.text.FieldPosition;\r
  10 import java.text.ParsePosition;\r
  11 import java.util.Date;\r
  12 \r
  13 import com.ibm.icu.impl.duration.BasicDurationFormat;\r
  14 import com.ibm.icu.util.ULocale;\r
  15 \r
  16 /**\r
  17  * This class implements a formatter over a duration in time\r
  18  * such as "2 days from now" or "3 hours ago".\r
  19  * \r
  20  * @stable ICU 3.8\r
  21  */\r
  22 public abstract class DurationFormat extends UFormat {\r
  23 \r
  24     private static final long serialVersionUID = -2076961954727774282L;\r
  25 \r
  26     /**\r
  27      * Construct a duration format for the specified locale\r
  28      * @stable ICU 3.8\r
  29      */\r
  30     public static DurationFormat getInstance(ULocale locale) {\r
  31         return BasicDurationFormat.getInstance(locale);\r
  32     }\r
  33     \r
  34 \r
  35     /**\r
  36      * Subclass interface\r
  37      * @internal\r
  38      * @deprecated This API is ICU internal only.\r
  39      */\r
  40     protected DurationFormat() {\r
  41     }\r
  42     \r
  43     /**\r
  44      * Subclass interface\r
  45      * @internal\r
  46      * @deprecated This API is ICU internal only.\r
  47      */\r
  48     protected DurationFormat(ULocale locale) {\r
  49         setLocale(locale,locale);\r
  50     }\r
  51 \r
  52     /**\r
  53      * Format an arbitrary object.\r
  54      * Defaults to a call to formatDurationFromNow() for either Long or Date objects.\r
  55      * @param object the object to format. Should be either a Long, Date, or javax.xml.datatype.Duration object.\r
  56      * @param toAppend the buffer to append to\r
  57      * @param pos the field position, may contain additional error messages.\r
  58      * @return the toAppend buffer\r
  59      * @stable ICU 3.8\r
  60      */\r
  61     public abstract StringBuffer format(Object object, StringBuffer toAppend,\r
  62             FieldPosition pos);\r
  63 \r
  64     /**\r
  65      * DurationFormat cannot parse, by default. This method will throw an UnsupportedOperationException.\r
  66      * @stable ICU 3.8\r
  67      */\r
  68     public Object parseObject(String source, ParsePosition pos) {\r
  69        throw new UnsupportedOperationException();\r
  70     }\r
  71 \r
  72     /**\r
  73      * Formats the duration between now and a target date.\r
  74      * <p>\r
  75      * This is a convenience method that calls\r
  76      * formatDurationFrom(long, long) using now\r
  77      * as the reference date, and the difference between now and\r
  78      * <code>targetDate.getTime()</code> as the duration.\r
  79      * \r
  80      * @param targetDate the ending date\r
  81      * @return the formatted time\r
  82      * @stable ICU 3.8\r
  83      */\r
  84     public abstract String formatDurationFromNowTo(Date targetDate);\r
  85 \r
  86     /**\r
  87      * Formats a duration expressed in milliseconds.\r
  88      * <p>\r
  89      * This is a convenience method that calls formatDurationFrom\r
  90      * using the current system time as the reference date.\r
  91      * \r
  92      * @param duration the duration in milliseconds\r
  93      * @return the formatted time\r
  94      * @stable ICU 3.8\r
  95      */\r
  96     public abstract String formatDurationFromNow(long duration);\r
  97 \r
  98     /**\r
  99      * Formats a duration expressed in milliseconds from a reference date.\r
 100      * <p>\r
 101      * The reference date allows formatters to use actual durations of\r
 102      * variable-length periods (like months) if they wish.\r
 103      * <p>\r
 104      * The duration is expressed as the number of milliseconds in the\r
 105      * past (negative values) or future (positive values) with respect\r
 106      * to a reference date (expressed as milliseconds in epoch).\r
 107      * \r
 108      * @param duration the duration in milliseconds\r
 109      * @param referenceDate the date from which to compute the duration\r
 110      * @return the formatted time\r
 111      * @stable ICU 3.8\r
 112      */\r
 113     public abstract String formatDurationFrom(long duration, long referenceDate);\r
 114 }\r