com.atlassian.jira.issue.customfields

Interface CustomFieldType<T,S>

Type Parameters:

T - Transport Object For a single Transport Objects this will be the same as S. Otherwise, the transport Object currently supports Collection<S>, Map<String,S> or Map<String, Collection<S>>. N.B. Support for CustomFieldParams as the Transport Object has been deprecated since 5.0.

S - Singular Form of the Transport object T.

All Known Subinterfaces:

MultipleCustomFieldType<T,S>, MultipleSettableCustomFieldType<T,S>

All Known Implementing Classes:

AbstractCustomFieldType, AbstractMultiCFType, AbstractMultiSettableCFType, AbstractSingleFieldType, CalculatedCFType, CascadingSelectCFType, DateCFType, DateTimeCFType, FuncTestTextAreaCFType, GenericTextCFType, ImportIdLinkCFType, InitialWatchersCFType, LabelsCFType, MockCustomFieldType, MultiGroupCFType, MultiSelectCFType, MultiUserCFType, NumberCFType, ProjectCFType, ReadOnlyCFType, RenderableTextCFType, SelectCFType, StringCFType, TextAreaCFType, TextAreaNoValidationCFType, TextCFType, URLCFType, UserCFType, VersionCFType

@PublicApi
 @PublicSpi
public interface CustomFieldType<T,S>

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(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, T), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, T)) and Transfer Object Getters getValueFromIssue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue) and getValueFromCustomFieldParams(com.atlassian.jira.issue.customfields.view.CustomFieldParams).

However, two special conversion methods (getSingularObjectFromString(java.lang.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)

Since:

JIRA 3.0

See Also:

CustomField, CustomFieldParams

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_VALUE_TYPE
static String	RESOURCE_PREVIEW Name of the resource that can be used as a preview for the CustomField when rendering in the UI.

Method Summary

Modifier and Type	Method and Description
default boolean	areAllRequiredParametersPresent(Map<String,Object> params, String customFieldId) This method validates if all the obligatory parameters of a given custom field type have been set when the custom field is set to be required.
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.
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.
String	getChangelogValue(CustomField field, T value) Returns a values to be stored in the change log, example is the id of the changed item.
default CloneOptionConfiguration	getCloneOptionConfiguration(CustomField field, Issue issueToClone) Get the clone option configuration for the given custom field in the context of the given issue.
default T	getCloneValue(CustomField field, Issue issueToClone, Optional<Boolean> cloneOptionSelection) Get the cloned value for the specified custom field when cloning the specified issue.
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()
default NonnullCustomFieldProvider	getNonnullCustomFieldProvider() Deprecated. since 8.12 use getNonNullCustomFieldProvider()
default NonNullCustomFieldProvider	getNonNullCustomFieldProvider() Returns an instance of NonNullCustomFieldProvider that Jira will use to optimize indexing performance.
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.
T	getValueFromIssue(CustomField field, Issue issue) Retrieves the Transport Object representing the current CustomField value for the given issue.
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.
default boolean	isUserInputRequiredForMove(CustomFieldParams relevantParams, FieldConfig config, Long targetProjectId, String targetIssueTypeId) Allow Custom Field Type to determine whether it needs user input during a move operation.
Set<Long>	remove(CustomField field) Performs additional tasks when an entire CustomField of this type is being removed CustomField.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

Field Detail

DEFAULT_VALUE_TYPE

static final String DEFAULT_VALUE_TYPE

See Also:

Constant Field Values

RESOURCE_PREVIEW

static final String RESOURCE_PREVIEW

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

See Also:

Constant Field Values

Method Detail

init

void init(CustomFieldTypeModuleDescriptor customFieldTypeModuleDescriptor)

Initialises the CustomFieldType with the given descriptor.

Parameters:

customFieldTypeModuleDescriptor - CustomFieldTypeModuleDescriptor

getKey

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

getName

String getName()

getDescription

String getDescription()

getDescriptor

CustomFieldTypeModuleDescriptor getDescriptor()

getStringFromSingularObject

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

getSingularObjectFromString

S getSingularObjectFromString(String string)
                       throws FieldValidationException

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.

remove

Set<Long> remove(CustomField field)

Performs additional tasks when an entire CustomField of this type is being removed CustomField.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

validateFromParams

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 errors should be added (never null)

config - FieldConfig

areAllRequiredParametersPresent

default boolean areAllRequiredParametersPresent(Map<String,Object> params,
                                                String customFieldId)

This method validates if all the obligatory parameters of a given custom field type have been set when the custom field is set to be required. In the general case, we are checking if a validated custom field is present in the parameters map and has the value assigned. Depending on the custom field type we may want to extend the validation for additional requirements. For e.g. "Select List (cascading)" requires to have set only the parent option if no children options are configured for the parent, and both parent and child options are to be set otherwise.

Parameters:

params - A map of parameters attached to an issue create/edit action.

customFieldId - An ID of a custom field which is being validated e.g. "customfield_10101".

Returns:

Returns true if parameters map contains customFieldId as key, and the CustomFieldParams value for the key is not null, false otherwise.

createValue

void createValue(CustomField field,
                 Issue issue,
                 @Nonnull
                 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.

updateValue

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.

getValueFromCustomFieldParams

T getValueFromCustomFieldParams(CustomFieldParams parameters)
                         throws FieldValidationException

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:

Transport Object matching the Object parameter of createValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, T), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, T)

