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 import java.util.Collections;
22 import java.util.List;
23 import javax.faces.model.DataModel;
24
25 /**
26 * The data model that is used by the Trinidad Table and Iterator components.
27 * This extends the Faces DataModel class and adds on support for
28 * rowKeys and sorting. Ordinary DataModels are still supported,
29 * and will automatically be wrapped into CollectionModels, but
30 * without the added functionality.
31 * <p>
32 * <h3>Row key support</h3>
33 * <p>
34 * In the Faces DataModel, rows are identified entirely by
35 * index. This causes major problems if the underlying data
36 * changes from one request to the next - a user request
37 * to delete one row may delete a different row because a
38 * row got added by another user, etc. To work around
39 * this, CollectionModel is based around row keys instead
40 * of indices. An implementation of CollectionModel must
41 * implement getRowKey() and setRowKey(), and handle
42 * conversion from integer indices to row keys. A trivial
43 * implementation might simply use Integer objects as
44 * the row keys, but a better version could use a unique ID
45 * in the row.
46 * <p>
47 */
48 public abstract class CollectionModel extends DataModel
49 implements RowKeyIndex
50 {
51
52 /**
53 * Gets the rowKey of the current row.
54 * rowKeys are safer to use than row indices because rowKeys are
55 * unaffected by mutations to this collection.
56 * rowKeys should have efficient implementations of
57 * {@link Object#equals} and {@link Object#hashCode} as they will be used
58 * as keys in hashtables. rowKeys should also be Serializable, so that the
59 * application can run under all JSF state-saving schemes.
60 * @return this key should be Serializable and immutable.
61 * @see #setRowKey
62 */
63 public abstract Object getRowKey();
64
65 /**
66 * Finds the row with the matching key and makes it current
67 * @param key the rowKey, previously obtained from {@link #getRowKey}.
68 */
69 public abstract void setRowKey(Object key);
70
71
72 /**
73 * Checks to see if the row at the given index is available.
74 * This method makes the given row current and calls
75 * {@link #isRowAvailable()}.
76 * Finally, the row that was current before this method was called
77 * is made current again.
78 * @param rowIndex the index of the row to check.
79 * @return true if data for the row exists.
80 */
81 public boolean isRowAvailable(int rowIndex)
82 {
83 int oldIndex = getRowIndex();
84 try
85 {
86 setRowIndex(rowIndex);
87 return isRowAvailable();
88 }
89 finally
90 {
91 setRowIndex(oldIndex);
92 }
93 }
94
95 /**
96 * Gets the rowData at the given index.
97 * This method makes the given row current and calls
98 * {@link #getRowData()}.
99 * Finally, the row that was current before this method was called
100 * is made current again.
101 * @param rowIndex the index of the row to get data from.
102 * @return the data for the given row.
103 */
104 public Object getRowData(int rowIndex)
105 {
106 int oldIndex = getRowIndex();
107 try
108 {
109 setRowIndex(rowIndex);
110 return getRowData();
111 }
112 finally
113 {
114 setRowIndex(oldIndex);
115 }
116 }
117
118 /**
119 * Return true if this collection is sortable by the given property.
120 * This implementation always returns false;
121 */
122 public boolean isSortable(String property)
123 {
124 return false;
125 }
126
127 /**
128 * Gets the criteria that this collection is sorted by.
129 * This method should never return null.
130 * This implementation always returns an empty List.
131 * @return each element in this List is of type SortCriterion.
132 * An empty list is returned if this collection is not sorted.
133 * @see SortCriterion
134 */
135 public List<SortCriterion> getSortCriteria()
136 {
137 return Collections.emptyList();
138 }
139
140 /**
141 * Sorts this collection by the given criteria.
142 * @param criteria Each element in this List must be of type SortCriterion.
143 * The empty list may be used to cancel any sort order. null should be treated
144 * the same as an empty list.
145 * @see SortCriterion
146 */
147 public void setSortCriteria(List<SortCriterion> criteria)
148 {
149 }
150
151 }