Package com.almworks.jira.structure.api.attribute

Class ValueFormat<T>

Object
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 side by Structure extensions. Only the 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 Details

    • 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 Details

    • 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 Details

    • 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:

    • 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