@PublicApi public interface

FieldLayoutManager

com.atlassian.jira.issue.fields.layout.field.FieldLayoutManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

The FieldLayoutManager is responsible for managing field configurations and field configuration schemes.

Summary

Constants
String TYPE_DEFAULT JIRA must have a default field layout.
Public Methods
void addSchemeAssociation(Project project, Long fieldLayoutSchemeId)
Associates a FieldLayoutScheme to the project supplied.
void addSchemeAssociation(GenericValue project, Long fieldLayoutSchemeId)
This method is deprecated. Use addSchemeAssociation(com.atlassian.jira.project.Project, Long) instead. Since v5.2.
FieldLayoutScheme copyFieldLayoutScheme(FieldLayoutScheme scheme, String name, String description)
Copies an existing field layout to a new one.
FieldLayoutScheme createFieldLayoutScheme(String name, String description)
Persists a new field Layout scheme (i.e Field Configuration Scheme).
FieldLayoutScheme createFieldLayoutScheme(FieldLayoutScheme fieldLayoutScheme)
Persists a new field Layout scheme (i.e Field Configuration Scheme).
void createFieldLayoutSchemeEntity(FieldLayoutSchemeEntity fieldLayoutSchemeEntity)
Persists a new FieldLayoutSchemeEntity for a particular FieldLayoutScheme.
FieldLayoutSchemeEntity createFieldLayoutSchemeEntity(FieldLayoutScheme fieldLayoutScheme, String issueTypeId, Long fieldConfigurationId)
Persists a new FieldLayoutSchemeEntity for a particular FieldLayoutScheme.
void deleteFieldLayout(FieldLayout fieldLayout)
Deletes a custom FieldLayout
void deleteFieldLayoutScheme(FieldLayoutScheme fieldLayoutScheme)
Removes the FieldLayoutScheme supplied.
boolean fieldConfigurationSchemeExists(String schemeName)
Checks if a FieldConfigurationScheme with the given name exists.
EditableDefaultFieldLayout getEditableDefaultFieldLayout()
Returns the default EditableDefaultFieldLayout.
EditableFieldLayout getEditableFieldLayout(Long id)
Returns an EditableFieldLayout for the id supplied.
List<EditableFieldLayout> getEditableFieldLayouts()
Retrieves editable (see EditableFieldLayout versions of the field layouts.
FieldConfigurationScheme getFieldConfigurationScheme(Project project)
Retrieves the Field Configuration Scheme associated with the supplied project.
FieldConfigurationScheme getFieldConfigurationScheme(Long schemeId)
Retrieves a FieldConfigurationScheme by id
FieldConfigurationScheme getFieldConfigurationSchemeForProject(Long projectId)
Retrieves the Field Configuration Scheme associated with the supplied project.
Collection<FieldConfigurationScheme> getFieldConfigurationSchemes(FieldLayout fieldLayout)
Returns a collection of FieldConfigurationSchemes that include the given FieldLayout.
FieldLayout getFieldLayout(Project project, String issueTypeId)
FieldLayout getFieldLayout()
Used to retrieve FieldLayout information when rendering a screen.
FieldLayout getFieldLayout(GenericValue issue)
This method is deprecated. Use getFieldLayout(com.atlassian.jira.issue.Issue) instead. Since v5.0.
FieldLayout getFieldLayout(Long id)
Used to retrieve FieldLayout information when rendering a screen given the id of the field layout.
FieldLayout getFieldLayout(Long projectId, String issueTypeId)
Find the FieldLayout for the given Project and IssueType.
FieldLayout getFieldLayout(Issue issue)
Returns the fieldLayout for an issue.
Collection<FieldLayoutSchemeEntity> getFieldLayoutSchemeEntities(FieldLayoutScheme fieldLayoutScheme)
Returns a collection of FieldLayoutSchemeEntitys.
List<FieldLayoutScheme> getFieldLayoutSchemes()
Retries Field Configuration Schemes.
FieldLayoutScheme getMutableFieldLayoutScheme(Long schemeId)
Retrieves a mutable FieldLayoutScheme by id.
Collection<GenericValue> getProjects(FieldConfigurationScheme fieldConfigurationScheme)
This method is deprecated. Use getProjectsUsing(FieldConfigurationScheme) instead. Since v6.4.
Collection<GenericValue> getProjects(FieldLayoutScheme fieldLayoutScheme)
This method is deprecated. Use getProjectsUsing(FieldLayoutScheme) instead. Since v6.4.
Collection<Project> getProjectsUsing(FieldLayout fieldLayout)
Finds all projects that use the given FieldLayout (via the configured FieldConfigurationScheme).
Collection<Project> getProjectsUsing(FieldConfigurationScheme fieldConfigurationScheme)
Returns all projects that use the given FieldConfigurationScheme.
Collection<Project> getProjectsUsing(FieldLayoutScheme fieldLayoutScheme)
Returns all projects that use the given FieldLayoutScheme.
Collection<GenericValue> getRelatedProjects(FieldLayout fieldLayout)
This method is deprecated. Use getProjectsUsing(FieldLayout) instead. Since v6.4.
Set<FieldLayout> getUniqueFieldLayouts(Project project)
Retrieves all the FieldLayout's for a project.
@Nonnull Set<FieldLayout> getUniqueFieldLayouts(Collection<Project> projects, Collection<String> issueTypeIds)
Retrieves all the FieldLayout's for a collection of projects and issue types.
boolean hasDefaultFieldLayout()
Checks to see if a FieldLayout entity with type TYPE_DEFAULT exists
boolean isFieldLayoutSchemesVisiblyEquivalent(Long fieldConfigurationSchemeId1, Long fieldConfigurationSchemeId2)
Will determine whether or not two FieldLayoutSchemes are "visibly equivalent".
boolean isFieldLayoutsVisiblyEquivalent(Long fieldLayoutId1, Long fieldLayoutId2)
Will determine whether or not two FieldLayouts are "visibly equivalent".
void refresh()
Clears all local caches.
void removeFieldLayoutScheme(FieldLayoutScheme fieldLayoutScheme)
void removeFieldLayoutSchemeEntity(FieldLayoutSchemeEntity fieldLayoutSchemeEntity)
Removes a FieldLayoutSchemeEntity
void removeSchemeAssociation(Project project, Long fieldLayoutSchemeId)
Removes an association between a particular project and field configuration scheme.
void removeSchemeAssociation(GenericValue project, Long fieldLayoutSchemeId)
This method is deprecated. Use removeSchemeAssociation(com.atlassian.jira.project.Project, Long) instead. Since v5.2.
void restoreDefaultFieldLayout()
This method can be used to rollback any changes to the default field configuration.
EditableFieldLayout storeAndReturnEditableFieldLayout(EditableFieldLayout editableFieldLayout)
Persists the EditableFieldLayout provided and returns a new instance as stored in the database.
void storeEditableDefaultFieldLayout(EditableDefaultFieldLayout editableDefaultFieldLayout)
Persist the given default EditableDefaultFieldLayout
void storeEditableFieldLayout(EditableFieldLayout editableFieldLayout)
Persists the EditableFieldLayout provided.
void updateFieldLayoutScheme(FieldLayoutScheme fieldLayoutScheme)
Persists the FieldLayoutScheme supplied.
void updateFieldLayoutSchemeEntity(FieldLayoutSchemeEntity fieldLayoutSchemeEntity)
Updates a FieldLayoutSchemeEntity.

Constants

public static final String TYPE_DEFAULT

JIRA must have a default field layout. This is used identify the default layout.

Constant Value: "default"

Public Methods

public void addSchemeAssociation (Project project, Long fieldLayoutSchemeId)

Associates a FieldLayoutScheme to the project supplied.

Parameters
project The project
fieldLayoutSchemeId ID of the FieldLayoutScheme
Throws
IllegalArgumentException If the project supplied is null.

public void addSchemeAssociation (GenericValue project, Long fieldLayoutSchemeId)

This method is deprecated.
Use addSchemeAssociation(com.atlassian.jira.project.Project, Long) instead. Since v5.2.

Associates a FieldLayoutScheme to the project supplied.

Parameters
project A project GenericValue
fieldLayoutSchemeId ID of the FieldLayoutScheme
Throws
DataAccessException If there is an error in the DB layer
UnsupportedOperationException If this is executed against standard edition
IllegalArgumentException If the project supplied is null.

public FieldLayoutScheme copyFieldLayoutScheme (FieldLayoutScheme scheme, String name, String description)

Copies an existing field layout to a new one.

public FieldLayoutScheme createFieldLayoutScheme (String name, String description)

Persists a new field Layout scheme (i.e Field Configuration Scheme).

public FieldLayoutScheme createFieldLayoutScheme (FieldLayoutScheme fieldLayoutScheme)

Persists a new field Layout scheme (i.e Field Configuration Scheme).

Parameters
fieldLayoutScheme The FieldLayoutScheme to persist.
Returns
Throws
DataAccessException If there is a Data Layer error.
UnsupportedOperationException If this is executed against standard edition

public void createFieldLayoutSchemeEntity (FieldLayoutSchemeEntity fieldLayoutSchemeEntity)

Persists a new FieldLayoutSchemeEntity for a particular FieldLayoutScheme. The appropriate scheme is retrieved using getFieldLayoutScheme()

Parameters
fieldLayoutSchemeEntity The FieldLayoutSchemeEntity
Throws
UnsupportedOperationException If this is executed against standard edition

public FieldLayoutSchemeEntity createFieldLayoutSchemeEntity (FieldLayoutScheme fieldLayoutScheme, String issueTypeId, Long fieldConfigurationId)

Persists a new FieldLayoutSchemeEntity for a particular FieldLayoutScheme. The appropriate scheme is retrieved using getFieldLayoutScheme()

Parameters
fieldLayoutScheme the FieldLayoutScheme
issueTypeId the Issue Type
fieldConfigurationId the FieldConfig
Throws
UnsupportedOperationException If this is executed against standard edition

public void deleteFieldLayout (FieldLayout fieldLayout)

Deletes a custom FieldLayout

Parameters
fieldLayout The FieldLayout
Throws
UnsupportedOperationException If this is executed against standard edition

public void deleteFieldLayoutScheme (FieldLayoutScheme fieldLayoutScheme)

Removes the FieldLayoutScheme supplied.

Parameters
fieldLayoutScheme The FieldLayoutScheme
Throws
DataAccessException If there is a Data Layer error.
UnsupportedOperationException If this is executed against standard edition

public boolean fieldConfigurationSchemeExists (String schemeName)

Checks if a FieldConfigurationScheme with the given name exists.

Parameters
schemeName The scheme name
Returns
  • true if a FieldConfigurationScheme with the given name exists.
Throws
DataAccessException If there is a DB error.
UnsupportedOperationException If this is executed against standard edition

public EditableDefaultFieldLayout getEditableDefaultFieldLayout ()

Returns the default EditableDefaultFieldLayout.

Returns
Throws
DataAccessException If there is a Data Layer error.

public EditableFieldLayout getEditableFieldLayout (Long id)

Returns an EditableFieldLayout for the id supplied.

Parameters
id If the id is NULL, the default layout is returned.
Returns
Throws
UnsupportedOperationException If this is executed against standard edition

public List<EditableFieldLayout> getEditableFieldLayouts ()

Retrieves editable (see EditableFieldLayout versions of the field layouts. Note: For standard edition this simply returns an editable version of the default field layout. (see EditableDefaultFieldLayout)

Returns

public FieldConfigurationScheme getFieldConfigurationScheme (Project project)

Retrieves the Field Configuration Scheme associated with the supplied project.

Parameters
project A project
Returns

public FieldConfigurationScheme getFieldConfigurationScheme (Long schemeId)

Retrieves a FieldConfigurationScheme by id

Parameters
schemeId FieldConfigurationScheme ID
Returns
Throws
DataAccessException If there is a DB exception.
UnsupportedOperationException If this is executed against standard edition

public FieldConfigurationScheme getFieldConfigurationSchemeForProject (Long projectId)

Retrieves the Field Configuration Scheme associated with the supplied project.

Parameters
projectId The project ID
Returns

public Collection<FieldConfigurationScheme> getFieldConfigurationSchemes (FieldLayout fieldLayout)

Returns a collection of FieldConfigurationSchemes that include the given FieldLayout.

This is determined by retrieving all FieldLayoutSchemeEntitys with the FieldLayout and calculating a set of FieldConfigurationSchemes using these entities.

Parameters
fieldLayout The FieldLayout.
Returns
Throws
UnsupportedOperationException If this is executed against standard edition

public FieldLayout getFieldLayout (Project project, String issueTypeId)

Parameters
project A project
issueTypeId The IssueType id of the issue.
Returns
Throws
DataAccessException If there is a Data Layer error.
See Also

public FieldLayout getFieldLayout ()

Used to retrieve FieldLayout information when rendering a screen.

Returns
  • the default FieldLayout
Throws
DataAccessException If there is a Data Layer error.

public FieldLayout getFieldLayout (GenericValue issue)

This method is deprecated.
Use getFieldLayout(com.atlassian.jira.issue.Issue) instead. Since v5.0.

Returns the fieldLayout for an issue.

Parameters
issue An issue GenericValue
Returns
Throws
DataAccessException If there is a Data Layer error.

public FieldLayout getFieldLayout (Long id)

Used to retrieve FieldLayout information when rendering a screen given the id of the field layout. If the ID is null, the default layout is returned.

Parameters
id The FieldLayout ID.
Returns
Throws
UnsupportedOperationException If this is executed against standard edition

public FieldLayout getFieldLayout (Long projectId, String issueTypeId)

Find the FieldLayout for the given Project and IssueType.

Parameters
projectId the project
issueTypeId the issue type
Returns
  • the FieldLayout for the given Project and IssueType.

public FieldLayout getFieldLayout (Issue issue)

Returns the fieldLayout for an issue.

Parameters
issue An Issue
Returns

public Collection<FieldLayoutSchemeEntity> getFieldLayoutSchemeEntities (FieldLayoutScheme fieldLayoutScheme)

Returns a collection of FieldLayoutSchemeEntitys. These are used to record mappings from IssueType -> FieldLayout for the FieldLayoutScheme passed in.

Parameters
fieldLayoutScheme The FieldLayoutScheme
Returns
Throws
UnsupportedOperationException If this is executed against standard edition

public List<FieldLayoutScheme> getFieldLayoutSchemes ()

Retries Field Configuration Schemes. These are used to link field configurations to projects.

Returns
Throws
DataAccessException If there is a Data Layer error.
UnsupportedOperationException If this is executed against standard edition

public FieldLayoutScheme getMutableFieldLayoutScheme (Long schemeId)

Retrieves a mutable FieldLayoutScheme by id.

This returns a new copy of the object from the DB, and so will incur some performance penalty. Please use getFieldConfigurationScheme(Long) for access to a cached immutable scheme object.

Parameters
schemeId the scheme ID
Returns
Throws
DataAccessException if an error occurs in the DB layer
UnsupportedOperationException If this is executed against standard edition

public Collection<GenericValue> getProjects (FieldConfigurationScheme fieldConfigurationScheme)

This method is deprecated.
Use getProjectsUsing(FieldConfigurationScheme) instead. Since v6.4.

Returns all projects that use the given FieldConfigurationScheme.

Parameters
fieldConfigurationScheme the FieldConfigurationScheme
Returns
  • A list of projects that use the given FieldConfigurationScheme.

public Collection<GenericValue> getProjects (FieldLayoutScheme fieldLayoutScheme)

This method is deprecated.
Use getProjectsUsing(FieldLayoutScheme) instead. Since v6.4.

Returns all associated projects for the FieldLayoutScheme supplied.

Parameters
fieldLayoutScheme the FieldLayoutScheme
Returns
  • A list of project GenericValues
Throws
DataAccessException If there is a Data Layer error.
UnsupportedOperationException If this is executed against standard edition

public Collection<Project> getProjectsUsing (FieldLayout fieldLayout)

Finds all projects that use the given FieldLayout (via the configured FieldConfigurationScheme).

NOTE: In the case of Standard & Professional, this simply returns ALL projects, as the only fieldlayout is the default field layout.

Parameters
fieldLayout The FieldLayout.
Returns
  • The set of Projects that use the given FieldLayout.

public Collection<Project> getProjectsUsing (FieldConfigurationScheme fieldConfigurationScheme)

Returns all projects that use the given FieldConfigurationScheme.

Parameters
fieldConfigurationScheme the FieldConfigurationScheme
Returns
  • A list of projects that use the given FieldConfigurationScheme.

public Collection<Project> getProjectsUsing (FieldLayoutScheme fieldLayoutScheme)

Returns all projects that use the given FieldLayoutScheme.

Parameters
fieldLayoutScheme the FieldLayoutScheme
Returns
  • A list of projects that use the given FieldLayoutScheme.

public Collection<GenericValue> getRelatedProjects (FieldLayout fieldLayout)

This method is deprecated.
Use getProjectsUsing(FieldLayout) instead. Since v6.4.

Finds all projects that use the given FieldLayout (via the configured FieldConfigurationScheme).

NOTE: In the case of Standard & Professional, this simply returns ALL projects, as the only fieldlayout is the default field layout.

Parameters
fieldLayout The FieldLayout.
Returns
  • The set of Projects that use the given FieldLayout.

public Set<FieldLayout> getUniqueFieldLayouts (Project project)

Retrieves all the FieldLayout's for a project.

Parameters
project a project
Returns
  • the unique set of FieldLayout's for the provided project, an empty set if there are none.
Throws
DataAccessException If there is a Data Layer error.

@Nonnull public Set<FieldLayout> getUniqueFieldLayouts (Collection<Project> projects, Collection<String> issueTypeIds)

Retrieves all the FieldLayout's for a collection of projects and issue types.

Parameters
projects a collection of projects.
issueTypeIds An collection of issue type ids.
Returns
  • the unique set of FieldLayout's for the provided projects, an empty set if there are none.

public boolean hasDefaultFieldLayout ()

Checks to see if a FieldLayout entity with type TYPE_DEFAULT exists

Returns
Throws
DataAccessException If there is a Data Layer error.

public boolean isFieldLayoutSchemesVisiblyEquivalent (Long fieldConfigurationSchemeId1, Long fieldConfigurationSchemeId2)

Will determine whether or not two FieldLayoutSchemes are "visibly equivalent".

This can be useful for determining if swapping one field layout scheme for another in a project will have any affect on the visibility of fields in the project's issues. For instance, this will let us know if we need to re-index or not.

Since a scheme is a mapping from issue types to field layouts, two schemes are visibly equivalent if:

  • All issue types map to the same field layouts; or else
  • The field layouts that an issue type is associated with in each scheme are visibly equivalent
It is possible that one scheme may have a mapping for an issue type, but the other does not. In this case, equivalence is compared between the issue type specific one and the default field layout.

Note that equivalence is reflexive - all the associations in scheme1 must have equivalent associations in scheme2, and vice versa.

Parameters
fieldConfigurationSchemeId1 the first scheme; can use null for the system default scheme
fieldConfigurationSchemeId2 the second scheme; can use null for the system default scheme
Returns
  • the result of the equivalence comparison
Throws
DataAccessException If there is a Data Layer error.

public boolean isFieldLayoutsVisiblyEquivalent (Long fieldLayoutId1, Long fieldLayoutId2)

Will determine whether or not two FieldLayouts are "visibly equivalent".

This can be useful for determining if swapping one field layout for another in a project will have any affect on the visibility of fields in the project's issues. For instance, this will let us know if we need to re-index or not.

Two field layouts are visibly equivalent if:

  • They contain the same fields, and
  • Each field has the same shown/hidden flag
Note that equivalence is reflexive: layout1 == layout2 implies layout2 == layout1.

Parameters
fieldLayoutId1 the first layout id; null signifies the default field layout in the system
fieldLayoutId2 the second layout id; null signifies the default field layout in the system
Returns
  • the result of the equivalence comparison

public void refresh ()

Clears all local caches.

public void removeFieldLayoutScheme (FieldLayoutScheme fieldLayoutScheme)

Parameters
fieldLayoutScheme The FieldLayoutScheme
Throws
UnsupportedOperationException If this is executed against standard edition

public void removeFieldLayoutSchemeEntity (FieldLayoutSchemeEntity fieldLayoutSchemeEntity)

Removes a FieldLayoutSchemeEntity

Parameters
fieldLayoutSchemeEntity The FieldLayoutSchemeEntity
Throws
UnsupportedOperationException If this is executed against standard edition

public void removeSchemeAssociation (Project project, Long fieldLayoutSchemeId)

Removes an association between a particular project and field configuration scheme.

Parameters
project The project
fieldLayoutSchemeId The fieldLayoutScheme ID

public void removeSchemeAssociation (GenericValue project, Long fieldLayoutSchemeId)

This method is deprecated.
Use removeSchemeAssociation(com.atlassian.jira.project.Project, Long) instead. Since v5.2.

Removes an association between a particular project and field configuration scheme.

Parameters
project A project GenericValue
fieldLayoutSchemeId The fieldLayoutScheme ID
Throws
UnsupportedOperationException If this is executed against standard edition
DataAccessException If there is an error in the DB layer.

public void restoreDefaultFieldLayout ()

This method can be used to rollback any changes to the default field configuration.

Throws
DataAccessException If there is a Data Layer error.

public EditableFieldLayout storeAndReturnEditableFieldLayout (EditableFieldLayout editableFieldLayout)

Persists the EditableFieldLayout provided and returns a new instance as stored in the database.

Parameters
editableFieldLayout the EditableFieldLayout.
Returns
  • the layout as stored in the database.
Throws
DataAccessException If there is a Data Layer error.

public void storeEditableDefaultFieldLayout (EditableDefaultFieldLayout editableDefaultFieldLayout)

Persist the given default EditableDefaultFieldLayout

Parameters
editableDefaultFieldLayout The EditableDefaultFieldLayout.
Throws
DataAccessException If there is a Data Layer error.

public void storeEditableFieldLayout (EditableFieldLayout editableFieldLayout)

Persists the EditableFieldLayout provided.

Parameters
editableFieldLayout the EditableFieldLayout.
Throws
DataAccessException If there is a Data Layer error.

public void updateFieldLayoutScheme (FieldLayoutScheme fieldLayoutScheme)

Persists the FieldLayoutScheme supplied.

Parameters
fieldLayoutScheme The FieldLayoutScheme
Throws
DataAccessException If there is a Data Layer error.
UnsupportedOperationException If this is executed against standard edition

public void updateFieldLayoutSchemeEntity (FieldLayoutSchemeEntity fieldLayoutSchemeEntity)

Updates a FieldLayoutSchemeEntity.

Parameters
fieldLayoutSchemeEntity The FieldLayoutSchemeEntity
Throws
UnsupportedOperationException If this is executed against standard edition