com.atlassian.jira.propertyset

Interface JiraPropertySetFactory

All Known Implementing Classes:

DefaultJiraPropertySetFactory

public interface JiraPropertySetFactory

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:

• 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.

Since:

v3.12

Method Summary

Modifier and Type	Method and Description
com.opensymphony.module.propertyset.PropertySet	buildCachingDefaultPropertySet(String entityName) Returns a caching PropertySet for the given entity name and an assumed entity ID of 1.
com.opensymphony.module.propertyset.PropertySet	buildCachingDefaultPropertySet(String entityName, boolean bulkLoad) Deprecated. The bulkLoad flag is no longer relevant. Use buildCachingDefaultPropertySet(String) instead. Since v6.2.
com.opensymphony.module.propertyset.PropertySet	buildCachingPropertySet(com.opensymphony.module.propertyset.PropertySet propertySet, boolean bulkLoad) Deprecated. These property sets can become stale if multiple instances are created with the same backing propertySet delegate and are also unsafe in a clustered environment. Use buildCachingDefaultPropertySet(String) or buildCachingPropertySet(String, Long) instead. Since v6.2.
com.opensymphony.module.propertyset.PropertySet	buildCachingPropertySet(String entityName, Long entityId) Returns a caching PropertySet for the given entity name and ID.
com.opensymphony.module.propertyset.PropertySet	buildCachingPropertySet(String entityName, Long entityId, boolean bulkLoad) Deprecated. The bulkLoad flag is no longer relevant. Use buildCachingPropertySet(String, Long) instead. Since v6.2.
com.opensymphony.module.propertyset.PropertySet	buildMemoryPropertySet(String entityName, Long entityId) Returns an in-memory copy of a property set from the database.
com.opensymphony.module.propertyset.PropertySet	buildNoncachingPropertySet(String entityName) Returns a non-caching PropertySet for the given entity name and an assumed entity ID of 1.
com.opensymphony.module.propertyset.PropertySet	buildNoncachingPropertySet(String entityName, Long entityId) Returns a non-caching PropertySet for the given entity name and ID.

Method Detail

buildNoncachingPropertySet

@Nonnull
com.opensymphony.module.propertyset.PropertySet buildNoncachingPropertySet(String entityName)

Returns a non-caching PropertySet for the given entity name and an assumed entity ID of 1.

Parameters:

entityName - the entity name for the entity that owns this property set

Returns:

a non-caching PropertySet

buildNoncachingPropertySet

@Nonnull
com.opensymphony.module.propertyset.PropertySet buildNoncachingPropertySet(String entityName,
                                                                                    Long entityId)

Returns a non-caching PropertySet for the given entity name and ID.

Parameters:

entityName - the entity name for the entity that owns this property set

entityId - the entity ID for the entity that owns this property set

Returns:

a non-caching PropertySet

buildCachingDefaultPropertySet

@Deprecated
 @Nonnull
com.opensymphony.module.propertyset.PropertySet buildCachingDefaultPropertySet(String entityName,
                                                                                                     boolean bulkLoad)

Deprecated. The bulkLoad flag is no longer relevant. Use buildCachingDefaultPropertySet(String) instead. Since v6.2.

This is the old form of buildCachingDefaultPropertySet(String). Its bulkLoad option is no longer significant.

Parameters:

entityName - the entity name for the entity that owns this property set

bulkLoad - Ignored

Returns:

a caching PropertySet

buildCachingPropertySet

@Deprecated
 @Nonnull
com.opensymphony.module.propertyset.PropertySet buildCachingPropertySet(String entityName,
                                                                                              Long entityId,
                                                                                              boolean bulkLoad)

Deprecated. The bulkLoad flag is no longer relevant. Use buildCachingPropertySet(String, Long) instead. Since v6.2.

This is the old form of buildCachingPropertySet(String, Long). Its bulkLoad option is no longer significant.

Parameters:

entityName - the entity name for the entity that owns this property set

entityId - the entity ID for the entity that owns this property set

bulkLoad - Ignored

Returns:

a caching PropertySet

buildCachingDefaultPropertySet

@Nonnull
com.opensymphony.module.propertyset.PropertySet buildCachingDefaultPropertySet(String entityName)

Returns a caching PropertySet for the given entity name and an assumed entity ID of 1.

Parameters:

entityName - the entity name for the entity that owns this property set

Returns:

a caching PropertySet

buildCachingPropertySet

@Nonnull
com.opensymphony.module.propertyset.PropertySet buildCachingPropertySet(String entityName,
                                                                                 Long entityId)

Returns a caching PropertySet for the given entity name and ID.

Parameters:

entityName - the entity name for the entity that owns this property set

entityId - the entity ID for the entity that owns this property set

Returns:

a caching PropertySet

buildCachingPropertySet

@Deprecated
 @Nonnull
com.opensymphony.module.propertyset.PropertySet buildCachingPropertySet(com.opensymphony.module.propertyset.PropertySet propertySet,
                                                                                              boolean bulkLoad)

Deprecated. These property sets can become stale if multiple instances are created with the same backing propertySet delegate and are also unsafe in a clustered environment. Use buildCachingDefaultPropertySet(String) or buildCachingPropertySet(String, Long) instead. Since v6.2.

Returns a PropertySet that caches the return values of the PropertySet that is provided. This can be used to provide short-term caching around another property set implementation, but its use is now discouraged.

WARNING: These property sets are not cluster-safe and generally not safe to hold onto for extended time periods. They do not share cache state with any other cached property set, even if exactly the same delegate propertySet is supplied to this method multiple times.

Parameters:

propertySet - the PropertySet to which requests should be delegated when the request is not cached

bulkLoad - If true, then all properties will be loaded into the cache during initialisation of the property set.

Returns:

a PropertySet which wraps the supplied property set with a short term, non-cluster-safe cache

buildMemoryPropertySet

@Nonnull
com.opensymphony.module.propertyset.PropertySet buildMemoryPropertySet(String entityName,
                                                                                Long entityId)

Returns an in-memory copy of a property set from the database. This property set will not have its configuration saved to the database on each change. It is up to the caller of this method to manually synchronize the returned property set with the database.

Parameters:

entityName - the entity name for the entity that owns this property set

entityId - the entity ID for the entity that owns this property set

Returns:

a PropertySet held completely in memory. Changes will not be written to the database.