jars/icu4j-52_1/main/classes/core/src/com/ibm/icu/impl/duration/PeriodBuilderFactory.java

   1 /*
   2 ******************************************************************************
   3 * Copyright (C) 2007-2009, International Business Machines Corporation and   *
   4 * others. All Rights Reserved.                                               *
   5 ******************************************************************************
   6 */
   7
   8 package com.ibm.icu.impl.duration;
   9
  10 import java.util.TimeZone;
  11
  12 /**
  13  */
  14 public 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