AS400Credential

java.lang.Object
- com.ibm.as400.security.auth.AS400Credential

All Implemented Interfaces:

AS400SwappableCredential, java.io.Serializable

Direct Known Subclasses:

ProfileHandleCredential, ProfileTokenCredential
```
public abstract class AS400Credential
extends java.lang.Object
implements java.io.Serializable, AS400SwappableCredential
```
Provides an abstract superclass for representations of IBM i system security-related attributes.
Credentials may be used for authenticating to system services, or may simply enable certain actions to be performed.
Typical IBM i system credentials include, but are not limited to, profile tokens.
This abstract class must be subclassed to provide specific credential functions. Each subclass can contain credential data that may be security-sensitive. It is the responsibility of each class to provide appropriate access controls to sensitive data.
AS400Credential objects generate the following events:
- AS400CredentialEvent
  - CR_CREATE
  - CR_DESTROY
  - CR_REFRESH
  - CR_SWAP
- PropertyChangeEvent
- VetoableChangeEvent
See Also:
Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CR_AUTO_REFRESH_FAILED` ID indicating that automatic refresh has failed.
`static int`	`CR_AUTO_REFRESH_NOT_VALID` ID indicating that automatic refresh is not a valid operation.
`static int`	`CR_AUTO_REFRESH_STARTED` ID indicating that automatic refresh is started.
`static int`	`CR_AUTO_REFRESH_STOPPED` ID indicating that automatic refresh is stopped.

Constructor Summary

Constructors
Constructor and Description

AS400Credential()
Constructs an AS400Credential object.

Constructors
Constructor and Description
`AS400Credential()` Constructs an AS400Credential object.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addCredentialListener(AS400CredentialListener listener)` Adds a listener to receive credential events.
`void`	`addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Adds a PropertyChangeListener.
`void`	`addVetoableChangeListener(java.beans.VetoableChangeListener listener)` Adds a VetoableChangeListener.
`java.lang.String[]`	`basicAuthenticationPrompt()` Returns text that can be displayed to prompt for the basic user and password information used to initialize the credential.
`void`	`destroy()` Destroys the credential by destroying or clearing sensitive information for the credential.
`protected void`	`finalize()` Called when garbage collection determines that there are no more references to the object.
`java.lang.Throwable`	`getAutomaticRefreshFailure()` Returns the exception resulting from failure of the most recent auto-refresh attempt.
`int`	`getAutomaticRefreshStatus()` Returns the current status of automatic refresh activity for the credential.
`AS400Principal`	`getPrincipal()` Returns the AS400Principal associated with the credential.
`AS400`	`getSystem()` Returns the AS400 system object for the credential.
`int`	`getTimeToExpiration()` Returns the number of seconds before the credential is due to expire.
`boolean`	`isCurrent()` Indicates if a timed credential is still considered valid for authenticating to associated IBM i system services or performing related actions.
`boolean`	`isDestroyed()` Indicates if the credential has been destroyed.
`boolean`	`isPrivate()` Indicates whether the credential is considered private.
`boolean`	`isRenewable()` Indicates if the credential can be refreshed.
`boolean`	`isTimed()` Indicates if the credential will expire based on time.
`void`	`refresh()` Updates or extends the validity period for the credential.
`void`	`removeCredentialListener(AS400CredentialListener listener)` Removes the specified listener from the internal list.
`void`	`removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Removes the specified listener from the internal list.
`void`	`removeVetoableChangeListener(java.beans.VetoableChangeListener listener)` Removes the specified listener from the internal list.
`void`	`setPrincipal(AS400Principal p)` Sets the principal associated with the credential.
`void`	`setSystem(AS400 system)` Sets the AS400 system object for the credential.
`void`	`startAutomaticRefresh(int refreshInterval, int maxRefreshes)` Starts automatic refresh for the credential.
`void`	`stopAutomaticRefresh()` Stops and clears the state of any automatic refresh in progress for the credential.
`void`	`swap()` Attempts to swap the current thread identity based on this credential.
`AS400Credential`	`swap(boolean returnCredential)` Attempts to swap the current thread identity based on this credential.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CR_AUTO_REFRESH_FAILED
```
public static final int CR_AUTO_REFRESH_FAILED
```
    ID indicating that automatic refresh has failed.
    
    See Also:
    Constant Field Values
  - CR_AUTO_REFRESH_NOT_VALID
