Class AbstractIssueFetcher

  • All Implemented Interfaces:
    IssueFetcher

    public abstract class AbstractIssueFetcher
    extends java.lang.Object
    implements IssueFetcher
    Represents the issue fetcher used by AbstractIssueProvider. This class contains commonly used routines for downloading and parsing XML.

    It also uses caching of the fetched issues (invalidated after certain time period) to improve overall performance.

    Author:
    Maxim Podkolzine (maxim.podkolzine@jetbrains.com)
    • Constructor Detail

      • AbstractIssueFetcher

        @Deprecated
        public AbstractIssueFetcher​(@NotNull
                                    EhCacheUtil cacheUtil)
        Deprecated.
        since 10.0, will be removed in future versions
    • Method Detail

      • fetchHttpFile

        @NotNull
        @Deprecated
        protected java.io.InputStream fetchHttpFile​(@NotNull
                                                    java.lang.String url,
                                                    @Nullable
                                                    org.apache.commons.httpclient.Credentials credentials)
                                             throws java.io.IOException
        Fetches the document from HTTP resource specified by url with specified credentials.
        Parameters:
        url - the url of file to fetch
        credentials - basic auth credentials (null means no credentials)
        Returns:
        result input stream, or null in case of HTTP error
        Throws:
        java.io.IOException - if I/O error occurs
      • getHttpFile

        @NotNull
        @Deprecated
        protected java.io.InputStream getHttpFile​(@NotNull
                                                  java.lang.String url,
                                                  @NotNull
                                                  IssueFetcherAuthenticator authenticator)
                                           throws java.io.IOException
        Fetches the document from HTTP resource specified by url with specified credentials.
        Parameters:
        url - the url of file to fetch
        authenticator - authenticator
        Returns:
        result input stream, or null in case of HTTP error
        Throws:
        java.io.IOException - if I/O error occurs
      • getHttpFile

        @Deprecated
        protected java.io.InputStream getHttpFile​(@NotNull
                                                  java.lang.String url,
                                                  @Nullable
                                                  SimpleCredentials credentials,
                                                  boolean usePreemptiveAuthentication,
                                                  @Nullable
                                                  java.security.KeyStore trustStore)
                                           throws java.io.IOException,
                                                  java.net.URISyntaxException
        Fetches the document from HTTP resource specified by url with specified credentials.
        Parameters:
        url - the url of file to fetch
        credentials - the data for authentication
        usePreemptiveAuthentication - is it necessary to use preemptive authentication
        trustStore - store with trusted SSL certificates
        Returns:
        result input stream
        Throws:
        java.io.IOException - if I/O error occurs
        java.net.URISyntaxException - if specified url cannot be converted to valid URI
      • getHttpFile

        protected java.io.InputStream getHttpFile​(@NotNull
                                                  java.lang.String url,
                                                  @Nullable
                                                  SimpleCredentials credentials,
                                                  boolean usePreemptiveAuthentication,
                                                  @Nullable
                                                  java.security.KeyStore trustStore,
                                                  @NotNull
                                                  HTTPRequestBuilder.ResponseConsumer errorsConsumer)
                                           throws java.io.IOException,
                                                  java.net.URISyntaxException
        Fetches the document from HTTP resource specified by url with specified credentials. If authentication requires setting specific properties to request or uses custom logic implemented in authenticator, use getHttpFile(String, IssueFetcherAuthenticator, KeyStore, HTTPRequestBuilder.ResponseConsumer)
        Parameters:
        url - the url of file to fetch
        credentials - the data for authentication
        usePreemptiveAuthentication - is it necessary to use preemptive authentication
        trustStore - store with trusted SSL certificates
        errorsConsumer - the handler of HTTP errors after unsuccessful GET request
        Returns:
        result input stream
        Throws:
        java.io.IOException - if I/O error occurs
        java.net.URISyntaxException - if specified url cannot be converted to valid URI
      • getHttpFile

        protected java.io.InputStream getHttpFile​(@NotNull
                                                  java.lang.String url,
                                                  @NotNull
                                                  IssueFetcherAuthenticator authenticator,
                                                  @Nullable
                                                  java.security.KeyStore trustStore,
                                                  @NotNull
                                                  HTTPRequestBuilder.ResponseConsumer errorsConsumer)
                                           throws java.io.IOException,
                                                  java.net.URISyntaxException
        Fetches the document from HTTP resource specified by url with specified credentials.
        Parameters:
        url - the url of file to fetch
        authenticator - authenticator
        trustStore - store with trusted SSL certificates
        errorsConsumer - the handler of HTTP errors after unsuccessful GET request
        Returns:
        result input stream
        Throws:
        java.io.IOException - if I/O error occurs
        java.net.URISyntaxException - if specified url cannot be converted to valid URI
        Since:
        2019.1
      • fetchIssue

        @NotNull
        public IssueData fetchIssue​(@NotNull
                                    java.lang.String host,
                                    @NotNull
                                    java.lang.String id,
                                    @NotNull
                                    IssueFetcherAuthenticator authenticator)
                             throws java.lang.Exception
        backward compatibility
        Specified by:
        fetchIssue in interface IssueFetcher
        Parameters:
        host - the server host
        id - issue id
        authenticator - authenticator
        Returns:
        the issue corresponding to id
        Throws:
        java.lang.Exception - in case of I/O, parsing or any other error
      • handleHttpError

        protected void handleHttpError​(int code,
                                       @NotNull
                                       org.apache.commons.httpclient.methods.GetMethod get)
                                throws java.io.IOException
        Deprecated.
        method is deprecated because corresponding methods fetchHttpFile(String, Credentials) and getHttpFile(String, IssueFetcherAuthenticator) are deprecated
        Handles the HTTP error after unsuccessful GET request.
        Parameters:
        code - the response code
        get - get method
        Throws:
        java.io.IOException - if I/O error occurs
      • getChildContent

        @Nullable
        protected java.lang.String getChildContent​(@NotNull
                                                   org.jdom.Element element,
                                                   @NotNull
                                                   java.lang.String childName)
        Returns the content text of the child element.
        Parameters:
        element - the parent DOM element
        childName - child name
        Returns:
        the textual content directly held under the child, or null
      • getAttribute

        @Nullable
        protected java.lang.String getAttribute​(@NotNull
                                                org.jdom.Element element,
                                                @NotNull
                                                java.lang.String attributeName)
        Returns the element's attribute value.
        Parameters:
        element - the DOM element
        attributeName - attribute name
        Returns:
        the textual value of the specified attribute, or null
      • isFeature

        protected boolean isFeature​(@Nullable
                                    java.lang.String field)
        Returns whether the issue is a feature request (by a single field, which can be a type, severity, or any other one).

        The implementation is default (simply checks that field equals to "feature" or "enhancement" ignoring the case), may not be applicable for a particular issue tracking system.

        Parameters:
        field - the field that determines feature attribute
        Returns:
        true if the issue is a feature based on a field
      • getFromCacheOrFetch

        @NotNull
        protected IssueData getFromCacheOrFetch​(@NotNull
                                                java.lang.Object key,
                                                @NotNull
                                                AbstractIssueFetcher.FetchFunction function)
                                         throws java.lang.Exception
        Returns a cached issue, or performs a slow fetch operation specified by a function and returns the result.

        Note that if the issue cannot be fetched, a null value is still put in cache, so the issue won't be requested until the cache entry is expired.

        Use this method to implement a IssueFetcher.getIssue(String, String, Credentials) method. Example:

           @NotNull
           public Issue getIssue(@NotNull String host, @NotNull String id,
                                 @Nullable final Credentials credentials) {
             final String url = composeUrl(host, id);
             return getFromCacheOrFetch(url, new FetchFunction() {
               @NotNull
               public Issue fetch() throws Exception {
                 return doFetch(url, credentials);
               }
             });
           }
         
        Parameters:
        key - the issue key (usually an URL corresponding to an issue)
        function - a function called when the cache doesn't contain the result
        Returns:
        an issue
        Throws:
        java.lang.Exception - if the issue cannot be fetched
      • toString

        @Nullable
        protected java.lang.String toString​(@Nullable
                                            java.lang.Object obj)
        An utility method to transform an object to string safely.
        Parameters:
        obj - any object
        Returns:
        obj.toString(), or null
      • hasInCache

        public boolean hasInCache​(@NotNull
                                  java.lang.String host,
                                  @NotNull
                                  java.lang.String id)
        Description copied from interface: IssueFetcher
        Returns whether the fetcher contains the issue corresponding to id in its cache.
        Specified by:
        hasInCache in interface IssueFetcher
        Parameters:
        host - server host
        id - issue id
        Returns:
        true if the issue is in cache
        See Also:
        IssueFetcher.hasInErrorCache(String, String)
      • hasInErrorCache

        public boolean hasInErrorCache​(@NotNull
                                       java.lang.String host,
                                       @NotNull
                                       java.lang.String id)
        Description copied from interface: IssueFetcher
        Returns whether the fetcher contains the error retrieving id in its cache.
        Specified by:
        hasInErrorCache in interface IssueFetcher
        Parameters:
        host - server host
        id - issue id
        Returns:
        true if the issue is in error cache
        See Also:
        IssueFetcher.hasInCache(String, String)
      • removeFromCache

        public void removeFromCache​(@NotNull
                                    java.lang.String host,
                                    @NotNull
                                    java.lang.String id)
        Description copied from interface: IssueFetcher
        Removes the cached entry corresponding to the issue id.
        Specified by:
        removeFromCache in interface IssueFetcher
        Parameters:
        host - server host
        id - issue id
      • getCache

        @NotNull
        protected net.sf.ehcache.Cache getCache()
      • getErrorCache

        @NotNull
        protected net.sf.ehcache.Cache getErrorCache()
      • getPossiblyExpiredData

        public IssueData getPossiblyExpiredData​(@NotNull
                                                java.lang.String host,
                                                @NotNull
                                                java.lang.String id)
        Description copied from interface: IssueFetcher
        Returns the cached issue data, no matter if it's expired or not.
        Specified by:
        getPossiblyExpiredData in interface IssueFetcher
        Parameters:
        host - server host
        id - issue id
        Returns:
        the cached issue data (if exists), or null
      • getIssuesInBatch

        @Nullable
        public java.util.Collection<IssueData> getIssuesInBatch​(@NotNull
                                                                java.lang.String host,
                                                                @NotNull
                                                                java.util.Collection<java.lang.String> ids,
                                                                @Nullable
                                                                org.apache.commons.httpclient.Credentials credentials)
        Batch fetching.
        Specified by:
        getIssuesInBatch in interface IssueFetcher
        Parameters:
        host - server host
        ids - issue ids
        credentials - basic auth credentials (null means no credentials)
        Returns:
        the cached issue data (if exists), or null
      • fetchIssuesInBatch

        @Nullable
        public java.util.Collection<IssueData> fetchIssuesInBatch​(@NotNull
                                                                  java.lang.String host,
                                                                  @NotNull
                                                                  java.util.Collection<java.lang.String> ids,
                                                                  @NotNull
                                                                  IssueFetcherAuthenticator authenticator)
        backward compatibility
        Specified by:
        fetchIssuesInBatch in interface IssueFetcher
        Parameters:
        host - server host
        ids - issue ids
        authenticator - authenticator
        Returns:
        the cached issue data (if exists), or null
      • fetchNonCachedIssues

        @NotNull
        protected java.util.Collection<IssueData> fetchNonCachedIssues​(@NotNull
                                                                       java.util.Collection<java.lang.String> ids,
                                                                       @NotNull
                                                                       AbstractIssueFetcher.CacheKeyFunction keyFunction,
                                                                       @NotNull
                                                                       AbstractIssueFetcher.BatchFetchFunction fetchFunction)
        Performs a specified fetch function fetchFunction for a number of issue ids, which are not cached at the moment.

        For this purpose ids must be mutable.

        Parameters:
        ids - the collection of ids to fetch
        keyFunction - the function used to get a cache key by issue id
        fetchFunction - general fetch function
        Returns:
        the collection of fetch data
      • fetchProjectIds

        @Nullable
        public java.util.List<java.lang.String> fetchProjectIds​(@NotNull
                                                                java.lang.String host,
                                                                @NotNull
                                                                IssueFetcherAuthenticator authenticator)
        Description copied from interface: IssueFetcher
        Fetches all available project ids.
        Specified by:
        fetchProjectIds in interface IssueFetcher
        Parameters:
        host - server host
        authenticator - authenticator
        Returns:
        see above