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 < 2 116 * and the next period has a count >= 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