jenkins.scm.api

Class SCMEvent<P>

java.lang.Object

jenkins.scm.api.SCMEvent<P>

Type Parameters:

P - the type of (provider specific) payload.

Direct Known Subclasses:

SCMHeadEvent, SCMNavigatorEvent, SCMSourceEvent

public abstract class SCMEvent<P>
extends Object

Base class for all events from a SCM system.

NOTE: Not every SCM system will be able to support all possible events. Not every plugin building on top of the SCM API will be able to respond to every event.

Information for SCM API consumers

Consumers of events should assume that the data from an event is unverified / untrusted. Events should be used to scope queries against the SCMNavigator / SCMSource to which they relate. In all other respects, consumers should treat the event payload and information derived from the payload as being just a rumour.

NOTE: Implementations may retain their own internal tracking of portions of the event payload that are verified / trusted and use such internal information to assist in optimization of the processing of scoped queried, but at this time we are not exposing such partial trust information to consumers until we have established some patterns.

The priority for consumers of the SCM API, in other words, implementations of SCMNavigatorOwner and SCMSourceOwner, is to avoid full rescans as a means of detecting:

• Creation of new SCMSource instances within a SCMNavigator, i.e. a SCMNavigatorOwner implementation should make best effort to handle a SCMSourceEvent of SCMEvent.Type.CREATED without resorting to SCMNavigator.visitSources(SCMSourceObserver)
• Creation of new SCMHead instances within a SCMSource, i.e. a SCMSourceOwner implementation should make best effort to handle a SCMHeadEvent of SCMEvent.Type.CREATED without resorting to SCMSource.fetch(SCMHeadObserver, TaskListener) or SCMSource.fetch(SCMSourceCriteria, SCMHeadObserver, TaskListener)
• The update of a SCMHead instance to point to a new SCMRevision, i.e. a SCMHeadEvent of SCMEvent.Type.UPDATED. NOTE: typically existing legacy SCM implementations will handle this out-of-band, but it would be nice if the notification could be consolidated.

Information for SCM API providers

The priority for implementers of the SCM API, in other words, implementations of SCMNavigator and SCMSource, is to ensure that consumers do not have to trigger full rescans.

Where implementers can obtain some form of trust / verification about event payloads, please share your patterns with the maintainers of this API so that a generic set of patterns can be abstracted for exposure to consumers.

Since:

2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	SCMEvent.Dispatcher<E extends SCMEvent<?>>
static class	SCMEvent.EventQueueMetrics
static class	SCMEvent.Type The type of event.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ORIGIN_UNKNOWN An unknown origin.

Constructor Summary

Constructors

Modifier	Constructor and Description
	SCMEvent(SCMEvent.Type type, long timestamp, P payload) Deprecated. use SCMEvent(Type, long, Object, String)
	SCMEvent(SCMEvent.Type type, long timestamp, P payload, String origin) Constructor to use when the timestamp is available from the external SCM.
	SCMEvent(SCMEvent.Type type, P payload) Deprecated. use SCMEvent(Type, Object, String)
	SCMEvent(SCMEvent.Type type, P payload, String origin) Constructor to use when the timestamp is not available from the external SCM.
protected	SCMEvent(SCMEvent<P> copy) Copy constructor which may be required in cases where sub-classes need to implement readResolve

Method Summary

Modifier and Type	Method and Description
Cause[]	asCauses() If this event is being used to trigger a build, what - if any - Causes should be added to the triggered build.
static void	closeExecutorService() Shutdown the timer and throw it away.
String	description() Return a description of the event.
boolean	equals(Object o)
protected static ScheduledExecutorService	executorService() The ScheduledExecutorService that events should be fired on.
Date	getDate() Gets the timestamp of the event as a Date.
static SCMEvent.EventQueueMetrics	getEventProcessingMetrics()
String	getOrigin() Gets the origin of the event, e.g.
P	getPayload() Gets the provider specific event payload.
long	getTimestamp() Gets the timestamp of the event (see System.currentTimeMillis() for start and units).
SCMEvent.Type	getType() Gets the type of event.
int	hashCode()
static String	originOf(javax.servlet.http.HttpServletRequest req) Helper method to get the origin of an event from a HttpServletRequest.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

