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.@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)
CustomField
,
CustomFieldParams
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.
|
Modifier and Type | Method and Description |
---|---|
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
|
static final String DEFAULT_VALUE_TYPE
static final String RESOURCE_PREVIEW
void init(CustomFieldTypeModuleDescriptor customFieldTypeModuleDescriptor)
customFieldTypeModuleDescriptor
- CustomFieldTypeModuleDescriptorString getKey()
String getName()
String getDescription()
CustomFieldTypeModuleDescriptor getDescriptor()
String getStringFromSingularObject(S singularObject)
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
singularObject
- the objectS getSingularObjectFromString(String string) throws FieldValidationException
string
- the StringFieldValidationException
- if the string is an invalid representation of the Object.Set<Long> remove(CustomField field)
CustomField.remove()
.
This includes removal of values & options.field
- The custom field that is being removed, so any data stored for
any issues for that field can be deleted.Set
of issue ids that has been affectedvoid validateFromParams(CustomFieldParams relevantParams, ErrorCollection errorCollectionToAddTo, FieldConfig config)
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.relevantParams
- parameter object of StringserrorCollectionToAddTo
- errorCollection to which any errors should be added (never null)config
- FieldConfigvoid createValue(CustomField field, Issue issue, @Nonnull T value)
field
- CustomField
for which the value is being storedissue
- The Issue
to be stored against.value
- Transport Object representing the value instance of the CustomField.
Can not be null
.void updateValue(CustomField field, Issue issue, T value)
field
- CustomField
for which the value is being storedissue
- The Issue
to be stored against.value
- Transport Object representing the value instance of the CustomField.T getValueFromCustomFieldParams(CustomFieldParams parameters) throws FieldValidationException
parameters
- CustomFieldParams of String objects. Will contain one value for Singular field types.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)
FieldValidationException
- if the String value fails to convert into ObjectscreateValue(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)
Object getStringValueFromCustomFieldParams(CustomFieldParams parameters)
parameters
- - CustomFieldParams containing String values@Nullable T getValueFromIssue(CustomField field, Issue issue)
field
- Custom field for which to retrieve the valueissue
- Issue from which to retrieve the valuecreateValue(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)
T getDefaultValue(FieldConfig fieldConfig)
fieldConfig
- CustomField for default valuevoid setDefaultValue(FieldConfig fieldConfig, T value)
fieldConfig
- CustomField for which the default is being storedvalue
- Transport Object representing the value instance of the CustomField@Nullable String getChangelogValue(CustomField field, T value)
field
- CustomField that the value belongs tovalue
- Transport Object representing the value instance of the CustomFieldnull
. This should only occur when no change log is desired.@Nullable String getChangelogString(CustomField field, T value)
field
- CustomField that the value belongs tovalue
- Transport Object representing the value instance of the CustomFieldnull
. 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.@Nonnull Map<String,Object> getVelocityParameters(Issue issue, CustomField field, FieldLayoutItem fieldLayoutItem)
The values are added to the context for all velocity views (edit, search, view, xml)
issue
- The issue currently in context (Note: this will be null in cases like 'default value')field
- CustomFieldfieldLayoutItem
- FieldLayoutItemMap
of parameters to add to the velocity context, or an empty Map otherwise (never null)@Nonnull List<FieldConfigItemType> getConfigurationItemTypes()
FieldConfigItemType
objects. Can not be immutable.
This opens up possibilities for configurable custom fields.FieldConfigItemType
@Nullable List<FieldIndexer> getRelatedIndexers(CustomField customField)
customField
- the custom field to get the related indexers of.FieldIndexer
objects. Null if no related indexers.boolean isRenderable()
boolean valuesEqual(T v1, T v2)
v1
- current valuev2
- new value@Nullable String availableForBulkEdit(BulkEditBean bulkEditBean)
bulkEditBean
- BulkEditBean@Nonnull default CloneOptionConfiguration getCloneOptionConfiguration(CustomField field, Issue issueToClone)
field
- Custom field whose clone behaviour is being configuredissueToClone
- Issue to clone@Nullable default T getCloneValue(CustomField field, Issue issueToClone, Optional<Boolean> cloneOptionSelection)
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
.
field
- Custom field being clonedissueToClone
- Issue to clonecloneOptionSelection
- Indicates whether a clone option was displayed on the clone dialog and if so whether
it was selected.default boolean isUserInputRequiredForMove(CustomFieldParams relevantParams, FieldConfig config, Long targetProjectId, String targetIssueTypeId)
relevantParams
- parameter object of Stringsconfig
- FieldConfigtargetProjectId
- The target project id for the move operationtargetIssueTypeId
- The target issue type id for the move operation@Deprecated @ExperimentalApi default NonnullCustomFieldProvider getNonnullCustomFieldProvider()
getNonNullCustomFieldProvider()
NonNullCustomFieldProvider
that Jira will use to optimize indexing performance.@ExperimentalApi default NonNullCustomFieldProvider getNonNullCustomFieldProvider()
NonNullCustomFieldProvider
that Jira will use to optimize indexing performance.Copyright © 2002-2021 Atlassian. All Rights Reserved.