jetbrains.buildServer.issueTracker
Interface IssueProvider

All Known Subinterfaces:

SIssueProvider

All Known Implementing Classes:

AbstractIssueProvider

public interface IssueProvider

Represents the provider of issues from the issues-tracking system (ITS). This interface is intended to be implemented by TeamCity plugins (Jira, Charisma, Bugzilla, etc).

In general the plugin implementing this interface is responsible to:

• parse the issue ids mentioned in the comment, description, etc of an entity provided by server (e.g. VCS modification);
• fetch (and possibly cache) the corresponsing issue data from the ITS, and return it.

The server does not expect (unless stated otherwise) that the plugin will modify the data in the ITS based on provided VCS modifications, comments, etc. Particularly the plugin should not fix the bug by "TW-1234 fix" comment.

Issue provider can have any properties, but some of them can be recognized by server and treated specially:

• name - provider name. This name will be shown in UI as a tooltip for various links, and also will designate each provider in admin page;
• host - provider host URL. This URL can be displayed as a tooltip for provider-related links;
• secure: - secure prefix. The properties with this prefix are scrambled when persisted on disk.

Issue provider should be thread-safe (see setProperties(java.util.Map) method).

Since:

5.0

Author:

Maxim Podkolzine (maxim.podkolzine@jetbrains.com)

See Also:

IssueProviderFactory

Field Summary

static java.lang.String

SECURE_PROPERTY_PREFIX This prefix means that the property is secure, and should be scrambled upon save.

Method Summary

void	dispose() Disposes the provider (releases all necessary resources, dumps caches on disk, etc).
IssueData	findIssueById(java.lang.String id) Returns the issue by the specified id.
CommentTransformationHelper	getCommentTransformationHelper() Returns the instance of helper class to support comment transformation (i.e.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Returns the map of provider properties.
java.util.Collection<IssueMention>	getRelatedIssues(java.lang.String comment) Returns the collection of issues related, or mentioned in the comment.
java.util.Collection<IssueMention>	getRelatedIssues(VcsModification modification) Returns the collection of issues related to a modification.
java.lang.String	getType() Returns the type of this provider (the type of the corresponding factory).
boolean	isHasRelatedIssues(java.lang.String comment) Returns whether there are related issues in the specified comment.
boolean	isHasRelatedIssues(VcsModification modification) Returns whether there are related issues in the specified modification.
void	setProperties(java.util.Map<java.lang.String,java.lang.String> map) Sets the provider properties (see getProperties() method for the details).

Field Detail

SECURE_PROPERTY_PREFIX

@NonNls
static final java.lang.String SECURE_PROPERTY_PREFIX

This prefix means that the property is secure, and should be scrambled upon save.

See Also:

Constant Field Values

Method Detail

getType

@NotNull
java.lang.String getType()

Returns the type of this provider (the type of the corresponding factory). The type is immutable and consists of alpha-numeric characters.

Returns:

provider type

getRelatedIssues

@NotNull
java.util.Collection<IssueMention> getRelatedIssues(@NotNull
                                                            java.lang.String comment)

Returns the collection of issues related, or mentioned in the comment. The relation can be defined by a mention in the text (a mention means that comment contains the substring that matches a certain pattern), or by any way the plugin chooses.

Parameters:

comment - the comment

Returns:

collection of related issues

See Also:

isHasRelatedIssues(String)

isHasRelatedIssues

boolean isHasRelatedIssues(@NotNull
                           java.lang.String comment)

Returns whether there are related issues in the specified comment. The relation can be defined by a mention in the text (a mention means that comment contains the substring that matches a certain pattern), or by any way the plugin chooses.

Parameters:

comment - the comment

Returns:

true if the comment has related issues

Since:

7.0

See Also:

getRelatedIssues(String)

getRelatedIssues

@NotNull
java.util.Collection<IssueMention> getRelatedIssues(@NotNull
                                                            VcsModification modification)

Returns the collection of issues related to a modification. In most cases the relation is defined via mentioning the issue id in the modification comment, but could also be some extra field in VCS commit.

Parameters:

modification - VCS modification

Returns:

collection of related issues

Since:

6.0

See Also:

isHasRelatedIssues(jetbrains.buildServer.vcs.VcsModification)

isHasRelatedIssues

boolean isHasRelatedIssues(@NotNull
                           VcsModification modification)

Returns whether there are related issues in the specified modification. In most cases the relation is defined via mentioning the issue id in the modification comment, but could also be some extra field in VCS commit.

Parameters:

provider - issue provider

modification - a VCS modification

Returns:

true if the modification has related issues

Since:

7.0

See Also:

getRelatedIssues(jetbrains.buildServer.vcs.VcsModification)

findIssueById

@Nullable
IssueData findIssueById(@NotNull
                                 java.lang.String id)

Returns the issue by the specified id. Returned data isn't expected to be up-to-date, i.e. fetched from the ITS at the moment of call.

The implementors are encouraged to report retrieving errors by throwing RetrieveIssueException, rather than simply return null: NotFoundException when the issue cannot be found, UnsupportedException when the issue tracker protocol is not supported, etc.

Parameters:

id - issue id

Returns:

the corresponding issue, or null if the issue cannot be retrieved

getProperties

@NotNull
java.util.Map<java.lang.String,java.lang.String> getProperties()

Returns the map of provider properties. This map includes all fields that are configured in admin UI and stored in TeamCity config file (e.g. credentials used in all communications with remote server, server url, etc, but not the id or type).

The keys should consist of alphanumeric characters and start with a letter.

Returns:

the properties map

setProperties

void setProperties(@NotNull
                   java.util.Map<java.lang.String,java.lang.String> map)

Sets the provider properties (see getProperties() method for the details).

Few words about thread-safety: properties can be changed from the admin UI, or in config file. By any of these events this method is called (synchronously). Hence this method should lock any other API method.

Parameters:

map - a properties map

See Also:

getProperties()

dispose

void dispose()

Disposes the provider (releases all necessary resources, dumps caches on disk, etc). This method is called when the provider is deleted from the system, and on server shutdown.

getCommentTransformationHelper

@Nullable
CommentTransformationHelper getCommentTransformationHelper()

Returns the instance of helper class to support comment transformation (i.e. automatic replacement of issues, mentioned in a comment, with a link and a popup).

Returns:

a helper, or null