001/*
002 * (C) Copyright 2009-2010 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Radu Darlea
016 *     Florent Guillaume
017 */
018
019package org.nuxeo.ecm.platform.tag;
020
021import java.util.List;
022
023import org.nuxeo.ecm.core.api.CoreSession;
024
025/**
026 * The Tag Service interface. It gathers the entire service API. The available capabilities are:
027 * <ul>
028 * <li>list the tags, either related or not to a document
029 * <li>create tags and taggings
030 * <li>obtain tag cloud
031 * </ul>
032 */
033public interface TagService {
034
035    String ID = "org.nuxeo.ecm.platform.tag.TagService";
036
037    /**
038     * Defines if tag service is enable.
039     *
040     * @return true if the underlying repository supports the tag feature
041     */
042    boolean isEnabled();
043
044    /**
045     * Tags a document with a given tag.
046     *
047     * @param session the session
048     * @param docId the document id
049     * @param label the tag
050     * @param username the user associated to the tagging
051     */
052    void tag(CoreSession session, String docId, String label, String username);
053
054    /**
055     * Untags a document of the given tag
056     *
057     * @param session the session
058     * @param docId the document id
059     * @param label the tag, or {@code null} for all tags
060     * @param username the user associated to the tagging
061     */
062    void untag(CoreSession session, String docId, String label, String username);
063
064    /**
065     * Gets the tags applied to a document by a given user, or by all users.
066     *
067     * @param session the session
068     * @param docId the document id
069     * @param username the user name, or {@code null} for all users
070     * @return the list of tags
071     */
072    List<Tag> getDocumentTags(CoreSession session, String docId, String username);
073
074    /**
075     * Gets the tags applied to a document by a given user, or by all users.
076     * <p>
077     * Alternative method allowing to specify whether the core should be used for this query.
078     *
079     * @param session the session
080     * @param docId the document id
081     * @param username the user name, or {@code null} for all users
082     * @param useCore if true, the core should be used to retrieve tags.
083     * @return the list of tags
084     * @since 6.0
085     */
086    List<Tag> getDocumentTags(CoreSession session, String docId, String username, boolean useCore);
087
088    /**
089     * Removes all the tags applied to a document.
090     *
091     * @since 5.7.3
092     */
093    void removeTags(CoreSession session, String docId);
094
095    /**
096     * Copy all the tags applied to the source document to the destination document.
097     * <p>
098     * The tags are merged.
099     *
100     * @param srcDocId the source document id
101     * @param dstDocId the destination document id
102     * @since 5.7.3
103     */
104    void copyTags(CoreSession session, String srcDocId, String dstDocId);
105
106    /**
107     * Replace all the existing tags applied on the destination document by the ones applied on the source document.
108     *
109     * @param srcDocId the source document id
110     * @param dstDocId the destination document id
111     * @since 5.7.3
112     */
113    void replaceTags(CoreSession session, String srcDocId, String dstDocId);
114
115    /**
116     * Gets the documents to which a tag is applied.
117     *
118     * @param session the session
119     * @param label the tag
120     * @param username the user name, or {@code null} for all users
121     * @return the set of document ids
122     */
123    List<String> getTagDocumentIds(CoreSession session, String label, String username);
124
125    /**
126     * Gets the tag cloud for a set of documents (tags with weight corresponding to their popularity).
127     * <p>
128     * If a docId is passed, only documents under it are considered, otherwise all documents in the database are used.
129     * <p>
130     * The cloud is returned unsorted.
131     *
132     * @param session the session
133     * @param docId the document id under which to look, or {@code null} for all documents
134     * @param username the user name, or {@code null} for all users
135     * @param normalize null for no weight normalization (a count is returned), {@code FALSE} for 0-100 normalization,
136     *            {@code TRUE} for logarithmic 0-100 normalization
137     * @return the cloud (a list of weighted tags)
138     */
139    List<Tag> getTagCloud(CoreSession session, String docId, String username, Boolean normalize);
140
141    /**
142     * Gets suggestions for a given tag label prefix.
143     *
144     * @param session the session
145     * @param label the tag label prefix
146     * @param username the user name, or {@code null} for all users
147     * @return a list of tags
148     */
149    List<Tag> getSuggestions(CoreSession session, String label, String username);
150
151}