com.filenet.api.util

Class UserContext

java.lang.Object

com.filenet.api.util.UserContext

public class UserContext
extends java.lang.Object

Used to override the locale and authentication for the requests a given thread makes to the server. It is not required if your application is already running in a Java™ Authentication and Authorization Service (JAAS) context or if the JVM's default locale is sufficient. When a subject is specified, a request to the server is limited, through authorization access control, to the operations that have been granted to the specified principal. Correspondingly, if a locale is specified, the server attempts to return localizable messages, such as exceptions, according to the language code specified by the locale.

As noted above, UserContext operations are performed on a per-thread basis. When working with multiple locales, for example when servicing requests via a thread pool, you must explicitly call setLocale at the beginning of each new thread (request). The following code snippet illustrates the call to make at the startup phase of every request, where reqLocale is the locale to be used for this request:

     UserContext uc = UserContext.get();
     uc.setLocale(reqLocale);
 

Calls to the pushSubject and popSubject methods must always be balanced. That is, a call to pushSubject must eventually be followed by a balancing call to popSubject, particularly for Java EE applications or other situations in which threads are reused. The UserContext object, and therefore its internal stack of Subjects, is thread local. If the pushSubject and popSubject calls are not balanced, an incorrect Subject might be used by a component that is reusing the thread. The coding pattern shown below is a good way to ensure that the calls are balanced:

     UserContext.get().pushSubject(mySubject);
     try
     {
         // do work
     }
     finally
     {
         UserContext.get().popSubject();
     }
 

To ensure that an ambient JAAS Subject is used for Content Engine API server roundtrips, you can employ the coding pattern below. You can view this as defensive coding against the possibility that another component has neglected to call the matching popSubject() method. Because the stack of Subjects is affiliated with a thread, a defect in one application can lead to problems in other applications (typically thread-pool environments).

     boolean ambient = true; //true means container-managed authentication
     UserContext origUC = UserContext.get();
     UserContext tempUC = new UserContext();
     tempUC.setLocale(origUC.getLocale());
     try
     {
         if (ambient) UserContext.set(tempUC);

         // execute code using ambient Subject

     }
     finally
     {
         if (ambient) UserContext.set(origUC);
     }
 

Note: The style of programming using push/popSubject is no longer preferred. Instead the doAs(javax.security.auth.Subject, java.security.PrivilegedExceptionAction<T>) method should be used or, as of 5.5.9, SubjectCredentials.doAs(java.security.PrivilegedExceptionAction<T>).

Constructor Summary

Constructors

Constructor and Description
UserContext() Constructs a new instance of a UserContext object with uninitialized properties.

Method Summary

Modifier and Type	Method and Description
static javax.security.auth.Subject	createSubject(Connection conn, java.lang.String user, java.lang.String password, java.lang.String optionalJAASStanzaName) Uses standard JAAS calls to authenticate with the application server and return a JAAS Subject object.
static <T> java.lang.Object	doAs(javax.security.auth.Subject subject, java.security.PrivilegedExceptionAction<T> pea) Deprecated. As of version 5.5.9. The SubjectCredentials.doAs(java.security.PrivilegedExceptionAction<T>) method should be used instead.
static UserContext	get() This method returns the UserContext object associated with the current thread.
static javax.security.auth.Subject	getAmbientSubject() Returns the current ambient JAAS Subject, if any.
java.util.Locale	getLocale() Returns the locale identifier for this user context.
javax.security.auth.Subject	getSubject() Returns the current Subject associated with the thread.
javax.security.auth.Subject	popSubject() Removes and returns the currently active Subject, making the previously active Subject the current one.
void	pushSubject(javax.security.auth.Subject sub) Saves any previously active Subject and makes the specified Subject active.
static void	set(UserContext uc) This method associates the current thread with a UserContext object.
void	setLocale(java.util.Locale locale) Sets the locale identifier for this user context.

Methods inherited from class java.lang.Object

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

Constructor Detail

UserContext

public UserContext()

Constructs a new instance of a UserContext object with uninitialized properties.

Method Detail

getSubject

public javax.security.auth.Subject getSubject()

Returns the current Subject associated with the thread. To associate the Subject with the thread, call the pushSubject() method. This method does not consider any ambient JAAS Subjects. For that, use the method getAmbientSubject().

