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;
023import java.util.Set;
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     * @since 9.3
053     */
054    void tag(CoreSession session, String docId, String label);
055
056    /**
057     * Tags a document with a given tag.
058     *
059     * @param session the session
060     * @param docId the document id
061     * @param label the tag
062     * @param username the user associated to the tagging
063     * @deprecated since 9.3, username is not needed anymore
064     */
065    @Deprecated
066    void tag(CoreSession session, String docId, String label, String username);
067
068    /**
069     * Untags a document of the given tag
070     *
071     * @param session the session
072     * @param docId the document id
073     * @param label the tag, or {@code null} for all tags
074     */
075    void untag(CoreSession session, String docId, String label);
076
077    /**
078     * Untags a document of the given tag
079     *
080     * @param session the session
081     * @param docId the document id
082     * @param label the tag, or {@code null} for all tags
083     * @param username the user associated to the tagging
084     * @deprecated since 9.3, username is not needed anymore
085     */
086    @Deprecated
087    void untag(CoreSession session, String docId, String label, String username);
088
089    /**
090     * Returns whether or not the current session can untag tag on provided document.
091     *
092     * @param session the session
093     * @param docId the document id
094     * @param label the tag, or {@code null} for all tags
095     * @return whether or not the current session can untag provided document
096     * @since 8.4
097     */
098    boolean canUntag(CoreSession session, String docId, String label);
099
100    /**
101     * Gets the tags applied to a document.
102     *
103     * @param session the session
104     * @param docId the document id
105     * @return the list of tags
106     * @since 9.3
107     */
108    Set<String> getTags(CoreSession session, String docId);
109
110    /**
111     * Gets the tags applied to a document by a given user, or by all users.
112     *
113     * @param session the session
114     * @param docId the document id
115     * @param username the user name, or {@code null} for all users
116     * @return the list of tags
117     * @deprecated since 9.3, username is not needed anymore
118     */
119    @Deprecated
120    List<Tag> getDocumentTags(CoreSession session, String docId, String username);
121
122    /**
123     * Gets the tags applied to a document by a given user, or by all users.
124     * <p>
125     * Alternative method allowing to specify whether the core should be used for this query.
126     *
127     * @param session the session
128     * @param docId the document id
129     * @param username the user name, or {@code null} for all users
130     * @param useCore if true, the core should be used to retrieve tags.
131     * @return the list of tags
132     * @since 6.0
133     * @deprecated since 9.3, username and useCore are not needed anymore
134     */
135    @Deprecated
136    List<Tag> getDocumentTags(CoreSession session, String docId, String username, boolean useCore);
137
138    /**
139     * Removes all the tags applied to a document.
140     *
141     * @since 5.7.3
142     */
143    void removeTags(CoreSession session, String docId);
144
145    /**
146     * Copy all the tags applied to the source document to the destination document.
147     * <p>
148     * The tags are merged.
149     *
150     * @param srcDocId the source document id
151     * @param dstDocId the destination document id
152     * @since 5.7.3
153     */
154    void copyTags(CoreSession session, String srcDocId, String dstDocId);
155
156    /**
157     * Replace all the existing tags applied on the destination document by the ones applied on the source document.
158     *
159     * @param srcDocId the source document id
160     * @param dstDocId the destination document id
161     * @since 5.7.3
162     */
163    void replaceTags(CoreSession session, String srcDocId, String dstDocId);
164
165    /**
166     * Gets the documents to which a tag is applied.
167     *
168     * @param session the session
169     * @param label the tag
170     * @return the set of document ids
171     * @since 9.3
172     */
173    List<String> getTagDocumentIds(CoreSession session, String label);
174
175    /**
176     * Gets the documents to which a tag is applied.
177     *
178     * @param session the session
179     * @param label the tag
180     * @param username the user name, or {@code null} for all users
181     * @return the set of document ids
182     * @deprecated since 9.3, username is not needed anymore
183     */
184    @Deprecated
185    List<String> getTagDocumentIds(CoreSession session, String label, String username);
186
187    /**
188     * Gets the tag cloud for a set of documents (tags with weight corresponding to their popularity).
189     * <p>
190     * If a docId is passed, only documents under it are considered, otherwise all documents in the database are used.
191     * <p>
192     * The cloud is returned unsorted.
193     *
194     * @param session the session
195     * @param docId the document id under which to look, or {@code null} for all documents
196     * @param username the user name, or {@code null} for all users
197     * @param normalize null for no weight normalization (a count is returned), {@code FALSE} for 0-100 normalization,
198     *            {@code TRUE} for logarithmic 0-100 normalization
199     * @return the cloud (a list of weighted tags)
200     * @deprecated since 9.3, seems unused
201     */
202    @Deprecated
203    List<Tag> getTagCloud(CoreSession session, String docId, String username, Boolean normalize);
204
205    /**
206     * Gets suggestions for a given tag label prefix.
207     *
208     * @param session the session
209     * @param label the tag label prefix
210     * @return a list of tags
211     * @since 9.3
212     */
213    Set<String> getSuggestions(CoreSession session, String label);
214
215    /**
216     * Gets suggestions for a given tag label prefix.
217     *
218     * @param session the session
219     * @param label the tag label prefix
220     * @param username the user name, or {@code null} for all users
221     * @return a list of tags
222     * @deprecated since 9.3, username is not needed anymore
223     */
224    @Deprecated
225    List<Tag> getSuggestions(CoreSession session, String label, String username);
226
227    /**
228     * Features of the implementation of the service.
229     *
230     * @see TagService#hasFeature
231     * @since 9.3
232     */
233    enum Feature {
234        /** Tags are properties of the document itself. */
235        TAGS_BELONG_TO_DOCUMENT,
236    }
237
238    /**
239     * Checks if a feature is available.
240     *
241     * @since 9.3
242     */
243    boolean hasFeature(Feature feature);
244
245    /**
246     * Checks if document support tag.
247     *
248     * @since 9.3
249     */
250    boolean supportsTag(CoreSession session, String docId);
251
252}