001: /*
002: * @(#)IEditableIssue.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: * Allows for editing of an issue. The only parts that can't be edited are
033: * the ID and type, since those uniquely identify the issue at hand. Editing
034: * an issue has several constraints that should be known by the user:
035: * <UL>
036: * <LI>
037: * Just like with the <tt>IIssue</tt> instances, the issue being
038: * edited will NOT be real-time updated to reflect the current
039: * tracker state. Currently, the only way to update an issue is by
040: * re-polling the <tt>ProblemManager</tt>. Individual implementations
041: * may provide for alternative means to receive synchronized issues.
042: * </LI>
043: * <LI>
044: * No changes to an editable issue will be committed to the problem
045: * tracker is to call <tt>commit()</tt> on the issue.
046: * </LI>
047: * </UL>
048: *
049: * @author Matt Albrecht <a href="mailto:groboclown@users.sourceforge.net">groboclown@users.sourceforge.net</a>
050: * @version $Date: 2003/02/10 22:51:54 $
051: * @since July 6, 2002
052: */
053: public interface IEditableIssue extends IIssue {
054:
055: /**
056: *
057: */
058: public void setShortDescription(String desc);
059:
060: /**
061: * @return <tt>true</tt> if <tt>setShortDescription( String )</tt> was
062: * called with a different description string than the original
063: * issue, otherwise <tt>false</tt>.
064: */
065: public boolean hasShortDescriptionChanged();
066:
067: /**
068: * Returns the list of all states that this issue can move to next.
069: * This is part of the workflow logic of the underlying PMT. The returned
070: * states may be safely edited without any affect; the only effect will be
071: * when the state is explicitly set. This will always return, in index 0,
072: * a <b>copy</b> of the current state as editable.
073: */
074: public IEditableIssueState[] getNextStates();
075:
076: /**
077: * Sets the current state. Since there is no getEditableState() method,
078: * use this method if any information in the current state needs to be
079: * updated. You can retrieve the current state as an editable state
080: * using <tt>getNextStates()[0]</tt>, but note that any changes to that
081: * editable version will not affect the tracker's state unless that
082: * editable instance is explicitly set in this method.
083: *
084: * @exception ProblemManagerException if the input state is not a valid
085: * next state.
086: */
087: public void setState(IIssueState state)
088: throws ProblemManagerException;
089:
090: /**
091: * @return <tt>true</tt> if the <tt>setState( IIssueState )</tt> method
092: * has been invoked and did not throw an exception, otherwise
093: * <tt>false</tt>. Note that even if the set state is an unchanged
094: * version of the current issue's state, this will still return
095: * <tt>true</tt>.
096: */
097: public boolean hasStateChanged();
098:
099: /**
100: * This is a synonymn for <tt>getAttributes()</tt>, but this explicitly
101: * sets the returned value as an editable set, without the need for an
102: * extra cast. The returned attribute set may be safely edited, and
103: * changes there will affect the issue that returned them.
104: */
105: public IEditableAttributeSet getEditableAttributes();
106:
107: /**
108: * Commits all changes from the issue to the tracker.
109: * <P>
110: * In theory, issues should never be removed. However, some systems allow
111: * them to be deleted (say, if there was an accidental creation). In this
112: * case, an <tt>IssueRemovedException</tt> will be thrown.
113: *
114: * @exception ProblemManagerException if there was an underlying tracker
115: * error.
116: */
117: public void commit() throws ProblemManagerException;
118: }
|