| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
Application user sessions are used to allow applications to store security and application context on the user session. An application can easily reconnect to the same user session for each request, maintaining the user context over the duration of the user's session without the overhead of having to obtain and initiate a database connection each time. The actual connection used is not guaranteed to be the same between requests. Application user session roles can be enabled for a user, and dictate what actions that user has.
This chapter includes the following sections:
Section 48.2, "Configuring Your Project to Use Application User Sessions"
Section 48.3, "Accessing Properties of the Applications Context"
Configuring your user interface project for an application user session is a requirement whenever you want to secure data and interact with Oracle Fusion Data Security. Additionally, before you can run and test your application from a task flow or web page, you should configure your user interface project to use an application user session.
The application user session is used to store user and application context from the time the user logs in until log out. The application user session stores common information used in Oracle Fusion Applications as session attributes and includes basic information about user identity and language preferences, as well as context important to particular applications. Specifically, session information includes the session ID, current user information, current language, date and number formatting, and other similar properties. Session attributes can also be used to track application specific information such as, the current user's shopping cart, the country selection, or the currently selected operating unit.
Application user session namespaces are where attributes on the session are stored. These attributes are then available over multiple requests whenever the session is attached.
Oracle Fusion Applications maintains its own namespaces - one for tracking security information, and another that developers can use to store attributes that they need to track over the life of a session.
Additionally, developers can create their own namespaces for any product specific attributes that they need to track over the life of a session. For example, when a large number of attributes exists, developers may want to create their own namespaces to group the attributes together more cleanly.
Oracle Fusion Middleware Extensions for Applications provides covers on top of the routines for getting attributes. To access the attributes of the application context, APIs exist in both PL/SQL and Java, as described in Section 48.3, "Accessing Properties of the Applications Context."
When you create a user interface project to test or run a task flow (anything that contains a .jspx file) you need to enable application user sessions for any JSPX pages or task flows that you have created in your user interface project.
If the user interface project provides task flows that are only called from a page in another project, then there is no need to configure your project to use sessions.
By default, application user sessions are not enabled for your project. If you wish to access this functionality, you must configure your project.
To configure your project to use application user sessions:
In your Application Navigator, select your data model project and then right-click and choose Project Properties. In the Categories tree, select Libraries and Classpath and verify that the Applications Core and Web Services Data Control libraries have been added.
In your Application Navigator, select the web.xml file in the WEB-INF folder of your user interface project. Double-click to open the file. In the Categories tree, select Filters to create a new filter. Enter the following information:
Filter Name: Enter ApplSessionFilter
Filter Class: Enter oracle.apps.fnd.applcore.common.ApplSessionFilter
Select the Source view to manually modify the web.xml source to add the ApplSessionFilter mapping definition into the same section where other filters are defined—immediately after the JpsFilter mapping definition and before any other definitions.
Example 48-1 shows the ApplSessionFilter mapping definition to add.
Example 48-1 Creating a New Filter Mapping Definition
... <filter-mapping> <filter-name>ApplSessionFilter</filter-name> <servlet-name>Faces Servlet</servlet-name> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> </filter-mapping> ...
It is important that you add this filter mapping immediately after the JpsFilter mapping definition and before any other definitions. This is to ensure that the ApplSessionFilter servlet filter executes immediately after the JpsFilter servlet handles authentication. Normally, this does not make a difference, however there are cases, such as customization code, where this is required.
You can create the above through the Filter Mappings tab (with Mapping Type set to Servlet, and Mapping set to Faces Servlet, and Dispatcher Type set to Forward, Request) but in order to change the ordering of the filter mapping, you must modify the web.xml file directly.
Save all changes.
You should also stop and restart any server processes that you have running to make sure JDeveloper notices this new change. At this point you can run your page with application user sessions enabled, but you will always be running as the anonymous user. If you wish to require that users to authenticate, you will need to enable authentication and define some users and roles, as described in Section 49.3, "Adding Function Security to the Application."
The steps in Section 48.2.1, "How to Configure Your Project to Use Application User Sessions" can be used to configure the ADF Business Component Browser to run in a mode that supports application user sessions.
If you are running a standalone Java program or a JUnit test, you must explicitly call the ApplSessionUtil.initializeSession API at the beginning of your program to create an applications context object. For more information about how to call the ApplSession.initializeSession API, see Section 48.3.2.1, "Initializing Sessions."
When you run your page, an authentication dialog displays. Login as OPERATIONS / welcome1. An application user session for the OPERATIONS user is created and associated with your application user session. Your page can access this application user session through the ApplSessionUtil class, as described in Section 48.3, "Accessing Properties of the Applications Context."
For details about enforcing security and granting access to application resources while testing the applications, see Section 49.3, "Adding Function Security to the Application."
The applications context is a set of properties relevant to applications that is stored on the application user session as a series of name-value pairs. You can access the core application security context in one of two ways:
Through the ApplSession.java class in the oracle.apps.fnd.applcore.common package
Through the FND_GLOBAL package in PLSQL
The list of context attributes includes information such as current user name and the current language. The core attributes that are now supported were derived from the following:
Customization layer hierarchy.
Central context attributes.
National Language Support (NLS) properties.
The following is the list of context attributes that are automatically captured and maintained in the ApplSession context. The values listed are the exact names of the attributes as they are defined in the session context. Note that developers can add their own custom attributes as well.
Security and Customization attributes:
USER_GUID - The unique GUID that identifies the currently logged in user.
USER_NAME - The name of the currently logged in user.
PRODUCT_FAMILY - The current active product family.
PRODUCT - The current active product.
INDUSTRY - The current active industry.
TERRITORY - The current active territory.
SITE - Returns the constant value SITE.
GLOBAL - Returns the constant value GLOBAL.
ADDTL_CUSTOM_LEVEL - Additional customization level is a context property that can be customized by developers.
INDUSTRY_IN_TERRITORY - The current active industry in a particular territory.
ROLES - A list of roles that are currently active. (Assigned to the currently logged in user).
Language attributes:
LANGUAGE - The language tag representing the current language.
NLS_LANG - The two-letter database language code. Derived from the language.
NLS_LANGUAGE - The database language. Derived from the language.
NLS_SORT - String sorting logic in database. This is from linguistic sorting support project.
TERRITORY - Listed above as part of the customization context.
DATE_FORMAT - Format mask pattern for date parsing and formatting.
TIME_FORMAT - Format mask pattern for time parsing and formatting. This includes time zone formatting.
GROUPING_SEPARATOR - Grouping separator for number formatting.
DECIMAL_SEPARATOR - Decimal separator for number formatting.
TIME_ZONE - User's preferred time zone in Oracle E-Business Suite (EBS) R12.
CURRENCY - The current currency code.
CLIENT_ENCODING - Client native encoding used for file uploading, downloading, export, and attachment.
Note:
All language context attributes are handled using Java conventions, except for those that are explicitly prefixed with
NLS. For example, getLanguage() returns en-US (corresponding to "AMERICAN" in the database) and getDateFormat() returns dd-MMM-yy (corresponding to DD-MON-RR in the database).Miscellaneous attributes:
TRACE_LEVEL - The current tracing level when tracing is turned on.
MODULE - Stores the current module for tracing purposes.
ACTION - Stores the current action, such as page, being taken for tracing.
ACCESSIBILITY_MODE - The current accessibility mode.
The stored name-value pairs are partitioned into separate namespaces. Oracle Fusion Applications creates namespaces to store the context attributes.
Note:
The actual names of these namespaces and which attributes are used in which namespace is an implementation detail that you do not need to be aware of.Developers can access the attribute-storage namespaces through the standard APIs that are detailed below.
Developers may also choose to define their own namespaces, especially if they have a number of attributes they wish to store on the session. Developer may currently choose among the following APIs for initializing namespaces:
Java: ApplSession.initializeNamespace(String namespaceName)
PL/SQL: fnd_global.initialize_namespace (namespace_name IN VARCHAR2);
The Java and PL/SQL initializeNamespace routines are identical, just invoked from different layers—these will dynamically create a new namespace associated with the currently attached session, which you can then access and retrieve session attributes from for the duration of that session.
In Java, the applications context is accessed through the ApplSession.java and ApplSessionUtil.java classes, which can be found in the oracle.apps.fnd.applcore.common package. Each of the attributes listed above have corresponding APIs in the ApplSession class, along with a corresponding static API in the ApplSessionUtil class for easier access.
For more information, see the javadoc included with Oracle Fusion Middleware Extensions for Applications libraries.
Because it is not possible to authenticate users in the PLSQL layer, the API to initialize a session in PS/SQL is only expected to be called for testing. In order to use sessions, you must first configure your project to use application user sessions. For more information about configuring your project, see Section 48.2, "Configuring Your Project to Use Application User Sessions."
After you have configured your project to use application user sessions, you should be able to access sessions automatically if you are running a J2EE page.
For J2SE programs, such as JUnit tests, you must call an explicit API to initialize your session. As Example 48-2 shows, for JUnit tests in particular, this is most likely your setUp() or setUpBeforeClass() method along with a terminateSession call in the corresponding tearDown() or tearDownAfterClass() method.
Example 48-2 Initializing Your Session
@BeforeClass
public static void setUpBeforeClass()
throws exception
{
//
// Create a session for the OPERATIONS user
//
List<String> roleGuids = new ArrayList<String>(1);
List<String> roleNames = new ArrayList<String>(1);
roleGuids.add("1807EDD02DBB11DDBFDC91643D402C34");
roleNames.add("operationsRole");
ApplSession session =
ApplSessionUtil,initializeSession("43B84790D5F011DCAF4F5FFD8462C8E7",
"OPERATIONS", roleGuids, roleNames, null);
}
@AfterClass
public static void tearDownAfterClass()
throws exception
{
//
// note that if a connection to the 'initializeSession' call had been passed
// in, it would would have to be freed here. Since null is passed in, the
// connection that was obtained in that call will be freed automatically.
//
ApplSessionUtil.terminateSession();
}
Caution:
Remember, every call toinitializeSession should have a corresponding terminateSession invoked after the code completes.Accessing a context attribute is simple. First, make sure your project is configured to use application user sessions and then import the ApplSession and ApplSessionUtil classes. As Example 48-3 shows, after you complete those tasks you can access the session and its properties using the static APIs that are provided.
Example 48-3 Accessing the Session
ApplSession session = ApplSessionUtil.getSession(); String guid1 = session.getUserGuid(); String guid2 = ApplSessionUtil.getUserGuid();
Using the example, guid1 and guid2 should both return the same value. The ApplSessionUtil API is a convenience method that essentially calls the same code as the first two lines. One difference is that ApplSessionUtil.getUserGuid() raises an exception if the session is not available. This is true for all the ApplSessionUtil get methods, except for getSession(), which just returns null if there is no session.
All of the centrally maintained attributes listed above have corresponding get APIs available. Example 48-4 shows a mechanism for getting generic attributes.
Example 48-4 Getting Generic Attributes
String attr1 = ApplSessionUtil.getSessionAttribute("ATTRIBUTE1");
Example 48-5 shows the API you use to fetch attributes from a particular namespace.
In addition to providing getters for all of the context attributes listed above, there are corresponding set APIs directly available in the ApplSession class. Attributes like the user name or the language are set automatically on the context at creation time, but the set APIs can also be called if an attribute needs to be changed in the middle of the request.
Example 48-6 sets the PRODUCT_FAMILY attribute to FND and also sets a generic attribute called ATTRIBUTE1 to VALUE1 on both the session and a private namespace using the Java APIs.
Example 48-6 Setting Context Attributes
ApplSession session = ApplSessionUtil.getSession();
if (session != null)
{
session.setProductFamily("FND");
session.setSessionAttribute("ATTRIBUTE1", "VALUE1");
session.setNamespaceAttribute("MY$NAMESPACE", "ATTRIBUTE1", "VALUE1");
}
Note:
Sets ofApplSession attributes get cached in the middle tier, and only written to the database when the session is detached or the ApplSession.synchronize() method is explicitly called. If the set operation takes place from within a request, synchronization will happen automatically. However, if you are running standalone java or need the attributes to get written to the database immediately, you should add a call to session.synchronize().The applications context does not hold onto connections, instead it obtains and releases them as needed. As Example 48-7 shows, if your application explicitly obtains a connection via the ApplSession.getConnection() API, you will need to add a finally block that releases that connection. It is recommended that you call the newly provided ApplSession.releaseConnection(Connection conn) API as it takes care of clearing out session-specific PL/SQL state in the connection before closing it.
To access the context in your Java code, just call any of the static methods in the ApplSessionUtil class. As long as you are running from an environment where application user sessions are enabled, there should not be anything else you need to do aside from importing the ApplSessionUtil class.
Tip:
If you are running without application user sessions enabled, an exception will be thrown when any of the above calls are made with the exception of thegetSession() API. This API returns a null if sessions are not enabled.The following is a more complex example of how you might use this:
You have a view object (TestVO) where you want to always display the current user name as one of the fields.
To always display the current user name as one of the fields:
Add a non-column based UserName attribute to the TestVO object.
Generate the View Row Class for the view object.
Look for the definition of getUserName(). As shown in Example 48-8, change it to return the value of the call to ApplSessionUtil.getUserName() in the TestVORowImpl.java that gets autogenerated.
Example 48-8 Changing the getUserName() Value
public String getUserName()
{
return ApplSessionUtil.getUserName();
}
Whenever the TestVO view object is displayed, by default it will include the current user name field.
Example 48-9 uses the SysadminInfo field that was added to the TestVO view object to display a value when running the FND product.
The applications context can also be accessed through APIs that are provided in the FND_GLOBAL package. As in Java, functions exist to get and to set each of the core attributes listed in Section 48.3, "Accessing Properties of the Applications Context," assuming you have initialized the connection to use sessions properly. For detailed information about the FND_GLOBAL package, see the javadoc.
The FND_GLOBAL.INITIALIZE_SESSION takes in the user GUID, the user name, and two lists of roles. The first represents the list of role GUIDs, and the second represents the list of corresponding role names. As Example 48-10 shows, the lists must be of the same length.
Example 48-10 Initializing Sessions
DECLARE
1_roleguids FND_TABLE_OF_VARCHAR2_4000 := FND_TABLE_OF_VARCHAR2_4000();
1_rolenames FND_TABLE_OF_VARCHAR2_4000 := FND_TABLE_OF_VARCHAR2_4000();
BEGIN
1_roleguids.extend(1);
1_rolenames.extend(1);
1_roleguids(1) := '1807EDD02DBB11DDBFDC91643D402C34';
1_rolenames(1) := 'operationsRole';
fnd_global.initialize_session('43B84790D5F011DCAF4F5FFD8462C8E7','OPERATIONS', 1_roleguids, 1_rolenames);
<your code here>
fnd_global.terminate_session;
END;
/
As an example, you can retrieve the current user by calling FND_GLOBAL.USER_NAME, and you can get a generic attribute by calling FND_GLOBAL.GET_SESSION_ATTRIBUTE.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|