com.cloudbees.plugins.credentials

Class CredentialsStore

java.lang.Object

com.cloudbees.plugins.credentials.CredentialsStore

All Implemented Interfaces:

Saveable, AccessControlled

Direct Known Subclasses:

SystemCredentialsProvider.StoreImpl, UserCredentialsProvider.StoreImpl

public abstract class CredentialsStore
extends Object
implements AccessControlled, Saveable

A store of Credentials. Each CredentialsStore is associated with one and only one CredentialsProvider though a CredentialsProvider may provide multiple CredentialsStores (for example a folder scoped CredentialsProvider may provide a CredentialsStore for each folder or a user scoped CredentialsProvider may provide a CredentialsStore for each user).

Since:

1.8

Author:

Stephen Connolly

Field Summary

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Constructor and Description
CredentialsStore() Constructor that auto-detects the CredentialsProvider that this CredentialsStore is associated with by examining the outer classes until an outer class that implements CredentialsProvider is found.
CredentialsStore(Class<? extends CredentialsProvider> providerClass) Constructor for use when the CredentialsStore is not an inner class of its CredentialsProvider.

Method Summary

Modifier and Type	Method and Description
protected boolean	_isApplicable(Descriptor<?> descriptor) CredentialsStore subtypes can override this method to veto some Descriptors from being available from their store.
abstract boolean	addCredentials(Domain domain, Credentials credentials) Adds the specified Credentials within the specified Domain for this CredentialsStore.
boolean	addDomain(Domain domain, Credentials... credentials) Adds a new Domain with seed credentials.
boolean	addDomain(Domain domain, List<Credentials> credentials) Adds a new Domain with seed credentials.
void	checkPermission(Permission p) Checks if the current security principal has this permission.
ACL	getACL()
abstract ModelObject	getContext() Returns the context within which this store operates.
String	getContextDisplayName() Returns the display name of the getContext() of this CredentialsStore.
abstract List<Credentials>	getCredentials(Domain domain) Returns an unmodifiable list of credentials for the specified domain.
List<CredentialsDescriptor>	getCredentialsDescriptors() Returns the list of CredentialsDescriptor instances that are applicable within this CredentialsStore.
Domain	getDomainByName(String name) Retrieves the domain with the matching name.
List<Domain>	getDomains() Returns all the Domains that this credential provider has.
CredentialsProvider	getProvider() Returns the CredentialsProvider.
CredentialsProvider	getProviderOrDie() Returns the CredentialsProvider or dies trying.
String	getRelativeLinkTo(Domain domain) Computes the relative path from the current page to the specified domain.
String	getRelativeLinkToAction() Computes the relative path from the current page to this store.
String	getRelativeLinkToContext() Computes the relative path from the current page to this store.
Set<CredentialsScope>	getScopes() Returns the CredentialsScope instances that are applicable to this store.
CredentialsStoreAction	getStoreAction() Return the CredentialsStoreAction for this store.
abstract boolean	hasPermission(Authentication a, Permission permission) Checks if the given principle has the given permission.
boolean	hasPermission(Permission p) Checks if the current security principal has this permission.
boolean	isApplicable(Descriptor<?> descriptor) Determines if the specified Descriptor is applicable to this CredentialsStore.
boolean	isDomainsModifiable() Identifies whether this CredentialsStore supports making changes to the list of domains or whether it only supports a fixed set of domains (which may only be one domain).
abstract boolean	removeCredentials(Domain domain, Credentials credentials) Removes the specified Credentials from the specified Domain for this CredentialsStore.
boolean	removeDomain(Domain domain) Removes an existing Domain and all associated Credentials.
void	save() Persists the state of this object into XML.
abstract boolean	updateCredentials(Domain domain, Credentials current, Credentials replacement) Updates the specified Credentials from the specified Domain for this CredentialsStore with the supplied replacement.
boolean	updateDomain(Domain current, Domain replacement) Updates an existing Domain keeping the existing associated Credentials.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, hasAnyPermission

Constructor Detail

CredentialsStore

public CredentialsStore(Class<? extends CredentialsProvider> providerClass)

Constructor for use when the CredentialsStore is not an inner class of its CredentialsProvider.

Parameters:

