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