Developing Web Applications with Oracle ADF Essentials: Quickly build attractive, user-friendly web applications using Oracle's free ADF Essentials toolkit

This section will walk you through the installation of the MySQL database on Windows – if you are running another operating system, the process is similar.

Start the installer, click on OK to any warnings about installing software and changing your machine, and choose Install MySQL Products. Read and accept the license agreement and allow it to check for later versions of the software.

For the purposes of this book, you can simply choose a Developer Default setup type when prompted. If you already know MySQL and have specific ideas about your installation, feel free to change the options.

Change the installation path to C:\adfessentials\MySQL\product and the data path to C:\adfessentials\MySQL\data.

In the Check Requirements step, you may be prompted to install various additional packages—simply accept this. If you are told that you are missing various versions of the Python programming language, you can just click on Execute a few times to acknowledge the warnings.

Once you are done with this step, the installer starts installing the actual MySQL software as shown as follows:

When the software is installed, you can click on Next a few times to start the configuration. The first screen looks like this:

On this screen, you can leave the defaults:

In step 2 shown in the following screenshot, you are asked to provide a root password for the database. You can always create separate users later.

/usr/local/mysql/bin/mysqladmin –u root –p password

In step 3, you are prompted for a Windows service name as shown in the following screenshot:

You can leave the defaults on this screen.

When you click on Next, the configuration of MySQL runs. When this is complete, click on Next to install the samples and examples and then finish the installation.

JDeveloper generates code with two vertical bars (|| or pipes) for string concatenation, and while this is valid SQL92, it is not supported in a default MySQL configuration. To enable this in MySQL, find the MySQL configuration file my.ini in the database directory (for example, C:\adfessentials\MySQL\data).

Search for a line starting with sql_mode=. If such a line exists, add a comma after the existing value and then the keyword PIPES_AS_CONCAT. If there is no sql_mode line, add the following:

sql_mode=PIPES_AS_CONCAT

If you come from an Oracle background, you might want to set sql_mode=ORACLE instead—this sets PIPES_AS_CONCAT and a couple of other settings to make MySQL behave more Oracle-like.

You will need to restart the MySQL database in order for this change to take effect. On Windows, you can open the Control Panel, choose Administrative Tools, and then Services. Find the MySQL56 service and choose Action | Restart. You can also restart the database from the MySQL Workbench by double-clicking on your database in the Server Administration column to the right.

Once you have your Sakila database installed, you can start the MySQL Workbench from the Start menu. You should see Local instance MySQL56 or similar to the left under the SQL Development heading, as shown in the following screenshot:

You can double-click on this and provide your root password to connect to the database. If an SQL Editor window opens with various schemas to the left (including your Sakila database) as shown in the following screenshot, your installation was successful:

If you prefer to use a command line, you can start the MySQL 5.6 Command Line Client from the Start menu, provide your root password, and type the following command:

show databases;

If you see a couple of databases as in the following screenshot, your MySQL server is running correctly:

The MySQL command line can also be started from a command prompt by running the following command:

C:\adfessentials\MySQL\product\bin\mysql –u root -p

This attempts to log in as user root and prompts you for the password.

/usr/local/mysql/bin/mysql –u root –p

As installed, the Sakila database does not contain any DVDs not returned—every rental record has a return_date.

Because we will be building a screen to return DVDs, we want some unreturned rentals in the database. From either MySQL Workbench or the command line, execute the following command:

update rental set return_date = null where staff_id = 2;

This clears the return date for about half the rentals, making them unreturned.

You can download Java Development Kit 7 from http://www.oracle.com/technetwork/java/javase/downloads. You need the JDK download as shown in the following screenshot:

Accept the license agreement and choose the right bundle for your operating system and architecture, for example, Windows x64 for 64-bit Windows or Windows x86 for 32-bit Windows.

When the installation is complete, double-click on the downloaded file to install the JDK. In the second step of the install wizard, change the directory to one placed under your adfessentials folder, for example, C:\adfessentials\jdk1.7.0_25 as shown in the following screenshot:

When asked where to install the JRE, change the destination folder to C:\adfessentials\jre7 as shown in the following screenshot:

When the installation is complete, you need to set your JAVA_HOME environment variable to point to the JDK directory (for example, C:\adfessentials\jdk1.7.0_25).

