Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.security.auth
Class ThreadSubject

    java.lang.Object
      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.

Author:
  D Kent Soper, Andrew Gotte

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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD