001: /*
002: * Copyright 2004, 2005, 2006 Odysseus Software GmbH
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 de.odysseus.calyxo.forms.view;
017:
018: import java.util.Iterator;
019: import java.util.Locale;
020:
021: /**
022: * List model interface.
023: * <p/>
024: * A list model defines a bijection between string keys and object values.
025: * That is, each key corresponds to exacly one value and vice versa.
026: * Keys must not be <code>null</code> or empty. Values must not be <code>null</code>.
027: * <p/>
028: * The interface provides a method to lookup labels and to get all values
029: * in some sorted order. The interface defines some keys for common
030: * sort criteria. Generally, an implementation must support the
031: * <code>INDEX_ORDER</code> order. If an implementation does not
032: * support some other requested order, it should answer the values in
033: * <code>INDEX_ORDER</code> instead.
034: *
035: * @author Oliver Stuhr
036: * @author Christoph Beck
037: */
038: public interface ListModel {
039:
040: /**
041: * Index order. This order refers to the model's internal order.
042: * For example, it may reflect the order, values have been added.
043: * to the model. The sorted sequence contains
044: * <code>getValue(0), ..., getValue(getSize()-1)</code>.
045: */
046: public static final int INDEX_ORDER = 0;
047:
048: /**
049: * Key order. Lexicographical order of the keys.
050: */
051: public static final int KEY_ORDER = 1;
052:
053: /**
054: * Value order. Some order defined on the values.
055: * Implementation-dependent.
056: */
057: public static final int VALUE_ORDER = 2;
058:
059: /**
060: * Label order. Lexicographical order of the labels.
061: */
062: public static final int LABEL_ORDER = 3;
063:
064: /**
065: * Get the number of values in this model.
066: */
067: public int getSize();
068:
069: /**
070: * Get the value for specified index (according to index order).
071: */
072: public Object getValue(int index);
073:
074: /**
075: * Answer <code>true</code> iff the specified key is valid.
076: * The result of this method is equivalent to
077: * <code>key == getKey(getValue(key))</code>.
078: */
079: public boolean containsKey(String key);
080:
081: /**
082: * Get the corresponding key for the specified value. If the
083: * value is not contained in the model, answer <code>null</code>.
084: * Because valid keys must not be <code>null</code>, this indicates
085: * an invalid value.
086: */
087: public String getKey(Object value);
088:
089: /**
090: * Get the corresponding value for the specified key. If the key
091: * is not contained in the model, answer <code>null</code>.
092: */
093: public Object getValue(String key);
094:
095: /**
096: * Lookup the label used for display purposes for the specified
097: * value. The passed <code>locale</code> parameter may be used
098: * to lookup a localized label.
099: */
100: public String getLabel(Object value, Locale locale);
101:
102: /**
103: * Iterate over values (in no particular order).
104: */
105: public Iterator getValues();
106:
107: /**
108: * Get the values sorted according to the specified order.
109: * In case of <code>order == LABEL_ORDER</code>, the passed
110: * <code>locale</code> parameter may be used to lookup localized
111: * labels.
112: */
113: public Iterator getValues(int order, boolean descending,
114: Locale locale);
115: }
|