com.atlassian.jira.issue
Interface CustomFieldManager

All Known Implementing Classes:
DefaultCustomFieldManager

@PublicApi
public interface CustomFieldManager

Functions for working with CustomFields.


Field Summary
static String PLUGIN_KEY
           
 
Method Summary
 void clear()
          clear the cache
 CustomField createCustomField(String fieldName, String description, CustomFieldType fieldType, CustomFieldSearcher customFieldSearcher, List contexts, List issueTypes)
          Creates a custom field with the given name and description of the given CustomFieldType using the given CustomFieldSearcher that is displayed in the given list of contexts available to the given list of issueTypes.
 CustomField getCustomFieldInstance(org.ofbiz.core.entity.GenericValue customFieldGv)
          Converts a customfield GenericValue to a CustomField instance.
 CustomField getCustomFieldObject(Long id)
          Get a CustomField by ID.
 CustomField getCustomFieldObject(String id)
          Get a CustomField by its text key (eg 'customfield_10000').
 CustomField getCustomFieldObjectByName(String customFieldName)
          Retrieve the first custom field object with the specified name.
 List<CustomField> getCustomFieldObjects()
          Returns all custom fields.
 List<CustomField> getCustomFieldObjects(org.ofbiz.core.entity.GenericValue issue)
          Returns a list of CustomFields that apply to a particular issue.
 List<CustomField> getCustomFieldObjects(Issue issue)
          Returns a list of CustomFields that apply to a particular issue.
 List<CustomField> getCustomFieldObjects(Long projectId, List<String> issueTypes)
          Returns the same as getCustomFieldObjects(Long,String) but allows to specify a list of issueTypes.
 List<CustomField> getCustomFieldObjects(Long projectId, String issueType)
          Gets a list of custom fields for a particular project and issue type.
 List<CustomField> getCustomFieldObjects(SearchContext searchContext)
          Returns all customfields in a particular SearchContext.
 Collection<CustomField> getCustomFieldObjectsByName(String customFieldName)
          Retrieve custom field(s) of a certain name.
 CustomFieldSearcher getCustomFieldSearcher(String key)
          Retrieve a custom field searcher by its type key.
 Class getCustomFieldSearcherClass(String key)
          Retrieve a custom field searcher by its type key.
 List getCustomFieldSearchers(CustomFieldType customFieldType)
          Retrieves all the searchers registered for a particular custom Field.
 CustomFieldType getCustomFieldType(String key)
          Retrieve a custom field type by its type key.
 List getCustomFieldTypes()
          Retrieve all customfieldtypes registered in the sytem.
 List<CustomField> getGlobalCustomFieldObjects()
          Returns a list of custom fields where the CustomField.isGlobal() is true.
 void refresh()
          reloads all customfields into the cache from the DB, this is an expensive operation, so avoid it if you can.
 void refreshConfigurationSchemes(Long customFieldId)
          Causes a reload of the field configuration scheme for a specified custom field id Call when the configuration scheme changes
 void removeCustomField(CustomField customField)
          Removes the customfield supplied including all associations and values.
 void removeCustomFieldPossiblyLeavingOrphanedData(Long customFieldId)
          Removes the customfield supplied.
 void removeCustomFieldValues(org.ofbiz.core.entity.GenericValue issue)
          Removes the values stored by customfields for a particular Issue.
 void removeProjectAssociations(org.ofbiz.core.entity.GenericValue project)
          Deprecated. Use removeProjectAssociations(Project) instead. Since v5.1.
 void removeProjectAssociations(Project project)
          Used if a project is deleted to remove the project field associations.
 void removeProjectCategoryAssociations(ProjectCategory projectCategory)
          Used if a project category is deleted to remove the field associations.
 void updateCustomField(CustomField updatedField)
          Updates the supplied custom field, refreshes the underlying cache
 

Field Detail

PLUGIN_KEY

static final String PLUGIN_KEY
See Also:
Constant Field Values
Method Detail

getCustomFieldObjectsByName

Collection<CustomField> getCustomFieldObjectsByName(String customFieldName)
Retrieve custom field(s) of a certain name.

Parameters:
customFieldName -
Returns:
A collection of CustomFields.

getCustomFieldObjectByName

CustomField getCustomFieldObjectByName(String customFieldName)
Retrieve the first custom field object with the specified name. WARNING: Custom Field names are no longer guaranteed to be unique. This method returns the first named custom field. Use getCustomFieldObjectsByName(String) to retrieve all custom fields.

Parameters:
customFieldName - the Name
Returns:
The first named CustomField, or null if not found.

getCustomFieldObject

CustomField getCustomFieldObject(Long id)
Get a CustomField by ID.

