jenkins.scm.api

Class SCMSourceObserver

java.lang.Object

jenkins.scm.api.SCMSourceObserver

Direct Known Subclasses:

SCMSourceObserver.Wrapped

public abstract class SCMSourceObserver
extends Object

Callback used by SCMNavigator.

Since:

0.3-beta-1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SCMSourceObserver.Filter<O extends SCMSourceObserver> An observer that filters the observed sources to a subset of named instances.
static class	SCMSourceObserver.ProjectObserver Nested callback produced by observe(java.lang.String).
static class	SCMSourceObserver.Wrapped<O extends SCMSourceObserver> Base class for an observer that wraps another observer.

Constructor Summary

Constructors

Constructor and Description
SCMSourceObserver()

Method Summary

Modifier and Type	Method and Description
abstract void	addAttribute(String key, Object value) Adds extra metadata about the overall organization.
static <O extends SCMSourceObserver> SCMSourceObserver.Filter<O>	filter(O delegate, String... projectNames) Creates an observer that filters a delegates observer to the specified project names
abstract SCMSourceOwner	getContext() Indicates who is asking for sources.
Set<String>	getIncludes() Returns the subset of "project" names that this observer is interested in or null if interested in all "project" names.
abstract TaskListener	getListener() Provides a way of reporting progress.
boolean	isObserving() Returns information about whether the observer wants more results.
abstract SCMSourceObserver.ProjectObserver	observe(String projectName) Declare that a new “project” such as a source repository has been found.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SCMSourceObserver

public SCMSourceObserver()

Method Detail

getContext

@NonNull
public abstract SCMSourceOwner getContext()

Indicates who is asking for sources.

Returns:

a contextual item, typically a OrganizationFolder

getListener

@NonNull
public abstract TaskListener getListener()

Provides a way of reporting progress.

Returns:

a logger

getIncludes

@CheckForNull
public Set<String> getIncludes()

Returns the subset of "project" names that this observer is interested in or null if interested in all "project" names.

Implementations should not assume that the getIncludes() will be honoured. This method is designed to provide a hint to SCMNavigator implementations.

Returns:

the subset of "project" names that this observer is interested in or null.

Since:

2.0

See Also:

for the definition of "project" names

observe

@NonNull
public abstract SCMSourceObserver.ProjectObserver observe(@NonNull
                                                                   String projectName)
                                                            throws IllegalArgumentException,
                                                                   IOException,
                                                                   InterruptedException

Declare that a new “project” such as a source repository has been found.

Parameters:

projectName - a name of the project, such as a repository name within an organization; may be used as an Item.getName()

Returns:

a secondary callback to customize the project, on which you must call SCMSourceObserver.ProjectObserver.complete()

Throws:

IllegalArgumentException - if this projectName has already been encountered

IOException - if observing this projectName could not be completed due to an IOException.

InterruptedException - if observing this projectName was interrupted.

addAttribute

public abstract void addAttribute(@NonNull
                                  String key,
                                  @Nullable
                                  Object value)
                           throws IllegalArgumentException,
                                  ClassCastException

Adds extra metadata about the overall organization. Currently no metadata keys are defined; placeholder for description, icon, URL, etc.

Parameters:

key - a predefined attribute name

value - some value, of a type defined by the attribute, perhaps null if allowed by the attribute documentation

Throws:

IllegalArgumentException - if the attribute name is unrecognized, or this attribute was already added

ClassCastException - if the attribute value is inappropriate for its type

isObserving

public boolean isObserving()

Returns information about whether the observer wants more results.

Returns:

true if the observer is still observing or false to signal that it is ok to stop early.

Since:

2.0

filter

@NonNull
public static <O extends SCMSourceObserver> SCMSourceObserver.Filter<O> filter(O delegate,
                                                                                        String... projectNames)

Creates an observer that filters a delegates observer to the specified project names

Type Parameters:

O - the type of observer that will be filtered.

Parameters:

delegate - the delegate

projectNames - the project names to watch out for.

Returns:

an observer that wraps the supplied delegate.

Since:

2.0