Olaf Heimburger's Blog

Oracle TopLink

When looking around for O/R mapping frameworks, Oracle TopLink will appear as one of the most mature frameworks. Oracle TopLink builds high-performance applications that store persistent object-oriented data in a relational database. It successfully transforms object-oriented data into either relational data or Extensible Markup Language (XML) elements.

Entities

In TopLink Entities are defined as Plain Old Java Objects (POJOs) with additional files containing the mapping information. These files hold the meta data for the connection and mapping information.

Implementing the TopLink Model Layer

Similar to implementing the EJB Model Layer we're using the  existing Database Model as developed in the previous posts (see Setting up the Gear, Creating the Database, and Deploying the Database Model). Additionally you should make sure that your database is up and running and a Database Connection called survey configured. The steps in JDeveloper 10.1.3 and 11g are quite similar.

1. Create a Model Layer Project
2. Import TopLink Entities from Database Tables
3. Check the generated files
4. Create a Session Facade
5. Create a Test Client

Steps for JDeveloper 10.1.3

Step 1: Create a Model Layer Project

• To create a new Model Layer Project select OnlineSurvey in the Application Navigator, open the Context Menu and chose the New Project... menu entry.
• In the New Gallery select an Empty Project and click on OK.
• In the Create Project window set the Project Name to ModelTopLink and click on the OK button.
• Select the newly created ModelTopLink project in the Application Navigator and open the Project Properties window with a double-click.
• In the Project Properties window, check the values of Project Content and make sure that the Default Package is set to demo.survey.model.toplink. Click OK to close this window.

Step 2: Import TopLink Entities from Database Tables

Select the ModelTopLink project in the Application Navigator. Open the New Gallery from the Context Menu -> New .... In the New Gallery expand the Business Tier and select TopLink. On the right-hand side select Java Objects From Tables and click on the OK button.

• In the Create Java Objects From Tables wizard step 1, select the survey connection and Oracle 10g for the Database Platform. For the TopLink Map, click on the New ... button (note the underscore under the first point of the elipses. Hard to read.). In the Create Object-Relational Map window set the TopLink Map Name to surveyMap and click on the OK button. This will create a new TopLink map. Click on Next to go to the Select Tables step.
• In step 2 click on the Query button to get all available tables. Once the table names appear, select all of them. Move all entries from Available to Selected, by clicking on the >> button.
• Click Next to go to wizard step 3. In step 3, General Options, accept the default value, the package name, and click Next to go to wizard step 4.
• In step 4, Specify Object Details, we can change the names of the Java Classes from plural to singular. This is a bit cumbersome as we have to select the Table Name, change the Java Class name and so on. Add the end of this step we should have a singular Java Class name for every Table Name.
  
• Click Next to go to the Summary and click on Finish to close the wizard. Now all six entities will be created.

You can find them in the Application Navigator under ModelTopLink->Application Sources->demo.survey.model.toplink. Also notice some additional files like sessions.xml and surveyMap under ModelTopLink->Application Sources->TopLink.

Step 3: Check the generated files

To check the generated files open them by selecting Answer.java, hold the Shift key, select Survey.java, and drag them into the working area right to Application Navigator. Every selected file will be opened in its own Code Editor. Select the tab named Answer.java to bring it to the front. You will see the completely generated code. This class has a small flaw, it is not Serializable, ie. you can not move it between two JVMs. We have to change the code to get the lines below:

import java.io.Serializable;

import oracle.toplink.indirection.ValueHolder;
import oracle.toplink.indirection.ValueHolderInterface;

public class Answer implements Serializable {

We do this by entering the implements Serializable part and let JDeveloper ask us to add the import statement via Alt-Enter. Be sure to select Serializable (java.io). This is the right package. We have to do this for every class, but rely on JDeveloper's support for knowing which import statement is the correct one for a specific piece of code:

• Select the implements Serializable snippet (including the leading blank) and copy into the clipboard (Ctrl-C). Open Author.java. Point your text cursor right after the class name, hit Ctrl-V and you are done.
• Repeat this for Item.java, Question.java, Response.java, and Survey.java.
• Save your work.

Now is the right time to add the database sequences to the layer. This is not done automatically and must be configured in the TopLink configuration files sessions.xml and surveyMap.

• In the Application Navigator select sessions.xml. In the Structure window, double-click on default to open the Mapping Editor for the sessions.xml.
• Click on the Login tab and click on the Sequencing sub-tab. The information in the General sub-tab is good enough at the moment. In the Sequencing sub-tab we change the Use Native Sequencing to True. Also check the Preallocation Size check-box to make the number field editable. Change the value to 1 to make it work with the current database sequence increment.
• Save your work.
• Now click on the surveyMap.
• In the Structure window expand demo.survey.model.toplink to get all available Java Classes in this map.
• Double-click on the Answer mapping. This opens the Mapping Editor for the Answer class.
• In the Descriptor Info tab check the Use Sequencing check-box. This makes this block editable.
• The values for Table and Field are correct. Set the value for Name to SEQ_ANSWERS.
• Now repeat setting of the database sequence for the classes Author, Item, Question, Response, and SurveySequencing Name to SEQ_AUTHORS, SEQ_ITEMS, SEQ_QUESTIONS, SEQ_RESPONSES, and SEQ_SURVEYS, respectively.
• Save your work.

Step 4: Create a Session Facade

Click on ModelTopLink in the Application Navigator. Any other entry of the ModelTopLink project will do, also. Select New... from the Context Menu and navigate to Business Tier -> EJB in the New Gallery. On the right-hand side select Session Bean (EJB 1.1/2.x/3.0) and click on the OK button to open the 4 step Create Session Bean wizard.

• In wizard step 1 change the EJB Name to SurveySession, accept the pre-selected defaults. Note that JDeveloper already recognized the Entity implementation as TopLink POJOs. Click on Next.
  
• In wizard step 2 make sure that all methods are checked (expand the tree to see which methods are available). Click Next to go to the next wizard step.
• Step 3 shows the default values for the bean class and step 4 - Click Next to go from step 3 to step 4 - shows the implemented interfaces. Remote and Local interfaces are good enough for our scenario.
• Clicking Next in step 4 directs us to the wizard Summary window which we close by clicking on the Finish to go to the next wizard step.
  

A SurveySessionBean will be added to the project. Double-click on it and you'll see the generated Session Facade in the Code Editor.

Step 5: Create a Test Client

To finish the JDeveloper 10.1.3 tasks the creation of a test client needs to be done. Click on the SurveySessionBean in the Application Navigator and open the Context Menu. Find the New Sample Java Client entry and click on it. Accept all default values and click on the OK button to generate the test client. Open it and change the main method as follows:

