EBS Software Development Kit For Java R11i and 12

Oracle E-Business Suite
Software Development Kit for Java Release 11i and 12

Part No. E28169-02
June 2012
Oracle E-Business Suite Software Development Kit for Java, Release 11i and 12 Part No. E28169-02 Copyright 2009, 2012, Oracle and/or its affiliates. All rights reserved. Primary Author: Sara Woodhull Contributor: Deepika Annavarapu, Mamata Challagulla, Nitu Chiring, Rajesh Ghosh, Sunil Ghosh, Clara Jaeckel, Pandurang Kamble, Duncan Mills, Vijayakumar Nagarajan, Frank Nimphius, Juan Camilo Ruiz; Shay Shmeltzer; Veshaal Singh, Sukanya Tadepalli Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Contents
Send Us Your Comments Preface 1 Introduction to Oracle E-Business Suite SDK for Java
Introduction............................................................................................................................... 1-1 Prerequisite Patches for Oracle E-Business Suite Instance...................................................... 1-3 Instructions for Applying this Patch........................................................................................ 1-4
Using Oracle E-Business Suite Data Sources

Overview of Using AppsDataSource and AppsXADataSource............................................... 2-1 2.1. Configuring AppsDataSource............................................................................................ 2-2 2.1.2. Register the External Node and Generate the Desktop DBC File...................................2-3 2.1.3. Set Up Necessary Oracle E-Business Suite Users............................................................ 2-5 2.1.4. Configuring AppsDataSource on an OC4J Instance....................................................... 2-9 2.1.5. Configuring AppsDataSource on Oracle WebLogic Server (WLS)...............................2-20 2.2. Using AppsDataSource Directly from Java Programs..................................................... 2-31
3 Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3.1 Overview of Using the JAAS Feature.................................................................................. 3-1 3.2 Configuring JAAS................................................................................................................ 3-5 3.3 JAAS Configuration for Oracle WebLogic Server ............................................................. 3-7 3.4 JAAS Configuration for OC4J........................................................................................... 3-37
iii
Utilities
4.1. Automated Setup Script...................................................................................................... 4-1 4.2. AdminDesktop Utility........................................................................................................ 4-4 4.2.1. AdminDesktop Usage Examples..................................................................................... 4-4
Using Lightweight Java Error Logging with Oracle E-Business Suite

5.1. Existing Logging Framework in Oracle E-Business Suite................................................. 5-1 5.6. Logging Configuration....................................................................................................... 5-6
Session Management
Session Management................................................................................................................. 6-1 Session Management Classes and APIs................................................................................... 6-2
Message Dictionary
Using Message Dictionary Routines.........................................................................................7-1
User Profiles
User Profiles.............................................................................................................................. 8-1
Navigation to External Applications

Launching an External Application from the Oracle E-Business Suite Home Page................9-1
10
Java EE Session Management Tutorial

Java EE Session Management Tutorial................................................................................... 10-1 About the Tutorial Application.............................................................................................. 10-1 Building the Tutorial Application.......................................................................................... 10-3
iv

Send Us Your Comments
Oracle E-Business Suite Software Development Kit for Java, Release 11i and 12
Part No. E28169-02
Oracle welcomes customers' comments and suggestions on the quality and usefulness of this document. Your feedback is important, and helps us to best meet your needs as a user of our products. For example: Are the implementation steps correct and complete? Did you understand the context of the procedures? Did you find any errors in the information? Does the structure of the information help you with your tasks? Do you need different information or graphics? If so, where, and in what format? Are the examples correct? Do you need more examples?
If you find any errors or have any other suggestions for improvement, then please tell us your name, the name of the company who has licensed our products, the title and part number of the documentation and the chapter, section, and page number (if available). Note: Before sending us your comments, you might like to check that you have the latest version of the document and if any concerns are already addressed. To do this, access the new Oracle E-Business Suite Release Online Documentation CD available on My Oracle Support and www.oracle.com. It contains the most current Documentation Library plus all documents revised or released recently. Send your comments to us using the electronic mail address: appsdoc_us@oracle.com Please give your name, address, electronic mail address, and telephone number (optional). If you need assistance with Oracle software, then please contact your support representative or Oracle Support Services. If you require training or instruction in using Oracle software, then please contact your Oracle local office and inquire about our Oracle University offerings. A list of Oracle offices is available on our Web site at www.oracle.com.

Preface
Intended Audience
Welcome to Release 11i and 12 of the Oracle E-Business Suite Software Development Kit for Java. This guide assumes you have a working knowledge of the following: The principles and customary practices of your business area. Computer desktop application usage and terminology.
If you have never used Oracle E-Business Suite, we suggest you attend one or more of the Oracle E-Business Suite training classes available through Oracle University. See Related Information Sources on page viii for more Oracle E-Business Suite product information.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Structure
1 Introduction to Oracle E-Business Suite SDK for Java
vii
This chapter introduces the Oracle E-Business Suite SDK for Java, which is contained in Patch 13882058. This chapter also covers the prerequisites and installation of the patch. The Oracle E-Business Suite SDK for Java includes AppsDataSource, Java Authentication and Authorization Service, and Utilities for Oracle E-Business Suite.
2 Using Oracle E-Business Suite Data Sources
The AppsDataSource and AppsXADataSource standard data sources enable access to the Oracle E-Business Suite APPS database schema from external Java EE environments without requiring sharing of the password for the APPS schema (database user).
3 Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 4 Utilities 5 Using Lightweight Java Error Logging with Oracle E-Business Suite 6 Session Management 7 Message Dictionary 8 User Profiles 9 Navigation to External Applications 10 Java EE Session Management Tutorial
Related Information Sources

This book is included in the Oracle E-Business Suite Documentation Library, which is supplied in the Release 12.2 Media Pack. If this guide refers you to other Oracle E-Business Suite documentation, use only the latest Release 12.2 versions of those guides. Online Documentation All Oracle E-Business Suite documentation is available online (HTML or PDF). Online Help - Online help patches (HTML) are available on My Oracle Support. PDF Documentation - See the Oracle E-Business Suite Documentation Library for current PDF documentation for your product with each release. Release Notes - For information about changes in this release, including new features, known issues, and other details, see the release notes for the relevant product, available on My Oracle Support. Oracle Electronic Technical Reference Manual - The Oracle Electronic Technical Reference Manual (eTRM) contains database diagrams and a detailed description of database tables, forms, reports, and programs for each Oracle E-Business Suite product. This information helps you convert data from your existing applications and integrate Oracle E-Business Suite data with non-Oracle applications, and write custom reports for Oracle E-Business Suite products. The Oracle eTRM is available on My Oracle Support.
Related Guides You should have the following related books on hand. Depending on the requirements
viii
of your particular installation, you may also need additional manuals or guides. Oracle Application Framework Developer's Guide This guide contains the coding standards followed by the Oracle E-Business Suite development staff to produce applications built with Oracle Application Framework. This guide is available in PDF format on My Oracle Support and as online documentation in JDeveloper 10g with Oracle Application Extension. Oracle E-Business Suite Developer's Guide This guide contains the coding standards followed by the Oracle E-Business Suite development staff. It describes the Oracle Application Object Library components needed to implement the Oracle E-Business Suite user interface described in the Oracle E-Business Suite User Interface Standards for Forms-Based Products. It provides information to help you build your custom Oracle Forms Developer forms so that they integrate with Oracle E-Business Suite. In addition, this guide has information for customizations in features such as concurrent programs, flexfields, messages, and logging. Oracle E-Business Suite System Administrator's Guide Documentation Set This documentation set provides planning and reference information for the Oracle E-Business Suite System Administrator. Oracle E-Business Suite System Administrator's Guide - Configuration contains information on system configuration steps, including defining concurrent programs and managers, enabling Oracle Applications Manager features, and setting up printers and online help. Oracle E-Business Suite System Administrator's Guide - Maintenance provides information for frequent tasks such as monitoring your system with Oracle Applications Manager, administering Oracle E-Business Suite Secure Enterprise Search, managing concurrent managers and reports, using diagnostic utilities including logging, managing profile options, and using alerts. Oracle E-Business Suite System Administrator's Guide - Security describes User Management, data security, function security, auditing, and security configurations.
Do Not Use Database Tools to Modify Oracle E-Business Suite Data

Oracle STRONGLY RECOMMENDS that you never use SQL*Plus, Oracle Data Browser, database triggers, or any other tool to modify Oracle E-Business Suite data unless otherwise instructed. Oracle provides powerful tools you can use to create, store, change, retrieve, and maintain information in an Oracle database. But if you use Oracle tools such as SQL*Plus to modify Oracle E-Business Suite data, you risk destroying the integrity of your data and you lose the ability to audit changes to your data. Because Oracle E-Business Suite tables are interrelated, any change you make using an Oracle E-Business Suite form can update many tables at once. But when you modify Oracle E-Business Suite data using anything other than Oracle E-Business Suite, you may change a row in one table without making corresponding changes in related tables. If your tables get out of synchronization with each other, you risk retrieving erroneous information and you risk unpredictable results throughout Oracle E-Business Suite.
ix
When you use Oracle E-Business Suite to modify your data, Oracle E-Business Suite automatically checks that your changes are valid. Oracle E-Business Suite also keeps track of who changes information. If you enter information into database tables using database tools, you may store invalid information. You also lose the ability to track who has changed your information because SQL*Plus and other database tools do not keep a record of changes.
1
Introduction to Oracle E-Business Suite SDK for Java
This chapter introduces the Oracle E-Business Suite SDK for Java, which is contained in Patch 13882058. This chapter also covers the prerequisites and installation of the patch. The Oracle E-Business Suite SDK for Java includes AppsDataSource, Java Authentication and Authorization Service, and Utilities for Oracle E-Business Suite. This chapter covers the following topics: Introduction Prerequisite Patches for Oracle E-Business Suite Instance Instructions for Applying this Patch
Introduction
The Oracle E-Business Suite Software Development Kit (SDK) for Java is a library that provides lightweight APIs for integrating external Java EE applications with Oracle E-Business Suite. These external Java EE programs typically reside on an external server/node that is not co-located with the Oracle E-Business Suite middle tier installation. External applications cannot use the Java APIs normally used in modules developed using Oracle Application Framework (OAF), for example, because those APIs are heavily dependent on many other parts of the Oracle E-Business Suite code and require a full middle tier installation of the Oracle E-Business Suite.
Features
The Oracle E-Business Suite SDK for Java includes the following features: AppsDataSource Java Authentication and Authorization Service (JAAS) Error logging
Introduction to Oracle E-Business Suite SDK for Java 1-1
Session Management APIs Internationalization APIs Message Dictionary APIs Profile Options Navigation
Use Cases
The uses of the Oracle E-Business Suite SDK for Java fall into two general use cases for integrating external applications with Oracle E-Business Suite: Application sharing a session with Oracle E-Business Suite Independent application (not shared session)
With an independent application, the external application accesses Oracle E-Business Suite data and server-side APIs, but it has a completely separate user interface. The external application may also launch pages from the Oracle E-Business Suite home page, but after the initial launch there is no further communication with the Oracle E-Business Suite user interface. Shared session integration, for the purposes of this document, means that the external application seems as if it is part of the Oracle E-Business Suite. The application uses an Oracle E-Business Suite session (ICX session), shares session context information with Oracle E-Business Suite, and accesses Oracle E-Business Suite data. The external application may also launch pages from the Oracle E-Business Suite home page, or regions or pages from the external application may be embedded as regions with Oracle Application Framework pages. Both shared session applications and independent applications use the AppsDataSource feature of the Oracle E-Business Suite SDK for Java. Independent applications may also use the Java Authentication and Authorization (JAAS) and logging features of the SDK. Applications that are sharing the Oracle E-Business Suite session use the session management feature (instead of the JAAS feature), and they may also use the logging, profiles, and Message Dictionary features of the SDK.
Independent Application AppsDataSource JAAS Shared Session Application AppsDataSource Session Management
1-2 Oracle E-Business Suite Software Development Kit for Java
Error Logging
Error Logging Profile Options Message Dictionary
Building External Applications with Oracle ADF

External applications can be built with any appropriate Java EE framework, including Oracle Application Development Framework (ADF). Because Oracle ADF is a declarative framework, this document includes specific instructions for using Oracle ADF with Oracle WebLogic Server for some features. This document has been written using version 11.1.1.5 of Oracle ADF with version 10.3.5 of Oracle WebLogic server.
Audience
This document applies to both Java developers building external applications and administrators configuring the external applications on the system. Java developers are expected to have familiarity with at least the following: Java Server Pages (JSP), servlet, servlet filters, and deployment descriptors. See http://docs.oracle.com/javaee/6/tutorial/doc/bnafd.html for an overview of Servlets and Filters. Java Authentication and Authorization (JAAS). See http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide. html for an overview of JAAS. Java logging. See http://docs.oracle.com/javase/1.4.2/docs/guide/util/logging/overview.html for an overview of Java Logging and http://docs.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html for API specification.
Administrators should be familiar with configuring and using the appropriate application server, such as Oracle WebLogic Server or OC4J.
Prerequisite Patches for Oracle E-Business Suite Instance

This document covers the contents of the Oracle E-Business Suite SDK for Java, which is contained in Patch 13882058 (replacing Patch 13562125). The SDK includes AppsDataSource, Java Authentication and Authorization Service, and Utilities for Oracle E-Business Suite. These features are meant for use with Java EE programs
Introduction to Oracle E-Business Suite SDK for Java 1-3
deployed in application servers on external nodes, that is, nodes other than those where the Oracle E-Business Suite is installed. For Oracle Applications Technology 11i.ATG_PF.H.delta.6 (11i RUP 6), apply Patch 6930112. No patches are needed for higher versions of Release 11i. For Oracle Applications Technology Update Pack 4 for Release 12.0 (12 RUP 4) or Oracle Applications Technology Update Pack 5 for Release 12.0 (12 RUP 5), apply Patch 7319110 (compatible with R12.FND.A). For Oracle Applications Technology Update Pack 4 for Release 12.0 (12 RUP 4) or higher, apply Patch 12715586 (compatible with R12.FND.A). For Release 12.1 (Release 12.1.1 or higher), apply Patch 12715586 (compatible with R12.FND.B).
Instructions for Applying this Patch

This patch is applicable for both Oracle E-Business Suite Release 11i and Release 12 (that is, this patch is release independent assuming the prerequisites above are met). JVM dependency: This patch works only for JRE 1.5 and above.
1.
Download Patch 13882058 from My Oracle Support and unzip the patch zip file. The zip file contains: The Oracle E-Business Suite SDK for Java file, fndext.jar README.txt Javadoc for Oracle E-Business Suite SDK for Java An Apache Ant XML file named txkEbsSdkConfig.xml
2.
Copy the extracted fndext.jar file and the txkEbsSdkConfig.xml file to a directory such as/home/user1/ebssdk on the external application server machine. Copy the Javadoc to any appropriate location for convenient reference.
2
Using Oracle E-Business Suite Data Sources
The AppsDataSource and AppsXADataSource standard data sources enable access to the Oracle E-Business Suite APPS database schema from external Java EE environments without requiring sharing of the password for the APPS schema (database user). This chapter covers the following topics: Overview of Using AppsDataSource and AppsXADataSource 2.1. Configuring AppsDataSource 2.1.2. Register the External Node and Generate the Desktop DBC File 2.1.3. Set Up Necessary Oracle E-Business Suite Users 2.1.4. Configuring AppsDataSource on an OC4J Instance 2.1.5. Configuring AppsDataSource on Oracle WebLogic Server (WLS) 2.2. Using AppsDataSource Directly from Java Programs
Overview of Using AppsDataSource and AppsXADataSource

