org.netbeans.modules.bugtracking.spi

Interface IssueStatusProvider<R,I>

Type Parameters:

R - the implementation specific repository type

I - the implementation specific issue type

public interface IssueStatusProvider<R,I>

Provides information and functionality related to incoming and outgoing issue changes. Issue Status information is used by the Tasks Dashboard to e.g.:

• appropriately render Issue Status annotations (e.g. by coloring)
• list Issues with outgoing changes in a Tasks Dashboard category, submit or discard them, etc.

An implementation of this interface is not mandatory for a NetBeans bugtracking plugin. The IssueStatusProvider.Status.SEEN status is default for all issues in such a case. Implement only in cases you want to reflect incoming or outgoing changes.

Also note that it is not to mandatory to honor all status values in a particular implementation - e.g. it is ok for a plugin to handle only the INCOMING_NEW, INCOMING_MODIFIED and SEEN values. In case that also outgoing changes are reflected then also CONFLICT should be taken in count.

Incoming changes:
Represented by the status values INCOMING_NEW or INCOMING_MODIFIED. In case the implementation keeps track of changes the user haven't seen yet (e.g. by opening the Issue UI) then it is also expected to provide the relevant incoming status values.

Outgoing changes:
Represented by the status values OUTGOING_NEW or OUTGOING_MODIFIED. Typically each particular issue editor UI is expected to provide a way to change an issue and to submit those changes. In case the implementation keeps track of changes made locally between more editing sessions, then it is also expected to provide the relevant outgoing status values and implement the relevant methods in this interface - e.g. getUnsubmittedIssue(I i), discardOutgoing(I i), submit(i I).

Even though the status value is entirely given by the particular implementation, the precedence of Status values is expected to be the following:

precedence of Status

Issue state	Expected Status
no changes	SEEN
only incoming changes	INCOMING_NEW or INCOMING_MODIFIED
only outgoing changes	OUTGOING_NEW or OUTGOING_MODIFIED
incoming and outgoing changes	CONFLICT

Since:

1.85

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	IssueStatusProvider.Status Determines an Issue status.

Field Summary

Fields

Modifier and Type	Field and Description
static String	EVENT_STATUS_CHANGED Issue status has changed.

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(I i, PropertyChangeListener listener) Unregisters a PropertyChangeListener.
void	discardOutgoing(I i) Discard outgoing local changes from the given issue.
IssueStatusProvider.Status	getStatus(I i) Get the Issue Status.
Collection<I>	getUnsubmittedIssues(R r) Returns unsubmitted issues from the given repository.
void	removePropertyChangeListener(I i, PropertyChangeListener listener) Registers a PropertyChangeListener to notify about status changes for an issue.
void	setSeenIncoming(I i, boolean seen) Sets the information if the user has seen the incoming changes or wishes to mark them as seen (so that they aren't annotated anymore). Called e.g.
boolean	submit(I i) Submits outgoing local changes.

Field Detail

EVENT_STATUS_CHANGED

static final String EVENT_STATUS_CHANGED

Issue status has changed. Fire this to notify e.g. Issue nodes in Tasks Dashboard where the status is rendered.

Old value should be the status before the change, new value the Status after the change.

Since:

1.85

See Also:

Constant Field Values

Method Detail

getStatus

IssueStatusProvider.Status getStatus(I i)

Get the Issue Status.

Parameters:

i - an implementation specific Issue instance

Returns:

teh status

Since:

1.85

setSeenIncoming

void setSeenIncoming(I i,
                     boolean seen)

Sets the information if the user has seen the incoming changes or wishes to mark them as seen (so that they aren't annotated anymore).
Called e.g. by the 'Mark as Seen/Unseen' action in the Tasks Dashboard or when an Issue was opened by the user.

The expected result of setting seen to true:

expected result

Status before	Status after
SEEN	SEEN
INCOMING_NEW or INCOMING_MODIFIED	SEEN
OUTGOING_NEW or OUTGOING_MODIFIED	no effect
CONFLICT	OUTGOING_NEW or OUTGOING_MODIFIED

It is up the particular implementation if and for how long the information about incoming changes will be preserved so that it can be restored after setting seen back to false. E.g. resulting to a status change from SEEN to INCOMMING_XXX or from OUTGOING_XXX to CONFLICT. Please note that doing so at least for a running IDE session would be considered as polite to the user.

Note that in case the implementation provides either IssueStatusProvider.Status.INCOMING_NEW or IssueStatusProvider.Status.INCOMING_MODIFIED status values, this method may be called to either reset those values to IssueStatusProvider.Status.SEEN or set to set back the previous INCOMING_XXX status value.

Parameters:

i - an implementation specific Issue instance

seen - true if the Issue was seen or set as seen by the user

Since:

1.85

getUnsubmittedIssues

Collection<I> getUnsubmittedIssues(R r)

Returns unsubmitted issues from the given repository. Implement in case the implementation supports also outgoing changes mode.

Note that this method is going to be called only for issue with IssueStatusProvider.Status being either IssueStatusProvider.Status.OUTGOING_NEW or IssueStatusProvider.Status.OUTGOING_MODIFIED.

Parameters:

r - an implementation specific Repository instance

Returns:

collection of unsubmitted issues

Since:

1.85

discardOutgoing

void discardOutgoing(I i)

Discard outgoing local changes from the given issue. Implement in case the implementation supports also outgoing changes mode.

Note that this method is going to be called only for issue with IssueStatusProvider.Status being either IssueStatusProvider.Status.OUTGOING_NEW or IssueStatusProvider.Status.OUTGOING_MODIFIED.

Parameters:

i - an implementation specific Issue instance

Since:

1.85

submit

boolean submit(I i)

Submits outgoing local changes. Implement in case the implementation supports also outgoing changes mode.

In case an error appears during execution, the implementation should take care of the error handling, user notification etc.

Note that this method is going to be called only for issue with IssueStatusProvider.Status being either IssueStatusProvider.Status.OUTGOING_NEW or IssueStatusProvider.Status.OUTGOING_MODIFIED.

Parameters:

i - an implementation specific Issue instance

Returns:

true if the task was successfully submitted,false if the task was not submitted for any reason.

Since:

1.85

removePropertyChangeListener

void removePropertyChangeListener(I i,
                                  PropertyChangeListener listener)

Registers a PropertyChangeListener to notify about status changes for an issue.

Parameters:

i - an implementation specific Issue instance

listener - a PropertyChangeListener

Since:

1.85

addPropertyChangeListener

void addPropertyChangeListener(I i,
                               PropertyChangeListener listener)

Unregisters a PropertyChangeListener.

Parameters:

i - an implementation specific Issue instance

listener - a PropertyChangeListener

Since:

1.85