001: package org.tigris.scarab.om;
002:
003: /* ================================================================
004: * Copyright (c) 2001-2005 Collab.Net. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions are
008: * met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in the
015: * documentation and/or other materials provided with the distribution.
016: *
017: * 3. The end-user documentation included with the redistribution, if
018: * any, must include the following acknowlegement: "This product includes
019: * software developed by Collab.Net <http://www.Collab.Net/>."
020: * Alternately, this acknowlegement may appear in the software itself, if
021: * and wherever such third-party acknowlegements normally appear.
022: *
023: * 4. The hosted project names must not be used to endorse or promote
024: * products derived from this software without prior written
025: * permission. For written permission, please contact info@collab.net.
026: *
027: * 5. Products derived from this software may not use the "Tigris" or
028: * "Scarab" names nor may "Tigris" or "Scarab" appear in their names without
029: * prior written permission of Collab.Net.
030: *
031: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
032: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
033: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
034: * IN NO EVENT SHALL COLLAB.NET OR ITS CONTRIBUTORS BE LIABLE FOR ANY
035: * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
036: * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
037: * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
038: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
039: * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
040: * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
041: * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
042: *
043: * ====================================================================
044: *
045: * This software consists of voluntary contributions made by many
046: * individuals on behalf of Collab.Net.
047: */
048:
049: import com.workingdogs.village.DataSetException;
050: import java.io.Serializable;
051: import java.util.List;
052: import java.util.Locale;
053:
054: import org.apache.fulcrum.security.entity.Role;
055: import org.apache.regexp.REProgram;
056:
057: import org.tigris.scarab.om.Attribute;
058: import org.tigris.scarab.om.RModuleAttribute;
059: import org.tigris.scarab.om.Issue;
060: import org.tigris.scarab.om.IssueType;
061: import org.tigris.scarab.om.MITList;
062: import org.tigris.scarab.om.ScarabUser;
063: import org.tigris.scarab.om.RModuleIssueType;
064: import org.tigris.scarab.om.RModuleOption;
065: import org.tigris.scarab.om.AttributeOption;
066: import org.tigris.scarab.om.AttributeGroup;
067: import org.tigris.scarab.tools.localization.L10NKey;
068: import org.tigris.scarab.util.ScarabException;
069: import org.tigris.scarab.util.ScarabPaginatedList;
070:
071: import org.apache.torque.TorqueException;
072: import org.apache.torque.om.ObjectKey;
073: import org.apache.torque.om.Persistent;
074: import org.apache.torque.util.Criteria;
075: import org.tigris.scarab.util.ValidationException;
076:
077: /**
078: * This class describes a Module within the Scarab system
079: *
080: * @author <a href="mailto:jon@collab.net">Jon S. Stevens</a>
081: * @version $Id: Module.java 10198 2006-07-03 23:33:30Z dabbous $
082: */
083: public interface Module extends Serializable, Persistent {
084: /**
085: * The deliminator between parent/child Modules
086: * This is used to build up the getName() results.
087: */
088: final L10NKey NAME_DELIMINATOR = new L10NKey("ModuleDeliminator");//" > ";
089:
090: final Integer ROOT_ID = new Integer(0);
091:
092: final String USER = "user";
093: final String NON_USER = "non-user";
094:
095: /**
096: * Get a list of <code>ScarabUser</code>'s that have the given
097: * permission in the given module.
098: *
099: * @param permission a <code>String</code> value
100: * @return ScarabUser[]
101: */
102: ScarabUser[] getUsers(String permission) throws TorqueException;
103:
104: /**
105: * Get a list of <code>ScarabUser</code>'s that have any of the given
106: * permissions in the given module.
107: *
108: * @param permissions a <code>List</code> value
109: * @return ScarabUser[]
110: */
111: ScarabUser[] getUsers(List permissions) throws TorqueException;
112:
113: /**
114: * Gets users which match all of the given criteria and have at least
115: * one permission that is applicable to user attributes active in the
116: * given issue type. The String arguments may be null. Implementations
117: * are encouraged to include users where the given Strings are
118: * contained within respective fields. So firstName=fred would return
119: * a user named fredrick.
120: */
121: List getUsers(String firstName, String lastName, String username,
122: String email, IssueType issueType) throws TorqueException;
123:
124: /**
125: * Gets users for a given criteria, starting at a particular offset,
126: * for a given length, and have at least one permission that is
127: * applicable to user attributes active in the given issue type.
128: * This method handles the case where limiting the result size
129: * is best accomplished by limiting the database transaction
130: * size, and not postfiltering the list. This is extremely helpful
131: * with large user datasets.
132: */
133: ScarabPaginatedList getUsers(String name, String username,
134: MITList mitList, int offset, int resultSize,
135: String sortColumn, String sortPolarity,
136: boolean includeCommitters) throws TorqueException,
137: DataSetException;
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 getName();
149:
150: void setName(String name);
151:
152: /**
153: * This method is only used by the Turbine Group interface.
154: * The implementation of getName() returns a unique name for
155: * this Module that is human readable because our
156: * implementation of Flux needs it as well as the fact that
157: * each Group needs to have a unique name. If you want to get
158: * the actual name of the Module, you need to call the getRealName
159: * method.
160: */
161: String getRealName();
162:
163: void setRealName(String name);
164:
165: String getCode();
166:
167: void setCode(String code);
168:
169: /** www.foo.com */
170: String getHttpDomain();
171:
172: void setHttpDomain(String domain);
173:
174: /** arbitrary value, represents the individual instance
175: * on which this module has been created.
176: **/
177: String getScarabInstanceId();
178:
179: void setScarabInstanceId(String domain);
180:
181: /** the port number used for the domain */
182: String getPort() throws TorqueException;
183:
184: void setPort(String port) throws TorqueException;
185:
186: /** the scheme (http|https) used */
187: String getScheme() throws TorqueException;
188:
189: void setScheme(String scheme) throws TorqueException;
190:
191: /** the scriptName used: /scarab/issues */
192: String getScriptName() throws TorqueException;
193:
194: void setScriptName(String scriptName) throws TorqueException;
195:
196: String getDescription();
197:
198: void setDescription(String description);
199:
200: String getUrl();
201:
202: void setUrl(String url);
203:
204: ObjectKey getPrimaryKey();
205:
206: void setPrimaryKey(ObjectKey key) throws TorqueException;
207:
208: Integer getModuleId();
209:
210: void setModuleId(Integer v) throws TorqueException;
211:
212: /** @deprecated THESE WILL BE DEPRECATED */
213: Integer getQaContactId();
214:
215: /** @deprecated THESE WILL BE DEPRECATED */
216: void setQaContactId(Integer v) throws TorqueException;
217:
218: Integer getOwnerId();
219:
220: void setOwnerId(Integer v) throws TorqueException;
221:
222: /**
223: * gets a list of all of the Attributes in a Module based on the Criteria.
224: */
225: List getAttributes(Criteria criteria) throws TorqueException;
226:
227: /**
228: * Gets a list of attributes for this module with a specific
229: * issue type.
230: */
231: List getAttributes(IssueType issueType) throws TorqueException;
232:
233: /**
234: * Gets a list of all of the Attributes in this module.
235: */
236: List getAllAttributes() throws TorqueException;
237:
238: /**
239: * Creates new attribute group.
240: */
241: AttributeGroup createNewGroup(IssueType issueType)
242: throws TorqueException;
243:
244: /**
245: * This method is used within Wizard1.vm to get a list of attribute
246: * groups which are marked as dedupe and have a list of attributes
247: * in them.
248: */
249: List getDedupeGroupsWithAttributes(IssueType issueType)
250: throws TorqueException;
251:
252: /**
253: * List of active dedupe attribute groups associated with this module.
254: */
255: List getDedupeAttributeGroups(IssueType issueType)
256: throws TorqueException;
257:
258: /**
259: * List of attribute groups associated with this module.
260: */
261: List getDedupeAttributeGroups(IssueType issueType,
262: boolean activeOnly) throws TorqueException;
263:
264: /**
265: * Gets the sequence where the dedupe screen fits between groups.
266: */
267: int getDedupeSequence(IssueType issueType) throws TorqueException;
268:
269: List getRModuleAttributes(IssueType issueType, boolean activeOnly,
270: String attributeType) throws TorqueException;
271:
272: List getRModuleAttributes(IssueType issueType, boolean activeOnly)
273: throws TorqueException;
274:
275: List getRModuleAttributes(IssueType issueType)
276: throws TorqueException;
277:
278: List getRModuleAttributes(Criteria criteria) throws TorqueException;
279:
280: /**
281: * Returns default issue list attributes for this module.
282: */
283: List getDefaultRModuleUserAttributes(IssueType issueType)
284: throws TorqueException;
285:
286: RModuleAttribute getRModuleAttribute(Attribute attribute,
287: IssueType issueType) throws TorqueException;
288:
289: int getLastAttribute(IssueType issueType, String attributeType)
290: throws TorqueException;
291:
292: int getLastAttributeOption(Attribute attribute, IssueType issueType)
293: throws TorqueException;
294:
295: String getQueryKey();
296:
297: boolean getDeleted();
298:
299: void setDeleted(boolean b);
300:
301: Integer getParentId() throws TorqueException;
302:
303: void setParentId(Integer v) throws TorqueException;
304:
305: void setParent(Module module) throws TorqueException;
306:
307: /**
308: * Same as the getModuleRelatedByParentIdCast(), just a better name.
309: */
310: Module getParent() throws TorqueException;
311:
312: /**
313: * Returns this ModuleEntities ancestors in ascending order.
314: * It does not return the 0 parent though.
315: */
316: List getAncestors() throws TorqueException;
317:
318: /**
319: * check for endless loops where Module A > Module B > Module A
320: */
321: boolean isEndlessLoop(Module parent) throws TorqueException;
322:
323: Issue getNewIssue(IssueType issueType) throws TorqueException;
324:
325: List getRModuleIssueTypes() throws TorqueException;
326:
327: List getRModuleOptions(Attribute attribute, IssueType issueType)
328: throws TorqueException;
329:
330: List getRModuleOptions(Attribute attribute, IssueType issueType,
331: boolean activeOnly) throws TorqueException;
332:
333: List getRModuleOptions(Criteria crit) throws TorqueException;
334:
335: List getLeafRModuleOptions(Attribute attribute, IssueType issueType)
336: throws TorqueException;
337:
338: List getLeafRModuleOptions(Attribute attribute,
339: IssueType issueType, boolean activeOnly)
340: throws TorqueException;
341:
342: RModuleOption getRModuleOption(AttributeOption option,
343: IssueType issueType) throws TorqueException;
344:
345: ScarabUser[] getEligibleUsers(Attribute attribute)
346: throws TorqueException, ScarabException;
347:
348: ScarabUser[] getEligibleIssueReporters() throws TorqueException;
349:
350: /**
351: * List of saved reports associated with this module and
352: * created by the given user.
353: * @param user the user
354: * @return a <code>List</code> value
355: */
356: List getSavedReports(ScarabUser user) throws TorqueException,
357: ScarabException;
358:
359: List getUserAttributes(IssueType issueType, boolean activeOnly)
360: throws TorqueException;
361:
362: List getUserAttributes(IssueType issueType) throws TorqueException;
363:
364: List getUserPermissions(IssueType issueType) throws TorqueException;
365:
366: RModuleIssueType getRModuleIssueType(IssueType issueType)
367: throws TorqueException;
368:
369: void addIssueType(IssueType issueType) throws TorqueException,
370: ValidationException, DataSetException, ScarabException;
371:
372: void addAttributeOption(IssueType issueType, AttributeOption option)
373: throws TorqueException, ScarabException;
374:
375: /**
376: * Adds module-attribute mapping to module.
377: */
378: RModuleAttribute addRModuleAttribute(IssueType issueType,
379: Attribute attribute) throws TorqueException,
380: ScarabException;
381:
382: /**
383: * Adds module-attribute-option mapping to module.
384: */
385: RModuleOption addRModuleOption(IssueType issueType,
386: AttributeOption option) throws TorqueException;
387:
388: List getIssueTypes() throws TorqueException;
389:
390: List getIssueTypes(boolean activeOnly) throws TorqueException;
391:
392: List getTemplateTypes() throws TorqueException, ScarabException;
393:
394: List getNavIssueTypes() throws TorqueException;
395:
396: /**
397: * Determines whether this module allows users to vote many times for
398: * the same issue. This feature needs schema change to allow a
399: * configuration screen. Currently only one vote per issue is supported
400: *
401: * @return false
402: */
403: boolean allowsMultipleVoting();
404:
405: /**
406: * How many votes does the user have left to cast. Currently always
407: * returns 1, so a user has unlimited voting rights. Should look to
408: * UserVote for the answer when implemented properly.
409: */
410: int getUnusedVoteCount(ScarabUser user);
411:
412: /**
413: * Returns list of queries needing approval.
414: */
415: List getUnapprovedQueries() throws TorqueException;
416:
417: /**
418: * Returns list of enter issue templates needing approval.
419: */
420: List getUnapprovedTemplates() throws TorqueException;
421:
422: /**
423: * Gets a list of active RModuleOptions which have had their level
424: * within the options for this module set.
425: *
426: * @param attribute an <code>Attribute</code> value
427: * @return a <code>List</code> value
428: * @exception Exception if an error occurs
429: */
430: List getOptionTree(Attribute attribute, IssueType issueType)
431: throws TorqueException;
432:
433: /**
434: * Gets a list of RModuleOptions which have had their level
435: * within the options for this module set.
436: *
437: * @param attribute an <code>Attribute</code> value
438: * @param activeOnly a <code>boolean</code> value
439: * @return a <code>List</code> value
440: * @exception Exception if an error occurs
441: */
442: List getOptionTree(Attribute attribute, IssueType issueType,
443: boolean activeOnly) throws TorqueException;
444:
445: /**
446: * All emails related to this module will have a copy sent to
447: * this address.
448: */
449: String getArchiveEmail();
450:
451: /**
452: * The default address that is used to fill out either the From or
453: * ReplyTo header on emails related to this module. In many cases
454: * the From field is taken as the user who acted that resulted in the
455: * email, but replies should still go to the central location for
456: * the module, so in this address would be used in the ReplyTo field.
457: *
458: * @return a <code>String[]</code> of length=2 where the first element
459: * is a name such as "Scarab System" and the second is an email address.
460: */
461: String[] getSystemEmail();
462:
463: /**
464: * Determines wether a 'reason' is required for every change in the issues
465: * of this module. This can be both because of the module configuration and
466: * the configuration of the first module up the hierarchy that set this
467: * option up.
468: * @return
469: */
470: boolean isIssueReasonRequired();
471:
472: /**
473: * Determines if the value of isIssueReasonRequired is due to the configuration
474: * of this module or inherited from ancestors or default configuration.
475: * @return True if the configuration is inherited.
476: */
477: boolean isIssueReasonRequiredInherited();
478:
479: /**
480: * Returns the required role for *any* access to this module
481: * including for requesting roles.
482: * @return
483: */
484: public Role getRequiredRole();
485:
486: /**
487: * Determines whether this module is accepting new issues.
488: */
489: boolean allowsNewIssues();
490:
491: /**
492: * Retruns the currently used rendering engine for comments
493: */
494: String getCommentRenderingEngine();
495:
496: /**
497: * Determines whether this module accepts issues.
498: */
499: boolean allowsIssues();
500:
501: /**
502: * Returns true if no issue types are associated with this module, or if the module
503: * is currently getting its initial values set.
504: */
505: boolean isInitializing() throws TorqueException;
506:
507: /**
508: * Returns true if this module is the the top level parent module.
509: *
510: * @return a <code>boolean</code> value
511: */
512: boolean isGlobalModule();
513:
514: /**
515: * returns a compiled regex that can used to create a new RE
516: * for matching some given text.
517: */
518: REProgram getIssueRegex() throws TorqueException;
519:
520: /**
521: * This method is useful for getting an issue object
522: * by a String id. It has some logic in it for appending
523: * the Module Code as well as stripping spaces off the
524: * id value using the String.trim() method.
525: * @deprecated use IssueManager.getIssueById(String id, String defaultCode)
526: * I think this method should only return issues from this module,
527: * but there is only one place in the code where something like that
528: * was needed and the check is done there. Its possible we would want
529: * to define this method to return issues in children or some other
530: * criteria. deprecating for removal until a definite reason for it to
531: * exist appears.
532: */
533: Issue getIssueById(String id) throws TorqueException;
534:
535: String toString();
536:
537: List getRoles() throws TorqueException;
538:
539: /**
540: * The default locale for this module will be used in cases
541: * where a response is going to no particular user (a mailing
542: * list) or can also be used as a default in cases where
543: * a user does not have a preference.
544: *
545: * @return a <code>Locale</code> value
546: */
547: Locale getLocale();
548: }
|