KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)IEditableIssue.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  * Allows for editing of an issue. The only parts that can't be edited are
35  * the ID and type, since those uniquely identify the issue at hand. Editing
36  * an issue has several constraints that should be known by the user:
37  * <UL>
38  * <LI>
39  * Just like with the <tt>IIssue</tt> instances, the issue being
40  * edited will NOT be real-time updated to reflect the current
41  * tracker state. Currently, the only way to update an issue is by
42  * re-polling the <tt>ProblemManager</tt>. Individual implementations
43  * may provide for alternative means to receive synchronized issues.
44  * </LI>
45  * <LI>
46  * No changes to an editable issue will be committed to the problem
47  * tracker is to call <tt>commit()</tt> on the issue.
48  * </LI>
49  * </UL>
50  *
51  * @author Matt Albrecht <a HREF="mailto:groboclown@users.sourceforge.net">groboclown@users.sourceforge.net</a>
52  * @version $Date: 2003/02/10 22:51:54 $
53  * @since July 6, 2002
54  */
55 public interface IEditableIssue extends IIssue
56 {
57     
58     
59     /**
60      *
61      */
62     public void setShortDescription( String JavaDoc desc );
63     
64     
65     /**
66      * @return <tt>true</tt> if <tt>setShortDescription( String )</tt> was
67      * called with a different description string than the original
68      * issue, otherwise <tt>false</tt>.
69      */
70     public boolean hasShortDescriptionChanged();
71     
72     
73     /**
74      * Returns the list of all states that this issue can move to next.
75      * This is part of the workflow logic of the underlying PMT. The returned
76      * states may be safely edited without any affect; the only effect will be
77      * when the state is explicitly set. This will always return, in index 0,
78      * a <b>copy</b> of the current state as editable.
79      */
80     public IEditableIssueState[] getNextStates();
81     
82     
83     /**
84      * Sets the current state. Since there is no getEditableState() method,
85      * use this method if any information in the current state needs to be
86      * updated. You can retrieve the current state as an editable state
87      * using <tt>getNextStates()[0]</tt>, but note that any changes to that
88      * editable version will not affect the tracker's state unless that
89      * editable instance is explicitly set in this method.
90      *
91      * @exception ProblemManagerException if the input state is not a valid
92      * next state.
93      */
94     public void setState( IIssueState state )
95             throws ProblemManagerException;
96     
97     
98     /**
99      * @return <tt>true</tt> if the <tt>setState( IIssueState )</tt> method
100      * has been invoked and did not throw an exception, otherwise
101      * <tt>false</tt>. Note that even if the set state is an unchanged
102      * version of the current issue's state, this will still return
103      * <tt>true</tt>.
104      */
105     public boolean hasStateChanged();
106     
107     
108     /**
109      * This is a synonymn for <tt>getAttributes()</tt>, but this explicitly
110      * sets the returned value as an editable set, without the need for an
111      * extra cast. The returned attribute set may be safely edited, and
112      * changes there will affect the issue that returned them.
113      */
114     public IEditableAttributeSet getEditableAttributes();
115     
116     
117     /**
118      * Commits all changes from the issue to the tracker.
119      * <P>
120      * In theory, issues should never be removed. However, some systems allow
121      * them to be deleted (say, if there was an accidental creation). In this
122      * case, an <tt>IssueRemovedException</tt> will be thrown.
123      *
124      * @exception ProblemManagerException if there was an underlying tracker
125      * error.
126      */
127     public void commit()
128             throws ProblemManagerException;
129 }
130
131
Popular Tags