Returns:

A JAAS Subject object.

See Also:

getAmbientSubject()

doAs

public static <T> java.lang.Object doAs(javax.security.auth.Subject subject,
                                        java.security.PrivilegedExceptionAction<T> pea)

Deprecated. As of version 5.5.9. The SubjectCredentials.doAs(java.security.PrivilegedExceptionAction<T>) method should be used instead.

Performs the PrivilegedExceptionAction with the given ambient Subject. It is preferable to use this method instead of the pushSubject() and popSubject() methods because it eliminates the chance for unmatched push/pop. It also places the Subject into the ambient JAAS context, so it will be in effect for all software, not just the CE API.

Returns:

The value returned by the PrivilegedExceptionAction.run() method.

Throws:

EngineRuntimeException - if the PrivilegedExceptionAction.run() method throws any Throwable. In contrast to the standard JDK Subject.doAs() method, any Throwable thrown will be wrapped in an unchecked EngineRuntimeException rather than a checked PrivilegedActionException.

getAmbientSubject

public static javax.security.auth.Subject getAmbientSubject()

Returns the current ambient JAAS Subject, if any. Ambient means put into the thread context via JAAS APIs, including container-managed authentication in J2EE. This method ignores any Subjects pushed onto the stack via UserContext.pushSubject() but considers to be ambient a Subject in effect via UserContext.doAs().

Returns:

A JAAS Subject object.

See Also:

getSubject()

pushSubject

public void pushSubject(javax.security.auth.Subject sub)

Saves any previously active Subject and makes the specified Subject active. To restore the previous Subject, call the popSubject() method.

Parameters:

sub - The JAAS Subject object to be associated with the thread. Cannot be null.

Throws:

EngineRuntimeException - if the parameter is not specified or is an invalid value.

popSubject

public javax.security.auth.Subject popSubject()

Removes and returns the currently active Subject, making the previously active Subject the current one. Note that this method does not return the restored Subject. To retrieve the restored Subject, you must call getSubject().

Returns:

The currently active JAAS Subject for the thread.

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale identifier for this user context. For more information, see the LocaleName property.

Parameters:

locale - The Java Locale object to be associated with the current user context. Can be null, in which case the default locale for the JVM is used.

getLocale

public java.util.Locale getLocale()

Returns the locale identifier for this user context. If no locale has been set, this method returns the default locale defined for the JVM. For more information, see the LocaleName property.

Returns:

A Java Locale object.

createSubject

public static javax.security.auth.Subject createSubject(Connection conn,
                                                        java.lang.String user,
                                                        java.lang.String password,
                                                        java.lang.String optionalJAASStanzaName)

Uses standard JAAS calls to authenticate with the application server and return a JAAS Subject object. The client must be properly configured for JAAS. The calling code can optionally provide a JAAS configuration stanza name or pass in a null value, in which case the stanza name defaults to "FileNetP8". Note that the returned Subject has no association to the current user context. It is up to the caller to use the Subject with the UserContext or to use the JAAS Subject.doAs method.

Note: As of version 5.5.9, if using the WSI transport the UsernameCredentials class can be used to execute actions using username/password authentication, avoiding the need to perform a JAAS login.

Parameters:

conn - The Connection object for this thread. Cannot be null.

user - A string containing the user name to be authenticated.

password - A string containing the user's password.

optionalJAASStanzaName - A string containing the JAAS configuration stanza name. Can be null, in which case the stanza name defaults to "FileNetP8".

Returns:

A JAAS Subject object.

Throws:

EngineRuntimeException - if the connection is null or an invalid value.

get

public static UserContext get()

This method returns the UserContext object associated with the current thread. When no user context has been set, a default one exists containing the current locale default from the JVM.

Returns:

The UserContext object associated with the current thread.

set

public static void set(UserContext uc)

This method associates the current thread with a UserContext object. In general, a UserContext object should not be shared between threads. So this operation should only be invoked from the same thread that created the given object. If an attempt is made to set a UserContext object on a different thread than the one from which it was created, a clone of the UserContext is made and set to the current thread instead. This clone will contain a shallow copy of the Subjects in the given UserContext so that the underlying Subjects are shared between cloned instances, however the push/pop list of Subjects is unique per instance of UserContext.

Parameters:

uc - A UserContext object.