KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > sourceforge > groboutils > pmti > v1 > IIssue


1 /*
2  * @(#)IIssue.java
3  *
4  * Copyright (C) 2002-2003 Matt Albrecht
5  * groboclown@users.sourceforge.net
6  * http://groboutils.sourceforge.net
7  *
8  * Part of the GroboUtils package at:
9  * http://groboutils.sourceforge.net
10  *
11  * Permission is hereby granted, free of charge, to any person obtaining a
12  * copy of this software and associated documentation files (the "Software"),
13  * to deal in the Software without restriction, including without limitation
14  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
15  * and/or sell copies of the Software, and to permit persons to whom the
16  * Software is furnished to do so, subject to the following conditions:
17  *
18  * The above copyright notice and this permission notice shall be included in
19  * all copies or substantial portions of the Software.
20  *
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
24  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27  * DEALINGS IN THE SOFTWARE.
28  */
29 package net.sourceforge.groboutils.pmti.v1;
30
31  
32
33 /**
34  * Reflects an issue (or bug, or anomally report, or problem ticket) that
35  * is generic enough to be used by most problem tracker system. All
36  * <tt>IIssue</tt> instances are immutable, unless they also implement
37  * <tt>IEditableIssue</tt>.
38  * <P>
39  * An issue will only reflect the data associated with the issue at the time of
40  * the polling of the issue from the tracker. Currently, the only way to
41  * update the issue's data fields is to re-poll the issue from the
42  * <tt>ProblemManager</tt>, or to call <tt>reload()</tt>. Individual
43  * implemenations of the PMTI framework
44  * may provide alternative means to real-time update the issue data, but that
45  * is not the standard implementation.
46  * <P>
47  * Containment patterns would require the creation methods for an editable form
48  * of the issue to be in this interface. For security reasons, this method
49  * is placed in the <tt>ProblemManager</tt> interface instead.
50  * <P>
51  * NOTE: this interface may be too generic to be useful.
52  *
53  * @author Matt Albrecht <a HREF="mailto:groboclown@users.sourceforge.net">groboclown@users.sourceforge.net</a>
54  * @version $Date: 2003/02/10 22:51:54 $
55  * @since July 6, 2002
56  */
57 public interface IIssue
58 {
59     /**
60      * Returns the unique ID associated with this issue.
61      *
62      * @return the problem tracker's assigned ID for this issue, which can
63      * never be <tt>null</tt>.
64      */
65     public String JavaDoc getID();
66     
67     
68     /**
69      * Returns the type of issue. For the SourceForge.net site, this may
70      * be "bug", "feature request", and so forth. Some trackers may only
71      * have one type of issue, so this field may not be as useful. For
72      * those trackers that have different attribute data sets for different
73      * types, this may aid programs in decoding the attributes and states.
74      * <P>
75      * NOTE: this field may be deprecated in the future in favor of specific
76      * IAttributeSet types.
77      *
78      * @return the issue's type, which may be <tt>null</tt>.
79      * @see #getAttributes()
80      */
81     public String JavaDoc getType();
82     
83     
84     /**
85      * Retrieves the short description of the issue. This can also be
86      * referred to as the issue title or summary. It should be a
87      * human-readable short description, describing a general overview
88      * of the issue.
89      *
90      * @return the issue's short description, which may be <tt>null</tt>.
91      */
92     public String JavaDoc getShortDescription();
93     
94     
95     /**
96      * Queries the "state" of the issue. In a very general way, this refers
97      * to various progress states an issue can be in, such as "new", "assigned",
98      * "investigating", "resolved", "verified", "closed", and so on. Additional
99      * data may be associated with this state, such as who's working on the
100      * issue, the resolution of the issue, who verified the resolution, and
101      * so on. If the tracker does not support a state, then <tt>null</tt>
102      * may be returned.
103      * <P>
104      * Some trackers may have different state categories for different
105      * issue types.
106      *
107      * @return the issue's state, which may be <tt>null</tt>.
108      */
109     public IIssueState getState();
110     
111     
112     /**
113      * Returns a list of all attributes associated with this issue. All
114      * issues of a particular type should have the same set of issues.
115      *
116      * @return the set of tracker-specific and issue type-specific attributes
117      * and values associated with this issue. Can never return
118      * <tt>null</tt>.
119      */
120     public IAttributeSet getAttributes();
121     
122     
123     /**
124      * Returns a new issue instance, containing the most up-to-date tracker
125      * information for this issue. Since the <tt>IIssue</tt> instances are
126      * immutable, this will not change the invoked issue. If the current
127      * instance is of type <tt>IEditableIssue</tt>, then an
128      * <tt>IEditableIssue</tt> will be returned, but will contain none of the
129      * non-committed changes performed on the owning issue.
130      * <P>
131      * In theory, issues should never be removed. However, some systems allow
132      * them to be deleted (say, if there was an accidental creation). In this
133      * case, an <tt>IssueRemovedException</tt> will be thrown.
134      *
135      * @return an IIssue with the
136      * @exception ProblemManagerException if there was an underlying tracker
137      * error.
138      */
139     public IIssue reload()
140             throws ProblemManagerException;
141 }
142
143
Popular Tags