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}