Class 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 Detail

      • 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

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

        protected SCMHeadEvent​(@NonNull
                               SCMHeadEvent<P> src)
    • Method Detail

      • 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
      • 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:
        SCMTriggerListener, SCMTrigger.isIgnorePostCommitHooks()
      • 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
      • 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.