Howto: Install ADF 10 runtime and deploy ADF BC App to Oracle WebLogic 10.3 running on Linux

This tutorial shows how to deploy an ADF BC Application to an Oracle Weblogic 10.3 Application Server running on Linux.

For the windows installation you should refer to the great tutorial and screencast from Shay Shmeltzer on OTN. Read: Deploying The SRDemo ADF Sample Application on WebLogic Servers
But if you try to adept this way of installation to linux, you’ll probably end up in some errors. That’s from my experience so far. Maybe because the whole ADF / WebLogic / Jdeveloper stuff is quite in development state and will work better in 11g release later on.

• Requirements:
• Oracle WebLogic Server 10.3
• Jdeveloper 10.1.3.4
• Oracle ADF Installer 10.1.3.4

Now, let’s start. The following sections assume that you’ve installed Oracle WebLogic Server 10.3 successful, an empty WebLogic domain is created and there is a ready to deploy ADF BC application or any other ADF application. It doens’t have to be a BC app. I suppose also a toplink app will work, because we will setup the complete ADF runtime on WebLogic, which also for example includes toplink libraries.

1. Setting up ADF Libraries on WebLogic

Before we actually deploy the application onto the WebLogic server we need to install the ADF Runtime libraries on the server. To do this we can use either the installer that is embedded inside JDeveloper or the stand alone ADF Installer utility - which we’ll use in this how-to.
The detailed instructions for setting ADF libraries on WebLogic are described in the deployment chapter of the ADF Developer Guide. (Note that these instruction are for windows installation - we will install on linux!)

1.1 Shutdown WebLogic instance

It’s recommended to shutdown the WebLogic instance for the domain where you want to install the ADF runtime.

1.2 Prepare ADF Installer properties

Download and unzip the ADF Installer. Follow the included “README.html” and edit the “adfinstaller.properties” as follows:

# The absolute path to the directory containing  the ADF jars to be installed.
# This is the location of the directory where you unzipped the adfinsatller.zip
OracleHome = /path_to_adfinstaller_dir/

# Home directory for the destination application server,
# where the ADF Jars need to be installed
DesHome = /your_weblogic_home/wlserver_10.3/

# Specify the platform for the Application Server where the ADF libraries need
# to be installed. This has to be one of the following choices.
# OC4J/AS/TOMCAT/JBOSS/WEBLOGIC
type = WEBLOGIC

# Specify the weblogic domain directory, when choosing the type as WEBLOGIC
UserHome = /your_weblogic_home/user_projects/domains/your_weblogic_domain/

# If the type is OC4J or AS, change the oc4jInstance Name if it is other than the default name home.
Oc4jInstanceName = home

# Specify the install action to be taken.
# Please note, UNINSTALL is not supported with AS
# INSTALL/UNINSTALL/RESTORE
InstallOption = INSTALL

# Please specify the version of the ADF libraries to be restored, in case of
# the RESTORE Option. Uncomment and provide the correct version.

# RES_VERSION = 10.1.3.xx.xx

# Specify if the output should be silent, or written to the screen.
# The installer output is also written to a ${platform}.html file.
# silent = true

1.3 Run ADF Installer

Run the ADF Installer as described in the “README.html”.

fengel@D630fengel:~/Temp/adfinstaller$ java -jar runinstaller.jar adfinstaller.properties
The version for the ADF libraries being installed is 10.1.3.42.70

Installer log will be written to /home/fengel/Temp/adfinstaller//weblogic.html
ADF Runtime Installer
Modify your startup file to invoke the setupadf.cmd(.sh) file to configure your classpath.

Copied  /home/fengel/Temp/adfinstaller/BC4J/lib/adfcm.jar to instance  /opt/bea/wlserver_10.3/ADF/lib/adfcm.jar
Copied  /home/fengel/Temp/adfinstaller/BC4J/lib/adfm.jar to instance  /opt/bea/wlserver_10.3/ADF/lib/adfm.jar
Copied  /home/fengel/Temp/adfinstaller/BC4J/lib/adfmweb.jar to instance  /opt/bea/wlserver_10.3/ADF/lib/adfmweb.jar
[...]

1.4 Remove “^M” from “setupadf.sh”

The ADF Installer creates a “setupadf.sh” script which is responsible for loading ADF libs into classpath. Anyway, this script is buggy and will end up in errors when executed. Reason: The ADF Installer puts a “^M” carriage return character at each end of line. This won’t work on linux.
To remove the “^M” characters at the end of all lines open “setupadf.sh” in vi, use:
:%s/^V^M//g