```
public static final int CR_AUTO_REFRESH_NOT_VALID
```
    ID indicating that automatic refresh is not a valid operation.
    
    See Also:
    Constant Field Values
  - CR_AUTO_REFRESH_STARTED
```
public static final int CR_AUTO_REFRESH_STARTED
```
    ID indicating that automatic refresh is started.
    
    See Also:
    Constant Field Values
  - CR_AUTO_REFRESH_STOPPED
```
public static final int CR_AUTO_REFRESH_STOPPED
```
    ID indicating that automatic refresh is stopped.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - AS400Credential
```
public AS400Credential()
```
    Constructs an AS400Credential object.
- Method Detail
  - addCredentialListener
```
public void addCredentialListener(AS400CredentialListener listener)
```
    Adds a listener to receive credential events.
    
    Parameters:
    listener - The AS400CredentialListener.
    See Also:
    removeCredentialListener(com.ibm.as400.security.auth.AS400CredentialListener)
  - addPropertyChangeListener
```
public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
```
    Adds a PropertyChangeListener.
    The specified listener's propertyChange method will be called each time the value of a bound property is changed.
    
    Parameters:
    listener - The PropertyChangeListener.
    See Also:
    removePropertyChangeListener(java.beans.PropertyChangeListener)
  - addVetoableChangeListener
```
public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
```
    Adds a VetoableChangeListener.
    The specified listener's vetoableChange method will be called each time the value of a constrained property is changed.
    
    Parameters:
    listener - The VetoableChangeListener.
    See Also:
    removeVetoableChangeListener(java.beans.VetoableChangeListener)
  - basicAuthenticationPrompt
```
public java.lang.String[] basicAuthenticationPrompt()
```
    Returns text that can be displayed to prompt for the basic user and password information used to initialize the credential.
    
    Returns:
    An array of two Strings. The first string is the text to prompt for the user name; the second is the text to prompt for the password.
  - destroy
```
public void destroy()
             throws AS400SecurityException
```
    Destroys the credential by destroying or clearing sensitive information for the credential.
    
    Throws:
    
    AS400SecurityException - If an IBM i system security or authentication error occurs.
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Called when garbage collection determines that there are no more references to the object.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable - If an error occurs.
  - getAutomaticRefreshFailure
```
public java.lang.Throwable getAutomaticRefreshFailure()
```
    Returns the exception resulting from failure of the most recent auto-refresh attempt.
    Available when the automatic refresh status is CR_AUTO_REFRESH_FAILED.
    
    Returns:
    The exception; null if not available.
    See Also:
    getAutomaticRefreshStatus()
  - getAutomaticRefreshStatus
```
public int getAutomaticRefreshStatus()
```
    Returns the current status of automatic refresh activity for the credential.
    Possible identifiers are defined as fields on this class:
    - CR_AUTO_REFRESH_STARTED
    - CR_AUTO_REFRESH_STOPPED
    - CR_AUTO_REFRESH_FAILED
    - CR_AUTO_REFRESH_NOT_VALID
    Automatic refresh is not valid if the credential cannot be programmatically updated or extended, or if the associated AS400 system object is not set or not allowed to start additional threads.
    If automatic refresh fails, the associated exception is available from the getAutomaticRefreshFailure() method.
    Returns:
    The integer identifier representing the status.
    See Also:
    startAutomaticRefresh(int, int), stopAutomaticRefresh(), getAutomaticRefreshFailure()
  - getPrincipal
