jenkins.scm.api

Class SCMHeadEvent<P>

java.lang.Object

jenkins.scm.api.SCMEvent<P>

jenkins.scm.api.SCMHeadEvent<P>

Type Parameters:

P - the (provider specific) payload.

public abstract class SCMHeadEvent<P>
extends SCMEvent<P>

Base class for events relating to SCMHead instances.

Since:

2.0

Nested Class Summary

Nested classes/interfaces inherited from class jenkins.scm.api.SCMEvent

SCMEvent.Dispatcher<E extends SCMEvent<?>>, SCMEvent.EventQueueMetrics, SCMEvent.Type

Field Summary

Fields inherited from class jenkins.scm.api.SCMEvent

ORIGIN_UNKNOWN

Constructor Summary

Constructors

Modifier	Constructor and Description
	SCMHeadEvent(SCMEvent.Type type, long timestamp, P payload) Deprecated.
	SCMHeadEvent(SCMEvent.Type type, long timestamp, P payload, String origin)
	SCMHeadEvent(SCMEvent.Type type, P payload) Deprecated.
	SCMHeadEvent(SCMEvent.Type type, P payload, String origin)
protected	SCMHeadEvent(SCMHeadEvent<P> src)

Method Summary

Modifier and Type	Method and Description
String	descriptionFor(SCM scm) Return a description of the event in the context of the supplied SCM.
String	descriptionFor(SCMNavigator navigator) Return a description of the event in the context of the supplied SCMNavigator.
String	descriptionFor(SCMSource source) Return a description of the event in the context of the supplied SCMSource.
<O extends SCMHeadObserver> SCMHeadObserver.Wrapped<O>	filter(SCMSource source, O delegate) Wraps a SCMHeadObserver such that the wrapped observer will only observe SCMHead instances mentioned in this event.
static void	fireLater(SCMHeadEvent<?> event, long delay, TimeUnit delayUnits) Fires the SCMHeadEvent to all registered SCMEventListener instances after the specified delay.
static void	fireNow(SCMHeadEvent<?> event) Fires the SCMHeadEvent to all registered SCMEventListener instances.
abstract String	getSourceName() Returns the name of the SCMSource, such as a repository name within an organization; may be used as an Item.getName().
abstract Map<SCMHead,SCMRevision>	heads(SCMSource source) Returns the SCMHead for the supplied SCMSource that this event corresponds to.
abstract boolean	isMatch(SCM scm) Tests if this event applies to the supplied SCM.
abstract boolean	isMatch(SCMNavigator navigator) Tests if this event applies to the supplied SCMNavigator.
boolean	isMatch(SCMSource source) Tests if this event applies to the supplied SCMSource.

Methods inherited from class jenkins.scm.api.SCMEvent

asCauses, closeExecutorService, description, equals, executorService, getDate, getEventProcessingMetrics, getOrigin, getPayload, getTimestamp, getType, hashCode, originOf, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SCMHeadEvent

@Deprecated
public SCMHeadEvent(@NonNull
                                SCMEvent.Type type,
                                long timestamp,
                                @NonNull
                                P payload)

Deprecated.

SCMHeadEvent

public SCMHeadEvent(@NonNull
                    SCMEvent.Type type,
                    long timestamp,
                    @NonNull
                    P payload,
                    @CheckForNull
                    String origin)

SCMHeadEvent

@Deprecated
public SCMHeadEvent(@NonNull
                                SCMEvent.Type type,
                                @NonNull
                                P payload)

Deprecated.

SCMHeadEvent

public SCMHeadEvent(@NonNull
                    SCMEvent.Type type,
                    @NonNull
                    P payload,
                    @CheckForNull
                    String origin)

SCMHeadEvent

protected SCMHeadEvent(@NonNull
                       SCMHeadEvent<P> src)

Method Detail

isMatch

public abstract boolean isMatch(@NonNull
                                SCMNavigator navigator)

Tests if this event applies to the supplied SCMNavigator.

Parameters:

navigator - the SCMNavigator.

Returns:

