Package hudson.model

Interface Action

All Superinterfaces:

ModelObject

All Known Subinterfaces:

BuildBadgeAction, EnvironmentContributingAction, FoldableAction, HealthReportingAction, LabelAssignmentAction, ModelObjectWithContextMenu.ContextMenuVisibility, PermalinkProjectAction, ProminentProjectAction, Queue.QueueAction, RootAction, RunAction, RunAction2, SimpleBuildStep.LastBuildAction, UnprotectedRootAction

All Known Implementing Classes:

AboutJenkins, AbstractScmTagAction, AdministrativeMonitorsApi, AssetManager, CauseAction, CLIAction, CliLink, ConfigureLink, ConsoleLink, EnvironmentContributor.EnvVarsHtml, Fingerprinter.FingerprintAction, GlobalCloudConfiguration, GlobalSecurityConfiguration, GlobalToolConfiguration, HudsonPrivateSecurityRealm.ManageUserLinks, I18n, IdentityRootAction, InterruptedBuildAction, InvisibleAction, ManageJenkinsAction, ManagementLink, MyViewsProperty, MyViewsProperty.GlobalAction, NodesLink, OldDataMonitor.ManagementLinkImpl, ParametersAction, ParametersDefinitionProperty, PluginsLink, ReloadLink, RenameAction, ResourceDomainRootAction, Run.KeepLogBuildBadge, RunIdMigrator.UnmigrationInstruction, SCMRevisionState, SCMTrigger.BuildAction, SCMTrigger.SCMAction, ShutdownLink, StatisticsLink, SystemInfoLink, SystemLogLink, TaskAction, WebSocketAgents, WebSocketEcho, WhoAmI, WindowsInstallerLink, WorkspaceSnapshot

public interface Action
extends ModelObject

Object that contributes additional information, behaviors, and UIs to ModelObject (more specifically Actionable objects, which most interesting ModelObjects are.)

Actions added to a model object creates additional URL subspace under the parent model object, through which it can interact with users. Actions are also capable of exposing themselves to the left hand side menu of a ModelObject (for example to Project, Build, and etc.)

Some actions use the latter without the former (for example, to add a link to an external website), while others do the former without the latter (for example, to just draw some graphs in floatingBox.jelly), and still some others do both.

Views

If an action has a view named floatingBox.jelly, it will be displayed as a floating box on the top page of the target ModelObject. (For example, this is how the JUnit test result trend shows up in the project top page. See TestResultProjectAction.)

On the target ModelObject page, actions are rendered as an item in the side panel by the "/lib/hudson:actions" jelly tag, but you can override this for your action by writing action.jelly. See the "actions" tag for what the default handling is and tweak from there. One of the use cases of this is to show nested actions, like where Jenkins show the option to wipe out the workspace inside the workspace link:

 <l:task icon="icon-folder icon-md"  href="${url}/ws/" title="${%Workspace}">
   <l:task icon="icon-delete icon-md"  href="${url}/wipeOutWorkspace" title="${%Wipe Out Workspace}" />
 </l:task>
 

Persistence

Actions are often persisted as a part of Actionable (for example with Build) via XStream. In some other cases, Actions are transient and not persisted (such as when it's used with Job).

The Actionable.replaceAction(Action), Actionable.addOrReplaceAction(Action), and Actionable.removeAction(Action) methods use Object.equals(java.lang.Object) to determine whether to update or replace or remove an Action. As such, Action subclasses that provide a deep Object.equals(java.lang.Object) will assist in reducing the need for unnecessary persistence.

Author:

Kohsuke Kawaguchi

Method Summary

Modifier and Type	Method	Description
String	getDisplayName()	Gets the string to be displayed.
String	getIconFileName()	Gets the name of the icon.
String	getUrlName()	Gets the URL path name.

Method Detail

getIconFileName

@CheckForNull
String getIconFileName()

Gets the name of the icon.

Returns:

If the icon name is prefixed with "symbol-", a Jenkins Symbol will be used.

If just a file name (like "abc.gif") is returned, it will be interpreted as a file name inside /images/24x24. This is useful for using one of the stock images.

If an absolute file name that starts from '/' is returned (like "/plugin/foo/abc.gif"), then it will be interpreted as a path from the context root of Jenkins. This is useful to pick up image files from a plugin.

Finally, return null to hide it from the task list. This is normally not very useful, but this can be used for actions that only contribute floatBox.jelly and no task list item. The other case where this is useful is to avoid showing links that require a privilege when the user is anonymous.

See Also:

Jenkins Symbols, Functions.isAnonymous(), Functions.getIconFilePath(Action)

getDisplayName

@CheckForNull
String getDisplayName()

Gets the string to be displayed. The convention is to capitalize the first letter of each word, such as "Test Result".

Specified by:

getDisplayName in interface ModelObject

Returns:

Can be null in case the action is hidden.

getUrlName

@CheckForNull
String getUrlName()

Gets the URL path name.

For example, if this method returns "xyz", and if the parent object (that this action is associated with) is bound to /foo/bar/zot, then this action object will be exposed to /foo/bar/zot/xyz.

This method should return a string that's unique among other Actions.

The returned string can be an absolute URL, like "http://www.sun.com/", which is useful for directly connecting to external systems.

If the returned string starts with '/', like '/foo', then it's assumed to be relative to the context path of the Jenkins webapp.

Returns:

null if this action object doesn't need to be bound to web (when you do that, be sure to also return null from getIconFileName().

See Also:

Functions.getActionUrl(String, Action)