Oracle® E-Business Suite Software Development Kit for Java Release 11i and and 12 Part No. E28169-02
June 2012
Oracle E-Business Suite Software Development Kit for Java, Release 11i 11 i and 12 Part No. E28169-02 Copyright © 2009, 2012, Oracle and/or its affiliates. All rights reserved. Primary Author:
Sara Woodhull
Contributor: Deepika Annavarapu, Annavarapu, Mamata Mamata Challagulla, Challagulla, Nitu Chiring, Rajesh Ghosh, Sunil Ghosh, Clara Jaeckel, Pandurang Kamble, Duncan Mills, Vijayakumar 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
Introdu Introductio ction n to Orac Oracle le E-Bus E-Busine iness ss Suite Suite SDK SDK for for Java Java Introduction..................... ............................... .................... .................... .................... ..................... ..................... .................... .................... ..................... ..................... .............. .... 1-1 Prerequisite Patches for Oracle E-Business Suite Instance .................... .............................. ..................... ..................... ............. ... 1-3 Instructions for Applying this Patch .................... .............................. ..................... ..................... .................... .................... .................... ................. ....... 1-4
2
Using Using Oracle Oracle E-Busi E-Busines ness s Suit Suite e Data Data Sources Sources Overview of Using AppsDataSource and AppsXADataSource ..................... ............................... .................... ................2-1 ......2-1 2.1. Configuring AppsDataSource ..................... ............................... .................... .................... ..................... ..................... .................... .................... .......... 2-2 2.1.2. Register the External Node and Generate the Desktop DBC File .................... .............................. ...............2-3 .....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-20 2.2. Using AppsDataSource Directly from Java Programs ................... .............................. ..................... .................... ............. ... 2-31
3 Oracle Oracle E-Busi E-Busines ness s Suite Suite Impleme Implementa ntatio tion n of Java Authent Authentica icatio tion n 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
4
Utilities 4.1. Automated Setup Script ...................................................................................................... 4-1 4.2. AdminDesktop Utility ........................................................................................................ 4-4 4.2.1. AdminDesktop Usage Examples ..................................................................................... 4-4
5
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
6
Session Management Session Management.................................................................................................................6-1 Session Management Classes and APIs ................................................................................... 6-2
7
Message Dictionary Using Message Dictionary Routines .........................................................................................7-1
8
User Profiles User Profiles .............................................................................................................................. 8-1
9
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 o r released recently. Send your comments to us using the electronic mail address:
[email protected] 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 o f Oracle offices is available on our Web site at www.oracle.com.
v
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 no t 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.
2-2
Register the external node
Oracle E-Business Suite Software Development Kit for Java
2.
Generate the desktop DBC file.
3.
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 req uired 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>
Using Oracle E-Business Suite Data Sources
2-3
<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.
In your browser, navigate to the Oracle Enterprise Manager for your application server: http://<your host>:<your port>/em
2-14
2.
Log in as the OC4J administrator.
3.
Select the OC4J instance.
4.
Select the Administration tab.
Oracle E-Business Suite Software Development Kit for Java
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.
Using Oracle E-Business Suite Data Sources
2-15
7.
Select "default" for Application and the Connection Pool Type of " New Connection Pool". Click Continue.
8.
Enter a name for your connection pool.
9.
For Connection Factory Class enter oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource (or
2-16
Oracle E-Business Suite Software Development Kit for Java
5.
Enter the following values for the elements on this page: 1.
Name: <your data source name, for example: MyAppsDataSourceDS>
2.
JNDI location: <by convention you should enter the standard jdbc/<yourName> for example: jdbc/MyAppsDataSourceDS>
3.
Transaction Level: Global & Local Transactions
4.
Connection Pool: Select the connection pool you defined de fined in the "Creating a Connection Pool using Enterprise Manager" section above.
5.
Login Timeout (seconds): 0
Using Oracle E-Business Suite Data Sources
2-19
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
2-20
Oracle E-Business Suite Software Development Kit for Java
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 re built 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 re built 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 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. 2-21 above. 1.
Log in to the Oracle WebLogic Server node as a user who has read and write permissions on the node.
2.
Set up the WebLogic domain environment. Using the appropriate <domain_name> value, run: <domain_name>/bin/setDomainEnv.sh
Using Oracle E-Business Suite Data Sources
2-21
3.
Ensure that typing "echo $WL_HOME " shows the Oracle WebLogic Server home directory.
4.
Create a new directory under a top-level directory such as root (/). For example, create /tmp/mysrc : $ mkdir /tmp/mysrc
5.
Copy the original fndext.jar file from the patch to /tmp/mysrc.
6.
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: •
2-22
META-INF
Oracle E-Business Suite Software Development Kit for Java
•
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.
Open a Windows command prompt.
2.
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.
Copy the original fndext.jar from the patch to D:\mysrc .
6.
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
Using Oracle E-Business Suite Data Sources
2-23
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.
2-24
Shut down the Oracle WebLogic Server.
Oracle E-Business Suite Software Development Kit for Java
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.
Log in.
3.
Navigate to Domain Structure > Services > Data Sources
4.
Click the New button for Data Sources and select Generic Data Source.
Using Oracle E-Business Suite Data Sources
2-25
/** * 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... }
}
Using Oracle E-Business Suite Data Sources
2-33
}
2-34
Oracle E-Business Suite Software Development Kit for Java
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:
3-2
•
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
Oracle E-Business Suite Software Development Kit for Java
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).
3-4
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.
3.
Assign grants to your roles to let them access task flows and pages as appropriate for your application security.
4.
Do not create users within the Oracle ADF Security Wizard.
5.
If needed, use Oracle ADF component-level security using the Oracle ADF expression language (such as menu rendering using #{securityContext.userInRole...}).
6.
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.
Oracle E-Business Suite Software Development Kit for Java
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 s elect "Remove ADF Security Configuration" in the Configure ADF Security wizard. You do not de fine 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.
Set up users and roles, page 3-6 in the Oracle E-Business Suite instance
2.
Edit the web.xml file, page 3-6 for security constraints (container-managed security only)
3.
Set up security role elements, page 3-6 (for Oracle WebLogic Server, container-managed security only)
4.
Set up global access, page 3-7 for all authenticated Oracle E-Business Suite users (optional, for Oracle WebLogic Server, container-managed security only)
5.
Configure JAAS in either Oracle WebLogic Server, page 3-7 or OC4J, page 3-37
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3-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
3-6
Oracle E-Business Suite Software Development Kit for Java
<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
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3-7
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.
3-10
Oracle E-Business Suite Software Development Kit for Java
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3-11
5.
3-12
Select SUFFICIENT in the Control Flag: field and click Save.
Oracle E-Business Suite Software Development Kit for Java
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3-13
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.
3-24
Oracle E-Business Suite Software Development Kit for Java
1.
From the Domain Structure pane, click Deployments. Click Install on the Deployments table.
2.
Browse and select your application war file. Click Next.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3-25
3.
3-26
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.
Oracle E-Business Suite Software Development Kit for Java
4.
Click Finish. You will then see the deployment's configuration screen.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS)
3-27
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.
Import oracle.apps.fnd.ext.logging.ExtendedLevel into your code.
2.
Call ExtendedLevel.ERROR or ExtendedLevel.PROCEDURE as needed in your code, as shown in the following example:
Using Lightweight Java Error Logging with Oracle E-Business Suite
5-5
package oracle.apps.fnd.ext.sampl oracle.apps.fnd.ext.sample; e; import java.util.logging.Level; import java.util.logging.Logger; import oracle.apps.fnd.ext.loggin oracle.apps.fnd.ext.logging.ExtendedLevel; g.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
5-6
Oracle E-Business Suite Software Development Kit for Java
configuration from a properties file lib/logging.properties in the JRE directory. The logging levels are the same s ame 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. •
SEVE SEVERE RE (hig (highe hest st valu value) e)
•
ERROR
•
WARNING
•
INFO
•
CONFIG
•
PROCEDURE
•
FINE
•
FINER
•
FINE FINEST ST (low (lowes estt valu value) e)
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 , 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.L oracle.apps.fnd.ext.logging.Log4jLogHandler og4jLogHandler
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 o f the following optional properties:
Using Lightweight Java Error Logging with Oracle E-Business Suite
5-7
oracle.apps.fnd.ext.logging.Log4jLogHandler.level = oracle.apps.fnd.ext.logging.Log4jLogHandler.level <your desired level> oracle.apps.fnd.ext.logging.Log4jLogHandler.formatter oracle.apps.fnd.ext.logging. Log4jLogHandler.formatter = <your message formatter class name> oracle.apps.fnd.ext.logging.Log4jLogHandler.filter oracle.apps.fnd.ext.logging. Log4jLogHandler.filter = <your log filter class name> oracle.apps.fnd.ext.logging.Log4jLogHandler.encoding 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 oracle.apps.fnd.ext.logging.AppsLogHandler .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 = oracle.apps.fnd.ext.logging.AppsLogHandler.level <your desired level> oracle.apps.fnd.ext.logging.AppsLogHandler.formatter oracle.apps.fnd.ext.logging. AppsLogHandler.formatter = oracle.apps.fnd.ext.logging.AppsLogFormatter oracle.apps.fnd.ext.logging.AppsLogHandler.filter oracle.apps.fnd.ext.logging. AppsLogHandler.filter = <your log filter class name> oracle.apps.fnd.ext.logging.AppsLogHandler.encoding 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 se t these two additional properties in the logging configuration: oracle.apps.fnd.ext.logging.AppsLogHandler.connectionMode = 1 oracle.apps.fnd.ext.logging.AppsLogHandler.connectionMode oracle.apps.fnd.ext.logging.AppsLogHandler.connectionRefer oracle.apps.fnd.ext.logging. AppsLogHandler.connectionReference ence = <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 , 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 mo dules (globally), then AFLOG_MODULE should be set to %.
5-8
Oracle E-Business Suite Software Development Kit for Java
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.loggi oracle.apps.fnd.ext.logging.AppsLogHandler ng.AppsLogHandler
oracle.apps.fnd.ext.logging.AppsLogHandler.connectionMod oracle.apps.fnd.ext.logging .AppsLogHandler.connectionMode e =1 oracle.apps.fnd.ext.logging.AppsLogHandler.connectionReference =jdbc/MyAppsDS
oracle.apps.fnd.ext.logging.AppsLogHandler.level 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 ).
Using Lightweight Java Error Logging with Oracle E-Business Suite
5-9
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,
6-2
Oracle E-Business Suite Software Development Kit for Java
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; } }
Java EE Session Management Tutorial
10-7
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:
10-8
Oracle E-Business Suite Software Development Kit for Java
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." +
Java EE Session Management Tutorial
10-9
<%@ 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") %>
Java EE Session Management Tutorial
10-17
<% } %> </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.
10-18
Oracle E-Business Suite Software Development Kit for Java
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,
Java EE Session Management Tutorial
10-19
10-24
Oracle E-Business Suite Software Development Kit for Java
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.
Java EE Session Management Tutorial
10-25
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.
10-26
Oracle E-Business Suite Software Development Kit for Java