Parameters:
id - ID of field, eg. 10000
Returns:
The CustomField or null.

getCustomFieldObject

CustomField getCustomFieldObject(String id)
Get a CustomField by its text key (eg 'customfield_10000').

Parameters:
id - Eg. 'customfield_10000'
Returns:
The CustomField or null if not found.

getCustomFieldObjects

List<CustomField> getCustomFieldObjects()
Returns all custom fields.

Returns:
A list of all CustomFields.

getGlobalCustomFieldObjects

List<CustomField> getGlobalCustomFieldObjects()
Returns a list of custom fields where the CustomField.isGlobal() is true.

Returns:
A list of CustomFields

getCustomFieldObjects

List<CustomField> getCustomFieldObjects(Long projectId,
                                        String issueType)
Gets a list of custom fields for a particular project and issue type.

Parameters:
projectId - Id of the project
issueType - An issue type. See ConstantsManager.ALL_ISSUE_TYPES, ConstantsManager.ALL_STANDARD_ISSUE_TYPES and ConstantsManager.ALL_SUB_TASK_ISSUE_TYPES
Returns:
A list of CustomFields

getCustomFieldObjects

List<CustomField> getCustomFieldObjects(Long projectId,
                                        List<String> issueTypes)
Returns the same as getCustomFieldObjects(Long,String) but allows to specify a list of issueTypes.

Parameters:
projectId - Id of the project
issueTypes - A list of issue types. See ConstantsManager.ALL_ISSUE_TYPES, ConstantsManager.ALL_STANDARD_ISSUE_TYPES and ConstantsManager.ALL_SUB_TASK_ISSUE_TYPES
Returns:
A list of CustomFields

getCustomFieldObjects

List<CustomField> getCustomFieldObjects(SearchContext searchContext)
Returns all customfields in a particular SearchContext. Also see CustomField.isInScope(com.atlassian.crowd.embedded.api.User,com.atlassian.jira.issue.search.SearchContext).

Parameters:
searchContext - the SearchContext
Returns:
A list of CustomFields

getCustomFieldObjects

List<CustomField> getCustomFieldObjects(org.ofbiz.core.entity.GenericValue issue)
Returns a list of CustomFields that apply to a particular issue.

Parameters:
issue - A GenericValue of the issue
Returns:
A list of CustomFields

getCustomFieldObjects

List<CustomField> getCustomFieldObjects(Issue issue)
Returns a list of CustomFields that apply to a particular issue.

Parameters:
issue - A Issue object
Returns:
A list of CustomFields

getCustomFieldTypes

List getCustomFieldTypes()
Retrieve all customfieldtypes registered in the sytem.

Returns:
a list of CustomFieldTypes

getCustomFieldType

CustomFieldType getCustomFieldType(String key)
Retrieve a custom field type by its type key.

The key is the "full plugin module key". That is, the plugin key for the plugin it comes from, a colon separator, and then the module key. e.g. the system types are specified in system-customfieldtypes-plugin.xml:

 <atlassian-plugin key="com.atlassian.jira.plugin.system.customfieldtypes" name="Custom Field Types & Searchers">
     ...
     <customfield-type key="float" name="Number Field"
     ...
 
To access the 'Number Field' type, the key would then be 'com.atlassian.jira.plugin.system.customfieldtypes:float'.

Parameters:
key - Type identifier constructed from plugin XML.
Returns:
the CustomFieldType for the given key

getCustomFieldSearchers

List getCustomFieldSearchers(CustomFieldType customFieldType)
Retrieves all the searchers registered for a particular custom Field. Searchers may be registred via:
   <customfield-searcher key="daterange" name="Date Range picker"
                     i18n-name-key="admin.customfield.searcher.daterange.name"
                     class="com.atlassian.jira.issue.customfields.searchers.DateRangeSearcher">
 

Parameters:
customFieldType - the CustomFieldType
Returns:
A list of CustomFieldSearchers

getCustomFieldSearcher

CustomFieldSearcher getCustomFieldSearcher(String key)
Retrieve a custom field searcher by its type key.

The key is the "full plugin module key". That is, the plugin key for the plugin it comes from, a colon separator, and then the module key. e.g. the system types are specified in system-customfieldtypes-plugin.xml:

 <atlassian-plugin key="com.atlassian.jira.plugin.system.customfieldtypes" name="Custom Field Types & Searchers">
     ...
     <customfield-type key="float" name="Number Field"
     ...
 
To access the 'Number Field' type, the key would then be 'com.atlassian.jira.plugin.system.customfieldtypes:float'.

Parameters:
key - Type identifier constructed from plugin XML.
Returns:
the CustomFieldSearcher for the given key

createCustomField

