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 javax.faces.model;
20
21 import java.util.ArrayList;
22 import java.util.List;
23
24 /**
25 * Represents the data presented by a UIData component, together with
26 * some state information about the currently selected row within the
27 * datalist for use by listeners on UIData components. This class allows
28 * managed bean code to avoid binding directly to UIData components for
29 * typical uses.
30 * <p>
31 * Note that DataModel and its standard subclasses are not serializable,
32 * as there is no state in a DataModel object itself that needs to be
33 * preserved between render and restore-view. UIData components therefore
34 * do not store their DataModel when serialized; they just evaluate their
35 * "value" EL expression to refetch the object during the
36 * apply-request-values phase.
37 * <p>
38 * Because DataModel is not serializable, any managed bean that needs to
39 * be serialized and which has a member of type DataModel should therefore
40 * mark that member transient. If there is a need to preserve the datalist
41 * contained within the DataModel then ensure a reference to that list is
42 * stored in a non-transient member, or use a custom serialization method
43 * that explicitly serializes dataModel.getWrappedData.
44 *
45 * See Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> for more.
46 *
47 * @author Thomas Spiegl (latest modification by $Author: skitching $)
48 * @version $Revision: 676278 $ $Date: 2008-07-13 03:35:04 -0500 (Sun, 13 Jul 2008) $
49 */
50 public abstract class DataModel
51 {
52 // FIELDS
53 private List _listeners;
54
55 // METHODS
56 public void addDataModelListener(DataModelListener listener)
57 {
58 if (listener == null) throw new NullPointerException("listener");
59 if (_listeners == null)
60 {
61 _listeners = new ArrayList();
62 }
63 _listeners.add(listener);
64 }
65
66 public DataModelListener[] getDataModelListeners()
67 {
68 if (_listeners == null)
69 {
70 return new DataModelListener[0];
71 }
72 return (DataModelListener[])_listeners.toArray(new DataModelListener[_listeners.size()]);
73 }
74
75 /**
76 * Return the number of rows of data available.
77 * <p>
78 * If the number of rows of data available is not known then -1 is returned.
79 * This may happen for DataModels that wrap sources of data such as
80 * java.sql.ResultSet that provide an iterator to access the "next item"
81 * rather than a fixed-size collection of data.
82 */
83 abstract public int getRowCount();
84
85 /**
86 * Return the object associated with the current row index.
87 * <p>
88 * Method isRowAvailable may be called before attempting to access
89 * this method, to ensure that the data is available.
90 *
91 * @throws RuntimeException subclass of some kind if the current row index
92 * is not within the range of the current wrappedData property.
93 */
94 abstract public Object getRowData();
95
96 /**
97 * Get the current row index.
98 */
99 abstract public int getRowIndex();
100
101 /**
102 * Get the entire collection of data associated with this component. Note that
103 * the actual type of the returned object depends upon the concrete
104 * subclass of DataModel; the object will represent an "ordered sequence
105 * of components", but may be implemented as an array, java.util.List,
106 * java.sql.ResultSet or other similar types.
107 */
108 abstract public Object getWrappedData();
109
110 /**
111 * Returns true if a call to getRowData will return a valid object.
112 */
113 abstract public boolean isRowAvailable();
114
115 public void removeDataModelListener(DataModelListener listener)
116 {
117 if (listener == null) throw new NullPointerException("listener");
118 if (_listeners != null)
119 {
120 _listeners.remove(listener);
121 }
122 }
123
124 /**
125 * Set the current row index. This affects the behaviour of the
126 * getRowData method in particular.
127 *
128 * Parameter rowIndex may be -1 to indicate "no row", or may be a value
129 * between 0 and getRowCount()-1.
130 */
131 abstract public void setRowIndex(int rowIndex);
132
133 /**
134 * Set the entire list of data associated with this component. Note that
135 * the actual type of the provided object must match the expectations
136 * of the concrete subclass of DataModel. See getWrappedData.
137 */
138 abstract public void setWrappedData(Object data);
139 }