true if and only if this event concerns the supplied SCMNavigator.

descriptionFor

@CheckForNull
public String descriptionFor(@NonNull
                                           SCMNavigator navigator)

Return a description of the event in the context of the supplied SCMNavigator.

Parameters:

navigator - the SCMNavigator, the navigator must be isMatch(SCMNavigator).

Returns:

the description or null if no description can be provided.

Since:

2.1.1

getSourceName

@NonNull
public abstract String getSourceName()

Returns the name of the SCMSource, such as a repository name within an organization; may be used as an Item.getName(). Must be the same as the name that would be passed to SCMSourceObserver.observe(String) by any SCMNavigator that isMatch(SCMNavigator).

NOTE: if and only if isMatch(SCMNavigator) always returns false then the value returned here does not matter and a dummy value can be returned instead.

DO NOT TRUST THE RETURN VALUES. Data from events should only be used as a rumour that requires verification.

Returns:

the name of the SCMSource

isMatch

public boolean isMatch(@NonNull
                       SCMSource source)

Tests if this event applies to the supplied SCMSource.

Parameters:

source - the SCMSource.

Returns:

true if and only if this event concerns the supplied SCMSource.

descriptionFor

@CheckForNull
public String descriptionFor(SCMSource source)

Return a description of the event in the context of the supplied SCMSource.

Parameters:

source - the SCMSource, the source must be isMatch(SCMSource).

Returns:

the description or null if no description can be provided.

Since:

2.1.1

heads

@NonNull
public abstract Map<SCMHead,SCMRevision> heads(@NonNull
                                                        SCMSource source)

Returns the SCMHead for the supplied SCMSource that this event corresponds to.

DO NOT TRUST THE RETURN VALUES. Data from events should only be used as a rumour that requires verification.

Parameters:

source - the SCMSource.

Returns:

the SCMHead (and optional SCMRevision) that this event corresponds to when considered from the point of view of the supplied SCMSource. The map may be empty in the case where the event is not relevant to the supplied SCMSource

isMatch

public abstract boolean isMatch(@NonNull
                                SCM scm)

Tests if this event applies to the supplied SCM. Implementations that return true will trigger polling for the matching jobs that have enabled the SCMTrigger and have not disabled the post commit hooks SCMTrigger.isIgnorePostCommitHooks().

NOTE: if you are implementing SCMHeadEvent and you already have a separate code path responsible for notifying SCMTrigger then you should either remove that code path or always return false from this method. The recommendation is to consolidate on SCMHeadEvent based triggering as that minimizes the number of times the graph of all items needs to be traversed by event listeners.

Parameters:

scm - the SCM.

Returns:

true if and only if this event concerns the supplied SCM.

See Also:

SCMTriggerListener, SCMTrigger.isIgnorePostCommitHooks()

descriptionFor

@CheckForNull
public String descriptionFor(SCM scm)

Return a description of the event in the context of the supplied SCM.

Parameters:

scm - the SCM, the scm must be isMatch(SCM).

Returns:

the description or null if no description can be provided.

Since:

2.1.1

filter

public <O extends SCMHeadObserver> SCMHeadObserver.Wrapped<O> filter(@NonNull
                                                                     SCMSource source,
                                                                     O delegate)

Wraps a SCMHeadObserver such that the wrapped observer will only observe SCMHead instances mentioned in this event.

Type Parameters:

O - the type of delegate.

Parameters:

source - the SCMSource.

delegate - the delegate.

Returns:

the wrapped delegate.

fireNow

public static void fireNow(@NonNull
                           SCMHeadEvent<?> event)

Fires the SCMHeadEvent to all registered SCMEventListener instances.

Parameters:

event - the event to fire.

fireLater

public static void fireLater(@NonNull
                             SCMHeadEvent<?> event,
                             long delay,
                             TimeUnit delayUnits)

Fires the SCMHeadEvent to all registered SCMEventListener instances after the specified delay.

Parameters:

event - the event to fire.

delay - how long to wait before firing the event.

delayUnits - the units of time in which the delay is expressed.