Yes, it's not a great name. I wrote about it in detail in "Practical JIRA Plugins"
(O'Reilly). Here's an extract from there describing many of the methods in detail (sorry about the formatting). The book also has worked examples available at https://bitbucket.org/mdoar/practical-jira-plugins
CustomFieldType Methods
The example’s custom field type class will implement the CustomFieldType interface as usual, but instead will extend a class higher up in the inheritance hierarchy than NumberCFType. The class we will extend is AbstractCustomFieldType and it’s at the root of most classes that implement CustomFieldType.
The methods in the CustomFieldType interface with “SingularObject” in their name refer to the singular object, in this example a Carrier object. All other methods in JIRA 4 custom fields that refer to an Object are referring the transport object, e.g., a Collection of Carrier objects. JIRA 5 removed the use of Object in most custom field methods.
For more information about what changed in JIRA 5.0 with custom fields see https://developer.atlassian.com/display/JIRADEV/Java+API+Changes+in+JIRA+5.0#JavaAPIChangesinJIRA5.0-CustomFieldTypes. There were some major changes in the class hierarchy, and most classes now have a Java generic as a parameter instead of just using an Object as before.
There are two objects that are typically injected into the constructor of a custom field type’s class. The first is a CustomFieldValuePersister persister object, which is what will actually interact with the database. The second is a GenericConfigManager object that is used for storing and retrieving default values for the custom field. Other objects are injected into the constructor as needed—for example, the DoubleConverter in Example 2-2.
The first set of methods to consider are the ones that the custom field type uses to interact with the database in some way.
getSingularObjectFromString()
This method converts a string taken from the database such as “42.0###The answer” into a Carrier object. A null value means that there is no such object defined.
Fields with Multiple Values
Collection<Carrier> getValueFromIssue(CustomField field, Issue issue)
This is the main method for extracting what a field contains for a given issue. It uses the persister to retrieve the values from the database for the issue, converts each value into a Carrier object and then puts all the Carrier objects into a trans- port object Collection. A null value means that this field has no value stored for the given issue. This is one of the methods that used to return an Object before JIRA 5.0
createValue(CustomField field, Issue issue, Collection<Carrier> value)
updateValue(CustomField field, Issue issue, Collection<Carrier> value)
These methods create a new value or update an existing value for the field in the given issue. The persister that does this expects a Collection of Strings to store, so both of these methods call the method getDbValueFromCollection to help with that.
getDbValueFromCollection()
A private convenience method found in many custom field type classes, sometimes with a different name. It is used to convert a transport object (e.g., a Collection of Carrier objects) to a Collection of Strings for storing in the database.
setDefaultValue(FieldConfig fieldConfig, Collection<Carrier> value)
Convert a transport object (a Collection of Carrier objects) to its database repre- sentation and store it in the database in the genericconfiguration table.
Collection<Carrier> getDefaultValue(FieldConfig fieldConfig)
Retrieve a default value, if any, from the database and convert it to a transport object (a Collection of Carrier objects). The FieldConfig object is what represents the context of each default value in a custom field.
The next set of methods to consider are the ones that interact with a web page in some way. All values from web pages arrive at a custom field type object as part of a Custom FieldParams object, which is a holder for a Map of the values of the HTML input elements.
validateFromParams(CustomFieldParams params, ErrorCollection errors, FieldConfig config)
This is the first method that is called after a user has edited a custom field’s value. Any errors recorded here will be nicely displayed next to the field in the edit page.
getValueFromCustomFieldParams(CustomFieldParams customFieldParams)
This method is where a new value for a field that has been accepted by validate FromParams is cleaned and converted into a transport object. The custom FieldParams object will only contain strings for the HTML elements with a name attribute that is the custom field ID—e.g., customfield_10010. A null value means that there is no value for this field.
getStringValueFromCustomFieldParams(CustomFieldParams parameters)
This method returns an object that may be a String, a Collection of Strings or even a CustomFieldParams object. It’s used to populate the value variable used in Chapter 3: Advanced Custom Field Types Velocity templates. It’s also used in the Provider classes that are used by custom field searchers.
String getStringFromSingularObject(Carrier singularObject)
This method is not the direct opposite of getSingularObjectFromString as you might expect. Instead, it is used to convert a singular object (Carrier) to the string that is used in the web page, not to the database value. The returned String is also sometimes what is stored in the Lucene indexes for searching (“More Complex Searchers” on page 57). The singular object was passed into this method as an Object before JIRA 5.0.
The final set of CustomFieldType methods to consider are:
Set<Long> remove(CustomField field)
This method is called when a custom field is entirely removed from a JIRA instance, and returns the issue ids that were affected by the removal. The correct method to use for deleting a value from a field is updateValue.
String getChangelogValue(CustomField field, Object value)
String getChangelogString(CustomField field, Object value)
These methods are how the text that is seen in the History tab of an issue is gen- erated. When a custom field of this type changes, these methods are called with the before and after values of the field. The difference between the two methods is that the if the value later becomes invalid, the string will be shown instead (https://developer.atlassian.com/display/JIRADEV/Database+Schema#DatabaseSchema-ChangeHistory).
extractTransferObjectFromString()
extractStringFromTransferObject()
These methods are not from the CustomFieldType interface but they exist in the standard Multi fields for use during project imports.
Other Interfaces
There are a few other interfaces that are commonly implemented by custom field types.
ProjectImportableCustomField
The getProjectImporter method from this interface is used to implement how the custom field is populated during importing a project from an XML backup. If you don’t implement this interface then project imports will not import values for your custom field.
MultipleCustomFieldType
MultipleSettableCustomFieldType
These two interfaces are used by custom fields with options and that furthermore can have more than one option. For these classes, the values can be accessed using the Options class, which is a simple subclass of a Java List. These interfaces are not really intended for use by general-purpose multiple value custom field types.
Fields with Multiple Values | 41
SortableCustomField
This interface contains a compare method for comparing two singular objects. This is used by the Issue Navigator when you click on a column’s heading to sort a page of issues. This is actually a slower fallback for custom fields that don’t have a searcher associated with them (see Chapter 4).
RestAwareCustomFieldType
RestCustomFieldTypeOperations
These two interfaces are how the JIRA REST API knows which fields can be retrieved or updated. New in JIRA 5.0.
