KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > tigris > scarab > om > Module


1 package org.tigris.scarab.om;
2
3 /* ================================================================
4  * Copyright (c) 2001-2003 Collab.Net. All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are
8  * met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  *
13  * 2. Redistributions in binary form must reproduce the above copyright
14  * notice, this list of conditions and the following disclaimer in the
15  * documentation and/or other materials provided with the distribution.
16  *
17  * 3. The end-user documentation included with the redistribution, if
18  * any, must include the following acknowlegement: "This product includes
19  * software developed by Collab.Net <http://www.Collab.Net/>."
20  * Alternately, this acknowlegement may appear in the software itself, if
21  * and wherever such third-party acknowlegements normally appear.
22  *
23  * 4. The hosted project names must not be used to endorse or promote
24  * products derived from this software without prior written
25  * permission. For written permission, please contact info@collab.net.
26  *
27  * 5. Products derived from this software may not use the "Tigris" or
28  * "Scarab" names nor may "Tigris" or "Scarab" appear in their names without
29  * prior written permission of Collab.Net.
30  *
31  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
32  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
33  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
34  * IN NO EVENT SHALL COLLAB.NET OR ITS CONTRIBUTORS BE LIABLE FOR ANY
35  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
37  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
38  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
39  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
40  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
41  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42  *
43  * ====================================================================
44  *
45  * This software consists of voluntary contributions made by many
46  * individuals on behalf of Collab.Net.
47  */

48
49 import java.io.Serializable JavaDoc;
50 import java.util.List JavaDoc;
51 import java.util.Locale JavaDoc;
52
53 import org.apache.regexp.REProgram;
54
55 import org.tigris.scarab.om.Attribute;
56 import org.tigris.scarab.om.RModuleAttribute;
57 import org.tigris.scarab.om.Issue;
58 import org.tigris.scarab.om.IssueType;
59 import org.tigris.scarab.om.MITList;
60 import org.tigris.scarab.om.ScarabUser;
61 import org.tigris.scarab.om.RModuleIssueType;
62 import org.tigris.scarab.om.RModuleOption;
63 import org.tigris.scarab.om.AttributeOption;
64 import org.tigris.scarab.om.AttributeGroup;
65 import org.tigris.scarab.util.ScarabPaginatedList;
66
67 import org.apache.torque.TorqueException;
68 import org.apache.torque.om.ObjectKey;
69 import org.apache.torque.util.Criteria;
70
71 /**
72  * This class describes a Module within the Scarab system
73  *
74  * @author <a HREF="mailto:jon@collab.net">Jon S. Stevens</a>
75  * @version $Id: Module.java 9476 2005-03-16 22:56:11Z dabbous $
76  */

