com.filenet.api.util
Class UserContext

java.lang.Object
  extended by 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 J2EE 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 uc = UserContext.get();
     try
     {
         uc.pushSubject(mySubject);
         // do work
     }
     finally
     {
         uc.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);
     }
 


Constructor Summary
UserContext()
          Constructs a new instance of a UserContext object with uninitialized properties.
 
Method Summary
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 UserContext get()
          This method returns the UserContext object associated with the current thread.
 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.

Returns:
A JAAS Subject object.

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.

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.


© Copyright IBM Corporation 2006, 2008. All rights reserved.