Interface IssueFetcher

  • All Known Implementing Classes:
    AbstractIssueFetcher

    public interface IssueFetcher
    Represents a fetcher interface: a helper entity responsible only for fetching (downloading) the issue data from a remote server. The fetcher uses a persistent cache to optimize retrieving the issues.
    Since:
    5.0
    Author:
    Maxim Podkolzine (maxim.podkolzine@jetbrains.com)
    • Method Detail

      • getIssue

        @NotNull
        IssueData getIssue​(@NotNull
                           String host,
                           @NotNull
                           String id,
                           @Nullable
                           org.apache.commons.httpclient.Credentials credentials)
                    throws Exception
        Fetches and parses the issue from the remote server (issue-tracker). The tracker location is specified by host, issue is specified by id.

        The implementers are encouraged to report general fetching errors by throwing RetrieveIssueException: NotFoundException when the issue cannot be found, UnsupportedException when the issue tracker protocol is not supported, etc.

        Parameters:
        host - the server host
        id - issue id
        credentials - basic auth credentials (null means no credentials)
        Returns:
        the issue corresponding to id
        Throws:
        Exception - in case of I/O, parsing or any other error
      • fetchIssue

        @NotNull
        IssueData fetchIssue​(@NotNull
                             String host,
                             @NotNull
                             String id,
                             @NotNull
                             IssueFetcherAuthenticator authenticator)
                      throws Exception
        Fetches and parses the issue from the remote server (issue-tracker). The tracker location is specified by host, issue is specified by id.

        The implementers are encouraged to report general fetching errors by throwing RetrieveIssueException: NotFoundException when the issue cannot be found, UnsupportedException when the issue tracker protocol is not supported, etc.

        Parameters:
        host - the server host
        id - issue id
        authenticator - authenticator
        Returns:
        the issue corresponding to id
        Throws:
        Exception - in case of I/O, parsing or any other error
        Since:
        9.0
      • getUrl

        @NotNull
        String getUrl​(@NotNull
                      String host,
                      @NotNull
                      String id)
        Returns the URL corresponding the issue #id. This method is needed for the comment transformation.

        The URL is also serves as a key in the cache.

        Parameters:
        host - server host
        id - issue id
        Returns:
        the URL for fetching the issue
      • hasInCache

        boolean hasInCache​(@NotNull
                           String host,
                           @NotNull
                           String id)
        Returns whether the fetcher contains the issue corresponding to id in its cache.
        Parameters:
        host - server host
        id - issue id
        Returns:
        true if the issue is in cache
        See Also:
        hasInErrorCache(String, String)
      • hasInErrorCache

        boolean hasInErrorCache​(@NotNull
                                String host,
                                @NotNull
                                String id)
        Returns whether the fetcher contains the error retrieving id in its cache.
        Parameters:
        host - server host
        id - issue id
        Returns:
        true if the issue is in error cache
        Since:
        7.1
        See Also:
        hasInCache(String, String)
      • removeFromCache

        void removeFromCache​(@NotNull
                             String host,
                             @NotNull
                             String id)
        Removes the cached entry corresponding to the issue id.
        Parameters:
        host - server host
        id - issue id
      • getPossiblyExpiredData

        @Nullable
        IssueData getPossiblyExpiredData​(@NotNull
                                         String host,
                                         @NotNull
                                         String id)
        Returns the cached issue data, no matter if it's expired or not.
        Parameters:
        host - server host
        id - issue id
        Returns:
        the cached issue data (if exists), or null
      • getIssuesInBatch

        @Nullable
        Collection<IssueData> getIssuesInBatch​(@NotNull
                                               String host,
                                               @NotNull
                                               Collection<String> ids,
                                               @Nullable
                                               org.apache.commons.httpclient.Credentials credentials)
        Fetches a number of issues in a batch, and returns the corresponding data. Returns null if batch fetching is not supported.

        Note: method doesn't throw. Issues that cannot be fetched are simply ignored.

        Note: no particular order is guaranteed.

        Note: method may be significantly slow for some implementations.

        Parameters:
        host - server host
        ids - issue ids
        credentials - basic auth credentials (null means no credentials)
        Returns:
        the cached issue data (if exists), or null
        Since:
        7.0
      • fetchIssuesInBatch

        @Nullable
        Collection<IssueData> fetchIssuesInBatch​(@NotNull
                                                 String host,
                                                 @NotNull
                                                 Collection<String> ids,
                                                 @NotNull
                                                 IssueFetcherAuthenticator authenticator)
        Fetches a number of issues in a batch, and returns the corresponding data. Returns null if batch fetching is not supported.

        Note: method doesn't throw. Issues that cannot be fetched are simply ignored.

        Note: no particular order is guaranteed.

        Note: method may be significantly slow for some implementations.

        Parameters:
        host - server host
        ids - issue ids
        authenticator - authenticator
        Returns:
        the cached issue data (if exists), or null
        Since:
        9.0
      • fetchProjectIds

        @Nullable
        @Deprecated
        List<String> fetchProjectIds​(@NotNull
                                     String host,
                                     @NotNull
                                     IssueFetcherAuthenticator authenticator)
        Deprecated.
        Fetches all available project ids.
        Parameters:
        host - server host
        authenticator - authenticator
        Returns:
        see above
        Since:
        9.0