# Configuring and Using ADF with GlassFish Server

You can configure GlassFish Server to run your Oracle ADF applications, and configure an ADF-enabled GlassFish Server run-time in your Java applications.

For a list of the supported Oracle ADF features for GlassFish, go to the OTN site at `http://www.oracle.com/technetwork/developer-tools/adf/overview/adfessentials-1719844.html`.

The following sections describe how to configure GlassFish Server for use with Oracle ADF:

- How to Download ADF Essentials.

- How to Download and Install GlassFish Server.

- How to Configure GlassFish for OEPE

- How to Configure GlassFish for ADF Essentials

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

- How to Create an ADF Application that Uses GlassFish Runtime

- How to Create a Global JDBC Data Source

- Known Problems and Solutions

For more information, see "Configuring GlassFish Server" in Administering Oracle ADF Applications.

## 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:

- "Using the asadmin Utility" in Oracle GlassFish Server Reference Manual.
- create-domain in Oracle GlassFish Server Reference Manual.

## 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

### Installing ADF Essentials on a Domain

If you are configuring a domain that does not use a password, you can use the server adapter from within OEPE.

To configure a domain that does not use a password:

1. In OEPE, in the Servers pane, right-click the GlassFish server node and choose GlassFish > Install ADF Essentials, as shown in Figure: GlassFish Menu in Servers Pane.

   GlassFish Menu in Servers Pane

2. Navigate to the `adf-essentials.zip` file that you downloaded from OTN and click Open.

   You can follow the installation in the console, Window > Show View > Console, as shown in Figure: Importing ADF Essentials Console.

   Importing ADF Essentials Console

   Check that the GlassFish server is not stopped in the server pane. This confirms that ADF Essentials is configured correctly and running in the server instance. You now have a connection to a GlassFish Server, which is configured for ADF Essentials.

### Installing ADF Essentials on a Domain With a Password

If you are installing ADF Essentials on a domain that has been configured to require a password, you must manually configure the domain from the GlassFish console.

To configure a domain that does use a password:

1. Login to the GlassFish admin console, which is at `http://<machine_name>:4848/`. For example, `http://localhost:4848/` when the server runs on the local machine.

2. Navigate to Configurations > server-config > JVM Settings.

3. Select JVM Options and add the following JVM options:

   - -`Doracle.mds.cache=simple`

   - `XX:MaxPermSize=512m`

4. Once you have set the JVM parameters, restart the server.

Alternatively, you can set these as `<jvm-options>` entries in the `domain.xml` file for the domain, `<glassfish_install>\glassfish\domains\<domain>\config\domain.xml`.

## 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`.