@PublicApi @PublicSpi public interface

CustomFieldType

com.atlassian.jira.issue.customfields.CustomFieldType<T, S>
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

@PublicSpi

This interface is designed for plugins to implement.

Clients of @PublicSpi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicSpi as per each product's API policy (clients should refer to each product's API policy for the exact guarantee -- usually binary compatibility is guaranteed at least across minor versions).

Note: @PublicSpi interfaces and classes are specifically designed to be implemented/extended by clients. Hence, the guarantee of binary compatibility is different to that of @PublicApi elements (if an element is both @PublicApi and @PublicSpi, both guarantees apply).

Class Overview

This interface represents a particular type of CustomField. It encapsulates all logic dealing with values of a Custom Field, such as creation, update and removal of values, storage & retrieval of defaults and validation of values.

A value instance of a custom field is represented as an Object, from hereon in referred to as a Transport Object. These may be of singular types (eg. Number, String) or Multi-Dimensional (eg. Collection of Strings, Map of Date Objects, CustomFieldParams of Option). Most methods in the interface expect/returns Transfer Objects (e.g. Persistence Methods (createValue(CustomField, Issue, T), updateValue(CustomField, Issue, T)) and Transfer Object Getters getValueFromIssue(CustomField, Issue) and getValueFromCustomFieldParams(CustomFieldParams).

However, two special conversion methods (getSingularObjectFromString(String) & getStringFromSingularObject(S)) act on the Singular Object level. Thus, even when the Transfer Object type is a Collection of Number, getSingularObjectFromString would still return a single Number object.

Implementing classes should clearly document the exact structure of the Transport Object in the Class javadoc header. If the Transport Object is Multi-Dimensional, the type of the Singular Object should also be specified. This is especially relevant for complex custom field types (CascadingSelectCFType for example)

See Also

Summary

Constants
String DEFAULT_VALUE_TYPE
String RESOURCE_PREVIEW Name of the resource that can be used as a preview for the CustomField when rendering in the UI.
Public Methods
@Nullable String availableForBulkEdit(BulkEditBean bulkEditBean)
Allow the custom field type perform a specific check as to its availability for bulk editing.
void createValue(CustomField field, Issue issue, T value)
Save the value for this Custom Field in a particular issue to the database.
@Nullable String getChangelogString(CustomField field, T value)
Returns a String of representing values to be stored in the change log, an example is the name of a version field that a version id will resolve to within JIRA.
@Nullable String getChangelogValue(CustomField field, T value)
Returns a values to be stored in the change log, example is the id of the changed item.
@Nonnull List<FieldConfigItemType> getConfigurationItemTypes()
Returns a List of FieldConfigItemType objects.
T getDefaultValue(FieldConfig fieldConfig)
Retrieves the Object representing the default CustomField value for the Custom Field.
String getDescription()
CustomFieldTypeModuleDescriptor getDescriptor()
String getKey()
Returns the full key of the CustomFieldType.
String getName()
@Nullable List<FieldIndexer> getRelatedIndexers(CustomField customField)
Returns a list of indexers that will be used for the field.
S getSingularObjectFromString(String string)
Returns a Singular Object, given the string value as passed by the presentation tier.
String getStringFromSingularObject(S singularObject)
Returns the String representation of a single value within the CustomFieldType.
Object getStringValueFromCustomFieldParams(CustomFieldParams parameters)
Return the String value object from the CustomFieldParams.
T getValueFromCustomFieldParams(CustomFieldParams parameters)
Retrieves the Transport Object representing the CustomField value instance from the CustomFieldParams of Strings.
@Nullable T getValueFromIssue(CustomField field, Issue issue)
Retrieves the Transport Object representing the current CustomField value for the given issue.
@Nonnull Map<String, Object> getVelocityParameters(Issue issue, CustomField field, FieldLayoutItem fieldLayoutItem)
The custom field may wish to pass parameters to the velocity context beyond the getValueFromIssue methods (eg managers).
void init(CustomFieldTypeModuleDescriptor customFieldTypeModuleDescriptor)
Initialises the CustomFieldType with the given descriptor.
boolean isRenderable()
This is a mirror of the method from the RenderableField interface and is needed to bridge the gap between CustomFields and CustomFieldTypes.
Set<Long> remove(CustomField field)
Performs additional tasks when an entire CustomField of this type is being removed remove().
void setDefaultValue(FieldConfig fieldConfig, T value)
Sets the default value for a Custom Field
void updateValue(CustomField field, Issue issue, T value)
Update the value for this Custom Field in a particular issue currently stored in the database.
void validateFromParams(CustomFieldParams relevantParams, ErrorCollection errorCollectionToAddTo, FieldConfig config)
Ensures that the CustomFieldParams of Strings is a valid representation of the Custom Field values.
boolean valuesEqual(T v1, T v2)
Used to compare 2 field values and work out whether a change item should be generated

Constants

public static final String DEFAULT_VALUE_TYPE

Constant Value: "DefaultValue"

public static final String RESOURCE_PREVIEW

Name of the resource that can be used as a preview for the CustomField when rendering in the UI.

Constant Value: "customfieldpreview.png"

Public Methods

@Nullable public String availableForBulkEdit (BulkEditBean bulkEditBean)

Allow the custom field type perform a specific check as to its availability for bulk editing.

Parameters
bulkEditBean BulkEditBean
Returns
  • null if available for bulk edit or appropriate unavailable message

public void createValue (CustomField field, Issue issue, T value)

Save the value for this Custom Field in a particular issue to the database.

Parameters
field CustomField for which the value is being stored
issue The Issue to be stored against.
value Transport Object representing the value instance of the CustomField. Can not be null.

@Nullable public String getChangelogString (CustomField field, T value)

Returns a String of representing values to be stored in the change log, an example is the name of a version field that a version id will resolve to within JIRA.

Parameters
field CustomField that the value belongs to
value Transport Object representing the value instance of the CustomField
Returns
  • Change log string.

@Nullable public String getChangelogValue (CustomField field, T value)

Returns a values to be stored in the change log, example is the id of the changed item.

Parameters
field CustomField that the value belongs to
value Transport Object representing the value instance of the CustomField
Returns
  • Change log value.

@Nonnull public List<FieldConfigItemType> getConfigurationItemTypes ()

Returns a List of FieldConfigItemType objects. Can not be immutable. This opens up possibilities for configurable custom fields.

Returns

public T getDefaultValue (FieldConfig fieldConfig)

Retrieves the Object representing the default CustomField value for the Custom Field.

Parameters
fieldConfig CustomField for default value
Returns
  • Transport Object of the Default Value

public String getDescription ()

public CustomFieldTypeModuleDescriptor getDescriptor ()

public String getKey ()

Returns the full key of the CustomFieldType. Typically, this will be prefixed with "com.atlassian.jira.plugin.system.customfieldtypes:"

Returns
  • CustomFieldType Key prefixed with the Package

public String getName ()

@Nullable public List<FieldIndexer> getRelatedIndexers (CustomField customField)

Returns a list of indexers that will be used for the field.

Parameters
customField the custom field to get the related indexers of.
Returns
  • List of instantiated and initialised FieldIndexer objects. Null if no related indexers.

public S getSingularObjectFromString (String string)

Returns a Singular Object, given the string value as passed by the presentation tier. Throws FieldValidationException if the string is an invalid representation of the Object.

Parameters
string the String
Returns
  • singularObject instance
Throws
FieldValidationException if the string is an invalid representation of the Object.

public String getStringFromSingularObject (S singularObject)

Returns the String representation of a single value within the CustomFieldType. This is the value that is passed to the presentation tier for editing. For single CustomFieldTypes the Singular Object is the same as a Transport Object. However, for multi-dimensional CustomFieldTypes, the Singular Object is the Object contained within the Collection or Map

Parameters
singularObject the object
Returns
  • String representation of the Object

public Object getStringValueFromCustomFieldParams (CustomFieldParams parameters)

Return the String value object from the CustomFieldParams. The object may be a single String (e.g. TextCFType, List of Strings (e.g. MultiSelectCFType) or CustomFieldParams of Strings (e.g. CascadingSelectCFType). Among other things these values are passed to Velocity for rendering edit screens.

Parameters
parameters - CustomFieldParams containing String values
Returns
  • String value object from the CustomFieldParams

public T getValueFromCustomFieldParams (CustomFieldParams parameters)

Retrieves the Transport Object representing the CustomField value instance from the CustomFieldParams of Strings.

Parameters
parameters CustomFieldParams of String objects. Will contain one value for Singular field types.
Returns
Throws
FieldValidationException if the String value fails to convert into Objects
See Also

@Nullable public T getValueFromIssue (CustomField field, Issue issue)

Retrieves the Transport Object representing the current CustomField value for the given issue.

Parameters
field Custom field for which to retrieve the value
issue Issue from which to retrieve the value
Returns

@Nonnull public Map<String, Object> getVelocityParameters (Issue issue, CustomField field, FieldLayoutItem fieldLayoutItem)

The custom field may wish to pass parameters to the velocity context beyond the getValueFromIssue methods (eg managers).

The values are added to the context for all velocity views (edit, search, view, xml)

Parameters
issue The issue currently in context (Note: this will be null in cases like 'default value')
field CustomField
fieldLayoutItem FieldLayoutItem
Returns
  • A Map of parameters to add to the velocity context, or an empty Map otherwise (never null)

public void init (CustomFieldTypeModuleDescriptor customFieldTypeModuleDescriptor)

Initialises the CustomFieldType with the given descriptor.

Parameters
customFieldTypeModuleDescriptor CustomFieldTypeModuleDescriptor

public boolean isRenderable ()

This is a mirror of the method from the RenderableField interface and is needed to bridge the gap between CustomFields and CustomFieldTypes.

Returns
  • true if the field is configurable for use with the renderers, a text based field, false otherwise.

public Set<Long> remove (CustomField field)

Performs additional tasks when an entire CustomField of this type is being removed remove(). This includes removal of values & options.

Parameters
field The custom field that is being removed, so any data stored for any issues for that field can be deleted.
Returns
  • Set of issue ids that has been affected

public void setDefaultValue (FieldConfig fieldConfig, T value)

Sets the default value for a Custom Field

Parameters
fieldConfig CustomField for which the default is being stored
value Transport Object representing the value instance of the CustomField

public void updateValue (CustomField field, Issue issue, T value)

Update the value for this Custom Field in a particular issue currently stored in the database.

Parameters
field CustomField for which the value is being stored
issue The Issue to be stored against.
value Transport Object representing the value instance of the CustomField.

public void validateFromParams (CustomFieldParams relevantParams, ErrorCollection errorCollectionToAddTo, FieldConfig config)

Ensures that the CustomFieldParams of Strings is a valid representation of the Custom Field values. Any errors should be added to the ErrorCollection under the appropriate key as required.

Parameters
relevantParams parameter object of Strings
errorCollectionToAddTo errorCollection to which any erros should be added (never null)
config FieldConfig

public boolean valuesEqual (T v1, T v2)

Used to compare 2 field values and work out whether a change item should be generated

Parameters
v1 current value
v2 new value
Returns
  • true if the change item should be generated, false otherwise