```
public AS400Principal getPrincipal()
```
    Returns the AS400Principal associated with the credential.
    
    Returns:
    The principal associated with the credential; null if not assigned.
  - getSystem
```
public AS400 getSystem()
```
    Returns the AS400 system object for the credential.
    
    Returns:
    The AS400 system for the credential; null if not assigned.
  - getTimeToExpiration
```
public int getTimeToExpiration()
                        throws AS400SecurityException
```
    Returns the number of seconds before the credential is due to expire.
    
    Returns:
    The number of seconds before expiration; zero (0) if already expired or if the credential is not identified as expiring based on time.
    
    Throws:
    
    AS400SecurityException - If an IBM i system security or authentication error occurs.
  - isCurrent
```
public boolean isCurrent()
```
    Indicates if a timed credential is still considered valid for authenticating to associated IBM i system services or performing related actions.
    
    Returns:
    true if valid or not timed; false if not valid or if the operation fails.
  - isDestroyed
```
public boolean isDestroyed()
```
    Indicates if the credential has been destroyed.
    The credential is considered destroyed if the contained information is no longer sufficient to access host information for or take action against the credential.
    
    Returns:
    true if destroyed; otherwise false.
  - isPrivate
```
public boolean isPrivate()
```
    Indicates whether the credential is considered private.
    This value can be referenced by authentication services as an indication of when to check permissions or otherwise protect access to sensitive credentials.
    
    Returns:
    true if private; false if public.
  - isRenewable
```
public boolean isRenewable()
```
    Indicates if the credential can be refreshed.
    
    Returns:
    true if the validity period of the credential can be programmatically updated or extended using refresh(); otherwise false.
    See Also:
    refresh()
  - isTimed
```
public boolean isTimed()
```
    Indicates if the credential will expire based on time.
    
    Returns:
    true if the credential has been identified as expiring at the end of a predetermined time interval; otherwise false.
  - refresh
```
public void refresh()
             throws AS400SecurityException
```
    Updates or extends the validity period for the credential.
    Does nothing if the credential cannot be programmatically updated or extended.
    
    Throws:
    
    AS400SecurityException - If an IBM i system security or authentication error occurs.
  - removeCredentialListener
```
public void removeCredentialListener(AS400CredentialListener listener)
```
    Removes the specified listener from the internal list.
    Does nothing if the listener is not in the list.
    
    Parameters:
    listener - The AS400CredentialListener.
    See Also:
    addCredentialListener(com.ibm.as400.security.auth.AS400CredentialListener)
  - removePropertyChangeListener
```
public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
```
    Removes the specified listener from the internal list.
    Does nothing if the listener is not in the list.
    
    Parameters:
    listener - The PropertyChangeListener.
    See Also:
    addPropertyChangeListener(java.beans.PropertyChangeListener)
  - removeVetoableChangeListener
```
public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
```
    Removes the specified listener from the internal list.
    Does nothing if the listener is not in the list.
    
    Parameters:
    listener - The VetoableChangeListener.
    See Also:
    addVetoableChangeListener(java.beans.VetoableChangeListener)
  - setPrincipal
```
public void setPrincipal(AS400Principal p)
                  throws java.beans.PropertyVetoException
```
    Sets the principal associated with the credential.
    This property cannot be changed once a request initiates a connection for the object to the IBM i system (for example, refresh).
    
    Parameters:
    p - The principal.
    
    Throws:
    
    java.beans.PropertyVetoException - If the change is vetoed.
    
    ExtendedIllegalStateException - If the property cannot be changed due to the current state.
  - setSystem
```
public void setSystem(AS400 system)
               throws java.beans.PropertyVetoException
```
    Sets the AS400 system object for the credential.
    This property cannot be changed once a request initiates a connection for the object to the IBM i system (for example, refresh).
    
    Parameters:
    system - The AS400 system object.
    
    Throws:
    
    java.beans.PropertyVetoException - If the change is vetoed.
    
    ExtendedIllegalStateException - If the property cannot be changed due to the current state.
  - startAutomaticRefresh
