Added support for result set meta data

Added size limits for result sets
Updated/improved comments

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@2573 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/service/cmr/search/LimitBy.java

@@ -0,0 +1,11 @@
+package org.alfresco.service.cmr.search;
+
+/**
+ * Enum to describe how the maximum size of the returned result set should be determined.
+ * 
+ * @author Andy Hind
+ */
+public enum LimitBy
+{
+    UNLIMITED, FINAL_SIZE; // NUMBER_OF_PERMISSION_EVALUATIONS
+}

source/java/org/alfresco/service/cmr/search/PermissionEvaluationMode.java

@@ -0,0 +1,11 @@
+package org.alfresco.service.cmr.search;
+
+/**
+ * Enum to control how permissions are evaluated.
+ * 
+ * @author Andy Hind
+ */
+public enum PermissionEvaluationMode
+{
+    EAGER; // LAZY
+}

source/java/org/alfresco/service/cmr/search/ResultSet.java

@@ -53,26 +53,45 @@ public interface ResultSet extends Iterable<ResultSetRow> // Specfic iterator
     float getScore(int n);
 
     /**
-     * Generate the XML form of this result set
+     * Close the result set.
+     * This must be called to allow the release of underlying resources.
      */
-    // Dom getXML(int page, int pageSize, boolean includeMetaData);
-    /**
-     * Generate as XML for Reading
-     */
-    // Stream getStream(int page, int pageSize, boolean includeMetaData);
-    /**
-     * toString() as above but for the whole set
-     */
-    // String toString();
-    // ResultSetMetaData getMetaData();
     
     void close();
     
+    /**
+     * Get a row from the result set by row index, starting at 0.
+     * 
+     * @param i
+     * @return
+     */
     ResultSetRow getRow(int i);
     
+    /**
+     * Get a list of all the node refs in the result set
+     * @return
+     */
     List<NodeRef> getNodeRefs();
     
+    /**
+     * Get a list of all the child associations in the results set.
+     * 
+     * @return
+     */
     List<ChildAssociationRef> getChildAssocRefs();
     
+    /**
+     * Get the child assoc ref for a particular row.
+     * 
+     * @param n
+     * @return
+     */
     ChildAssociationRef getChildAssocRef(int n);
+    
+    /**
+     * Get the meta data for the results set.
+     * 
+     * @return
+     */
+    ResultSetMetaData getResultSetMetaData();
 }

source/java/org/alfresco/service/cmr/search/ResultSetMetaData.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2005 Alfresco, Inc.
+ *
+ * Licensed under the Mozilla Public License version 1.1 
+ * with a permitted attribution clause. You may obtain a
+ * copy of the License at
+ *
+ *   http://www.alfresco.org/legal/license.txt
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific
+ * language governing permissions and limitations under the
+ * License.
+ */
+package org.alfresco.service.cmr.search;
+
+/**
+ * Meta Data associated with a result set.
+ * 
+ * @author Andy Hind
+ */
+public interface ResultSetMetaData
+{
+    
+    /**
+     * Return how, <b>in fact</b>, the result set was limited.
+     * This may not be how it was requested.
+     * 
+     * If a limit of 100 were requested and there were 100 or less actual results
+     * this will report LimitBy.UNLIMITED.
+     * 
+     * @return
+     */
+    public LimitBy getLimitedBy();
+    
+    /**
+     * Return how permission evaluations are being made.
+     * 
+     * @return
+     */
+    public PermissionEvaluationMode getPermissionEvaluationMode();
+    
+    /**
+     * Get the parameters that were specified to define this search.
+     * 
+     * @return
+     */
+    public SearchParameters getSearchParameters();
+    
+}

source/java/org/alfresco/service/cmr/search/SearchParameters.java

