hudson.security

Class Permission

java.lang.Object

hudson.security.Permission

public final class Permission
extends Object

Permission, which represents activity that requires a security privilege.

Each permission is represented by a specific instance of Permission.

Author:

Kohsuke Kawaguchi

See Also:

Plugins in secured Jenkins

Field Summary

Fields

Modifier and Type	Field and Description
static Permission	CONFIGURE Generic configuration access.
static Permission	CREATE Generic create access.
static Permission	DELETE Generic delete access.
org.jvnet.localizer.Localizable	description Human-readable description of this permission.
boolean	enabled Whether this permission is available for use.
static Permission	FULL_CONTROL Deprecated. since 2009-01-23. Use Jenkins.ADMINISTER.
PermissionGroup	group
static PermissionGroup	GROUP
static Permission	HUDSON_ADMINISTER Deprecated. since 2009-01-23. Access Jenkins.ADMINISTER instead.
static PermissionGroup	HUDSON_PERMISSIONS Deprecated. since 2009-01-23. Access Jenkins.PERMISSIONS instead.
static Comparator<Permission>	ID_COMPARATOR Comparator that orders Permission objects based on their ID.
Permission	impliedBy Bundled Permission that also implies this permission.
String	name Human readable ID of the permission.
Class	owner
static Permission	READ Generic read access.
static Permission	UPDATE Generic update access.
static Permission	WRITE Generic write access.

Constructor Summary

Constructors

Constructor and Description
Permission(PermissionGroup group, String name, org.jvnet.localizer.Localizable description, Permission impliedBy) Deprecated. as of 1.421 Use Permission(PermissionGroup, String, Localizable, Permission, PermissionScope)
Permission(PermissionGroup group, String name, org.jvnet.localizer.Localizable description, Permission impliedBy, boolean enable) Deprecated. as of 1.421 Use Permission(PermissionGroup, String, Localizable, Permission, boolean, PermissionScope[])
Permission(PermissionGroup group, String name, org.jvnet.localizer.Localizable description, Permission impliedBy, boolean enable, PermissionScope[] scopes) Defines a new permission.
Permission(PermissionGroup group, String name, org.jvnet.localizer.Localizable description, Permission impliedBy, PermissionScope scope)
Permission(PermissionGroup group, String name, Permission impliedBy) Deprecated. since 1.257. Use Permission(PermissionGroup, String, Localizable, Permission)

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
static Permission	fromId(String id) Convert the ID representation into Permission object.
static List<Permission>	getAll() Returns all the Permissions available in the system.
boolean	getEnabled()
String	getId() Returns the string representation of this Permission, which can be converted back to Permission via the fromId(String) method.
int	hashCode()
boolean	isContainedBy(PermissionScope s) Checks if this permission is contained in the specified scope, (either directly or indirectly.)
void	setEnabled(boolean enable)
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

ID_COMPARATOR

public static final Comparator<Permission> ID_COMPARATOR

Comparator that orders Permission objects based on their ID.

owner

@NonNull
public final Class owner

group

@NonNull
public final PermissionGroup group

name

@NonNull
public final String name

Human readable ID of the permission.

This name should uniquely determine a permission among its owner class. The name must be a valid Java identifier.

The expected naming convention is something like "BrowseWorkspace".

description

@CheckForNull
public final org.jvnet.localizer.Localizable description

Human-readable description of this permission. Used as a tooltip to explain this permission, so this message should be a couple of sentences long.

If null, there will be no description text.

impliedBy

@CheckForNull
public final Permission impliedBy

Bundled Permission that also implies this permission.

This allows us to organize permissions in a hierarchy, so that for example we can say "view workspace" permission is implied by the (broader) "read" permission.

The idea here is that for most people, access control based on such broad permission bundle is good enough, and those few that need finer control can do so.

enabled

public boolean enabled

Whether this permission is available for use.

This allows us to dynamically enable or disable the visibility of permissions, so administrators can control the complexity of their permission matrix.

Since:

1.325

HUDSON_PERMISSIONS

@Deprecated
public static final PermissionGroup HUDSON_PERMISSIONS

Deprecated. since 2009-01-23. Access Jenkins.PERMISSIONS instead.

