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

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:

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();

}