Oracle ADF Essentials on GlassFish 3.1 with EBS datasource

Hi All!

Today I will give you a full guide to install and configure a workable ADF Essentials installation based on a GlassFish 3.1 application server and I will configure an Oracle EBS datasource.

Main steps:

1. GlassFish server installation and base configuration
2. ADF Essentials runtime installation
3. Oracle EBS datasource configuration

Prerequisites

First of all the softwares and their version what you will need to download and use during the installation and configuration:

• JDK 7
• Oracle GlassFish Server OpenSource Edition 3.1 (4.0 is based on the latest J2EE specification and Oracle ADF is not compatible with this version yet) 
• Oracle ADF Essentials 12.1.2 - of course for development you will need the latest Oracle JDeveloper 12.1.2 too
• 13882058 Oracle EBS patch for creating the EBS datasource

Documentations and blog posts I have used during the configuration.

• Shay Shmeltzer's post about "Deploying Oracle ADF Essentials Applications to Glassfish"
• Juan Camilo Rui's post about "Using the Oracle E-Business Suite SDK for Java on ADF Applications - The AppsDataSource"
• Sara Woodhull's post on Steve Chan blog from "AppsDataSource and Java Authentication and Authorization Service for Oracle E-Business Suite"
• Andrejus Baranovskis blog post about the ADF Essentials Security implementation on GlassFish Server.
• 974949.1 note on Oracle Support site
• Oracle EBS SDK documentation (number: E28169_02) within the same note from Oracle Support Site.
• Charlee Chitsuk's post about how to enable Secure Admin feature in GlassFish 3.1

Installation Steps

The installation example commands and directories are MS Windows commands and directories, but an Unix based installation is very similar.

Install JDK 7

First of all install the latest JDK 7 on your server. It is very easy, please read the installation manuals on Oracle site. During the installation I have accepted all default values (do not install anything else, just the JDK and JRE)

Install Glassfish 3.1.2

Installation of a Glassfish 3.1.2 is so easy step again. Just download the zip file and unzip it anywhere you want to. I have unzipped into the C:\ so the glassfish server will be under C:\glassfish3 directory.

After installation start the Glassfish server with the asadmin tool. If you have more then 1 JDK installation on your server before starting the server edit the glassfish\config\asenv.bat - asenv.conf on unix - the set the AS_JAVA parameter to the new JDK 7 installation.
If you have installed and Oracle database on the same server it is possible that the standard GlassFish port (8080) is already occupied. So you have to modify this port number after starting the server on the admin console and restart the whole server.