PermissionGroup for Jenkins.

HUDSON_ADMINISTER

@Deprecated
public static final Permission HUDSON_ADMINISTER

Deprecated. since 2009-01-23. Access Jenkins.ADMINISTER instead.

Permission that represents the God-like access. Equivalent of Unix root.

All permissions are eventually implied by this permission.

GROUP

public static final PermissionGroup GROUP

FULL_CONTROL

@Deprecated
public static final Permission FULL_CONTROL

Deprecated. since 2009-01-23. Use Jenkins.ADMINISTER.

Historically this was separate from HUDSON_ADMINISTER but such a distinction doesn't make sense any more, so deprecated.

READ

public static final Permission READ

Generic read access.

WRITE

public static final Permission WRITE

Generic write access.

CREATE

public static final Permission CREATE

Generic create access.

UPDATE

public static final Permission UPDATE

Generic update access.

DELETE

public static final Permission DELETE

Generic delete access.

CONFIGURE

public static final Permission CONFIGURE

Generic configuration access.

Constructor Detail

Permission

public Permission(@NonNull
                  PermissionGroup group,
                  @NonNull
                  String name,
                  @CheckForNull
                  org.jvnet.localizer.Localizable description,
                  @CheckForNull
                  Permission impliedBy,
                  boolean enable,
                  @NonNull
                  PermissionScope[] scopes)
           throws IllegalStateException

Defines a new permission.

Parameters:

group - Permissions are grouped per classes that own them. Specify the permission group created for that class. The idiom is:

 class Foo {
     private static final PermissionGroup PERMISSIONS = new PermissionGroup(Foo.class,...);
     public static final Permission ABC = new Permission(PERMISSION,...) ;
 }
 

Because of the classloading problems and the difficulty for Hudson to enumerate them, the permission constants really need to be static field of the owner class.

name - See name.

description - See description.

impliedBy - See impliedBy.

Throws:

IllegalStateException - if this permission was already defined

Permission

public Permission(@NonNull
                  PermissionGroup group,
                  @NonNull
                  String name,
                  @CheckForNull
                  org.jvnet.localizer.Localizable description,
                  @CheckForNull
                  Permission impliedBy,
                  @NonNull
                  PermissionScope scope)

Permission

@Deprecated
public Permission(@NonNull
                              PermissionGroup group,
                              @NonNull
                              String name,
                              @CheckForNull
                              org.jvnet.localizer.Localizable description,
                              @CheckForNull
                              Permission impliedBy,
                              boolean enable)

Deprecated. as of 1.421 Use Permission(PermissionGroup, String, Localizable, Permission, boolean, PermissionScope[])

Permission

@Deprecated
public Permission(@NonNull
                              PermissionGroup group,
                              @NonNull
                              String name,
                              @CheckForNull
                              org.jvnet.localizer.Localizable description,
                              @CheckForNull
                              Permission impliedBy)

Deprecated. as of 1.421 Use Permission(PermissionGroup, String, Localizable, Permission, PermissionScope)

Permission

@Deprecated
public Permission(@NonNull
                              PermissionGroup group,
                              @NonNull
                              String name,
                              @CheckForNull
                              Permission impliedBy)

Deprecated. since 1.257. Use Permission(PermissionGroup, String, Localizable, Permission)

Method Detail

isContainedBy

public boolean isContainedBy(@NonNull
                             PermissionScope s)

Checks if this permission is contained in the specified scope, (either directly or indirectly.)

getId

@NonNull
public String getId()

Returns the string representation of this Permission, which can be converted back to Permission via the fromId(String) method.

This string representation is suitable for persistence.

Returns:

ID with the following format: permissionClass.permissionName

See Also:

fromId(String)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

fromId

@CheckForNull
public static Permission fromId(@NonNull
                                              String id)

Convert the ID representation into Permission object.

Returns:

null if the conversion failed.

See Also:

getId()

toString

public String toString()

Overrides:

toString in class Object

setEnabled

public void setEnabled(boolean enable)

getEnabled

public boolean getEnabled()

getAll

@NonNull
public static List<Permission> getAll()

Returns all the Permissions available in the system.

Returns:

always non-null. Read-only.