1 /*
2 * Copyright (C) 2003-2008 eXo Platform SAS.
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Affero General Public License
6 * as published by the Free Software Foundation; either version 3
7 * of the License, or (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, see<http://www.gnu.org/licenses/>.
16 */
17 package org.exoplatform.services.cms.folksonomy;
18
19 import java.util.List;
20 import java.util.Set;
21
22 import javax.jcr.Node;
23
24 import org.exoplatform.services.jcr.ext.common.SessionProvider;
25 import org.exoplatform.services.jcr.ext.distribution.DataDistributionType;
26
27 /**
28 * Manages all tags and their styles.
29 * Currently, it just supports adding/editing/removing private and public tags.
30 *
31 * @LevelAPI Experimental
32 */
33 public interface NewFolksonomyService {
34
35 /** Property name TAG_RATE_PROP */
36 final public static String TAG_RATE_PROP = "exo:styleRange";
37
38 /** Property name HTML_STYLE_PROP */
39 final public static String HTML_STYLE_PROP = "exo:htmlStyle";
40
41 /** Property name EXO_TOTAL */
42 final static public String EXO_TOTAL = "exo:total";
43
44 /** Property name EXO_TAGGED */
45 final static public String EXO_TAGGED = "exo:tagged";
46
47 /** Property name EXO_UUID */
48 final static public String EXO_UUID = "exo:uuid";
49
50 /** Property name EXO_TAGSTYLE */
51 final static public String EXO_TAGSTYLE = "exo:tagStyle";
52
53 /** Property name PUBLIC */
54 final static public int PUBLIC = 0;
55
56 /** Property name GROUP */
57 final static public int GROUP = 3;
58
59 /** Property name SITE */
60 final static public int SITE = 2;
61
62 /** Property name PRIVATE */
63 final static public int PRIVATE = 1;
64
65 /**
66 * Adds a private tag to a document. A folksonomy link will be created in the tag node.
67 *
68 * @param tagsName The array of tag names.
69 * @param documentNode The document node to which the private tag is added.
70 * @param workspace Name of the workspace that contains the document node.
71 * @param userName The user who added the private tag.
72 * @throws Exception The exception
73 */
74 public void addPrivateTag(String[] tagsName,
75 Node documentNode,
76 String workspace,
77 String userName) throws Exception;
78
79 /**
80 * Adds a group tag to a document. A folksonomy link will be created in the tag node.
81 *
82 * @param tagsName The array of tag names.
83 * @param documentNode The document node to which the group tag is added.
84 * @param workspace Name of the workspace that contains the document node.
85 * @param roles Roles of the user who added the group tag.
86 * @throws Exception The exception
87 */
88 public void addGroupsTag(String[] tagsName,
89 Node documentNode,
90 String workspace,
91 String[] roles) throws Exception;
92
93 /**
94 * Adds a public tag to a document. A folksonomy link will be created in the tag node.
95 *
96 * @param treePath Path of the folksonomy tree.
97 * @param tagsName The array of the tag names.
98 * @param documentNode The document node to which the public tag is added.
99 * @param workspace Name of the workspace that contains the document node.
100 * @throws Exception The exception
101 */
102 public void addPublicTag(String treePath,
103 String[] tagsName,
104 Node documentNode,
105 String workspace) throws Exception;
106
107 /**
108 * Adds a site tag to a document. A folksonomy link will be created in the tag node.
109 *
110 * @param siteName The site name.
111 * @param tagsName The array of tag names.
112 * @param node The document node to which the site tag is added.
113 * @param workspace Name of the workspace that contains the document node.
114 * @throws Exception The exception
115 */
116 public void addSiteTag(String siteName,
117 String[] tagsName,
118 Node node,
119 String workspace) throws Exception;
120
121 /**
122 * Gets all private tags of a given user.
123 *
124 * @param userName Name of the given user.
125 * @return The list of private tags.
126 * @throws Exception The exception
127 */
128 public List<Node> getAllPrivateTags(String userName) throws Exception;
129
130 /**
131 * Gets all public tags.
132 *
133 * @param treePath Path of the folksonomy tree.
134 * @param workspace Name of the workspace that contains public tags.
135 * @return The list of public tags.
136 * @throws Exception The exception
137 */
138 public List<Node> getAllPublicTags(String treePath, String workspace) throws Exception;
139
140 /**
141 * Gets all tags of groups that a given user belongs to.
142 *
143 * @param role Roles of the given user.
144 * @param workspace Name of the workspace that contains tags.
145 * @return The tags of groups.
146 * @throws Exception The exception
147 */
148 public List<Node> getAllGroupTags(String[] role, String workspace) throws Exception;
149
150 /**
151 * Gets all tags of a group that a given user belongs to.
152 *
153 * @param role Roles of the given user.
154 * @param workspace Name of the workspace that contains tags.
155 * @return The tags of the given group.
156 * @throws Exception The exception
157 */
158 public List<Node> getAllGroupTags(String role, String workspace) throws Exception;
159
160 /**
161 * Gets all site tags.
162 *
163 * @param siteName The site name.
164 * @param workspace Name of the workspace that contains the site tags.
165 * @return The list of site tags.
166 * @throws Exception The exception
167 */
168 public List<Node> getAllSiteTags(String siteName, String workspace) throws Exception;
169
170 /**
171 * Gets all documents which are marked with given tags and that are located in a selected path.
172 *
173 * @param selectedPath Parent path to filter nodes
174 * @param tagPaths list of tags JCR paths
175 * @param workspace the workspace of resulted nodes
176 * @param sessionProvider use session provider to query JCR
177 *
178 * @return the filtered {@link List} of {@link Node}
179 *
180 * @throws Exception
181 */
182 List<Node> getAllDocumentsByTagsAndPath(String selectedPath,
183 Set<String> tagPaths,
184 String workspace,
185 SessionProvider sessionProvider) throws Exception;
186
187 /**
188 * Gets all documents which are marked with a given tag.
189 *
190 * @param tagPath Path of the given tag.
191 * @param workspace Name of the workspace that contains the given tag.
192 * @param sessionProvider The session provider.
193 * @return The list of documents.
194 * @throws Exception The exception
195 */
196 public List<Node> getAllDocumentsByTag(String tagPath,
197 String workspace,
198 SessionProvider sessionProvider) throws Exception;
199
200 /**
201 * Gets a tag style.
202 *
203 * @param tagPath Path to the tag.
204 * @param workspace Name of the workspace that contains the tag.
205 * @return Style values of the tag.
206 * @throws Exception The exception
207 */
208 public String getTagStyle(String tagPath, String workspace) throws Exception;
209
210 /**
211 * Adds a tag style.
212 *
213 * @param styleName Name of the tag style.
214 * @param tagRange The number of times the tag is used for the tag style.
215 * @param htmlStyle The tag style.
216 * @param workspace Name of the workspace that contains the tag style.
217 * @throws Exception The exception
218 */
219 public void addTagStyle(String styleName,
220 String tagRange,
221 String htmlStyle,
222 String workspace) throws Exception;
223
224 /**
225 * Updates a tag style.
226 *
227 * @param styleName Name of the tag style.
228 * @param tagRange The number of times the tag is used for the tag style.
229 * @param htmlStyle The tag style.
230 * @param workspace Name of the workspace that contains the tag style.
231 * @throws Exception The exception
232 */
233 public void updateTagStyle(String styleName,
234 String tagRange,
235 String htmlStyle,
236 String workspace) throws Exception;
237
238 /**
239 * Gets all tag styles of a folksonomy tree.
240 *
241 * @param workspace Name of the workspace that contains the tag styles.
242 * @return The tag styles.
243 * @throws Exception The exception
244 */
245 public List<Node> getAllTagStyle(String workspace) throws Exception;
246
247 /**
248 * Initializes all tag style plugins.
249 *
250 * @throws Exception The exception
251 */
252 public void init() throws Exception;
253
254 /**
255 * Initializes the predefined tag permission list
256 * @throws Exception
257 */
258 public void initTagPermissionListCache() throws Exception;
259
260 /**
261 * Removes tag from a given document.
262 *
263 * @param tagPath Path of the tag.
264 * @param document The document from which the tag is removed.
265 * @throws Exception The exception
266 */
267 public void removeTagOfDocument(String tagPath, Node document, String workspace) throws Exception;
268
269 /**
270 * Removes a tag.
271 *
272 * @param tagPath Path of the tag.
273 * @param workspace Name of the workspace that contains the removed tag.
274 * @throws Exception The exception
275 */
276 public void removeTag(String tagPath, String workspace) throws Exception;
277
278 /**
279 * Renames a tag.
280 *
281 * @param tagPath Path of the tag.
282 * @param newTagName New name of the tag.
283 * @param workspace Name of the workspace that contains the renamed tag.
284 * @return The renamed tag.
285 * @throws Exception The exception
286 */
287 public Node modifyTagName(String tagPath, String newTagName, String workspace) throws Exception;
288
289 /**
290 * Renames a public tag.
291 *
292 * @param tagPath Path of the public tag.
293 * @param newTagName New name of the public tag.
294 * @param workspace Name of the workspace that contains the renamed public tag.
295 * @param treeTagPath Path of the folksonomy tree.
296 * @return The renamed public tag.
297 * @throws Exception The exception
298 */
299 public Node modifyPublicTagName(String tagPath, String newTagName, String workspace, String treeTagPath) throws Exception;
300
301 /**
302 * Gets all tags linked to a given document.
303 *
304 * @param documentNode The document node.
305 * @param workspace Name of the workspace that contains all tags.
306 * @return The list of tags.
307 * @throws Exception The exception
308 */
309 public List<Node> getLinkedTagsOfDocument(Node documentNode, String workspace) throws Exception;
310
311 /**
312 * Get all tags linked to a given document by scope.
313 *
314 * @param scope The tag's scope.
315 * @param documentNode The document node.
316 * @param workspace Name of the workspace that contains all tags.
317 * @return The list of tags.
318 * @throws Exception The exception
319 */
320 public List<Node> getLinkedTagsOfDocumentByScope(int scope,
321 String value,
322 Node documentNode,
323 String workspace) throws Exception;
324
325 /**
326 * Removes all tags linked to the child nodes of a given node.
327 *
328 * @param node The given node.
329 * @param workspace Name of the workspace that contains all tags.
330 * @param username The user who removed all tags.
331 * @throws Exception The exception
332 */
333 public void removeTagsOfNodeRecursively(Node node,
334 String workspace,
335 String username,
336 String groups) throws Exception;
337
338 /**
339 * Adds a given user or group to the list of tag permissions.
340 *
341 * @param usersOrGroups Name of the given user or group.
342 */
343 public void addTagPermission(String usersOrGroups);
344
345 /**
346 * Removes a given user or group from the list of tag permissions.
347 *
348 * @param usersOrGroups Name of the user or group.
349 */
350 public void removeTagPermission(String usersOrGroups);
351
352 /**
353 * Gets a list of users and groups who have the tag permission.
354 *
355 * @return The list of users and groups.
356 */
357 public List<String> getTagPermissionList();
358
359 /**
360 * Checks if a given user has the "edit tag" permission.
361 *
362 * @param scope The tag's scope.
363 * @param memberships The memberships.
364 * @return "True" if the given user has the "edit tag" permission. Otherwise, it returns "false".
365 */
366 public boolean canEditTag(int scope, List<String> memberships);
367
368 /**
369 * Gets names of all tags under a given scope.
370 *
371 * @param workspace Name of the workspace that contains the tags.
372 * @param scope The tags' scope.
373 * @param value Path of the folksonomy tree.
374 * @return The tag names.
375 * @throws Exception The exception
376 */
377 public List<String> getAllTagNames(String workspace, int scope, String value) throws Exception;
378
379 /**
380 * Gets a type of data distribution.
381 *
382 * @return The type of data distribution.
383 */
384 public DataDistributionType getDataDistributionType();
385
386 }