jetbrains.buildServer.issueTracker
Interface IssueProvider

All Known Subinterfaces:
SIssueProvider
All Known Implementing Classes:
AbstractIssueProvider, AbstractPrefixBasedIssueProvider

public interface IssueProvider

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

In general the plugin implementing this interface is responsible to:

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:

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)
                        throws RetrieveIssueException
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
Throws:
RetrieveIssueException - 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