CustomField createCustomField(String fieldName,
                              String description,
                              CustomFieldType fieldType,
                              CustomFieldSearcher customFieldSearcher,
                              List contexts,
                              List issueTypes)
                              throws org.ofbiz.core.entity.GenericEntityException
Creates a custom field with the given name and description of the given CustomFieldType using the given CustomFieldSearcher that is displayed in the given list of contexts available to the given list of issueTypes.

Returns:
the newly created CustomField.
Throws:
org.ofbiz.core.entity.GenericEntityException - if the CustomField could not be created.

removeCustomFieldPossiblyLeavingOrphanedData

void removeCustomFieldPossiblyLeavingOrphanedData(Long customFieldId)
                                                  throws RemoveException,
                                                         IllegalArgumentException
Removes the customfield supplied. This method will try to lookup the customfield object via the manager first. If the customfield object can be retrieved this way, it simply delegates the removal to the removeCustomField(com.atlassian.jira.issue.fields.CustomField) method, which will not leave any orphaned data behind.

NOTE: Generally you should use the removeCustomField(com.atlassian.jira.issue.fields.CustomField) method to remove a custom field, as it is guaranteed to remove all data. This method should only be used if a customfield needs to be removed when the customfieldtype for that field is no longer available!

If however the customfield object cannot be retrieved via the manager, which may be the case if the custom field type is no longer available (a plugin may have been removed), then this method will try to lookup the custom field directly in the database. If it doesn't exist in the database, an IllegalArgumentException will be thrown. Otherwise, the customfield and all associated configurations will be removed. This method will also call to the CustomFieldValuePersister.removeAllValues(String) method to delete any values. Please note however, that if your custom field stores any other values (such as options for example), they will have to be removed by the caller of this method, as the custom field type is not accessible (which is usually responsible for removing such values).

Parameters:
customFieldId - The id of the customField to be removed.
Throws:
RemoveException - On any error removing the custom field
IllegalArgumentException - If no customfield matching the customFieldId can be found

removeCustomField

void removeCustomField(CustomField customField)
                       throws RemoveException
Removes the customfield supplied including all associations and values.

Parameters:
customField - The CustomField to be removed.
Throws:
RemoveException - On any error removing the custom field

updateCustomField

void updateCustomField(CustomField updatedField)
Updates the supplied custom field, refreshes the underlying cache

Parameters:
updatedField - updated Custom field

removeCustomFieldValues

void removeCustomFieldValues(org.ofbiz.core.entity.GenericValue issue)
                             throws org.ofbiz.core.entity.GenericEntityException
Removes the values stored by customfields for a particular Issue.

Parameters:
issue - The issue GenericValue
Throws:
org.ofbiz.core.entity.GenericEntityException - DB error

removeProjectAssociations

void removeProjectAssociations(org.ofbiz.core.entity.GenericValue project)
Deprecated. Use removeProjectAssociations(Project) instead. Since v5.1.

Used if a project is deleted to remove the project field associations.

Parameters:
project - The project being deleted.

removeProjectAssociations

void removeProjectAssociations(Project project)
Used if a project is deleted to remove the project field associations.

Parameters:
project - The project being deleted.

removeProjectCategoryAssociations

void removeProjectCategoryAssociations(ProjectCategory projectCategory)
Used if a project category is deleted to remove the field associations.

Parameters:
projectCategory - The project category being deleted.

getCustomFieldInstance

CustomField getCustomFieldInstance(org.ofbiz.core.entity.GenericValue customFieldGv)
Converts a customfield GenericValue to a CustomField instance.

Parameters:
customFieldGv -
Returns:
a CustomField instance

refresh

void refresh()
reloads all customfields into the cache from the DB, this is an expensive operation, so avoid it if you can.


refreshConfigurationSchemes

void refreshConfigurationSchemes(Long customFieldId)
Causes a reload of the field configuration scheme for a specified custom field id Call when the configuration scheme changes

Parameters:
customFieldId -

clear

void clear()
clear the cache


getCustomFieldSearcherClass

Class getCustomFieldSearcherClass(String key)
Retrieve a custom field searcher by its type key.

The key is the "full plugin module key". That is, the plugin key for the plugin it comes from, a colon separator, and then the module key. e.g. the system types are specified in system-customfieldtypes-plugin.xml:

 <atlassian-plugin key="com.atlassian.jira.plugin.system.customfieldtypes" name="Custom Field Types & Searchers">
     ...
     <customfield-type key="float" name="Number Field"
     ...
 
To access the 'Number Field' type, the key would then be 'com.atlassian.jira.plugin.system.customfieldtypes:float'.

Parameters:
key - Type identifier constructed from plugin XML.


Copyright © 2002-2013 Atlassian. All Rights Reserved.