Professional Documents
Culture Documents
Oracle® E-Business Suite: Software Development Kit For Java Release 11i and 12
Oracle® E-Business Suite: Software Development Kit For Java Release 11i and 12
June 2012
Oracle E-Business Suite Software Development Kit for Java, Release 11i and 12
Copyright © 2009, 2012, Oracle and/or its affiliates. All rights reserved.
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
Preface
iii
4 Utilities
4.1. Automated Setup Script...................................................................................................... 4-1
4.2. AdminDesktop Utility........................................................................................................ 4-4
4.2.1. AdminDesktop Usage Examples..................................................................................... 4-4
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
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.
v
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.
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.
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
• 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.
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.
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.
x
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
• Error logging
• Internationalization 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
AppsDataSource AppsDataSource
Profile Options
Message Dictionary
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.
• 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).
• README.txt
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.
• in an application server such as OC4J, page 2-9 or Oracle WebLogic Server, page
2-20
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).
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>
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
4. 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
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).
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.
2. Create a shared library in the OC4J instance using Oracle Enterprise Manager.
1. In your browser, navigate to the Oracle Enterprise Manager for your
application server:
http://<your host>:<your port>/em
5. Click the Go to Task icon for the Shared Libraries line under Administration
Tasks > Properties.
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.
For example:
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
2. Click the Go to Task icon for the JDBC Resources line under Administration Tasks >
Services.
4. Enter "default" under the Application section. Select Managed Data Source under
the Data Source Type section. Click Continue.
2. JNDI location: <by convention you should enter the standard jdbc/<yourName>
for example: jdbc/MyAppsDataSourceDS>
4. Connection Pool: Select the connection pool you defined in the "Creating a
Connection Pool using Enterprise Manager" section above.
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.
4. Create a new directory under a top-level directory such as root (/). For example,
create /tmp/mysrc:
$ mkdir /tmp/mysrc
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
• schemacom_bea_xml
• weblogic
• commo.dtd
• ExtAuthOnlyAuthenticator.xml
• ExtAuthenticator.xml
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
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
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. Log in.
4. Click the New button for Data Sources and select Generic Data Source.
6. Click Next.
7. 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.
4. 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.
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.
...
/**
* 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.
st = null;
rs = null;
dbConn = null;
try {
// We get our java.sql.Connection object from our AppsDataSource
dbConn = this.ads.getConnection() ;
try {
if (dbConn != null) {
dbConn.close();
}
} catch (SQLException e) {
// Ignore...
}
}
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
• 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.
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
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-3
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.
3. Assign grants to your roles to let them access task flows and pages as appropriate
for your application security.
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.
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.
<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>
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-7
10.3.3.0 does not accept the pipe ( | ) character present in Oracle E-Business Suite role
names.
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.
2. 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.
4. 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).
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-9
7. In the Realms table, click the name of your new realm.
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. Select SUFFICIENT in the Control Flag: field and click Save.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-13
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-15
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.
12. Enter XACMLAuthorizer in the Name field and select XACMLAuthorizer from the
Type drop-down list. Click OK.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-17
13. Click the Adjudication tab. Click New.
16. Enter XACMLRoleMapper in the Name field and select XACMLRoleMapper from
the Type drop-down list. Click OK.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-19
17. Click the Credential Mapping tab. Click New.
20. Select WebLogicCertPathProvider from the Type drop-down list. Click Next.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-21
21. Accept the defaulted value for the Name field by clicking Next.
22. Check the Replace Existing Builder check box, and click Finish.
2. Click the Security tab. Select EbsRealm from the Default Realm drop-down list.
Click Save.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-23
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-25
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-27
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.
3. From the Domain Structure pane, click Deployments. The Deployments listing
should show your newly-installed war. Click its link.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-29
4. From the Security tab, select the Application Scope tab, then select the Roles tab,
and click New.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-31
6. From the Stand-Alone Web Application Scoped Roles listing, click the role name
(for example, UMX|DEMO).
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-33
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.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-35
11. Log out of the console, and restart Oracle WebLogic Server.
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.
7. Click the link for the name of your deployed web application.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-37
3.4.3 Change Security Provider:
1. Select the Administration tab.
3. Select Required or Sufficient from the Login Module Control Flag drop-down
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-39
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 Value
connectionMode DATASOURCE
5. Click OK.
Oracle E-Business Suite Implementation of Java Authentication and Authorization Service (JAAS) 3-41
4
Utilities
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.
2. 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.
5. Ensure that typing "echo $WL_HOME" shows the Oracle WebLogic Server
home directory.
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.
3. Shut down and restart Oracle WebLogic Server before proceeding further so
that WebLogic Server reads the rebuilt copies of fndext.jar.
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
• ADD_SERVER - generate a new server ID and associate it with the specified node,
updating the resulting DBC file as well
• 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.
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.
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.
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.
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.
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.
2. 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).
• 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
Using Lightweight Java Error Logging with Oracle E-Business Suite 5-3
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
• 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.
• 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.
Using Lightweight Java Error Logging with Oracle E-Business Suite 5-5
package oracle.apps.fnd.ext.sample;
import java.util.logging.Level;
import java.util.logging.Logger;
import oracle.apps.fnd.ext.logging.ExtendedLevel;
• ERROR
• WARNING
• INFO
• CONFIG
• PROCEDURE
• FINE
• FINER
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.
Because the AppsLogHandler is fully compliant with the JDK Handler specification,
you can also set any of the following optional properties:
Using Lightweight Java Error Logging with Oracle E-Business Suite 5-7
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>
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>
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
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
com.foo.level=FINE
Using Lightweight Java Error Logging with Oracle E-Business Suite 5-9
6
Session Management
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.
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
• 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.
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.
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();
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()
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".
Note: Please refer to the Javadoc for the complete set of APIs.
Retrieves a JDBC connection whose database session is already initialized with Oracle
E-Business Suite context information such as the NLS context.
The rest of this document assumes you are familiar with the documentation resources
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.
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)
//First we instantiate the wrapped request and using that we get the
//EBiz instance
//Now we can get the message directory from EBiz and then retrieve the
message
//into the string myMessageText
String myMessageText =
msgdir.getMessageText(appName, mesgName, myLangCode, conn);
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.
• 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.
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.
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.
Note: Please refer to the Javadoc for the complete set of APIs.
2. The external application is deployed using Oracle WebLogic Server 11g or another
appropriate application server.
4. 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:
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.
6. Select the new link from the Oracle E-Business Suite home page to go to the external
application.
7. You may also call your function from within Oracle Application Framework-based
pages the same way you call other registered functions.
2. Message Dictionary
2. 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.
3. 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.
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. index.jsp (the initial page)
2. EBizUtil.java
3. EBSWrapperFilter
4. HomeServlet.java
6. 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:
Set up AppsDataSource:
All of the Oracle E-Business Suite SDK for Java classes require AppsDataSource, so first
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.
import java.sql.Connection;
import java.sql.SQLException;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.sql.DataSource;
try {
Context ctx = new InitialContext();
myDS = (DataSource)ctx.lookup("jdbc/myAppsDataSource");
// your datasource jndi name as defined during configuration
if (ctx != null)
ctx.close();
private ConnectionProvider() {
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();
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;
static {
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) {
}
}
}
import java.io.IOException;
import java.sql.SQLException;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import oracle.apps.fnd.ext.common.AppsRequestWrapper;
import oracle.apps.fnd.ext.common.AppsRequestWrapper.WrapperException;
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 {
} 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
//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;
}
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
import java.io.IOException;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.util.Calendar;
import java.util.Date;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import 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 {
/**
* @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
String agent =
wrappedRequest.getEbizInstance().getAppsServletAgent();
response.sendRedirect(agent + "AppsLocalLogin.jsp");
return;
}
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;
}
// we query now --
// user name --from ICX_SESSIONS table
// the last time when the user logged into EBS -- from FND_USER
table
// when the user account was created -- from FND_USER table
// we intend to display these values on the home page
String 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
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
}
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();
}
}
AppsRequestWrapper wrappedRequest =
(AppsRequestWrapper)request;
String agent =
wrappedRequest.getEbizInstance().getAppsServletAgent();
response.sendRedirect(agent + "AppsLocalLogin.jsp");
return;
}
request.setAttribute("message_text",
wrappedRequest.getEbizInstance()
.getMessageDirectory()
.getMessageText(appName.toUpperCase(),
mesgName.toUpperCase(),
wrappedRequest.getConnection()));
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;
home.jsp:
Here is the JSP for our main (landing) page.
%>
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>
Logout.java:
Here is our logout servlet.
import java.io.IOException;
import java.util.logging.Logger;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import 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;
request.getSession(true).invalidate();
wrappedRequest.getRequestDispatcher("/WEB-INF/logout.jsp")
.forward(wrappedRequest, response);
}
/**
* @see HttpServlet#doPost(HttpServletRequest request,
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.
import java.io.IOException;
import java.util.logging.Logger;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import 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;
request.getSession(true).invalidate();
wrappedRequest.getRequestDispatcher("/WEB-INF/logout.jsp")
.forward(wrappedRequest, 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>
<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>