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
PropertySet#getKeys() and write operations will access the database, but queries
like
PropertySet#exists(String),
PropertySet#getType(String), and the various
PropertySet#getString(String) 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 — a storage class
that is suitable for use by cross-product plugins.
-
com.atlassian.jira.entity.property.JsonEntityPropertyManager — similar
to a property set, but using JSON as the storage format.
-
com.atlassian.jira.issue.fields.CustomField — issue-specific values that
are user-visible and searchable.
- Active Objects —
customized object-relational mappings and persistence.