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 }