The ^v is a CONTROL-V character and ^m is a CONTROL-M. When you type this, it will look like this:
:%s/^M//g

Information:
In UNIX, you can escape a control character by preceeding it with a CONTROL-V. The :%s is a basic search and replace command in vi. It tells vi to replace the regular expression between the first and second slashes (^M) with the text between the second and third slashes (nothing in this case). The g at the end directs vi to search and replace globally (all occurrences).

Save “setupadf.sh” and exit vi, use:
:wq

1.5 Replace relative path with ${WL_HOME}

Now open “setupadf.sh” again with a more comfortable editor like kate or gedit. Replace all the relative paths to “../../../wlserver_10.3//” with “${WL_HOME}“.

1.6 Set bc4j lib usage

If your Business Component using Oracle DB you should change the generic BC4J library to the Oracle specific one. Change the “bc4jdomgnrc.jar” to “bc4jdomorcl.jar”:

## bc4j generic
#CLASSPATH=${CLASSPATH}:${WL_HOME}/ADF/jlib/bc4jdomgnrc.jar
## bc4j oracle
CLASSPATH=${CLASSPATH}:${WL_HOME}/ADF/lib/bc4jdomorcl.jar

1.7 Edit “setDomainEnv.sh” to call “setupadf.sh”

The “setDomainEnv.sh” is called by “startWebLogic.sh” and is used to build and export the CLASSPATH. The ADF libs need to be included to CLASSPATH, so the “setupadf.sh” must be called from here.
Open “your_domain/bin/setDomainEnv.sh” with a text editor, scroll down to “#SET CLASSPATH” and append the following changes. In that way the ADF libs are added to CLASSPATH and loaded during startup of the server instance.

# SET THE CLASSPATH
# include ADF runtime libs
. "${DOMAIN_HOME}/setupadf.sh"

CLASSPATH="${PRE_CLASSPATH}${CLASSPATHSEP}${WEBLOGIC_CLASSPATH}${CLASSPATHSEP}${POST_CLASSPATH}${CLASSPATHSEP}${WLP_POST_CLASSPATH}${CLASSPATH}"
export CLASSPATH

Save and exit.

1.8 Start Weblogic Instance

The ADF libs should now be loaded during startup. So start your WebLogic instance:
fengel@D630fengel:/opt/bea/user_projects/domains/adfdomain$ ./startWebLogic.sh
… and check the console output. Here they are:

Now ADF is running on WebLogic.

2 Prepare and deploy ADF BC application

This part shows what is needed for successful deployment of a ADF BC application to Oracle WebLogic 10.3 Application Server.

2.1 Configure Application Module to use JDBC connection

As there are problems using datasource connections you should use JDBC connection for all of your application modules.

2.2 Add libs for BC apps and JDBC support to ViewController Project

For a BC app and JDBC support you need to include some additional libraries to the ViewController Project. Add the following libraries to ViewController Project:

• In the ViewController project properties, go to Libraries.
• Add the following libraries that are needed for the Model project:
  • BC4J Oracle Domains
  • Oracle JDBC
  • SQLJ Runtime

For more information read: How to deploy a JDev 10.1.3 application to OracleAS 10.1.2 (Step 4,5)

2.3 Create Deployment Profile

Add a new “war” deployment profile to your ViewController project:

(You can either create a deployment profile from the context menu of you web.xml.)

2.4 Enable JDBC and BC4J Libs in deployment profile

This step is very essential. If you don’t do this, you’ll end up in a JBO-30003 error when trying to checkout an application module.
The JBDC and BC4J libs need to be include in your deployment. You have to enable them. Go to your “deployment profile > properties > WEB-INF/lib > Contributors” and enable the libs you added to your ViewController project in step 2.2:

Depending on your project requirements you may have to enable other libraries too. For more information read: How to deploy a JDev 10.1.3 application to OracleAS 10.1.2 (Step 7,8,9)

2.5 Deployment

Recommending an established connection to the WebLogic Server you can deploy the application by one-click-deployment from the context menu of the deployment profile.

Otherwise deployment needs to be done in two steps:

1. create *.war archive from deployment profile
2. from inside WebLogic administration console upload *.war archive and deploy.

2.6 Check running application

Now the ADF application should be up and running on WebLogic.

That’s it.