Package jetbrains.buildServer.issueTracker

Interface IssueProvider

  • All Known Subinterfaces:
    SIssueProvider
    All Known Implementing Classes:
    AbstractIssueProvider, AbstractPatternBasedIssueProvider, 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:

    • 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 corresponding 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 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:
        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