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}