All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.ibm.as400.security.auth.AS400Credential

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

public abstract class AS400Credential
extends Object
implements Serializable, AS400SwappableCredential
The AS400Credential class provides an abstract superclass for representations of AS/400 security-related attributes.

Credentials may be used for authenticating to system services, or may simply enable certain actions to be performed.

Typical AS/400 credentials include, but are not necessarily 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:


Variable Index

 o CR_AUTO_REFRESH_FAILED
ID indicating that automatic refresh has failed.
 o CR_AUTO_REFRESH_NOT_VALID
ID indicating that automatic refresh is not a valid operation.
 o CR_AUTO_REFRESH_STARTED
ID indicating that automatic refresh is started.
 o CR_AUTO_REFRESH_STOPPED
ID indicating that automatic refresh is stopped.

Constructor Index

 o AS400Credential()
Constructs an AS400Credential object.

Method Index

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

Variables

 o CR_AUTO_REFRESH_FAILED
 public static final int CR_AUTO_REFRESH_FAILED
ID indicating that automatic refresh has failed.

 o CR_AUTO_REFRESH_NOT_VALID
 public static final int CR_AUTO_REFRESH_NOT_VALID
ID indicating that automatic refresh is not a valid operation.

 o CR_AUTO_REFRESH_STARTED
 public static final int CR_AUTO_REFRESH_STARTED
ID indicating that automatic refresh is started.

 o CR_AUTO_REFRESH_STOPPED
 public static final int CR_AUTO_REFRESH_STOPPED
ID indicating that automatic refresh is stopped.

Constructors

 o AS400Credential
 public AS400Credential()
Constructs an AS400Credential object.

Methods

 o addCredentialListener
 public void addCredentialListener(AS400CredentialListener listener)
Adds a listener to receive credential events.

Parameters:
listener - The AS400CredentialListener.
See Also:
removeCredentialListener
 o addPropertyChangeListener
 public void addPropertyChangeListener(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
 o addVetoableChangeListener
 public void addVetoableChangeListener(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
 o basicAuthenticationPrompt
 public 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.
 o destroy
 public void destroy() throws AS400SecurityException
Destroys the credential by destroying or clearing sensitive information for the credential.

Throws: AS400SecurityException
If an AS/400 security or authentication error occurs.
 o finalize
 protected void finalize() throws Throwable
Called when garbage collection determines that there are no more references to the object.

Throws: Throwable
If an error occurs.
Overrides:
finalize in class Object
 o getAutomaticRefreshFailure
 public 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
 o getAutomaticRefreshStatus
 public int getAutomaticRefreshStatus()
Returns the current status of automatic refresh activity for the credential.

Possible identifiers are defined as fields on this class:

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, stopAutomaticRefresh, getAutomaticRefreshFailure
 o getPrincipal
 public AS400Principal getPrincipal()
Returns the AS400Principal associated with the credential.

Returns:
The principal associated with the credential; null if not assigned.
 o getSystem
 public AS400 getSystem()
Returns the AS400 system object for the credential.

Returns:
The AS400 system for the credential; null if not assigned.
 o 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 AS/400 security or authentication error occurs.
 o isCurrent
 public boolean isCurrent()
Indicates if a timed credential is still considered valid for authenticating to associated AS/400 services or performing related actions.

Returns:
true if valid or not timed; false if not valid or if the operation fails.
 o 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.
 o 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.
 o 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
 o 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.
 o 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 AS/400 security or authentication error occurs.
 o 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
 o removePropertyChangeListener
 public void removePropertyChangeListener(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
 o removeVetoableChangeListener
 public void removeVetoableChangeListener(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
 o setPrincipal
 public void setPrincipal(AS400Principal p) throws PropertyVetoException
Sets the principal associated with the credential.

This property cannot be changed once a request initiates a connection for the object to the AS/400 system (for example, refresh).

Parameters:
p - The principal.
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalStateException
If the property cannot be changed due to the current state.
 o setSystem
 public void setSystem(AS400 system) throws 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 AS/400 system (for example, refresh).

Parameters:
system - The AS400 system object.
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalStateException
If the property cannot be changed due to the current state.
 o 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: 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.
Throws: ExtendedIllegalArgumentException
If a parameter value is out of range.
See Also:
refresh, getAutomaticRefreshStatus, stopAutomaticRefresh
 o 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, getAutomaticRefreshStatus
 o swap
 public void swap() throws Exception
Attempts to swap the OS/400 thread identity based on the 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 AS/400 system. Other AS400 instances, even if defined for the local host and current user, are not affected if connections have been established under the old identity.

Throws: Exception
If an exception occurs.
 o swap
 public AS400Credential swap(boolean returnCredential) throws AS400SecurityException
Attempts to swap the OS/400 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 AS/400 system. Other AS400 instances, even if defined for the local host and current user, are not affected if connections have been established under the old identity.

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 AS/400 security or authentication error occurs.

All Packages  Class Hierarchy  This Package  Previous  Next  Index