com.atlassian.jira.issue.customfields
Interface CustomFieldType

All Known Subinterfaces:
MultipleCustomFieldType, MultipleSettableCustomFieldType
All Known Implementing Classes:
AbstractCustomFieldType, AbstractMultiCFType, AbstractMultiSettableCFType, AbstractSingleFieldType, CalculatedCFType, CascadingSelectCFType, DateCFType, DateTimeCFType, ImportIdLinkCFType, MultiGroupCFType, MultiSelectCFType, MultiUserCFType, NumberCFType, ProjectCFType, ReadOnlyCFType, RenderableTextCFType, SelectCFType, StringCFType, TextAreaCFType, TextCFType, URLCFType, UserCFType, VersionCFType

public interface CustomFieldType

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, java.lang.Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object)) 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(java.lang.Object)) 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 (See CascadingSelectCFType for example)

Since:
JIRA 3.0
See Also:
CustomField, CustomFieldParams

Field Summary
static String DEFAULT_VALUE_TYPE
           
 
Method Summary
 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, Object value)
           
 String getChangelogString(CustomField field, Object 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, Object value)
          Returns a values to be stored in the change log, example is the id of the changed item.
 List getConfigurationItemTypes()
          Returns a List of FieldConfigItemType objects.
 Object 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()
           
 List<FieldIndexer> getRelatedIndexers(CustomField customField)
          Returns a list of indexers that will be used for the field.
 Object getSingularObjectFromString(String string)
          Returns a Singular Object, given the string value as passed by the presentation tier.
 String getStringFromSingularObject(Object singularObject)
          Returns the String representation of a single value within the CustomFieldType.
 Object getStringValueFromCustomFieldParams(CustomFieldParams parameters)
          Return the String value object from the CustomFieldParams.
 Object getValueFromCustomFieldParams(CustomFieldParams parameters)
          Retrieves the Object representing the CustomField value instance from the CustomFieldParams of Strings.
 Object getValueFromIssue(CustomField field, Issue issue)
          Retrieves the 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.
 Set<Long> remove(CustomField field)
          Performs additional tasks when a CustomField of this type is being removed CustomField.remove().
 void setDefaultValue(FieldConfig fieldConfig, Object value)
          Sets the default value for a Custom Field
 void updateValue(CustomField field, Issue issue, Object value)
           
 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(Object v1, Object 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
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(Object singularObject)
Returns the String representation of a single value within the CustomFieldType. This is the value that will 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 CustomFieldParams

Parameters:
singularObject - the object
Returns:
String representation of the Object

getSingularObjectFromString

Object 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 a 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 erros should be added (never null)
config - FieldConfig

createValue

void createValue(CustomField field,
                 Issue issue,
                 Object value)

updateValue

void updateValue(CustomField field,
                 Issue issue,
                 Object value)

getValueFromCustomFieldParams

Object getValueFromCustomFieldParams(CustomFieldParams parameters)
                                     throws FieldValidationException
Retrieves the Object representing the CustomField value instance from the CustomFieldParams of Strings. This return type must exactly match that of the value Object parameter in the persistance methods (createValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object)) and Object returned from getValueFromIssue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue).

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, java.lang.Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object)
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, java.lang.Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.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)

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

getValueFromIssue

Object getValueFromIssue(CustomField field,
                         Issue issue)
Retrieves the Object representing the current CustomField value for the given issue. See getValueFromCustomFieldParams(com.atlassian.jira.issue.customfields.view.CustomFieldParams) for more detailed notes.

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, java.lang.Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object)
See Also:
getValueFromCustomFieldParams(com.atlassian.jira.issue.customfields.view.CustomFieldParams)

getDefaultValue

Object getDefaultValue(FieldConfig fieldConfig)
Retrieves the Object representing the default CustomField value for the Custom Field. See getValueFromCustomFieldParams(com.atlassian.jira.issue.customfields.view.CustomFieldParams) for more detailed notes.

Parameters:
fieldConfig - CustomField for default value
Returns:
Transport Object matching the Object parameter of createValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object), updateValue(com.atlassian.jira.issue.fields.CustomField, com.atlassian.jira.issue.Issue, java.lang.Object)

setDefaultValue

void setDefaultValue(FieldConfig fieldConfig,
                     Object 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

String getChangelogValue(CustomField field,
                         Object 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 Implementions can return null. This should only occur when no change log is desired

getChangelogString

String getChangelogString(CustomField field,
                          Object 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 Implementions can return null. This should only occur when no change log is desired or when the value returned from the getChangelogValue method is an acurate representation of the data's value.

getVelocityParameters

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

List getConfigurationItemTypes()
Returns a List of FieldConfigItemType objects. This opens up possibilties for configurable custom fields

Returns:
List of FieldConfigItemType

getRelatedIndexers

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(Object v1,
                    Object 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 teh change item should be generated, false otherwise

availableForBulkEdit

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


Copyright © 2002-2009 Atlassian. All Rights Reserved.