com.almworks.jira.structure.api.attribute

Class ValueFormat<T>

java.lang.Object

com.almworks.jira.structure.api.attribute.ValueFormat<T>

Type Parameters:

T - value type

@PublicApi
public final class ValueFormat<T>
extends Object

ValueFormat is used as a part of AttributeSpec to define in what format the value should be returned.

There are a number of "well-known" formats, defined in this class. However, custom formats can be created and used on the server by Structure extensions. Only standard formats can be sent over via REST API.

It is important to note the difference between value format and value type. The format defines value type but also the semantics of the value. For example, both HTML and TEXT formats provide String values, but HTML values can actually be rendered as-is on a web page (without HTML escaping) and they are unsuitable to be shown to the user as plain text.

Different value types must have different IDs. When creating a new value type, it's recommended to have your package prefix as a part of the value type ID.

Field Summary

Fields

Modifier and Type	Field and Description
static ValueFormat<Object>	ANY ANY format is suitable when the requesting code can accept object of any type and there's no knowledge at development time what format of the attribute is going to be available.
static ValueFormat<Boolean>	BOOLEAN BOOLEAN value contains simple boolean value.
static ValueFormat<Long>	DURATION DURATION format contain the number of milliseconds between two points in time.
static ValueFormat<String>	HTML HTML values can be shown on a web page.
static ValueFormat<String>	ID ID is a special format for values that represent entities.
static ValueFormat<List>	JSON_ARRAY JSON_ARRAY values are Java lists, ready to be converted to a JSON array.
static ValueFormat<Map>	JSON_OBJECT JSON_OBJECT values are Java maps, ready to be converted to a JSON object.
static ValueFormat<Number>	NUMBER NUMBER values are numeric and usually are either Long or Double.
static ValueFormat<Comparable>	ORDER ORDER values are special values that can be used to sort by this attributes.
static ValueFormat<String>	TEXT TEXT values are plain text.
static ValueFormat<Long>	TIME TIME values contain Epoch time in milliseconds.

Constructor Summary

Constructors

Constructor and Description
ValueFormat(String formatId, Class<T> valueClass) Creates a new value format.

Method Summary

Modifier and Type	Method and Description
AttributeSpec<T>	cast(AttributeSpec<?> spec) Performs type checking and cast of an arbitrary attribute specification to the given format.
AttributeValue<T>	cast(AttributeValue<?> value) Performs type checking and cast of an arbitrary value to the given Java type.
boolean	equals(Object o)
String	getFormatId() Returns the unique ID of the value format.
static ValueFormat<?>	getStandardFormat(String formatId) Returns a standard format (declared in this class) given its format ID.
Class<T>	getValueClass() Returns the Java class of the values in this format.
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

HTML

public static final ValueFormat<String> HTML

HTML values can be shown on a web page. Most attributes can provide HTML values.

TEXT

public static final ValueFormat<String> TEXT

TEXT values are plain text. If shown on a web page, they must be HTML-escaped.

ID

public static final ValueFormat<String> ID

ID is a special format for values that represent entities. Some attributes may provide ID format in case the client needs only the ID of the value. If the ID is numeric, it is converted to String.

NUMBER

public static final ValueFormat<Number> NUMBER

NUMBER values are numeric and usually are either Long or Double. When interpreting NUMBER values, try to avoid casts and use Number.longValue() and Number.doubleValue() instead.

BOOLEAN

public static final ValueFormat<Boolean> BOOLEAN

BOOLEAN value contains simple boolean value.

TIME

public static final ValueFormat<Long> TIME

TIME values contain Epoch time in milliseconds.

DURATION

public static final ValueFormat<Long> DURATION

DURATION format contain the number of milliseconds between two points in time.

JSON_OBJECT

public static final ValueFormat<Map> JSON_OBJECT

JSON_OBJECT values are Java maps, ready to be converted to a JSON object. The maps must contain only String keys and only JSON-compatible values: numbers, strings, booleans, maps or lists.

JSON_ARRAY

public static final ValueFormat<List> JSON_ARRAY

JSON_ARRAY values are Java lists, ready to be converted to a JSON array. The lists must contain only JSON-compatible values: numbers, strings, booleans, maps or lists.

ANY

public static final ValueFormat<Object> ANY

ANY format is suitable when the requesting code can accept object of any type and there's no knowledge at development time what format of the attribute is going to be available. This format is used for nested attribute specs that can provide results of any format. The Java type may be any class.

ORDER

public static final ValueFormat<Comparable> ORDER

ORDER values are special values that can be used to sort by this attributes. The Java type of the value may be any class, as long as a) they are Comparable, and b) the ORDER values for the same item type will be the same Java type.

Values are compared using TotalOrder or ComparableTuple.

Constructor Detail

ValueFormat

public ValueFormat(@NotNull
                   String formatId,
                   @NotNull
                   Class<T> valueClass)

Creates a new value format.

Parameters:

formatId - unique format ID (use your package prefix to guarantee uniqueness). Must not contain colon (":") or be unreasonably long.

valueClass - Java type of the values

Method Detail

getFormatId

@NotNull
public String getFormatId()

Returns the unique ID of the value format.

getValueClass

@NotNull
public Class<T> getValueClass()

Returns the Java class of the values in this format.

cast

@NotNull
public AttributeSpec<T> cast(@NotNull
                                       AttributeSpec<?> spec)

Performs type checking and cast of an arbitrary attribute specification to the given format. This method should be used only to cast AttributeSpec type parameter to the desired format. It does not convert AttributeSpec, so if the format is different, an exception will be thrown.

Parameters:

spec - attribute spec with unknown type

Returns:

attribute spec with type T

Throws:

ClassCastException - in case attribute specification is of different format

See Also:

AttributeSpec.as(ValueFormat)

cast

@NotNull
public AttributeValue<T> cast(@NotNull
                                        AttributeValue<?> value)

Performs type checking and cast of an arbitrary value to the given Java type.

Note that AttributeValue does not bear information about the format that was used to produce it, so the only check made is that the value matches the type. So it's possible to cast a value that was received as TEXT format as a HTML value. Be careful!

Parameters:

value - a value of unknown type

Returns:

a value of type T

Throws:

ClassCastException - if the value is not null and of different type

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

getStandardFormat

@Nullable
public static ValueFormat<?> getStandardFormat(String formatId)

Returns a standard format (declared in this class) given its format ID.

Parameters:

formatId - format ID

Returns:

the standard format or null if there's no such standard format