Configuring and Using ADF with GlassFish Server

How to Download ADF Essentials

In order for a GlassFish Server to run Oracle ADF applications, you must download the Oracle ADF Essentials files from the Oracle Technology Network at http://www.oracle.com/technetwork/developer-tools/adf/downloads/adf-download-1649592.html, as shown in Figure: Oracle ADF Essentials Download Page.

Oracle ADF Essentials Download Page

Download the Oracle ADF Essentials file adf-essentials.zip to a temporary location. You will install the ADF Runtime library files into the GlassFish installation directory, as described in How to Configure GlassFish for OEPE.

Download the Oracle ADF Essentials Client files adf-essentials-client-ear.zip and adf-essentials-client-war.zip to a temporary location and then extract the files to flat-structured temporary directories, a separate directory for each download.

For instance, if you are using unzip, you can add the -j option to create a flat directory structure that has no hierarchical folders.

unzip -j <file> -d <destination>

From adf-essentials-client-war.zip, you will create a user library which you will use when you create an ADF Application, described in How to Create an ADF Application that Uses GlassFish Runtime..

Once you have created the ADF Application, you will import the files from adf-essentials-client-ear.zip to the EarContent/lib folder of your application, described in How to Create an ADF Application that Uses GlassFish Runtime.

How to Download and Install GlassFish Server

For instructions on obtaining and installing GlassFish, see http://glassfish.java.net/downloads/3.1.2-final.html.

If you install from Zip, after you have unzipped the files you can start the server using <glassfish_install>/bin/asadmin start-domain. Alternatively, you can start and stop the server from the Servers pane in OEPE once the server has been defined in OEPE.

If you use the native installer, you can choose from Typical Installation or Custom Installation. Custom Installation allows you to specify a domain name other than domain1, and to choose to use different port numbers for the administration and HTTP listener ports. At the end of installation, the server is started.

You can create a GlassFish domain by using the GlassFish Administration utility asadmin. For more information see the following OTN websites,

http://docs.oracle.com/cd/E26576_01/doc.312/e24928/general-administration.htm#giobi

http://docs.oracle.com/cd/E26576_01/doc.312/e24938/create-domain.htm#GSRFM00023

How to Configure GlassFish for OEPE

You need to create a server configuration for GlassFish Server. It will be the link to the GlassFish Server that you use to run your project.

To configure GlassFish:

1. From the main menu, select Window > Show View > Servers to open the Servers pane.

2. In the Servers pane, right-click and select New > Server.

   Alternatively if there are no servers defined, click the No servers are available. Click this link to create new server. link.

3. On the Define a New Server page of the New Server wizard, expand GlassFish and select the type of GlassFish server you are running, for example, GlassFish 3.1.2. Enter the server's hostname, for example localhost and click Next.

4. On the server details page of the Define a New Server wizard the default domain directory is displayed.

   If necessary, click Browse next to Domain Directory to open the Browse for Folder dialog. Navigate to the domain location which is typically at <glassfish_install>/glassfish/domains and choose the domain. Click OK.

   If necessary, enter the GlassFish Server Administrator Password, and click Finish.

5. The new server connection appears in the Servers pane. You can start and stop the server from the right-mouse menu of the server node.

How to Configure GlassFish for ADF Essentials

Once you have create a server configuration for GlassFish server you can configure the GlassFish domain for ADF Essentials. See:

• Installing ADF Essentials on a Domain

• Installing ADF Essentials on a Domain With a Password

How to Register the ADF Essentials Client WAR Library in Your Workspace

In this procedure, you will add the ADF Essentials Client WAR files to a user library in OEPE so that when you create an ADF Application you can add the user library.

To register your ADF essentials client libraries

1. In OEPE, go to Windows > Preferences. Search for "User", and select Java > Build Path > User Libraries to display the User Libraries page of the Preferences dialog, as shown in Figure: User Libraries - Java.

   User Libraries - Java

   
   

2. Click New to open the New User Library dialog. Enter a name for the new ADF Essentials Client WAR library and click OK.

3. In the User Libraries page of the Preferences dialog, select the new library and click Add External JARS.

   Navigate to the location where you flat unzipped the adf-essentials-client-war.zip. Select all the files and click Open.

   The User Libraries page now shows the as shown in Figure: User Libraries - Java - Add External JARS.

   User Libraries - Java - Add External JARS

   
   

4. Click OK.

How to Create an ADF Application that Uses GlassFish Runtime

Now that you have installed GlassFish Server, configured a domain for ADF Essentials, and added the ADF Essentials Client WAR library to your workspace, you can create an ADF application.

To create a new ADF Application that uses GlassFish

1. In OEPE, go to File > New > ADF Application. The New Oracle ADF Application wizard appears.

2. If you performed the previous procedures correctly, you will see that your GlassFish server is listed in Target runtime with ADF extension. If your GlassFish server is not listed, cancel the wizard, and go back and perform the procedures in How to Configure GlassFish for OEPE and How to Configure GlassFish for ADF Essentials..

   Enter a name for your application.

3. Click New JPA Project to open the New JPA Project dialog. You use the JPA project for access to the data for your application.

4. Click Next twice to display the JPA Facet page of the New JPA Project dialog, as shown in Figure: Defining the JPA Facet.

   Defining the JPA Facet

   
   

   If necessary, change the Platform. EclipseLink is the reference implementation of JPA, and if you choose it you can take advantage of the EclipseLink shared libraries. For more information, see the "EclipseLink User's Guide - Developing JPA Projects" which is available on the Eclipse site at http://wiki.eclipse.org/EclipseLink/UserGuide/Developing_JPA_Projects_%28ELUG%29.

5. Choose from the list to use an existing database connection, or click Add connection to create a new database connection.

   Click Finish to return to the New Oracle ADF Application wizard.

6. In the New Oracle ADF Application dialog, click Next to open the ADF Library page. You should be able to see the library that you defined in How to Register the ADF Essentials Client WAR Library in Your Workspace.

   If you have not yet downloaded the ADF Essentials Client files from OTN, you can download them by clicking Download from OTN. Flat unzip the client Zip files to a local location.

   If you have downloaded the ADF Essentials Client files from OTN, but not already created the user library for the War client files, click (Manage libraries) to open the User Libraries dialog, where you can create a user library (under Java > Build Path > User Libraries), to contain the flat unzipped content of adf-essentials-client-war.zip.

   If the library is not already selected, select it as shown in Figure: ADF Library Page, and click Finish.

   ADF Library Page

   
   

7. In the New Oracle ADF Application, click Finish. The application is created, and the generated projects are displayed in the Project Explorer.

8. The final step is to add the files contained in adf-essentials-client-ear.zip to your new project.

   In the Project Explorer, expand the <project_name> and EarContent nodes, as shown in Figure: ADF Project EAR Library Directory.

   ADF Project EAR Library Directory

   
   

   Right-click lib and choose Import.

9. In the Import wizard, choose General > File System and click Next.

   In the File System page of the Import wizard, browse to the location where you flat unzipped adf-essentials-client-ear.zip.

   Select all files and click Finish. If you see a dialog asking whether to overwrite a file, select Yes to All.

How to Create a Global JDBC Data Source

To run an ADF application that uses JPA entities you first need to create a global JDBC data source. You can do this in by running the GlassFish admin console in the Eclipse browser.

Once you have created the JDBC connection pool, you can define a JDBC resource that uses your new connection pool.

To create a Global JDBC Data Source

1. In OEPE from the Server view select GlassFish and right-click and choose GlassFish > View > Admin Console.

   The GlassFish admin server opens in the Eclipse browser.

2. Expand the Resources node and choose JDBC > JDBC Connection Pools. Click New to open the new JDBC Connection Pool page.

3. Name your connection, choose Resource Type of javax.sql.XADataSource, and choose the Database Driver Vendor Oracle. Make sure that Introspect is unselected (introspection not enabled). Click Next.

4. In New JDBC Connection Pool (step 2 of 2), scroll to Additional Properties and add your database information, as shown in Figure: GlassFIsh Server Console - Additional Properties.

   GlassFIsh Server Console - Additional Properties

   
   

   For example, the values for Oracle XE running on the local machine are:

   • user = hr

   • Password = hr

   • databaseName = XE

   • ServerName = localhost

   • DriverType = thin

   • PortNumber =1521

5. Click Finish. Check your connection by selecting the new JDBC connection pool you have just created in the Tree, and clicking Ping on the General tab. If your ping is successful, you next need to define a JDBC resource that uses your new JDBC connection pool.

To define a JDBC resource that uses your new connection pool

1. In the admin console, go to Resources > JDBC > JDBC Resources>. Click New to display the New JDBC Resource page, as show in Figure: GlassFIsh Server Console - New JDBC Resource.

   GlassFIsh Server Console - New JDBC Resource

   
   

2. Enter the JNDI name, for example jdbc/hr.

3. Select your new connection pool.

4. Click OK.

Known Problems and Solutions

The following are issues that you might encounter with your GlassFish installation and runtime, and some solutions to address these issues.

1. ADF DVT components are not rendered.

   If your ADF DVT components such as Graph are not rendered at runtime, the issue is that the application is missing the dvt-as.jar and dvt-shared-js.jar. Do the following steps to correct this issue:

   1. Download the latest distribution of ADF Essentials and extract the JARs as detailed in How to Download ADF Essentials.

   2. Update the libraries in the Workspace User Library, as detailed in How to Register the ADF Essentials Client WAR Library in Your Workspace.

   3. Remove the deployed application from the server and re-deploy the application.

2. Content on a page failing to load.

   If you get the error message "The content of this page failed to load as expected because data transmission was interrupted. Please try again or contact your system admin", follow the steps above for ADF DVT components are not rendered.

3. Running the application gives the HTTP Status 500 -ADF_Faces-30200 error:

   If you get the error message "HTTP Status 500 - ADF_FACES-30200:For more information, see the server's error log for an entry beginning with: The UIViewRoot is null. Fatal exception during PhaseId: RESTORE_VIEW 1."

   Do the following steps:

   1. Un-deploy the application.

   2. Clean the server instance. With the server stopped, right-click and choose Clean.

   3. Re-deploy the application.

4. Unable to deploy an application that includes JPA Entities.

   If you have trouble deploying your application that includes JPA entities, do the following steps:

   1. Define a JDBC DataSource in GlassFish, as described in How to Create a Global JDBC Data Source.

   2. Add the data source you just defined to your JPA persistence.xml.