@@ -24,20 +24,41 @@ import org.alfresco.service.cmr.repository.StoreRef;
 /**
  * This class provides parameters to define a search.
  * 
+ * TODO
+ *  - paging of results page number and page size
+ *  - paging isolation - REPEATABLE READ, READ COMMITTED, may SEE ONCE tracking node refs in previous result sets
+ *  - how long repeatable read may be held
+ *  - limit by the number of permission evaluations
+ * 
  * @author Andy Hind
  */
 public class SearchParameters extends SearchStatement
 {
+    /*
+     * The default limit if someone asks for a limited result set but does not say how to limit....
+     */
+    private static int DEFAULT_LIMIT = 500;
+    
+    /*
+     * Standard sort definitions for sorting in document and score order.
+     */
     public static final SortDefinition SORT_IN_DOCUMENT_ORDER_ASCENDING = new SortDefinition(SortDefinition.SortType.DOCUMENT, null, true);
     public static final SortDefinition SORT_IN_DOCUMENT_ORDER_DESCENDING = new SortDefinition(SortDefinition.SortType.DOCUMENT, null, false);
     public static final SortDefinition SORT_IN_SCORE_ORDER_ASCENDING = new SortDefinition(SortDefinition.SortType.SCORE, null, false);
     public static final SortDefinition SORT_IN_SCORE_ORDER_DESCENDING = new SortDefinition(SortDefinition.SortType.SCORE, null, true);
     
+    /**
+     * An emum defining if the default action is to "and" or "or" unspecified components in the query register.
+     * Not all search implementations will support this.
+     */
     public enum Operator
     {
         OR, AND
     }
     
+    /*
+     * Expose as constants 
+     */
     public static final Operator OR = Operator.OR;
     public static final Operator AND = Operator.AND;
     
@@ -54,7 +75,8 @@ public class SearchParameters extends SearchStatement
     }
 
     /**
-     * Set the stores to be supported - currently there can be only one 
+     * Set the stores to be supported - currently there can be only one.
+     * Searching across multiple stores is on the todo list. 
      * 
      * @param store
      */
@@ -68,7 +90,11 @@ public class SearchParameters extends SearchStatement
     }
     
     /**
-     * Add paths for attributes in the result set
+     * Add paths for attributes in the result set.
+     * 
+     * Generally this only makes sense for disconnected results sets.
+     * These atttributes/paths state what must be present in the result set, akin
+     * to the selection of columns is sql.
      * 
      * @param attributePath
      */
@@ -91,6 +117,13 @@ public class SearchParameters extends SearchStatement
      * If true, any data in the current transaction will be ignored in the search. 
      * You will not see anything you have added in the current transaction.
      * 
+     * By default you will see data in the current transaction.
+     * This effectively gives read committed isolation.
+     * 
+     * There is a performance overhead for this, at least when using lucene.
+     * This flag may be set to avoid that performance hit if you know you do not want to find results
+     * that are yet to be committed (this includes creations, deletions and updates)
+     * 
      * @param excludeDataInTheCurrentTransaction
      */
     public void excludeDataInTheCurrentTransaction(boolean excludeDataInTheCurrentTransaction)
@@ -101,28 +134,36 @@ public class SearchParameters extends SearchStatement
     /**
      * Add a sort to the query (for those query languages that do not support it directly)
      * 
+     * The first sort added is treated as primary, the second as secondary etc.
+     * 
+     * A helper method to create SortDefinitions.
+     * 
      * @param field - this is intially a direct attribute on a node not an attribute on the parent etc
      * TODO: It could be a relative path at some time. 
      * 
-     * 
-     * @param ascending
+     * @param ascending - true to sort ascending, false for descending.
      */
     public void addSort(String field, boolean ascending)
     {
         addSort(new SortDefinition(SortDefinition.SortType.FIELD,  field, ascending));
     }
     
+    /**
+     * Add a sort definition.
+     * 
+     * @param sortDefinition - the sort definition to add. Use the static member variables
+     * for sorting in score and index order.
+     */
     public void addSort(SortDefinition sortDefinition)
     {
         sortDefinitions.add(sortDefinition);
     }
     
     /**
-     * A helper class for sort definition
-     * @author andyh
-     *
-     * TODO To change the template for this generated type comment go to
-     * Window - Preferences - Java - Code Style - Code Templates
+     * A helper class for sort definition.
+     * Encapsulated using the lucene sortType, field name and a flag for ascending/descending.
+     * 
+     * @author Andy Hind
      */
     public static class SortDefinition
     {
@@ -157,38 +198,131 @@ public class SearchParameters extends SearchStatement
         
     }
 
+    /**
+     * Get the list of attribute paths that are guarenteed to be in the result set.
+     * 
+     * @return
+     */
     public ArrayList<Path> getAttributePaths()
     {
         return attributePaths;
     }
 
+    /** 
+     * Is data in the current transaction excluded from the search.
+     * 
+     * @return
+     */
     public boolean excludeDataInTheCurrentTransaction()
     {
         return excludeDataInTheCurrentTransaction;
     }
 
+    /** 
+     * Get the query parameters that apply to this query.
+     * 
+     * @return
+     */
     public ArrayList<QueryParameterDefinition> getQueryParameterDefinitions()
     {
         return queryParameterDefinitions;
     }
 
+    /**
+     * Get the sort definitions that apply to this query.
+     * 
+     * @return
+     */
     public ArrayList<SortDefinition> getSortDefinitions()
     {
         return sortDefinitions;
     }
 
+    /**
+     * Get the stores in which this query should find results.
+     * 
+     * @return
+     */
     public ArrayList<StoreRef> getStores()
     {
         return stores;
     }
     
+    /**
+     * Set the default operator for query elements when they are not explicit in the query.
+     * 
+     * @param defaultOperator
+     */
     public void setDefaultOperator(Operator defaultOperator)
     {
         this.defaultOperator = defaultOperator;
     }
     
+    /**
+     * Get the default operator for query elements when they are not explicit in the query.
+     * 
+     * @return
+     */
     public Operator getDefaultOperator()
     {
         return defaultOperator;
     }
+    
+    private LimitBy limitBy = LimitBy.UNLIMITED;
+    
+    private PermissionEvaluationMode permissionEvaluation = PermissionEvaluationMode.EAGER;
+    
+    private int limit = DEFAULT_LIMIT;
+
+    /** 
+     * Get how the result set should be limited
+     * 
+     * @return
+     */
+    public LimitBy getLimitBy()
+    {
+        return limitBy;
+    }
+
+    /**
+     * Set how the result set should be limited.
+     * 
+     * @param limitBy
+     */
+    public void setLimitBy(LimitBy limitBy)
+    {
+        this.limitBy = limitBy;
+    }
+
+    /**
+     * Get when permissions are evaluated.
+     * 
+     * @return
+     */
+    public PermissionEvaluationMode getPermissionEvaluation()
+    {
+        return permissionEvaluation;
+    }
+
+    /**
+     * Set when permissions are evaluated.
+     * 
+     * @param permissionEvaluation
+     */
+    public void setPermissionEvaluation(PermissionEvaluationMode permissionEvaluation)
+    {
+        this.permissionEvaluation = permissionEvaluation;
+    }
+
+    public int getLimit()
+    {
+        return limit;
+    }
+
+    public void setLimit(int limit)
+    {
+        this.limit = limit;
+    }
+    
+    
 }

source/java/org/alfresco/service/cmr/search/SearchStatement.java

@@ -32,27 +32,53 @@ public class SearchStatement
         super();
     }
     
+    /**
+     * A constructor that takes both arguments.
+     * 
+     * @param language
+     * @param query
+     */
     SearchStatement(String language, String query)
     {
         this.language = language;
         this.query = query;
     }
 
+    /**
+     * Get the query language. 
+     * 
+     * @return
+     */
     public String getLanguage()
     {
         return language;
     }
 
+    /**
+     * Get the query.
+     * 
+     * @return
+     */
     public String getQuery()
     {
         return query;
     }
 
+    /**
+     * Set the query language.
+     * 
+     * @param language - the query language.
+     */
     public void setLanguage(String language)
     {
         this.language = language;
     }
 
+    /**
+     * Set the query string.
+     * 
+     * @param query - the query string.
+     */
     public void setQuery(String query)
     {
         this.query = query;