|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.filenet.api.util.UserContext
public class UserContext
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 |
---|
public UserContext()
UserContext
object with
uninitialized properties.
Method Detail |
---|
public javax.security.auth.Subject getSubject()
Subject
associated with the
thread. To associate the Subject
with the thread, call the
pushSubject()
method.
Subject
object.public void pushSubject(javax.security.auth.Subject sub)
Subject
and makes
the specified Subject
active. To restore the previous Subject
,
call the popSubject()
method.
sub
- The JAAS Subject
object to be associated with the thread. Cannot be null
.
EngineRuntimeException
- if the parameter is not specified or is an invalid value.public javax.security.auth.Subject popSubject()
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()
.
Subject
for the thread.public void setLocale(java.util.Locale locale)
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.public java.util.Locale getLocale()
Locale
object.public static javax.security.auth.Subject createSubject(Connection conn, java.lang.String user, java.lang.String password, java.lang.String optionalJAASStanzaName)
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.
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”.
Subject
object.
EngineRuntimeException
- if the connection is null
or an invalid value.public static UserContext get()
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.
UserContext
object associated with the current thread.public static void set(UserContext uc)
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
.
uc
- A UserContext
object.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |