How does aFieldConfigScheme.getOneAndOnlyConfig() work?

[Holger Schimanski]

To add custom field options, I need to retrieve the right FieldConfig to add new option values. I am iterating over all FieldConfigurationSchemes of that custom field.

List<FieldConfigScheme> tmpConfigSchemes = aCustomField.getConfigurationSchemes();
for (FieldConfigScheme aFieldConfigScheme : tmpConfigSchemes) { ... }

and look which one matched to my project using

List<Project> tmpContextProjects = aFieldConfigScheme.getAssociatedProjectObjects();
if (tmpContextProjects.contains(aProject)) { ... }

Then I use

aFieldConfigScheme.getOneAndOnlyConfig()

In the JavaDoc it says, that "Returns the one and only config for this scheme if there's only one config associated".

My Question is: In which situations will aFieldConfigScheme.getOneAndOnlyConfig() not return a config?

[Boris Georgiev _Appfire_ · Accepted solution]

"Null if no configs, or more than one config"

I think this is possible just theoretically but not in practice, as this means that you should have two or more different configurations within the same field context or no at all. In some parts of the JIRA code there is asumption that there is always only one config, so I suppose this will not return null or at least not soon :)

[George Dinkov _Botron_]

I can also confirm that just about everywhere in the JIRA source the getOneAndOnlyConfig() call is used without any special checking of the result or before the call. The method uses internally getConfigsByConfig(), so you can call that if you want to be extra safe, but I don't think this is necessary.

[crf]

The documentation could certainly stand to be improved, here.

The getOneAndOnlyConfig() method calls getConfigsByConfig() (as George Dinkov already noted). If the returned MultiMap has exactly one entry, then it extracts the single key that it has and returns it; otherwise, it logs a warning and returns null.

Which leads to two more questions:

1. What does getConfigsByConfig() really do?
2. Why would we expect it to only have one item in it?

The first question's answer isn't that surprising. It returns an inverted map derived from getConfigs(), which itself returns a mapping from an issue type to its corresponding field configuration. The map from getConfigsByConfig() would then return the mapping from each field configuration in the scheme back to the issue types that use it. Putting this all together, calling getOneAndOnlyConfig() implies that you expect all issue types defined by the scheme to belong to a single field configuration.

As to the second question, as far as I can tell by digging into the code, any other possibility is an artifact of long since abandoned ideas from back in 2005 that there would be a more advanced editing mode (Note isBasicMode(), which apparently is always true) for the already complicated field configuration schemes.

In reality, I don't think you should ever be getting a null from this without some kind of corruption, and where I see this method used internally by JIRA, it seems to be intended as a guard (with logging) against exactly that.

[Andreas Ebert]

Depending on what you consider "the right FieldConfig" in your particular situation, you could also use CustomField#getRelevantConfig(Issue). If you don't have a real Issue, then you can create a dummy Issue just to call that method. Like so:

MutableIssue myIssue = ComponentAccessor.getIssueFactory().getIssue();
myIssue.setProjectObject(myProject);
myIssue.setIssueTypeObject(myIssueType);

This will also work with a null IssueType.