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:

CoreItemTypes, CoreIdentities, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ItemIdentity.LongIdentity Represents long-based ID.
static class	ItemIdentity.StringIdentity Represents string-based ID.

Field Summary

Fields

Modifier and Type	Field and Description
static ItemIdentity	ITEM_ZERO Represents non-existing item.

Method Summary

Modifier and Type	Method and Description
String	getItemType() Returns item type.
long	getLongId() Gets the long ID from a long-based ItemIdentity.
String	getStringId() Gets the string ID from a string-based ItemIdentity.
boolean	isLongId() Returns true if this ID is long-based.
boolean	isStringId() Returns true if this ID is string-based.
static ItemIdentity	longId(String itemType, long longId) Creates a new long-based ID.
static ItemIdentity	parse(String id) Parses canonical string representation of the item ID, which can be retrieved with toString() method.
static ItemIdentity	stringId(String itemType, String stringId) Creates a new string-based ID.
abstract String	toSimplifiedString()

Methods inherited from class Object

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

Field Detail

ITEM_ZERO

public static final ItemIdentity ITEM_ZERO

Represents non-existing item.

Method Detail

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()