JiraPropertySetFactory

Class Overview

Provides a number of utility methods to retrieve a property set from JIRA. Please note that this class's sole responsibility is to create a property set. It does not cache them internally, and repeated method calls will create a new property set every time, even if supplied with same arguments. Property sets are not particularly expensive to construct, but it still makes sense to avoid recreating them every time they are needed, if possible.

Property sets belong to an "entity", as defined by an entityName and entityId. Normally, the entity name is one of those defined by JIRA's entitymodel.xml file, such as "Issue" or "CustomField" and the entity ID is the value of its "id" field, but this is not strictly required. Plugins may store their own property sets without attaching them to any actual database entity. It is recommended that the plugin's key be used as a prefix for the entity name when storing a property set for this purpose. JIRA stores its own properties for some entities, and plugins should avoid modifying these values directly, as an entity's property set contents are not considered part of its API.

The factory methods that return a non-caching property set return an implementation that does not interact with caches in any way. Any access to them, read or write, will result in a database call. Any caching property sets for the same entity will not be notified that their cached state is invalid, potentially leaving them with stale values. For this reason, as well as for performance reasons, a caching property set should usually be preferred.

The factory methods that return a caching property set return an implementation that caches its properties. Calls to getKeys and write operations will access the database, but queries like exists, getType, and the various getters to retrieve a property's value will rely on cached information whenever possible. The caching property sets are cluster-safe unless otherwise noted.

Plugin developers that are looking for a general storage mechanism might also want to consider one of the alternatives that are available:

• com.atlassian.sal.api.pluginsettings.PluginSettings Plugin Settings — a storage class that is suitable for use by cross-product plugins.
• JSON Entity Properties — similar to a property set, but using JSON as the storage format.
• Custom Fields — issue-specific values that are user-visible and searchable.
• Active Objects — customized object-relational mappings and persistence.

Summary