This lesson should take about an hour to complete.
Viewing Screenshots
Move your mouse over this icon to show all screenshots.
You can also move your mouse over each individual icon to see only the screenshot
associated with it.
Overview
After completing this lesson, you will be able to store
data from a Java class into a relational database and access existing database
information from Java classes. The figure below illustrates the object model
for this system.
Before starting this lesson, you should have completed the
following:
1.
Install Oracle JDeveloper 10g.
2.
Install the sample tables and classes for this lesson.
Copy introductory.zip
to your hard drive and extract the files.
3.
Using SQLPlus, connect to an Oracle8i or higher database and run the
introductory.sql script.
The script creates a user named tltutorial
and populates tables in the tltutorial
schema.
4.
Create a database connection in JDeveloper for the tltutorial
user. Instructions for creating a database connection in JDeveloper
can be found in the lesson: Installing
the Sample Schemas and Establishing a Database Connection. However,
instead of creating a connection named jdbc_tutorial_connection, create
a connection using the tltutorial
connection name, specifying tltutorial
as both the username and password.
TopLink mappings are stored in a JDeveloper workspace
and project. Each project may have a single TopLink Mapping deployment descriptor.
1.
In JDeveloper, create a new workspace and project.
From the File menu, select New.
The New Gallery appears.
2.
In the Categories pane, select General. In the Items pane, select
Workspace and click OK.
The Create Workspace dialog appears.
3.
In the Create Workspace dialog, enter TopLinkTutorials as the
workspace name and click OK.
The Create Project dialog appears.
4.
In the Create Project dialog, enter Employee as the project name
and click OK.
The workspace and project are added to the Navigator.
5.
In the Application Navigator, right-click Employee and select
New.
The New Gallery appears.
6.
In the Filter By drop-down list, select All Technologies.
In the Categories pane, select General > Deployment Descriptors.
In the Items pane, select TopLink Mapping Descriptor and click
OK.
The TopLink Mappings element appears in the Navigator.
7.
Right-click TopLink Mappings and select Mapping Defaults.
The TopLink Mappings page appears in the Mapping editor and the Structure
window.
8.
From the File menu, choose Save All.
Adding Java Classes
and Creating TopLink Descriptors
You must add the Employee,
PhoneNumber, and Address
classes (provided in the examples.session.threetier.model
package) to your JDeveloper project for this lesson. The following table shows
how the classes relate to the database tables.
To add these files to the project, follow these steps:
1.
In the Navigator, right click the Employee node,
and choose Add to Project...
The Add Files or Directories dialog box appears
2.
Navigate to the examples directory in the location
where you extracted the files for this lesson and click Open. If
you have not extracted the supporting files, see the prerequisites section
above.
3.
In the Refine File Selection window, select the following
classes:
When you create a new TopLink descriptor in a project and
add Java classes, the descriptors are initially "unmapped." They do
not contain any information about how the classes are associated with the tables.
Follow these steps to associate classes with database tables:
Right-click Employee in the Navigator and select New.
The New Gallery appears.
2.
In the Categories pane, select Database Tier > Offline Database
Objects.
In the Items pane, select Offline Database Objects Imported from a
Database.
Click OK. The Offline Database Import Wizard appears.
3.
Review the information in the first page and click Next.
Select tltutorial as the connection name. If you have not created
this connection, see the prerequisites section above. Click Next.
4.
In the Available section, select ADDRESS, EMPLOYEE, and
PHONE. Move them to the Selected section using the shuttle buttons
and click Next.
5.
Accept the default schema name TLTUTORIAL. Click Finish.
JDeveloper adds the offline database tables to the project.
Use these steps to associate the Address TopLink
descriptor with the ADDRESS database table.
1.
In the Navigator, select TopLink Mappings.
Double-click the Address descriptor in the TopLink Mappings Structure
pane.
The TopLink Mapping Editor appears in the Editor pane.
2.
Click the Descriptor Info tab in the Mapping Editor. In the Associated
Table field, choose the TLTUTORIAL.ADDRESS table. TopLink automatically
identifies the primary key(s) for each descriptor.
3.
Repeat steps 1 and 2 to associate:
Employee with the TLTUTORIAL.EMPLOYEE table PhoneNumber with the TLTUTORIAL.PHONE table
Although you have associated the descriptors with specific database tables,
the class attributes have not yet been mapped to the tables' columns.
You will map the attributes later in this lesson.
The Address
class does not reference any other classes. Instead, its attributes map directly
to database fields as a direct-to-field mapping. To map the Address
class attributes directly to the ADDRESS table's fields, follow these steps:
1.
In the TopLink Mappings Structure window, expand the
Address descriptor.
The Structure window displays the attributes for the
descriptor.
2.
Click the city attribute.
TopLink displays the valid mappings for this attribute in the Editor
pane.
3.
Choose Direct-to-Field and click Map As.
The Direct-to-Field mapping General tab appears in the Editor pane.
You can also map the attribute by right-clicking the city attribute
in the Structure window and choosing Map As > Direct to Field
from the context menu or by clicking Map As in the TopLink Mappings
Structure toolbar.
4.
In the Database Field, choose the CITY field.
5.
Repeat steps 2 through 4 to map the remaining attributes in the ADDRESS
table:
Map the country attribute to the COUNTRY field.
Map the id attribute to the ADDRESS_ID field.
Map the postalCode attribute to the P_CODE field.
Map the province attribute to the PROVINCE field.
Map the street attribute to the STREET field.
6.
Repeat steps 1 through 4 to map the following attributes in the EMPLOYEE
table:
Map the firstName
attribute to the F_NAME field.
Map the id
attribute to the EMP_ID field.
Map the lastName
attribute to the L_NAME field.
Repeat steps 1 through 4 to map the following attributes in the PHONE
table:
Map the areaCode attribute to AREA_CODE field.
Map the number attribute to P_NUMBER field.
Map the type attribute to TYPE field.
Because only one home address is associated with each employee,
the address attribute requires a one-to-one mapping with the Address class,
as shown below:
To create a one-to-one mapping:
1.
Expand the Employee descriptor in the Structure window.
2.
In the structure pane, click the address attribute. TopLink displays
the valid mappings for this attribute in the Editor pane.
3.
Choose One-to-One and click Map As. The
One-to-One General mapping tab appears in the Editor pane.
You can also map the attribute by right-clicking on the address attribute
in the Structure window and choosing Map As > One-to-One from
the context menu or by clicking Map As in the TopLink Mappings
Structure toolbar.
4.
In the Reference Descriptor field, choose the Address class. Ensure
the UseValueHolder Indirection and Private Owned
options are checked. This allows the Address object to be created, updated,
or deleted automatically when the Employee owning it changes.
5.
One-to-one mappings use the relational database concept of foreign keys
to access other classes stored in the database. You must specify the foreign
key information in the descriptor so that TopLink knows how to search
for a referenced object.
Click the Table Reference tab.
From the table reference dropdown list, choose EMPLOYEE_ADDRESS.
In this table reference, the foreign key is the ADDRESS_ID from the EMPLOYEE
table; the primary key is the ADDRESS_ID from the ADDRESS table.
6.
Follow steps 1 through 6 above to map the owner
attribute of the PhoneNumber
descriptor as a one-to-one mapping to the Employee
class.
Select EMPLOYEE as the Reference Descriptor.
On the Table Reference tab, select the PHONE_EMPLOYEE table.
To map an attribute to a Java collection (javautil.Collection)
such as a Vector, the application must make a one-to-many (1:M) mapping for
the class owning the collection, and a one-to-one mapping back from the class
being referenced. The one-to-one mapping in the referenced class is implemented
as a foreign key to the source class. This lesson requires a one-to-many mapping
from the phoneNumbers attribute
of the Employee class to the
PhoneNumber class and a one-to-one
mapping from the owner attribute of the PhoneNumber
class back to the Employee class.
To map the phoneNumbers attribute:
1.
Expand the Employee descriptor in the Structure
window.
2.
Click the phoneNumbers attribute. TopLink displays the valid mappings
for this attribute in the Editor pane.
3.
Choose One-to-Many and click Map As. The
One-to-Many General mapping tab appears in the Editor pane.
You can also map the attribute by right-clicking on
the phoneNumbers attribute in the Structure window and choosing
Map As > One-to-Many from the context menu or by clicking Map
As in the TopLink Mappings Structure toolbar.
4.
Use the Reference Descriptor drop-down list to choose PhoneNumber.
5.
Click the Table Reference tab, and select the PHONE_EMPLOYEE table.
In these steps, you create a TopLink deployment descriptor,
session descriptor, sample client, and data control layer for the Employee project.
Finally, you create a JSP page, then display the employee data in a web browser.
1.
Create a deployment connection for the TopLink Mappings. Select Toplink
Mappings from the Structure Pane and select the Database Info
tab. Select tltutorial in the Deployment Connection dropdown list.
2.
In the Navigator, right click TopLink Mappings (under the TopLink
package) and select New sessions.xml
Double click sessions.xml to open it in the code editor.
3.
Click Add to create a new session.
4.
Change the session name to IntroToplinkSession.
Click OK to create the session.
5.
Create a TopLink deployment descriptor. Right-click TopLink Mappings
in the Navigator and choose Generate toplink-deployment-descriptor.xml
from the context menu.
JDeveloper compiles the Java source, checks the TopLink mappings, and
generates the toplink-deployment-descriptor.xml
file. Click OK to exit the deployment descriptor window.
6.
Create a data control layer for the Employee.java object.
Right-click Employee.java in the Navigator and choose Create
Data Control from the context menu.
In the Select Deployment Resource dialog, select Sessions Configuration
and specify Location as sessions.xml and Sessions as IntroToplinkSession.
7.
Create a JSP page to render the data from the Java object.
Right-click the Employee project in the Navigator and choose New
from the context menu.
The New gallery appears.
8.
In the Categories pane, select Web Tier and JavaServer Pages
(JSP). In the Items pane, select JSP Page.
Click OK.
9.
Rename the JSP to Toplink.jsp.
Click OK. The JSP will open in the visual editor.
10.
In the Data Control Palette, expand the EmployeeDataControl and
readAllEmployee nodes, and select the return node. Ensure
that Read-Only Table is selected in the Drop As dropdown list.
11.
Drag the return node onto the visual editor.
12.
Right click and select Run to run the JSP page.
Summary
This introductory lesson explained the basic steps required
to create a Java project that accesses a relational database through TopLink.
To create a TopLink application utilizing EJB mappings, continue with the Advanced
TopLink Lesson.
Bookmark
