Package 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

  • Constructor Details

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

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

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