Page Comparison

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