com.ibm.security.auth
Class ThreadSubject

java.lang.Object
  extended by com.ibm.security.auth.ThreadSubject
Direct Known Subclasses:
NTThreadSubject

public abstract class ThreadSubject
extends java.lang.Object

Subclasses of this abstract class provide a way to set the underlying operating system thread identity to the appropriate value.

The default ThreadSubject implementation for NT is com.ibm.security.auth.NTThreadSubject. This can be overridded by specifying or modifying the value of the "thread.subject.provider" security property (in the Java security properties file) to the fully qualified name of the desired ThreadSubject implementation class. The Java security properties file is located in the file named <JAVA_HOME>/lib/security/java.security, where <JAVA_HOME> refers to the directory where the JDK was installed. To disallow ThreadSubject processing completely, the following line can be inserted in the Java security properties file:

thread.subject.provider=

Each implementation must have a constructor which takes no arguments. This allows the doAs method to properly instantiate it.


Constructor Summary
ThreadSubject()
           
 
Method Summary
static java.lang.Object doAs(Subject subject, java.security.PrivilegedAction action)
          Perform work as a particular Subject.
static java.lang.Object doAs(Subject subject, java.security.PrivilegedExceptionAction action)
          Perform work as a particular Subject.
static java.lang.Object doAsPrivileged(Subject subject, java.security.PrivilegedAction action, java.security.AccessControlContext acc)
          Perform work as a particular Subject.
static java.lang.Object doAsPrivileged(Subject subject, java.security.PrivilegedExceptionAction action, java.security.AccessControlContext acc)
          Perform work as a particular Subject.
protected abstract  void restore()
          Restore the underlying operating system thread's original identity.
protected abstract  void set(Subject subject)
          Set the underlying operating system thread identity.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ThreadSubject

public ThreadSubject()
Method Detail

set

protected abstract void set(Subject subject)
                     throws java.lang.UnsupportedOperationException,
                            java.lang.SecurityException
Set the underlying operating system thread identity.

This method extracts the relevant Principal and/or Credential information from the specified Subject and associate it with the underlying operating system thread.

Parameters:
subject - from which the method implementation extracts the relevant Principal and/or Credential information from the specified Subject. This information is then associated with the underlying operating system thread.
Throws:
java.lang.UnsupportedOperationException - if this operation is not supported or if this operation fails.

java.lang.SecurityException - if the caller attempts to invoke this method and does not have permission.

restore

protected abstract void restore()
                         throws java.lang.UnsupportedOperationException,
                                java.lang.SecurityException
Restore the underlying operating system thread's original identity.

Implementations of this method restore the original operating system thread identity modified by the set method.

Throws:
java.lang.UnsupportedOperationException - if this operation is not supported or if this operation fails.

java.lang.SecurityException - if the caller attempts to invoke this method and does not have permission.

doAs

public static java.lang.Object doAs(Subject subject,
                                    java.security.PrivilegedAction action)
Perform work as a particular Subject. This method implementation is identical to the corresponding Subject.doAs method implementation but with one major addition:

This method instantiates the default or specified ThreadSubject and invokes its set method prior to invoking the ExceptionAction's run method. After the run completes, the ThreadSubject's restore method is invoked.

Note that since this method instantiates a new ThreadSubject during each invocation, the ThreadSubject's set and restore method are called only one time each.

Parameters:
subject - the Subject that the specified action will run as.

action - the code to be run as the specified Subject.

Returns:
the Object returned by the PrivilegedAction's run method.

Throws:
java.lang.NullPointerException - if the PrivilegedAction is null.

java.lang.SecurityException - if the caller attempts to invoke this method and does not have permission, or if the caller invokes this method as privileged and does not have permission. Note that since ThreadSubject also incorporates Subject processing, the permissions must include doAs permissions as well as threadSubjectDoAs.

java.lang.UnsupportedOperationException - if the ThreadSubject.set or ThreadSubject.restore implementation fails or is not supported.


doAs

