1. /* ====================================================================
  2. * The Apache Software License, Version 1.1
  3. *
  4. * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
  5. * reserved.
  6. *
  7. * Redistribution and use in source and binary forms, with or without
  8. * modification, are permitted provided that the following conditions
  9. * are met:
  10. *
  11. * 1. Redistributions of source code must retain the above copyright
  12. * notice, this list of conditions and the following disclaimer.
  13. *
  14. * 2. Redistributions in binary form must reproduce the above copyright
  15. * notice, this list of conditions and the following disclaimer in
  16. * the documentation and/or other materials provided with the
  17. * distribution.
  18. *
  19. * 3. The end-user documentation included with the redistribution, if
  20. * any, must include the following acknowledgement:
  21. * "This product includes software developed by the
  22. * Apache Software Foundation (http://www.apache.org/)."
  23. * Alternately, this acknowledgement may appear in the software itself,
  24. * if and wherever such third-party acknowledgements normally appear.
  25. *
  26. * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  27. * Foundation" must not be used to endorse or promote products derived
  28. * from this software without prior written permission. For written
  29. * permission, please contact apache@apache.org.
  30. *
  31. * 5. Products derived from this software may not be called "Apache"
  32. * nor may "Apache" appear in their names without prior written
  33. * permission of the Apache Software Foundation.
  34. *
  35. * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38. * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39. * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42. * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43. * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44. * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46. * SUCH DAMAGE.
  47. * ====================================================================
  48. *
  49. * This software consists of voluntary contributions made by many
  50. * individuals on behalf of the Apache Software Foundation. For more
  51. * information on the Apache Software Foundation, please see
  52. * <http://www.apache.org/>.
  53. */
  54. package org.apache.commons.lang.time;
  55. /**
  56. * <p>Duration formatting utilites and constants.</p>
  57. *
  58. * @author Apache Ant - DateUtils
  59. * @author <a href="mailto:sbailliez@apache.org">Stephane Bailliez</a>
  60. * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
  61. * @author Stephen Colebourne
  62. * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
  63. * @since 2.0
  64. * @version $Id: DurationFormatUtils.java,v 1.5 2003/08/18 02:22:25 bayard Exp $
  65. */
  66. class DurationFormatUtils {
  67. // TODO: Make class public once methods can fully select which fields to output
  68. /**
  69. * <p>Pattern used with <code>FastDateFormat</code> and <code>SimpleDateFormat </code> for the ISO8601
  70. * date time extended format used in durations.</p>
  71. *
  72. * @see org.apache.commons.lang.time.FastDateFormat
  73. * @see java.text.SimpleDateFormat
  74. */
  75. public static final String ISO_EXTENDED_FORMAT_PATTERN = "'P'yyyy'Y'M'M'd'DT'H'H'm'M's.S'S'";
  76. /**
  77. * <p>ISO8601 formatter for the date time extended format used in durations,
  78. * with XML Schema durations particularly in mind.</p>
  79. *
  80. * <p>This format represents the Gregorian year, month, day, hour, minute, and second components defined
  81. * in  5.5.3.2 of ISO 8601, respectively. These components are ordered in their significance by their order
  82. * of appearance i.e. as year, month, day, hour, minute, and second.</p>
  83. *
  84. * <p>The ISO8601 extended format P<i>n</i>Y<i>n</i>M<i>n</i>DT<i>n</i>H<i>n</i>M<i>n</i>S, where <i>n</i>Y
  85. * represents the number of years, <i>n</i>M the number of months, <i>n</i>D the number of days,
  86. * 'T' is the date/time separator, <i>n</i>H the number of hours, <i>n</i>M the number of minutes and
  87. * <i>n</i>S the number of seconds. The number of seconds can include decimal digits to arbitrary precision.</p>
  88. *
  89. * @see #ISO_EXTENDED_FORMAT_PATTERN
  90. * @see <a href="http://www.w3.org/TR/xmlschema-2/#duration">http://www.w3.org/TR/xmlschema-2/#duration</a>
  91. */
  92. public static final FastDateFormat ISO_EXTENDED_FORMAT =
  93. FastDateFormat.getInstance(ISO_EXTENDED_FORMAT_PATTERN);
  94. /**
  95. * <p>Get the time gap as a string.</p>
  96. *
  97. * <p>The format used is ISO8601-like:
  98. * <i>hours</i>:<i>minutes</i>:<i>seconds</i>.<i>milliseconds</i>.</p>
  99. *
  100. * @param millis the duration to format
  101. * @return the time as a String
  102. */
  103. public static String formatISO(long millis) {
  104. int hours, minutes, seconds, milliseconds;
  105. hours = (int) (millis / DateUtils.MILLIS_IN_HOUR);
  106. millis = millis - (hours * DateUtils.MILLIS_IN_HOUR);
  107. minutes = (int) (millis / DateUtils.MILLIS_IN_MINUTE);
  108. millis = millis - (minutes * DateUtils.MILLIS_IN_MINUTE);
  109. seconds = (int) (millis / DateUtils.MILLIS_IN_SECOND);
  110. millis = millis - (seconds * DateUtils.MILLIS_IN_SECOND);
  111. milliseconds = (int) millis;
  112. StringBuffer buf = new StringBuffer(32);
  113. buf.append(hours);
  114. buf.append(':');
  115. buf.append((char) (minutes / 10 + '0'));
  116. buf.append((char) (minutes % 10 + '0'));
  117. buf.append(':');
  118. buf.append((char) (seconds / 10 + '0'));
  119. buf.append((char) (seconds % 10 + '0'));
  120. buf.append('.');
  121. if (milliseconds < 10) {
  122. buf.append('0').append('0');
  123. } else if (milliseconds < 100) {
  124. buf.append('0');
  125. }
  126. buf.append(milliseconds);
  127. return buf.toString();
  128. }
  129. /**
  130. * <p>Format an elapsed time into a plurialization correct string.
  131. * It is limited only to report elapsed time in minutes and
  132. * seconds and has the following behavior.</p>
  133. *
  134. * <ul>
  135. * <li>minutes are not displayed when <code>0</code> (ie:
  136. * "45 seconds")</li>.
  137. * <li>seconds are always displayed in plural form (ie
  138. * "0 seconds" or "10 seconds") except
  139. * for <code>1</code> (ie "1 second")</li>
  140. * </ul>
  141. *
  142. * @param millis the elapsed time to report in milliseconds
  143. * @return the formatted text in minutes/seconds
  144. */
  145. public static String formatWords(
  146. long millis,
  147. boolean supressLeadingZeroElements,
  148. boolean supressTrailingZeroElements) {
  149. long[] values = new long[4];
  150. values[0] = millis / DateUtils.MILLIS_IN_DAY;
  151. values[1] = (millis / DateUtils.MILLIS_IN_HOUR) % 24;
  152. values[2] = (millis / DateUtils.MILLIS_IN_MINUTE) % 60;
  153. values[3] = (millis / DateUtils.MILLIS_IN_SECOND) % 60;
  154. String[] fieldsOne = { " day ", " hour ", " minute ", " second" };
  155. String[] fieldsPlural = { " days ", " hours ", " minutes ", " seconds" };
  156. StringBuffer buf = new StringBuffer(64);
  157. boolean valueOutput = false;
  158. for (int i = 0; i < 4; i++) {
  159. long value = values[i];
  160. if (value == 0) {
  161. // handle zero
  162. if (valueOutput) {
  163. if (supressTrailingZeroElements == false) {
  164. buf.append('0').append(fieldsPlural[i]);
  165. }
  166. } else {
  167. if (supressLeadingZeroElements == false) {
  168. buf.append('0').append(fieldsPlural[i]);
  169. }
  170. }
  171. } else if (value == 1) {
  172. // one
  173. valueOutput = true;
  174. buf.append('1').append(fieldsOne[i]);
  175. } else {
  176. // other
  177. valueOutput = true;
  178. buf.append(value).append(fieldsPlural[i]);
  179. }
  180. }
  181. return buf.toString().trim();
  182. }
  183. /**
  184. * <p>DurationFormatUtils instances should NOT be constructed in standard programming.</p>
  185. *
  186. * <p>This constructor is public to permit tools that require a JavaBean instance
  187. * to operate.</p>
  188. */
  189. public DurationFormatUtils() {
  190. }
  191. }