com.atlassian.jira.entity.property

Interface JsonEntityPropertyManager

All Known Implementing Classes:

JsonEntityPropertyManagerImpl

@ExperimentalApi
public interface JsonEntityPropertyManager

Low-level database API for accessing JSON entity properties.

JSON entity properties are similar to PropertySets in that they are permitted to hold more or less arbitrary collections of data. There are, however, several important differences:

• Property sets support a wider range of data types, including things like XML documents, Properties, and any serializable object. JSON entity properties support only those data types that JSON itself supports.
• Property sets are stored as an individual database row for each property while JSON Entity Properties are stored as a single row containing the entire data structure.
• Property sets are expected to be directly associated with an OfBiz entity of some kind, and only one such property set can exist for any given entity. JSON entity properties are more flexible, in that they are keyed by an entity name, entity ID, and a key. This allows multiple kinds of metadata to be attached to the entity, such as both issue links and issue properties, without the data colliding.
• Property sets are loaded by direct reference using the owning entity name and entity ID. JSON entity properties are more flexible in this regard as there is a fluent query service for locating them.

Note: The entityName used here MUST be unique to the service that maintains the properties. To reduce the risk of collision, it SHOULD NOT be the same as the name of the owning entity itself, as there may be other services that also which to attach properties to that same entity. For example, the RemoteVersionLinkService uses "RemoteVersionLink" as its entityName, not "Version".

Since:

v6.1

Method Summary

Modifier and Type	Method and Description
long	countByEntity(String entityName, Long entityId) Counts the number of properties that match the given entity.
long	countByEntityNameAndPropertyKey(String entityName, String key) Counts the number of properties that match the given entity name and property key.
void	delete(String entityName, Long entityId, String key) Deletes the stored value for an entity property, if it exists.
void	deleteByEntity(String entityName, Long entityId) Deletes all properties that are associated with the provided entity.
void	deleteByEntityNameAndPropertyKey(String entityName, String key) Deletes all properties that are associated with the provided entity name and property key.
boolean	exists(String entityName, Long entityId, String key) Returns whether or not a given property exists.
List<String>	findKeys(String entityName, Long entityId) Produces a list of entity property keys that match the provided entity name and entity id.
List<String>	findKeys(String entityName, String keyPrefix) Produces a list of entity property keys that match the provided entity name and key prefix.
Map<String,EntityProperty>	get(String entityName, Long entityId) Retrieve all entity properties by the entity name, entity id.
Map<String,EntityProperty>	get(String entityName, Long entityId, List<String> keys) Retrieve all entity properties by the entity name, entity id and the supplied keys
EntityProperty	get(String entityName, Long entityId, String key) Look up an entity property by the entity name, entity id, and property key.
int	getMaximumValueLength() The maximum allowed length (in characters) permitted for the String json value when calling put(String, Long, String, String) (or putDryRun(String, String, String)).
default void	put(ApplicationUser user, String entityName, Long entityId, String key, String json, java.util.function.BiFunction<ApplicationUser,EntityProperty,? extends EntityPropertySetEvent> eventFunction, boolean dispatchEvent) Set the value for an entity property, creating, updating, or deleting it as necessary.
void	put(ApplicationUser user, String entityName, Long entityId, String key, String json, com.atlassian.fugue.Function2<ApplicationUser,EntityProperty,? extends EntityPropertySetEvent> eventFunction, boolean dispatchEvent) Deprecated. In 7.0.0 Function2 has been deprecated in favour of BiFunction. Use put(com.atlassian.jira.user.ApplicationUser, String, Long, String, String, BiFunction, boolean) instead.
void	put(String entityName, Long entityId, String key, String json) Deprecated. In 6.2.3 as this method does not properly throw events. Use put(com.atlassian.jira.user.ApplicationUser, String, Long, String, String, BiFunction, boolean) instead.
void	putDryRun(String entityName, String key, String json) Performs all of the validation that would be performed during a put(String, Long, String, String) request, but does not actually store the value.
EntityPropertyQuery<?>	query() Returns a query object for finding, counting, or deleting properties with various restrictions.

Method Detail

get

@Nullable
EntityProperty get(String entityName,
                             Long entityId,
                             String key)

Look up an entity property by the entity name, entity id, and property key.

Parameters:

entityName - the entity name of the property

entityId - the entity ID of the property

key - the key of the property

Returns:

the matching property, or null if the property does not exist.

get

@Nullable
Map<String,EntityProperty> get(String entityName,
                                         Long entityId)

Retrieve all entity properties by the entity name, entity id.

Parameters:

entityName - the entity name of the property

entityId - the entity ID of the property

Returns:

a map with the property key as the map key of all properties for the entity.

get

@Nullable
Map<String,EntityProperty> get(String entityName,
                                         Long entityId,
                                         List<String> keys)

Retrieve all entity properties by the entity name, entity id and the supplied keys

Parameters:

entityName - the entity name of the property

entityId - the entity ID of the property

keys - list of property keys to match

Returns:

a map with the property key as the map key of all properties for the entity.

put

@Deprecated
void put(@Nonnull
                     String entityName,
                     @Nonnull
                     Long entityId,
                     @Nonnull
                     String key,
                     @Nullable
                     String json)

Deprecated. In 6.2.3 as this method does not properly throw events. Use put(com.atlassian.jira.user.ApplicationUser, String, Long, String, String, BiFunction, boolean) instead.

Set the value for an entity property, creating, updating, or deleting it as necessary.

Parameters:

entityName - the entity name for the property (maximum length 255). As explained in the class documentation, this value should be unique to the service creating the properties and will generally not be the same as the entity to which the properties are attached.

entityId - the entity ID for the property. In general, this will be the same as the ID of the owning entity; for example, the RemoteVersionLinkService uses the version ID for this value.

key - the key for the property (maximum length 255). This value should generally be suitable for a reverse lookup when the same data might be associated with multiple entities. For example, the RemoteVersionLinkService uses the global ID of the remote object, which is the same identifier used by applinks to identify a Confluence page, Bamboo project, etc.

json - the new value for the property, or null to delete it (maximum length is available by calling getMaximumValueLength())

Throws:

FieldTooLongJsonPropertyException - if any of the values exceed the maximum permitted length

InvalidJsonPropertyException - if json is malformed

IllegalArgumentException - if entityId is null, or if entityName or key is either null or blank.

See Also:

putDryRun(String, String, String)

put

@Deprecated
void put(ApplicationUser user,
                     @Nonnull
                     String entityName,
                     @Nonnull
                     Long entityId,
                     @Nonnull
                     String key,
                     @Nullable
                     String json,
                     com.atlassian.fugue.Function2<ApplicationUser,EntityProperty,? extends EntityPropertySetEvent> eventFunction,
                     boolean dispatchEvent)

Deprecated. In 7.0.0 Function2 has been deprecated in favour of BiFunction. Use put(com.atlassian.jira.user.ApplicationUser, String, Long, String, String, BiFunction, boolean) instead.

Set the value for an entity property, creating, updating, or deleting it as necessary.

Parameters:

user - The user performing the action. The event will be actioned as this user

entityName - the entity name for the property (maximum length 255). As explained in the class documentation, this value should be unique to the service creating the properties and will generally not be the same as the entity to which the properties are attached.

entityId - the entity ID for the property. In general, this will be the same as the ID of the owning entity; for example, the RemoteVersionLinkService uses the version ID for this value.

key - the key for the property (maximum length 255). This value should generally be suitable for a reverse lookup when the same data might be associated with multiple entities. For example, the RemoteVersionLinkService uses the global ID of the remote object, which is the same identifier used by applinks to identify a Confluence page, Bamboo project, etc.

json - the new value for the property, or null to delete it (maximum length is available by calling getMaximumValueLength())

eventFunction - the function that generates the event to be thrown. See EntityPropertyHelper for some functions that may be used to generate events

dispatchEvent - true if the method should dispatch an event after it is run.

Throws:

FieldTooLongJsonPropertyException - if any of the values exceed the maximum permitted length

InvalidJsonPropertyException - if json is malformed

IllegalArgumentException - if entityId is null, or if entityName or key is either null or blank.

See Also:

putDryRun(String, String, String)

put

default void put(ApplicationUser user,
                 @Nonnull
                 String entityName,
                 @Nonnull
                 Long entityId,
                 @Nonnull
                 String key,
                 @Nullable
                 String json,
                 java.util.function.BiFunction<ApplicationUser,EntityProperty,? extends EntityPropertySetEvent> eventFunction,
                 boolean dispatchEvent)

Set the value for an entity property, creating, updating, or deleting it as necessary.

Parameters:

user - The user performing the action. The event will be actioned as this user

entityName - the entity name for the property (maximum length 255). As explained in the class documentation, this value should be unique to the service creating the properties and will generally not be the same as the entity to which the properties are attached.

entityId - the entity ID for the property. In general, this will be the same as the ID of the owning entity; for example, the RemoteVersionLinkService uses the version ID for this value.

key - the key for the property (maximum length 255). This value should generally be suitable for a reverse lookup when the same data might be associated with multiple entities. For example, the RemoteVersionLinkService uses the global ID of the remote object, which is the same identifier used by applinks to identify a Confluence page, Bamboo project, etc.

json - the new value for the property, or null to delete it (maximum length is available by calling getMaximumValueLength())

eventFunction - the function that generates the event to be thrown. See EntityPropertyHelper for some functions that may be used to generate events

dispatchEvent - true if the method should dispatch an event after it is run.

Throws:

FieldTooLongJsonPropertyException - if any of the values exceed the maximum permitted length

InvalidJsonPropertyException - if json is malformed

IllegalArgumentException - if entityId is null, or if entityName or key is either null or blank.

Since:

7.0.0

See Also:

putDryRun(String, String, String)

putDryRun

void putDryRun(@Nonnull
               String entityName,
               @Nonnull
               String key,
               @Nullable
               String json)

Performs all of the validation that would be performed during a put(String, Long, String, String) request, but does not actually store the value.

Parameters:

entityName - as for put(String, Long, String, String)

key - as for put(String, Long, String, String)

json - as for put(String, Long, String, String)

Throws:

FieldTooLongJsonPropertyException - as for put(String, Long, String, String)

InvalidJsonPropertyException - as for put(String, Long, String, String)

IllegalArgumentException - as for put(String, Long, String, String)

See Also:

put(String, Long, String, String)

delete

void delete(@Nonnull
            String entityName,
            @Nonnull
            Long entityId,
            @Nonnull
            String key)

Deletes the stored value for an entity property, if it exists.

Parameters:

entityName - the entity name of the property to be deleted

entityId - the entity ID of the property to be deleted

key - the key of the property to be deleted

getMaximumValueLength

int getMaximumValueLength()

The maximum allowed length (in characters) permitted for the String json value when calling put(String, Long, String, String) (or putDryRun(String, String, String)). This value is currently 32,768, but this may change in the future.

query

EntityPropertyQuery<?> query()

Returns a query object for finding, counting, or deleting properties with various restrictions. See EntityPropertyQuery for usage and minimum requirements.

Returns:

the query object

findKeys

@Nonnull
List<String> findKeys(@Nonnull
                               String entityName,
                               @Nonnull
                               String keyPrefix)

Produces a list of entity property keys that match the provided entity name and key prefix. This convenience method is exactly equivalent to:

     query().entityName(entityName)
          .keyPrefix(keyPrefix)
          .findDistinctKeys()
 

Parameters:

entityName - the entity name for the entities that are associated with the properties.

keyPrefix - the prefix to apply for limiting which keys are returned; must not be null or a blank string

Returns:

the list of distinct matching keys, sorted in ascending alphabetical order

Throws:

IllegalArgumentException - if either entityName or keyPrefix is null or blank

findKeys

@Nonnull
List<String> findKeys(@Nonnull
                               String entityName,
                               @Nonnull
                               Long entityId)

Produces a list of entity property keys that match the provided entity name and entity id. This convenience method is exactly equivalent to:

     query().entityName(entityName)
          .entityId(entityId)
          .EntityPropertyQuery.ExecutableQuery.findKeys()
 

Parameters:

entityName - the entity name for the entities that are associated with the properties.

entityId - the id of the entity.

Returns:

the list of distinct matching keys, sorted in ascending alphabetical order

Throws:

IllegalArgumentException - if either entityName or entityId is null or blank

exists

boolean exists(@Nonnull
               String entityName,
               @Nonnull
               Long entityId,
               @Nonnull
               String key)

Returns whether or not a given property exists. This convenience method is equivalent to get(String, Long, String) != null, but does not actually retrieve the JSON data from the database, so it may have better performance characteristics when the JSON content is not needed.

Parameters:

entityName - the entity name for the property

entityId - the entity ID for the property

key - the key for the property

countByEntity

long countByEntity(@Nonnull
                   String entityName,
                   @Nonnull
                   Long entityId)

Counts the number of properties that match the given entity. This convenience method is exactly equivalent to:

     query().entityName(entityName)
          .entityId(entityId)
          .count()
 

Parameters:

entityName - the entity name of the owning entity

entityId - the entity ID of the owning entity

Returns:

the count of properties assigned to that entity

Throws:

IllegalArgumentException - if either entityName is null or blank or entityId is null.

countByEntityNameAndPropertyKey

long countByEntityNameAndPropertyKey(@Nonnull
                                     String entityName,
                                     @Nonnull
                                     String key)

Counts the number of properties that match the given entity name and property key. This convenience method is exactly equivalent to:

     query().entityName(entityName)
          .key(key)
          .count()
 

Parameters:

entityName - the entity name of the owning entities

key - the property key to look for

Returns:

the count of properties with that key which are assigned to entities with the given name

Throws:

IllegalArgumentException - if either entityName or key is null or blank

deleteByEntity

void deleteByEntity(@Nonnull
                    String entityName,
                    @Nonnull
                    Long entityId)

Deletes all properties that are associated with the provided entity. This convenience method is exactly equivalent to:

     query().entityName(entityName)
          .entityId(entityId)
          .delete()
 

Parameters:

entityName - the entity name for the properties

entityId - the entity ID for the properties

deleteByEntityNameAndPropertyKey

void deleteByEntityNameAndPropertyKey(@Nonnull
                                      String entityName,
                                      @Nonnull
                                      String key)

Deletes all properties that are associated with the provided entity name and property key. This convenience method is exactly equivalent to:

     query().entityName(entityName)
          .key(key)
          .delete()
 

Parameters:

entityName - the entity name for the properties

key - the property key for the properties