Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 4 (11.1.4)

Part Number E15524-09
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Feedback page
Contact Us

Go to previous page
Go to next page
PDF · Mobi · ePub

48 Implementing Application User Sessions

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:

48.1 Introduction to Application User Sessions

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 48.3, "Accessing Properties of the Applications Context."

48.2 Configuring Your Project to Use Application User Sessions

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.

48.2.1 How to Configure Your Project to Use Application User 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 48, "Implementing Application User Sessions."

You may need to complete these tasks:

To configure your project to use application user sessions:

  1. 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.

  2. 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

  3. 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

       <servlet-name>Faces Servlet</servlet-name>

    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.

  4. 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 50.3, "Adding Function Security to the Application."

48.2.2 How to Configure the ADF Business Component Browser

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, "Initializing Sessions."

48.2.3 How to Use the ApplSession Logger for Troubleshooting

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.

48.2.4 What Happens at Runtime: How the Application User Session is Used

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 50.3, "Adding Function Security to the Application."

48.3 Accessing Properties of the Applications Context

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:

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:

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:

Language attributes:


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:

The stored name-value pairs are partitioned into separate namespaces. Oracle Fusion Applications creates namespaces to store the context attributes.


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:

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.

48.3.1 How to Access Sessions Using Java APIs

In Java, the applications context is accessed through the and 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. Initializing Sessions

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 Java EE 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

  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);
    ApplSession session = 
                                        "OPERATIONS", roleGuids, roleNames, null);

  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.


Remember, every call to initializeSession should have a corresponding terminateSession invoked after the code completes. Getting Context Attributes

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.

Example 48-5 Fetching Attributes From A Particular Namespace

String attr1 = ApplSessionUtil,getNamespaceAttribute("MY$NAMESPACE", "ATTRIBUTE1"); Setting Context Attributes

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.setSessionAttribute("ATTRIBUTE1", "VALUE1");
    session.setNamespaceAttribute("MY$NAMESPACE", "ATTRIBUTE1", "VALUE1");


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(). Accessing the Connection

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.

Example 48-7 Accessing the Connection of the Current ApplSession

Connection conn = null;
ApplSession session = ApplSessionUtil.getSession();
if (session != null)
      conn = session.getConnection();
      if (conn != null)
} Accessing Session Context Using the Java API

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.


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:

  1. Add a non-column based UserName attribute to the TestVO object.

  2. Generate the View Row Class for the view object.

  3. 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 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.

Example 48-9 TestVO Example

public String getSysAdminInfo()
  String productName = ApplSessionUtil.getProduct();
  if ("FND".equals(productName))
    return (String) getAttributeInternal(SYSADMININFO);
    return null;

48.3.2 How to Access Sessions Using PL/SQL APIs

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. Initializing Sessions

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

  1_roleguids FND_TABLE_OF_VARCHAR2_4000 := FND_TABLE_OF_VARCHAR2_4000();
  1_rolenames FND_TABLE_OF_VARCHAR2_4000 := FND_TABLE_OF_VARCHAR2_4000();
  1_roleguids(1) := '1807EDD02DBB11DDBFDC91643D402C34';
  1_rolenames(1) := 'operationsRole';
  fnd_global.initialize_session('43B84790D5F011DCAF4F5FFD8462C8E7','OPERATIONS', 1_roleguids, 1_rolenames);
  <your code here>
/ Getting Context Attributes

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. Setting Context Attributes

As an example, you can set the language by calling FND_GLOBAL.SET_LANGUAGE, and you can set a generic attribute by calling FND_GLOBAL.SET_SESSION_ATTRIBUTE.