providerClass - the CredentialsProvider class.

Since:

2.0

CredentialsStore

public CredentialsStore()

Constructor that auto-detects the CredentialsProvider that this CredentialsStore is associated with by examining the outer classes until an outer class that implements CredentialsProvider is found.

Since:

2.0

Method Detail

getProviderOrDie

@NonNull
public final CredentialsProvider getProviderOrDie()

Returns the CredentialsProvider or dies trying.

Returns:

the CredentialsProvider

Since:

2.0

getProvider

@Nullable
public final CredentialsProvider getProvider()

Returns the CredentialsProvider.

Returns:

the CredentialsProvider (may be null if the admin has removed the provider from the ExtensionList)

Since:

2.0

getScopes

@Nullable
public final Set<CredentialsScope> getScopes()

Returns the CredentialsScope instances that are applicable to this store.

Returns:

the CredentialsScope instances that are applicable to this store or null if the store instance is no longer enabled.

Since:

2.1.5

getContext

@NonNull
public abstract ModelObject getContext()

Returns the context within which this store operates. Credentials in this store will be available to child contexts (unless CredentialsScope.SYSTEM is valid for the store) but will not be available to parent contexts.

Returns:

the context within which this store operates.

hasPermission

public abstract boolean hasPermission(@NonNull
                                      Authentication a,
                                      @NonNull
                                      Permission permission)

Checks if the given principle has the given permission.

Specified by:

hasPermission in interface AccessControlled

Parameters:

a - the principle.

permission - the permission.

Returns:

false if the user doesn't have the permission.

getACL

public ACL getACL()

Specified by:

getACL in interface AccessControlled

checkPermission

public final void checkPermission(@NonNull
                                  Permission p)

Checks if the current security principal has this permission.

Note: This is just a convenience function.

Specified by:

checkPermission in interface AccessControlled

Throws:

AccessDeniedException - if the user doesn't have the permission.

hasPermission

public final boolean hasPermission(@NonNull
                                   Permission p)

Checks if the current security principal has this permission.

Specified by:

hasPermission in interface AccessControlled

Returns:

false if the user doesn't have the permission.

getDomains

@NonNull
public List<Domain> getDomains()

Returns all the Domains that this credential provider has. Most implementers of CredentialsStore will probably want to override this method.

Returns:

the list of domains.

getDomainByName

@CheckForNull
public Domain getDomainByName(@CheckForNull
                                            String name)

Retrieves the domain with the matching name.

Parameters:

name - the name (or null to match Domain.global() as that is the domain with a null name)

Returns:

the domain or null if there is no domain with the supplied name.

Since:

2.1.1

isDomainsModifiable

public final boolean isDomainsModifiable()

Identifies whether this CredentialsStore supports making changes to the list of domains or whether it only supports a fixed set of domains (which may only be one domain).

Note: in order for implementations to return true all of the following methods must be overridden:

• getDomains()
• addDomain(Domain, java.util.List)
• removeDomain(Domain)
• updateDomain(Domain, Domain)

Returns:

true iff addDomain(Domain, List) addDomain(Domain, Credentials...), removeDomain(Domain) and updateDomain(Domain, Domain) are expected to work

getCredentials

@NonNull
public abstract List<Credentials> getCredentials(@NonNull
                                                          Domain domain)

Returns an unmodifiable list of credentials for the specified domain.

Parameters:

domain - the domain.

Returns:

the possibly empty (e.g. for an unknown Domain) unmodifiable list of credentials for the specified domain.

addDomain

public final boolean addDomain(@NonNull
                               Domain domain,
                               Credentials... credentials)
                        throws IOException

Adds a new Domain with seed credentials.

Parameters:

domain - the domain.

credentials - the initial credentials with which to populate the domain.

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

addDomain

public boolean addDomain(@NonNull
                         Domain domain,
                         List<Credentials> credentials)
                  throws IOException

Adds a new Domain with seed credentials.

Parameters:

domain - the domain.

credentials - the initial credentials with which to populate the domain.

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

removeDomain

public boolean removeDomain(@NonNull
                            Domain domain)
                     throws IOException

Removes an existing Domain and all associated Credentials.

Parameters:

domain - the domain.

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

updateDomain

public boolean updateDomain(@NonNull
                            Domain current,
                            @NonNull
                            Domain replacement)
                     throws IOException

Updates an existing Domain keeping the existing associated Credentials.

Parameters:

current - the domain to update.

replacement - the new replacement domain.

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

addCredentials

public abstract boolean addCredentials(@NonNull
                                       Domain domain,
                                       @NonNull
                                       Credentials credentials)
                                throws IOException

Adds the specified Credentials within the specified Domain for this CredentialsStore.

Parameters:

domain - the domain.

credentials - the credentials

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

removeCredentials

public abstract boolean removeCredentials(@NonNull
                                          Domain domain,
                                          @NonNull
                                          Credentials credentials)
                                   throws IOException

Removes the specified Credentials from the specified Domain for this CredentialsStore.

Parameters:

domain - the domain.

credentials - the credentials

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

updateCredentials

public abstract boolean updateCredentials(@NonNull
                                          Domain domain,
                                          @NonNull
                                          Credentials current,
                                          @NonNull
                                          Credentials replacement)
                                   throws IOException

Updates the specified Credentials from the specified Domain for this CredentialsStore with the supplied replacement.

Parameters:

domain - the domain.

current - the credentials to update.

replacement - the new replacement credentials.

Returns:

true if the CredentialsStore was modified.

Throws:

IOException - if the change could not be persisted.

isApplicable

public final boolean isApplicable(Descriptor<?> descriptor)

Determines if the specified Descriptor is applicable to this CredentialsStore.

The default implementation consults the DescriptorVisibilityFilters, _isApplicable(Descriptor) and the getProviderOrDie().

Parameters:

descriptor - the Descriptor to check.

Returns:

true if the supplied Descriptor is applicable in this CredentialsStore

Since:

2.0

_isApplicable

protected boolean _isApplicable(Descriptor<?> descriptor)

CredentialsStore subtypes can override this method to veto some Descriptors from being available from their store. This is often useful when you are building a custom store that holds a specific type of credentials or where you want to limit the number of choices given to the users.

Parameters:

descriptor - the Descriptor to check.

Returns:

true if the supplied Descriptor is applicable in this CredentialsStore

Since:

2.0

getCredentialsDescriptors

public final List<CredentialsDescriptor> getCredentialsDescriptors()

Returns the list of CredentialsDescriptor instances that are applicable within this CredentialsStore.

Returns:

the list of CredentialsDescriptor instances that are applicable within this CredentialsStore.

Since:

2.0

getRelativeLinkToContext

@CheckForNull
public String getRelativeLinkToContext()

Computes the relative path from the current page to this store.

Returns:

the relative path from the current page or null

Since:

2.0

getRelativeLinkToAction

@CheckForNull
public String getRelativeLinkToAction()

Computes the relative path from the current page to this store.

Returns:

the relative path from the current page or null

Since:

2.0

getRelativeLinkTo

@CheckForNull
public String getRelativeLinkTo(Domain domain)

Computes the relative path from the current page to the specified domain.

Parameters:

domain - the domain

Returns:

the relative path from the current page or null

Since:

2.0

getContextDisplayName

public final String getContextDisplayName()

Returns the display name of the getContext() of this CredentialsStore. The default implementation can handle both Item and ItemGroup as long as these are accessible from Jenkins, and User. If the CredentialsStore provides an alternative getContext() that is outside of the normal tree then that implementation is responsible for overriding this method to produce the correct display name.

Returns:

the display name.

Since:

2.0

getStoreAction

@Nullable
public CredentialsStoreAction getStoreAction()

Return the CredentialsStoreAction for this store. The action will be displayed as a sub-item of the ViewCredentialsAction. Return null if this store will take control of displaying its action (which will be the case for legacy implementations)

Returns:

the CredentialsStoreAction for this store to be rendered in ViewCredentialsAction or null for old implementations compiled against pre 2.0 versions of credentials plugin.

Since:

2.0

save

public void save()
          throws IOException

Persists the state of this object into XML. Default implementation delegates to getContext() if it implements Saveable otherwise dropping back to a no-op.

Specified by:

save in interface Saveable

Throws:

IOException

Since:

2.1.9

See Also:

Saveable.save()