View Javadoc

1   /*
2    * Copyright (c) 2001 - 2005 ivata limited.
3    * All rights reserved.
4    * -----------------------------------------------------------------------------
5    * ivata masks may be redistributed under the GNU General Public
6    * License as published by the Free Software Foundation;
7    * version 2 of the License.
8    *
9    * These programs are free software; you can redistribute them and/or
10   * modify them under the terms of the GNU General Public License
11   * as published by the Free Software Foundation; version 2 of the License.
12   *
13   * These programs are distributed in the hope that they will be useful,
14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16   *
17   * See the GNU General Public License in the file LICENSE.txt for more
18   * details.
19   *
20   * If you would like a copy of the GNU General Public License write to
21   *
22   * Free Software Foundation, Inc.
23   * 59 Temple Place - Suite 330
24   * Boston, MA 02111-1307, USA.
25   *
26   *
27   * To arrange commercial support and licensing, contact ivata at
28   *                  http://www.ivata.com/contact.jsp
29   * -----------------------------------------------------------------------------
30   * $Log: Group.java,v $
31   * Revision 1.6  2005/04/11 12:27:02  colinmacleod
32   * Added preliminary support for filters.
33   * Added FieldValueConvertor factor interface
34   * to split off value convertors for reuse.
35   *
36   * Revision 1.5  2005/04/09 18:04:15  colinmacleod
37   * Changed copyright text to GPL v2 explicitly.
38   *
39   * Revision 1.4  2005/01/19 12:38:05  colinmacleod
40   * Changed Id --> Name.
41   *
42   * Revision 1.3  2005/01/06 22:13:22  colinmacleod
43   * Moved up a version number.
44   * Changed copyright notices to 2005.
45   * Updated the documentation:
46   *   - started working on multiproject:site docu.
47   *   - changed the logo.
48   * Added checkstyle and fixed LOADS of style issues.
49   * Added separate thirdparty subproject.
50   * Added struts (in web), util and webgui (in webtheme) from ivata op.
51   *
52   * Revision 1.2  2004/12/30 20:15:14  colinmacleod
53   * Moved first and last fields up to Group from Mask.
54   *
55   * Revision 1.1  2004/12/29 20:07:09  colinmacleod
56   * Renamed subproject masks to mask.
57   *
58   * Revision 1.1.1.1  2004/05/16 20:40:32  colinmacleod
59   * Ready for 0.1 release
60   * -----------------------------------------------------------------------------
61   */
62  package com.ivata.mask.group;
63  import java.util.List;
64  import java.util.Set;
65  import com.ivata.mask.field.Field;
66  /***
67   * Instances of this interface define a group of masks which share common field
68   * definitions and other characteristics.
69   *
70   * @since ivata masks 0.1 (2004-02-26)
71   * @author Colin MacLeod
72   * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
73   */
74  public interface Group {
75      /***
76       * <p>
77       * Get the field identifiers of all fields which have been excluded from
78       * this and its parents.
79       * </p>
80       * <p>
81       * <b>Note: </b> This will list fields which were explicitly excluded, even
82       * if a parent class included them before.
83       * </p>
84       *
85       * @return list of all excluded field ids, as a <code>List</code> of
86       *         <code>String</code> instances.
87       * @see #getExcludedFieldNames
88       */
89      Set getAllExcludedFieldNames();
90      /***
91       * <p>
92       * Get the field identifiers of all fields which should appear at the start
93       * of the group/mask, including those defined by its parent.
94       * </p>
95       *
96       * @return list of all first field ids, as a <code>List</code> of
97       *         <code>String</code> instances.
98       * @see #getFirstFieldNames
99       */
100     List getAllFirstFieldNames();
101     /***
102      * <p>
103      * Get the field identifiers of all fields which should appear at the end of
104      * the group/mask, including those defined by its parent.
105      * </p>
106      *
107      * @return list of all last field ids, as a <code>List</code> of
108      *         <code>String</code> instances.
109      * @see #getFirstFieldNames
110      */
111     List getAllLastFieldNames();
112     /***
113      * <p>
114      * Get the field ids which have been explicitly excluded from this group.
115      * </p>
116      *
117      * @return the field ids which have been explicitly excluded from this group
118      *         (not including those excluded by parent groups).
119      */
120     Set getExcludedFieldNames();
121     /***
122      * <p>
123      * Default field definitions. These can be altered/overridden.
124      * </p>
125      *
126      * @param name name of the field to be returned.
127      * @return read-only copy of the fields.
128      */
129     Field getField(String name);
130     /***
131      * Get all of the filters applied to this group, as a <code>List</code> of
132      * {@link com.ivata.mask.filter.Filter Filter} instances.
133      *
134      * @return all filters as a list.
135      */
136     List getFilters();
137     /***
138      * <p>
139      * Get the ids of all fields which should appear at the start of masks in
140      * this group. For an input mask this usually means the fields will appear
141      * at the top of the page; for a list the fields will appear at the left of
142      * the list.
143      * </p>
144      * <p>
145      * <b>Note </b> that all these fields do not need to be present in all masks
146      * of this group (some value objects may not have all the fields listed).
147      * Those fields which are listed and present in the value object will appear
148      * at the start, in the order given.
149      * </p>
150      *
151      * @return list containing string identifiers of fields which should appear
152      *         first in the mask.
153      */
154     List getFirstFieldNames();
155     /***
156      * By explicitly including fields in a mask, you can override fields
157      * excluded by one of its parents.
158      *
159      * @return fields explicitly included (overridden) in this mask.
160      */
161     Set getIncludedFieldNames();
162     /***
163      * <p>
164      * Get the ids of all fields which should appear at the end of masks in this
165      * group. For an input mask this usually means the fields will appear at the
166      * bottom of the page; for a list the fields will appear at the right of the
167      * list.
168      * </p>
169      * <p>
170      * <b>Note </b> that all these fields do not need to be present in all masks
171      * of this group (some value objects may not have all the fields listed).
172      * Those fields which are listed and present in the value object will appear
173      * at the end, in the order given.
174      * </p>
175      *
176      * @return list containing string identifiers of fields which should appear
177      *         last in the mask.
178      */
179     List getLastFieldNames();
180     /***
181      * Get the identifier of this group. This identifier is unique within
182      * the system, for groups (but not necessarily for their subclasses).
183      *
184      * @return unique identifier of this group.
185      */
186     String getName();
187     /***
188      * <p>
189      * Get the parent of this group, if any.
190      * </p>
191      *
192      * <p>
193      * Each group or mask can define a parent, from which it can inherit field
194      * definitions and group/mask properties.
195      * </p>
196      *
197      * @return parent of this group, or <code>null</code> if this is a
198      *         top-level group.
199      */
200     Group getParent();
201     /***
202      * <p>
203      * If <code>true</code>, only the values in this mask will be displayed.
204      * Otherwise, input fields are displayed.
205      * </p>
206      *
207      * @return whether or not the mask should only display field values.
208      */
209     boolean isDisplayOnly();
210     /***
211      * <p>
212      * When first field identifiers are defined for a group, normally these are
213      * appended to the list of all parent group first field identifiers, i.e.
214      * the list returned by calling
215      * {@link #getFirstFieldNames getFirstFieldNames} on the parent group.
216      * </p>
217      * <p>
218      * This is the standard, default behavior when this method returns
219      * <code>false</code>. However, if this method returns <code>true</code>,
220      * then the first field identifiers in this group override (replace) the
221      * list returned by the group's parents.
222      * </p>
223      *
224      * @return <code>true</code> if this group replaces the list of first
225      *         field ids defined by parent groups, otherwise <code>false</code>
226      *         if this group's list will be appended to that of its parents.
227      * @see #getFirstFieldNames
228      */
229     boolean isParentFirstFieldNamesReplaced();
230     /***
231      * <p>
232      * When last field identifiers are defined for a group, normally these are
233      * appended to the list of all parent group last field identifiers, i.e. the
234      * list returned by calling {@link #getLastFieldNames getLastFieldNames} on
235      * the parent group.
236      * </p>
237      * <p>
238      * This is the standard, default behavior when this method returns
239      * <code>false</code>. However, if this method returns <code>true</code>,
240      * then the last field identifiers in this group override (replace) the list
241      * returned by the group's parents.
242      * </p>
243      *
244      * @return <code>true</code> if this group replaces the list of last field
245      *         ids defined by parent groups, otherwise <code>false</code> if
246      *         this group's list will be appended to that of its parents.
247      * @see #getLastFieldNames
248      */
249     boolean isParentLastFieldNamesReplaced();
250 }