public static java.lang.Object doAs(Subject subject,
                                    java.security.PrivilegedExceptionAction action)
                             throws java.security.PrivilegedActionException
Perform work as a particular Subject. This method implementation is identical to the corresponding Subject.doAs method implementation but with one major addition:

This method instantiates the default or specified ThreadSubject and invokes its set method prior to invoking the ExceptionAction's run method. After the run completes, the ThreadSubject's restore method is invoked.

Note that since this method instantiates a new ThreadSubject during each invocation, the ThreadSubject's set and restore method are called only one time each.

Parameters:
subject - the Subject that the specified action will run as.

action - the code to be run as the specified Subject.

Returns:
the Object returned by the PrivilegedExceptionAction's run method.

Throws:
java.security.PrivilegedActionException - if the PrivilegedExceptionAction.run method throws a checked exception.

java.lang.NullPointerException - if the PrivilegedExceptionAction is null.

java.lang.SecurityException - if the caller attempts to invoke this method and does not have permission, or if the caller invokes this method as privileged and does not have permission. Note that since ThreadSubject also incorporates Subject processing, the permissions must include doAs permissions as well as threadSubjectDoAs.

java.lang.UnsupportedOperationException - if the ThreadSubject.set or ThreadSubject.restore implementation fails or is not supported.


doAsPrivileged

public static java.lang.Object doAsPrivileged(Subject subject,
                                              java.security.PrivilegedAction action,
                                              java.security.AccessControlContext acc)
Perform work as a particular Subject. This method implementation is identical to the corresponding Subject.doAs method implementation but with one major addition:

This method instantiates the default or specified < code>ThreadSubject and invokes its set method prior to invoking the ExceptionAction's run method. After the run completes, the ThreadSubject's restore method is invoked.

Note that since this method instantiates a new ThreadSubject during each invocation, the ThreadSubject's set and restore method are called only one time each.

Parameters:
subject - the Subject that the specified action will run as.

action - the code to be run as the specified Subject.

acc - the AccessControlContext to be tied to the specified subject and action.

Returns:
the Object returned by the PrivilegedAction's run method.
Throws:
java.lang.NullPointerException - if the PrivilegedAction is null.

java.lang.SecurityException - if the caller attempts to invoke this method and does not have permission, or if the caller invokes this method as privileged and does not have permission. Note that since ThreadSubject also incorporates Subject processing, the permissions must include doAsPrivileged permissions as well as threadSubjectDoAsPrivileged.

java.lang.UnsupportedOperationException - if the ThreadSubject.set or ThreadSubject.restore implementation fails or is not supported.


doAsPrivileged

public static java.lang.Object doAsPrivileged(Subject subject,
                                              java.security.PrivilegedExceptionAction action,
                                              java.security.AccessControlContext acc)
                                       throws java.security.PrivilegedActionException
Perform work as a particular Subject. This method implementation is identical to the corresponding Subject.doAs method implementation but with one major addition:

This method instantiates the default or specified ThreadSubject and invokes its set method prior to invoking the ExceptionAction's run method. After the run completes, the ThreadSubject's restore method is invoked.

Note that since this method instantiates a new ThreadSubject during each invocation, the ThreadSubject's set and restore method are called only one time each.

Parameters:
subject - the Subject that the specified action will run as.

action - the code to be run as the specified Subject.

acc - the AccessControlContext to be tied to the specified subject and action.

Returns:
the Object returned by the PrivilegedExceptionAction's run method.
Throws:
java.lang.NullPointerException - if the PrivilegedExceptionAction is null.

java.lang.SecurityException - if the caller attempts to invoke this method and does not have permission, or if the caller invokes this method as privileged and does not have permission. Note that since ThreadSubject also incorporates Subject processing, the permissions must include doAs permissions as well as threadSubjectDoAs.

java.lang.UnsupportedOperationException - if the ThreadSubject.set or ThreadSubject.restore implementation fails or is not supported.

java.security.PrivilegedActionException