1/*
2******************************************************************************
3* Copyright (C) 2007-2009, International Business Machines Corporation and   *
4* others. All Rights Reserved.                                               *
5******************************************************************************
6*/
7
8package com.ibm.icu.impl.duration;
9
10import java.util.TimeZone;
11
12/**
13 */
14public interface PeriodBuilderFactory {
15
16  /**
17   * Sets the time units available for use.  Default is all units.
18   * @param minUnit the smallest time unit available for use
19   * @param maxUnit the largest time unit available for use
20   * @return this factory
21   */
22  PeriodBuilderFactory setAvailableUnitRange(TimeUnit minUnit,
23                         TimeUnit maxUnit);
24
25  /**
26   * Sets whether the time unit is available for use.
27   * @param unit the time unit
28   * @param available true if the unit is available for use
29   * @return this factory
30   */
31  PeriodBuilderFactory setUnitIsAvailable(TimeUnit unit, boolean available);
32
33  /**
34   * Sets the maximum value for the largest available time unit (as
35   * set in setUnits).  Periods that represent a longer duration than
36   * this will be pinned to this value of that time unit and return
37   * true for 'isMoreThan'.  Default is no limit.  Setting a value of
38   * zero restores the default.
39   */
40  PeriodBuilderFactory setMaxLimit(float maxLimit);
41
42  /**
43   * Sets the minimum value for the smallest available time unit (as
44   * set in setUnits).  Periods that represent a shorter duration than
45   * this will be pinned to this value of that time unit and return
46   * true for 'isLessThan'.  Default is no limit.  Setting a value of
47   * zero restores the default.
48   */
49  PeriodBuilderFactory setMinLimit(float minLimit);
50
51  /**
52   * Sets whether units with a value of zero are represented in a
53   * period when 'gaps' appear between time units, e.g.
54   * '2 hours, 0 minutes, and 33 seconds'.  Default is to
55   * not represent these explicitly ('2 hours and 33 seconds').
56   */
57  PeriodBuilderFactory setAllowZero(boolean allow);
58
59  /**
60   * Sets whether weeks are used with other units, or only when
61   * weeks are the only unit.  For example '3 weeks and 2 days'
62   * versus '23 days'.  Default is to use them alone only.
63   */
64  PeriodBuilderFactory setWeeksAloneOnly(boolean aloneOnly);
65
66  /**
67   * Sets whether milliseconds are allowed.  This is only examined
68   * when milliseconds are an available field. The default is to allow
69   * milliseconds to display normally.
70   * <p>
71   * This is intended to be used to set locale-specific behavior.  Typically clients will
72   * not call this API and instead call {@link #setLocale}.
73   *
74   * @param allow whether milliseconds should be allowed.
75   * @return a builder
76   */
77   PeriodBuilderFactory setAllowMilliseconds(boolean allow);
78
79  /**
80   * Sets the locale for the factory.  Setting the locale can adjust
81   * the values for some or all of the other properties to reflect
82   * language or cultural conventions.  Default is to use
83   * the default locale.
84   */
85  PeriodBuilderFactory setLocale(String localeName);
86
87  /**
88   * Sets the time zone for the factory.  This can affect the timezone
89   * used for date computations.
90   * @param timeZone the timeZone
91   * @return a builder
92   */
93  PeriodBuilderFactory setTimeZone(TimeZone timeZone);
94 /**
95   * Returns a builder that represents durations in terms of the single
96   * given TimeUnit.  If the factory settings don't make the given unit
97   * available, this will return null.
98   *
99   * @param unit the single TimeUnit with which to represent times
100   * @return a builder
101   */
102  PeriodBuilder getFixedUnitBuilder(TimeUnit unit);
103
104  /**
105   * Returns a builder that represents durations in terms of the
106   * single largest period less than or equal to the duration.
107   *
108   * @return a builder
109   */
110  PeriodBuilder getSingleUnitBuilder();
111
112  /**
113   * Returns a builder that formats the largest one or two time units,
114   * starting with the largest period less than or equal to the duration.
115   * It formats two periods if the first period has a count &lt; 2
116   * and the next period has a count &gt;= 1.
117   *
118   * @return a builder
119   */
120  PeriodBuilder getOneOrTwoUnitBuilder();
121
122  /**
123   * Returns a builder that formats up to the given number of time units,
124   * starting with the largest unit less than or equal to the
125   * duration.
126   *
127   * @return a builder
128   */
129  PeriodBuilder getMultiUnitBuilder(int unitCount);
130}
131
132