cz.auderis.tools.time

Class SimpleDurationFormat

java.lang.Object

cz.auderis.tools.time.SimpleDurationFormat

All Implemented Interfaces:

Serializable

public abstract class SimpleDurationFormat
extends Object
implements Serializable

SimpleDurationFormat is a class for formatting human-readable, localized duration information.

In order to improve readability, the leading (i.e. most significant) time unit has typically value greater than 1:

Duration in seconds	Typical formatted representation
59	59 seconds
60	60 seconds
61	61 seconds
119	119 seconds
120	2 minutes
121	2 minutes 1 second

Version:

1.0

Author:

Boleslav Bobcik <bbobcik@gmail.com>

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected static Map<TimeUnit,String>	LABEL_BY_UNIT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SimpleDurationFormat() The default constructor has protected visibility

Method Summary

Modifier and Type	Method and Description
static SimpleDurationFormat	getInstance() Obtains an instance of SimpleDurationFormat for the default locale.
static SimpleDurationFormat	getInstance(Locale locale) Obtains an instance of SimpleDurationFormat for the provided locale.
static SimpleDurationFormat	getLanguageNeutralInstance() Obtains an instance of SimpleDurationFormat for the "undefined" locale, specified in JDK by an "und" language tag.
String	toHumanDuration(long millis) Returns the duration specified in milliseconds in the appropriate human-readable representation.
abstract Appendable	toHumanDuration(long millis, Appendable target) Translates the duration specified in milliseconds to the appropriate human-readable representation and appends it to the target.
String	toHumanDuration(long duration, TimeUnit unit) Returns the duration specified in milliseconds in the appropriate human-readable representation.
Appendable	toHumanDuration(long duration, TimeUnit unit, Appendable target) Translates the duration specified in an arbitrary time unit to the appropriate human-readable representation and appends it to the target.
abstract Appendable	toHumanDurationSafe(long millis, Appendable target) Translates the duration specified in milliseconds to the appropriate human-readable representation and appends it to the target.
Appendable	toHumanDurationSafe(long duration, TimeUnit unit, Appendable target) Translates the duration specified in an arbitrary time unit to the appropriate human-readable representation and appends it to the target.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LABEL_BY_UNIT

protected static final Map<TimeUnit,String> LABEL_BY_UNIT

Constructor Detail

SimpleDurationFormat

protected SimpleDurationFormat()

The default constructor has protected visibility

Method Detail

getInstance

public static SimpleDurationFormat getInstance()

Obtains an instance of SimpleDurationFormat for the default locale.

Returns:

instance for default locale

See Also:

Locale.getDefault()

getLanguageNeutralInstance

public static SimpleDurationFormat getLanguageNeutralInstance()

Obtains an instance of SimpleDurationFormat for the "undefined" locale, specified in JDK by an "und" language tag.

Returns:

instance for the neutral locale

See Also:

Locale.forLanguageTag(String)

getInstance

public static SimpleDurationFormat getInstance(Locale locale)

Obtains an instance of SimpleDurationFormat for the provided locale. If no localization data for the given locale are found, the normal fall-back mechanism of ResourceBundle is applied.

Parameters:

locale - the locale

Returns:

instance for the requested locale

Throws:

NullPointerException - if locale is null

toHumanDuration

public abstract Appendable toHumanDuration(long millis,
                                           Appendable target)
                                    throws IOException

Translates the duration specified in milliseconds to the appropriate human-readable representation and appends it to the target.

If the checked IOException is deemed unnecessary (e.g. while appending to a StringBuilder), the sibling method toHumanDurationSafe(long, Appendable) may be more appropriate.

Parameters:

millis - duration given in milliseconds

target - object to which the formatted duration is appended

Returns:

the provided target reference

Throws:

NullPointerException - if target is null

IllegalArgumentException - if millis is negative

IOException - if appending to the target caused an error

toHumanDurationSafe

public abstract Appendable toHumanDurationSafe(long millis,
                                               Appendable target)

Translates the duration specified in milliseconds to the appropriate human-readable representation and appends it to the target.

This method differs from toHumanDuration(long, Appendable) in that the potential IOException is suppressed (and omitted from method signature).

Parameters:

millis - duration given in milliseconds

target - object to which the formatted duration is appended

Returns:

the provided target reference

Throws:

NullPointerException - if target is null

IllegalArgumentException - if millis is negative

toHumanDuration

public final String toHumanDuration(long millis)

Returns the duration specified in milliseconds in the appropriate human-readable representation.

Parameters:

millis - duration given in milliseconds

Returns:

human-readable representation of the duration

Throws:

IllegalArgumentException - if millis is negative

toHumanDuration

public final Appendable toHumanDuration(long duration,
                                        TimeUnit unit,
                                        Appendable target)
                                 throws IOException

Translates the duration specified in an arbitrary time unit to the appropriate human-readable representation and appends it to the target.

If the checked IOException is deemed unnecessary (e.g. while appending to a StringBuilder), the sibling method toHumanDurationSafe(long, java.util.concurrent.TimeUnit, Appendable) may be more appropriate.

Parameters:

duration - duration given in unit time unit

unit - time unit

target - object to which the formatted duration is appended

Returns:

the provided target reference

Throws:

NullPointerException - if unit or target is null

IllegalArgumentException - if duration is negative

IOException - if appending to the target caused an error

toHumanDurationSafe

public final Appendable toHumanDurationSafe(long duration,
                                            TimeUnit unit,
                                            Appendable target)

Translates the duration specified in an arbitrary time unit to the appropriate human-readable representation and appends it to the target.

This method differs from toHumanDuration(long, java.util.concurrent.TimeUnit, Appendable) in that the potential IOException is suppressed (and omitted from method signature).

Parameters:

duration - duration given in unit time unit

unit - time unit

target - object to which the formatted duration is appended

Returns:

the provided target reference

Throws:

NullPointerException - if unit or target is null

IllegalArgumentException - if duration is negative

toHumanDuration

public final String toHumanDuration(long duration,
                                    TimeUnit unit)

Returns the duration specified in milliseconds in the appropriate human-readable representation.

Parameters:

duration - duration given in unit time unit

unit - time unit

Returns:

human-readable representation of the duration

Throws:

IllegalArgumentException - if duration is negative