From 8c7782027f9289599e06f927d9d88c29d6d4e1ea Mon Sep 17 00:00:00 2001 From: Jon Cox Date: Wed, 16 May 2007 03:42:15 +0000 Subject: [PATCH] Point checkin for link management, plus more docs for AttributeService. git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@5688 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261 --- .../cmr/attributes/AttributeService.java | 135 ++++++++++++++---- 1 file changed, 109 insertions(+), 26 deletions(-) diff --git a/source/java/org/alfresco/service/cmr/attributes/AttributeService.java b/source/java/org/alfresco/service/cmr/attributes/AttributeService.java index 68447dcd5e..770fe628bc 100644 --- a/source/java/org/alfresco/service/cmr/attributes/AttributeService.java +++ b/source/java/org/alfresco/service/cmr/attributes/AttributeService.java @@ -18,7 +18,7 @@ * As a special exception to the terms and conditions of version 2.0 of * the GPL, you may redistribute this Program in connection with Free/Libre * and Open Source Software ("FLOSS") applications as described in Alfresco's - * FLOSS exception. You should have recieved a copy of the text describing + * FLOSS exception. You should have received a copy of the text describing * the FLOSS exception, and it is also available here: * http://www.alfresco.com/legal/licensing" */ @@ -32,34 +32,69 @@ import org.alfresco.util.Pair; /** * This provides services for reading, writing, and querying global attributes. + *

+ * Attributes are organized hierarchically. + * Each segment within the hierarchy is referred to as a "key". + * Keys are indexed so that they may be queried efficiently. + * Because databases may impose length restrictions + * on index of primary keys, you are strongly advised to keep + * "large" strings in values, not keys. + * For example, + * http://dev.mysql.com/tech-resources/crash-me.php reports + * that the index length limit of MySQL-4.1.1pre InnoDB is 1024, + * bytes. Assuming keys are stored in UTF8, this means keys + * should be no longer 170 chars (170*6 + 1 = 1020 < 1024). + *

+ * + * When an attribute within the hierarchy is represented as a "path", + * the set of keys used to reach it is concatenated using the '/' character. + * Thus, "a/b/c" refers to attribute "c" within "b" within "a". + * This "path" notation is merely a convenience; if you prefer, + * lower-level functions can also be used that allow you to + * supply the list of keys directly. If you need to create a "path" + * that includes a key with an embedded '/' character, you must + * escape it with '\' (e.g.: "silly\/example"). No such restriction + * applies when you use an API that accepts a list of keys directly. + *

