jars/icu4j-52_1/main/classes/core/src/com/ibm/icu/text/DurationFormat.java

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