applying patch tuscany_2552_phillipe_ramalho_09_30_2009.patch from TUSCANY-2552

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@830448 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 73 insertions, 0 deletions

diff --git a/branches/sca-java-1.x/modules/domain-search/src/main/java/org/apache/tuscany/sca/domain/search/Result.java b/branches/sca-java-1.x/modules/domain-search/src/main/java/org/apache/tuscany/sca/domain/search/Result.java
index 53fb9c4803..edbebac6b4 100644
--- a/branches/sca-java-1.x/modules/domain-search/src/main/java/org/apache/tuscany/sca/domain/search/Result.java
+++ b/branches/sca-java-1.x/modules/domain-search/src/main/java/org/apache/tuscany/sca/domain/search/Result.java
@@ -22,27 +22,100 @@ import java.io.Serializable;
 import java.util.Map;
 
 /**
+ * <p>
+ * The object that implements this interface carries a search's result data.
+ * </p>
+ * <p>
+ * A result contains a value, which is the value displayed to the user. It also
+ * contains a field name, which is the field the value is related to.
+ * </p>
+ * <p>
+ * A search result may be split into different {@link Result} objects, each one
+ * contained inside other, representing a complex result hierarchy. For example:
+ * a result structure may represent as result a folder and files/folders
+ * contained in it.
+ * </p>
+ * 
+ * @see ResultProcessor
+ * @see ResultFactory
  * 
  * @version $Rev$ $Date$
  */
 public interface Result extends Serializable {
 
+    /**
+     * Returns the value held by this object.
+     * 
+     * @return the value held by this object
+     */
     String getValue();
 
+    /**
+     * Sets the result value.
+     * 
+     * @param value the result value
+     */
     void setValue(String value);
 
+    /**
+     * Returns the {@link Result} object that contains this object or
+     * <code>null</code> if it's not contained in any object.
+     * 
+     * @return the {@link Result} object that contains this object or
+     *         <code>null</code> if it's not contained in any object
+     */
     Result getContainer();
 
+    /**
+     * A {@link Map} containing {@link Result} objects contained in this
+     * {@link Object}. The contents are mapped from a key, which may be any kind
+     * of identifier, the identifier is chosen by the {@link Result}
+     * implementation.
+     * 
+     * @return the contents map
+     */
     Map<String, Result> getContents();
 
+    /**
+     * Adds a {@link Result} content to this result.
+     * 
+     * @param artifactResult the {@link Result} content
+     * @throw {@link UnsupportedOperationException} if the {@link Result}
+     *        implementations does not support this operation
+     * @see #getContents()
+     */
     void addContent(Result artifactResult);
 
+    /**
+     * Removes a {@link Result} content from this result.
+     * 
+     * @param artifactResult the {@link Result} content
+     * @throw {@link UnsupportedOperationException} if the {@link Result}
+     *        implementations does not support this operation
+     * @see #getContents()
+     */
     void removeContent(Result artifactResult);
 
+    /**
+     * Sets this object's container.
+     * 
+     * @param container the object's container
+     * @see #getContainer()
+     */
     void setContainer(Result container);
 
+    /**
+     * Returns the field related to the result's value.
+     * 
+     * @return the field name
+     */
     String getField();
 
+    /**
+     * Sets the field related to the result's value.
+     * 
+     * @param field the field name
+     */
     void setField(String field);
 
 }