+ * Lookups for attributes never attempt to search any other + * leaf key (final path segment) than the one specified + * function call. Thus, if you have an attribute named + * "egg", but no attribute named "hen/egg", a lookup for + * "egg" will suceed, but a lookup for "hen/egg" will fail + * (i.e.: it will return null). + * * @author britt */ public interface AttributeService { /** - * Get an Attribute. - * @param path The path of the Attribute. + * Get an Attribute using a path. + * + * @param path The path of the Attribute * @return The value of the attribute or null. */ public Attribute getAttribute(String path); /** - * Get an attribute. - * @param keys The keys in the attribute path. + * Get an attribute using a list of keys. + * + * @param keys List of attribute path keys (path components). * @return The value of the attribute or null. */ public Attribute getAttribute(List keys); /** - * Set an attribute. Overwrites if it exists. + * Set an attribute, overwriting its prior value if it already existed. + * * @param name The name of the Attribute. * @param value The value to set. */ public void setAttribute(String path, String name, Attribute value); /** - * Set an attribute - * @param keys List of attribute path keys. + * Set an attribute, overwriting its prior value if it already existed. + * + * @param keys List of attribute path keys (path components). * @param name The name of the attribute to set. * @param value The Attribute to set. */ @@ -67,7 +102,8 @@ public interface AttributeService /** * Set an attribute in a list. - * @param path The path to the list. + * + * @param path The path to the {@link org.alfresco.repo.attributes.ListAttribute ListAttribute}. * @param index The list index. * @param value The Attribute to set. */ @@ -75,23 +111,25 @@ public interface AttributeService /** * Set an attribute in a list. - * @param keys The path components to the list. + * @param keys List of attribute path keys (path components). * @param index The list index. - * @param value The Attribute to set. + * @param value The Attribute to set within the {@link org.alfresco.repo.attributes.ListAttribute ListAttribute} */ public void setAttribute(List keys, int index, Attribute value); /** - * Add an attribute to a List Attribute + * Add an attribute to a list. + * * @param path The path to the list. - * @param value The Attribute to add. + * @param value The Attribute to add to the {@link org.alfresco.repo.attributes.ListAttribute ListAttribute} */ public void addAttribute(String path, Attribute value); /** - * Add an attribute to a List Attribute. - * @param keys The path components to the list. - * @param value The Attribute to add. + * Add an attribute to a list. + * + * @param keys List of attribute path keys (path components). + * @param value The Attribute to add to the {@link org.alfresco.repo.attributes.ListAttribute ListAttribute} */ public void addAttribute(List keys, Attribute value); @@ -103,7 +141,7 @@ public interface AttributeService /** * Remove an Attribute. - * @param keys List of attribute path keys. + * @param keys List of attribute path keys (path components). * @param name The name of the attribute to remove. */ public void removeAttribute(List keys, String name); @@ -111,20 +149,40 @@ public interface AttributeService /** * Remove an attribute from a list. * @param path The path to the list. - * @param index The index to remove. + * @param index The index to remove from the + * {@link org.alfresco.repo.attributes.ListAttribute ListAttribute} */ public void removeAttribute(String path, int index); /** * Remove an attribute from a list. - * @param keys The components of the path to the list. - * @param index The index to remove. + * @param keys List of attribute path keys (path components). + * @param index The index to remove from the + * {@link org.alfresco.repo.attributes.ListAttribute ListAttribute} */ public void removeAttribute(List keys, int index); /** - * Query for a list of attributes which are contained in the map + * Query for the list of attributes that is contained in the map * defined by the given path and meet the query criteria. + * + *

+ * Example 1:
+ * Find all attributes within the nested namespace "a/b" + * that are lexically greater than or equal to the string "v": + * 

+     *          query("a/b", new AttrQueryGTE("v"))
+     *
+ *

+ * Example 2:
+ * Find all attributes within the namespace "xyz" that are + * either lexically less than the string "d" or greater than + * the string "w": + * 

+     *           query("xyz", new AttrOrQuery(new AttrQueryLT("d"),
+     *                                        new AttrQueryGT("w")))
+     *
+ * * @param path * @param query * @return A List of matching attributes. @@ -134,23 +192,48 @@ public interface AttributeService /** * Query for a list of attributes which are contained in a map defined by the * given path and meet the query criteria. - * @param keys The list of attribute path keys. + * @param keys List of attribute path keys (path components). * @param query * @return A list of matching attributes. */ public List> query(List keys, AttrQuery query); /** - * Get all the keys for a given attribute path. + * Get all the keys at a given attribute path. + * When prior call to + * {@link #setAttribute setAttribute} + * has associated a path with a + * {@link org.alfresco.repo.attributes.Attribute.Type#MAP MAP}, you can fetch the + * keys for that map via this function. + *

+ * Example:
+ * Suppose AttribSvc is an attribute service object:

+     *
+     *   MapAttribute x = new MapAttributeValue();
+     *   x.put("cow",  new StringAttributeValue("moo");
+     *   x.put("bird", new StringAttributeValue("tweet");
+     *  
+     *   MapAttribute y = new MapAttributeValue();
+     *   y.put("pekingese",    new StringAttributeValue("yip-yip-yip");
+     *   y.put("blood hound",  new StringAttributeValue("Aroooooooooooo");
+     *   y.put("labrador",     new StringAttributeValue("Hello, kind stranger!");
+     *
+     *   AttribSvc.setAttribute("",  "x", x);
+     *   AttribSvc.setAttribute("x", "y", y);
+     *
+     *   List<String> x_keys  = AttribSvc.getKeys("x");    // cow, bird
+     *   List<String> y_keys  = AttribSvc.getKeys("x/y");  // pekingese, blood hound, labrador
+     *
+ * * @param path The attribute path. * @return A list of all keys. */ public List getKeys(String path); /** - * Get all the keys for a give attribute path. - * @param keys The keys of the attribute path. - * @return A list of all keys. + * Get all the keys at a given attribute path as specified by a list of path components. + * @param keys List of attribute path keys (path components). + * @return A list of all keys at the specified Attribute location */ public List getKeys(List keys); }