001: /*
002: * Copyright 2004-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.springframework.webflow.core.collection;
017:
018: import java.util.Collection;
019:
020: import org.springframework.binding.collection.MapAdaptable;
021:
022: /**
023: * An immutable interface for accessing attributes in a backing map with string keys.
024: * <p>
025: * Implementations can optionally support {@link AttributeMapBindingListener listeners}
026: * that will be notified when they're bound in or unbound from the map.
027: *
028: * @author Keith Donald
029: */
030: public interface AttributeMap extends MapAdaptable {
031:
032: /**
033: * Get an attribute value out of this map, returning <code>null</code> if
034: * not found.
035: * @param attributeName the attribute name
036: * @return the attribute value
037: */
038: public Object get(String attributeName);
039:
040: /**
041: * Returns the size of this map.
042: * @return the nubmer of entries in the map
043: */
044: public int size();
045:
046: /**
047: * Is this attribute map empty with a size of 0?
048: * @return true if empty, false if not
049: */
050: public boolean isEmpty();
051:
052: /**
053: * Does the attribute with the provided name exist in this map?
054: * @param attributeName the attribute name
055: * @return true if so, false otherwise
056: */
057: public boolean contains(String attributeName);
058:
059: /**
060: * Does the attribute with the provided name exist in this map and is its
061: * value of the specified required type?
062: * @param attributeName the attribute name
063: * @param requiredType the required class of the attribute value
064: * @return true if so, false otherwise
065: * @throws IllegalArgumentException when the value is not of the required
066: * type
067: */
068: public boolean contains(String attributeName, Class requiredType)
069: throws IllegalArgumentException;
070:
071: /**
072: * Get an attribute value, returning the default value if no value is found.
073: * @param attributeName the name of the attribute
074: * @param defaultValue the default value
075: * @return the attribute value, falling back to the default if no such
076: * attribute exists
077: */
078: public Object get(String attributeName, Object defaultValue);
079:
080: /**
081: * Get an attribute value, asserting the value is of the required type.
082: * @param attributeName the name of the attribute
083: * @param requiredType the required type of the attribute value
084: * @return the attribute value, or null if not found
085: * @throws IllegalArgumentException when the value is not of the required
086: * type
087: */
088: public Object get(String attributeName, Class requiredType)
089: throws IllegalArgumentException;
090:
091: /**
092: * Get an attribute value, asserting the value is of the required type and
093: * returning the default value if not found.
094: * @param attributeName the name of the attribute
095: * @param requiredType the value required type
096: * @param defaultValue the default value
097: * @return the attribute value, or the default if not found
098: * @throws IllegalArgumentException when the value (if found) is not of the
099: * required type
100: */
101: public Object get(String attributeName, Class requiredType,
102: Object defaultValue) throws IllegalStateException;
103:
104: /**
105: * Get the value of a required attribute, throwing an exception of no
106: * attribute is found.
107: * @param attributeName the name of the attribute
108: * @return the attribute value
109: * @throws IllegalArgumentException when the attribute is not found
110: */
111: public Object getRequired(String attributeName)
112: throws IllegalArgumentException;
113:
114: /**
115: * Get the value of a required attribute and make sure it is of the required
116: * type.
117: * @param attributeName name of the attribute to get
118: * @param requiredType the required type of the attribute value
119: * @return the attribute value
120: * @throws IllegalArgumentException when the attribute is not found or not
121: * of the required type
122: */
123: public Object getRequired(String attributeName, Class requiredType)
124: throws IllegalArgumentException;
125:
126: /**
127: * Returns a string attribute value in the map, returning <code>null</code>
128: * if no value was found.
129: * @param attributeName the attribute name
130: * @return the string attribute value
131: * @throws IllegalArgumentException if the attribute is present but not a
132: * string
133: */
134: public String getString(String attributeName)
135: throws IllegalArgumentException;
136:
137: /**
138: * Returns a string attribute value in the map, returning the default value
139: * if no value was found.
140: * @param attributeName the attribute name
141: * @param defaultValue the default
142: * @return the string attribute value
143: * @throws IllegalArgumentException if the attribute is present but not a
144: * string
145: */
146: public String getString(String attributeName, String defaultValue)
147: throws IllegalArgumentException;
148:
149: /**
150: * Returns a string attribute value in the map, throwing an exception if the
151: * attribute is not present and of the correct type.
152: * @param attributeName the attribute name
153: * @return the string attribute value
154: * @throws IllegalArgumentException if the attribute is not present or
155: * present but not a string
156: */
157: public String getRequiredString(String attributeName)
158: throws IllegalArgumentException;
159:
160: /**
161: * Returns a collection attribute value in the map.
162: * @param attributeName the attribute name
163: * @return the collection attribute value
164: * @throws IllegalArgumentException if the attribute is present but not a
165: * collection
166: */
167: public Collection getCollection(String attributeName)
168: throws IllegalArgumentException;
169:
170: /**
171: * Returns a collection attribute value in the map and make sure it is of
172: * the required type.
173: * @param attributeName the attribute name
174: * @param requiredType the required type of the attribute value
175: * @return the collection attribute value
176: * @throws IllegalArgumentException if the attribute is present but not a
177: * collection of the required type
178: */
179: public Collection getCollection(String attributeName,
180: Class requiredType) throws IllegalArgumentException;
181:
182: /**
183: * Returns a collection attribute value in the map, throwing an exception if
184: * the attribute is not present or not a collection.
185: * @param attributeName the attribute name
186: * @return the collection attribute value
187: * @throws IllegalArgumentException if the attribute is not present or is
188: * present but not a collection
189: */
190: public Collection getRequiredCollection(String attributeName)
191: throws IllegalArgumentException;
192:
193: /**
194: * Returns a collection attribute value in the map, throwing an exception if
195: * the attribute is not present or not a collection of the required type.
196: * @param attributeName the attribute name
197: * @param requiredType the required collection type
198: * @return the collection attribute value
199: * @throws IllegalArgumentException if the attribute is not present or is
200: * present but not a collection of the required type
201: */
202: public Collection getRequiredCollection(String attributeName,
203: Class requiredType) throws IllegalArgumentException;
204:
205: /**
206: * Returns an array attribute value in the map and makes sure it is of the
207: * required type.
208: * @param attributeName the attribute name
209: * @param requiredType the required type of the attribute value
210: * @return the array attribute value
211: * @throws IllegalArgumentException if the attribute is present but not an
212: * array of the required type
213: */
214: public Object[] getArray(String attributeName, Class requiredType)
215: throws IllegalArgumentException;
216:
217: /**
218: * Returns an array attribute value in the map, throwing an exception if the
219: * attribute is not present or not an array of the required type.
220: * @param attributeName the attribute name
221: * @param requiredType the required array type
222: * @return the collection attribute value
223: * @throws IllegalArgumentException if the attribute is not present or is
224: * present but not a array of the required type
225: */
226: public Object[] getRequiredArray(String attributeName,
227: Class requiredType) throws IllegalArgumentException;
228:
229: /**
230: * Returns a number attribute value in the map that is of the specified
231: * type, returning <code>null</code> if no value was found.
232: * @param attributeName the attribute name
233: * @param requiredType the required number type
234: * @return the number attribute value
235: * @throws IllegalArgumentException if the attribute is present but not a
236: * number of the required type
237: */
238: public Number getNumber(String attributeName, Class requiredType)
239: throws IllegalArgumentException;
240:
241: /**
242: * Returns a number attribute value in the map of the specified type,
243: * returning the default value if no value was found.
244: * @param attributeName the attribute name
245: * @param defaultValue the default
246: * @return the number attribute value
247: * @throws IllegalArgumentException if the attribute is present but not a
248: * number of the required type
249: */
250: public Number getNumber(String attributeName, Class requiredType,
251: Number defaultValue) throws IllegalArgumentException;
252:
253: /**
254: * Returns a number attribute value in the map, throwing an exception if the
255: * attribute is not present and of the correct type.
256: * @param attributeName the attribute name
257: * @return the number attribute value
258: * @throws IllegalArgumentException if the attribute is not present or
259: * present but not a number of the required type
260: */
261: public Number getRequiredNumber(String attributeName,
262: Class requiredType) throws IllegalArgumentException;
263:
264: /**
265: * Returns an integer attribute value in the map, returning
266: * <code>null</code> if no value was found.
267: * @param attributeName the attribute name
268: * @return the integer attribute value
269: * @throws IllegalArgumentException if the attribute is present but not an
270: * integer
271: */
272: public Integer getInteger(String attributeName)
273: throws IllegalArgumentException;
274:
275: /**
276: * Returns an integer attribute value in the map, returning the default
277: * value if no value was found.
278: * @param attributeName the attribute name
279: * @param defaultValue the default
280: * @return the integer attribute value
281: * @throws IllegalArgumentException if the attribute is present but not an
282: * integer
283: */
284: public Integer getInteger(String attributeName, Integer defaultValue)
285: throws IllegalArgumentException;
286:
287: /**
288: * Returns an integer attribute value in the map, throwing an exception if
289: * the attribute is not present and of the correct type.
290: * @param attributeName the attribute name
291: * @return the integer attribute value
292: * @throws IllegalArgumentException if the attribute is not present or
293: * present but not an integer
294: */
295: public Integer getRequiredInteger(String attributeName)
296: throws IllegalArgumentException;
297:
298: /**
299: * Returns a long attribute value in the map, returning <code>null</code>
300: * if no value was found.
301: * @param attributeName the attribute name
302: * @return the long attribute value
303: * @throws IllegalArgumentException if the attribute is present but not a
304: * long
305: */
306: public Long getLong(String attributeName)
307: throws IllegalArgumentException;
308:
309: /**
310: * Returns a long attribute value in the map, returning the default value if
311: * no value was found.
312: * @param attributeName the attribute name
313: * @param defaultValue the default
314: * @return the long attribute value
315: * @throws IllegalArgumentException if the attribute is present but not a
316: * long
317: */
318: public Long getLong(String attributeName, Long defaultValue)
319: throws IllegalArgumentException;
320:
321: /**
322: * Returns a long attribute value in the map, throwing an exception if the
323: * attribute is not present and of the correct type.
324: * @param attributeName the attribute name
325: * @return the long attribute value
326: * @throws IllegalArgumentException if the attribute is not present or
327: * present but not a long
328: */
329: public Long getRequiredLong(String attributeName)
330: throws IllegalArgumentException;
331:
332: /**
333: * Returns a boolean attribute value in the map, returning <code>null</code>
334: * if no value was found.
335: * @param attributeName the attribute name
336: * @return the long attribute value
337: * @throws IllegalArgumentException if the attribute is present but not a
338: * boolean
339: */
340: public Boolean getBoolean(String attributeName)
341: throws IllegalArgumentException;
342:
343: /**
344: * Returns a boolean attribute value in the map, returning the default value
345: * if no value was found.
346: * @param attributeName the attribute name
347: * @param defaultValue the default
348: * @return the boolean attribute value
349: * @throws IllegalArgumentException if the attribute is present but not a
350: * boolean
351: */
352: public Boolean getBoolean(String attributeName, Boolean defaultValue)
353: throws IllegalArgumentException;
354:
355: /**
356: * Returns a boolean attribute value in the map, throwing an exception if
357: * the attribute is not present and of the correct type.
358: * @param attributeName the attribute name
359: * @return the boolean attribute value
360: * @throws IllegalArgumentException if the attribute is not present or
361: * present but is not a boolean
362: */
363: public Boolean getRequiredBoolean(String attributeName)
364: throws IllegalArgumentException;
365:
366: /**
367: * Returns a new attribute map containing the union of this map with the
368: * provided map.
369: * @param attributes the map to combine with this map
370: * @return a new, combined map
371: */
372: public AttributeMap union(AttributeMap attributes);
373:
374: }
|