77 public interface Module
78     extends Serializable JavaDoc
79 {
80     /**
81      * The deliminator between parent/child Modules
82      * This is used to build up the getName() results.
83      * FIXME: define this in a properties file
84      */

85     String JavaDoc NAME_DELIMINATOR = " > ";
86
87     Integer JavaDoc ROOT_ID = new Integer JavaDoc(0);
88
89     String JavaDoc USER = "user";
90     String JavaDoc NON_USER = "non-user";
91
92     /**
93      * Get a list of <code>ScarabUser</code>'s that have the given
94      * permission in the given module.
95      *
96      * @param permission a <code>String</code> value
97      * @return ScarabUser[]
98      */

99     ScarabUser[] getUsers(String JavaDoc permission) throws Exception JavaDoc;
100
101     /**
102      * Get a list of <code>ScarabUser</code>'s that have any of the given
103      * permissions in the given module.
104      *
105      * @param permissions a <code>List</code> value
106      * @return ScarabUser[]
107      */

108     ScarabUser[] getUsers(List JavaDoc permissions) throws Exception JavaDoc;
109
110
111     /**
112      * Gets users which match all of the given criteria and have at least
113      * one permission that is applicable to user attributes active in the
114      * given issue type. The String arguments may be null. Implementations
115      * are encouraged to include users where the given Strings are
116      * contained within respective fields. So firstName=fred would return
117      * a user named fredrick.
118      */

119     List JavaDoc getUsers(String JavaDoc firstName, String JavaDoc lastName, String JavaDoc username,
120                          String JavaDoc email, IssueType issueType)
121         throws Exception JavaDoc;
122
123     /**
124      * Gets users for a given criteria, starting at a particular offset,
125      * for a given length, and have at least one permission that is
126      * applicable to user attributes active in the given issue type.
127      * This method handles the case where limiting the result size
128      * is best accomplished by limiting the database transaction
129      * size, and not postfiltering the list. This is extremely helpful
130      * with large user datasets.
131      */

132     ScarabPaginatedList getUsers(String JavaDoc name, String JavaDoc username,
133                                         MITList mitList,
134                                         int offset, int resultSize,
135                                         String JavaDoc sortColumn, String JavaDoc sortPolarity,
136                                         boolean includeCommitters)
137         throws Exception JavaDoc;
138
139     /**
140      * This method is only used by the Turbine Group interface.
141      * The implementation of getName() returns a unique name for
142      * this Module that is human readable because our
143      * implementation of Flux needs it as well as the fact that
144      * each Group needs to have a unique name. If you want to get
145      * the actual name of the Module, you need to call the getRealName
146      * method.
147      */

148     String JavaDoc getName();
149     void setName(String JavaDoc name);
150
151     /**
152      * This method is only used by the Turbine Group interface.
153      * The implementation of getName() returns a unique name for
154      * this Module that is human readable because our
155      * implementation of Flux needs it as well as the fact that
156      * each Group needs to have a unique name. If you want to get
157      * the actual name of the Module, you need to call the getRealName
158      * method.
159      */

160     String JavaDoc getRealName();
161     void setRealName(String JavaDoc name);
162
163     String JavaDoc getCode();
164     void setCode(String JavaDoc code);
165
166     /** www.foo.com */
167     String JavaDoc getHttpDomain();
168     void setHttpDomain(String JavaDoc domain);
169
170     /** arbitrary value, represents the individual instance
171      * on which this module has been created.
172      **/

173     String JavaDoc getScarabInstanceId();
174     void setScarabInstanceId(String JavaDoc domain);
175
176     /** the port number used for the domain */
177     String JavaDoc getPort() throws Exception JavaDoc;
178     void setPort(String JavaDoc port) throws Exception JavaDoc;
179     
180     /** the scheme (http|https) used */
181     String JavaDoc getScheme() throws Exception JavaDoc;
182     void setScheme(String JavaDoc scheme) throws Exception JavaDoc;
183
184     /** the scriptName used: /scarab/issues */
185     String JavaDoc getScriptName() throws Exception JavaDoc;
186     void setScriptName(String JavaDoc scriptName) throws Exception JavaDoc;
187
188     String JavaDoc getDescription();
189     void setDescription(String JavaDoc description);
190
191     String JavaDoc getUrl();
192     void setUrl(String JavaDoc url);
193
194     ObjectKey getPrimaryKey();
195     void setPrimaryKey(ObjectKey key) throws Exception JavaDoc;
196     Integer JavaDoc getModuleId();
197     void setModuleId(Integer JavaDoc v) throws TorqueException;
198     
199 /** @deprecated THESE WILL BE DEPRECATED */
200     Integer JavaDoc getQaContactId();
201 /** @deprecated THESE WILL BE DEPRECATED */
202     void setQaContactId(Integer JavaDoc v) throws Exception JavaDoc;
203
204     Integer JavaDoc getOwnerId();
205     void setOwnerId(Integer JavaDoc v) throws Exception JavaDoc;
206
207     void save() throws Exception JavaDoc;
208
209     /**
210      * gets a list of all of the Attributes in a Module based on the Criteria.
211      */

212     List JavaDoc getAttributes(Criteria criteria)
213         throws Exception JavaDoc;
214
215     /**
216      * Gets a list of attributes for this module with a specific
217      * issue type.
218      */

219     List JavaDoc getAttributes(IssueType issueType)
220         throws Exception JavaDoc;
221
222     /**
223      * Gets a list of all of the Attributes in this module.
224      */

225     List JavaDoc getAllAttributes()
226         throws Exception JavaDoc;
227
228     /**
229      * Creates new attribute group.
230      */

231     AttributeGroup createNewGroup (IssueType issueType)
232         throws Exception JavaDoc;
233
234     /**
235      * This method is used within Wizard1.vm to get a list of attribute
236      * groups which are marked as dedupe and have a list of attributes
237      * in them.
238      */

239     List JavaDoc getDedupeGroupsWithAttributes(IssueType issueType)
240         throws Exception JavaDoc;
241
242     /**
243      * List of active dedupe attribute groups associated with this module.
244      */

245     List JavaDoc getDedupeAttributeGroups(IssueType issueType)
246         throws Exception JavaDoc;
247
248     /**
249      * List of attribute groups associated with this module.
250      */

251     List JavaDoc getDedupeAttributeGroups(IssueType issueType,
252                                          boolean activeOnly)
253         throws Exception JavaDoc;
254
255     /**
256      * Gets the sequence where the dedupe screen fits between groups.
257      */

258     int getDedupeSequence(IssueType issueType)
259         throws Exception JavaDoc;
260
261     List JavaDoc getRModuleAttributes(IssueType issueType, boolean activeOnly,
262                                      String JavaDoc attributeType)
263         throws Exception JavaDoc;
264
265     List JavaDoc getRModuleAttributes(IssueType issueType, boolean activeOnly)
266         throws Exception JavaDoc;
267
268     List JavaDoc getRModuleAttributes(IssueType issueType)
269         throws Exception JavaDoc;
270
271     List JavaDoc getRModuleAttributes(Criteria criteria)
272         throws Exception JavaDoc;
273
274     /**
275      * Returns default issue list attributes for this module.
276      */

277     List JavaDoc getDefaultRModuleUserAttributes(IssueType issueType)
278         throws Exception JavaDoc;
279
280     RModuleAttribute getRModuleAttribute(Attribute attribute,
281                                                 IssueType issueType)
282         throws Exception JavaDoc;
283     int getLastAttribute(IssueType issueType, String JavaDoc attributeType)
284         throws Exception JavaDoc;
285
286     int getLastAttributeOption(Attribute attribute,
287                                       IssueType issueType)
288         throws Exception JavaDoc;
289
290     String JavaDoc getQueryKey();
291
292     boolean getDeleted();
293     void setDeleted(boolean b);
294
295     Integer JavaDoc getParentId() throws TorqueException;
296     void setParentId(Integer JavaDoc v) throws TorqueException;
297
298     void setParent(Module module)
299         throws Exception JavaDoc;
300
301     /**
302      * Same as the getModuleRelatedByParentIdCast(), just a better name.
303      */

304     Module getParent() throws Exception JavaDoc;
305
306     /**
307      * Returns this ModuleEntities ancestors in ascending order.
308      * It does not return the 0 parent though.
309      */

310     List JavaDoc getAncestors() throws Exception JavaDoc;
311
312     /**
313      * check for endless loops where Module A > Module B > Module A
314      */

315     boolean isEndlessLoop(Module parent)
316         throws Exception JavaDoc;
317     
318     Issue getNewIssue(IssueType issueType)
319         throws Exception JavaDoc;
320
321     List JavaDoc getRModuleIssueTypes()
322         throws TorqueException;
323         
324     List JavaDoc getRModuleOptions(Attribute attribute, IssueType issueType)
325         throws Exception JavaDoc;
326
327     List JavaDoc getRModuleOptions(Attribute attribute, IssueType issueType,
328                                   boolean activeOnly)
329         throws Exception JavaDoc;
330
331     List JavaDoc getRModuleOptions(Criteria crit)
332         throws Exception JavaDoc;
333
334     List JavaDoc getLeafRModuleOptions(Attribute attribute, IssueType issueType)
335         throws Exception JavaDoc;
336
337     List JavaDoc getLeafRModuleOptions(Attribute attribute, IssueType issueType,
338                                       boolean activeOnly)
339         throws Exception JavaDoc;
340
341     RModuleOption getRModuleOption(AttributeOption option,
342                                           IssueType issueType)
343         throws Exception JavaDoc;
344
345     ScarabUser[] getEligibleUsers(Attribute attribute)
346         throws Exception JavaDoc;
347
348     ScarabUser[] getEligibleIssueReporters()
349         throws Exception JavaDoc;
350
351     /**
352      * List of saved reports associated with this module and
353      * created by the given user.
354      * @param user the user
355      * @return a <code>List</code> value
356      */

357     List JavaDoc getSavedReports(ScarabUser user)
358         throws Exception JavaDoc;
359
360     List JavaDoc getUserAttributes(IssueType issueType, boolean activeOnly)
361         throws Exception JavaDoc;
362
363     List JavaDoc getUserAttributes(IssueType issueType)
364         throws Exception JavaDoc;
365
366     List JavaDoc getUserPermissions(IssueType issueType)
367         throws Exception JavaDoc;
368
369     RModuleIssueType getRModuleIssueType(IssueType issueType)
370         throws Exception JavaDoc;
371
372     void addIssueType(IssueType issueType)
373         throws Exception JavaDoc;
374
375     void addAttributeOption(IssueType issueType, AttributeOption option)
376         throws Exception JavaDoc;
377
378     /**
379      * Adds module-attribute mapping to module.
380      */

381     RModuleAttribute addRModuleAttribute(IssueType issueType,
382                                                 Attribute attribute)
383         throws Exception JavaDoc;
384
385     /**
386      * Adds module-attribute-option mapping to module.
387      */

388     RModuleOption addRModuleOption(IssueType issueType,
389                                           AttributeOption option)
390         throws Exception JavaDoc;
391
392     List JavaDoc getIssueTypes()
393         throws Exception JavaDoc;
394
395     List JavaDoc getIssueTypes(boolean activeOnly)
396         throws Exception JavaDoc;
397     
398     List JavaDoc getTemplateTypes()
399         throws Exception JavaDoc;
400
401     List JavaDoc getNavIssueTypes()
402         throws Exception JavaDoc;
403
404     /**
405      * Determines whether this module allows users to vote many times for
406      * the same issue. This feature needs schema change to allow a
407      * configuration screen. Currently only one vote per issue is supported
408      *
409      * @return false
410      */

411     boolean allowsMultipleVoting();
412
413     /**
414      * How many votes does the user have left to cast. Currently always
415      * returns 1, so a user has unlimited voting rights. Should look to
416      * UserVote for the answer when implemented properly.
417      */

418     int getUnusedVoteCount(ScarabUser user);
419
420     /**
421      * Returns list of queries needing approval.
422      */

423     List JavaDoc getUnapprovedQueries() throws Exception JavaDoc;
424
425     /**
426      * Returns list of enter issue templates needing approval.
427      */

428     List JavaDoc getUnapprovedTemplates() throws Exception JavaDoc;
429
430     /**
431      * Gets a list of active RModuleOptions which have had their level
432      * within the options for this module set.
433      *
434      * @param attribute an <code>Attribute</code> value
435      * @return a <code>List</code> value
436      * @exception Exception if an error occurs
437      */

438     List JavaDoc getOptionTree(Attribute attribute, IssueType issueType)
439         throws Exception JavaDoc;
440
441     /**
442      * Gets a list of RModuleOptions which have had their level
443      * within the options for this module set.
444      *
445      * @param attribute an <code>Attribute</code> value
446      * @param activeOnly a <code>boolean</code> value
447      * @return a <code>List</code> value
448      * @exception Exception if an error occurs
449      */

450     List JavaDoc getOptionTree(Attribute attribute, IssueType issueType,
451                               boolean activeOnly)
452         throws Exception JavaDoc;
453
454     /**
455      * All emails related to this module will have a copy sent to
456      * this address.
457      */

458     String JavaDoc getArchiveEmail();
459
460     /**
461      * The default address that is used to fill out either the From or
462      * ReplyTo header on emails related to this module. In many cases
463      * the From field is taken as the user who acted that resulted in the
464      * email, but replies should still go to the central location for
465      * the module, so in this address would be used in the ReplyTo field.
466      *
467      * @return a <code>String[]</code> of length=2 where the first element
468      * is a name such as "Scarab System" and the second is an email address.
469      */

470     String JavaDoc[] getSystemEmail();
471
472     /**
473      * Determines whether this module is accepting new issues.
474      */

475     boolean allowsNewIssues();
476
477     /**
478      * Determines whether this module accepts issues.
479      */

480     boolean allowsIssues();
481
482     /**
483      * Returns true if no issue types are associated with this module, or if the module
484      * is currently getting its initial values set.
485      */

486     boolean isInitializing()
487         throws Exception JavaDoc;
488
489     /**
490      * Returns true if this module is the the top level parent module.
491      *
492      * @return a <code>boolean</code> value
493      */

494     boolean isGlobalModule();
495
496     /**
497      * returns a compiled regex that can used to create a new RE
498      * for matching some given text.
499      */

500     REProgram getIssueRegex()
501         throws TorqueException;
502
503     /**
504      * This method is useful for getting an issue object
505      * by a String id. It has some logic in it for appending
506      * the Module Code as well as stripping spaces off the
507      * id value using the String.trim() method.
508      * @deprecated use IssueManager.getIssueById(String id, String defaultCode)
509      * I think this method should only return issues from this module,
510      * but there is only one place in the code where something like that
511      * was needed and the check is done there. Its possible we would want
512      * to define this method to return issues in children or some other
513      * criteria. deprecating for removal until a definite reason for it to
514      * exist appears.
515      */

516     Issue getIssueById(String JavaDoc id)
517         throws Exception JavaDoc;
518
519     String JavaDoc toString();
520  
521     List JavaDoc getRoles() throws Exception JavaDoc;
522
523     /**
524      * The default locale for this module will be used in cases
525      * where a response is going to no particular user (a mailing
526      * list) or can also be used as a default in cases where
527      * a user does not have a preference.
528      *
529      * @return a <code>Locale</code> value
530      */

531     Locale JavaDoc getLocale();
532 }
533
534
Popular Tags