jetbrains.buildServer.issueTracker
Class AbstractIssueFetcher

java.lang.Object
  extended by jetbrains.buildServer.issueTracker.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)

Nested Class Summary
protected static interface AbstractIssueFetcher.BatchFetchFunction
          An interface represents an action of fetching in a batch.
protected static interface AbstractIssueFetcher.CacheKeyFunction
          The cache key function.
protected static interface AbstractIssueFetcher.FetchFunction
          An interface represents an action of actual issue fetching.
 
Constructor Summary
AbstractIssueFetcher(EhCacheUtil cacheUtil)
           
 
Method Summary
protected  java.util.Collection<IssueData> defaultGetIssuesInBatch(java.lang.String host, java.util.Collection<java.lang.String> ids, AbstractIssueFetcher.BatchFetchFunction function)
          Method is identical to fetchNonCachedIssues(Collection, CacheKeyFunction, BatchFetchFunction), but uses a default key function (id -> url).
protected  java.io.InputStream fetchHttpFile(java.lang.String url, org.apache.commons.httpclient.Credentials credentials)
          Fetches the document from HTTP resource specified by url with specified credentials.
protected  java.util.Collection<IssueData> fetchNonCachedIssues(java.util.Collection<java.lang.String> ids, AbstractIssueFetcher.CacheKeyFunction keyFunction, AbstractIssueFetcher.BatchFetchFunction fetchFunction)
          Performs a specified fetch function fetchFunction for a number of issue ids, which are not cached at the moment.
protected  java.lang.String getAttribute(org.jdom.Element element, java.lang.String attributeName)
          Returns the element's attribute value.
protected  net.sf.ehcache.Cache getCache()
           
protected  java.lang.String getChildContent(org.jdom.Element element, java.lang.String childName)
          Returns the content text of the child element.
protected  net.sf.ehcache.Cache getErrorCache()
           
protected  IssueData getFromCacheOrFetch(java.lang.Object key, AbstractIssueFetcher.FetchFunction function)
          Returns a cached issue, or performs a slow fetch operation specified by a function and returns the result.
 java.util.Collection<IssueData> getIssuesInBatch(java.lang.String host, java.util.Collection<java.lang.String> ids, org.apache.commons.httpclient.Credentials credentials)
          Batch fetching.
 IssueData getPossiblyExpiredData(java.lang.String host, java.lang.String id)
          Returns the cached issue data, no matter if it's expired or not.
protected  void handleHttpError(int code, org.apache.commons.httpclient.methods.GetMethod get)
          Handles the HTTP error after unsuccessful GET request.
 boolean hasInCache(java.lang.String host, java.lang.String id)
          Returns whether the fetcher contains the issue corresponding to id in its cache.
 boolean hasInErrorCache(java.lang.String host, java.lang.String id)
          Returns whether the fetcher contains the error retrieving id in its cache.
protected  boolean isFeature(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).
 void removeFromCache(java.lang.String host, java.lang.String id)
          Removes the cached entry corresponding to the issue id.
protected  java.lang.String toString(java.lang.Object obj)
          An utility method to transform an object to string safely.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface jetbrains.buildServer.issueTracker.IssueFetcher
getIssue, getUrl
 

Constructor Detail

AbstractIssueFetcher

public AbstractIssueFetcher(@NotNull
                            EhCacheUtil cacheUtil)
Method Detail

fetchHttpFile

@NotNull
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 - 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

handleHttpError

protected void handleHttpError(int code,
                               @NotNull
                               org.apache.commons.httpclient.methods.GetMethod get)
                        throws java.io.IOException
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 - auth credentials (null means no credentials)
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

defaultGetIssuesInBatch

@NotNull
protected java.util.Collection<IssueData> defaultGetIssuesInBatch(@NotNull
                                                                          java.lang.String host,
                                                                          @NotNull
                                                                          java.util.Collection<java.lang.String> ids,
                                                                          @NotNull
                                                                          AbstractIssueFetcher.BatchFetchFunction function)
Method is identical to fetchNonCachedIssues(Collection, CacheKeyFunction, BatchFetchFunction), but uses a default key function (id -> url).

Parameters:
host - the remote issue tracker host
ids - the ids to fetch (can be immutable)
function - general fetch function
Returns:
the collection of fetch data