1 package org.argeo.connect.resources;
2
3 import java.util.List;
4
5 import javax.jcr.Node;
6 import javax.jcr.NodeIterator;
7 import javax.jcr.RepositoryException;
8 import javax.jcr.Session;
9
10 import org.argeo.connect.AppService;
11
12 /**
13 * Provides method interfaces to manage resources like Labels, Catalogues or Tag
14 * like multi value properties in a People repository.
15 *
16 * The correct instance of this interface must be acquired through the
17 * peopleService.
18 */
19 public interface ResourcesService extends AppService {
20
21 /* LABEL FOR NODE TYPES AND PROPERTY NAMES MANAGEMENT */
22 /**
23 * Returns a canonical English label for each of the JCR Property or node
24 * types defined in the current People Repository. If no such label is
25 * defined, returns the given itemName
26 *
27 **/
28 public String getItemDefaultEnLabel(String itemName);
29
30 /**
31 * Returns a label for each of the JCR property name or node type defined in
32 * the current People Repository in a internationalised context. If the
33 * correct item label is not found for this language, the English label is
34 * returned. If such a label is not defined, it returns the item name.
35 *
36 **/
37 public String getItemLabel(String itemName, String langIso);
38
39 /* PREDEFINED TEMPLATES AND CORRESPONDING CATALOGUES */
40 /**
41 * Returns the predefined possible English values of a property of a given
42 * node type as defined in the current People Repository and that match the
43 * corresponding filter. For the time being, a like "%value%" is assumed.
44 *
45 * It returns an empty list if the corresponding template is not found, if
46 * it has no property with such a name or if the filter does not match any
47 * of the predefined values.
48 *
49 * @param session
50 * @param templateId
51 * generally, the corresponding NodeType
52 * @param propertyName
53 * @param filter
54 * @return a <code>List<String></code> of status
55 */
56 public List<String> getTemplateCatalogue(Session session,
57 String templateId, String propertyName, String filter);
58
59 /**
60 * Returns the predefined possible English values as defined in the passed
61 * template node and that match the corresponding filter. For the time
62 * being, a like "%value%" is assumed.
63 *
64 * It returns an empty the template does not have a with such a name or if
65 * the filter does not match any of the predefined values.
66 *
67 * @param templateNode
68 * the template, must not be null
69 * @param propertyName
70 * @param filter
71 * @return a <code>List<String></code> of status
72 */
73 public List<String> getTemplateCatalogue(Node templateNode,
74 String propertyName, String filter);
75
76 /**
77 *
78 * @param session
79 * @param nodeType
80 * @param templateId
81 * optional distinct id for this template
82 * @return
83 */
84 public Node createTemplateForType(Session session, String nodeType,
85 String templateId);
86
87 /**
88 *
89 * @param session
90 * @param templateId
91 * the template ID, it is by default the nodeType of the node for
92 * which this node is a template
93 * @return
94 */
95 public Node getNodeTemplate(Session session, String templateId);
96
97 /**
98 * Retrieves all entities which property has the given value
99 *
100 * @param session
101 * @param entityType
102 * @param propName
103 * @param value
104 * @return
105 */
106 public NodeIterator getCatalogueValueInstances(Session session,
107 String entityType, String propName, String value);
108
109 /**
110 * Change the value of a given template catalogue. It also updates this
111 * value in all business objects of the repository that have this value.
112 *
113 * If newValue is null it will only remove old value and unmark all entities
114 *
115 * TODO do this in a transaction and revert if the process is unsuccessful.
116 */
117 public void updateCatalogueValue(Node templateNode, String taggableType,
118 String propertyName, String oldValue, String newTitle);
119
120 /* TAG LIKE PROPERTIES MANAGEMENT */
121 /**
122 * @param session
123 * with write rights
124 * @param tagId
125 * An optional ID to differentiate distinct parent that might be
126 * similar
127 * @param tagInstanceType
128 * The node type of the corresponding resources. It defines the
129 * created parent if tagId is null
130 * @param codePropName
131 * The name of the property that provides the code in case the
132 * string we store in the taggable multi value property is not
133 * the label that has to be displayed
134 * @param taggableParentPath
135 * Absolute path to parent of the taggable nodes
136 * @param taggableNodeType
137 * Node type of the taggable nodes
138 * @param taggablePropName
139 * Name of the multi value property of the taggable node in which
140 * the corresponding tag is stored
141 * @return the newly created parent for tag instances
142 */
143 public Node createTagLikeResourceParent(Session session, String tagId,
144 String tagInstanceType, String codePropName,
145 String taggableParentPath, String taggableNodeType,
146 String taggablePropName);
147
148 /**
149 * @param session
150 * with write rights
151 * @param tagId
152 * An optional ID to differentiate distinct parent that might be
153 * similar
154 * @param tagInstanceType
155 * The node type of the corresponding resources. It defines the
156 * created parent if tagId is null
157 * @param codePropName
158 * The name of the property that provides the code in case the
159 * string we store in the taggable multi value property is not
160 * the label that has to be displayed
161 * @param taggableParentPath
162 * Absolute path to parent of the taggable nodes
163 * @param taggableNodeType
164 * Node type of the taggable nodes
165 * @param taggablePropNames
166 * Names of the multi value property of the taggable node in
167 * which the corresponding tag is stored
168 * @return the newly created parent for tag instances
169 */
170 public Node createTagLikeResourceParent(Session session, String tagId,
171 String tagInstanceType, String codePropName,
172 String taggableParentPath, String taggableNodeType,
173 List<String> taggablePropNames);
174
175 /**
176 * Retrieves the parent for tag instances that correspond to this ID or null
177 * if non has been found
178 *
179 * @param session
180 * @param tagId
181 * @return
182 */
183 public Node getTagLikeResourceParent(Session session, String tagId);
184
185 /**
186 * Register a new tag if such a tag does not exist, does nothing otherwise.
187 * Corresponding session is not saved
188 *
189 * Comparison is case *insensitive* and a trim() is applied on the passed
190 * String
191 *
192 * @param session
193 * @param tagId
194 * @param tagValue
195 * @return
196 * @throws RepositoryException
197 */
198 public Node registerTag(Session session, String tagId, String tagValue)
199 throws RepositoryException;
200
201 /**
202 * Register a new tag if a tag with such a code does not yet exist, returns
203 * the existing one otherwise. Corresponding session is not saved
204 *
205 * Comparison of the code is case *sensitive*.
206 *
207 * A trim() is applied on the passed tagValue before it is stored
208 *
209 * TODO also make a check if a tag already has such a value and prevent
210 * creation in this case. It is not blocker yet because we only use encode
211 * tags for country and languages that should not be manually updated
212 *
213 * @param session
214 * @param tagId
215 * @param tagCode
216 * @param tagValue
217 * @return
218 * @throws RepositoryException
219 */
220 public Node registerTag(Session session, String tagId, String tagCode,
221 String tagValue) throws RepositoryException;
222
223 /**
224 * Retrieve the instance node given its value or code if it is an encodedTag
225 * or null if such a tag has not yet been registered
226 *
227 * Comparison is case insensitive and a trim() is applied on the passed
228 * String for not encoded tag
229 */
230 public Node getRegisteredTag(Session session, String tagId, String tag);
231
232 /**
233 * Retrieves the instance node given its value or code if it is an
234 * encodedTag or null if such a tag has not yet been registered
235 *
236 * Comparison is case insensitive and a trim() is applied on the passed
237 * String for not encoded tag
238 */
239 public Node getRegisteredTag(Node tagInstanceParent, String tag);
240
241 /**
242 * Retrieves the value of an encoded tag or null if such a tag has not yet
243 * been registered
244 */
245 public String getEncodedTagValue(Session session, String tagId, String code);
246
247 /**
248 * Retrieves the code of an encoded tag given its English value or null if
249 * no such tag exists.
250 *
251 * WARNING: if two tags have the same value first found code will be
252 * returned see {@link registerTag(Session session, String tagId, String
253 * tagCode, String tagValue)}
254 */
255 public String getEncodedTagCodeFromValue(Session session, String tagId,
256 String value);
257
258 /**
259 * Shortcut to retrieve a string that concatenates the corresponding values
260 * of a multi value property that refers to multiple encoded tags
261 *
262 * @return
263 */
264 public String getEncodedTagValuesAsString(String tagId, Node taggedNode,
265 String propertyName, String separator);
266
267 /**
268 * Change the value of an already registered tag that does not rely on a
269 * code (e.g. the value that is stored in the various corresponding
270 * multi-value property). It also updates this value in all business objects
271 * of the repository that have this tag.
272 *
273 * TODO do this in a transaction and revert if the process is unsuccessful.
274 * TODO rather throw an exception than returning false
275 */
276 public boolean updateTag(Node tagInstance, String newValue)
277 throws RepositoryException;
278
279 /**
280 * Unregister an existing tag and remove all references to this tag on all
281 * nodes under the tagableParentPath that have this tag
282 */
283 public void unregisterTag(Session session, String tagId, String tag);
284
285 /**
286 * Retrieves all entities that have this tag key
287 *
288 * @param key
289 * the code in case of an encoded tag, the value itself otherwise
290 * @return null if the corresponding tag parent is not found, and a node
291 * iterator (that might be empty) otherwise
292 */
293 public NodeIterator getTaggedEntities(Session session, String tagId,
294 String key);
295
296 /**
297 * Retrieves all entities that have this key
298 *
299 * @param key
300 * the code in case of an encoded tag, the value itself otherwise
301 */
302 public NodeIterator getTaggedEntities(Node tagInstancesParent, String key);
303
304 /**
305 * Browses the repository using the parameters stored in the tagParent node
306 * and creates a new tag instance for all new value found in the taggable
307 * property of one of the valid node. It is meant to update the tag
308 * referential after importing entity instances that are tagged.
309 *
310 * Please note that newly created encoded tags will be created by default
311 * with a label that is also the code. For the time being, this must be
312 * later manually fixed via the system UI.
313 */
314 public void refreshKnownTags(Session session, String tagId);
315
316 /**
317 * Browses the repository using the parameters stored in the tagParent node
318 * and creates a new tag instance for all new value found in the taggable
319 * property of one of the valid node. It is meant to update the tag
320 * referential after importing entity instances that are tagged.
321 *
322 * Please note that newly created encoded tags will be created by default
323 * with a label that is also the code. For the time being, this must be
324 * later manually fixed via the system UI.
325 */
326 public void refreshKnownTags(Node tagParent);
327
328 /**
329 *
330 * @param session
331 * @param tagId
332 * @param filter
333 * @return the value of the known instances for this ID. Note that in the
334 * case of an encoded tag, the returned list contains values of the
335 * tags, not the codes but the filter applies on both (with a or)
336 */
337 public List<String> getRegisteredTagValueList(Session session,
338 String tagId, String filter);
339
340 /**
341 * Count members that have such a tag in the corresponding taggable sub tree
342 */
343 public long countMembers(Node tag);
344
345
346 public boolean canCreateTag(Session session);
347
348 }