Don’t be a
Muggle!
Be a
JDeveloper 9i
Wizard!
Overview
JDeveloper9i represents an exciting new development environment for Oracle professionals, allowing even novice developers to create simple applications easily and quickly. However, to really become proficient in any application development product is a huge task. When Peter Koletzke and I wrote Oracle Developer: Advanced Forms & Reports (Oracle Press, 2000), we tried to discuss what we believed it was important to know to be a good Oracle Forms and Reports developer. 1200 pages later, when the book was complete, we realized that we still had not completed the task. There was still much more to say about the product, but space, time and energy ran out.
Moving into the new product environment of JDeveloper 9i, we are faced with the even more daunting task of mastering a less mature, less unified and even more complex environment. Straightforward Java applications must be built in conjunction with Business Components for Java (BC4J) and the JDeveloper-generated Java (with knowledge of JDBC and SQLJ helpful). For web based applications there is a dizzying additional complication of HTML, XML and JavaScript.
Despite the difficulty, there are still many things that even novice developers can do with the JDeveloper 9i wizards which will never require more than writing an occasional line of code. Although you may not be able to create complex production applications using only the wizards, you will be able to build working prototypes which can be expanded.
This paper will introduce readers to the JDeveloper 9i product by briefly discussing its architecture and giving a sense of what can be accomplished using the wizards through a simple tutorial.
The JDeveloper Integrated Development Environment (IDE)
The first thing to recognize in JDeveloper is that, when building an application, all of its associated components do not sit in one file in the same directory. JDeveloper uses the concepts of workspaces and projects as ways to organize the parts of the programs created. In JDeveloper, you begin with the idea of a workspace. There is a natural partitioning of workspaces and projects in Developer terms. Forms developers should think of a workspace as an .fmb file and a project as a substantial portion of the program. Over time, you may find that you may want to partition a large application across multiple workspaces.
Workspaces, Projects and Packages
Physically, a workspace is a text file (with a .jws extension) that contains information about a set of projects. The workspace file is stored with other project-related files in one or more folders (operating system directory).
Project files can be found in multiple places across different directories. JDeveloper places all of the files required in one higher level directory with some number of sub-directories underneath. Projects can be used for two purposes:
1. To hold BC4J components to support the middle tier connection to the database.
2. To hold Java classes for your applications.
In general, you will have at least two projects in each workspace – one for BC4J components and a second one for the Java classes and interface objects if you are creating a Java application. If you are creating a JSP, all of its related elements are placed in a separate project. For very complex applications, you may need to use different projects to hold different portions of the application.
There is nothing to prevent you from using a single project for both purposes. Unlike Forms’ rigorously structured environment, in JDeveloper, you are writing 3GL code. Logical constructs such as workspaces and projects are simply ways of organizing the code. Any structure and discipline that exists can be either utilized or ignored.
Independent of the logical organization of the application is its physical organization, which is done through the specification of packages in Java. Packages correspond to operating system file folders. Java uses the term packages to maintain platform-independence. During development, the physical subdirectory/folder (path) where groups of related files are stored is referred to as a package. The term package also refers to a duplicate structure that exists in a class library file (.jar or .zip) that represents the storage paths within the library. The workspace file can maintain information about files stored in many different packages. Whenever you save the workspace, all current open files and windows are updated and saved for you. When you open a workspace, all of the files that it contains will be easily available in the Navigator.
Whenever you specify an object in JDeveloper, it will always be built in the context of a workspace, project and specific package (subdirectory) where the associated file components will be stored. Until you are much more experienced, it is simpler to use a single package for all of the components in a workspace. Within Java, if you are writing code in one class that exists in one package to reference an object existing in another package, you need to append the package path to the object references so that your program can find the object. This can be confusing for beginners, but won’t happen if all of the objects associated with a given workspace reside in a single package.
For the exercise in this paper, you will build a simple master-detail application using a few of the simple high-level wizards. Typically, a simple JDeveloper application will consist of one workspace and 2 projects (1 for BC4J and 1 for UI components) all residing in the same package.
Using the Wizards
It is important to understand how the wizards work. The way in which the JDeveloper wizards generate applications is not the only way to build applications. Users with JDeveloper experience will notice that Oracle’s generators themselves have slightly changed the algorithm that the wizards use to generate code from the 3.2 to the 9i versions of JDeveloper.
There are many high and low level wizards in JDeveloper (see Appendix). A great deal of work can be done in JDeveloper using the wizards. This greatly reduces, and in some cases, eliminates the need to write code. You can interact with JDeveloper in many of the same ways that you could with Oracle Forms while, behind the scenes, a lot of Java code is being written. If necessary, you can still make manual changes to the code that has been generated.
You will find numerous places where having everything as code makes a developer’s job easier. Searches and code replacements or cuts and pastes from one program into another can be easily and quickly done.
Naming Conventions
Consistently applied naming conventions are critical for the success of any system. Given the enormous number of elements available in the Java and JDeveloper environments, it is even more important to have a clearly defined set of conventions to follow.
Creating naming conventions for your Java applications has several benefits. First, when you review your code, you can quickly grasp the meaning of a particular element simply by seeing its name. Also, by knowing how elements are named, you can locate specific elements more efficiently, making your applications easier to maintain. Another benefit of using a naming convention is that it frees you from having to re-create ways to name elements. By having a naming framework, you will not have to stop and think about how to name each new element.
Ultimately, consistent naming conventions in a Java environment are even more important than they were in traditional development environments such as Oracle Developer. All of your program elements will not be neatly organized into an object navigator. You want to be able to scan through the code and quickly identify the type of element you are looking for. By using distinctive naming conventions with consistent prefixes or suffixes for the elements, you can quickly and easily search all of the elements of a particular type using an automated search routine.
Some general guidelines to follow in creating naming conventions are as follows:
· Use suffixes to imply type
· Be aware of case sensitivity – Java is case sensitive. Oracle is not.
· Use a dictionary of allowable words – Limit developers to a finite list of words that can be used
· Use abbreviations carefully – Make sure that abbreviations are long enough to quickly understand (5-6 characters is usually optimal)
If you don’t use precise naming conventions, you may end up spending time unnecessarily searching for a particular element. Consistently named elements applied throughout an organization also make it easier for developers to work on each other’s code.
Even though elements imported from other sources may not adhere to these conventions, enforcing a naming standard makes it easier to identify those elements that are imported from outside sources as well as better organizing those created internally.
Build a Java Application Using the Wizards
This application will display employee information by department, in a simple master-detail relationship. The data for this application is from the Scott schema (part of the starter database), which comes with all Oracle databases.
NOTE: JDeveloper wizards that contain more than one page start with a Welcome Page that provides a brief introduction to the purpose of the wizard and the types of details that you will need to specify. You can uncheck the “Display this page next time” checkbox if you do not need this information later. Clicking Back the next time you start the wizard will display the Welcome Page if you have unchecked this checkbox.
Similarly, the Finish page in each JDeveloper wizard provides a summary of the settings that you specified in the wizard and indicate what you will create when you click the Finish button. In most wizards, the Finish button is enabled on the next to last page and you can skip the Finish page by clicking this button (if you know which page is next to last).
A. Setting up the Workspace
1. Right-click the Workspaces node in the System tab of the Navigator and select New Workspace item. The New Workspace dialog will be displayed.
2. The default directory name and file names will be something like “Workspace1.” Change the default directory name to “employee” and the workspace file name to “Employee” as shown in Figure 1.
Figure 1. New Workspace dialog
3. Click OK to display the Project wizard. The default directory and file name will be something like “Project1.” Change the default directory name to “buscomp” and the workspace name to “DeptBusComp.”
4. Click OK to complete the project file. Click the Save All button in the toolbar.
Organizing files in JDeveloper
You have now created a workspace file (with a .jws extension) and a directory (package) to hold the workspace file for this application. Keeping the workspace in a separate directory allows easier access to the files related to the application. Under the workspace directory are the project directories that organize each of the projects.
The previous steps added a project file (with a .jpr extension) and directory that you will use for the Business Components for Java (BC4J) files. This project is empty, but you will add the Java files to define the business components later. The business components layer allows your Java application code to easily access database objects.
Any number of workspaces can access the same project. For example, Workspace 1 contains Project 1 and Workspace 2 also contains Project 1. You need to manage your workspaces carefully since changes that you make in one workspace may affect another workspace’s projects.
Typically, you will build one business components project that will be accessed by a number of application (front-end) projects. Therefore, the business components project will be common to more than one workspace and you need to take care when making changes to that project because it will affect other applications.
Creating a Connection
When you are asked to create an application, you generally have access to a limited number of database instances. Connecting to these databases is a repetitive task. To facilitate this task, JDeveloper has implemented a definition called a connection that is shared across all development sessions. This definition is used to store the user name, password, URL, and related parameters for your database connections.
You can expand the Connections node (in the Navigator Pane) to view the server connections you have already defined as shown in Figure 2.
Figure 2. Connections Node
By doubleclicking a connection, you can view its properties such as the username and password. If you have not created a database connection, follow these steps before setting up the BC4J layer. This is normally a one-time operation for each database connection.
1. Right click the Connections node and select New Database Connection to start the Connection Wizard.
2.
Enter the connection name as “ScottConnection” and leave
the default type of “Oracle (JDBC).” Click Next to display the Authentication
Page. Enter the following:
Username as “SCOTT”
Password as “tiger”
Deploy Password (checked)
Role (leave blank)
3.
Click Next to display the Connection page. Check to see
that the fields are filled in as follows:
Driver as “thin”
Host ID as “localhost” or whatever
you use as the database machine name
SID as “ORCL” or whatever you use as
the database name
4. Click Next to display the Test page. Click the Test button. Dismiss the success message dialog and click Finish to close the Connection Wizard. If the test is unsuccessful, move back to the previous pages and correct the connection properties.
B. Creating the Business Components
Now you need to create the Java and XML business components files that will provide the data access layer for your Java applications. It will use the business components wizard to build Java code views of the employee and department tables. The BC4J layer will maintain the parent-child association rules for the tables and be responsible for updating the database when you insert, delete, or change rows. Each table will have a .java file that implements the business components functionality and a .xml file that holds the data dictionary metadata (table definition).
JDeveloper wizards that contain more than one page start with a Welcome Page that provides a brief introduction to the purpose of the wizard and the types of details that you will need to specify. You can uncheck the “Display this page next time” checkbox if you do not need this information later. Clicking “Back” the next time you start the wizard will display the Welcome Page if you have unchecked this checkbox. Similarly, the Finish page in each JDeveloper wizard provides a summary of the settings that you specified in the wizard and indicate what you will create when you click the Finish button. In most wizards, the Finish button is enabled on the next to last page and you can skip the Finish page by clicking this button.
Run the Business Components Project Wizard
1. Click the DeptBusComp project node. Select File | New, click the Business Components category and select Business Components.
2. Click OK to start the Business Components Project Wizard.
3.
Select ScottConnection for the Connection Name field. If necessary,
you can add a connection or edit an existing connection using the appropriate
buttons on this page. Leave the default SQL flavor and Type Map as “Oracle.”
Click the Next button to display the Package page.
4.
Enter “bc4j” as the package name. Click Next to display
the Business Components page.
5.
The schema field should show “SCOTT” and the Tables
checkbox should be checked. Select DEPT and EMP (using ctrl-click) from the Available field and move them to the
Selected field using the
> button.
6. Change the module name field at the bottom to “DeptEmpModule.” The page should appear as shown in Figure 3.
Figure 3. Business Components Project Wizard
7. Click Finish to create the business components and add them to your project. If you expand the project node and the DeptEmpModule nodes in the Navigator, you will see something like Figure 4.
Figure 4. Files created in BC4J project
8. Click the Save All button. Note that before saving, items will appear in italics in the Navigator. This is a visual cue to indicate which items have not yet been saved.
Look at the code that JDeveloper has generated so far by double clicking on file names in the Navigator to open them in the Source Editor.. You now have over 1000 lines of code that can be modified and extended to fulfill your needs. Be sure to look at the XML files, which hold the definitions for the BC4J objects. You will see many terms, tags, specifiers, classes, and language constructs that are new to you but the table definition information will be familiar.
C. Create a User Interface (UI) Project
The next project that you will add to the workspace will be used to store the GUI code to display the data from DEPT and EMP. This project logically isolates the GUI code from the business components code since each of the projects represents a different functional area and may be deployed separately. Projects can have one or more deployment profiles that designate how to deploy the project.
Create the Project
1. Right click the Employee.jws workspace node in the Navigator and select File | New and double click Empty Project to display the New Project dialog.
2. Change the default directory name (for example, “Project1”) to “deptempapp” and the project file name to “DeptEmpApp” as shown in Figure 5.
Figure 5. New Project window
3. Click OK to create the project. Click Save All.
Create the Client Data Model
Before creating an application, you need to define which view objects (representing tables) you will use in the BC4J project. This definition is stored in a client data model.
1. To define the data model, select File | New, click the JClient Objects category and double click the JClient Data Model item. Click Next.
2. On the Name page, change the name to “DeptEmpModel” and click Next to display the Application Module page.
3. Click Next and Finish. This will create a .cpx file under the project node in the Navigator.
4. Click Save All. Examine the Structure Window at the bottom of the navigator and expand the DeptEmpModel and View objects nodes to verify that the Dept and Emp views are defined.
Create the Application
Now that the data model is created, you can define the classes that will display the data on a form.
1. Right click the DeptEmpApp project node and select New to display the New Gallery. Select the JClient Objects category and double click the JClient Form item to start the JClient Form Wizard.
2. Select Master-Detail tables and Frame. Click Next to display the Form Layout page.
3. The default master detail layout is set up to use a single columns layout for the master and table layout for the detail. This will work for this application. Click the Next button to display the Data Model page.
4. The Data Model page is used to select the client data model. If the data model were not defined, you could click the New button to configure the data model. For this application, the data model that you created before will appear. Click Next to move to the Panel View page.
5. The DeptView object will be pre-selected as the master. The EmpView object will be selected as the detail. These selections are correct. Click Next to display the Attribute Selection page for the master view.
6. All attributes will appear in the selection box on the right. Click Next to display the Attribute Selection page for the detail view. All attributes will appear in the selection box on the right. Click Next to display the File Names page.
7.
Change the following fields on this
page:
Package name
to “deptempapp”
Frame
name to “DeptEmpFrame”
Layout panel name to “DeptEmpLayout”
Master panel name to
“DeptPanel”
Detail panel
name to “EmpPanel”
8. Click Next and Finish. Four Java files will be added under the .cpx file in the project node as shown in Figure 6:
Figure 6. Java files added by Application Wizard
5. Click Save All. .
6. Run the form by right-clicking DeptEmpFrame.java and selecting Run DeptEmpFrame.java. The application should start up and look like Figure 7.
Figure 7. Sample Dept/Emp application
Note that you created another project to contain the GUI code and files for the application that you are building. You also defined a client data model that the user interface code attaches to when it requires business components services. The JClient Form wizard stepped you through defining the proper panels in the master-detail application. For a production-level form, you would modify the form and BC4J code to meet your needs. The wizard approach gives you a default with which to start.
Conclusions
The JDeveloper wizards have great power and flexibility and can automate many tasks. There are high level wizards that build whole parts of your application with limited flexibility and lower level wizards that build a single small component at a time.
Most of these wizards are accessible from the File|New menu, but some are only available in particular contexts.
The wizards can’t be used exclusively to build robust applications. There are still places where you will need to modify (or write) the code.
Experienced Java Developers will tend to avoid the wizards and to build their code by hand. I believe that this is a mistake. The wizards will enforce a certain level of consistency in the application. Code should be generated from the wizards where possible and code that is written by hand should be written in a way that is consistent with the generated code.
If you are careful and make your hand modifications to the code using a similar style to the wizard-generated code, you can still maintain much of your application using the wizards. However, if you ignore the wizards and write your code as you please, then the JDeveloper wizards will be unable to read and extract code into the appropriate structures. It is easy to write code that negates much of the power of JDeveloper.
About the Author
Dr.
Appendix
The following is a list of many of the JDeveloper Wizards. Many can be accessed using the File|New menu command. Others are automatically started at certain points in the creation of your applications or triggered by the completion of another wizard. Most are re-entrant.
List of JDeveloper9i Wizards
In addition to these “official” wizards, JDeveloper contains many easy-to-use dialog windows where users simply fill in the information and click OK to create various components and other items necessary for their applications.