Package jenkins.scm.api

Class 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

    • Constructor Detail

      • 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

        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

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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode 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