hudson.model.Action Maven / Gradle / Ivy
Show all versions of hudson-core Show documentation
/*******************************************************************************
*
* Copyright (c) 2004-2009 Oracle Corporation.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*
* Kohsuke Kawaguchi, Michael B. Donohue
*
*
*******************************************************************************/
package hudson.model;
import hudson.tasks.test.TestResultProjectAction;
/**
* Object that contributes additional information, behaviors, and UIs to
* {@link ModelObject} (more specifically {@link Actionable} objects, which most
* interesting {@link ModelObject}s are.)
*
* {@link Action}s added to a model object creates additional URL subspace
* under the parent model object, through which it can interact with users.
* {@link Action}s are also capable of exposing themselves to the left hand side
* menu of a {@link ModelObject} (for example to {@link Project}, {@link 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.
*
*
If an action has a view named floatingBox.jelly, it will be
* displayed as a floating box on the top page of the target
* {@link ModelObject}. (For example, this is how the JUnit test result trend
* shows up in the project top page. See {@link TestResultProjectAction}.
*
*
Persistence
Actions are often persisted as a part of
* {@link Actionable} (for example with {@link Build}) via XStream. In some
* other cases, {@link Action}s are transient and not persisted (such as when
* it's used with {@link Job}).
*
* @author Kohsuke Kawaguchi
*/
public interface Action extends ModelObject {
/**
* Gets the file name of the icon.
*
* @return If just a file name (like "abc.png") 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.png'), then it will be
* interpreted as a path from the context root of Hudson. 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 Hudson#isAdmin()
*/
String getIconFileName();
/**
* Gets the string to be displayed.
*
* The convention is to capitalize the first letter of each word, such as
* "Test Result".
*/
String getDisplayName();
/**
* 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
* {@link Action}s.
*
*
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 Hudson webapp.
*
* @return null if this action object doesn't need to be bound to web (when
* you do that, be sure to also return null from {@link #getIconFileName()}.
*/
String getUrlName();
}