001/*
002 * (C) Copyright 2009-2016 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Radu Darlea
018 *     Florent Guillaume
019 */
020package org.nuxeo.ecm.platform.tag;
021
022import java.util.List;
023
024import org.nuxeo.ecm.core.api.CoreSession;
025
026/**
027 * The Tag Service interface. It gathers the entire service API. The available capabilities are:
028 * <ul>
029 * <li>list the tags, either related or not to a document
030 * <li>create tags and taggings
031 * <li>obtain tag cloud
032 * </ul>
033 */
034public interface TagService {
035
036    String ID = "org.nuxeo.ecm.platform.tag.TagService";
037
038    /**
039     * Defines if tag service is enable.
040     *
041     * @return true if the underlying repository supports the tag feature
042     */
043    boolean isEnabled();
044
045    /**
046     * Tags a document with a given tag.
047     *
048     * @param session the session
049     * @param docId the document id
050     * @param label the tag
051     * @param username the user associated to the tagging
052     */
053    void tag(CoreSession session, String docId, String label, String username);
054
055    /**
056     * Untags a document of the given tag
057     *
058     * @param session the session
059     * @param docId the document id
060     * @param label the tag, or {@code null} for all tags
061     * @param username the user associated to the tagging
062     */
063    void untag(CoreSession session, String docId, String label, String username);
064
065    /**
066     * Returns whether or not the current session can untag tag on provided document.
067     * 
068     * @param session the session
069     * @param docId the document id
070     * @param label the tag, or {@code null} for all tags
071     * @return whether or not the current session can untag provided document
072     * @since 8.4
073     */
074    boolean canUntag(CoreSession session, String docId, String label);
075
076    /**
077     * Gets the tags applied to a document by a given user, or by all users.
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     * @return the list of tags
083     */
084    List<Tag> getDocumentTags(CoreSession session, String docId, String username);
085
086    /**
087     * Gets the tags applied to a document by a given user, or by all users.
088     * <p>
089     * Alternative method allowing to specify whether the core should be used for this query.
090     *
091     * @param session the session
092     * @param docId the document id
093     * @param username the user name, or {@code null} for all users
094     * @param useCore if true, the core should be used to retrieve tags.
095     * @return the list of tags
096     * @since 6.0
097     */
098    List<Tag> getDocumentTags(CoreSession session, String docId, String username, boolean useCore);
099
100    /**
101     * Removes all the tags applied to a document.
102     *
103     * @since 5.7.3
104     */
105    void removeTags(CoreSession session, String docId);
106
107    /**
108     * Copy all the tags applied to the source document to the destination document.
109     * <p>
110     * The tags are merged.
111     *
112     * @param srcDocId the source document id
113     * @param dstDocId the destination document id
114     * @since 5.7.3
115     */
116    void copyTags(CoreSession session, String srcDocId, String dstDocId);
117
118    /**
119     * Replace all the existing tags applied on the destination document by the ones applied on the source document.
120     *
121     * @param srcDocId the source document id
122     * @param dstDocId the destination document id
123     * @since 5.7.3
124     */
125    void replaceTags(CoreSession session, String srcDocId, String dstDocId);
126
127    /**
128     * Gets the documents to which a tag is applied.
129     *
130     * @param session the session
131     * @param label the tag
132     * @param username the user name, or {@code null} for all users
133     * @return the set of document ids
134     */
135    List<String> getTagDocumentIds(CoreSession session, String label, String username);
136
137    /**
138     * Gets the tag cloud for a set of documents (tags with weight corresponding to their popularity).
139     * <p>
140     * If a docId is passed, only documents under it are considered, otherwise all documents in the database are used.
141     * <p>
142     * The cloud is returned unsorted.
143     *
144     * @param session the session
145     * @param docId the document id under which to look, or {@code null} for all documents
146     * @param username the user name, or {@code null} for all users
147     * @param normalize null for no weight normalization (a count is returned), {@code FALSE} for 0-100 normalization,
148     *            {@code TRUE} for logarithmic 0-100 normalization
149     * @return the cloud (a list of weighted tags)
150     */
151    List<Tag> getTagCloud(CoreSession session, String docId, String username, Boolean normalize);
152
153    /**
154     * Gets suggestions for a given tag label prefix.
155     *
156     * @param session the session
157     * @param label the tag label prefix
158     * @param username the user name, or {@code null} for all users
159     * @return a list of tags
160     */
161    List<Tag> getSuggestions(CoreSession session, String label, String username);
162
163}