P
- the type of (provider specific) payload.public abstract class SCMEvent<P> extends Object
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.
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:
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)
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)
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.
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.
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.
|
Modifier and Type | Field and Description |
---|---|
static String |
ORIGIN_UNKNOWN
An unknown origin.
|
Modifier | Constructor and Description |
---|---|
|
SCMEvent(SCMEvent.Type type,
long timestamp,
P payload)
Deprecated.
|
|
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.
|
|
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 |
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() |
public static final String ORIGIN_UNKNOWN
@Deprecated public SCMEvent(@NonNull SCMEvent.Type type, long timestamp, @NonNull P payload)
SCMEvent(Type, long, Object, String)
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.public SCMEvent(@NonNull SCMEvent.Type type, long timestamp, @NonNull P payload, @CheckForNull String origin)
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.@Deprecated public SCMEvent(@NonNull SCMEvent.Type type, @NonNull P payload)
SCMEvent(Type, Object, String)
System.currentTimeMillis()
type
- the type of event.payload
- the original provider specific payload.public SCMEvent(@NonNull SCMEvent.Type type, @NonNull P payload, @CheckForNull String origin)
System.currentTimeMillis()
type
- the type of event.payload
- the original provider specific payload.origin
- the (optional) origin of the event, e.g. a hostname, etc@NonNull protected static ScheduledExecutorService executorService()
ScheduledExecutorService
that events should be fired on.ScheduledExecutorService
.public static SCMEvent.EventQueueMetrics getEventProcessingMetrics()
@Terminator public static void closeExecutorService()
@NonNull public SCMEvent.Type getType()
public long getTimestamp()
System.currentTimeMillis()
for start and units).@NonNull public Date getDate()
Date
.@NonNull public P getPayload()
@NonNull public String getOrigin()
ORIGIN_UNKNOWN
if the origin is unknown)@CheckForNull public String description()
null
if no description can be provided.@NonNull public Cause[] asCauses()
Cause
instances should probably be new instances each time, see
Cause.onAddedTo(Run)
.Cause
instances to add to any builds triggered by this event.@CheckForNull public static String originOf(@CheckForNull javax.servlet.http.HttpServletRequest req)
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).req
- the HttpServletRequest
or null
(this is to allow passing
Stapler.getCurrentRequest()
without having to check for null
)null
if the HttpServletRequest
is null.Copyright © 2016–2022. All rights reserved.