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 callsetLocale
at the beginning of each new thread (request). The following code snippet illustrates the call to make at the startup phase of every request, wherereqLocale
is the locale to be used for this request:UserContext uc = UserContext.get(); uc.setLocale(reqLocale);
Calls to the
pushSubject
andpopSubject
methods must always be balanced. That is, a call topushSubject
must eventually be followed by a balancing call topopSubject
, particularly for Java EE applications or other situations in which threads are reused. TheUserContext
object, and therefore its internal stack ofSubjects
, is thread local. If thepushSubject
andpopSubject
calls are not balanced, an incorrectSubject
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 matchingpopSubject()
method. Because the stack ofSubjects
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
Constructors Constructor and Description UserContext()
Constructs a new instance of aUserContext
object with uninitialized properties.
-
Method Summary
Methods 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 JAASSubject
object.static <T> java.lang.Object
doAs(javax.security.auth.Subject subject, java.security.PrivilegedExceptionAction<T> pea)
Performs thePrivilegedExceptionAction
with the given ambientSubject
.static UserContext
get()
This method returns theUserContext
object associated with the current thread.static javax.security.auth.Subject
getAmbientSubject()
Returns the current ambient JAASSubject
, if any.java.util.Locale
getLocale()
Returns the locale identifier for this user context.javax.security.auth.Subject
getSubject()
Returns the currentSubject
associated with the thread.javax.security.auth.Subject
popSubject()
Removes and returns the currently activeSubject
, making the previously activeSubject
the current one.void
pushSubject(javax.security.auth.Subject sub)
Saves any previously activeSubject
and makes the specifiedSubject
active.static void
set(UserContext uc)
This method associates the current thread with aUserContext
object.void
setLocale(java.util.Locale locale)
Sets the locale identifier for this user context.
-
-
-
Constructor Detail
-
UserContext
public UserContext()
Constructs a new instance of aUserContext
object with uninitialized properties.
-
-
Method Detail
-
getSubject
public javax.security.auth.Subject getSubject()
Returns the currentSubject
associated with the thread. To associate theSubject
with the thread, call thepushSubject()
method. This method does not consider any ambient JAAS Subjects. For that, use the methodgetAmbientSubject()
.- 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)
Performs thePrivilegedExceptionAction
with the given ambientSubject
. It is preferable to use this method instead of thepushSubject()
andpopSubject()
methods because it eliminates the chance for unmatched push/pop. It also places theSubject
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 thePrivilegedExceptionAction.run()
method throws anyThrowable
. In contrast to the standard JDKSubject.doAs()
method, anyThrowable
thrown will be wrapped in an uncheckedEngineRuntimeException
rather than a checkedPrivilegedActionException
.
-
getAmbientSubject
public static javax.security.auth.Subject getAmbientSubject()
Returns the current ambient JAASSubject
, if any. Ambient means put into the thread context via JAAS APIs, including container-managed authentication in J2EE. This method ignores anySubject
s pushed onto the stack viaUserContext.pushSubject()
but considers to be ambient aSubject
in effect viaUserContext.doAs()
.- Returns:
- A JAAS
Subject
object. - See Also:
getSubject()
-
pushSubject
public void pushSubject(javax.security.auth.Subject sub)
Saves any previously activeSubject
and makes the specifiedSubject
active. To restore the previousSubject
, call thepopSubject()
method.- Parameters:
sub
- The JAASSubject
object to be associated with the thread. Cannot benull
.- 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 activeSubject
, making the previously activeSubject
the current one. Note that this method does not return the restoredSubject
. To retrieve the restoredSubject
, you must callgetSubject()
.- 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 JavaLocale
object to be associated with the current user context. Can benull
, 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 JAASSubject
object. The client must be properly configured for JAAS. The calling code can optionally provide a JAAS configuration stanza name or pass in anull
value, in which case the stanza name defaults to "FileNetP8". Note that the returnedSubject
has no association to the current user context. It is up to the caller to use theSubject
with theUserContext
or to use the JAASSubject.doAs
method.- Parameters:
conn
- TheConnection
object for this thread. Cannot benull
.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 benull
, in which case the stanza name defaults to "FileNetP8".- Returns:
- A JAAS
Subject
object. - Throws:
EngineRuntimeException
- if the connection isnull
or an invalid value.
-
get
public static UserContext get()
This method returns theUserContext
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 aUserContext
object. In general, aUserContext
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 aUserContext
object on a different thread than the one from which it was created, a clone of theUserContext
is made and set to the current thread instead. This clone will contain a shallow copy of the Subjects in the givenUserContext
so that the underlying Subjects are shared between cloned instances, however the push/pop list of Subjects is unique per instance ofUserContext
.- Parameters:
uc
- AUserContext
object.
-
-