@ExperimentalApi
public interface JsonEntityPropertyManager
JSON entity properties are similar to PropertySet
s
in that they are permitted to hold more or less arbitrary collections of data. There are, however, several
important differences:
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"
.
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 |
deleteByEntityNameAndEntityIds(String entityName,
List<Long> entityIds)
Deletes all properties that are associated with the provided entities.
|
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) ). |
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(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.
|
@Nullable EntityProperty get(String entityName, Long entityId, String key)
entityName
- the entity name of the propertyentityId
- the entity ID of the propertykey
- the key of the propertynull
if the property does not exist.@Nullable Map<String,EntityProperty> get(String entityName, Long entityId)
entityName
- the entity name of the propertyentityId
- the entity ID of the property@Nullable Map<String,EntityProperty> get(String entityName, Long entityId, List<String> keys)
entityName
- the entity name of the propertyentityId
- the entity ID of the propertykeys
- list of property keys to match@Deprecated void put(@Nonnull String entityName, @Nonnull Long entityId, @Nonnull String key, @Nullable String json)
put(com.atlassian.jira.user.ApplicationUser, String, Long, String, String, BiFunction, boolean)
instead.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()
)FieldTooLongJsonPropertyException
- if any of the values exceed the maximum permitted lengthInvalidJsonPropertyException
- if json
is malformedIllegalArgumentException
- if entityId
is null
, or if entityName
or
key
is either null
or blank.putDryRun(String, String, String)
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)
user
- The user performing the action. The event will be actioned as this userentityName
- 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 eventsdispatchEvent
- true if the method should dispatch an event after it is run.FieldTooLongJsonPropertyException
- if any of the values exceed the maximum permitted lengthInvalidJsonPropertyException
- if json
is malformedIllegalArgumentException
- if entityId
is null
, or if entityName
or
key
is either null
or blank.putDryRun(String, String, String)
void putDryRun(@Nonnull String entityName, @Nonnull String key, @Nullable String json)
put(String, Long, String, String)
request, but does not actually store the value.entityName
- as for put(String, Long, String, String)
key
- as for put(String, Long, String, String)
json
- as for put(String, Long, String, String)
FieldTooLongJsonPropertyException
- as for put(String, Long, String, String)
InvalidJsonPropertyException
- as for put(String, Long, String, String)
IllegalArgumentException
- as for put(String, Long, String, String)
put(String, Long, String, String)
void delete(@Nonnull String entityName, @Nonnull Long entityId, @Nonnull String key)
entityName
- the entity name of the property to be deletedentityId
- the entity ID of the property to be deletedkey
- the key of the property to be deletedint getMaximumValueLength()
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.EntityPropertyQuery<?> query()
EntityPropertyQuery
for usage and minimum requirements.@Nonnull List<String> findKeys(@Nonnull String entityName, @Nonnull String keyPrefix)
query()
.entityName(entityName)
.keyPrefix(keyPrefix)
.findDistinctKeys()
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 stringIllegalArgumentException
- if either entityName
or keyPrefix
is null
or blank@Nonnull List<String> findKeys(@Nonnull String entityName, @Nonnull Long entityId)
query()
.entityName(entityName)
.entityId(entityId)
.EntityPropertyQuery.ExecutableQuery.findKeys()
entityName
- the entity name for the entities that are associated with the properties.entityId
- the id of the entity.IllegalArgumentException
- if either entityName
or entityId
is null
or blankboolean exists(@Nonnull String entityName, @Nonnull Long entityId, @Nonnull String key)
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.entityName
- the entity name for the propertyentityId
- the entity ID for the propertykey
- the key for the propertylong countByEntity(@Nonnull String entityName, @Nonnull Long entityId)
query()
.entityName(entityName)
.entityId(entityId)
.count()
entityName
- the entity name of the owning entityentityId
- the entity ID of the owning entityIllegalArgumentException
- if either entityName
is null
or blank or entityId
is null
.long countByEntityNameAndPropertyKey(@Nonnull String entityName, @Nonnull String key)
query()
.entityName(entityName)
.key(key)
.count()
entityName
- the entity name of the owning entitieskey
- the property key to look forIllegalArgumentException
- if either entityName
or key
is null
or blankvoid deleteByEntity(@Nonnull String entityName, @Nonnull Long entityId)
query()
.entityName(entityName)
.entityId(entityId)
.delete()
entityName
- the entity name for the propertiesentityId
- the entity ID for the propertiesvoid deleteByEntityNameAndPropertyKey(@Nonnull String entityName, @Nonnull String key)
query()
.entityName(entityName)
.key(key)
.delete()
entityName
- the entity name for the propertieskey
- the property key for the propertiesCopyright © 2002-2022 Atlassian. All Rights Reserved.