If you want to do the configuration steps more comfortable you should enable the Secure Admin feature on the GlassFish domain. Follow configuration steps in Charlee Chitsuk's post.
(don't forget to set the admin password before running the enable-secure-admin command!)

Now we could "install" the ADF Essentials library into the new GlassFish domain.

ADF Essentials installation

It's very easy step again. I had to do only to thing, unzip the download ADF Essentials zip file, then made some JVM option configuration on the GlassFish admin console.

1. First unzip the adf_essentials.zip file with "-j" option into the glassfish3\glassfish\domains\domain1\lib directory. The "-j" option is mandatory! If you using other tool than the unzip.exe then you have to ensure that all files what the adf_essentials.zip file is contain are unzipped into the lib directory without any subdirectory!
2. Login into the GlassFish admin console made the following modification under JVM Settings tab on Server-config webpage:
1. Modify the "-XX:MaxPermsize" parameter value to "512m" at least.
2. Add the new "-Doracle.mds.cache" JVM parameter and set it's value to "simple".

From this point you could deploy any ADF Essentials program to this GlassFish server.

EBS datasource configuration

If you already have got an Oracle EBS installation (11i or R12) it is possible that your ADF Essentials application is want to use it's database. Nothing else to do to configure an J2EE datasource. The easiest way if you create a standard JDBC connection using the apps user and it's password. Of course it's possible but from security viewpoint giving the apps password to other's hand isn't a good idea, is it? So the other possibility to do the following configuration mentioned by the Oracle.

First of all read the 974949.1 note, read the E28169_02.pdf file and download the latest EBS SDK patch, then follow the below steps. I will not give you an exactly detailed configuration steps (you could find all necessary technical details (commands etc) in the documents) only a summarization.

1. Check your EBS system that your system is already at the minimal patch level. (You should the ATG RUP modul level) Read the prerequisite part of the document.
2. Made all the necessary registration and configuration on your EBS server. The document contain a wrong order so follow these steps
1. Set Up Necessary Oracle E-Business Suite Users. If your system is an R12 then it is already contain a preconfigure application server EBS user (ASADMIN) whether you want to use it then activate it. If your system is an 11i system then you should create a new user. I mention to not create the ASADMIN user now, create an other one because it could be a problem during an upgrade. Follow the user creation instructions in the document. (You have to have "system administrator" responsibility and "User Management" role for a succesful user creation). Don't add any other role and responsibility except what the document ask! It should have any workable menu point!!
2. Register the External Node. Run the AdminDesktop java tool for registering the GlassFish server. You should set for NODE_NAME parameter the glassfish server full name, for DBC parameter the current .dbc file under $FND_SECURE directory and I mention to set the optional IP_ADDRESS parameter too (for the GlassFish server) - If you want to you could register your own JDeveloper development desktop too, just gave the correct data of your computer. In this case you could use the appsdatasource on your computer for development too.
3. Check the FND_NODES table that it is contain the correct data what you have setted. Check the generated new .dbc file too that it is contain the correct data. (Sometimes the APPLSYSPUB password is incorrectly putted into this new dbc file). Copy this new dbc file to your GlassFish server (the best place if you copy it into the glassfish\domains\domain1\config directory).
4. With a user with system administrator responsibility set the profile options what the document asked on site level to "Desktop only".
5. Set the Desktop node allowed profile option value for the new "ASADMIN" user to your glassfish server full name. Use capitilized characters, it should be the same as you could find in the FND_NODES table. If you registered your development PCs too, then put all new nodes name and separte them with comma.
6. Check that your system is already configured for "SECURE". Check the FND_NODES table content. If not then follow the instructions in the document for this setup.
3. Create the AppsDatasource in the GlassFish server. 
1. Check whether that you already have an ojdbc6dms.jar file under glassfish\domains\domain1\lib directory. If not copy one into it from a 11g, or 12c client or database installation.
2. Copy the fndext.jar fromt the 13882058 patch into the same lib directory.
3. If you don't do it earlier copy the newly generated dbc file into the config directory under domain1.
4. Restart the glassfish server.
5. Now you could register the AppsDataSource on the admin console. These steps are not well documented so do the following steps:
1. Login in into the admin console and open the JDBC Connection Pools menupoint. Start to create a new datasource.
2. Gave the following parameters
1. Set a pool name what you want.
2. For Resource Type choose "javax.sql.XADataSource" value.
3. For Database Driver Vendor choose Oracle value.
4. Next
5. For Datasource Classname set this custom Java class: oracle.apps.fnd.ext.jdbc.datasource.AppsXADataSource.
6. Under Additional Properties set ServerName, PortNumber, DatabaseName, DriverType (thin), URL for your EBS database parameter.
7. Set User and password parameters to the new EBS "ASADMIN" user and password.
8. Create a new parameter with name "dbcFile" and it's value should be point to the new dbc file under config directory. For example "C:\glassfish3\glassfish\domains\domain1\config\db_tst_HOSTNAM.DOMAINNAME.dbc"
9. Finish
3. Test the new connection with the ping button. It's possible that the ping will not work, then correct all problems what you have found in the glassfish's server.log file. The new datasource will not work until the ping will not give back "Ping Suceeded" message! - For example it is possible that the password was mistyped, check it, and check the username and password with the fnd_web_sec.validate_login PL/SQL function in the EBS database.
4. Create a new JDBC Resource. Set the "JDNI/Name" what you want - this name is what you have to use during the ADF development - and set the Pool Name parameter to the newly created datasource's name.

Now you have a configured GlassFish server with an installed ADF Essentials library and a configured EBS datasource without using apps password.

Be aware! This configuration is not enough for creation an EBS based Realm (for example for using the EBS authentication) but is not so far from it. You should develop your own LoginModule class register is in the login.conf then you could configure a Realm. If you interested in please comment this post :)