jetbrains.buildServer.issueTracker
Class AbstractIssueFetcher

java.lang.Object
  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 perfomance.

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.
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

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

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