Oracle® Fusion Applications Developer's Guide 11g Release 5 (11.1.5) Part Number E15524-10 |
|
|
PDF · Mobi · ePub |
This chapter describes how to implement application user sessions in an Oracle Fusion application to allow applications to store security and application context on the user session.
This chapter includes the following sections:
Section 47.2, "Configuring Your Project to Use Application User Sessions"
Section 47.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. When the application user session is implemented, the Oracle Fusion 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.
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 47.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.
Before you begin:
It may be helpful to have an understanding of application user sessions. For more information, see Chapter 47, "Implementing Application User Sessions."
You may need to complete these tasks:
If you have any web services projects, you must configure them to maintain the application user session across the web service request. For more information, see Section 50.7, "Maintaining Application Session Context Across Web Service Requests."
If you have any portlet projects, you must configure them to maintain the application user session across the web service request. For more information, see Section 51.5, "Maintaining Application Session Context Across Web Service Requests."
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 47-1 shows the ApplSessionFilter
mapping definition to add.
Example 47-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 47.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 47.3.2.1, "Initializing Sessions."
One of the most useful diagnostic tools for applications configured for application user sessions is the ApplSession logger. The specific logger for application users sessions logging is named oracle.apps.fnd.applcore.common.session
(also called the ApplSession logger). You use this logger to capture runtime traces messages that are specific to application user sessions. By default, the logger records messages at the WARNING
level. If you need to log additional details as part of troubleshooting, you can increase the ApplSession log level to adjust the amount of information that is recorded. For example, more detailed information may help you to quickly identify the origin of an application user sessions error.
In JDeveloper, when you configure a logger and run the application, JDeveloper displays runtime messages recorded by the logger in the Log window and a system log file. You configure logging in JDeveloper using the editor for Oracle Diagnostic Logging Configuration. After you have created a log, you can view and filter the log messages with Oracle Diagnostic Log Analyzer. This tool allows you to set filters for different log levels, define message time frames, and search on message text. For more information about these JDeveloper log tools, see the "Testing and Debugging ADF Components" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
After the application is deployed to standalone Oracle WebLogic Server, a system administrator uses Oracle Enterprise Manager Fusion Applications Control to adjust the log level and to view the logger's recorded messages. The system administrator may increase the ApplSession log level to gather detailed information for a particular managed server. For more information about adjusting log levels for the ApplSession logger, using Fusion Applications Control, see "Adjusting ApplSession Log Levels for Troubleshooting" in the Oracle Fusion Applications Administrator's Guide.
For information about Oracle Fusion Middleware logging functionality, see the "Managing Log Files and Diagnostic Data" chapter of the Oracle Fusion Middleware Administrator's Guide.
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 47.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 47.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 Java EE page.
For J2SE programs, such as JUnit tests, you must call an explicit API to initialize your session. As Example 47-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 47-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 to initializeSession
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 47-3 shows, after you complete those tasks you can access the session and its properties using the static APIs that are provided.
Example 47-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 47-4 shows a mechanism for getting generic attributes.
Example 47-4 Getting Generic Attributes
String attr1 = ApplSessionUtil.getSessionAttribute("ATTRIBUTE1");
Example 47-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 47-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 47-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 of ApplSession
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 47-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 the getSession()
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 47-8, change it to return the value of the call to ApplSessionUtil.getUserName()
in the TestVORowImpl.java
that gets autogenerated.
Example 47-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 47-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 47.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 47-10 shows, the lists must be of the same length.
Example 47-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
.