Monday, December 2, 2013

Creating ADF Essentials application with Oracle Enterprise Pack for Eclipse Part 1 of 2

I am going to describe the steps needed to create a sample data bound application built on ADF Essentials framework and developed using Oracle Enterprise Pack for Eclipse 12.1.2.1.1. The application server used is Glassfish 4.

The list of online resources I referenced while creating this tutorial:
https://blogs.oracle.com/shay/entry/deploying_oracle_adf_applications_to
http://oracle-adf.org/how_to_install_Oracle_ADF_Essentials_on_GlassFish_Server.php
http://docs.oracle.com/cd/E47843_02/12121/OEPUG/oracle_adf_tools.htm

You need to follow below steps to create an ADF essentials application that can run on Glassfish server:

Download

1. Download Oracle Enterprise Pack for Eclipse 12.1.2.1.1 from OTN
2. Download ADF essentials libraries (both Core and Client) from  OTN
3. Download Glassfish 4 if you do not have it installed already.

Configure  

In order to run ADF application on Glassfish, ADF Runtime needs to be installed on the server. This requires ADF Essential core libraries to be copied into lib folder of your Glassfish domain. You will also need to deploy ADF Essentials Client libraries along with your code to Glassfish server by including them in your application EAR.
There are ways of doing this but I prefer using Ant script provided in OEPE for configuring Glassfish as described in Oracle docs

1. Create a Java project in OEPE.
2. In your OEPE install, go to $install_dir/plugins/oracle.eclipse.tools.adf_6.2.0.$buildrelease/adf-essentials-glassfish-config
3. Copy the files called build.xml and build.properties into the root of your Java Project .
4. Open the build properties file and update the properties to reflect your specific environment properties.
5. Save the build properties file with your changes.
6. In OEPE, right click on build.xml in the Project Explorer and select Run As > Ant Build... , which opens the Edit Configuration and Launch dialog.
7. Choose the JRE tab and select Run in same JRE as workspace.
8. Choose the Targets tab and select create-domain/recreate-domain. Make sure all of the other options under Name are unselected.
9. Click Apply.
10. Click Run.


By following above steps you create/recreate a domain that you want to use for your ADFE application. By default Glassfish server provides domain1 that can be configured and used as the domain for deploying ADFE applications. You can create a fresh new domain or change the configuration of domain1. One of the settings you may need to change is HTTP listen port of your Glassfish server. By default the server uses 8080, which in many cases has already been used by other apps on your machine e.g. on my machine Oracle XE database listens to 8080.

Secondly you need to set up your domain for ADF Essentials applications. For that you can run build.xml again by selecting install-adfe-full.
If this command does not execute properly or you want to perform steps involved in this process individually (my preferred way) then you need to do as follows:
1. Unzip the core library files into lib folder of your Glassfish domain by running install-adfe-core in build.xml or using unzip -j command
2. Unzip the client libraries into any folder of your choice by running install-adfe-client in build.xml or by using unzip -j command
3. Start Glassfish server by running start-dev-domain in build.xml. Open admin console of Glassfish server using http://<your-host-name>:<glassfish_admin_port>.  Go to Configurations->Server-config->JVM Settings and choose the JVM Options tab and add the following:
 -XX:MaxPermSize=512m (this entry should already be there so just modify it)
 -Doracle.mds.cache=simple


Your Glassfish server is configured for running ADFE applications on it. Now you will need to create a Glassfish server connection in Eclipse using the domain you just configured before starting to create an ADFE application.

Create

Create an ADF application. Go to File > New > ADF Application.


In next window, specify the Application name and Target runtime. You will see the runtime for your Glassfish server if you have already created a server connection in eclipse, otherwise you can create one here. Now select New JPA Project as we need t o create a new JPAproject for our application.


In Create JPA Project wizard, keep default settings and press Next > , keep Java settings as they are and proceed to Java Facet window. Here select EclipseLink 2.5x  as the platform, Glassfish System Library as JPA implementation. Create a new connection by clicking on Add connection and select the type of connection you want to use. In this example we are going to use Oracle XE database. So select Oracle Database Connection and in next window specify the database details. For this tutorial I have created a connection to  HR schema of XE database. Keep rest of the settings as default and press Finish.


The JPA project will now appear in your new application window


Proceeding to next window we need to create a user library which will consist of ADFE client libraries we unzipped in a folder during the configuration process. Click on Manage Libraries, and specify the library name in User Libraries window.




Now Click on Add External JARs.. and naviagte to the folder where ADFE client libs have been extracted. Select and Open all the libraries


After verifying that  all the libraries have been included , Click Ok.
In next window, select the user library created in previous steps. Also select Include libraries with this application . This will make sure the client libraries are deployed as part of your your application EAR


Click Finish and you will see three new projects created in your workspace 
SampleADFEApp : Root project containing EAR contents for the Application
SampleADFEAppModel: JPA project
SampleADFEAppWeb: Web project


To test whether the application has been created properly and it can run on Glassfish  server,  right click on index.jspx in the web project and select Run As > Run on Server. In subsequent windows select the Glassfish server instance that is configured for ADFE and the application to be deployed on it


Monitor server console for any errors in server startup or during application deployment. If everything goes well then index.jspx should come up in your browser.
You should see welcome message on the index page in your browser. If you do not see anything in your browser then open web.xml, which is located at WebContent/WEB-INF and add the following in it:

  <filter>
    <filter-name>trinidad</filter-name>

    <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>

  </filter>

  <filter-mapping>

    <filter-name>trinidad</filter-name>

    <servlet-name>Faces Servlet</servlet-name>

    <dispatcher>FORWARD</dispatcher>

    <dispatcher>REQUEST</dispatcher>

    <dispatcher>ERROR</dispatcher>

  </filter-mapping>

  <servlet>

    <servlet-name>resources</servlet-name>

    <servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>

  </servlet>

  <servlet-mapping>

    <servlet-name>resources</servlet-name>

    <url-pattern>/adf/*</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>resources</servlet-name>

    <url-pattern>/afr/*</url-pattern>

  </servlet-mapping>

Now  Clean all the projects and run index.jspx again. You will see the welcome message in your browser.

We will see how to use ADF model layer in an ADFE application to display data coming from database tables in part 2 of this series.