```
public void startAutomaticRefresh(int refreshInterval,
                         int maxRefreshes)
```
    Starts automatic refresh for the credential.
    While this action is designed to automatically refresh the credential at the specified interval, this is subject to current workload and scheduling of the underlying Java Virtual Machine. Calling applications should take this into consideration when defining the refresh interval in relation to the credential's time to expiration, as it may not be possible to revive a credential once it has expired.
    
    Parameters:
    refreshInterval - The number of seconds between refresh attempts. The first refresh will occur immediately; the second will occur this many seconds after the first, and so on.
    maxRefreshes - The maximum number of times to refresh the credential. A value of negative one (-1) indicates no maximum.
    
    Throws:
    
    java.lang.IllegalStateException - If automatic refresh has already been started or is not a valid operation for the credential. Automatic refresh is not valid if the credential cannot be programmatically updated or extended, or if the associated AS400 system object is not allowed to start additional threads.
    
    ExtendedIllegalArgumentException - If a parameter value is out of range.
    See Also:
    refresh(), getAutomaticRefreshStatus(), stopAutomaticRefresh()
  - stopAutomaticRefresh
```
public void stopAutomaticRefresh()
```
    Stops and clears the state of any automatic refresh in progress for the credential.
    Does nothing if automatic refresh is not active.
    
    See Also:
    startAutomaticRefresh(int, int), getAutomaticRefreshStatus()
  - swap
```
public void swap()
          throws java.lang.Exception
```
    Attempts to swap the current thread identity based on this credential.
    No return credential is generated.
    Note: This method affects the running user profile for subsequent native code invocations and any further requests against the assigned IBM i system. Any currently existing AS400 instances, even if defined for the local host and current user, are not affected if connections have been established under the old identity.
    Note: swap() is supported only when running natively on IBM i. It is unsupported as a remote operation.
    
    Specified by:
    
    swap in interface AS400SwappableCredential
    
    Throws:
    
    java.lang.Exception - If an exception occurs.
    See Also:
    Swapper
  - swap
```
public AS400Credential swap(boolean returnCredential)
                     throws AS400SecurityException
```
    Attempts to swap the current thread identity based on this credential.
    Note: This method affects the running user profile for subsequent native code invocations and any further requests against the assigned IBM i system. Any currently existing AS400 instances, even if defined for the local host and current user, are not affected if connections have been established under the old identity.
    Note: swap() is supported only when running natively on IBM i. It is unsupported as a remote operation.
    
    Parameters:
    returnCredential - Indicates whether a credential should be returned that is capable of swapping back to the original thread identity. Not generating a return credential optimizes performance and avoids any potential problems in generating the return value. This parameter is ignored by credentials not supporting the ability to swap back to the original thread identity.
    
    Returns:
    A credential capable of swapping back to the original thread identity; classes not supporting this capability will return null. This value will also be null if returnCredential is false.
    
    Throws:
    
    AS400SecurityException - If an IBM i system security or authentication error occurs.
    See Also:
    Swapper

Methods inherited from class java.lang.Object

CR_AUTO_REFRESH_FAILED

CR_AUTO_REFRESH_NOT_VALID

CR_AUTO_REFRESH_STARTED

CR_AUTO_REFRESH_STOPPED

AS400Credential

addCredentialListener

addPropertyChangeListener

addVetoableChangeListener

basicAuthenticationPrompt

destroy

finalize

getAutomaticRefreshFailure

getAutomaticRefreshStatus

getPrincipal

getSystem

getTimeToExpiration

isCurrent

isDestroyed

isPrivate

isRenewable

isTimed

refresh

removeCredentialListener

removePropertyChangeListener

removeVetoableChangeListener

setPrincipal

setSystem

startAutomaticRefresh

stopAutomaticRefresh

swap

swap