Throws:

FieldValidationException - if the String value fails to convert into Objects

See Also:

createValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, Object), getValueFromIssue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue)

getStringValueFromCustomFieldParams

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

getValueFromIssue

@Nullable
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:

Transport Object matching the Object parameter of createValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, T), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, T)

getDefaultValue

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

setDefaultValue

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

getChangelogValue

@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.

Parameters:

field - CustomField that the value belongs to

value - Transport Object representing the value instance of the CustomField

Returns:

Change log value.

Since:

3.1 Implementations can return null. This should only occur when no change log is desired.

getChangelogString

@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.

Parameters:

field - CustomField that the value belongs to

value - Transport Object representing the value instance of the CustomField

Returns:

Change log string.

Since:

3.4 Implementations can return null. This should only occur when no change log is desired or when the value returned from the getChangelogValue method is an accurate representation of the data's value.

getVelocityParameters

@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).

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)

getConfigurationItemTypes

@Nonnull
List<FieldConfigItemType> getConfigurationItemTypes()

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

Returns:

List of FieldConfigItemType

getRelatedIndexers

@Nullable
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.

isRenderable

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.

valuesEqual

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

availableForBulkEdit

@Nullable
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

getCloneOptionConfiguration

@Nonnull
default CloneOptionConfiguration getCloneOptionConfiguration(CustomField field,
                                                                      Issue issueToClone)

Get the clone option configuration for the given custom field in the context of the given issue. A clone option configuration controls whether an option is displayed on the clone dialog allowing users to specify whether the field value should be cloned. Note by default, when no option is presented, the field value will be cloned.

Parameters:

field - Custom field whose clone behaviour is being configured

issueToClone - Issue to clone

Returns:

A clone option configuration for the given custom field in the context of the given issue.

Since:

7.2

getCloneValue

@Nullable
default T getCloneValue(CustomField field,
                                  Issue issueToClone,
                                  Optional<Boolean> cloneOptionSelection)

Get the cloned value for the specified custom field when cloning the specified issue. Note that while most implementations of CustomFieldType will interpret cloning as returning the same value, it is totally acceptable to return a different value, i.e. the interpretation of what it means to clone is left to each CustomFieldType implementation.

It is also possible to decide that cloning is not appropriate and that the cloned issue should not copy the value of the specified custom field. In this case, simply return null.

Parameters:

field - Custom field being cloned

issueToClone - Issue to clone

cloneOptionSelection - Indicates whether a clone option was displayed on the clone dialog and if so whether it was selected.

Returns:

The field value for the cloned issue, possibly null if the value should be left empty.

Since:

7.2

isUserInputRequiredForMove

default boolean isUserInputRequiredForMove(CustomFieldParams relevantParams,
                                           FieldConfig config,
                                           Long targetProjectId,
                                           String targetIssueTypeId)

Allow Custom Field Type to determine whether it needs user input during a move operation. The target project is provided as a parameter, to assist with this decision.

Parameters:

relevantParams - parameter object of Strings

config - FieldConfig

targetProjectId - The target project id for the move operation

targetIssueTypeId - The target issue type id for the move operation

Returns:

True if will require user input as part of move, and False otherwise

Since:

v7.3.0 with a default implementation that will always return false unless overridden

getNonnullCustomFieldProvider

@Deprecated
 @ExperimentalApi
default NonnullCustomFieldProvider getNonnullCustomFieldProvider()

Deprecated. since 8.12 use getNonNullCustomFieldProvider()

Returns an instance of NonNullCustomFieldProvider that Jira will use to optimize indexing performance.

Since:

8.10

getNonNullCustomFieldProvider

@ExperimentalApi
default NonNullCustomFieldProvider getNonNullCustomFieldProvider()

Returns an instance of NonNullCustomFieldProvider that Jira will use to optimize indexing performance.

Since:

8.12