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}