    public static void main(String[] args) {
        try {
            final Context context = getInitialContext();
            SurveySession surveySession = 
                (SurveySession)context.lookup("SurveySession");
            Author author = new Author();
            author.setName("Olaf Heimburger");
            surveySession.persistEntity(author);
            for (Author a : surveySession.queryAuthorFindAll()) {
                System.out.println("id = " + a.getId());
                System.out.println("name = " + a.getName());
            }
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }

To test the Session Facade and the Test Client do the following:

1. Select the SurveySessionBean, open the Context Menu and select Run. Wait until you see Oracle Containers for J2EE 10g (10.1.3.3.0)  initialized.
2. Select the SurveySessionClient, open the Context Menu and select Run. You should get some output.

Steps for JDeveloper 11g

Step 1: Create a Model Layer Project

• To create a new Model Layer Project select OnlineSurvey in the Application Navigator, click on the Applications Menu on the right-hand side select the New Project... menu entry.
• In the New Gallery select an Empty Project and click on OK.
• In the Create Project window set the Project Name to ModelTopLink and click on the OK button.
• Select the newly created ModelTopLink project in the Application Navigator and open the Project Properties window with a double-click.
• In the Project Source Paths window, check the values of Project Source Paths and make sure that the Default Package is set to demo.survey.model.toplink. Click OK to close this window.

Step 2: Import TopLink Entities from Database Tables

• Select the ModelTopLink project in the Application Navigator.
• Open the New Gallery from the Context Menu -> New ....
• In the New Gallery expand the Business Tier and select TopLink/JPA. On the right-hand side select Java Objects From Tables and click on the OK button.
• In the Create Java Objects From Tables wizard step 1, Select Object-Relational TopLink Map, click on the New ... button. In the New TopLink Object Map window set the TopLink Map Name to surveyMap. The window instantly complaints about the missing Offline Database setting.
• Click on the New ... button to open the Create Offline Database window. For Name enter SURVEY, for Default Schema enter SURVEY as well. Database to emulate should be Oracle10g Express Edition Release 2. Click on the OK button to close this window.
• Click on OK to close the New TopLink Object Map window.
• Click on Next to go to the Select Tables step.
• In this step click on the Query button to get all available tables. Once the table names appear, select all of them. Move all entries from Available to Selected, by clicking on the >> button.
• Click Next to go to step, Specify Default Package. Accept the default value, the package name, and click Next to go to the next step.
• In step Specify Object Details, we can change the names of the Java Classes from plural to singular. Here we have table with Table Name and Class Name columns. To edit the Class Name double-click in the Authors cell and change the name to Author. To finish this action click on the next cell.
• Repeat this for every Class Name.
• Click Next to go to the Specify Relationships to Generate.
  
• Click Next to go to the Summary and click on Finish to close the wizard. Now all six entities will be created.You can find them in the Application Navigator under ModelTopLink->Application Sources->demo.survey.model.toplink. Also notice some additional files like sessions.xml and surveyMapModelTopLink->Application Sources->TopLink.

Step 3: Check the generated files

To check the generated files open them by selecting Answer.java, hold the Shift key, select Survey.java, and drag them into the working area right to Application Navigator. Every selected file will be opened in its own Code Editor. Select the tab named Answer.java to bring it to the front. You will see the completely generated code. Note that this class implements Serializable already!

Now is the right time to add the database sequences to the layer. This is not done automatically and must be configured in the TopLink configuration files sessions.xml and surveyMap.

• In the Application Navigator select sessions.xml. In the Structure window, double-click on default to open the Mapping Editor for the sessions.xml.
• Click on the Login tab and scroll down to the Sequencing section. Here select the Native Sequencing radio button. Also change the Preallocation Size to 1 to make it work with the current database sequence increment.
• Save your work.
• Now click on the surveyMap.
• In the Structure window expand demo.survey.model.toplink to get all available Java Classes in this map.
• Double-click on the Answer mapping. This opens the Mapping Editor for the Answer class.
• In the Descriptor Info tab check the Use Sequencing check-box. This makes this block editable.
• The values for Table and Field are correct. Set the value for Name to SEQ_ANSWERS.
• Now repeat setting of the database sequence for the classes Author, Item, Question, Response, and SurveySequencing Name to SEQ_AUTHORS, SEQ_ITEMS, SEQ_QUESTIONS, SEQ_RESPONSES, and SEQ_SURVEYS, respectively.
• Save your work.

Step 4: Create a Session Facade

Click on ModelTopLink in the Application Navigator. Any other entry of the ModelTopLink project will do, also. Select New... from the Context Menu and navigate to Business Tier -> EJB in the New Gallery. On the right-hand side select Session Bean and click on the OK button to open the Create Session Bean wizard.

• In step Select EJB Version, accept the Enterprise JavaBeans 3.0 (Java EE 5.0) selection. Click Next to continue.
• In step EJB Name and Queries change the EJB Name to SurveySession, accept the pre-selected defaults. Note that JDeveloper already recognized the Entity implementation as TopLink POJOs. Click on Next.
  
• In step Session Facade - Select JPA Entity Methods make sure that all methods are checked (expand the tree to see which methods are available). Click Next to go to the next wizard step.
• Step EJB Home and Component Interfaces shows the implemented interfaces. Remote and Local interfaces are good enough for our scenario.
• Clicking Next directs us to the wizard Summary window which we close by clicking on the Finish to go to the next wizard step.
  

A SurveySessionBean will be added to the project. Double-click on it and you'll see the generated Session Facade in the Code Editor.

Step 5: Create a Test Client

To finish the JDeveloper 11g tasks the creation of a test client needs to be done. Click on the SurveySessionBean in the Application Navigator and open the Context Menu. Find the New Sample Java Client entry and click on it. Accept all default values, select the Connect to OC4J Embedded in JDeveloper and click on the OK button to generate the test client. Open it and change the main method as follows:

    public static void main(String[] args) {
        try {
            final Context context = getInitialContext();
            SurveySession surveySession = 
                (SurveySession)context.lookup("SurveySession");
            Author author = new Author();
            author.setName("Olaf Heimburger 11g");
            surveySession.persistEntity(author);
            for (Author a : surveySession.queryAuthorFindAll()) {
                System.out.println("id = " + a.getId());
                System.out.println("name = " + a.getName());
            }
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }

To test the Session Facade and the Test Client do the following:

1. Select the SurveySessionBean, open the Context Menu and select Run. Wait until you see somethink like Embedded OC4J Server startup time: 83594 ms.
2. Select the SurveySessionClient, open the Context Menu and select Run. You should get some output.

What have we done so far?

Essentially the same as for the EJB 3.0 Model Layer. The generation was quite similar but the setup of the sequencing was different. Configuration files vs. Annotations in the source code.

A Note on EclipseLink

EclipseLink is an open-sourced version of Oracle TopLink 11 and available from the Eclipse site.
EclipseLink is interesting because it will be the JPA 2.0 reference implementation and although not covered in this entry, I'll definitely give it a try.

References

Oracle TopLink Getting Started Guide
Oracle TopLink Developer's Guide