The AppsDataSource and AppsXADataSource standard data sources enable access to the Oracle E-Business Suite APPS database schema from external Java EE environments without requiring sharing of the password for the APPS schema (database user). Since the APPS database password is typically changed frequently, using these data sources insulates such programs from having to change their authentication information. Using these data sources also helps prevent wide exposure of the APPS password. When using the AppsDataSource feature, access to the APPS database is controlled using a dedicated Oracle E-Business Suite user name and password ("applications user", also known as an "FND user") instead of the APPS password. The specific applications user must be set up with the UMX|APPS_SCHEMA_CONNECT role and should not be used for any other purpose other than providing connectivity through AppsDataSource. Note that even though the APPS password is not explicitly shared,
Using Oracle E-Business Suite Data Sources 2-1
programs or users with access to the AppsDataSource will still be able to connect to the Oracle E-Business Suite as the APPS database user, so access to the AppsDataSource should be tightly controlled. Using the standard data sources lets you control access to the Oracle E-Business Suite data at the APPS schema level. For example, you can use AppsDataSource with BPEL processes and Oracle Service Bus services in Oracle Fusion Middleware. You may also use AppsDataSource as a standard datasource for Oracle ADF 11g applications (see My Oracle Support Document 1296491.1, "FAQ for Integration of Oracle E-Business Suite and Oracle Application Development Framework (ADF) Applications"). You use AppsDataSource to control an entire external application's access to the Oracle E-Business Suite database APPS schema. By contrast, if you are trying to control an individual user's access to the Oracle E-Business Suite at the application user level, you would use the Oracle E-Business Suite implementation of Java Authentication and Authorization Service (JAAS), page 3-1 or a shared session with Oracle E-Business Suite, where a user would use their individual credentials to access the functions they are authorized to use.
2.1.1. Local and Global Transactions (XA Data Sources)

You can set up local transactions that require a single resource, such as an Oracle E-Business Suite database. You can also set up global transactions that use multiple resources, such as an Oracle E-Business Suite database plus a Java Message Service (JMS) resource. For global transactions, the datasource implementation supports X/Open XA, a standard for distributed transaction processing from The Open Group (http://www.opengroup.org/). In this document, we refer to both the XA data source (AppsXADataSource) and the non-XA data source (AppsDataSource) collectively as AppsDataSource, except the few places where their setup steps are different, in which case we refer to them separately.
2.1. Configuring AppsDataSource

There are multiple ways to set up and use an AppsDataSource. You can configure and use an AppsDataSource: directly from a Java program (see Using AppsDataSource Directly from Java, page 2-31) in an application server such as OC4J, page 2-9 or Oracle WebLogic Server, page 2-20
Before you configure an AppsDataSource either in a Java program or an application server, your Oracle E-Business Suite system administrator must first:
1.
Register the external node
2. 3.
Generate the desktop DBC file. Set up a specific application user with the UMX|APPS_SCHEMA_CONNECT role.
Once the Oracle E-Business Suite system administrator has completed those tasks, you can set up the AppsDataSource. All the class files required for setting up the AppsDataSource and registering your external nodes are contained in the library file fndext.jar. If you are using Oracle WebLogic Server on UNIX/Linux to create a non-XA data source, you can use the Apache Ant XML file txkEbsSdkConfig.xml, page 4-1 to set up your data source automatically from the command line. For other configurations such as OC4J or Oracle WebLogic Server on Windows, or for an AppsXADataSource, you must follow the manual steps described in the following sections.
2.1.2. Register the External Node and Generate the Desktop DBC File
The external application server (or middle tier machine where a Java program will run) must be registered with the Oracle E-Business Suite database using the AdminDesktop utility contained in fndext.jar before the application server can connect to the database. The AdminDesktop utility uses as input a standard Oracle E-Business Suite DBC file generated by the system administrator. For Oracle E-Business Suite 11i, the DBC file is typically located under $FND_TOP/secure. For Release 12, the DBC file is typically located under $FND_SECURE. If the DBC file does not exist, the system administrator should generate it using Autoconfig. See the Oracle E-Business Suite System Administrator's Guide - Configuration for more information on the DBC file. Because the AdminDesktop utility requires the password for the APPS schema, the utility must be run by the Oracle E-Business Suite system administrator. AdminDesktop should be run from the Oracle E-Business Suite instance (that is, where all the instance's Java class files reside under $JAVA_TOP).
Note: If the Oracle E-Business Suite application server and Oracle
WebLogic Server are running on the same physical machine (not recommended, but occasionally done for development purposes), then you should use the standard DBC file instead of the one created by AdminDesktop.
To register the external server with the Oracle E-Business Suite instance, the system administrator should run the following command, passing the name of the external application server node.
java oracle.apps.fnd.security.AdminDesktop <apps user>/<apps pwd> \ CREATE \ NODE_NAME=<node name of the external application server> \ [IP_ADDRESS=<IP address of external application server>] \ DBC=<full name and path of existing standard dbc_file>
The CREATE command should only be run once for a given node. If the node has already been registered with the Oracle E-Business Suite instance, use the UPDATE command instead. The resulting desktop DBC file contains the registration information required to connect to the Oracle E-Business Suite database. The DBC file passed in using the DBC argument should be a standard DBC file generated by the Oracle E-Business Suite system administrator using Autoconfig. The AdminDesktop utility generates the desktop DBC file with its name set to the standard DBC file name plus the name of the node, for example, host_port_node.dbc. See AdminDesktop Utility, page 4-4 for more information on the AdminDesktop utility. You must also set the following profile options to correspond to the information in the desktop DBC file:
Profile Option Name FND: Validate User Type Profile Option Code FND_SERVER_SEC Recommended Setting Desktop Only (internal value D) at the site level Desktop Only (internal value D) at the site level <comma separated list of external nodes for which IP restriction is required> For example: NODENAME1, NODENAME2 where NODENAME1 and NODENAME2 are values for column NODE_NAME in the fnd_nodes table for the desktop nodes. Set this option at the user level for the user with the Apps Schema Connect role (that is, the AppsDataSource user).
FND: Validate IP address
FND_SERVER_IP_SEC
FND: Desktop Nodes allowed
FND_SERVER_ DESKTOP_USER
If you are unable to find these profile options in the Profiles page (Functional Administrator Responsibility) or the System Profiles form (System Administrator responsibility), verify that Patch 12715586 has been applied to your system. In addition, be sure to activate the application server security system by setting the server_id='SECURE' for the AUTHENTICATION node in the fnd_nodes table (the row returned by select * from fnd_nodes where server_address ='*' ) using
AutoConfig:
1.
Make a backup copy of the $APPL_TOP/admin/<SID>_ <hostname >.xml context file. Edit the file and locate the following context variable: s_appserverid_authentication Set the parameter equal to SECURE Run Oracle E-Business Suite AutoConfig to instantiate the changes. See My Oracle Support Knowledge Document 387859.1, "Using AutoConfig to Manage System Configurations with Oracle E-Business Suite Release 12" or My Oracle Support Knowledge Document 165195.1, "Using AutoConfig to Manage System Configurations with Oracle Applications 11i".
Warning: The IP address restricts the use of the DBC file to a machine
2.
3. 4.
with that IP address. While the IP_ADDRESS argument is optional (and leaving it out is convenient for development), it must always be included when generating a desktop DBC file for use in a production environment (and the related profile options must also be set correctly). Note that even though the APPS password is not explicitly shared when using AppsDataSource, programs or users with access to the AppsDataSource will still be able to connect to the Oracle E-Business Suite as the APPS database user, with all the abilities of the APPS database user, so access to the DBC files and AppsDataSource should be tightly controlled. For example, when installing the desktop DBC file on the client machine in a production environment, set the desktop DBC file protection so it can only be read by the expected calling program (runtime user).
2.1.3. Set Up Necessary Oracle E-Business Suite Users

Create a limited number of Oracle E-Business Suite users that will be authorized to connect to the Oracle E-Business Suite database. This application user is not intended to be an existing person, but it should be associated with a program (for example, BPEL runtime). The authorization to connect to the Oracle E-Business Suite database is determined by the role UMX|APPS_SCHEMA_CONNECT. A user that has this role will be authorized to connect to the Oracle E-Business Suite database. Within the Oracle E-Business Suite, the system administrator creates these users and assigns the UMX|APPS_SCHEMA_CONNECT role to them. Application users must be initially created using the Users window in the System Administrator responsibility within the Oracle E-Business Suite (Security > Users > Define menu path), shown in the following screenshot. The user meant to have the UMX|APPS_SCHEMA_CONNECT role does not need any assigned responsibilities. For
better security, in fact, this user should not have any roles or responsibilities other than UMX|APPS_SCHEMA_CONNECT. You may want to have a separate dedicated user with the UMX|APPS_SCHEMA_CONNECT role for each external application.
The following screenshot shows the Roles and Role Inheritance page in the User Management responsibility, specifically showing the Apps Schema Connect role. Note that the displayed name of the role is translated, but the UMX|APPS_SCHEMA_CONNECT code stays the same across languages.
The following screenshot shows the Users page in the User Management responsibility. In this example, a search for users with the Apps Schema Connect role displays several users with this role.
Click the Update icon for a particular user to navigate to the Update User page. The Update User page is shown below. Click the Assign Roles button to add more roles for this user.
For more information on setting up application users and assigning roles, see Oracle E-Business Suite System Administrator's Guide - Security.
2.1.4. Configuring AppsDataSource on an OC4J Instance

There are many available options for how to set up the application server and the related components. This document describes only the simplest case, and your setup may be different.
2.1.4.1. Deploy AppsDataSource Code on the OC4J Instance:

The AppsDataSource code must be deployed in the OC4J instance before defining connections. The steps to deploy the AppsDataSource are:
1.
Copy the desktop DBC file and fndext.jar to the external application server where you want to set up AppsDataSource. Create a shared library in the OC4J instance using Oracle Enterprise Manager.
1.
2.
In your browser, navigate to the Oracle Enterprise Manager for your application server:
http://<your host>:<your port>/em
2.
Log in as the OC4J administrator.
3. 4. 5.
Select the desired OC4J instance. Select the Administration tab. Click the Go to Task icon for the Shared Libraries line under Administration Tasks > Properties.
6.
Click the Create button on the Shared Libraries page.
7.
Give the shared library a name and a version (for example: oracle.apps.fnd.appsds, 1.0) and click Next.
8.
Click the Add button.
9.
In the following page, select the appropriate choice for the location of fndext.jar, such as "File is present on the server where Application Server Control is running."
10. Provide the complete path and filename for the location of fndext.jar, and click
Continue.
11. Click Next.
12. Look for the shared library "oracle.jdbc" on the following page, and check the
Import check box for this library.
13. Click Finish.
2.1.4.2. Edit application.xml File on OC4J Application Server:

To finish deploying the AppsDataSource code to your application, you must edit the application.xml file on the application server file system.
1.
Edit the application.xml file to import the data source shared library into the default application
1.
Edit the file located at $ORACLE_HOME/j2ee/<your OC4J name>/config/application.xml Search for the element imported-shared-libraries below the orion-application element. Add a new import-shared-library element under the imported-shared-libraries line as follows:
<import-shared-library name="(name given to the shared library while creating it)">
2.
3.
For example:
<import-shared-library name="oracle.apps.fnd.appsds">
4. 2.
Save the file application.xml.
Restart your OC4J instance.
2.1.4.3. Define the Connection in Oracle Enterprise Manager:

Now that you have deployed the AppsDataSource code to your application, you can define your connection. Create a Connection Pool using Oracle Enterprise Manager:
1.
2. 3. 4.
Log in as the OC4J administrator. Select the OC4J instance. Select the Administration tab.
5.
Click the Go to Task icon for the JDBC Resources line under Administration Tasks > Services.
6.
Click the Create button under the Connection Pools section.
7.
Select "default" for Application and the Connection Pool Type of "New Connection Pool". Click Continue.
8. 9.
Enter a name for your connection pool. For Connection Factory Class enter oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource (or
oracle.apps.fnd.ext.jdbc.datasource.AppsXADataSource for an XA data source).

10. Leave the URL as it is. The URL indicated here is not used by the Connection Pool
Manager.
11. Enter a valid Oracle E-Business Suite username in UPPERCASE for the username.
Enter the password in UPPERCASE. The user should already have the UMX|APPS_SCHEMA_CONNECT role as mentioned previously.
12. Click the Add Another Row button once under Connection Factory Properties. 13. Enter dbcFile in the Name field and the fully-qualified location of the desktop DBC
file in the Value field. For example: /u01/oracle/product/soasuite/apps/thisMidTier.dbc
14. Click Finish.
2.1.4.4. Creating a Data Source using Enterprise Manager:

1.
Return to the Administration tab for your OC4J instance (use the links at the top of the page to return to the OC4J home). Click the Go to Task icon for the JDBC Resources line under Administration Tasks > Services. Click the Create button for the Data Sources section.
2.
3.
4.
Enter "default" under the Application section. Select Managed Data Source under the Data Source Type section. Click Continue.
5.
Enter the following values for the elements on this page:

1. 2.
Name: <your data source name, for example: MyAppsDataSourceDS> JNDI location: <by convention you should enter the standard jdbc/<yourName> for example: jdbc/MyAppsDataSourceDS> Transaction Level: Global & Local Transactions Connection Pool: Select the connection pool you defined in the "Creating a Connection Pool using Enterprise Manager" section above. Login Timeout (seconds): 0
3. 4.
5.
6.
Click Finish.
2.1.4.5. Test Your Connection:

After you see the confirmation that your data source has been created, click the Test Connection icon to test your connection.
2.1.5. Configuring AppsDataSource on Oracle WebLogic Server (WLS)

This section assumes experience with Oracle WebLogic Server. If you are not familiar with Oracle WebLogic Server, you should review the material in the Oracle WebLogic Server Documentation Library before beginning this process. Also, there are many
available options for how to set up the application server and the related components. This document describes only the simplest case, and your setup may be different.
Important: If you plan to use the Oracle E-Business Suite Java
Authentication and Authorization Service (JAAS) feature on Oracle WebLogic Server, you must rebuild the fndext.jar file on the target Oracle WebLogic Server instance first, instead of using the fndext.jar file exactly as it comes from the patch. If you are using other fndext.jar features, such as AppsDataSource or Oracle E-Business Suite lightweight error logging, but you do not plan to use the Oracle E-Business Suite JAAS implementation, rebuilding the fndext.jar file is optional but strongly recommended. Rebuilding the file will not affect those features, but it will make implementation and maintenance simpler to already have the rebuilt file in place if you decide to use JAAS later.
This section is written using Oracle WebLogic Server 10.3.5.0. If you are using a different version of Oracle WebLogic Server, the screens may be different from what is shown in the pictures. If you are using the JAAS feature, you must use Oracle WebLogic Server 10.3.5.0 or higher. Because the rebuilding process is specific to a particular WebLogic Server version, the rebuilt version of the fndext.jar file is meant for use only with that specific environment. Note that you will need to rebuild the fndext.jar file (and put the rebuilt file in the correct locations) any time you install a patch that includes a new version of the fndext.jar file or a new version of Oracle WebLogic Server. If you are using Oracle WebLogic Server on UNIX/Linux, and you are creating a non-XA data source, you can use the Apache Ant XML automation script txkEbsSdkConfig.xml, page 4-1, or you can set up your data source manually by following the steps described below. The txkEbsSdkConfig.xml Ant script can both rebuild the fndext.jar file and set up the AppsDataSource (for a non-XA data source only), as well as set up a security realm if you are using the JAAS feature, page 3-1.
2.1.5.1. Rebuilding the fndext.jar file for Oracle WebLogic Server on UNIX/LINUX:
This step is optional but strongly recommended. See "Important" note, page 2-21 above.
1.
Log in to the Oracle WebLogic Server node as a user who has read and write permissions on the node. Set up the WebLogic domain environment. Using the appropriate <domain_name> value, run:
<domain_name>/bin/setDomainEnv.sh
2.
3.
Ensure that typing "echo $WL_HOME" shows the Oracle WebLogic Server home directory. Create a new directory under a top-level directory such as root (/). For example, create /tmp/mysrc:
$ mkdir /tmp/mysrc
4.
5. 6.
Copy the original fndext.jar file from the patch to /tmp/mysrc. Change directory to /tmp/mysrc:
$ cd /tmp/mysrc
7.
Unzip fndext.jar in /tmp/mysrc:

$ jar fx fndext.jar
8.
Delete the original fndext.jar file from /tmp/mysrc:

$ rm fndext.jar
9.
Copy $WL_HOME/server/lib/commo.dtd to /tmp/mysrc:

$ cp $WL_HOME/server/lib/commo.dtd .
10. Run the following Java commands from /tmp/mysrc: $ java -DMDF=/tmp/mysrc/ExtAuthenticator.xml \ -Dfiles=/tmp/mysrc \ -DcreateStubs="true" \ weblogic.management.commo.WebLogicMBeanMaker $ java -DMDF=/tmp/mysrc/ExtAuthOnlyAuthenticator.xml \ -Dfiles=/tmp/mysrc \ -DcreateStubs="true" \ weblogic.management.commo.WebLogicMBeanMaker 11. From /tmp/mysrc, run: $ mv oracle/apps/fnd/ext/jaas/weblogic/*.java . 12. Change to the parent directory: $ cd .. 13. From the /tmp/ directory, run the Java command: $ java -classpath /tmp/mysrc:$CLASSPATH \ -DMJF=/tmp/mysrc/fndext.jar \ -Dfiles=/tmp/mysrc \ weblogic.management.commo.WebLogicMBeanMaker 14. Now you should have a new fndext.jar file in /tmp/mysrc/. Unzip the file and
ensure that the jar has the following directory structure: META-INF
oracle schemacom_bea_xml weblogic commo.dtd ExtAuthOnlyAuthenticator.xml ExtAuthenticator.xml
2.1.5.2. Rebuilding the fndext.jar file for Oracle WebLogic Server on Windows:
This step is optional but strongly recommended. See note, page 2-21 above.
1. 2.
Open a Windows command prompt. Set up the Oracle WebLogic domain environment. Change to the appropriate <myWLSdomain\bin> directory for your domain (such as D:\Oracle\Middleware\user_projects\domains\base_domain\bin) and run setDomainEnv.cmd or run it directly. For example:
D:\Oracle\Middleware\user_projects\domains\base_domain3\bin\setDomai nEnv.cmd
Your directory will change automatically to the <myWLSdomain\bin> directory.

3.
Enter
echo %WL_HOME%
and ensure that the result shows the Oracle WebLogic Server home directory.
4.
Create a new directory under a top-level directory (that is, it may be directly under the D:\ or C:\ directory), such as D:\mysrc:
mkdir D:\mysrc
5. 6.
Copy the original fndext.jar from the patch to D:\mysrc. Change your work directory to D:\mysrc:
D:> cd D:\mysrc
7.
Unzip fndext.jar in D:\mysrc:

D:\mysrc> jar fx fndext.jar
8.
Delete the original fndext.jar from D:\mysrc:

D:\mysrc> del fndext.jar
9.
copy %WL_HOME%\server\lib\commo.dtd to D:\mysrc:

D:\mysrc> copy %WL_HOME%\server\lib\commo.dtd .
10. Run the following Java commands from D:\mysrc: java -DMDF=D:\mysrc\ExtAuthenticator.xml -Dfiles=D:\mysrc ^ -DcreateStubs="true" ^ weblogic.management.commo.WebLogicMBeanMaker java -DMDF=D:\mysrc\ExtAuthOnlyAuthenticator.xml -Dfiles=D:\mysrc ^ -DcreateStubs="true" ^ weblogic.management.commo.WebLogicMBeanMaker 11. From D:\mysrc>, run: move oracle\apps\fnd\ext\jaas\weblogic\*.java . 12. Change to the parent directory: D:\mysrc> cd .. 13. From D:\, run the following Java command: java -classpath "D:\mysrc;%CLASSPATH%" ^ -DMJF=D:\mysrc\fndext.jar ^ -Dfiles=D:\mysrc ^ weblogic.management.commo.WebLogicMBeanMaker 14. Now you should have a new fndext.jar file inD:\mysrc. Unzip the file and ensure
that the jar has the following directory structure and files: META-INF oracle schemacom_bea_xml weblogic commo.dtd ExtAuthOnlyAuthenticator.xml ExtAuthenticator.xml
2.1.5.3. Deploy AppsDataSource Code on the Oracle WebLogic Server Instance:

The AppsDataSource code must be deployed in the Oracle WebLogic Server before defining connections. If you rebuilt the fndext.jar file in the previous steps, use the rebuilt fndext.jar in the following steps. The steps to deploy the AppsDataSource are as follows:
1.
Shut down the Oracle WebLogic Server.
2.
Copy the fndext.jar file to the $DOMAIN_DIR/lib subdirectory of the managed server in the external node (where Oracle WebLogic Server will be running). For example:
work/Oracle/Middleware/user_projects/domains/base_domain/lib
3.
Start the server. Oracle WebLogic Server appends JAR files found in the lib directory to the system classpath. Multiple files are added in alphabetical order.
2.1.5.4. Configure the Data Source in the Administration Console:

Now you must configure the data source from within the WebLogic Administration Console.
1.
Navigate to the Oracle WebLogic Administration Console for your application server:
http://<your host>:<your port>/console
2. 3.
Log in. Navigate to Domain Structure > Services > Data Sources
4.
Click the New button for Data Sources and select Generic Data Source.
5.
Enter values for:

1. 2. 3. 4.
Name for the datasource JNDI Name, such as jdbc/myDS Database Type: Oracle Database Driver: "Oracle's Driver (Thin) for Instance connections; Versions:9.0.1,9.2.0,10,11". For an XA datasource, select "Oracle's Driver (Thin XA) for Instance connections; Versions:9.0.1,9.2.0,10,11" for the Database Driver field. The first screenshot shows these settings for a non-XA data source:
The second screenshot shows these settings for an XA data source:
6. 7.
Click Next. For a non-XA data source, uncheck the Supports Global Transactions check box. For an XA data source, leave the check box checked. Click Next.
8.
Enter values for:

1. 2. 3. 4.
Database Name: (SID of Oracle E-Business Suite database) Hostname (DB hostname) Port (DB port) DB username - Enter the valid Oracle E-Business Suite username (created in Set Up Necessary Oracle E-Business Suite Users, page 2-5) in UPPERCASE. The user should have the APPS_SCHEMA_CONNECT role as described previously. You do not use the APPS schema name here. Password for the Oracle E-Business Suite user
5. 9.
Confirm the password and click Next.
10. Enter the Driver Class Name: 1.
For a non-XA datasource, enter: oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource
2.
For an XA datasource, enter oracle.apps.fnd.ext.jdbc.datasource.AppsXADataSource in the Driver Class Name field.
11. In the Properties field, add a new property after the user property: dbcFile=<full path of your desktop DBC file>
For example:
dbcFile=C:\dbc_files\MYEBSDB_DESKTOP.dbc 12. Click the Test Configuration button. You will get a message indicating that the test
has succeeded or failed.

13. If the connection test succeeds, click Next. Check the check box for the appropriate
target server, and click Finish.
2.2. Using AppsDataSource Directly from Java Programs

AppsDataSource can be set up and used directly from Java programs. The server running your Java program needs to have a desktop DBC file, page 2-3 generated by the Oracle E-Business Suite system administrator using the AdminDesktop utility, page 4-
. You also need an Oracle E-Business Suite username and password (credentials) defined by the system administrator, and that applications user must have the UMX|APPS_SCHEMA_CONNECT role assigned to it. See Set Up Necessary Oracle E-Business Suite Users, page 2-5.
2.2.1. Writing the Java Program:

There are many available options for how to set up the application server, the application, and the related components. This document describes only a simple case, and your setup and program may be different. For example, exception handling in this sample is extremely simple and does not use more sophisticated logging mechanisms. Within your Java program, initialize the AppsDataSource in an init() method. For example:
/* * Imports */ import java.io.File; import java.sql.Connection; import java.sql.ResultSet; import java.sql.ResultSetMetaData; import java.sql.SQLException; import java.sql.Statement; import oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource; ... /** * Initialize: Here we create and initialize the * AppsDataSource object. We need the Oracle E-Business * Suite user's credentials and the desktop DBC file * (passed from command line in main, for example). * */ public void init() { ads = null ; try { ads = new AppsDataSource(); ads.setDescription("AppsDataSource Demo"); ads.setUser(this.appsUser); ads.setPassword(this.appsUserPassword); ads.setDbcFile(this.dbcFileName); } catch (SQLException ex) { System.out.println("AppsDataSourceDemo - Exception Creating an AppsDataSource object"); ex.printStackTrace(); ads = null ; // We check for null in the rest of our code. } }
Then use the new AppsDataSource to get a database connection. In this part of the example, we have already set up a query as a string and passed it in to our query() method.
/** * Get a Connection object reference from our * AppsDataSource object and use that to query the * Oracle E-Business Suite database. * * @param expression * @param colection * @return */ public synchronized void query( String expression ) { ResultSet rs; Statement st; Connection dbConn; // Sanity check... This IF condition will be satisfied if // something went wrong in the init() method and we don't have // a valid AppsdataSource object. if ( this.ads == null ) { System.out.println("No valid AppsDataSource object. Cannot proceed."); return ; } st = null; rs = null; dbConn = null; try { // We get our java.sql.Connection object from our AppsDataSource dbConn = this.ads.getConnection() ; // And use it to query the Oracle E-Business Suite Database st = dbConn.createStatement( ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY ); rs = st.executeQuery( expression ); if ( rs == null ) { // And dump out the results of our query to the console. dumpResultSet( rs ); //another method not shown here } } catch ( SQLException e ) { System.out.println("SQLException while querying the EBS Database: " + expression ) ; e.printStackTrace() ; } finally { try { if (st != null) { st.close(); } } catch (SQLException e) { // Ignore... } try { if (dbConn != null) { dbConn.close(); } } catch (SQLException e) { // Ignore... } }
3
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3.1 Overview of Using the JAAS Feature

Oracle E-Business Suite contains a repository of application users (FND users) and their associated roles (authorization for access to certain functional areas of the product). If you are developing a custom or third-party Java EE application to integrate with the Oracle E-Business Suite, and you want to use that existing repository of users and roles for authentication and authorization for your application, you should use the Oracle E-Business Suite implementation of Java Authentication and Authorization Service (JAAS). This feature is intended to secure an HTTP resource or piece of application functionality at the Oracle E-Business Suite user level. If you plan to use Oracle ADF 11g to build your application, see "Using Oracle ADF 11g with the JAAS Feature", page 3-3. This is a lightweight implementation that can be used on an external application server without needing to install an entire Oracle E-Business Suite instance on the application server machine.
Note: Generally you would use the Java Authentication and
Authorization (JAAS) feature of the SDK or the session management feature, but not both together. See "Use Cases, page 1-2".
With the JAAS feature, usernames are authenticated against the Oracle E-Business Suite FND_USERS table, and roles are checked against Oracle E-Business Suite roles. There are many available options for how to set up the application server and the related components. This document describes only a simple case, and your setup may be different. The following diagram shows how users and roles are used in the JAAS and
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-1
AppsDataSource setups:
There are two different users, A (with Clerk role, UMX|CLERK) and B (with Manager role, UMX|MANAGER), accessing a protected custom application (through a URL) on an external application server. The custom application has a web.xml file that allows access for the Manager role as
part of the JAAS setup. User A does not have the Manager role, so is not allowed access to the custom application. The external application server has an AppsDataSource set up to allow access to the Oracle E-Business Suite database using the dedicated AppsDataSource user that has the special UMX|APPS_SCHEMA_CONNECT role assigned to the dedicated user. A repository of users and roles resides inside the Oracle E-Business Suite database.
3.1.1 Using Oracle ADF 11g with the JAAS Feature

For the application developer, there are two main ways to implement security for Oracle ADF 11g applications:
1. 2.
Oracle ADF Security Framework (recommended) Standard Java EE container-managed security

Note: For the purposes of this document, where the setup instructions
differ between the two types of security, an Oracle ADF application that uses the Oracle ADF Security Framework will be called an Oracle ADF application. An Oracle ADF application that uses container-managed security instead of the Oracle ADF Security Framework will be considered a Java EE application (though it is still technically an Oracle ADF application, it does not use the advanced security framework provided by Oracle ADF).
For an Oracle ADF application, you use the Oracle ADF Security wizard to set up security for your application as described in the Oracle ADF documentation. Roles that come from Oracle E-Business Suite through the JAAS setup correspond to enterprise roles in an Oracle ADF application, so you need only define enterprise roles that you expect to use from Oracle E-Business Suite. When you build your Oracle ADF application, you must take the following steps to set up your application security and deployment properties so your application works with the JAAS feature:
1.
Within Oracle ADF security, create enterprise roles that match what you are expecting to get from Oracle E-Business Suite (only role names of the format: UMX|ROLECODE).
Note: Some versions of Oracle ADF 11g do not allow the pipe
character ( | ) to be used when creating enterprise role names in the ADF Security Wizard. The workaround is to put the pipe characters
in using source view in JDeveloper. You must be using WebLogic Server 10.3.5 or higher (WLS 10.3.3 does not allow the pipe character).
2.
If needed, create application roles within Oracle ADF. Make sure that if you have application roles that you include the mapping from enterprise roles to application roles within the ADF Security Wizard. Application roles will only be relevant with the JAAS feature if they are mapped to an enterprise role within Oracle ADF. Assign grants to your roles to let them access task flows and pages as appropriate for your application security. Do not create users within the Oracle ADF Security Wizard. If needed, use Oracle ADF component-level security using the Oracle ADF expression language (such as menu rendering using #{securityContext.userInRole...}). When you set your application properties for deployment, uncheck the "Auto Generate and Synchronize weblogic-jdbc.xml Descriptors During Deployment" checkbox. Also uncheck the Application Policies, Credentials, and Users and Groups checkboxes.
3.
4. 5.
6.
Oracle ADF recommends that you use the Oracle ADF Security Framework for your application. However, if you develop your ADF application to use container-managed security instead of the Oracle ADF Security Framework, you do not need to configure ADF security because you will not be using "ADF Authentication and Authorization". If you have already configured ADF security, you should select "Remove ADF Security Configuration" in the Configure ADF Security wizard. You do not define users, roles, or policies using the wizard. When using container-managed security, you simply include the security constraint with the role name in the web.xml file and the corresponding lines in the weblogic.xml file as in the setup instructions in this chapter. Oracle ADF 11g uses Oracle WebLogic Server only; it does not use OC4J.
3.2 Configuring JAAS

Setting up the JAAS feature consists of the following general steps:
1. 2.
Set up users and roles, page 3-6 in the Oracle E-Business Suite instance Edit the web.xml file, page 3-6 for security constraints (container-managed security only) Set up security role elements, page 3-6 (for Oracle WebLogic Server, container-managed security only) Set up global access, page 3-7 for all authenticated Oracle E-Business Suite users (optional, for Oracle WebLogic Server, container-managed security only) Configure JAAS in either Oracle WebLogic Server, page 3-7 or OC4J, page 3-37
3.
4.
5.
and deploy your application. If you are using Oracle WebLogic Server on UNIX/Linux, you can use the Apache Ant XML automation script txkEbsSdkConfig.xml, page 4-1, or you can set up your security realm manually by following the steps described in "Set Up Security Realm", page 3-8.
3.2.1 Set Up Users and Roles in Oracle E-Business Suite Instance:

Roles defined in the Oracle E-Business Suite instance are considered enterprise roles for external applications. For every enterprise role you plan to use with your external Java EE application, you must create a role with the same role code using the User Management responsibility in Oracle E-Business Suite. You (or the application administrator) must also assign the role to the intended Oracle E-Business Suite users. Only UMX roles (role codes of the format UMX|ROLECODE) can be used with the JAAS feature. Responsibilities (role codes such as FND_RESP|FND|APPLICATION_DEVELOPER|STANDARD) cannot be used with the JAAS feature.
3.2.2 Edit the web.xml File for Security Constraints:

For most Java EE applications, you place your security roles and constraints with the appropriate UMX|ROLECODE in the web.xml file for your custom application. If you are building an Oracle ADF application, skip this step. For Oracle ADF applications, you configure security constraints using the Oracle ADF Security Wizard, which updates the jazn-data.xml file. You do not edit the web.xml file with your role names. In the example, UMX|DEMO is the name of the role as defined in the User Management responsibility in the Oracle E-Business Suite. For example:
<security-role> <role-name>UMX|DEMO</role-name> </security-role> <security-constraint> <web-resource-collection> <web-resource-name>DemoAdmin</web-resource-name> <url-pattern>/admin/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>UMX|DEMO</role-name> </auth-constraint> </security-constraint>
3.2.3 Set Up Security Role Elements for Oracle WebLogic Server:

If you are building an Oracle ADF application, skip this step. If you are using Oracle WebLogic Server, note that for each security role element in your web.xml
<security-role> <role-name>UMX|DEMO</role-name> </security-role>
you must define a corresponding security role assignment element in the META-INF/weblogic.xml file:
<security-role-assignment> <role-name>UMX|DEMO</role-name> <externally-defined/> </security-role-assignment>
3.2.4 (Optional) Set Up Global Access for All Authenticated Oracle E-Business Suite Users:
For the primary JAAS use case described in this chapter, you are using Java authentication (user's name and password) and authorization (user's roles), so the JAAS setup uses ExtAuthenticator, which does both. Sometimes you may have a case where all authenticated Oracle E-Business Suite users are eligible to access a protected URL, regardless of what roles the users might have. For this case, JAAS can be configured with ExtAuthOnlyAuthenticator (authentication only) for Oracle WebLogic Server or oracle.apps.fnd.ext.jaas.security.auth.login.AppsAuthOnlyLoginMo dule for OC4J. For the global access case, the security role and constraint entries in web.xml should defined similar to the following, with "GLOBAL" as the role name:
<security-role> <role-name>GLOBAL</role-name> </security-role> <security-constraint> <web-resource-collection> <web-resource-name>admin job</web-resource-name> <url-pattern>/admin/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>GLOBAL</role-name> </auth-constraint> </security-constraint>
For OC4J, you must also create a third configuration name and value property, in addition to the connectionMode and connectionReference properties defined in Change Security Provider, page 3-38. Click the Add Another Row button a third time, and enter guestAllowed in the Name field, and enter true or false in the Value field, depending on whether the guest user is allowed to access the protected URL or not. For an ADF application, you would configure global access within the ADF Security Wizard instead of in the web.xml file.
3.3 JAAS Configuration for Oracle WebLogic Server

This section assumes experience with Oracle WebLogic Server. If you are not familiar with it, you should review the material in the Oracle WebLogic Server Documentation Library before beginning this process. You must be using Oracle WebLogic Server 10.3.5.0 or later. Oracle WebLogic Server
10.3.3.0 does not accept the pipe ( | ) character present in Oracle E-Business Suite role names.
Important: If you plan to use the Oracle E-Business Suite Java
Authentication and Authorization Service (JAAS) implementation on Oracle WebLogic Server, you must rebuild the fndext.jar file on the target Oracle WebLogic Server instance first, instead of using the fndext.jar file exactly as it comes from the patch. See Rebuilding the fndext.jar file for Oracle WebLogic Server on UNIX/LINUX, page 2-21 or Rebuilding the fndext.jar file for Oracle WebLogic Server on Windows, page 2-23 for instructions.
If you are using Oracle WebLogic Server on UNIX/Linux, you can use the Apache Ant XML automation script txkEbsSdkConfig.xml, page 4-1, or you can set up your security realm manually by following the steps described in "Set Up Security Realm", page 3-8.
3.3.1 Prerequisite: Set Up AppsDataSource for Oracle WebLogic Server

1.
If you have not already done so, rebuild the fndext.jar file as described in Rebuilding the fndext.jar file for Oracle WebLogic Server on UNIX/LINUX, page 221 or Rebuilding the fndext.jar file for Oracle WebLogic Server on Windows, page 2-23. If you have not already done so, set up your AppsDataSource. See Configuring AppsDataSource on an Oracle WebLogic Server Instance, page 2-20 for instructions.
2.
3.3.2 Set Up Security Realm:

1. 2. 3. 4.
Copy the fndext.jar to the $WL_HOME/server/lib/mbeantypes directory. Restart the server. Log in to the Administration Console. If you have not already done so, in the Change Center of the Administration Console, click the Lock & Edit button (see "Use the Change Center" in the Oracle WebLogic Server Administration Console online help).
5.
In the Domain Structure pane, select Security Realms. Click the New button in the Summary of Security Realms pane.
6.
Enter a name such as EbsRealm, and click OK.
7.
In the Realms table, click the name of your new realm.
3.3.3 Set up Providers:

1.
Select the Providers tab. Within the Providers tab, select the tab for the type of provider you are configuring.
2.
Select the Authentication tab. Click New.
3.
Enter DefaultAuthenticator in the Name field, and select DefaultAuthenticator from the Type drop-down. Click OK.
4.
From the Authentication Providers table, click the name of the new DefaultAuthenticator.
5.
Select SUFFICIENT in the Control Flag: field and click Save.
6.
Click the Providers link in the path above the Settings pane to return to the Settings for EbsRealm page and the Authentication Providers table. Click New.
7.
Create your Oracle E-Business Suite authentication provider. Enter ExtAuthenticator in the Name field, select ExtAuthenticator from the Type drop-down list, and click OK. If you are setting up global access for all authenticated users instead, enter ExtAuthOnlyAuthenticator in the Name field, select ExtAuthOnlyAuthenticator from the Type drop-down list, and click OK.
8.
From the Authentication Providers table, click the name of the new ExtAuthenticator.
9.
Select SUFFICIENT in the Control Flag: field and click Save.
10. Now click the Provider Specific tab. In the connection Reference: field, enter the
JNDI Name of the AppsDataSource you created earlier (see Configuring AppsDataSource on an Oracle WebLogic Server (WLS) Instance, page 2-20). In the connection Mode: field, enter DATASOURCE. Click Save.
11. Click the Providers link in the path above the Settings pane to return to the Settings
for EbsRealm page and the Authentication Providers table. Click the Authorization tab, and click New.
12. Enter XACMLAuthorizer in the Name field and select XACMLAuthorizer from the
Type drop-down list. Click OK.
13. Click the Adjudication tab. Click New.
14. Enter DefaultAdjudicator in the Name field and select DefaultAdjudicator
from the Type drop-down list. Click OK.
15. Click the Role Mapping tab. Click New.
16. Enter XACMLRoleMapper in the Name field and select XACMLRoleMapper from
the Type drop-down list. Click OK.
17. Click the Credential Mapping tab. Click New.
18. Enter DefaultCredentialMapper in the Name field and select
DefaultCredentialMapper from the Type drop-down list. Click OK.
19. Click the Certification Path tab. Click New.
20. Select WebLogicCertPathProvider from the Type drop-down list. Click Next.
21. Accept the defaulted value for the Name field by clicking Next.
22. Check the Replace Existing Builder check box, and click Finish.
3.3.4 Set Default Realm:

1.
Set your newly-created security realm (such as EbsRealm) as the default realm. On the Domain Structure pane, click the name of your domain.
2.
Click the Security tab. Select EbsRealm from the Default Realm drop-down list. Click Save.
3.
Activate your pending changes by clicking Activate Changes in the Change Center pane.
4.
Log out from the Administration Console and restart Oracle WebLogic Server.
3.3.5 Deploy the application on Oracle WebLogic Server:

Deploy your web application. In our example, we deploy the sample HelloWorld.war.
1.
From the Domain Structure pane, click Deployments. Click Install on the Deployments table.
2.
Browse and select your application war file. Click Next.
3.
In the Security section, if you are using container-managed security, select Custom Roles. If you are deploying an Oracle ADF application, select DD Only (the default choice). Click Next.
4.
Click Finish. You will then see the deployment's configuration screen.
3.3.6 Map Enterprise Roles to Application Roles for Your Deployment:

If you are deploying an Oracle ADF application, skip this step.
1.
From the configuration panel, select the Security tab, then the Application Scope tab, and then the Roles tab.
2.
If a link to the Domain Security Page is visible, click it, and from the next page, select the checkbox "Allow Security Management Operations if Non-dynamic Changes have been Made" and click Save. If the link is not visible, go to the next step. From the Domain Structure pane, click Deployments. The Deployments listing should show your newly-installed war. Click its link.
3.
4.
From the Security tab, select the Application Scope tab, then select the Roles tab, and click New.
5.
In the Name field, enter the name of the role defined in the web.xml file (such as UMX|DEMO) and click OK.
6.
From the Stand-Alone Web Application Scoped Roles listing, click the role name (for example, UMX|DEMO).
7.
Click Add Conditions.
8.
From the Predicate List drop-down list, select Group, and click Next.
9.
In the Group Argument Name: field, enter your role name (such as UMX|DEMO). Click Add.
10. Click Finish. Click Save.
11. Log out of the console, and restart Oracle WebLogic Server.
3.3.7 Test the JAAS Setup:

After you write your web application and deploy it in your application server, you will need to test the JAAS setup with your application to make sure the authentication and authorization behave properly. Access your protected URL (resource) with the applications user name and password for the user with the authorized role. You should be able to access the resource. Access your protected URL with the user name and password for a different application user who does not have the authorized role. You should not be able to access the resource. For testing purposes only, you can enable verbose debug messages in Oracle WebLogic Server. In your setDomainEnv file for your domain (such as D:\\Oracle\Middleware\user_projects\domains\base_domain_SDK\bin\setDomain Env.cmd for the Windows domain shown in the setup screenshots), add the debug and verbose arguments to the following line in the file:
set JAVA_OPTIONS=%JAVA_OPTIONS%
so the resulting line looks like this (formatted here for readability):
set JAVA_OPTIONS=%JAVA_OPTIONS% -Djps.auth.debug=true -Djps.auth.debug.verbose=true
This will show all of the subject and principal information that gets passed to your application.
3.4 JAAS Configuration for OC4J

3.4.1 Prerequisite: Set Up AppsDataSource for OC4J
See Configuring AppsDataSource on an OC4J Instance, page 2-9 for instructions on setting up your AppsDataSource.
3.4.2 Configure OC4J in Oracle Enterprise Manager to Use JAAS:

1.
2. 3. 4. 5. 6. 7.
Log in as the OC4J administrator. Select the desired OC4J instance. Select the Administration tab. Deploy or redeploy your web application. Select the Applications tab. Click the link for the name of your deployed web application.
3.4.3 Change Security Provider:

1. 2.
Select the Administration tab. Click the Go to Task icon for Security > Security Provider.
3.
Click the Change Security Provider button.
4.
In the Change Security Provider page:

1.
Select Custom Security Provider from the Security Provider Type drop-down list. Specify the JAAS Login Module Class value as oracle.apps.fnd.ext.jaas.security.auth.login.AppsLoginModu le Select Required or Sufficient from the Login Module Control Flag drop-down
2.
3.
list.
4.
Create two property rows by clicking the Add Another Row button twice. Enter the following property names and values to define the properties needed to configure AppsLoginModule.
Name connectionMode connectionReference Value DATASOURCE <JNDI name for the AppsDataSource created above>
5.
Click OK.
6. 7.
Log out of the OC4J Enterprise Manager console. Restart the OC4J server.
3.4.4 Test the JAAS Setup:

After you write your web application and deploy it in your application server, you will need to test the JAAS setup with your application to make sure the authentication and authorization behave properly. Access your protected URL (resource) with the applications user name and password for the user with the authorized role. You should be able to access the resource. Access your protected URL with the user name and password for a different application user who does not have the authorized role. You should not be able to access the resource.
4
Utilities
This chapter covers the following topics: 4.1. Automated Setup Script 4.2. AdminDesktop Utility 4.2.1. AdminDesktop Usage Examples
4.1. Automated Setup Script

If you are using Oracle WebLogic Server on UNIX/Linux, you have a choice: you can use the Apache Ant XML automation script txkEbsSdkConfig.xml, provided in the patch starting with Version 2.0.1 of the SDK, or you can set up your data source by following the manual steps listed in "Configuring AppsDataSource on Oracle WebLogic Server (WLS)", page 2-20. If you are not familiar with Apache Ant, please see http://ant.apache.org/. The txkEbsSdkConfig.xml Ant script can both rebuild the fndext.jar file and set up the AppsDataSource (for a non-XA data source only), as well as set up a security realm if you are using the JAAS feature. Because the rebuilding process is specific to a particular WebLogic Server version, the rebuilt version of the fndext.jar file is meant for use only with that specific environment. Note that you will need to rebuild the fndext.jar file (and put the rebuilt file in the correct locations) any time you install a patch that includes a new version of the fndext.jar file or a new version of Oracle WebLogic Server. The txkEbsSdkConfig.xml Ant script supports the following command names in the syntax
ant -f txkEbsSdkConfig.xml commandName
The command names are case sensitive. usage provides a list of command line arguments supported by the script. However, when the script is used following the steps below, the script will prompt for arguments if they are not provided on the command line. Note that for better
Utilities 4-1
security, it is preferable to not include arguments such as passwords on the command line. rebuildJar creates a new directory named temp inside the current directory and creates the rebuilt fndext.jar in temp. The script will also copy the rebuilt fndext.jar to $DOMAIN_HOME/lib and $WL_HOME/lib/mbeantypes. You must shut down and restart Oracle WebLogic Server after using this command. createDataSource creates a new data source on the target WebLogic Server instance based on user parameters. createSecurityRealm creates a new security realm with the name EBSRealm. When you use this command, the script prompts you to enter the Ext Authentication provider name (example: ExtAuthOnlyAuthenticator or ExtAuthenticator). See "(Optional) Set Up Global Access for All Authenticated Oracle E-Business Suite Users", page 3-7. Do not run createSecurityRealm unless you are using the JAAS feature, since this sets EBSRealm as the default realm and could therefore affect any other applications you have running in the same domain. configAll creates a new data source and security realm in a single step. Internally calls createDataSource and createSecurityRealm successively. Do not run configAll unless you are using the JAAS feature, since this sets EBSRealm as the default realm and could therefore affect any other applications you have running in the same domain.
Other parameters depend on the operation. Parameters include: wlshosturl=<Oracle WebLogic Server Administration Console URL> (example: myhost:7001) wlsuser=<Oracle WebLogic Server Admin user name> (example: weblogic) wlspwd=<Oracle WebLogic Server Admin password> dataSourceName=<Name of the data source> (example: visionDS) dataSourceJNDIName=<JNDI Name of the data source> (example: jdbc/visionDS) asadminUser=<Name of the EBS (FND) user with UMX|APPS_SCHEMA_CONNECT role> (example: ASADMIN) asadminPassword=<Password of the EBS (FND) user with UMX|APPS_SCHEMA_CONNECT role > (example: secret) dbcFile=<Absolute path to the Desktop DBC file> (example: /root/mywork/desktop.dbc) serverName=<Name of the target WLS Server> (example: AdminServer)
Running the Automated Setup Script:

1.
Prepare to run the script

1.
Log in to the Oracle WebLogic Server node as a user who has read and write permissions on the node. Copy the original fndext.jar file and the txkEbsSdkConfig.xml file from the patch to a directory such as/home/user1/ebssdk on the external Oracle WebLogic Server machine. Change directory to /home/user1/ebssdk:
$ cd /home/user1/ebssdk
2.
3.
4.
Set up the WebLogic domain environment. Using the appropriate <domain_name> value, run:
<domain_name>/bin/setDomainEnv.sh
5.
Ensure that typing "echo $WL_HOME" shows the Oracle WebLogic Server home directory. Unzip fndext.jar in /tmp/mysrc:
$ jar fx fndext.jar
6.
2.
Rebuild the fndext.jar file

1.
To rebuild the fndext.jar file, run the following command from /home/user1/ebssdk:
$ ant -f txkEbsSdkConfig.xml rebuildJar
2.
In the Oracle WebLogic Server Administration Console, verify that the existing security realm supplied with Oracle WebLogic Server is set to be the default realm. Shut down and restart Oracle WebLogic Server before proceeding further so that WebLogic Server reads the rebuilt copies of fndext.jar.
3.
3.
Configure the AppsDataSource

1.
To set up the AppsDataSource, run the following command from /home/user1/ebssdk:

$ ant -f txkEbsSdkConfig.xml createDataSource
The script will prompt for input values.

4.
Configure the EBSRealm security realm. Do not run createSecurityRealm unless you are using the JAAS feature, since this sets EBSRealm as the default realm and could
Utilities 4-3
therefore affect any other applications you have running in the same domain.
1.
To configure the EBSRealm, run the following command from /home/user1/ebssdk:

$ ant -f txkEbsSdkConfig.xml createSecurityRealm
The script will prompt for input values.
4.2. AdminDesktop Utility

AdminDesktop is a standalone Java utility used to create desktop DBC files. Desktop DBC files are used by external nodes or application servers (the client) to connect to the Oracle E-Business Suite database. The first parameter must be the connection string (APPS schema user name and password) followed by the command string, such as apps/apps CREATE. AdminDesktop supports the following commands: CREATE - create a desktop DBC file and call ADD_SERVER UPDATE - update a desktop DBC file with the specified values DELETE - delete a desktop DBC file and call DROP_SERVER ADD_SERVER - generate a new server ID and associate it with the specified node, updating the resulting DBC file as well DROP_SERVER - drop the existing server ID from the specified node
Other parameters depend on the operation. Parameters include: NODE_NAME - node name of the application server. Required. IP_ADDRESS - IP address of the client. Optional but strongly recommended for production environments. TWO_TASK - TWO_TASK for use on the client. This is not used by the AdminDesktop code when connecting to the database. It is simply a property stored in the desktop DBC file. DBC - name of an existing, standard DBC file previously generated by the Oracle E-Business Suite system administrator. Required, used to connect to the database. This is NOT the name of the desktop DBC file.
4.2.1. AdminDesktop Usage Examples

The AdminDesktop utility requires the password for the APPS schema, so the utility
must be run by the Oracle E-Business Suite system administrator. AdminDesktop should be run from the Oracle E-Business Suite instance (that is, where all the instance's Java class files reside under $JAVA_TOP). Note that these commands should be typed in on a single line or use the appropriate continuation character for the operating system.
To CREATE a desktop DBC file:

java oracle.apps.fnd.security.AdminDesktop apps/apps CREATE NODE_NAME=<name of the external node> [IP_ADDRESS=<IP address>] DBC=<name of the standard DBC file>
The name of the desktop DBC being generated will default to the standard DBC file name plus the name of the node, such as host_port_node.dbc. GWYUID, FNDNAM, and GUEST_USER_PWD will be defaulted from the database. TWO_TASK will default to the DB_NAME property from the existing DBC file if not specified.
To UPDATE the IP address in a desktop DBC file:

java oracle.apps.fnd.security.AdminDesktop apps/apps UPDATE NODE_NAME=<name of the external node> [IP_ADDRESS=<IP address>] DBC=<name of the standard DBC file>
If NODE_NAME is passed, only that node will be updated. The name of the desktop DBC file being updated will be derived based on the DBC argument and the NODE_NAME. If the desktop DBC file does not exist, an error is raised.
To DELETE a desktop dbc file:

java oracle.apps.fnd.security.AdminDesktop apps/apps DELETE NODE_NAME=<name of the external node> DBC=<name of the standard DBC file>
If NODE_NAME is passed, only that node will be deleted. The name of the desktop DBC file being deleted will be derived based on the database connection and the NODE_NAME. If the desktop DBC file does not exist, an error is raised.
To add a server (ADD_SERVER) to a desktop DBC file:

java oracle.apps.fnd.security.AdminDesktop apps/apps ADD_SERVER NODE_NAME=<name of the external node> DBC=<name of the standard DBC file>
This is not a common operation, but can be used if you have an existing desktop DBC file and that has had its server ID dropped, or if you just want to generate a new ID. The name of the desktop DBC file being updated will be derived based on the database connection and the NODE_NAME. If the desktop DBC file does not exist, an error is raised. The IP_ADDRESS and TWO_TASK arguments are ignored.
Utilities 4-5
To drop a server (DROP_SERVER) from a desktop DBC file:

java oracle.apps.fnd.security.AdminDesktop apps/apps DROP_SERVER NODE_NAME=<name of the external node> DBC=<name of the standard DBC file>
This is not a common operation. This command will delete the corresponding server ID for the node and remove that value from the desktop DBC file. The name of the desktop DBC file being updated will be derived based on the database connection and the NODE_NAME. If the desktop DBC file does not exist, an error is raised.
5
Using Lightweight Java Error Logging with Oracle E-Business Suite
5.1. Existing Logging Framework in Oracle E-Business Suite

Oracle Application Object Library provides a logging framework that can be used to log errors and other messages for diagnostic purposes. This logging framework can be used with PL/SQL, C code, and Java code. The logging framework is documented in the following locations: Oracle E-Business Suite Developer's Guide (formerly Oracle Applications Developer's Guide), "Logging Framework Overview". This chapter describes the properties and profile options used for logging on your Oracle E-Business Suite database and application tiers where Oracle E-Business Suite is installed, as well as what information is provided through the logging framework. Oracle E-Business Suite Developer's Guide (formerly Oracle Applications Developer's Guide), "Logging Guidelines for Developers". This chapter describes how developers should build log messages into their code, including performance considerations and logging standards. It also includes logging framework APIs for PL/SQL, C code, and Java. These APIs are heavily dependent on many other parts of Oracle E-Business Suite code and require a full application tier installation of the Oracle E-Business Suite. Oracle E-Business Suite System Administrator's Guide - Configuration (formerly Oracle Applications System Administrator's Guide - Configuration), "Logging". This chapter describes how to set properties and profile options to enable and configure logging on your Oracle E-Business Suite database and application tiers where Oracle E-Business Suite is installed.
The rest of this document assumes you are familiar with the documentation resources listed above.
Using Lightweight Java Error Logging with Oracle E-Business Suite 5-1
5.2. Lightweight Extended Java Error Logging

The Oracle E-Business Suite SDK for Java provides additional lightweight Java logging framework APIs for use with external Java EE programs. These external Java EE programs typically reside on an external server/node that is not co-located with the Oracle E-Business Suite application tier installation. For example, the lightweight implementations of AppsDataSource and JAAS for Oracle E-Business Suite (also in the SDK) require a lightweight implementation of the Oracle E-Business Suite logging framework. These programs cannot use the logging framework Java APIs documented in the resources mentioned above, because those APIs are heavily dependent on many other parts of Oracle E-Business Suite code and require a full application tier installation of Oracle E-Business Suite. Another such external Java EE program is Oracle E-Business Suite AccessGate, which is documented in My Oracle Support Knowledge Document 975182.1,"Integrating Oracle E-Business Suite with Oracle Access Manager using Oracle E-Business Suite AccessGate". The lightweight Java logging framework has two primary modes of use, which are documented in the rest of this section:
1.
Developers of external Java EE programs import a specific class into their programs and call the class in their code. Administrators of the external nodes configure the Java logging properties of the external machines to log messages of the desired level to the desired target (file, console, Oracle E-Business Suite database logging table, and so on).
2.
5.3. Logging for Java EE Applications on External Nodes

The following diagram shows how lightweight error logging for external nodes fits into the Oracle E-Business Suite three-tier architecture.
The application tier (middle tier) includes a machine for the Oracle E-Business Suite installation, and a separate machine for the external node. The external node contains the custom application, which logs error messages. The external node also contains the configuration (logging.properties file or Java system properties), which specifies where the error messages will be written: to the logging table in the database, to a log4j framework (Apache), or to a file, for example. This configuration is independent from the logging configuration for the Oracle E-Business Suite installation on the application tier and in the database.
5.4. Java JDK Logging Framework and Oracle E-Business Suite Extensions
In JDK 1.4 and later, Java supports a logging infrastructure that provides features to write logs to Console and File among other destinations (seeJava Logging Overview and java.util.logging package description in Java documentation if you are not
already familiar with the Java logging framework). The Oracle E-Business Suite lightweight Java logging framework extends this JDK logging framework. The Oracle E-Business Suite lightweight Java logging framework package, oracle.apps.fnd.ext.logging, provides additional java.util.logging.Handler implementations to enable logging messages for: Oracle E-Business Suite log table Log4j framework
The overview of logging control flow is shown in the following diagram:
Applications make logging calls on Logger objects. Logger objects allocate LogRecord objects that are passed to Handler objects for publishing. Both Loggers and Handlers may use logging Levels and (optionally) Filters to decide if they are interested in a particular LogRecord. When it is necessary to publish a LogRecord externally, a Handler can optionally use a Formatter to localize and format the message before publishing it to the outside world. This flow is the same as described in Java Logging Overview, with the addition of the Oracle E-Business Suite extended handler, which allows the logging framework to publish log messages to the Oracle E-Business Suite log table, log4j, and legacy logging systems.
5.5. Coding with Oracle E-Business Suite Logging Extensions

In addition to the standard Java logging levels (SEVERE , WARNING, INFO, CONFIG, FINE, FINER, and FINEST), Oracle E-Business Suite logging extensions also provide two more levels, ERROR and PROCEDURE, corresponding to the levels by the same names in Oracle E-Business Suite. To log messages at either of these two levels:
1. 2.
Import oracle.apps.fnd.ext.logging.ExtendedLevel into your code. Call ExtendedLevel.ERROR or ExtendedLevel.PROCEDURE as needed in your code, as shown in the following example:
package oracle.apps.fnd.ext.sample; import java.util.logging.Level; import java.util.logging.Logger; import oracle.apps.fnd.ext.logging.ExtendedLevel; public class MyClass { private static final Logger logger = Logger.getLogger( MyClass.class.getPackage().getName()); // or private static final Logger logger = // Logger.getLogger(MyClass.class.getName()); public static void main(String[] args) { System.out.println("This program does nothing but create a few log messages"); if(logger.isLoggable(Level.FINE)) logger.fine("Log message at FINE level"); if(logger.isLoggable(Level.FINER)) logger.finer("Log message at FINER level"); if(logger.isLoggable(Level.FINEST)) logger.finest("Log message at FINEST level"); if(logger.isLoggable(Level.CONFIG)) logger.config("Log message at CONFIG level"); if(logger.isLoggable(Level.INFO)) logger.info("Log message at INFO level"); if(logger.isLoggable(Level.WARNING)) logger.warning("Log message at WARNING level"); if(logger.isLoggable(Level.SEVERE)) logger.severe("Log message at SEVERE level"); /** In addition to the standard JDK log LEVELs above, fndext * logging also has two more extended levels, ERROR and * PROCEDURE, corresponding to the levels by the same name * in Oracle E-Business Suite. To log messages at either of * these two levels, use ExtendedLevel.ERROR or * ExtendedLevel.PROCEDURE */ if(logger.isLoggable(ExtendedLevel.ERROR)) logger.log(ExtendedLevel.ERROR, "Log message at ERROR level"); if(logger.isLoggable(ExtendedLevel.PROCEDURE)) logger.log(ExtendedLevel.PROCEDURE, "Log message at PROCEDURE level"); } }
5.6. Logging Configuration

Since the Oracle E-Business Suite lightweight logging framework is simply an extension of JDK logging, configuration is the same as for any standard JDK logging configuration. On the external node's Java system properties, you must set either java.util.logging.config.class or java.util.logging.config.file (with a corresponding logging.properties file) to provide an initial logging configuration specific to the client application. It will override the default logging
configuration from a properties file lib/logging.properties in the JRE directory. The logging levels are the same as in standard JDK logging, with the addition of ERROR and PROCEDURE. Client programs should normally use the predefined Level constants such as Level.SEVERE or Level.WARNING in their code. SEVERE (highest value) ERROR WARNING INFO CONFIG PROCEDURE FINE FINER FINEST (lowest value)
The special level OFF can be used to turn off logging, and the level ALL can be used to enable logging of all messages. Note that the handlers for the Oracle E-Business Suite database logging table and log4j perform level conversions appropriate to the target logging framework. For example, in the database logging table, FINE, FINER, and FINEST are all equivalent to the same level in the database, which is STATEMENT. Use of the lower logging levels is not recommended for a production system because they can cause performance issues. See Oracle E-Business Suite System Administrator's Guide - Configuration, "Logging" for more information.
5.6.1. Configuration to use log4j:

If you want to send messages to the log4j (Apache) logging framework, set the following properties:
handlers = oracle.apps.fnd.ext.logging.Log4jLogHandler
Alternatively, for a logging name such as com.foo, set:

com.foo.handlers=oracle.apps.fnd.ext.logging.Log4jLogHandler
Because the AppsLogHandler is fully compliant with the JDK Handler specification, you can also set any of the following optional properties:
oracle.apps.fnd.ext.logging.Log4jLogHandler.level = <your desired level> oracle.apps.fnd.ext.logging.Log4jLogHandler.formatter = <your message formatter class name> oracle.apps.fnd.ext.logging.Log4jLogHandler.filter = <your log filter class name> oracle.apps.fnd.ext.logging.Log4jLogHandler.encoding = <your encode charset>
5.6.2. Configuration to use the Database Logging Table:

If you want to send messages to the Oracle E-Business Suite database logging table, set the following properties:
handlers = oracle.apps.fnd.ext.logging.AppsLogHandler
or alternatively, for a logging name com.foo:

com.foo.handlers=oracle.apps.fnd.ext.logging.AppsLogHandler
Because the AppsLogHandler is fully compliant with the JDK Handler specification, you can also set any of the following optional properties:
oracle.apps.fnd.ext.logging.AppsLogHandler.level = <your desired level> oracle.apps.fnd.ext.logging.AppsLogHandler.formatter = oracle.apps.fnd.ext.logging.AppsLogFormatter oracle.apps.fnd.ext.logging.AppsLogHandler.filter = <your log filter class name> oracle.apps.fnd.ext.logging.AppsLogHandler.encoding = <your encode charset>
Because AppsLogHandler requires a JDBC connection to an Oracle E-Business Suite database to write messages, it must be configured to use the connection factory oracle.apps.fnd.ext.jdbc.connection.AppsConnectionFactory. To use the connection factory for AppsLogHandler, you must set these two additional properties in the logging configuration:
oracle.apps.fnd.ext.logging.AppsLogHandler.connectionMode = 1 oracle.apps.fnd.ext.logging.AppsLogHandler.connectionReference = <JNDI Name of datasource connection, such as jdbc/MyAppsDS>
Note that if you are logging messages to the Oracle E-Business Suite logging table, you must also set the AFLOG profile options. The AFLOG profile options should be enabled for the SYSADMIN user or at the site level for the same logger module and logging level. See Oracle E-Business Suite System Administrator's Guide - Configuration, "Logging" for more information. For example, suppose that logging.properties is configured for com.foo as com.foo.level=FINE. Then on the database tier (within Oracle E-Business Suite), the following AFLOG profile option values should be defined as, for example:
AFLOG_ENABLE= Yes AFLOG_MODULE=com.foo% AFLOG_LEVEL =1 //Statement
If logging.properties is configured for all the modules (globally), then AFLOG_MODULE should be set to %.
5.6.2.1. Log File Example for Sending Messages to Oracle E-Business Suite Database Logging Table:
#logging settings handlers = oracle.apps.fnd.ext.logging.AppsLogHandler oracle.apps.fnd.ext.logging.AppsLogHandler.connectionMode =1 oracle.apps.fnd.ext.logging.AppsLogHandler.connectionReference =jdbc/MyAppsDS oracle.apps.fnd.ext.logging.AppsLogHandler.level =ALL oracle.apps.fnd.ext.logging.AppsLogHandler.formatter =oracle.apps.fnd.ext.logging.AppsLogFormatter #setting log level specific to com.foo packages to level FINE #set the values to WARNING on the production site com.foo.level=FINE
The oracle.apps.fnd.ext.logging package is in the file fndext.jar. You must put the fndext.jar file in the appropriate location for your application server. For OC4J, create a shared library (see Configuring AppsDataSource on an OC4J Instance, page 2-9 ). For Oracle WebLogic Server, put fndext.jar in .../<domain_name>/lib. Note that if you are using Oracle WebLogic Server, you should use the rebuilt fndext.jar file (see Configuring AppsDataSource on an Oracle WebLogic Server (WLS) Instance, page 2-20 ).
6
Session Management
This chapter covers the following topics: Session Management Session Management Classes and APIs
Session Management
The Oracle E-Business Suite SDK for Java provides routines for session management. Use the session management APIs when you want to build a Java EE application that shares a user session (ICX session) with Oracle E-Business Suite. The session management APIs allow you to retrieve, create, validate and cancel an Oracle E-Business Suite session (ICX session) from your external application. Session information and context can travel back and forth between Oracle E-Business Suite and your application, allowing you to share session context information across applications.
Note: Generally you would use the Java Authentication and
Authorization (JAAS) feature of the SDK or the session management feature, but not both together. See "Use Cases, page 1-2".
Terminology
FND user An Oracle E-Business Suite user (application user) as recorded in the FND_USER table. Session, Status and Context When a user performs a business task in Oracle E-Business Suite, the task usually occurs across multiple HTTP requests from the client. HTTP servers respond to each client request independently, without relating that request to previous or subsequent requests. Oracle E-Business Suite maintains contextual information about the client to enable a meaningful dialogue over the duration of a user's "session." This context
Session Management 6-1
includes information such as the user who is currently logged in, as well as the user's responsibility, application, security group, and organization. The context also includes NLS data like NLS_DATE_FORMAT, NLS_LANGUAGE, and so on. At any given point in time, an Oracle E-Business Suite session can have one of the following five statuses: INVALID An ICX session is no longer valid or is not created yet. VALID_GUEST An ICX session exists and is valid, but the associated user is currently GUEST. VALID A valid ICX session exists and the associated user is a named FND user (non-GUEST user). EXPIRED_GUEST A guest user ICX session exists, but has timed out. EXPIRED A named FND user ICX session exists, but has timed out.
An ICX session also has a context which represents the contextual state under which a client is interacting at a particular point of time. A context thus consists of function ID, application ID, responsibility ID, security ID, group ID and the localization (NLS) information. This information defines the state of client interaction. ICX Cookie An Oracle E-Business Suite session is known as an ICX session. The ICX session is uniquely identified by a HTTP cookie known as the ICX cookie. The name of the cookie is usually same as the value of $TWO_TASK. ICX session-specific values are maintained in the ICX_SESSIONS and ICX_SESSION_ATTRIBUTES tables. Session Attribute Oracle E-Business Suite allows applications to bind objects to an ICX user session and later retrieve the objects in subsequent page requests. Therefore, session-related objects can be shared and reused across requests in the same user session, allowing the application to easily manage its state information. Such state information can also be shared with external applications based on Oracle E-Business Suite SDK. A session attribute is an object that is bound to the ICX session. It consists of a key-value pair. As long as the session is alive, given a key, you can query for the value.
Session Management Classes and APIs

The EBiz Class
The Message Dictionary, user profiles, and session management features all use a special object known as EBiz. The EBiz class is an object representation of the Oracle E-Business Suite environment with which you are integrating your application. The EBiz class holds various system-wide environment information such as protocol,
domain name, GUEST user name, database_id, whether the system is Release 11i or Release 12, and so on. This environment information is independent of user, application, responsibility, or ICX session and is made up of values that are static or unlikely to change. The EBiz class also exposes several APIs for site level profile values, message resources and NLS details. Since EBiz holds environment-wide system information, we only need a single instance of this class because the state of this instance never changes from user to user or session to session. You should create a utility class for your application that maintains a singleton oracle.apps.fnd.ext.common.EBiz instance. The EBiz API constructor signature for oracle.apps.fnd.ext.common.EBiz class is:
public EBiz(Connection connection, String applServerID) throws SQLException{ }
The EBiz object requires a connection and an applServerID as parameters. The applServerID parameter is the unique APPL_SERVER_ID value contained in the desktop DBC file used to set up the AppsDataSource. It is a node-specific value that cannot be known until the desktop DBC file is created for the external node machine. The desktop DBC file contents look similar to the following:
#Desktop DB Settings #Tue Nov 29 00:49:33 PST 2011 FNDNAM=APPS APPL_SERVER_ID=B2DBB2831ADF0A76E040B98BB01553703274985743148928407490481 5433153 APPS_JDBC_URL=jdbc\:oracle\:thin\:@(DESCRIPTION\= (ADDRESS_LIST\=(LOAD_BALANCE\=YES)(FAILOVER\=YES) (ADDRESS\=(PROTOCOL\=tcp)(HOST\=myhost.mycompany.com) (PORT\=1539)))(CONNECT_DATA\=(SID\=mydbsid))) GWYUID=APPLSYSPUB/PUB
How you retrieve the applServerID from the desktop DBC file depends on your application. For example, for some applications, you may require the application server administrator to put the node-specific value into a plan.xml file or the web.xml file or other source. Your application can then retrieve the applServerID as a context parameter (<context-param> </context-param>) from that source.
Important: Never hardcode the value of the applServerID in your
application.
Providing the connection for the EBiz object depends on AppsDataSource. You should write a utility class such as a ConnectionProvider class to obtain a connection based on the AppsDataSource you are using for your application. Once you have the connection provider class with a getConnection() method, you can use it to obtain a connection whenever you need one as follows:
Connection conn = ConnectionProvider.getConnection();
EBiz Class APIs The following major APIs are provided in the
Session Management 6-3
oracle.apps.fnd.ext.common.Session interface to let applications manage the ICX session.

public State getCurrentState()
gets the current state of the ICX session. The state value can be one of: INVALID, VALID_GUEST, VALID , EXPIRED_GUEST , or EXPIRED
public String check()
checks the current ICX session status of this instance. Returns one of: VALID, INVALID or EXPIRED.
public Map<String, Object> getInfo()
Retrieves session column information from ICX_SESSIONS for this session. Returns an immutable Map<String, String> instance containing ICX_SESSIONS stored session information.
public void setAttribute(String key, String value)
Binds an attribute to the current ICX session, using the name specified. If an attribute is already bound under this name, it is replaced. The method either inserts or updates a [key, value] attribute pair to ICX_SESSION_ATTRIBUTES for this session.
public String getAttribute(String key)
gets an attribute value from ICX_SESSION_ATTRIBUTES for this session for the specified key.
public Locale getLocale()
Returns Java Locale for the current ICX session.

Note: Please refer to the Javadoc for the complete set of APIs.
Related APIs
The AppsRequestWrapper, AppsSession, and AppsSessionHelper classes also provide APIs that help you manage your Oracle E-Business Suite session. For an example of how the various classes can be used together, please see "Java EE Session Management Tutorial, page 10-1".
AppsRequestWrapper Class APIs

getConnection()
Retrieves a JDBC connection whose database session is already initialized with Oracle E-Business Suite context information such as the NLS context.
7
Message Dictionary
Using Message Dictionary Routines

Oracle Application Object Library provides a feature called Message Dictionary that can be used to store and display errors and other messages to end users and others. Message Dictionary differs from logging in that Message Dictionary messages can be used as the source of text strings for logging and other purposes, but Message Dictionary does not handle where the text strings go. Message Dictionary messages reside in the database, can be reused, and can be changed and translated without recompiling application code. Message Dictionary can be used with PL/SQL, C code, and Java code. Message Dictionary is documented in the following locations: Oracle E-Business Suite Developer's Guide (formerly Oracle Applications Developer's Guide), "Message Dictionary ". This chapter describes how to create messages in Message Dictionary, PL/SQL APIs for retrieving and displaying messages, and content standards for writing messages. This is the primary source of information about Message Dictionary. Oracle E-Business Suite System Administrator's Guide - Configuration, "Loaders", "Functional Administrator and Functional Developer Tasks" and other locations. Message Dictionary is used by all Oracle E-Business Suite applications, so generating message files, maintaining messages in Message Dictionary, and similar tasks are covered here and in the corresponding online help. Oracle Application Framework Developer's Guide, "Internationalization" and throughout the guide. This chapter describes how developers should include translated messages into their code using Message Dictionary. It also includes Oracle Application Framework Java APIs for Message Dictionary. These APIs are heavily dependent on many other parts of the Oracle E-Business Suite code and require a full middle tier installation of the Oracle E-Business Suite.
The rest of this document assumes you are familiar with the documentation resources
Message Dictionary 7-1
listed above. The Oracle E-Business Suite SDK for Java provides lightweight Message Dictionary APIs to be used for external Java EE programs. These external Java EE programs typically reside on an external server/node that is not co-located with the Oracle E-Business Suite middle tier installation. For example, the lightweight implementations of AppsDataSource and JAAS for Oracle E-Business Suite (also in The Oracle E-Business Suite SDK for Java) require a lightweight implementation of the Oracle E-Business Suite Message Dictionary APIs. External applications cannot use the Message Dictionary APIs documented in the resources mentioned previously, because those APIs are heavily dependent on many other parts of the Oracle E-Business Suite code and require a full middle tier installation of the Oracle E-Business Suite. All of the Message Dictionary routines in the SDK require a reference to the EBiz object.
Terminology
Message Name A non-updatable internal identifier for a message. A message name can be up to 30 characters of text. A message name, together with your application short name and language code uniquely identifies your message text. You specify the message name when you call the Message Dictionary API from a program module. Message Text Text your application displays or prints to an output file. You can define your message text to be up to about 1800 characters long (about 1260 in English to allow for translation into longer languages such as German). Variable Token A keyword you create to represent a value when you define a message. You specify the same variable token, along with its current value, when you call the Message Dictionary API from your program module. The API replaces each variable token in your message with the current value you specify and then displays the message.
Message Dictionary APIs

The following APIs are provided in oracle.apps.fnd.ext.common.MessageDirectory to let applications to read messages from Message Dictionary. To use these APIs you must first get a message directory from the EBiz object.
public String getMessageText(String appName, String mesgName, String langCode, Connection connection)
Returns message text given an application short name, message name and language code that identifies a message in Message Dictionary.
public String getMessageText(String appName, String mesgName, String langCode, Stack<MessageToken> tokens, Connection conn)
Same as the method above except that you can pass a list of variable tokens.
setToken?
Example getMessageText Example

import=oracle.apps.fnd.ext.common.AppsRequestWrapper import=oracle.apps.fnd.ext.common.EBiz import=oracle.apps.fnd.ext.common.Session ... //First we instantiate the wrapped request and using that we get the //EBiz instance AppsRequestWrapper wrappedRequest = (AppsRequestWrapper) request; EBiz ebiz = wrappedRequest.getEbizInstance(); Connection conn = wrappedRequest.getConnection(); String myLangCode = wrappedRequest.getLangCode(); //Now we can get the message directory from EBiz and then retrieve the message //into the string myMessageText MessageDirectory msgdir = ebiz.getMessageDirectory(); String mesgName = "MY_ERROR_MESSAGE_NAME""; String appName = "FND"; String myMessageText = msgdir.getMessageText(appName, mesgName, myLangCode, conn); //Now we can do anything we want with the text in the string ...
Message Dictionary 7-3
8
User Profiles
This chapter covers the following topics: User Profiles
User Profiles
Oracle Application Object Library provides a feature called user profiles that can be used to change the way your application looks and behaves. User profiles can be used with PL/SQL, C code, and Java code. User profiles are documented in the following locations: Oracle E-Business Suite Developer's Guide (formerly Oracle Applications Developer's Guide), "User Profiles". This chapter describes how to define new user profile options for use in applications. The chapter also includes PL/SQL and C APIs for setting and getting profile option values. Oracle E-Business Suite System Administrator's Guide - Maintenance, "User Profiles", "Profile Options in Oracle Application Object Library" and other locations. The "User Profiles" chapter describes profile hierarchies as well as how system administrators set profile options for their sites and users. The "Profile Options in Oracle Application Object Library" appendix describes specific profile options used within the entire Oracle E-Business Suite. Oracle Application Framework Developer's Guide, "Oracle Application Framework Profile Options" and throughout the guide. This appendix describes profile options used in Oracle Application Framework. Other documents throughout the Oracle E-Business Suite decribe the use of various profile options used in specific modules.
The rest of this section assumes you are familiar with the documentation resources listed above.
User Profiles 8-1
Terminology
Profile Option Code A non-modifiable internal identifier for a profile option whose value you wish to use. Profile Levels Profile options exist at Site, Application, Responsibility and User levels. Oracle E-Business Suite treats profile levels as a hierarchy, where User is the highest level of the hierarchy, followed by Responsibility, Application and at the lowest level, Site. Higherlevel option values override lowerlevel option values. Each profile option ordinarily exists at each level. For example, Oracle Application Object Library provides a sitelevel Printer option, an applicationlevel Printer option, and so on. Oracle Application Object Library enforces the level hierarchy to ensure that higherlevel option values override lowerlevel values. As a result, if your Sitelevel Printer value is "New York", but your Userlevel Printer value is "Boston", your reports print on the Boston printer. For more information refer "Oracle Applications System Administrator's Guide". Site Level Site is the lowest user profile level. Sitelevel option values affect the way all applications run at a given installation. Application Level Application is the user profile level immediately above Site. Applicationlevel option values affect the way a particular application runs. Responsibility Level Responsibility is the user profile level immediately above Application. Responsibility level option values affect the way applications run for all users of a responsibility. User Level User is the highest user profile level and is immediately above Responsibility. User level option values affect the way applications run for an application user.
APIs
The following APIs are provided in oracle.apps.fnd.ext.common.ProfileDirectory to let applications manage profiles.
public String getSpecificProfile(String name, String userId, String appId, String respId, String orgId, String serverId, Connection connection)
Returns the profile value for a given key and profile level.
public boolean saveSpecificProfile(String pName, String pValue, String pLevelName, String pLevelValue, String pLevelValueAppId, Connection connection)
Sets a value for a profile option at the specified profile level. If a profile value already exists, it will reset the value to this new value.
User Profiles 8-3
9
Navigation to External Applications
This chapter covers the following topics: Launching an External Application from the Oracle E-Business Suite Home Page
Launching an External Application from the Oracle E-Business Suite Home Page
Release 12.1.3 and Up Only: Regardless of how or if an Oracle ADF 11g application integrates with Oracle E-Business Suite data on the back end, launching an external Java EE application (including Oracle ADF 11g applications) from the OA Framework home page in Oracle E-Business Suite is simple with the addition of new features in Oracle E-Business Suite Applications Technology Release 12.1.3. Note that this mechanism is only for launching Java EE application pages; it does not provide session management or other features that would allow a user to navigate back to the Oracle E-Business Suite UI from the external application.
1.
The external Java EE or Oracle ADF application must be located on a separate application tier server machine from the Oracle E-Business Suite application server. The external application is deployed using Oracle WebLogic Server 11g or another appropriate application server. In the Oracle E-Business Suite, set the value of the FND_EXTERNAL_ADF_URL profile option to the context root of the URL for the application, such as http://www.myhost.com:7001/my-context-root. The profile option may be set at whatever level is appropriate (site, responsibility, and so on). See Oracle E-Business Suite System Administrator's Guide - Maintenance for further information on setting profile options. Create a new Oracle E-Business Suite function using the ADFX function type for either Oracle ADF or other Java EE pages. Set the HTML Call as: GWY.jsp?targetPage=faces/<page name>. For example:
2.
3.
4.
Navigation to External Applications 9-1
GWY.jsp?targetPage=faces/MyADFShoppingAppDashboard 5.
Incorporate the new function into Oracle E-Business Suite function security by adding it onto a menu and creating appropriate roles, responsibilities, and grants. See Oracle E-Business Suite System Administrator's Guide - Security for further information on setting up function security. Select the new link from the Oracle E-Business Suite home page to go to the external application. You may also call your function from within Oracle Application Framework-based pages the same way you call other registered functions.
6.
7.
Embedding External Application Pages inside Oracle Application Framework Pages

Once you have created an ADFX function as previously described, you can embed your Java EE or Oracle ADF page inside an Oracle Application Framework-based page. For example, a display-only graph is an ideal object for this type of embedding. In your Oracle Application Framework page, create a rich container object. Call your function from the rich container.
10
This chapter covers the following topics: Java EE Session Management Tutorial About the Tutorial Application Building the Tutorial Application

Here is a worked Java EE example that you can follow as a tutorial for using the Oracle E-Business Suite SDK for Java. It includes the following features
1. 2.
Session management Message Dictionary
About the Tutorial Application

The following section walks you through a simple demo application. The use case of the sample application is as follows:
1.
When a user tries to directly access our application, the user needs to authenticate first. If a user is found to be unauthenticated by our application, then the application will redirect the user to Oracle E-Business Suite AppsLocalLogin.jsp. Once the user authenticates on AppsLocalLogin.jsp, the user can launch our application as a menu function on the Oracle E-Business Suite home page. When an authenticated user accesses our application, the home (landing) page will display the user's username, when the user's account was created, and when the last logon happened. In the page, the user can query Message Dictionary messages by giving a message name and clicking the submit button, and the page will display the text of the message retrieved from Message Dictionary.
2.
3.
Java EE Session Management Tutorial 10-1
4.
The user can logout from our application by selecting the logout link on the page.
For simplicity, we will use standard Servlet and JSP classes and avoid using any Java EE framework classes while developing this application. Our example contains three JSP files:
1. 2. 3.
index.jsp (the initial page) home.jsp (the main page or landing page) logout.jsp (logout page)
Our example also contains several Java files:

1. 2. 3. 4. 5. 6.
ConnectionProvider.java EBizUtil.java EBSWrapperFilter HomeServlet.java web.xml (deployment descriptor) Logout.java
We must also include the fndext.jar library in our classpath and set up AppsDataSource. Here is a picture of the overall application:
Building the Tutorial Application

Set up AppsDataSource:
All of the Oracle E-Business Suite SDK for Java classes require AppsDataSource, so first
we set up AppsDataSource in our application server according to the AppsDataSource setup instructions, page 2-1. For some IDEs you can set up AppsDataSource within the IDE. For this tutorial we use Oracle JDeveloper, and we set up our AppsDataSource within JDeveloper. We start by first choosing View > Application Server Navigator from the JDeveloper menu.
From within the Application Server Navigator, we select Launch Admin Console... from the context menu.
From that point everything is the same as covered in the instructions setting up AppsDataSource for Oracle WebLogic Server. We specify a JNDI name of jdbc/myAppsDataSource for our application. This name will be hard coded into our ConnectionProvider.java class.
ConnectionProvider.java:
Now that we have a JNDI-bound datasource, we create a centralized utility class for getting a connection, ConnectionProvider.java:
package com.oracle.ebssdkdemo.demo; import java.sql.Connection; import java.sql.SQLException; import javax.naming.Context; import javax.naming.InitialContext; import javax.naming.NamingException; import javax.sql.DataSource; public class ConnectionProvider { private static DataSource myDS = null; static { try { Context ctx = new InitialContext(); myDS = (DataSource)ctx.lookup("jdbc/myAppsDataSource"); // your datasource jndi name as defined during configuration if (ctx != null) ctx.close(); } catch (NamingException ne) { //ne.printStackTrace();//ideally you should log it throw new RuntimeException(ne); // means jndi setup is not correct or doesn't exist } } private ConnectionProvider() { } public static Connection getConnection() throws SQLException { if (myDS == null) throw new IllegalStateException("AppsDatasource is not properly initialized or available"); return myDS.getConnection(); } }
Now that we have our connection provider, we can use it anytime we need a connection:
Connection conn = ConnectionProvider.getConnection();
EBizUtil.java :
Next we create an EBizUtil class that takes the connection and applServerID objects and instantiates the EBiz object. This EBizUtil class maintains the EBiz object as a singleton.
package com.oracle.ebssdkdemo.demo; import java.sql.Connection; import java.sql.SQLException; import java.util.logging.Level; import java.util.logging.Logger; import oracle.apps.fnd.ext.common.EBiz; public class EBizUtil { private static final Logger logger = Logger.getLogger(EBizUtil.class.getName()); private static EBiz INSTANCE = null; static { Connection connection = null; try { connection = ConnectionProvider.getConnection(); // DO NOT hard code applServerID for a real application // Get applServerID as CONTEXT-PARAM from web.xml or elsewhere INSTANCE = new EBiz(connection, "B26134EFA9132575E040B98BD4152CED56206783189836025826612897843129"); } catch (SQLException e) { logger.log(Level.SEVERE, "SQLException while creating EBiz instance -->", e); throw new RuntimeException(e); } catch (Exception e) { logger.log(Level.SEVERE, "Exception while creating EBiz instance -->", e); throw new RuntimeException(e); } finally { if (connection != null) { try { connection.close(); } catch (SQLException e) { } } } } public static EBiz getEBizInstance() { return INSTANCE; } }
EBSWrapperFilter.java:
Next we are going to write a servlet filter. A servlet filter is not strictly required, but it offers a good design practice where we can instantiate an oracle.apps.fnd.ext.common.AppsRequestWrapper object in the filter and then push it down transparently through the service layer in the doGet() and doPost() methods using:
chain.doFilter(appsRequestWrapper, response);
Here we create our filter class:
package com.oracle.ebssdkdemo.demo; import java.io.IOException; import java.sql.SQLException; import java.util.logging.Level; import java.util.logging.Logger; import import import import import import import import javax.servlet.Filter; javax.servlet.FilterChain; javax.servlet.FilterConfig; javax.servlet.ServletException; javax.servlet.ServletRequest; javax.servlet.ServletResponse; javax.servlet.http.HttpServletRequest; javax.servlet.http.HttpServletResponse;
import oracle.apps.fnd.ext.common.AppsRequestWrapper; import oracle.apps.fnd.ext.common.AppsRequestWrapper.WrapperException; public class EBSWrapperFilter implements Filter { private static final Logger logger = Logger.getLogger(EBSWrapperFilter.class.getName()); public void destroy() { logger.info("Filter destroyed "); } public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { logger.info("-current URI =" + ((HttpServletRequest)request).getRequestURI()); AppsRequestWrapper wrapper = null; try { wrapper = new AppsRequestWrapper((HttpServletRequest)request, (HttpServletResponse)response, ConnectionProvider.getConnection(), EBizUtil.getEBizInstance()); } catch (WrapperException e2) { logger.log(Level.SEVERE, "WrapperException error encountered ", e2); throw new ServletException(e2); } catch (SQLException e2) { logger.log(Level.SEVERE, "SQLException error encountered ", e2); throw new ServletException(e2); } try { logger.info("Created AppsRequestWrapper object." +
" Continuing the filter chain."); chain.doFilter(wrapper, response); logger.info("- the filter chain ends"); } finally { //AppsRequestWrapper caches a connection internally. //AppsRequestWrapper.getConnection()--returns this connection //this connection can be used in doGet()/doPost() service layer //whenever our application requires a connection in order to //service the current request. //When AppsRequestWrapper instance is in use, this connection //should not be closed by other code. //At this point, we are done using AppsRequestWrapper instance //so, as good practice, we are going to close (release) this //connection now if (wrapper != null) { logger.info("- releasing the connection attached to the" + " current AppsRequestWrapper instance "); try { wrapper.getConnection().close(); } catch (SQLException e3) { logger.log(Level.WARNING, "SQLException error while closing connection-- ", e3); } } wrapper = null; } } public void init(FilterConfig filterConfig) throws ServletException { logger.info("Filter initialized "); } }
HomeServlet.java:
Our servlet layer includes a HomeServlet class that does processing for our landing page (home.jsp). This class checks whether the user is authenticated. That is, we check whether the current ICX session is valid. If the ICX session is valid, the servlet does further processing and forwards to the home.jsp page. Otherwise (ICX session not valid), the servlet redirects to the Oracle E-Business Suite login page (AppsLocalLogin.jsp). This class also manages certain ICX session attributes that we intend to display on the home.jsp page. In both the doGet() and doPost() methods, we query the FND_USER
table for last logon time and user creation date for the current user and cache them on the HTTP session. If the servlet is being called in the doPost() method, our servlet also takes the message name and application short name entered by the user in home.jsp and performs the query to retrieve the message text. Here is our HomeServlet class:
package com.oracle.ebssdkdemo.demo; import java.io.IOException; import import import import import import import import import import import import import java.sql.PreparedStatement; java.sql.ResultSet; java.sql.SQLException; java.sql.Timestamp; java.util.Calendar; java.util.Date; java.util.logging.Level; java.util.logging.Logger; javax.servlet.ServletException; javax.servlet.http.HttpServlet; javax.servlet.http.HttpServletRequest; javax.servlet.http.HttpServletResponse; javax.servlet.http.HttpSession;
import oracle.apps.fnd.ext.common.AppsRequestWrapper; import oracle.apps.fnd.ext.common.CookieStatus; import oracle.apps.fnd.ext.common.Session; /** * Servlet implementation class HomeServlet */ public class HomeServlet extends HttpServlet { private static final long serialVersionUID = 1L; private static final Logger logger = Logger.getLogger(HomeServlet.class.getName()); private static final String SQL = "select CREATION_DATE,LAST_LOGON_DATE from FND_USER " + "where USER_ID =:1"; /** * @see HttpServlet#HttpServlet() */ public HomeServlet() { super(); } /** * @see HttpServlet#doGet(HttpServletRequest request, * HttpServletResponse response) */ protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { AppsRequestWrapper wrappedRequest = (AppsRequestWrapper)request; if (!isAuthenticated(wrappedRequest, response)) { logger.info("doGet()--No valid FND user ICX session exists" + " currently. Redirecting to EBS AppsLogin
page"); String agent = wrappedRequest.getEbizInstance().getAppsServletAgent(); response.sendRedirect(agent + "AppsLocalLogin.jsp"); return; } logger.info("doGet()---we got a valid ICX session. Proceeding."); manageAttributes(wrappedRequest, response); wrappedRequest.getRequestDispatcher("/WEB-INF/home.jsp") .forward(wrappedRequest, response); } private boolean isAuthenticated(AppsRequestWrapper wrappedRequest, HttpServletResponse response) throws ServletException { Session session = wrappedRequest.getAppsSession(true); // It is always good to check for nullability // A null value means something went wrong in the JDBC operation if (session == null) throw new ServletException("Could not initailize ICX session object"); CookieStatus icxCookieStatus = session.getCurrentState().getIcxCookieStatus(); if (!icxCookieStatus.equals(CookieStatus.VALID)) { logger.info("Icx session either has expired or is invalid"); return false; } return true; } // // // table // // we query now -user name --from ICX_SESSIONS table the last time when the user logged into EBS -- from FND_USER when the user account was created -- from FND_USER table we intend to display these values on the home page
private void manageAttributes(AppsRequestWrapper wrappedRequest, HttpServletResponse response) throws ServletException { // First check whether we already have the values cached in the // HTTP session. Note, this is the HTTP session provided by the // application server, not our ICX session HttpSession httpSession = wrappedRequest.getSession(true); String currentUser =
(String)httpSession.getAttribute("currentUser"); Session session = wrappedRequest.getAppsSession(); // this gives us a // handle to our ICX // session if (currentUser == null) { // we need to read it from ICX session currentUser = session.getUserName(); // for performance reason, we can cache it in httpSession // for future HTTP requests httpSession.setAttribute("currentUser", currentUser); } Timestamp lastLogon = (Timestamp)httpSession.getAttribute("LAST_LOGON"); Timestamp createdOn = (Timestamp)httpSession.getAttribute("CREATED_ON"); if (lastLogon == null || createdOn == null) { // we are going query EBS // DB PreparedStatement stmt = null; try { stmt = wrappedRequest.getConnection() .prepareStatement(SQL); stmt.setInt(1, Integer.parseInt(session.getUserId())); ResultSet rs = stmt.executeQuery(); while (rs.next()) { createdOn = (Timestamp)rs.getObject("CREATION_DATE"); lastLogon = (Timestamp)rs.getObject("LAST_LOGON_DATE"); logger.info("DB query returned CREATION_DATE=" + createdOn + " ; LAST_LOGON_DATE =" + lastLogon); break; // we are expecting only one row } //cache values for future httpSession.setAttribute("LAST_LOGON", lastLogon); httpSession.setAttribute("CREATED_ON", createdOn); // we want to display createdOn & lastLogon in a nice human// readable format long longTime = createdOn.getTime(); Date date = new Date(longTime); // we now format the date as per DATE_FORMAT_MASK for this // ICX session String formattedDate = session.getDateFormat().format(date);
httpSession.setAttribute("FORMATTED_CREATION_DATE", formattedDate); // Now we process lastLogon longTime = lastLogon.getTime(); date = new Date(longTime); String formattedLogonDate = session.getDateFormat().format(date); httpSession.setAttribute("FORMATTED_LOGON_DATE", formattedLogonDate); // also process the time (hour:min:second) part // Unfortunately session.getDateFormat() (which is based on // underlying DATE_FORMAT_MASK) doesn't have a formatter // for the time part, so we are going to do ourselves using // user Locale Calendar cal = Calendar.getInstance(session.getLocale()); int hour = cal.get(Calendar.HOUR_OF_DAY); int min = cal.get(Calendar.MINUTE); int sec = cal.get(Calendar.SECOND); String formattedTime = new StringBuilder().append(hour).append(":") .append(min).append(":").append(sec).toString(); httpSession.setAttribute("FORMATTED_LOGON_TIME", formattedTime); } catch (SQLException e) { logger.log(Level.SEVERE, " SQLException error-->", e); throw new ServletException(e); } catch (Exception e) { logger.log(Level.SEVERE, " Unknown error-->", e); throw new ServletException(e); } finally { if (stmt != null) { try { stmt.close(); } catch (SQLException e) { // e.printStackTrace(); } } } } } protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { AppsRequestWrapper wrappedRequest = (AppsRequestWrapper)request;
if (!isAuthenticated(wrappedRequest, response)) { logger.info("doPost()--No valid FND user ICX session exists" + " currently. Redirecting to EBS AppsLogin page"); String agent = wrappedRequest.getEbizInstance().getAppsServletAgent(); response.sendRedirect(agent + "AppsLocalLogin.jsp"); return; } // process the request String mesgName = request.getParameter("message_name"); String appName = request.getParameter("app_name"); request.setAttribute("message_text", wrappedRequest.getEbizInstance() .getMessageDirectory() .getMessageText(appName.toUpperCase(), mesgName.toUpperCase(), wrappedRequest.getConnection())); // Note, we are not closing wrappedRequest.getConnection() connection // here. // Our EBSWrapperFilter takes care of that manageAttributes(wrappedRequest, response); wrappedRequest.getRequestDispatcher("/WEB-INF/home.jsp") .forward(wrappedRequest, response); } }
Note how we are casting the HttpServletRequest request object in doGet() and doPost() methods:
AppsRequestWrapper wrappedRequest = (AppsRequestWrapper) request;
We can do so because of our filter class. HttpServletRequest request is simply our AppsRequestWrapper object that was passed through our filter class earlier.
home.jsp:
Here is the JSP for our main (landing) page.
<%@ page language="java" contentType="text/html; charset=windows-1252" pageEncoding="UTF-8"%> <%@page import="java.sql.Timestamp"%> <%@page import="java.util.Date"%> <%@page import="oracle.apps.fnd.ext.common.AppsRequestWrapper"%> <%@page import="oracle.apps.fnd.ext.common.EBiz"%> <%@page import="oracle.apps.fnd.ext.common.Session"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"/> <title>Demo Home Page</title> </head> <body> <div> <a href="<%=request.getContextPath()%>/logout">Log out</a> </div> <h4>Your profile </h4> <% AppsRequestWrapper wrappedRequest = (AppsRequestWrapper) request; EBiz ebiz = wrappedRequest.getEbizInstance(); %> <div> <%= ebiz.getMessageDirectory().getMessageText("FND","FND_SSO_USER_NAME", wrappedRequest.getLangCode(),wrappedRequest.getConnection() ) %> : <%= (String)session.getAttribute("currentUser") %> <br/> Registered since : <%= (String)session.getAttribute("FORMATTED_CREATION_DATE") %><br/> Last login on <%= (String)session.getAttribute("FORMATTED_LOGON_TIME") %>, <%= (String)session.getAttribute("FORMATTED_LOGON_DATE") %> </div> <div> Query for a message text here.<br/> Note, we are not doing any input validation here. Please be nice and provide only valid inputs! <br/> <form action="<%=request.getContextPath()%>/home" method="post"> <p> Message Name:<input name="message_name" type="text"/><br/> (such as FND) </p> <p> App ShortName:<input name="app_name" type="text"/><br/> (such as ABOUT_PAGE_ERROR_MSG)<input type="submit"/> </p> </form> </div> <% String method = request.getMethod(); if("POST".equalsIgnoreCase(method) ){ %> You queried for message name <%= request.getParameter("message_name") %>, application shortName <%= request.getParameter("app_name") %> <br/> The result is: <%= (String)request.getAttribute("message_text") %>
<% } %> </body> </html>
Note how we are using ebiz.getMessageDirectory().getMessageText() here in this JSP to display "User name" as a label. For example, if the user logs in as SYSADMIN, then the page will display: User Name: SYSADMIN. The JSP also has a HTML form using which the user can query for a message using the application short name and message name as query keys. Using the same HomeServlet, we handle this message query in the doPost() method.
Logout.java:
Here is our logout servlet.
package com.oracle.ebssdkdemo.demo; import java.io.IOException; import java.util.logging.Logger; import import import import javax.servlet.ServletException; javax.servlet.http.HttpServlet; javax.servlet.http.HttpServletRequest; javax.servlet.http.HttpServletResponse;
import oracle.apps.fnd.ext.common.AppsRequestWrapper; import oracle.apps.fnd.ext.common.AppsSessionHelper; import oracle.apps.fnd.ext.common.Session; /** * Servlet implementation class Logout */ public class Logout extends HttpServlet { private static final long serialVersionUID = 1L; private static final Logger logger = Logger.getLogger(Logout.class.getName()); /** * @see HttpServlet#HttpServlet() */ public Logout() { super(); } /** * @see HttpServlet#doGet(HttpServletRequest request, * HttpServletResponse * response) */ protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { logger.info("Logout()----logging out the user--"); //invalidate ICX session & http session AppsRequestWrapper wrappedRequest = (AppsRequestWrapper)request; Session session = wrappedRequest.getAppsSession(); //logout only if it is present if (session != null) { AppsSessionHelper helper = new AppsSessionHelper(wrappedRequest.getEbizInstance()); helper.destroyAppsSession(wrappedRequest.getAppsSession(), wrappedRequest, response); } request.getSession(true).invalidate(); wrappedRequest.getRequestDispatcher("/WEB-INF/logout.jsp") .forward(wrappedRequest, response); } /** * @see HttpServlet#doPost(HttpServletRequest request,
* HttpServletResponse response) */ protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doGet(request, response); } }
logout.jsp:
Here is our logout JSP.
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="UTF-8"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"/> <title>Logout Page</title> </head> <body><div> You have successfully logged out. <br/> <a href="<%=request.getContextPath()%>"> Let's start all over (go back to index page)</a> </div> </body> </html>
index.jsp:
It would be nice to have a welcome page, so we create index.jsp. The index.jsp page does nothing but forward the HTTP request to the HomeServlet.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <%@ page contentType="text/html;charset=windows-1252"%> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"/> <title>Index Page</title> </head> <body><jsp:forward page="/home" /></body> </html>
Logout.java:
Now we code our logout servlet.
package com.oracle.ebssdkdemo.demo; import java.io.IOException; import java.util.logging.Logger; import import import import javax.servlet.ServletException; javax.servlet.http.HttpServlet; javax.servlet.http.HttpServletRequest; javax.servlet.http.HttpServletResponse;
import oracle.apps.fnd.ext.common.AppsRequestWrapper; import oracle.apps.fnd.ext.common.AppsSessionHelper; import oracle.apps.fnd.ext.common.Session; /** * Servlet implementation class Logout */ public class Logout extends HttpServlet { private static final long serialVersionUID = 1L; private static final Logger logger = Logger.getLogger(Logout.class.getName()); /** * @see HttpServlet#HttpServlet() */ public Logout() { super(); // TODO Auto-generated constructor stub } /** * @see HttpServlet#doGet(HttpServletRequest request, * HttpServletResponse * response) */ protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { logger.info("Logout()----logging out the user--"); //invalidate ICX session & HTTP session AppsRequestWrapper wrappedRequest = (AppsRequestWrapper)request; Session session = wrappedRequest.getAppsSession(); //logout only if it is present if (session != null) { AppsSessionHelper helper = new AppsSessionHelper(wrappedRequest.getEbizInstance()); helper.destroyAppsSession(wrappedRequest.getAppsSession(), wrappedRequest, response); } request.getSession(true).invalidate(); wrappedRequest.getRequestDispatcher("/WEB-INF/logout.jsp") .forward(wrappedRequest, response); } /**
* @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse response) */ protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doGet(request, response); } }
logout.jsp:
Here is the logout.jsp corresponding to our logout servlet.
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="UTF-8"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"/> <title>Logout Page</title> </head> <body><div> You have successfully logged out. <br/> <a href="<%=request.getContextPath()%>">Let's start all over (go back to index page)</a> </div> </body> </html>
Deployment descriptor: web.xml

Now we create our web.xml deployment descriptor file. The web.xml file ties all the pieces together in the application server by identifying our filter, the correspondence between our servlets and our JSP files, and so on.
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5"> <display-name>EBSSDKdemo</display-name> <context-param> <param-name>my.context.param</param-name> <param-value>B26134EFA9132575E040B98BD4152CED562067831898360258266128978 43129</param-value> </context-param> <filter> <description>This is my filter</description> <display-name>Http Request Wrapper Filter</display-name> <filter-name>wrapperFilter</filter-name> <filter-class>com.oracle.ebssdkdemo.demo.EBSWrapperFilter</filter-class> </filter> <filter-mapping> <filter-name>wrapperFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> <welcome-file-list> <welcome-file>index.jsp</welcome-file> </welcome-file-list> <servlet> <description>The main servlet for this demo</description> <display-name>HomeServlet</display-name> <servlet-name>HomeServlet</servlet-name> <servlet-class>com.oracle.ebssdkdemo.demo.HomeServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>HomeServlet</servlet-name> <url-pattern>/home</url-pattern> </servlet-mapping> <servlet> <description>Logs user out</description> <display-name>Logout</display-name> <servlet-name>Logout</servlet-name> <servlet-class>com.oracle.ebssdkdemo.demo.Logout</servlet-class> </servlet> <servlet-mapping> <servlet-name>Logout</servlet-name> <url-pattern>/logout</url-pattern> </servlet-mapping> </web-app>
Deploy the application:

Set up your deployment profile.
Once our application is ready, we build a .war file for the application, such as TutorialApp.war that we can deploy on our application server (Oracle WebLogic Server for this tutorial), which is running on an external node. In this case, we are going to deploy on Oracle WebLogic Server that is running on a local desktop and integrate this application with an Oracle E-Business Suite instance running on a remote server. Note that, by default, Oracle WebLogic server on our desktop will be running on localhost:7001. So, if we deploy TutorialApp.war under a context name TutorialApp-context-root, then the application will be available on http://localhost:7001/TutorialApp-context-root. However, both the Oracle E-Business Suite instance and the custom application must share the top-level subdomains and protocol, so we need to change two things first: 1. Open C:\WINDOWS\system32\drivers\etc\hosts file on notepad. Then replace the line 127.0.0.1 localhost with #127.0.0.1 localhost 127.0.0.1 myapp.us.oracle.com 2. This is mandatory if the Oracle E-Business instance is SSL based. In that case: We need to enable SSL on our Oracle WebLogic Server. Login to the Oracle WebLogic Server administration console using the administrator credential. Navigate to Environment >> Servers >> [Your Server Name]>> Configuration >> General Check "SSL Listen Port Enabled" checkbox. Note the SSL listen port 7002 in our case. If the Oracle E-Business Suite instance is not using SSL, this step is not required.
Set up Navigation:
Now we set up the Oracle E-Business Suite function, menu, and responsibility for our application and attach it to a user. In this section we use the Functional Administrator responsibility to create our function and menu. We also use the Functional Administrator responsibility to set the value of the FND_EXTERNAL_ADF_URL profile option that tells the Oracle E-Business Suite where to find our external application. The value of the profile option corresponds to your host name and application server port plus the context root you specified in your deployment profile. For example:
http://myexthost:7101/TutorialApp-context-root/
Test the Application:

Test your application.

EBS Software Development Kit For Java R11i and 12

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

EBS Software Development Kit For Java R11i and 12

Uploaded by

Copyright:

Available Formats

Oracle E-Business Suite

Software Development Kit for Java Release 11i and 12

Using Oracle E-Business Suite Data Sources

Using Lightweight Java Error Logging with Oracle E-Business Suite

Navigation to External Applications

Java EE Session Management Tutorial

Access to Oracle Support

Related Information Sources

Do Not Use Database Tools to Modify Oracle E-Business Suite Data

Introduction to Oracle E-Business Suite SDK for Java 1-1

1-2 Oracle E-Business Suite Software Development Kit for Java

Error Logging Profile Options Message Dictionary

Building External Applications with Oracle ADF

Prerequisite Patches for Oracle E-Business Suite Instance

Introduction to Oracle E-Business Suite SDK for Java 1-3

Instructions for Applying this Patch

1-4 Oracle E-Business Suite Software Development Kit for Java

Overview of Using AppsDataSource and AppsXADataSource

Using Oracle E-Business Suite Data Sources 2-1

2.1.1. Local and Global Transactions (XA Data Sources)

2.1. Configuring AppsDataSource

Register the external node

2-2 Oracle E-Business Suite Software Development Kit for Java

Using Oracle E-Business Suite Data Sources 2-3

FND: Validate IP address

FND: Desktop Nodes allowed

2-4 Oracle E-Business Suite Software Development Kit for Java

2.1.3. Set Up Necessary Oracle E-Business Suite Users

Using Oracle E-Business Suite Data Sources 2-5

2-6 Oracle E-Business Suite Software Development Kit for Java

Using Oracle E-Business Suite Data Sources 2-7

2-8 Oracle E-Business Suite Software Development Kit for Java

2.1.4. Configuring AppsDataSource on an OC4J Instance

2.1.4.1. Deploy AppsDataSource Code on the OC4J Instance:

Log in as the OC4J administrator.

Using Oracle E-Business Suite Data Sources 2-9

Click the Create button on the Shared Libraries page.

2-10 Oracle E-Business Suite Software Development Kit for Java

Click the Add button.

11. Click Next.

Using Oracle E-Business Suite Data Sources 2-11

Import check box for this library.

2-12 Oracle E-Business Suite Software Development Kit for Java

13. Click Finish.

2.1.4.2. Edit application.xml File on OC4J Application Server:

Using Oracle E-Business Suite Data Sources 2-13

Save the file application.xml.

Restart your OC4J instance.

2.1.4.3. Define the Connection in Oracle Enterprise Manager:

2-14 Oracle E-Business Suite Software Development Kit for Java

Click the Create button under the Connection Pools section.

Using Oracle E-Business Suite Data Sources 2-15

2-16 Oracle E-Business Suite Software Development Kit for Java

oracle.apps.fnd.ext.jdbc.datasource.AppsXADataSource for an XA data source).

file in the Value field. For example: /u01/oracle/product/soasuite/apps/thisMidTier.dbc

Using Oracle E-Business Suite Data Sources 2-17

14. Click Finish.

2.1.4.4. Creating a Data Source using Enterprise Manager:

2-18 Oracle E-Business Suite Software Development Kit for Java

Enter the following values for the elements on this page:

Using Oracle E-Business Suite Data Sources 2-19

2.1.4.5. Test Your Connection: