View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.trinidad.model;
20  
21  /**
22   * Defines a set of "local" APIs for a CollectionModel.
23   * The "local" APIs allow a client to query the model and determine if a 
24   * set of rows are locally available. "Locally available" can mean the 
25   * model has the given set of rows in a local cache and can honor a fetch request
26   * efficiently (for example, without performing a SQL query).
27   */
28  public interface LocalRowKeyIndex
29  {
30  
31    /**
32     * Given a row index, check if a row is locally available
33     * @param rowIndex index of row to check 
34     * @return <code>true</code> if row is locally available <code>flase</code> otherwise
35     */
36    public boolean isRowLocallyAvailable(int rowIndex);
37  
38    /**
39     * Given a row key, check if a row is locally available
40     * @param rowKey row key for the row to check 
41     * @return <code>true</code> if row is locally available <code>flase</code> otherwise
42     */
43    public boolean isRowLocallyAvailable(Object rowKey);
44  
45    /**
46     * Check if a range of rows is locally available starting from a row index
47     * @param startIndex staring index for the range  
48     * @param rowCount number of rows in the range
49     * @return <code>true</code> if range of rows is locally available <code>flase</code> otherwise
50     */
51    public boolean areRowsLocallyAvailable(int startIndex, int rowCount);
52  
53    /**
54     * Check if a range of rows is locally available starting from a row key
55     * @param startRowKey staring row key for the range  
56     * @param rowCount number of rows in the range
57     * @return <code>true</code> if range of rows is locally available <code>flase</code> otherwise
58     */
59    public boolean areRowsLocallyAvailable(Object startRowKey, int rowCount);
60    
61    /**
62     * Check if a range of rows is locally available starting from the current row
63     * @param rowCount number of rows in the range
64     * @return <code>true</code> if range of rows is locally available <code>flase</code> otherwise
65     */
66    public boolean areRowsLocallyAvailable(int rowCount);
67    
68    /**
69     * Convenient API to return a row count estimate.  This method can be optimized 
70     * to avoid a data fetch which may be required to return an exact row count.
71     * <p>
72     * This method can return -1 or a row count estimate if determining
73     * exact row count requires a data fetch.  When dealing with estimated row counts,
74     * the caller needs to gracefully handle the case where <code>isRowAvailable</code>
75     * returns <code>false</code> for a row index or a row key.
76     * @return estimated row count
77     */
78    public int getEstimatedRowCount();
79  
80  
81    /**
82     * Helper API to determine if the row count returned from {@link #getEstimatedRowCount} 
83     * is EXACT, or an ESTIMATE
84     */
85    public Confidence getEstimatedRowCountConfidence();
86  
87    
88    /**
89     * Enum used in the {@link #getEstimatedRowCountConfidence} API to determine 
90     * if the row count is exact or an estimate
91     */
92    public enum Confidence
93    {
94      /**
95       * The row count returned by {@link #getEstimatedRowCount} is exact
96       */
97      EXACT,
98  
99      /**
100      * The row count returned by {@link #getEstimatedRowCount} is an estimate
101      */
102     ESTIMATE,
103         
104     /**
105      * The row count returned by {@link #getEstimatedRowCount} is unknown (-1)
106      */
107     UNKNOWN    
108   }
109   
110   
111   //
112   // Local Cache management APIs
113   //
114   
115   /**
116    * clear all rows from the local cache
117    */
118   public void clearLocalCache();
119   
120   /**
121    * Clear the requested range of rows from the local cache
122    * @param startingIndex starting row index for the range to clear
123    * @param rowsToClear number of rows to clear from the cache
124    */
125   public void clearCachedRows(int startingIndex,  int rowsToClear);
126   
127   /**
128    * Clear the requested range of rows from the local cache
129    * @param startingRowKey starting row key for the range to clear
130    * @param rowsToClear number of rows to clear from the cache
131    */
132   public void clearCachedRows(Object startingRowKey, int rowsToClear);
133   
134   /**
135    * Clear a row from the local cache by row index
136    * @param index row index for the row to clear from the cache
137    */
138   public void clearCachedRow(int index);
139   
140   /**
141    * Clear a row from the local cache by row key
142    * @param rowKey row key for the row to clear from the cache
143    */
144   public void clearCachedRow(Object rowKey);
145   
146   /**
147    * Indicates the caching strategy supported by the model
148    * @see LocalCachingStrategy
149    * @return caching strategy supported by the model
150    */
151   public LocalCachingStrategy getCachingStrategy();
152   
153   /**
154    * Enum used to indicate the type of caching supported by the model
155    * @see #getCachingStrategy()
156    */
157   public enum LocalCachingStrategy
158   {
159     /**
160      * Caching is not supported
161      */
162     NONE,
163     
164     /**
165      * Supports caching certain ranges of rows
166      */
167     PARTIAL,
168     
169     /**
170      * Caches all rows
171      */
172     ALL
173   }
174 }