Package jetbrains.buildServer.issueTracker

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 Summary

Modifier and Type	Method	Description
IssueData	fetchIssue(java.lang.String host, java.lang.String id, IssueFetcherAuthenticator authenticator)	Fetches and parses the issue from the remote server (issue-tracker).
java.util.Collection<IssueData>	fetchIssuesInBatch(java.lang.String host, java.util.Collection<java.lang.String> ids, IssueFetcherAuthenticator authenticator)	Fetches a number of issues in a batch, and returns the corresponding data.
java.util.List<java.lang.String>	fetchProjectIds(java.lang.String host, IssueFetcherAuthenticator authenticator)	Deprecated.
IssueData	getIssue(java.lang.String host, java.lang.String id, org.apache.commons.httpclient.Credentials credentials)	Fetches and parses the issue from the remote server (issue-tracker).
java.util.Collection<IssueData>	getIssuesInBatch(java.lang.String host, java.util.Collection<java.lang.String> ids, org.apache.commons.httpclient.Credentials credentials)	Fetches a number of issues in a batch, and returns the corresponding data.
IssueData	getPossiblyExpiredData(java.lang.String host, java.lang.String id)	Returns the cached issue data, no matter if it's expired or not.
java.lang.String	getUrl(java.lang.String host, java.lang.String id)	Returns the URL corresponding the issue #id.
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.
void	removeFromCache(java.lang.String host, java.lang.String id)	Removes the cached entry corresponding to the issue id.

Method Detail

getIssue

@NotNull
IssueData getIssue(@NotNull
                   java.lang.String host,
                   @NotNull
                   java.lang.String id,
                   @Nullable
                   org.apache.commons.httpclient.Credentials credentials)
            throws java.lang.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:

java.lang.Exception - in case of I/O, parsing or any other error

fetchIssue

@NotNull
IssueData fetchIssue(@NotNull
                     java.lang.String host,
                     @NotNull
                     java.lang.String id,
                     @NotNull
                     IssueFetcherAuthenticator authenticator)
              throws java.lang.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:

java.lang.Exception - in case of I/O, parsing or any other error

Since:

9.0

getUrl

@NotNull
java.lang.String getUrl(@NotNull
                        java.lang.String host,
                        @NotNull
                        java.lang.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
                   java.lang.String host,
                   @NotNull
                   java.lang.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
                        java.lang.String host,
                        @NotNull
                        java.lang.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
                     java.lang.String host,
                     @NotNull
                     java.lang.String id)

Removes the cached entry corresponding to the issue id.

Parameters:

host - server host

id - issue id

getPossiblyExpiredData

@Nullable
IssueData getPossiblyExpiredData(@NotNull
                                 java.lang.String host,
                                 @NotNull
                                 java.lang.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
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)

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
java.util.Collection<IssueData> fetchIssuesInBatch(@NotNull
                                                   java.lang.String host,
                                                   @NotNull
                                                   java.util.Collection<java.lang.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
java.util.List<java.lang.String> fetchProjectIds(@NotNull
                                                 java.lang.String host,
                                                 @NotNull
                                                 IssueFetcherAuthenticator authenticator)

Deprecated.

Fetches all available project ids.

Parameters:

host - server host

authenticator - authenticator

Returns:

see above

Since:

9.0