001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata masks may be redistributed under the GNU General Public
006: * License as published by the Free Software Foundation;
007: * version 2 of the License.
008: *
009: * These programs are free software; you can redistribute them and/or
010: * modify them under the terms of the GNU General Public License
011: * as published by the Free Software Foundation; version 2 of the License.
012: *
013: * These programs are distributed in the hope that they will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: *
017: * See the GNU General Public License in the file LICENSE.txt for more
018: * details.
019: *
020: * If you would like a copy of the GNU General Public License write to
021: *
022: * Free Software Foundation, Inc.
023: * 59 Temple Place - Suite 330
024: * Boston, MA 02111-1307, USA.
025: *
026: *
027: * To arrange commercial support and licensing, contact ivata at
028: * http://www.ivata.com/contact.jsp
029: * -----------------------------------------------------------------------------
030: * $Log: Group.java,v $
031: * Revision 1.6 2005/04/11 12:27:02 colinmacleod
032: * Added preliminary support for filters.
033: * Added FieldValueConvertor factor interface
034: * to split off value convertors for reuse.
035: *
036: * Revision 1.5 2005/04/09 18:04:15 colinmacleod
037: * Changed copyright text to GPL v2 explicitly.
038: *
039: * Revision 1.4 2005/01/19 12:38:05 colinmacleod
040: * Changed Id --> Name.
041: *
042: * Revision 1.3 2005/01/06 22:13:22 colinmacleod
043: * Moved up a version number.
044: * Changed copyright notices to 2005.
045: * Updated the documentation:
046: * - started working on multiproject:site docu.
047: * - changed the logo.
048: * Added checkstyle and fixed LOADS of style issues.
049: * Added separate thirdparty subproject.
050: * Added struts (in web), util and webgui (in webtheme) from ivata op.
051: *
052: * Revision 1.2 2004/12/30 20:15:14 colinmacleod
053: * Moved first and last fields up to Group from Mask.
054: *
055: * Revision 1.1 2004/12/29 20:07:09 colinmacleod
056: * Renamed subproject masks to mask.
057: *
058: * Revision 1.1.1.1 2004/05/16 20:40:32 colinmacleod
059: * Ready for 0.1 release
060: * -----------------------------------------------------------------------------
061: */
062: package com.ivata.mask.group;
063:
064: import java.util.List;
065: import java.util.Set;
066: import com.ivata.mask.field.Field;
067:
068: /**
069: * Instances of this interface define a group of masks which share common field
070: * definitions and other characteristics.
071: *
072: * @since ivata masks 0.1 (2004-02-26)
073: * @author Colin MacLeod
074: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
075: */
076: public interface Group {
077: /**
078: * <p>
079: * Get the field identifiers of all fields which have been excluded from
080: * this and its parents.
081: * </p>
082: * <p>
083: * <b>Note: </b> This will list fields which were explicitly excluded, even
084: * if a parent class included them before.
085: * </p>
086: *
087: * @return list of all excluded field ids, as a <code>List</code> of
088: * <code>String</code> instances.
089: * @see #getExcludedFieldNames
090: */
091: Set getAllExcludedFieldNames();
092:
093: /**
094: * <p>
095: * Get the field identifiers of all fields which should appear at the start
096: * of the group/mask, including those defined by its parent.
097: * </p>
098: *
099: * @return list of all first field ids, as a <code>List</code> of
100: * <code>String</code> instances.
101: * @see #getFirstFieldNames
102: */
103: List getAllFirstFieldNames();
104:
105: /**
106: * <p>
107: * Get the field identifiers of all fields which should appear at the end of
108: * the group/mask, including those defined by its parent.
109: * </p>
110: *
111: * @return list of all last field ids, as a <code>List</code> of
112: * <code>String</code> instances.
113: * @see #getFirstFieldNames
114: */
115: List getAllLastFieldNames();
116:
117: /**
118: * <p>
119: * Get the field ids which have been explicitly excluded from this group.
120: * </p>
121: *
122: * @return the field ids which have been explicitly excluded from this group
123: * (not including those excluded by parent groups).
124: */
125: Set getExcludedFieldNames();
126:
127: /**
128: * <p>
129: * Default field definitions. These can be altered/overridden.
130: * </p>
131: *
132: * @param name name of the field to be returned.
133: * @return read-only copy of the fields.
134: */
135: Field getField(String name);
136:
137: /**
138: * Get all of the filters applied to this group, as a <code>List</code> of
139: * {@link com.ivata.mask.filter.Filter Filter} instances.
140: *
141: * @return all filters as a list.
142: */
143: List getFilters();
144:
145: /**
146: * <p>
147: * Get the ids of all fields which should appear at the start of masks in
148: * this group. For an input mask this usually means the fields will appear
149: * at the top of the page; for a list the fields will appear at the left of
150: * the list.
151: * </p>
152: * <p>
153: * <b>Note </b> that all these fields do not need to be present in all masks
154: * of this group (some value objects may not have all the fields listed).
155: * Those fields which are listed and present in the value object will appear
156: * at the start, in the order given.
157: * </p>
158: *
159: * @return list containing string identifiers of fields which should appear
160: * first in the mask.
161: */
162: List getFirstFieldNames();
163:
164: /**
165: * By explicitly including fields in a mask, you can override fields
166: * excluded by one of its parents.
167: *
168: * @return fields explicitly included (overridden) in this mask.
169: */
170: Set getIncludedFieldNames();
171:
172: /**
173: * <p>
174: * Get the ids of all fields which should appear at the end of masks in this
175: * group. For an input mask this usually means the fields will appear at the
176: * bottom of the page; for a list the fields will appear at the right of the
177: * list.
178: * </p>
179: * <p>
180: * <b>Note </b> that all these fields do not need to be present in all masks
181: * of this group (some value objects may not have all the fields listed).
182: * Those fields which are listed and present in the value object will appear
183: * at the end, in the order given.
184: * </p>
185: *
186: * @return list containing string identifiers of fields which should appear
187: * last in the mask.
188: */
189: List getLastFieldNames();
190:
191: /**
192: * Get the identifier of this group. This identifier is unique within
193: * the system, for groups (but not necessarily for their subclasses).
194: *
195: * @return unique identifier of this group.
196: */
197: String getName();
198:
199: /**
200: * <p>
201: * Get the parent of this group, if any.
202: * </p>
203: *
204: * <p>
205: * Each group or mask can define a parent, from which it can inherit field
206: * definitions and group/mask properties.
207: * </p>
208: *
209: * @return parent of this group, or <code>null</code> if this is a
210: * top-level group.
211: */
212: Group getParent();
213:
214: /**
215: * <p>
216: * If <code>true</code>, only the values in this mask will be displayed.
217: * Otherwise, input fields are displayed.
218: * </p>
219: *
220: * @return whether or not the mask should only display field values.
221: */
222: boolean isDisplayOnly();
223:
224: /**
225: * <p>
226: * When first field identifiers are defined for a group, normally these are
227: * appended to the list of all parent group first field identifiers, i.e.
228: * the list returned by calling
229: * {@link #getFirstFieldNames getFirstFieldNames} on the parent group.
230: * </p>
231: * <p>
232: * This is the standard, default behavior when this method returns
233: * <code>false</code>. However, if this method returns <code>true</code>,
234: * then the first field identifiers in this group override (replace) the
235: * list returned by the group's parents.
236: * </p>
237: *
238: * @return <code>true</code> if this group replaces the list of first
239: * field ids defined by parent groups, otherwise <code>false</code>
240: * if this group's list will be appended to that of its parents.
241: * @see #getFirstFieldNames
242: */
243: boolean isParentFirstFieldNamesReplaced();
244:
245: /**
246: * <p>
247: * When last field identifiers are defined for a group, normally these are
248: * appended to the list of all parent group last field identifiers, i.e. the
249: * list returned by calling {@link #getLastFieldNames getLastFieldNames} on
250: * the parent group.
251: * </p>
252: * <p>
253: * This is the standard, default behavior when this method returns
254: * <code>false</code>. However, if this method returns <code>true</code>,
255: * then the last field identifiers in this group override (replace) the list
256: * returned by the group's parents.
257: * </p>
258: *
259: * @return <code>true</code> if this group replaces the list of last field
260: * ids defined by parent groups, otherwise <code>false</code> if
261: * this group's list will be appended to that of its parents.
262: * @see #getLastFieldNames
263: */
264: boolean isParentLastFieldNamesReplaced();
265: }
|