Source code: com/clra/web/INameList.java
1 /*
2 * Copyright (c) Carnegie Lake Rowing Association 2002. All rights reserved.
3 * Distributed under the GPL license. See doc/COPYING.
4 * $RCSfile: INameList.java,v $
5 * $Date: 2003/02/26 03:38:46 $
6 * $Revision: 1.3 $
7 */
8
9 package com.clra.web;
10
11 import com.clra.util.ISerializableComparator;
12 import java.util.Iterator;
13
14 /**
15 * Declares JSP attributes and bean properties for alphabetized lists of
16 * stuff. Views that implement this interface may be controlled via components
17 * such as NameSelector.<p>
18 *
19 * For Java Server Pages, this interface declares three attributes that should
20 * be set and accessed within the scope of a request or session:<ul>
21 * <li><strong>restricted</strong>: is the view restricted to a range of
22 * items with names that start with a particular group of letters?
23 * [true,false]</li>
24 * <li><strong>group</strong>: if the view is restricted, the group of letters
25 * with the name of an item should begin.
26 * <li><strong>comparator</strong>: specifies a bean that implements
27 * <tt>java.util.Comparator</tt> which can compare instances of
28 * INamed. The current implementation of NameSelector does not
29 * use the value of this attribute.</li>
30 * </ul>
31 *
32 * <p>The Integer value specified by <tt>group</tt> refers to predefined
33 * groups:<ol>
34 * <li> ABC - names less than 'D'</li>
35 * <li> DEF - names between 'D' and 'F'</li>
36 * <li> GHI - names between 'G' and 'I'</li>
37 * <li> JKL - names between 'J' and 'L'</li>
38 * <li> MNO - names between 'M' and 'O'</li>
39 * <li> PQRS - names between 'P' and 'S'</li>
40 * <li> TUV - names between 'T' and 'V'</li>
41 * <li> WXYZ - names greater than or equal to 'W'</li>
42 * </ol>
43 * Note that the first group, <tt>ABC</tt>, may contain names like "3Com",
44 * whereas the last group, <tt>WXYZ</tt>, may contain names like "Ėtvos".
45 * Also note that the group index is indexed from '1', not '0'.</p>
46 *
47 * For beans, this interface declares five properties:<ul>
48 * <li><strong>restricted</strong>: read/write Boolean</li>
49 * <li><strong>group</strong>: read/write Integer</li>
50 * <li><strong>comparator</strong>: read/write java.util.Comparator, compares
51 * instances of INamed</li>
52 * <li><strong>iterator</strong>: read-only iterator of INamed
53 * instances</li>
54 * </ul>
55 *
56 * @version $Revision: 1.3 $ $Date: 2003/02/26 03:38:46 $
57 * @author <a href="mailto:rphall@pluto.njcc.com">Rick Hall</a>
58 */
59 public interface INameList {
60
61 /**
62 * Names an attribute within the scope of an HTTP request or session
63 * whose Boolean value indicates whether a list should be restricted to
64 * events that are scheduled to start within a particular month and year.
65 * A blank, null or missing value should default to non-restricted.
66 */
67 public final static String AN_ISRESTRICTED = "namerestricted";
68
69 /**
70 * Names an attribute within the scope of an HTTP request or session
71 * whose char[] value indicates the letters that with which a item
72 * name should begin within a restricted list.
73 */
74 public final static String AN_GROUP = "namegroup";
75
76 /**
77 * Names an attribute within the scope of an HTTP request or session
78 * that holds a bean which implements <tt>java.util.Comparator</tt>.
79 * The comparator must be able to operate on instances of
80 * <tt>INamed</tt>. Current implementations ignore this
81 * attribute, but it is reserved for future enhancements.
82 */
83 public final static String AN_COMPARATOR = "namecomparator";
84
85 /**
86 * Returns an iterator over a collection of INamed beans.
87 * The behavior of the iterator is specified by setting
88 * <tt>restricted</tt>, <tt>month</tt>, <tt>year</tt>, and
89 * <tt>comparator</tt> properties before the iterator is requested.
90 */
91 public Iterator getIterator() throws WebException;
92
93 /**
94 * Returns a flag that indicates whether an iterator will be restricted
95 * to events that are scheduled to start within a particular month
96 * and year. A null value indicates behavior that is
97 * implementation-specific.
98 */
99 public Boolean getRestricted();
100
101 /**
102 * Sets whether an iterator will be restricted to events that start
103 * within a particular month and year. A null value specifies
104 * implementation-specific behavior.
105 */
106 public void setRestricted( Boolean restricted );
107
108 /**
109 * Returns the group of letters to which an iteration is restricted
110 * (if it is restricted). If the return value is non-null, it must
111 * be in the range 1 - 8, inclusive.
112 */
113 public Integer getGroup();
114
115 /**
116 * Sets the group to which an iteration is restricted (if it is
117 * restricted). If the input value is non-null, it must be in the
118 * range 1 - 8, inclusive.
119 */
120 public void setGroup( Integer group );
121
122 /**
123 * Returns the sort-order that an iterator will use. Valid comparators
124 * must be able to compare instances of INamed. A null comparator
125 * indicates the natural sort order of the events will be used.
126 */
127 public ISerializableComparator getComparator();
128
129 /**
130 * Sets the sort-order that an iterator will use. Valid comparators
131 * must be able to compare instances of INamed. A null comparator
132 * indicates the natural sort order of the events will be used.
133 */
134 public void setComparator( ISerializableComparator comparator );
135
136 } // INameList
137
138 /*
139 * $Log: INameList.java,v $
140 * Revision 1.3 2003/02/26 03:38:46 rphall
141 * Added copyright and GPL license
142 *
143 * Revision 1.2 2002/02/18 18:06:05 rphall
144 * Ran dos2unix to remove ^M (carriage return) from end of lines
145 *
146 * Revision 1.1.1.1 2002/01/03 21:57:28 rphall
147 * Initial load, 5th try, Jan-03-2002 4:57 PM
148 *
149 * Revision 1.2 2002/01/01 03:40:33 rphall
150 * Moved getName() from MemberName to MemberView
151 *
152 * Revision 1.1 2002/01/01 00:52:22 rphall
153 * *** empty log message ***
154 *
155 */
156