001/*
002 * (C) Copyright 2009-2010 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 */
020
021package org.nuxeo.ecm.platform.tag;
022
023import java.util.List;
024
025import org.nuxeo.ecm.core.api.CoreSession;
026
027/**
028 * The Tag Service interface. It gathers the entire service API. The available capabilities are:
029 * <ul>
030 * <li>list the tags, either related or not to a document
031 * <li>create tags and taggings
032 * <li>obtain tag cloud
033 * </ul>
034 */
035public interface TagService {
036
037    String ID = "org.nuxeo.ecm.platform.tag.TagService";
038
039    /**
040     * Defines if tag service is enable.
041     *
042     * @return true if the underlying repository supports the tag feature
043     */
044    boolean isEnabled();
045
046    /**
047     * Tags a document with a given tag.
048     *
049     * @param session the session
050     * @param docId the document id
051     * @param label the tag
052     * @param username the user associated to the tagging
053     */
054    void tag(CoreSession session, String docId, String label, String username);
055
056    /**
057     * Untags a document of the given tag
058     *
059     * @param session the session
060     * @param docId the document id
061     * @param label the tag, or {@code null} for all tags
062     * @param username the user associated to the tagging
063     */
064    void untag(CoreSession session, String docId, String label, String username);
065
066    /**
067     * Gets the tags applied to a document by a given user, or by all users.
068     *
069     * @param session the session
070     * @param docId the document id
071     * @param username the user name, or {@code null} for all users
072     * @return the list of tags
073     */
074    List<Tag> getDocumentTags(CoreSession session, String docId, String username);
075
076    /**
077     * Gets the tags applied to a document by a given user, or by all users.
078     * <p>
079     * Alternative method allowing to specify whether the core should be used for this query.
080     *
081     * @param session the session
082     * @param docId the document id
083     * @param username the user name, or {@code null} for all users
084     * @param useCore if true, the core should be used to retrieve tags.
085     * @return the list of tags
086     * @since 6.0
087     */
088    List<Tag> getDocumentTags(CoreSession session, String docId, String username, boolean useCore);
089
090    /**
091     * Removes all the tags applied to a document.
092     *
093     * @since 5.7.3
094     */
095    void removeTags(CoreSession session, String docId);
096
097    /**
098     * Copy all the tags applied to the source document to the destination document.
099     * <p>
100     * The tags are merged.
101     *
102     * @param srcDocId the source document id
103     * @param dstDocId the destination document id
104     * @since 5.7.3
105     */
106    void copyTags(CoreSession session, String srcDocId, String dstDocId);
107
108    /**
109     * Replace all the existing tags applied on the destination document by the ones applied on the source document.
110     *
111     * @param srcDocId the source document id
112     * @param dstDocId the destination document id
113     * @since 5.7.3
114     */
115    void replaceTags(CoreSession session, String srcDocId, String dstDocId);
116
117    /**
118     * Gets the documents to which a tag is applied.
119     *
120     * @param session the session
121     * @param label the tag
122     * @param username the user name, or {@code null} for all users
123     * @return the set of document ids
124     */
125    List<String> getTagDocumentIds(CoreSession session, String label, String username);
126
127    /**
128     * Gets the tag cloud for a set of documents (tags with weight corresponding to their popularity).
129     * <p>
130     * If a docId is passed, only documents under it are considered, otherwise all documents in the database are used.
131     * <p>
132     * The cloud is returned unsorted.
133     *
134     * @param session the session
135     * @param docId the document id under which to look, or {@code null} for all documents
136     * @param username the user name, or {@code null} for all users
137     * @param normalize null for no weight normalization (a count is returned), {@code FALSE} for 0-100 normalization,
138     *            {@code TRUE} for logarithmic 0-100 normalization
139     * @return the cloud (a list of weighted tags)
140     */
141    List<Tag> getTagCloud(CoreSession session, String docId, String username, Boolean normalize);
142
143    /**
144     * Gets suggestions for a given tag label prefix.
145     *
146     * @param session the session
147     * @param label the tag label prefix
148     * @param username the user name, or {@code null} for all users
149     * @return a list of tags
150     */
151    List<Tag> getSuggestions(CoreSession session, String label, String username);
152
153}