Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[FIXED JENKINS-40138] Remove SCMHead.getAction(...)
- Not actually removing, just making the methods stubs and annotating as @restricted(DoNotUse) so that binary compatibility is retained
  • Loading branch information
stephenc committed Dec 1, 2016
1 parent 7873d16 commit d6bd43a
Show file tree
Hide file tree
Showing 27 changed files with 437 additions and 323 deletions.
76 changes: 27 additions & 49 deletions src/main/java/jenkins/scm/api/SCMHead.java
Expand Up @@ -28,43 +28,38 @@
import hudson.ExtensionList;
import hudson.ExtensionPoint;
import hudson.model.Action;
import hudson.model.Actionable;
import hudson.model.Item;
import hudson.model.ItemGroup;
import hudson.model.TaskListener;
import hudson.util.AlternativeUiTextProvider;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;
import jenkins.model.TransientActionFactory;
import jenkins.scm.api.actions.ChangeRequestAction;
import jenkins.scm.api.mixin.SCMHeadMixin;
import org.kohsuke.accmod.Restricted;
import org.kohsuke.accmod.restrictions.DoNotUse;
import org.kohsuke.stapler.export.Exported;
import org.kohsuke.stapler.export.ExportedBean;

/**
* Represents a named SCM branch, tag or mainline.
* 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 {@link String} around. Each {@link SCMSource} implementation may want to have their own
* subclasses in order assist to differentiating between different classes of head via the {@link SCMHeadMixin}
* interfaces.
*
* @author Stephen Connolly
*/
@ExportedBean
public class SCMHead implements Comparable<SCMHead>, Serializable {
public class SCMHead implements SCMHeadMixin {

/**
* Replaceable pronoun of that points to a {@link SCMHead}. Defaults to {@code null} depending on the context.
*
* @since FIXME
* @since 2.0
*/
public static final AlternativeUiTextProvider.Message<SCMHead> PRONOUN
= new AlternativeUiTextProvider.Message<SCMHead>();

/**
* Our logger.
*/
private static final Logger LOGGER = Logger.getLogger(SCMHead.class.getName());

/**
* Ensure consistent serialization.
*/
Expand All @@ -86,11 +81,7 @@ public SCMHead(@NonNull String name) {
this.name = name;
}

/**
* Returns the name.
*
* @return the name.
*/
@Override
@Exported
@NonNull
public String getName() {
Expand All @@ -101,7 +92,7 @@ public String getName() {
* Get the term used in the UI to represent this kind of {@link SCMHead}. Must start with a capital letter.
*
* @return the term or {@code null} to fall back to the calling context's default.
* @since FIXME
* @since 2.0
*/
@CheckForNull
public String getPronoun() {
Expand Down Expand Up @@ -155,47 +146,34 @@ public String toString() {
}

/**
* Gets all actions used to decorate the behavior of this branch.
* May be overridden to create a new list, perhaps with additions.
* @return a list of all actions associated with this branch (by default, an unmodifiable list searching {@link TransientActionFactory}s)
* @see Actionable#getAllActions
* Returns an empty list.
* @return an empty list
* @since 1.1
* @deprecated this was added to the API in error. Retained for backwards binary compatibility only. Use
* {@link SCMSource#fetchActions(SCMHead, SCMHeadEvent, TaskListener)} to get the actions associated with a
* {@link SCMHead}
*/
@Restricted(DoNotUse.class)
@Deprecated
@NonNull
@Exported(name="actions")
public List<? extends Action> getAllActions() {
List<Action> actions = new ArrayList<Action>();
for (TransientActionFactory<?> taf : ExtensionList.lookup(TransientActionFactory.class)) {
if (taf.type().isInstance(this)) {
try {
actions.addAll(createFor(taf));
} catch (Exception e) {
LOGGER.log(Level.SEVERE, "Could not load actions from " + taf + " for " + this, e);
}
}
}
return Collections.unmodifiableList(actions);
}
private <T> Collection<? extends Action> createFor(TransientActionFactory<T> taf) {
return taf.createFor(taf.type().cast(this));
return Collections.emptyList();
}

/**
* Gets a specific action used to decorate the behavior of this branch.
* May be overridden but suffices to override {@link #getAllActions}.
* Returns {@code null}.
* @param <T> a desired action type to query, such as {@link ChangeRequestAction}
* @param type type token
* @return an instance of that action interface (by default, filters {@link #getAllActions})
* @see Actionable#getAction(Class)
* @return {@code null}
* @since 1.1
* @deprecated this was added to the API in error. Retained for backwards binary compatibility only. Use
* {@link SCMSource#fetchActions(SCMHead, SCMHeadEvent, TaskListener)} to get the actions associated with a
* {@link SCMHead}
*/
@Restricted(DoNotUse.class)
@Deprecated
@CheckForNull
public <T extends Action> T getAction(@NonNull Class<T> type) {
for (Action action : getAllActions()) {
if (type.isInstance(action)) {
return type.cast(action);
}
}
return null;
}

Expand Down
61 changes: 12 additions & 49 deletions src/main/java/jenkins/scm/api/actions/ChangeRequestAction.java
Expand Up @@ -26,98 +26,61 @@

import edu.umd.cs.findbugs.annotations.CheckForNull;
import hudson.model.InvisibleAction;
import hudson.model.TaskListener;
import java.io.Serializable;
import java.net.URL;
import jenkins.scm.api.SCMHead;
import jenkins.scm.api.SCMHeadObserver;
import jenkins.scm.api.SCMRevision;
import jenkins.scm.api.SCMSource;
import jenkins.scm.api.metadata.ContributorMetadataAction;
import jenkins.scm.api.metadata.ObjectMetadataAction;
import jenkins.scm.api.mixin.ChangeRequestSCMHead;
import org.kohsuke.accmod.Restricted;
import org.kohsuke.accmod.restrictions.DoNotUse;
import org.kohsuke.accmod.restrictions.NoExternalUse;
import org.kohsuke.stapler.export.Exported;
import org.kohsuke.stapler.export.ExportedBean;

/**
* Indicates that an {@link SCMHead} represents a registered proposed change, such as a pull request.
* <p>Intended to capture concepts common to popular code review systems and which might warrant generic UI representation.
* Fields may be null in case the corresponding concept does not exist in the system being represented.
* <p>Should be restricted to those aspects of a change which are either immutable
* or otherwise not affected by changes to the head {@link SCMRevision}
* (as opposed to, say, mergeability status).
* Should also be restricted to short metadata which can be quickly retrieved during {@link SCMSource#retrieve(SCMHeadObserver, TaskListener)}.
* @see SCMHead#getAllActions
* Class retained for binary compatibility only for instances upgrading and deserializing data from disk.
* @since 1.1
* @deprecated use {@link ContributorMetadataAction} for the author information, {@link ObjectMetadataAction} for the
* title and links and {@link ChangeRequestSCMHead#getId()} and
* {@link ChangeRequestSCMHead#getTarget()}
*/
@ExportedBean
@Restricted(DoNotUse.class)
@Deprecated
public abstract class ChangeRequestAction extends InvisibleAction implements Serializable {

private static final long serialVersionUID = 1L;

/**
* Identifier of this change request.
* Expected to be unique among requests coming from a given {@link SCMSource}.
* @return an ID of some kind, such as a pull request number (decimal) or a Gerrit change ID
*/
@Exported
@CheckForNull
public String getId() {
return null;
}

/**
* Link to web representation of change.
* @return an HTTP(S) permalink
*/
@Exported
@CheckForNull
public URL getURL() {
return null;
}

/**
* Display title.
* @return a summary message
*/
@Exported
@CheckForNull
public String getTitle() {
return null;
}

/**
* Username of author of the proposed change.
* @return a user login name or other unique user identifier
*/
@Exported
@CheckForNull
public String getAuthor() {
return null;
}

/**
* Human name of author of proposed change.
* @return First M. Last, etc.
*/
@Exported
@CheckForNull
public String getAuthorDisplayName() {
return null;
}

/**
* Email address of author of proposed change.
* @return a valid email address
*/
@Exported
@CheckForNull
public String getAuthorEmail() {
return null;
}

/**
* Branch to which this change would be merged or applied if it were accepted.
* @return a “target” or “base” branch
*/
@Exported
@CheckForNull
public SCMHead getTarget() {
return null;
Expand Down
31 changes: 31 additions & 0 deletions src/main/java/jenkins/scm/api/actions/package-info.java
@@ -0,0 +1,31 @@
/*
* The MIT License
*
* Copyright (c) 2016 CloudBees, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*
*/

/**
* Do not use.
*
* @deprecated Do not use any of these classes they were added in error, retained for binary compatibility only
*/
package jenkins.scm.api.actions;
@@ -1,7 +1,7 @@
/*
* The MIT License
*
* Copyright 2016 CloudBees, Inc.
* Copyright (c) 2016 CloudBees, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
Expand All @@ -22,7 +22,7 @@
* THE SOFTWARE.
*/

package jenkins.scm.api.actions;
package jenkins.scm.api.metadata;

import edu.umd.cs.findbugs.annotations.CheckForNull;
import edu.umd.cs.findbugs.annotations.NonNull;
Expand Down
@@ -1,7 +1,7 @@
/*
* The MIT License
*
* Copyright 2016 CloudBees, Inc.
* Copyright (c) 2016 CloudBees, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
Expand All @@ -22,13 +22,13 @@
* THE SOFTWARE.
*/

package jenkins.scm.api.actions;
package jenkins.scm.api.metadata;

import edu.umd.cs.findbugs.annotations.CheckForNull;
import hudson.model.InvisibleAction;
import hudson.model.TaskListener;
import java.io.Serializable;
import jenkins.scm.api.ChangeRequestSCMHead;
import jenkins.scm.api.mixin.ChangeRequestSCMHead;
import jenkins.scm.api.SCMHead;
import jenkins.scm.api.SCMHeadEvent;
import jenkins.scm.api.SCMNavigator;
Expand Down
@@ -1,7 +1,7 @@
/*
* The MIT License
*
* Copyright 2016 CloudBees, Inc.
* Copyright (c) 2016 CloudBees, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
Expand All @@ -22,7 +22,7 @@
* THE SOFTWARE.
*/

package jenkins.scm.api.actions;
package jenkins.scm.api.metadata;

import edu.umd.cs.findbugs.annotations.CheckForNull;
import hudson.model.InvisibleAction;
Expand Down
44 changes: 44 additions & 0 deletions src/main/java/jenkins/scm/api/metadata/package-info.java
@@ -0,0 +1,44 @@
/*
* The MIT License
*
* Copyright (c) 2016 CloudBees, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*
*/

/**
* The {@linkplain hudson.model.InvisibleAction metadata} classes that can be used to report metadata about
* {@linkplain jenkins.scm.api.SCMNavigator navigator}, {@linkplain jenkins.scm.api.SCMSource source},
* {@linkplain jenkins.scm.api.SCMHead head} and {@linkplain jenkins.scm.api.SCMRevision revisions} objects via the
* {@link jenkins.scm.api.SCMNavigator#fetchActions(jenkins.scm.api.SCMNavigatorOwner, jenkins.scm.api.SCMNavigatorEvent, hudson.model.TaskListener) SCMNavigator.fetchActions(...)},
* {@link jenkins.scm.api.SCMSource#fetchActions(jenkins.scm.api.SCMSourceEvent, hudson.model.TaskListener) SCMSource.fetchActions(...)},
* {@link jenkins.scm.api.SCMSource#fetchActions(jenkins.scm.api.SCMHead, jenkins.scm.api.SCMHeadEvent, hudson.model.TaskListener) SCMSource.fetchActions(SCMHead, ...)}
* and
* {@link jenkins.scm.api.SCMSource#fetchActions(jenkins.scm.api.SCMRevision, jenkins.scm.api.SCMHeadEvent, hudson.model.TaskListener) SCMSource.fetchActions(SCMRevision, ...)}
* methods respectively.
*
* @see hudson.model.InvisibleAction
* @see jenkins.scm.api.SCMNavigator#fetchActions(jenkins.scm.api.SCMNavigatorOwner, jenkins.scm.api.SCMNavigatorEvent, hudson.model.TaskListener)
* @see jenkins.scm.api.SCMSource#fetchActions(jenkins.scm.api.SCMSourceEvent, hudson.model.TaskListener)
* @see jenkins.scm.api.SCMSource#fetchActions(jenkins.scm.api.SCMHead, jenkins.scm.api.SCMHeadEvent, hudson.model.TaskListener)
* @see jenkins.scm.api.SCMSource#fetchActions(jenkins.scm.api.SCMRevision, jenkins.scm.api.SCMHeadEvent, hudson.model.TaskListener)
* @since 2.0
*/
package jenkins.scm.api.metadata;

0 comments on commit d6bd43a

Please sign in to comment.