001: /*
002: * @(#)AbstractIssue.java
003: *
004: * Copyright (C) 2002-2003 Matt Albrecht
005: * groboclown@users.sourceforge.net
006: * http://groboutils.sourceforge.net
007: *
008: * Part of the GroboUtils package at:
009: * http://groboutils.sourceforge.net
010: *
011: * Permission is hereby granted, free of charge, to any person obtaining a
012: * copy of this software and associated documentation files (the "Software"),
013: * to deal in the Software without restriction, including without limitation
014: * the rights to use, copy, modify, merge, publish, distribute, sublicense,
015: * and/or sell copies of the Software, and to permit persons to whom the
016: * Software is furnished to do so, subject to the following conditions:
017: *
018: * The above copyright notice and this permission notice shall be included in
019: * all copies or substantial portions of the Software.
020: *
021: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
022: * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
023: * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
024: * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
025: * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
026: * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
027: * DEALINGS IN THE SOFTWARE.
028: */
029: package net.sourceforge.groboutils.pmti.v1.defimpl;
030:
031: import net.sourceforge.groboutils.pmti.v1.IIssue;
032: import net.sourceforge.groboutils.pmti.v1.IAttributeSet;
033: import net.sourceforge.groboutils.pmti.v1.IIssueState;
034: import net.sourceforge.groboutils.pmti.v1.ProblemManagerException;
035:
036: /**
037: * Reflects an issue (or bug, or anomally report, or problem ticket) that
038: * is generic enough to be used by most problem tracker system. All
039: * <tt>IIssue</tt> instances are immutable, unless they also implement
040: * <tt>IEditableIssue</tt>.
041: * <P>
042: * An issue will only reflect the data associated with the issue at the time of
043: * the polling of the issue from the tracker. Currently, the only way to
044: * update the issue's data fields is to re-poll the issue from the
045: * <tt>ProblemManager</tt>, or to call <tt>reload()</tt>. Individual
046: * implemenations of the PMTI framework
047: * may provide alternative means to real-time update the issue data, but that
048: * is not the standard implementation.
049: * <P>
050: * Containment patterns would require the creation methods for an editable form
051: * of the issue to be in this interface. For security reasons, this method
052: * is placed in the <tt>ProblemManager</tt> interface instead.
053: * <P>
054: * NOTE: this interface may be too generic to be useful.
055: *
056: * @author Matt Albrecht <a href="mailto:groboclown@users.sourceforge.net">groboclown@users.sourceforge.net</a>
057: * @version $Date: 2003/02/10 22:51:57 $
058: * @since July 12, 2002
059: */
060: public abstract class AbstractIssue implements IIssue {
061: private String id;
062: private String type;
063: private String desc;
064: private IIssueState state;
065: private IAttributeSet attribs;
066:
067: public AbstractIssue(String i, String t, String d, IIssueState s,
068: IAttributeSet a) {
069: if (i == null || s == null) {
070: throw new IllegalArgumentException("no null arguments");
071: }
072: this .id = i;
073: this .type = t;
074: this .desc = d;
075: this .state = s;
076: this .attribs = a;
077: }
078:
079: /**
080: * Returns the unique ID associated with this issue.
081: *
082: * @return the problem tracker's assigned ID for this issue.
083: */
084: public String getID() {
085: return this .id;
086: }
087:
088: /**
089: * Returns the type of issue. For the SourceForge.net site, this may
090: * be "bug", "feature request", and so forth. Some trackers may only
091: * have one type of issue, so this field may not be as useful. For
092: * those trackers that have different attribute data sets for different
093: * types, this may aid programs in decoding the attributes and states.
094: * <P>
095: * NOTE: this field may be deprecated in the future in favor of specific
096: * IAttributeSet types.
097: *
098: * @see #getAttributes()
099: */
100: public String getType() {
101: return this .type;
102: }
103:
104: /**
105: * Retrieves the short description of the issue. This can also be
106: * referred to as the issue title or summary. It should be a
107: * human-readable short description, describing a general overview
108: * of the issue.
109: *
110: * @return the issue's short description.
111: */
112: public String getShortDescription() {
113: return this .desc;
114: }
115:
116: /**
117: * Queries the "state" of the issue. In a very general way, this refers
118: * to various progress states an issue can be in, such as "new", "assigned",
119: * "investigating", "resolved", "verified", "closed", and so on. Additional
120: * data may be associated with this state, such as who's working on the
121: * issue, the resolution of the issue, who verified the resolution, and
122: * so on. If the tracker does not support a state, then <tt>null</tt>
123: * may be returned.
124: * <P>
125: * Some trackers may have different state categories for different
126: * issue types.
127: *
128: * @return the issue's state, which may be <tt>null</tt>.
129: */
130: public IIssueState getState() {
131: return this .state;
132: }
133:
134: /**
135: * Returns a list of all attributes associated with this issue. All
136: * issues of a particular type should have the same set of issues.
137: *
138: * @return the set of tracker-specific and issue type-specific attributes
139: * and values associated with this issue. Can never return
140: * <tt>null</tt>.
141: */
142: public IAttributeSet getAttributes() {
143: return this .attribs;
144: }
145:
146: /**
147: * Reloads all the data in this issue so that it reflects the most current
148: * tracker data possible. If this is called on an editable issue, then
149: * all changes will be forgotten, and the issue will reflect the current
150: * tracker state.
151: * <P>
152: * In theory, issues should never be removed. However, some systems allow
153: * them to be deleted (say, if there was an accidental creation). In this
154: * case, an <tt>IssueRemovedException</tt> will be thrown.
155: *
156: * @exception ProblemManagerException if there was an underlying tracker
157: * error.
158: */
159: public abstract IIssue reload() throws ProblemManagerException;
160: }
|