jenkins.scm.api

Class SCMHead

java.lang.Object

jenkins.scm.api.SCMHead

All Implemented Interfaces:

Serializable, Comparable<SCMHead>, SCMHeadMixin

@ExportedBean
public class SCMHead
extends Object
implements SCMHeadMixin

Represents a named SCM branch, change request, tag or mainline. This class is intended to be used as a typed key rather than passing a String around. Each SCMSource implementation may want to have their own subclasses in order assist to differentiating between different classes of head via the SCMHeadMixin interfaces.

Please note the equality contract for SCMHeadMixin implementations: Two SCMHeadMixin implementations are equal if and only if:

• They both are the same class
• They both have the same SCMHeadMixin.getName()
• For each implemented SCMHeadMixin sub-interface, they both return the same values from all Java Bean property getters declared on the sub-interface. Thus, for example ChangeRequestSCMHead implementations are only considered equal if ChangeRequestSCMHead.getId() and ChangeRequestSCMHead.getTarget() are also equal

The contract for Object.hashCode() is:

• Object.hashCode() for a SCMHeadMixin implementation must be equal to the String.hashCode() of SCMHeadMixin.getName()

The equals(Object) and hashCode() methods enforce the above requirements and are final.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SCMHead.HeadByItem Means of locating a head given an item.

Nested classes/interfaces inherited from interface jenkins.scm.api.mixin.SCMHeadMixin

SCMHeadMixin.Equality

Field Summary

Fields

Modifier and Type	Field and Description
static AlternativeUiTextProvider.Message<SCMHead>	PRONOUN Replaceable pronoun of that points to a SCMHead.

Constructor Summary

Constructors

Constructor and Description
SCMHead(String name) Constructor.

Method Summary

Modifier and Type	Method and Description
int	compareTo(SCMHead o)
boolean	equals(Object o) Indicates whether some other object is "equal to" this one.
<T extends Action> T	getAction(Class<T> type) Deprecated. this was added to the API in error. Retained for backwards binary compatibility only. Use SCMSource.fetchActions(SCMHead, SCMHeadEvent, TaskListener) to get the actions associated with a SCMHead
List<? extends Action>	getAllActions() Deprecated. this was added to the API in error. Retained for backwards binary compatibility only. Use SCMSource.fetchActions(SCMHead, SCMHeadEvent, TaskListener) to get the actions associated with a SCMHead
String	getName() Returns the name.
SCMHeadOrigin	getOrigin() Returns the origin of the head.
String	getPronoun() Get the term used in the UI to represent this kind of SCMHead.
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PRONOUN

public static final AlternativeUiTextProvider.Message<SCMHead> PRONOUN

Replaceable pronoun of that points to a SCMHead. Defaults to null depending on the context.

Since:

2.0

Constructor Detail

SCMHead

public SCMHead(@NonNull
               String name)

Constructor.

Parameters:

name - the name.

Method Detail

getName

@Exported
 @NonNull
public String getName()

Returns the name.

Specified by:

getName in interface SCMHeadMixin

Returns:

the name.

getOrigin

@Exported
 @NonNull
public SCMHeadOrigin getOrigin()

Returns the origin of the head.

• For centralized version control systems such as Subversion, CVS, etc the return value will always be SCMHeadOrigin.DEFAULT.
• For distributed version control systems such as Git, Mercurial etc the return value may have other values.
• For centralized distributed version control systems such as GitHub, Bitbucket, etc the return values may be restricted to SCMHeadOrigin.DEFAULT or instances of SCMHeadOrigin.Fork.

Specified by:

getOrigin in interface SCMHeadMixin

Returns:

the origin of the head or SCMHeadOrigin.DEFAULT if there can only ever be one origin.

getPronoun

@CheckForNull
public String getPronoun()

Get the term used in the UI to represent this kind of SCMHead. Must start with a capital letter.

Returns:

the term or null to fall back to the calling context's default.

Since:

2.0

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. Two SCMHeadMixin implementations are equal if and only if:

• They both are the same class
• They both have the same SCMHeadMixin.getName()
• For each implemented SCMHeadMixin sub-interface, they both return the same values from all Java Bean property getters declared on the sub-interface. Thus, for example ChangeRequestSCMHead implementations are only considered equal if ChangeRequestSCMHead.getId() and ChangeRequestSCMHead.getTarget() are also equal

By way of example, any implementation of ChangeRequestSCMHead will have their equals behave like so:

     public static class MyChangeRequestSCMHead extends SCMHead implements ChangeRequestSCMHead {
         //...
         // this method is implemented for you, but if you had to write it this is what you would
         // have to write
         public boolean equals(Object o) {
             if (!super.equals(o)) {
                 return false;
             }
             // can only be equal if they are the same class
             MyChangeRequestSCMHead that = (MyChangeRequestSCMHead)o;
             // because we implement ChangeRequestSCMHead and ChangeRequestSCMHead has a getId() method
             String id1 = this.getId();
             String id2 = that.getId();
             if (id1 == null ? id2 != null : !id1.equals(id2)) {
                 return false;
             }
             // because we implement ChangeRequestSCMHead and ChangeRequestSCMHead has a getTarget() method
             SCMHead t1 = this.getTarget();
             SCMHead t2 = that.getTarget();
             if (t1 == null ? t2 != null : !t1.equals(t2)) {
                 return false;
             }
             // we do not implement any other interfaces extending SCMHeadMixin, so we must be equal
             return true;
         }
     }
 

Overrides:

equals in class Object

Parameters:

o - the object to compare with.

Returns:

true if and only if the two objects are equal.

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(SCMHead o)

Specified by:

compareTo in interface Comparable<SCMHead>

toString

public String toString()

Overrides:

toString in class Object

getAllActions

@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
 @Deprecated
 @NonNull
public List<? extends Action> getAllActions()

Deprecated. this was added to the API in error. Retained for backwards binary compatibility only. Use SCMSource.fetchActions(SCMHead, SCMHeadEvent, TaskListener) to get the actions associated with a SCMHead

Returns an empty list.

Returns:

an empty list

Since:

1.1

getAction

@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
 @Deprecated
 @CheckForNull
public <T extends Action> T getAction(@NonNull
                                                                                                                                    Class<T> type)

Deprecated. this was added to the API in error. Retained for backwards binary compatibility only. Use SCMSource.fetchActions(SCMHead, SCMHeadEvent, TaskListener) to get the actions associated with a SCMHead

Returns null.

Type Parameters:

T - a desired action type to query, such as ChangeRequestAction

Parameters:

type - type token

Returns:

null

Since:

1.1