Package com.almworks.jira.structure.api.item

Class ItemIdentity

Object
ItemIdentity
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ItemIdentity.LongIdentity, ItemIdentity.StringIdentity
@PublicApi @Immutable public abstract class ItemIdentity extends Object implements Serializable

ItemIdentity represents an item, a core concept in Structure's architecture.

An item is an abstract notion that generalizes everything that can be put into a structure. Issues, projects, users and other JIRA objects — all can be represented as items. Structures themselves may be represented as items. Structure can be extended and new types of items can be added to it — for example, Structure.Pages extension adds "Confluence page" item type.

Because of such diversity, there's no single class that represents an item in the low-level API. Instead, there's ItemIdentity which represents the only single property that each item must have — its unique ID.

Anatomy of the item ID

Each ItemIdentity is a pair of item type and item id within that type.

Item type is nothing else but the complete module key of the <structure-item-type> module, which supports this item type. Main item types are listed in CoreItemTypes.

The actual item ID can be either long or String. Numeric item IDs are used whenever possible, as that allows Structure to save consumed memory and speed up calculations. Issues, Folders, Projects, Sprints and most other items are identified with long ID.

Text item IDs are used in other cases. For example, Users and Special Folders are represented with String IDs.

Item type does not prescribe whether IDs are long or string based. For one type there might be issues with long IDs and string IDs.

Uniqueness

It is important to remember that an item ID is unique only within a single instance of JIRA (or within a single cluster running JIRA Data Center). It is not globally unique. So when synchronizing multiple JIRAs or when restoring Structure data on another instance, all items must be mapped to the new instance.

Value Range

  • Both item type and string ID must not be null or empty and must not exceed 190 characters.
  • There are no limit on the value of long ID, it can be 0.

Canonical notation

ItemIdentity can be serialized into a String by calling toString() on it. The serialized form is either:

  • <itemType>/<itemID> for long-based identities, for example: com.almworks.jira.structure:type-issue/10000
  • <itemType>//<itemID> for string-based identities, for example: com.almworks.jira.structure:type-user//admin
See Also:

  • Field Details

    • ITEM_ZERO

      public static final ItemIdentity ITEM_ZERO
      Represents non-existing item.

  • Method Details

    • getItemType

      @NotNull public String getItemType()
      Returns item type.

    • isStringId

      public boolean isStringId()
      Returns true if this ID is string-based.

    • getStringId

      @NotNull public String getStringId()
      Gets the string ID from a string-based ItemIdentity.
      Returns:
      string ID, not null, not empty
      Throws:
      UnsupportedOperationException - if this is not a string-based ID

    • isLongId

      public boolean isLongId()
      Returns true if this ID is long-based.

    • getLongId

      public long getLongId()
      Gets the long ID from a long-based ItemIdentity.
      Returns:
      long ID, not 0
      Throws:
      UnsupportedOperationException - if this is not a long-based ID

    • stringId

      @NotNull public static ItemIdentity stringId(@NotNull String itemType, @NotNull String stringId)
      Creates a new string-based ID.
      Parameters:
      itemType - item type
      stringId - item ID
      Returns:
      identity
      Throws:
      IllegalArgumentException - if the parameters are invalid

    • longId

      @NotNull public static ItemIdentity longId(@NotNull String itemType, long longId)
      Creates a new long-based ID.
      Parameters:
      itemType - item type
      longId - item ID
      Returns:
      identity
      Throws:
      IllegalArgumentException - if the parameters are invalid

    • parse

      @NotNull public static ItemIdentity parse(@Nullable String id) throws ParseException
      Parses canonical string representation of the item ID, which can be retrieved with toString() method.
      Parameters:
      id - string representation of the item ID.
      Returns:
      identity
      Throws:
      ParseException - if there were errors parsing the string or if the parsed parameters were invalids

    • toSimplifiedString

      public abstract String toSimplifiedString()