001: /*
002: * @(#)IIssue.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;
030:
031: /**
032: * Reflects an issue (or bug, or anomally report, or problem ticket) that
033: * is generic enough to be used by most problem tracker system. All
034: * <tt>IIssue</tt> instances are immutable, unless they also implement
035: * <tt>IEditableIssue</tt>.
036: * <P>
037: * An issue will only reflect the data associated with the issue at the time of
038: * the polling of the issue from the tracker. Currently, the only way to
039: * update the issue's data fields is to re-poll the issue from the
040: * <tt>ProblemManager</tt>, or to call <tt>reload()</tt>. Individual
041: * implemenations of the PMTI framework
042: * may provide alternative means to real-time update the issue data, but that
043: * is not the standard implementation.
044: * <P>
045: * Containment patterns would require the creation methods for an editable form
046: * of the issue to be in this interface. For security reasons, this method
047: * is placed in the <tt>ProblemManager</tt> interface instead.
048: * <P>
049: * NOTE: this interface may be too generic to be useful.
050: *
051: * @author Matt Albrecht <a href="mailto:groboclown@users.sourceforge.net">groboclown@users.sourceforge.net</a>
052: * @version $Date: 2003/02/10 22:51:54 $
053: * @since July 6, 2002
054: */
055: public interface IIssue {
056: /**
057: * Returns the unique ID associated with this issue.
058: *
059: * @return the problem tracker's assigned ID for this issue, which can
060: * never be <tt>null</tt>.
061: */
062: public String getID();
063:
064: /**
065: * Returns the type of issue. For the SourceForge.net site, this may
066: * be "bug", "feature request", and so forth. Some trackers may only
067: * have one type of issue, so this field may not be as useful. For
068: * those trackers that have different attribute data sets for different
069: * types, this may aid programs in decoding the attributes and states.
070: * <P>
071: * NOTE: this field may be deprecated in the future in favor of specific
072: * IAttributeSet types.
073: *
074: * @return the issue's type, which may be <tt>null</tt>.
075: * @see #getAttributes()
076: */
077: public String getType();
078:
079: /**
080: * Retrieves the short description of the issue. This can also be
081: * referred to as the issue title or summary. It should be a
082: * human-readable short description, describing a general overview
083: * of the issue.
084: *
085: * @return the issue's short description, which may be <tt>null</tt>.
086: */
087: public String getShortDescription();
088:
089: /**
090: * Queries the "state" of the issue. In a very general way, this refers
091: * to various progress states an issue can be in, such as "new", "assigned",
092: * "investigating", "resolved", "verified", "closed", and so on. Additional
093: * data may be associated with this state, such as who's working on the
094: * issue, the resolution of the issue, who verified the resolution, and
095: * so on. If the tracker does not support a state, then <tt>null</tt>
096: * may be returned.
097: * <P>
098: * Some trackers may have different state categories for different
099: * issue types.
100: *
101: * @return the issue's state, which may be <tt>null</tt>.
102: */
103: public IIssueState getState();
104:
105: /**
106: * Returns a list of all attributes associated with this issue. All
107: * issues of a particular type should have the same set of issues.
108: *
109: * @return the set of tracker-specific and issue type-specific attributes
110: * and values associated with this issue. Can never return
111: * <tt>null</tt>.
112: */
113: public IAttributeSet getAttributes();
114:
115: /**
116: * Returns a new issue instance, containing the most up-to-date tracker
117: * information for this issue. Since the <tt>IIssue</tt> instances are
118: * immutable, this will not change the invoked issue. If the current
119: * instance is of type <tt>IEditableIssue</tt>, then an
120: * <tt>IEditableIssue</tt> will be returned, but will contain none of the
121: * non-committed changes performed on the owning issue.
122: * <P>
123: * In theory, issues should never be removed. However, some systems allow
124: * them to be deleted (say, if there was an accidental creation). In this
125: * case, an <tt>IssueRemovedException</tt> will be thrown.
126: *
127: * @return an IIssue with the
128: * @exception ProblemManagerException if there was an underlying tracker
129: * error.
130: */
131: public IIssue reload() throws ProblemManagerException;
132: }
|