GlassFish Server Open Source Edition 3.1.2.2 can be downloaded from http://glassfish.java.net/download-archive.html. Like MySQL, GlassFish exists in both an open source version and a commerical version—if you want the commercial version, it can be found on the Oracle Technology Network under Middleware, GlassFish Server.

As the following screenshot shows, there are install sets available for Windows, Linux, Unix, Mac, and so on. Just click on the link for the file that matches your environment:

To install GlassFish, change to the directory where you downloaded the file and execute the following command:

glassfish-3.1.2.2-windows.exe –j c:\adfessentials\jdk1.7.0_25

In the GlassFish installer, choose the following options:

When the software is installed, the installer will prompt you to create a domain like this:

You can leave the default domain name and ports. You should set a password for the admin user—again, if this is a non-critical development workstation and you want to be sure that you have the password written down, feel free to use this example password: ADFsecret/13.

After the domain has been created and started, click on Next to see the installation summary as shown in the following screenshot:

When you click on Exit, you will be prompted to register your GlassFish server, but this is not mandatory.

In order to check if your GlassFish server is indeed running, you can enter the URL http://localhost:<port> (for example, http://localhost:8080) in your browser to see the Your server is now running confirmation message like this:

In order to be able to connect from GlassFish to a database, you need a connector. GlassFish does not have a MySQL connector built-in, so you need to go to http://www.mysql.com/products/connector and download the JDBC Connector for MySQL (Connector/J). You may be prompted to log on to your Oracle Web account.

Unpack the file and copy the mysql-connector-java-5.1.25-bin.jar file (or whatever the version number is by the time you read this) into the lib directory of your GlassFish domain (C:\adfessentials\glassfish3\ glassfish\domains\domain1\lib or similar). Then, stop GlassFish and start it again (on Windows, the start and stop commands are found on the Start menu under GlassFish Server Open Source Edition).

In order for your applications to be able to connect to your MySQL database, you need to define a DataSource. Your applications will refer to the DataSource by name, and the configuration on the GlassFish server defines which database the DataSource will connect to. This gives the application server administrator the necessary freedom to move the application between environments, move databases to other servers, and so on.

You can set up a DataSource though the GlassFish Server Administration Console. You specified the port for this service as the Admin port when you installed GlassFish. The default port is 4848, so you can point your browser to http://localhost:4848 to start the admin console.

Open the Resources node on the left and then JDBC. Click on JDBC Connection Pools and then click on New in order to create a new connection pool. Give it the name SakilaPool, choose javax.sql.DataSource as Resource Type, and choose MySql as Database Driver Vendor. Your screen should look like this:

On the next screen, scroll down to the Additional Properties section and sort the properties by name (by clicking in the Name header). Find the following settings and set their value as follows:

When you have clicked on Finish to create the pool, click on the SakilaPool name and then click on the Ping button to test that GlassFish can connect to MySQL. You should see a Ping Succeded message as shown in the following screenshot:

Then, click on JDBC Resources and then click on New in order to create a new JDBC resource. Give it the JNDI name jdbc/SakilaDS and select the SakilaPool connection pool for this JDBC resource as shown in the following screenshot:

You can get the ADF Essentials package from the Oracle Technology Network—at the time of writing, the download URL is http://www.oracle.com/technetwork/developer-tools/adf/downloads. If this does not work, you can get to the Downloads for Oracle ADF 11g page by starting at the OTN homepage (http://otn.oracle.com), clicking Software downloads to the left, then scrolling down and clicking on JDeveloper and ADF, then selecting Application Development Framework to the left, and finally clicking on the Downloads tab.

The download page will look something like this:

Accept the license agreement (read it first!) and then scroll down to the Oracle ADF Essentials section shown in the following screenshot and download:

You may be asked to fill in a short survey before Oracle lets you have the software, and you'll probably be asked to accept the license agreement once more—just to be on the safe side.

The download you get is the adf-essentials.zip file.

To install the ADF Share libraries in GlassFish, first unpack your adf-essentials.zip file in a temporary directory to a flat structure without the directories. You can use a command like unzip -j adf_essentials.zip to achieve this.

Copy all the files to the lib directory of the GlassFish domain where you want to run ADF Essentials applications. If you performed the installation as described earlier in the chapter, the lib directory will be c:\adfessentials\glassfish3\glassfish\domains\domain1\lib.

