Package 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:

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

  • Field Details

  • Constructor Details

    • 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 Details

    • 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 jakarta.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.getCurrentRequest2() without having to check for null)
      Returns:
      the origin of the event or null if the HttpServletRequest is null.
      Since:
      TODO

    • originOf

      @CheckForNull @Deprecated public static String originOf(@CheckForNull javax.servlet.http.HttpServletRequest req)
      Deprecated.
      use originOf(HttpServletRequest)
      Since:
      2.0.3