How-to use our Java API

We exported our core service to allow other developers to access the metadata within their app or via Groovy scripts (further details about dependency injection : https://bitbucket.org/atlassian/atlassian-spring-scanner/src/master/ ).

Our core service implements the following MetadataService interface (>= version 4.5.0).

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 package com.osoboo.jira.metadata; import com.atlassian.activeobjects.tx.Transactional; import com.atlassian.annotations.ExperimentalApi; import com.atlassian.annotations.Internal; import java.util.Collection; /** * Core Service to load / store / delete metadata entities. * * @author Andreas Spall * */ @Transactional public interface MetadataService { /** Maximum amount of search results */ public final static int MAX_RESULT_LIMIT = 500; /** Default amount of search results */ public final static int MAX_RESULT_DEFAULT = 100; /** * Saves the passed value for the enrichedObject (e.g. User, Project, ...) / key combination with * hidden false * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param key the key specified by the user * @param value the value entered by the user */ void save(Object enrichedObject, String key, String value); /** * Saves the passed value for the enrichedObject / key combination. * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param key the key specified by the user * @param value the value entered by the user * @param hidden true : the value should not be displayed to the user */ void save(Object enrichedObject, String key, String value, boolean hidden); /** * Saves the passed value for the enrichedObject / key combination. * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param key the key specified by the user * @param value the value entered by the user * @param group the grouping (specified by the user) is used in the UI to represent individual metadata values to a group of values. * @param hidden true : the value should not be displayed to the user */ void save(Object enrichedObject, String key, String value, String group, boolean hidden); /** * Returns all metadata objects for the passed enriched Object * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param includeHidden the hidden values will be included in the result list * @param startAt the index of the first metadata value to return (0-based) * @param maxResults the maximum number of metadata values to return * @return returns all metadata objects for the passed enriched Object */ JiraMetadata[] getMetadata(Object enrichedObject, boolean includeHidden, int startAt, int maxResults); /** * Returns the JiraMetadata object or null (if the metadata entity doesn't exist or is hidden). * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param key the key specified by the user * @return the JiraMetadata object or null (if the metadata entity doesn't exist or is hidden). */ JiraMetadata getMetadata(Object enrichedObject, String key); /** * Returns the metadata for the passed enriched Object and key (and ignores the hidden flag) * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param key the key specified by the user * @return the JiraMetadata object or null (if the metadata entity doesn't exist) */ JiraMetadata getAllMetadata(Object enrichedObject, String key); /** * Deletes the metadata specified by the enriched Object and the unique id * of the metadata. * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param id the entity id */ void delete(Object enrichedObject, int id); /** * Deletes the passed metadata object. * @param metadata the to delete metadata entity */ void delete(JiraMetadata metadata); /** * Returns the metadata value for the passed enrichedObject / key * combination. * * @param enrichedObject the enriched object (e.g. User, Project, ...) * @param key the key specified by the user * @return the metadata value or an empty string */ String getMetadataValue(Object enrichedObject, String key); /** * Internal api : do not use : Will return all matching versions/components/... for passed key and value combination * @param enrichedClassIdentifierAsString version/component/project/user/group * @param userKey the metadata key * @param userValue the metadata value * @return all matching versions/components/... for passed key and value combination */ @Internal Collection<JiraMetadata> getMetadata(String enrichedClassIdentifierAsString, String userKey, String userValue); /** * @deprecated Use {@link #getMetadata(Object, boolean, int, int)} */ @Deprecated Collection<JiraMetadata> getMetadata(Object enrichedObject); /** * @deprecated Use {@link #getMetadata(Object, boolean, int, int)} */ @Deprecated Collection<JiraMetadata> getAllMetadata(Object enrichedObject); }

 

The JiraMetadata class used in the service has the following implementation:

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 package com.osoboo.jira.metadata; import net.java.ao.Accessor; import net.java.ao.Entity; import net.java.ao.Mutator; import net.java.ao.Preload; import net.java.ao.schema.StringLength; /** * The Metadata Entity. The unique key is a combination of userKey (specified by the user) * and enrichedObjectKey (the identifier of the object that has been enriched with metadata). * * @author Andreas Spall * */ @Preload public interface JiraMetadata extends Entity { /** * The calculated identifier of the object that has been enriched with metadata * (e.g. com.atlassian.jira.project.Project:OS for the project os). * @return the calculated identifier */ String getEnrichedObjectKey(); /** * The calculated identifier of the object that has been enriched with metadata * (e.g. com.atlassian.jira.project.Project:OS for the project os). * @param enrichedObjectKey calculated identifier */ void setEnrichedObjectKey(String enrichedObjectKey); /** * The key (specified by the user) for the metadata (e.g. Telephone, In Time, Risk, Management Summary). * @return the metadata user key */ String getUserKey(); /** * The key (specified by the user) for the metadata (e.g. Telephone, In Time, Risk, Management Summary). * @param userKey the metadata user key */ void setUserKey(String userKey); /** * The grouping (specified by the user) is used in the UI to represent individual metadata values to a group of values. * @return the users grouping value */ String getUserGrouping(); /** * The grouping (specified by the user) is used in the UI to represent individual metadata values to a group of values. * @param userGrouping the users grouping value */ void setUserGrouping(String userGrouping); /** * The value (specified by the user) of the metadata. * @return the value specified by the user */ @Accessor("UserValueLong") @StringLength(StringLength.UNLIMITED) String getUserValue(); /** *The value (specified by the user) of the metadata. * @param userValue the value specified by the user */ @Mutator("UserValueLong") @StringLength(StringLength.UNLIMITED) void setUserValue(String userValue); /** * The hidden value indicates that the value should not be displayed in the UI. * @param hidden true if the metadata should not be shown in the UI (default is false) */ void setHidden(boolean hidden); /** * The hidden value indicates that the value should not be displayed in the UI. * @return true if the metadata should not be shown in the UI */ boolean isHidden(); }