ORIGIN_UNKNOWN

public static final String ORIGIN_UNKNOWN

An unknown origin.

Since:

2.0.3

See Also:

Constant Field Values

Constructor Detail

SCMEvent

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

Deprecated. use SCMEvent(Type, long, Object, String)

Constructor to use when the timestamp is available from the external SCM.

Parameters:

type - the type of event.

timestamp - the timestamp from the external SCM (see System.currentTimeMillis() for start and units)

payload - the original provider specific payload.

SCMEvent

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

Constructor to use when the timestamp is available from the external SCM.

Parameters:

type - the type of event.

timestamp - the timestamp from the external SCM (see System.currentTimeMillis() for start and units)

payload - the original provider specific payload.

origin - the (optional) origin of the event, e.g. a hostname, etc. It is recommended to use originOf(HttpServletRequest) where the event originates from a HttpServletRequest and the request is available when the event is being created.

Since:

2.0.3

SCMEvent

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

Deprecated. use SCMEvent(Type, Object, String)

Constructor to use when the timestamp is not available from the external SCM. The timestamp will be set using System.currentTimeMillis()

Parameters:

type - the type of event.

payload - the original provider specific payload.

SCMEvent

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

Constructor to use when the timestamp is not available from the external SCM. The timestamp will be set using System.currentTimeMillis()

Parameters:

type - the type of event.

payload - the original provider specific payload.

origin - the (optional) origin of the event, e.g. a hostname, etc

Since:

2.0.3

SCMEvent

protected SCMEvent(SCMEvent<P> copy)

Copy constructor which may be required in cases where sub-classes need to implement readResolve

Parameters:

copy - the event to clone.

Method Detail

executorService

@NonNull
protected static ScheduledExecutorService executorService()

The ScheduledExecutorService that events should be fired on.

Returns:

a ScheduledExecutorService.

getEventProcessingMetrics

public static SCMEvent.EventQueueMetrics getEventProcessingMetrics()

closeExecutorService

@Terminator
public static void closeExecutorService()

Shutdown the timer and throw it away.

getType

@NonNull
public SCMEvent.Type getType()

Gets the type of event.

Returns:

the type of event.

getTimestamp

public long getTimestamp()

Gets the timestamp of the event (see System.currentTimeMillis() for start and units).

Returns:

the timestamp of the event.

getDate

@NonNull
public Date getDate()

Gets the timestamp of the event as a Date.

Returns:

the timestamp of the event.

getPayload

@NonNull
public P getPayload()

Gets the provider specific event payload.

Returns:

the provider specific event payload.

getOrigin

@NonNull
public String getOrigin()

Gets the origin of the event, e.g. a hostname, etc.

Returns:

the origin of the event (or ORIGIN_UNKNOWN if the origin is unknown)

Since:

2.0.3

description

@CheckForNull
public String description()

Return a description of the event.

Returns:

the description or null if no description can be provided.

Since:

2.1.1

asCauses

@NonNull
public Cause[] asCauses()

If this event is being used to trigger a build, what - if any - Causes should be added to the triggered build. The Cause instances should probably be new instances each time, see Cause.onAddedTo(Run).

Returns:

the Cause instances to add to any builds triggered by this event.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

originOf

@CheckForNull
public static String originOf(@CheckForNull
                                            javax.servlet.http.HttpServletRequest req)

Helper method to get the origin of an event from a HttpServletRequest. The current format is the list of hostname / ip addresses from the request (parsing X-Forwarded-For headers) separated by → followed by a ⇒ and finally the requested URL (omitting the query portion of the URL).

Parameters:

req - the HttpServletRequest or null (this is to allow passing Stapler.getCurrentRequest() without having to check for null)

Returns:

the origin of the event or null if the HttpServletRequest is null.

Since:

2.0.3