Because ADF applications are a bit more memory-hungry than the average JEE application, you will need to change the GlassFish JVM settings.

In a web browser, go to the GlassFish Administration page (by default on port 4848 of the server where you installed GlassFish, for example, http://localhost:4848). Log in with the admin user you created during installation and go to Configurations | server-config | JVM Settings. Open the JVM Options tab. Find the option -XX:MaxPermSize= and set it to -XX:MaxPermSize=512m in order to allow GlassFish to allocate more memory than default. Your screen should look like this:

Also, add the new value -Doracle.mds.cache=simple.

Then, click on Save and restart your GlassFish server. You might notice a Restart Required message in the top-left of your server administration window, like this:

You can click on the message to see why a restart is necessary and then click on the Restart button, or you can use the commands on the Windows Start menu.

There is no easy way to immediately determine if you installed ADF Essentials correctly into your GlassFish server, so we'll get right on to the task of building simple ADF Essentials applications to prove that your ADF Essentials libraries are indeed correctly installed.

There are two tools for building Oracle ADF applications: Oracle JDeveloper and Eclipse with Oracle Enterprise Pack for Eclipse. There are two kinds of ADF: Full ADF, which needs a WebLogic server (and a license fee), and ADF Essentials, which is free.

At the time of writing, JDeveloper was supported for developing both kinds of ADF applications, but Oracle Enterprise Pack for Eclipse is only supported for building applications for Full ADF. We can see the same in the following diagram:

There are two flavors of JDeveloper:

11.1.1.7.0 is actually the latest release, and Oracle are developing all of their big internal applications using 11gR1 versions. These are the ones that get bug fixes first and are the only ones to offer support for modern distributed version control tools like Git.

Unfortunately, only the 11gR2 branch has support for GlassFish, so this is the version we have to use for developing applications with ADF Essentials.

You can download JDeveloper from the Oracle Technology Network (OTN) website at http://otn.oracle.com. Click on the Downloads link and you will normally find a link to JDeveloper under Popular Downloads to the right. If it's not there, find it via the download index on the left.

Read and accept the OTN JDeveloper License and download the latest version for your platform. At the time of writing, this was 11.1.2.4.0. You'll want the Studio edition because this one includes Oracle ADF. Choose the install for your platform—the Windows install is an .exe file, and the Linux install is an executable (.bin). For other platforms, you will need to get the Generic installer. If you need the Generic installer, refer to the installation guide (under Prerequisites & Recommended Install Process) for detailed instructions. If you're not signed in to www.oracle.com, you'll have to do so before you can download.

The installation of JDeveloper on Windows is straightforward—just run the jdevstudio11124install.exe file. When prompted for an install directory, select C:\adfessentials\Middleware111240. Choose to perform a Typical installation.

The first time you start JDeveloper, you will be prompted to select a role. Select Studio Developer and remove the checkmark in the Always prompt for role selection on startup box.

By default, JDeveloper does not come with a connector to MySQL databases. However, you have already downloaded the JDBC Connector for MySQL (Connector/J) that you can use in JDeveloper as well.

To install it in JDeveloper, copy the mysql-connector-java-5.1.25-bin.jar file (or whatever the version number is by the time you read this) to C:\adfessentials\middleware111240\jdeveloper\jdev\lib.

Then, from within JDeveloper, choose Tools | Manage Libraries. Click on New to add a new library and call it MySQL Driver. Choose the Class Path node and click on Add Entry. Navigate to the C:\adfessentials\middleware111240\jdeveloper\jdev\lib directory, choose the JAR, file and click on Select.

The Create Library dialog should look like this:

Click on OK twice to close the dialog boxes. Now you have the MySQL driver available for your projects.

In order to make it easier to manage the GlassFish server from within JDeveloper, you should install the GlassFish Server Extension into JDeveloper.

In JDeveloper, choose Help, Check for Updates. In step 2 of the Check for Updates wizard, make sure that Open Source and Partner Extensions is checked. In step 3, find the Glassfish Server Extension and select it. Click on Next and then click on Finish, and allow JDeveloper to restart. When JDeveloper starts again, you should see some GlassFish icons on your toolbar, like this:

You also need to tell JDeveloper where you have installed GlassFish. Choose Tools | Preferences | GlassFish Preferences. If you only see a Load Extension button, click on it to load the GlassFish. Then, update all the paths to match your GlassFish installation. If you use the same directories as this book, your dialog box will look like this:

If your GlassFish server is not running, start it. On Windows, this is done via Start | GlassFish Server Open Source Edition | Start Application Server, or you can use the new GlassFish icons on the toolbar in JDeveloper.

Choose File | New | Connections | Application Server Connection. Give your connection a name and choose Glassfish 3.1 as Connection Type. In step 2, provide the admin username (admin) and leave the password field blank (the default GlassFish install doesn't set an admin password). In step 3, you can leave the default hostname and ports.

In step 4 of the wizard, test the connection. You should see all tests successful as shown in the following screenshot if your GlassFish server is running and JDeveloper can connect to it:

To create the application, click on the New Application link in the Application Navigator or choose File | New | Applications. Choose Fusion Web Application (ADF).

Give your application a name, provide a directory, and enter an application package prefix. This prefix is used in Java package naming in the application, so it should adhere to your normal Java naming standards. If your organization has the Internet domain company.com, your application package prefix will normally be something like com.company.<application>, for example, com.company.adfdemo1.

You can leave the defaults for the Model and ViewController projects in the following steps of the wizard.

When you are done, your screen will look like the following screenshot, with your application name at the top of the Application Navigator to the right, two projects under it, and a quick start checklist for the application in the middle:

You can explore the checklist to get a feel for the steps in ADF application development—it includes both detailed task lists and links to relevant places in the documentation.

We will be working on the film table in the MySQL Sakila demo database. To create a connection, choose File | New | Connections | Database Connection. Give your Connection Name, choose Connection Type as MySQL, fill in Username as root, and give the Password. Remember that the default port is 3306 and we use the default sakila database. Your screen should look like this:

In the Library field, click on Browse and select the MySQL Driver you created when you installed JDeveloper (it's under the User node in the Select Library dialog).

Click on Test Connection—if you get a Success! message, your driver is installed correctly and you have provided the right connection information.

To start building business services for your application, select the Model project in the Application Navigator and choose File | New | Business Tier | ADF Business Components | Business Components from Tables as shown in the following screenshot:

In the Initialize Business Components Project wizard, choose your Sakila connection, choose SQL92 as the SQL Platform, and choose Java as Data Type Map.

JDeveloper creates a number of objects for you—you can see them in the Application Navigator.

You can test your business components by right-clicking on the AppModule node (with the suitcase icon) and choosing Run as shown in the following screenshot:

This starts the Business Components Tester application shown in the following screenshot, which allows you to interact with your business service through a simple UI:

The model layer is automatically created for you when you create the business components. You can see the available data elements and operations in the Data Controls palette in the Application Navigator as shown in the following screenshot:

In the controller layer, we define the screens that make up the application and the possible navigation flows between them. For now, we'll just use the Unbounded Task Flow that every ADF application has.

Open the ViewController project and then Web Content | Page Flows to see the adfc-config element that represents the Unbounded Task Flow. Double-click on this element to open a visual representation of the flow. It's empty at the moment because we haven't added any pages yet.

Drag a View activity in from the Component Palette on the left as shown in the following screenshot and give it a name (for example, FilmPage):

You'll notice that the view component has a yellow exclamation mark, indicating a warning. This means that we have added a view component to the task flow, but we have not actually defined the page yet. So, let's do that.

In the View layer, we define the actual JSF pages that make up the application. Simply double-click on the page you just created in the unbounded task flow to open the Create JSF Page wizard. Set Document Type to Facelets and leave the page layout at Blank Page. We'll get back to using layouts and page templates in a later chapter.

Click on OK to actually create the page and open it in JDeveloper. You'll see an empty page in the Design view.

Find the Data Controls panel to the left and expand it. Expand the AppModuleDataControl node and drag the FilmView1 object onto the page as shown in the following screenshot:

When you release it, JDeveloper will automatically prompt you for a choice of component. Choose Table | ADF Read-Only Table. In the Edit Columns dialog, check the Enable Sorting and Enable Filtering checkboxes and click on OK.

Your page will show a representation of an ADF table full of mysterious #{…xxx} labels and fields. They represent bindings to the data control and will be replaced with actual labels and data at runtime—we'll get back to this in a later chapter.

By default, your application gets a long and complicated URL. You can change this by right-clicking on the ViewController project and choosing Project Properties. Select the Java EE Application node and set the Java EE Web Context Root to something simpler. It will typically default to something like FilmApp1-ViewController-context-root—you can change this to something like FilmApp1.

Click on Save All to save your work.

There are some settings that you need to change in order to make your application run with ADF Essentials on GlassFish.

DataSource

You just want your application to include the name of your database connection, not the actual connection details. In order to ensure this, you need to right-click on your Model project and choose Project Properties. In the properties dialog, choose Deployment and then Edit to edit the deployment profile. Choose Connections and then Connection Name Only as shown in the following screenshot:

Then, click on OK a couple of times to close the dialog box.

<Custom JDBCDataSource="jdbc/SakilaDS">

Now your first ADF Essentials application is ready to deploy and run!

Choose Application, Deploy. You should see a default deployment profile (something like FilmApp1_Project1_FilmApp1). Choose this default profile and choose Deploy to Application Server. Choose your GlassFish connection and click on Finish to deploy your application.

The log panel at the bottom of the JDeveloper window will show deployment messages on the Deployment tab.

[03:34:42 PM] ----  Deployment started.  ----
[03:34:42 PM] Target platform is  (Glassfish 3.1).
[03:34:42 PM] Retrieving existing application information
[03:34:42 PM] Running dependency analysis...
[03:34:42 PM] Building...
[03:34:49 PM] Deploying 2 profiles...
[03:34:51 PM] Wrote Web Application Module to C:\JDeveloper\mywork\FilmApp1\ViewController\deploy\FilmApp1_ViewController_webapp.war
[03:34:55 PM] Wrote Enterprise Application Module to C:\JDeveloper\mywork\FilmApp1\deploy\FilmApp1_Project1_FilmApp1.ear
[03:34:55 PM] Deploying Application...
[03:38:28 PM] Application Deployed Successfully.
[03:38:28 PM] Elapsed time for deployment:  3 minutes, 46 seconds
[03:38:28 PM] ----  Deployment finished.  ----

Have patience—it takes a while (up to several minutes) for JDeveloper to bundle up the necessary ADF Essentials libraries with your application and deploy it onto the GlassFish server.

Once the deployment is finished, you can run your application in a web browser. Your URL will be of the form http://<server>:<port>/<web context root>/faces/<page name>. Remember that you set the web context root in the properties of the ViewController project. In the preceding section on the controller layer, we set it to FilmApp1. An example of a URL would be http://localhost:8080/FilmApp1/faces/FilmPage.jspx. Your page should look like this:

Notice some of the cool features of the ADF table component we used:

If you want to run MySQL applications in the built-in WebLogic server, you first need to copy the MySQL Connector JAR (mysql-connector-java-5.1.25-bin.jar) to a directory where WebLogic can find it. A good choice is the directory for external libraries in the JRA installation: C:\adfessentials\middleware111240\jdk160_24\lib\ext.

Once you have the driver installed, you need to define a datasource with the right name like you did earlier in the chapter for GlassFish.

First, in JDeveloper, start the built-in WebLogic server with the command Run | Start Server Instance. The first time you start the server, you will be prompted for a password to the default domain. Watch the messages in the log window until you see the following command:

<Server started in RUNNING mode>

Then, open a web browser and type in the address http://localhost:7101/console. Log in with the admin user and the password you provided. After a little while, the WebLogic console window opens.

Expand the Services node under Domain Structure to the left and select the Data Sources node. Click on New | Generic Data Source. Give your datasource a Name (SakilaDS) and a JNDI Name (jdbc/SakilaDS), and choose Database Type as MySQL. In the next two steps, just leave the defaults. On the Connection Properties page, provide your connection details:

On the following screen, click on Test Configuration. You should see Connection test succeeded.

Click on Next (not Finish) and check the checkbox next to DefaultServer. Then, click on Finish.

To run your first ADF Essentials application in the built-in WebLogic, server simply right-click on FilmPage in the Application Navigator and choose Run. The application will automatically be re-built, deployed to the built-in WebLogic server, and opened in a browser.