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