Oracle9i Jdeveloper User's Guide

Oracle9i Developer Suite
Oracle9i JDeveloper User’s Guide
Release 9.0.2 Production

for Windows, Solaris, Linux, HP-UX
May, 2002
Part No. A97276-01
This book contains the Help topics including conceptual, procedural, and F1
Help in Oracle9i JDeveloper Release 9.0.2 Production available on Oracle
Technology Network (OTN).
Oracle9i JDeveloper User’s Guide, Release 9.0.2
Part No. A97276-01
Copyright © 1996, 2002, Oracle Corporation. All rights reserved.
The Programs (which include both the software and documentation) contain proprietary information of
Oracle Corporation; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent and other intellectual and industrial property
laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required
to obtain interoperability with other independently created software or as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any problems
in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this
document is error-free. Except as may be expressly permitted in your license agreement for these
Programs, no part of these Programs may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.
If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on
behalf of the U.S. Government, the following notice is applicable:
Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial
computer software" and use, duplication, and disclosure of the Programs, including documentation,
shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement.
Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer
software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR
52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500
Oracle Parkway, Redwood City, CA 94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,
redundancy, and other measures to ensure the safe use of such applications if the Programs are used for
such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the
Programs.
Oracle is a registered trademark. Oracle8i, Oracle9i, PL/SQL, JInitiator, and SQL*Plus are trademarks or
registered trademarks of Oracle Corporation. Other names may be trademarks of their respective
owners.
Copyright© 1999, 2000 The Apache Software Foundation. All rights reserved. This product includes
software developed by the Apache Software Foundation (http://www.apache.org). SOAP is provided
"AS IS".
Copyright© 2000 The Apache Software Foundation. All rights reserved. This product includes software
developed by the Apache Software Foundation (http://www.apache.org). BATIK is provided "AS IS".
Portions of this software and documentation copyright © 2001Three D Graphics.

Send Us Your Comments
Oracle9i JDeveloper User’s Guide, Release 9.0.2 for Windows, Solaris, Linux, HP-UX
Part No. A97276-01
Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this
document. Your input is an important part of the information used for revision.
■ Did you find any errors?
■ Is the information clearly presented?
■ Do you need more information? If so, where?
■ Are the examples correct? Do you need more examples?
■ What features did you like most?
If you find any errors or have any other suggestions for improvement, please indicate the document
title and part number, and the chapter, section, and page number (if available). You can send com-
ments to us in the following ways:
■ Post a message on the Oracle Technology Network - Oracle9i JDeveloper Forum at:
http://otn.oracle.com/products/jdev/content.html
Note: Click the Discussion Forum link
■ FAX: 650-506-7433 Attn: Oracle9i JDeveloper User Assistance
■ Postal service:
Oracle Corporation
Oracle9i JDeveloper User Assistance
500 Oracle Parkway, 2OP12
Redwood Shores, CA 94065
United States
If you would like a reply, please give your name, address, telephone number, and (optionally) elec-
tronic mail address.
Sofware-related Questions
If you have problems with the software, contact your local Oracle Support Services representative or
if you prefer, post a message on the Oracle Technology Network - Oracle9i JDeveloper Forum at:
■ http://otn.oracle.com/products/jdev/content.html
Note: Click the Discussion Forum link
iii
iv
Preface
This Adobe PDF document contains the entire set of Help topics in the Oracle9i
JDeveloper Release 9.0.2 online Help system. These topics include conceptual and
procedural help as well as the F1 Help (context-sensitive Help).
When running JDeveloper, you can access these topics directly by choosing the
Help | Help Topics menu option or by pressing the Help button on the dialog or
winodw or the F1 key anywhere in the user interface.
The main purpose of this document is to facilitate the printing of multiple Help
topics using Adobe Acrobat. As this document is quite lengthy, you can choose to
print only the desired range of pages.
Note:
■ To view this PDF document, you can download a free copy of Adobe
Acrobat Reader from http://www.adobe.com/.
■ Although you can search for a word(s) in Adobe Acrobat, excellent
full-text search capabilities are available within JDeveloper’s Help
system.
■ For more information, see "How to Use the Online Help."
■ This book is not an orderable part and therefore is not available for
purchase from Oracle Store.
Intended Audience
This document is intended for application developers interested in using
JDeveloper to create Java and Java2 Enterprise Edition (J2EE) applications with
end-to-end support for developing, debugging, and deploying e-business
applications.
Users should be familiar with general Web technology, HTML, and some Java.
Oracle9i JDeveloper is certified on Windows, Solaris, Linux, and HP-UX.
v
JDeveloper Book Structure
This PDF document and the bookmarks (left frame) are structured to closely mirror
the book order presented in the JDeveloper Online Help Table of Contents. The
conceptual and procedural help topics are presented first followed by the F1 Help
topics.
The following JDeveloper books are not available in PDF format:
■ UIX Developer’s Guide
■ UIX Element Reference
■ Developing Help With Oracle Help for Java
■ All Javadocs provided with JDeveloper
■ Oracle Business Intelligence (BI beans)
JDeveloper Conceptual and Task Help

The JDeveloper Conceptual and Task Help topics are presented in the following
book order:
1. Welcome to Oracle9i JDeveloper

This book contains information about new features, migration, copyright, and
contact information.
2. Getting Started with JDeveloper

This book contains information about everything you need to know to get started
with JDeveloper workspaces and projects, configuring database connections, and
how to customize the IDE.
3. Tutorials
This book contains a number of helpful tutorials, highlighting the various
JDeveloper features and capabilities. For example, you can learn how to build a
simple Java application, model Java classes, develop a Business Components for
Java (BC4J) application, create JSPs with data tags, create and use Web services, and
much more.
4. Developing Web Applications (J2EE Web Modules)

This book covers working with servlets, working with JSP pages, working with JSP
tag libraries, working with data bound BC4J JSP pages, working with UIX XML and
UIX JSP pages, working with XSQL servlets, and developing using UIX
technologies.
5. Working with XML Files

This book covers using the JDeveloper XML editor to edit XML languages
including UIX, UIT, XSQL, XSL, XHTML and WSDL files.
6. Working with UIX XML and UIX JSP Pages

This book covers developing, editing, and viewing UIX XML and UIX JSP pages.
vi
7. Working with XSQL Servlets
This book covers XSQL tags, XSQL servlet clients, and XSQL tag reference.
8. Developing Java GUI Clients

This book covers JDeveloper’s user interface design tools, layout managers,
working with containers and components, events, applets, JClient applications, and
Java Web Start.
9. Testing and Optimizing Your Code

This book covers compiling, running, debugging your Java applications. In
addition, JDeveloper features such as CodeCoaching and profiling address writing
more efficient Java programs.
10. Developing JavaBeans

This book covers creating and customizing JavaBeans and creating a Pluggable Java
Component (PJC).
11. Developing Business Components

This book covers the Business Components for Java (BC4J) framework including
new features, creating BC4J applications and BC4J clients, using the API,
customization, extending BC4J, developing BC4J for foreign datasources, using
XML with BC4J. In addition, the BC4J F1 Help and glossary are provided.
12. UML Modeling

This book covers UML modeling basics, diagram layouts and elements, modeling
Java classes, reverse engineering, modeling business components, modeling
activities for E-business integration, and deploying integration files.
13. Developing Enterprise JavaBeans

This book covers developing EJBs with JDeveloper, EJB generated files, EJB import
and migration, and several helpful EJB Walkthroughs.
14. Packaging and Deploying

This book covers the packaging and deployment of J2EE JAR files including Web
Archive (WAR), EJB JAR, and Enterprise Archive (EAR) to Oracle9iAS Containers
for J2EE (OC4J), BEA WebLogic, Apache Tomcat, and VisiBroker. Also, covered are
deployments to the Oracle9i database, BC4J deployments, and Web services
deployments.
15. Using SQL in Java Programs

This book covers embedding SQL in Java programs with JDBC, accessing Oracle
objects and PL/SQL packages using Java and JPublisher, and improving application
performance with Java stored procedures.
16. Browsing the Database

This book covers browsing schemas through JDBC connections, using the SQL
worksheet, and launching SQL*Plus.
vii
17. Using Source Control Support
This book covers using Oracle9i Software Configuration Manager (SCM) support,
branching with Oracle9i SCM, using Rational ClearCase with JDeveloper, using
Concurrent Versions System (CVS) with JDeveloper, and using your own source
control system.
18. Web Services

This book covers Web services concepts including WSDL and SOAP, getting started
with Web services, developing Web services, and using Web services.
19. Using WebDAV Support

This book covers creating a WebDAV connection, managing files and folders on a
WebDAV connection, and locking and unlocking files on a WebDAV connection.
20. Extending JDeveloper Using the Addin API

This book covers the JDeveloper Integrated Development Environment (IDE),
creating a Wizard, defining document types, creating an editor, creating an explorer,
defining a command, and other extension types.
viii
JDeveloper F1 Help
F1 Help topics include descriptions for each field and UI element in a JDeveloper
dialog box or window including the available options. The F1 topics for each book
are typically presented in alphabetical order. The JDeveloper F1 Help topics are
presented in the following book order:
1. Getting Started F1 Help

Information about the New Gallery, IDE Preferences dialog, UI editor, and general
IDE dialogs and windows are covered.
2. JClient F1 Help
Information about the JClient Data Model Definition Wizard, JClient Graph Wizard,
JClient Form Wizard, JClient Java Web Start Wizard, and various JClient dialogs are
covered.
3. Web Application F1 Help

Information about BC4J Web Application Wizard, BC4J Configuration Manager,
Data Tag Wizard, Web Module Wizard, Servlet Wizard, Web Application 2.2
Deployment Descriptor settings, Web Bean Editor, and Web Object Manager are
covered.
4. JSP Tag F1 Help

Information about Web beans, JSP tags, and JBO data tags are covered.
5. JSP and JSP UIX General F1 Help

Information about taglib deployment descriptors, JSP tags, XML editor, UIX JSP
Wizard, UIX Wizard, and the Java Web Start Wizard are covered.
6. UIX XML and UIX JSP Pages F1 Help

Information about bc4juix, uix, and xsql tags are covered.
7. Compiling and Debugging F1 Help

Information about all compiling, debugging, and running dialogs and windows
including those related to the breakpoints, smart data, watches, inspector, project
settings, remote debugging, tracing, and Tools Preferences are covered.
8. CodeCoach and Profiling F1 Help

Information about all CodeCoach and Profiling project settings and related dialogs
and windows are covered.
9. Developing JavaBeans F1 Help

Information about the PJC Class Editor, BeanInfo Class Editor, and related bean
dialogs and windows are covered.
10. UML Modeling F1 Help

Information about the Activity dialog, E-Business Integration Wizard, Swimlane
properties, and related dialogs and windows are covered.
ix
11. Enterprise JavaBeans F1 Help
Information about the EJB JAR deployment descriptors (ejb-jar.xml), EJB Class
Editor, and the EJB Wizard are covered.
12. Packaging and Deploying F1 Help

Information about the Business Components Deployment Wizard, Application
Server Connection Wizard, deployment profile settings, J2EE Client
(application-client.xml) and Web Module (web.xml) deployment
descriptors, OC4J EJB deployment descriptors (orion-ejb-jar.xml),
deployment preferences, preview deployment, and all deployment-related dialogs
and windows are covered.
13. SQL in Java Programs F1 Help

Information about SQLJ class, project properties, and viewer dialogs and windows
are covered.
14. Source Control F1 Help

Information about Oracle9i SCM Merge Wizard, ClearCase, CVS, Oracle9i SCM
Connection Wizard, Oracle9i SCM Workarea Wizard, and related dialogs and
windows are covered.
15. Web Services F1 Help

Information about Web Service Stub/Skeleton Wizard, Web Service Publishing
Wizard, and SOAP Server Connection Wizard are covered.
16. WebDAV F1 Help

Information about WebDAV connection, locks, and other related dialogs and
windows are covered.
x
Welcome to JDeveloper - Overview
● Welcome to Oracle9i JDeveloper
❍ Copyright and Other Legal Notices
❍ Contact Us
❍ How to Use the Online Help
■ Help Navigator Window
■ Help System Menus
❍ JDeveloper Accessibility Information

❍ Navigating JDeveloper with Keystrokes
❍ Ways to Migrate Projects to Oracle9i JDeveloper
■ Migrating JDeveloper 3.2.x Projects to Oracle9i JDeveloper
■ Importing JDeveloper 3.2.x Connections and Files into Oracle9i
JDeveloper
■ Updating JDeveloper 3.2.x Business Components Projects for
Oracle9i JDeveloper
■ Migrating XSQL Projects from JDeveloper 3.2.x to Oracle9i
JDeveloper
■ Creating Oracle9i JDeveloper Deployment Profiles for Migrated
JDeveloper 3.2.x Projects
■ Migrating Oracle9i JDeveloper Beta Projects to Oracle9i JDeveloper

Production
■ Updating Oracle9i JDeveloper Beta JSP Projects
■ Migrating Oracle9i JDeveloper Release Candidate Projects to Oracle9i

JDeveloper Production
■ About Changes to CMT Service Beans
■ Migrating Projects Between Different Installations of Oracle9i JDeveloper
1-1
Welcome to Oracle9i JDeveloper!
Oracle9i JDeveloper is a J2EE™ development environment with end-to-end support for
developing, debugging, and deploying e-business applications. JDeveloper empowers users
with highly productive tools, such as the industry's fastest Java debugger, a new profiler, and
the innovative CodeCoach tool for code performance analysis and improvement.
To take J2EE application development to a higher level of productivity, JDeveloper offers

Business Components for Java (BC4J), a standards-based, server-side framework for creating
scalable, high-performance Internet applications. The framework provides design-time facilities
and runtime services to drastically simplify the task of building and reusing business logic.
For more information, please see any of the following:
● New Features in Oracle9i JDeveloper

● Ways to Migrate Projects to Oracle9i JDeveloper
● How to Use the Online Help
● JDeveloper9i Tutorials
● Copyright and Other Legal Notices
● Contact Us
Additional information is available at the Oracle Technology Network (OTN)
OTN is your free definitive source for Oracle technical information on developing for the Internet
platform. You will be part of an online community with access to free software (including
JDeveloper addins), OTN-sponsored Internet developer conferences, and discussion groups on
up-to-date Oracle technology. If you are not already a member, please sign up for a free
membership at http://otn.oracle.com/free/
The most recent information regarding Oracle9i JDeveloper, including whitepapers, addins, and
product updates, is available at OTN at http://otn.oracle.com/products/jdev/
1-2
Copyright and Other Legal Notices
Copyright Notice
"Copyright © 1997, 2002, Oracle Corporation. All rights reserved."
"Copyright© 1999, 2000 The Apache Software Foundation. All rights reserved. This product includes
software developed by the Apache Software Foundation (http://www.apache.org). SOAP is provided
"AS IS". "
"Copyright© 2000 The Apache Software Foundation. All rights reserved. This product includes software
developed by the Apache Software Foundation (http://www.apache.org). BATIK is provided "AS IS". "
"Portions of this software and documentation copyright © 2001Three D Graphics."
License Restrictions & Warranty Disclaimer
"The Programs (which include both the software and documentation) contain proprietary information of
Oracle Corporation; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent and other intellectual and industrial property
laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent
required to obtain interoperability with other independently created software or as specified by law, is
prohibited.
The information contained in this document is subject to change without notice. If you find any
problems in the documentation, please report them to us in writing. Oracle Corporation does not
warrant that this document is error free. Except as may be expressly permitted in your license
agreement for these Programs, no part of these Programs may be reproduced or transmitted in any
form or by any means, electronic or mechanical, for any purpose, without the express written
permission of Oracle Corporation."
Restricted Rights Notice
"If the Programs are delivered to the US Government or anyone licensing or using the Programs on
behalf of the US Government, the following notice is applicable:"
"RESTRICTED RIGHTS NOTICE

Programs delivered subject to the DOD FAR Supplement are 'commercial computer software' and use,
duplication and disclosure of the Programs including documentation, shall be subject to the licensing
restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject
to the Federal Acquisition Regulations are 'restricted computer software' and use, duplication, and
disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer
Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA
94065."
Hazardous Applications
1-3
"The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other
inherently dangerous applications. It shall be licensee's responsibility to take all appropriate fail-safe,
back up, redundancy and other measures to ensure the safe use of such applications if the Programs
are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by
such use of the Programs."
Trademark Notice
"Oracle, Oracle9i, Oracle8i, PL/SQL, and JInitiator are trademarks or registered trademarks of Oracle
Corporation. Other names may be trademarks of their respective owners."
Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation accessible, with good
usability, to the disabled community. To that end, our documentation includes features that make
information available to users of assistive technology. This documentation is available in HTML format,
and contains markup to facilitate access by the disabled community. Standards will continue to evolve
over time, and Oracle Corporation is actively engaged with other market-leading technology vendors to
address technical obstacles so that our documentation can be accessible to all of our customers. For
additional information, visit the Oracle Accessibility Program Web site at
http://www.oracle.com/accessibility/.
Accessibility of Code Examples in Documentation

JAWS, a Windows screen reader, may not always correctly read the code examples in this document.
The conventions for writing code require that closing braces should appear on an otherwise empty
line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle
Corporation does not own or control. Oracle Corporation neither evaluates nor makes any
representations regarding the accessibility of these Web sites.
UIX Tag Libraries

Oracle has provided certain Java class definitions within the UIX tag library in JDeveloper which may
be used in accordance with the Oracle program license that accompanied JDeveloper ("Java Classes").
The Java Classes may be modified in future releases of JDeveloper, and future versions of the Java
Classes may not be backwardly compatible.
1-4
Contact Us
Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of
the Oracle9i JDeveloper Beta online documentation. Your input is an important part of the
information used for revisions.
We would like to know:
● Did you find any errors?

● Is the information clearly presented?
● Do you need more information? If so, where?
● Are the examples correct? Do you need more examples?
● What features did you like most about the guides?
You can send your comments by email at jdev_us@oracle.com
In your email, please indicate the following information:
● Topic title (for example, "Starting JDeveloper")

● Table of contents path (for example, "Working with JDeveloper/Introduction")
If you have problems with the software, please contact Oracle Support Services. Paste the
following URL in your web browser: www.oracle.com/support
1-5
How to Use the Online Help
The online help viewer has two windows and a menu bar:
Navigator window
Displays the table of contents, index, and search panel, depending on which tab you
select.
Topic window
Displays the help topic that you select from the table of contents. It is the window that
contains the topic that you are reading right now.
Menus
The menu commands available on the menu bar will vary depending on which window
you are viewing.
You can also use the online help in hosted or local mode. Hosted mode allows you to read the
documentation over the World Wide Web. The default option is to use the Oracle Technology
Network for hosted documentation, but you can also host the documentation on a local server.
Instructions for setting up your own documentation host are available in the installation guide.
Note: We only suggest using hosted documentation when you have a broadband connection.
When you start the help system in hosted mode, approximately 4 MB of information must be
downloaded before the help system will start.
Using hosted documentation
1. In JDeveloper, in the Tools menu, select Preferences .

2. In the Preferences dialog, click Documentation.
3. Click Use Hosted Documentation. By default, the OTN host is selected, but you can set
it ot any URL. If you need to reset it to OTN, enter
http://otn.oracle.com/hosted_doc/jdev/jdeveloper/jdeveloper.hs
Using local documentation
1. In JDeveloper, in the Tools menu, select Preferences .

2. In the Preferences dialog, click Documentation.
3. Click Use Local Documentation. If you have a default installation, you do not have to set
1-6
the path to the local documentation.
1-7
Help Navigator Window
The navigator window has three tabs:
Contents
Displays a list of all books and topics in the online help. To display a topic in the topic
window, double-click a topic title in the table of contents. If you want to open another
topic in a separate window, right click on the topic.
Index
Displays an alphabetical list of index entries much like the index of a book. To use the
index, scroll through the index list and click on an index entry, or type a word that is
related to the topic you want to view. A list of topics related to the word you select is
displayed in the lower pane of the window. Double click a topic in the list to display its
contents in the topic window.
Search
Allows you to search for a specific word in the entire online help system. Type a word
related to the topic you want to view, and click the Search button. A list of topics related
to that word is displayed in the lower pane of the window. Double click a topic in the list
to display its contents in the topic window.
The toolbar at the top of this window has buttons to:
Display a topic that you select in the table of contents, index, or search
list in the topic window.
Display a topic that you select in the table of contents, index, or search
list in a new topic window.
Launch the search window.
1-8
Help System Menus
The help system menus have the following functions:
File Comments
Enabled when a topic is selected in the tree; displays the topic in the
Display
docked topic window. Keyboard: Enter
Enabled when a topic is selected in the tree; displays the topic in a new
Display in New Window
topic window. Keyboard: Ctrl N
Print Tree Prints the contents tree as it currently appears. Keyboard: Ctrl X
Print Topic Prints the topic in the docked topic window. Keyboard: Ctrl P
Prints the selected topic and all the topics contained within it in the table of
Print Topics
contents.
Close Closes the current window
Exit Closes the help system viewer.
View Comments
Contents Switches the view of the Navigator to the Contents page
Index Switches the view of the Navigator to the Index page
Go Comments
Enabled when a second topic is displayed in the docked topic window;
Back
disabled when the user goes back to the first topic
Enabled when a user goes back to a previous topic; stays enabled if the
Forward user continues to go back to previous topics; disabled if the user goes
forward to the newest topic
Tools Comments
Displays the Navigator; when the Navigator is already running, choosing
Navigator
Navigator brings it to the front
Undocks the topic window and the Navigator, returning them to their default
Undock
states
Dock Enabled when the topic window and the Navigator are undocked
Help Comments
About Displays the About JDeveloper dialog box
1-9
JDeveloper Accessibility Information
It is our goal to make Oracle Products, Services, and supporting documentation accessible to
the disabled community. JDeveloper supports accessibility features. To make the best use of
our accessibility features, Oracle Corporation recommends the following software configuration:
● Windows NT 4.0 (with Service Pack 6) or Windows 2000

● Sun Java Access Bridge 1.0.2
● JAWS 3.70.87
● Microsoft Internet Explorer 5.5
● JDK 1.3.1
For additional accessibility information for Oracle products, paste the following URL in your web
browser:
www.oracle.com/accessibility
For the latest configuration information or for information on addressing accessibility and
assistive technology issues, see the Oracle Accessibility FAQ at:
www.oracle.com/accessibility/faq.html
This help topic includes the following information that pertains to JDeveloper accessibility:
● Using a Screen Reader and Java Access Bridge with JDeveloper

● JDeveloper Features that Support Accessibility
● Recommendations for Customizing JDeveloper
● Highly Visual Features of JDeveloper
Using a Screen Reader and Java Access Bridge with JDeveloper
In order for assistive technologies, like screen readers, to work with Java-based applications
and applets, the Windows-based computer must also have Sun's Java Access Bridge installed,
as described below.
Please refer to the Oracle9i Developer Suite Installation Guide found in the root directory on the
Oracle9i Developer Suite CD, in <oracle_ids_home>/doc/core902/install/toc.htm for information
about installing Oracle9iDS. Please refer to the Preface in the documentation found on the
1-10
Oracle9iDS CD, in <oracle_ids_home>/doc/core902/install/pref.htm for additional information
about accessibility.
Please refer to the following information to set up a screen reader and Java Access Bridge.
1. Install the screen reader, if it is not already installed.
Refer to the documentation for your screen reader for more information about
installation.
2. Install JDeveloper.
Refer to the Installation Guide found in <oracle_ids_home>/doc/core902/install/toc.htm

for more information about JDeveloper installation.
3. Download Java Access Bridge 1.0.2. The file you will download is accessbridge-
1_0_2.zip. It is available from
http://java.sun.com/products/accessbridge">http://java.sun.com/products/accessbridge.
Refer to the Java Access Bridge documentation available from this web site for more
information about installation and the Java Access Bridge.
4. After downloading the file, extract the contents to a folder; for example,
accessbridge_home.
5. Install Java Access Bridge by running Install.exe from the
<accessbridge_home>\installer folder.
6. Confirm that you want to install the Java Access Bridge into each of the Java virtual
machines displayed in the dialog. Click OK when you see the Installation Completed
message.
7. Confirm that two jar files: access-bridge.jar and jaccess-1_3.jar were added to the folder
<oracle_home>\jdk\jre\lib\ext during the install. If necessary, copy them from
<accessbridge_home>\installer\installerFiles to
<oracle_home>\jdk\jre\lib\ext.
8. Confirm that two DLL files: JavaAccessBridge.dll and WindowsAccessBridge.dll were
added to the folder <oracle_home>\jdk\jre\lib\ext. If necessary, copy them from
<accessbridge_home>\installer\installerFiles to <oracle_home>\jdk\jre\lib\ext.
9. Add the files listed above, JavaAccessBridge.dll and WindowsAccessBridge.dll, to the
Winnt\System32 directory, as they must be in the system path in order to work with
JDeveloper.
1-11
10. Confirm that the PATH environment variable has been updated to include the directory
where the DLL files were installed, <oracle_home>\jdk\jre\lib\ext.
11. Confirm that the file <oracle_home>\jdk\jre\lib\accessibility.properties includes the
following line:
assistive_technologies=com.sun.java.accessibility.AccessBridge
If necessary, copy the file accessibility.properties from

<accessbridge_home>\installer\installerFiles to <oracle_home>\jdk\jre\lib.
12. Modify the file jdev.conf located in the folder <JDeveloper Install directory>\jdev\bin to
uncomment the AddVMOption line as shown below:
#
# Prepend patches to the bootclasspath. Currently, rtpatch.jar contains a
# patch that fixes the javax.swing.JTree accessibility problems.
# Uncomment the line below if you need to run JDeveloper under JAWS.
#
AddVMOption -Xbootclasspath/p:../../jdk/jre/lib/patches/rtpatch.jar
13. It is also necessary to use Hotspot instead of OJVM to run JDeveloper. To do this, set
the SetJavaVM line in the jdev.conf file as follows:
SetJavaVM hotspot
14. Start your screen reader.

15. Start JDeveloper by running the file jdev.exe located in the folder <JDeveloper Install
directory>\jdev\bin.
The steps above assume you are running Windows and using a Windows-based screen
reader. A console window that contains error information (if any) will open first and then the
main JDeveloper window will appear, once JDeveloper has started.
JDeveloper Features that Support Accessibility
The following features in JDeveloper are designed to support accessibility:
● Keyboard Access
1-12
● Screen Reader Readability
● Flexibility in Font and Color Choices
● No Audio Only Feedback
● No Dependency on Blinking Cursor and Animation
● Screen Magnifier Usability
Keyboard Access
JDeveloper features support keyboard access to JDeveloper functionality; a summary is

provided below. The mnemonic keys used to open menus and choose commands are included
in all procedural topics. Please refer to the following topics for a summary of how keys are
assigned within JDeveloper and the lists of accelerator keys provided for commands:
● Navigating JDeveloper with Keystrokes

● Default Keymapping
● Classic Keymapping
● Emacs Keymapping
● Virtual C++ Keymapping
The following menu and toolbar functionality is provided through keyboard access:
● Users can navigate to and invoke all menu items

● All toolbar functions are accessible through menu items, including the Navigator toolbar
● All menus and menu items have unique and functioning mnemonic keys
● All context menus within the Navigator and Code Editor can be invoked
● Frequently used menu items have unique and functioning accelerator keys
The following functionality is available in JDeveloper IDE windows, which include the Navigator,
Structure Pane, Code Editor, Property Inspector, Constraints, Profilers, Debugger windows,
Help windows, Log window and BC4J Tester. Users can:
● Navigate between all open windows, to all nodes within a window or pane, and between
tabs in a window
● Set focus in a window or pane
1-13
● Invoke all controls within a window or pane, and perform basic operations
● Navigate and update properties in the Property Inspector
● Use Code Insight and Code Templates in the Code Editor
● Invoke context sensitive help topics, navigate to and open all help topics, and navigate
between the Contents, Index and Search tabs
● Open, close, dock, undock, minimize, restore and maximize the applicable JDeveloper
window
The following functionality is available in JDeveloper dialogs and wizards:
● Users can navigate to and invoke all controls within all wizards and dialogs
● The order in which the Tab key causes focus to flow is consistent and logical
● Mnemonic keys are provided for controls where appropriate
Navigation and controls are available with runtime applications, which include all runnable files
that are produced with JDeveloper, including Java applications, HTML applications, applets,
JSPs, Servlets, BC4J applications and JClient applications. With runtime applications, users
can:
● Navigate to all controls within all runtime applications

● Invoke all controls within all runtime applications
Screen Reader Readability
Here is a summary of JDeveloper's screen readability, when it is used with a screen reader.
When used with menus and toolbars:
● All menus and menu items are read

● All toolbar items, including the Navigator toolbar items, are read
● The hint text on all Toolbar items is read
When used with JDeveloper IDE windows:
● All open windows are read
1-14
● All components within each window, including tabs, are read
● Status text at the bottom of the JDeveloper IDE, and within the Code Editor, is read
When used with dialogs and wizards:
● All controls within all wizards and dialogs are read

● Hint text is read
When used with runtime applications:
● All controls within all runtime applications are read
Reading Text in a Multi-line Edit Field
To have the text in a multi-line edit field read by a screen reader, you can select text by holding
down the Shift key while moving the cursor either up or down with the Arrow keys, depending
on the initial cursor position. For example, on the View Object reentrant wizard Query panel,
the cursor is initially positioned at the end of the SQL statement, and you will need to use the
Up Arrow key to select the text to be read
Flexibility in Font and Color Choices
The user interface in JDeveloper improves usability for people who are visually impaired by
offering flexibility in color and font choices. The following font and color features are included:
● Users can specify both the font and the size in which the font displays for editors
● All features of the product have black text on a white or gray background
● Colored text, underlining or images are never used as the only method of conveying
information
No Audio Only Feedback
In JDeveloper, there is no situation in which the only feedback a user receives is audible
feedback. All audible feedback is accompanied by a visual indicator. For example, a prompt
accompanies the bell sound that occurs when an error or illegal action has taken place.
No Dependency on Blinking Cursor and Animation

1-15
JDeveloper makes minimal use of a blinking cursor and animation:
● No features in JDeveloper use blinking indicators, with the exception of the cursor in the
Code Editor
● No features rely on animated sequences
Screen Magnifier Usability
The JDeveloper user interface works well with screen magnifiers. All features of the product
can be magnified by a screen magnifier.
Recommendations for Customizing JDeveloper
JDeveloper provides a number of customization features that enable users to specify their
requirements for keyboard usage, display attributes of the IDE, and timing where appropriate.
All customization features are organized within the Preferences dialog. For maximum usability
and to accommodate your needs, you should consider changing any of the following from the
defaults to a more usable customized setting.
● Accelerators specified for menus, commands and actions

● Look and Feel of the IDE
● Font size and colors in editors
● Colors used for syntax highlighting in editors
● Display of line numbers in editors
● Timing that determines when Code Insight is invoked
● Column layout and types of information in the Debugger
Customizing the Accelerators Keys
You can add and change the default accelerator keys for JDeveloper in the Tools | Preferences
| Accelerators panel. You can also load preset keymaps that you are accustomed to using.
Please refer to the following topics for the procedure to modify the accelerator keys:
● Defining Custom Accelerators for the IDE

● Loading Preset Keymaps for the IDE
1-16
Changing the Look and Feel of the IDE
You can change the default look and feel for JDeveloper in the Tools | Preferences |
Environment panel. The look and feel determines the display colors and shapes of objects like
menus and buttons. Please refer to the following topic for the procedure to change the look and
feel of the IDE:
● Changing the Look and Feel of the IDE
Customizing the Fonts in Editors
You can change the font and font size that displays is editors in the Tools | Preferences | Editor
| Fonts panel. Please refer to the following topic for the procedure to customize the fonts in
editors:
● Setting Fonts for the Code Editor
Customizing the Syntax Highlighting
You can change the font style, as well as the foreground and background colors used in syntax
highlighting within the code editor in the Tools | Preferences | Editor | Syntax Colors panel.
Please refer to the following topic for the procedure to customize the syntax highlighting:
● Defining Syntax Highlighting for the Code Editor
Displaying Line Numbers in Editors
You can display or hide line numbers in the Code Editor in the Tools | Preferences | Editor |
Display panel. Please refer to the following topic for the procedure to display line numbers:
● Setting Display Options for the Code Editor
Changing the Timing for Code Insight
You can specify the number of seconds that Code Insight is delayed, or disable Code Insight in
the Tools | Preferences | Editor | Code Insight panel. Please refer to the following topic for the
1-17
procedure to change Code Insight defaults:
● Customizing Code Insight Options for the Code Editor
Specifying the Columns in the Debugger
You can choose the columns and types of information that display in the Debugger in the Tools
| Preferences | Debugger panels. Please refer to the following topic for the procedure to change
Debugger options:
● Setting Preferences for the Debugger Windows
Highly Visual Features of JDeveloper
JDeveloper includes two features that are highly visual, and these features have equivalent
functionality that is available to people who are blind or visually impaired:
● The UI Editor. The Code Editor provides equivalent functionality, as the UI can be
completely designed and coded in the Code Editor.
● The Component Palette. The Code Editor provides equivalent functionality, as elements
and tags that can be selected from the Component Palette can also be entered in the
Code Editor.
JDeveloper also includes two features that are entirely visual, and these features do not have
equivalent functionality that is available to people who are blind or visually impaired. They also
do not provide keyboard access. However, many properties of existing model elements can be
set using dialogs, which are accessible from the Navigator.
● The Class Modeler

● The Activity Modeler
1-18
Navigating JDeveloper with Keystrokes
You can accomplish any task in JDeveloper using the keyboard as you can using the mouse.
The accelerators defined in the Java Look and Feel guidelines (listed at
http://java.sun.com/products/jlf/ed1/dg/appendix.htm) provide the base set for JDeveloper. The
various keymappings available in JDeveloper are then overlaid upon this base set. If the same
accelerator exists in both the Look and Feel guidelines and the JDeveloper keymap, the
JDeveloper keymap prevails. If an accelerator defined by the Look and Feel guidelines does
not appear in a JDeveloper keymap, then it is the original Look and Feel definition that remains
in effect when the keymap in question is enabled.
At any given time, then, the accelerators enabled in JDeveloper depend upon the interaction of
the currently enabled keymap with the Java Look and Feel guidelines. When you first open
JDeveloper, the default keymap is enabled. You can change this keymap whenever you wish,
and within each keymap, you can customize any of the accelerator assignments that you would
like. Note that any customized accelerators you create in a keymap are not retained when
another preexisting keymap is activated (or even if the same keymap is reloaded).
To load preexisting keymaps, view current accelerator assignments within a keymap, and
customize those assignments, you will need to open the Preferences dialog. To open the
dialog, choose Tools | Preferences (or on the keyboard, press Alt+T+P) from the main menu
and then, using the arrow keys in the lefthand pane, navigate to the Accelerators node. For
details on working with the dialog, with the Accelerators page displayed, click Help (or on the
keyboard press H).
Related topics
Working with Keymaps in the IDE
Classic Keymapping
Default Keymapping
Default CDE Keymapping
Default KDE2 Keymapping
Emacs Keymapping
Visual C++ Keymapping
1-19
Ways to Migrate Projects to Oracle9i JDeveloper
These topics contain procedures for migrating projects to Oracle9i JDeveloper from other
versions and installations of JDeveloper.
● Migrating JDeveloper 3.2.x Projects to Oracle9i JDeveloper

● Migrating Oracle9i JDeveloper Beta Projects to Oracle9i JDeveloper Production
● Migrating Oracle9i JDeveloper Release Candidate Projects to Oracle9i JDeveloper
Production
● Migrating Projects Between Different Installations of Oracle9i JDeveloper
1-20
Migrating JDeveloper 3.2.x Projects to Oracle9i
JDeveloper
Note: If you have Enterprise JavaBeans you want to migrate from JDeveloper 3.2.3 to Oracle9i
JDeveloper, see Migrating EJBs from 3.2.3 to 9i.
Note: If you are migrating a DAC application, see About JClient Compatibility with DAC.
Note: If you are migrating from JDeveloper 3.2.x on Windows NT to Oracle9i JDeveloper on
Solaris, you must first migrate to Oracle9i JDeveloper on Windows NT and then migrate to
Solaris.
Otherwise, you can import JDeveloper 3.2.x projects into Oracle9i JDeveloper by following
these steps.
To migrate JDeveloper 3.2.x projects to Oracle9i JDeveloper:
1. Import JDeveloper 3.2.x connections and source files into Oracle9i JDeveloper.
2. Redefine any libraries you created in JDeveloper 3.2.x.
3. Update business components projects.
4. If you use JSPs with business components datatags, find all instances of the
<jbo:ApplicationModule> tag. Make sure the id attribute of this tag contains no
periods, and change it if it does. For example, you could change
<jbo:ApplicationModule id="mypackage.MyAppModule"
configname="mypackage.MyAppModule.MyAppModuleLocal" />
to
<jbo:ApplicationModule id="MyAppModule"
configname="mypackage.MyAppModule.MyAppModuleLocal" />
5. If you have to change any <jbo:ApplicationModule> tag id attributes, change the
appid attributes of <jbo:DataSource> tags to match.
6. If you use a business components JSP with the <jbo:RowsetNavigate> tag, be
aware that the functionality of this tag has changed. See About Changes to the
RowsetNavigate Tag for more information.
7. If you use interMedia domains, change calls of the form
1-21
domain.getLoader().setFileName(name);
to
domain.setContentSource(new OrdFileSource(name));
8. Update XSQL projects.
9. If you use XML Messaging with Advanced Queuing, be aware that the AQ API has
changed. See About Changes to the AQ API for more details.
10. If your project uses servlets (not including Business Components JSPs), add the Servlet
RT or JSP RT library.
11. Test your projects. If you receive a JBO-26061: Error while opening JDBC
connection and/or a JBO-30003: Error (failed to check out an
application module), make sure your connection has Deploy Password selected in
the connection wizard.
12. Recreate deployment profiles for your projects.
1-22
Importing JDeveloper 3.2.x Connections and Files
into Oracle9i JDeveloper
1. Open JDeveloper 3.2.x.
2. Choose Tools | Connections to open the Connections Manager.
3. Click Export to open the Export Connection Descriptors dialog. Export all the
connections used by your project. If you need further assistance with this dialog, click
Help.
4. Open your project.
5. Close all source views displaying source code from your project.
6. Choose File | Save All.
7. Choose Project | Project Properties.
8. Note the source directories (in the Source Root Directories field) and the HTML root (in
the HTML Root Directory field).
9. Close JDeveloper 3.2.x.
10. Copy the source root directories and HTML root directory (from step 8) into your Oracle9i
JDeveloper environment.
Note: It is important to preserve the relative path from the source root directories to the
HTML root. For example, suppose your source root directory is
/oracle/JDev3.2.3/work/myprojects and your HTML root is
/oracle/JDev3.2.3/html/myhtml. The relative path from the source root directory
to the HTML root is ../../html/myhtml. Therefore, if you copy the source root
directory to /oracle/JDev9i/importedsource, you must copy the HTML root
directory to /oracle/html/myhtml to preserve this relative path.
11. If your projects reference any files outside of these directories, those files may need to
be copied so that they have the same relative path to your source root directory.
12. Open Oracle9i JDeveloper.
13. In the Navigator, expand the Connections node.
14. Right-click the Database node and choose Import Connections.
15. In the Import Connection Descriptors dialog, click Browse.
16. Locate your JDeveloper 3.2.x connections in <jdev32x_home>/bin.
17. Select the connections you want to import, and click OK.
18. Choose File | Open.
1-23
19. Browse to <jdev9i_home>/myprojects and open your workspace.
1-24
Updating JDeveloper 3.2.x Business Components
Projects for Oracle9i JDeveloper
Before you complete this procedure, make sure you have imported your connections and
source files into Oracle9i JDeveloper.
To update business components projects for Oracle9i JDeveloper:
1. If you get a ClassCastException at runtime in your migrated project, you may have to
make changes to your code. SequenceImpl.getData() is no longer castable to an
Integer. Instead, you must cast it to a Long.
2. If you used dollar signs in your classnames, JDeveloper will confuse them with inner
classes. For example, JDeveloper will confuse a class named Dom$Currency with an
inner class Currency inside the class Dom. If you have dollar signs in your class names,
change them.
Section 3.8 of the Java Language Specification says that dollar signs are allowed in
class names but recommends that they be used only in machine-generated code.
Because the Java compiler uses the dollar sign in the machine-generated class files it
produces to represent inner classes, using dollar signs in your own application class files
is not advisable.
3. If your project uses the JBO Runtime library and the XML Parser Version 2 library,
remove the XML Parser Version 2 Library.
The XML Parser Version 2 library has been merged into the JBO Runtime library, and
leaving both on your classpath could cause conflicts.
4. Choose Project | Build.
5. Create a deployment profile for your business components and deploy.
1-25
Migrating XSQL Projects from JDeveloper 3.2.x to
Oracle9i JDeveloper
1. Add the XML SQL Utility library to your project.
2. In the Navigator, select XSQLconfig.xml.
3. Choose File | Remove from IDE.
4. In your file system, copy <jdev9i_home>/jdev/system/XSQLConfig.xml to your
project source directory in Oracle9i JDeveloper.
5. Choose File | Open.
6. Navigate to the new copy of XSQLConfig.xml.
7. Select XSQLConfig.xml and click Open.
8. Add any specific code you added to XSQLConfig.xml in JDeveloper 3.2.x.
1-26
Creating Oracle9i JDeveloper Deployment Profiles
for Migrated JDeveloper 3.2.x Projects
Oracle9i JDeveloper deployment profiles are different from JDeveloper 3.2.x profiles. The
following table indicates the best migration choice for JDeveloper 3.2.x profiles.
Note: Oracle9i JDeveloper will automatically create deployment profiles for web applications.
JDeveloper 3.2.x Deployment Profile Corresponding Oracle9i JDeveloper Deployment Profile

Classes and Stored Procedures to Oracle8i Stored Procedures
Java Classes to Oracle8i Loadjava
Oracle9i JDeveloper will automatically create a deployment
Web application
profile.
Not supported, but see Deploying a CORBA Server Object to
CORBA Object to Oracle8i
VisiBroker
CORBA Object to VisiBroker CORBA Object to VisiBroker
Not supported, but see Creating and Deploying a J2EE EJB
Module to OC4J or Creating and Deploying a J2EE EJB Module
EJB to Oracle8i
to WebLogic. You can also manually deploy to any J2EE-
compliant EJB server.
Simple archive Simple archive
1-27
Migrating Oracle9i JDeveloper Beta Projects to
Oracle9i JDeveloper Production
1. If your project contains XSQL pages, remove these pages from the project in Oracle9i
JDeveloper Beta by choosing File | Remove from IDE.
You will add these files back in later. Attempting to directly migrate XSQL files from the
Beta to the Production release can cause JDeveloper to hang.
2. Follow the instructions for migrating between installations of Oracle9i JDeveloper.
3. If your project contained XSQL files:
❍ In Oracle9i JDeveloper Production, in the Navigator, select your project node.
❍ Choose File | Open.
❍ Navigate to the location of your XSQL files.
❍ Select your XSQL files and click Open.
4. If you are migrating a Business Components JSP application, update your JSP projects.
1-28
Updating Oracle9i JDeveloper Beta JSP Projects for
Oracle9i JDeveloper Production Release
JSP projects that use business components data tags or component tags need to be updated
before they will work in Oracle9i JDeveloper Production Release.
To update JSP projects:
1. Replace <project_directory>/public.html/Web-inf/lib/datatags.jar
with <jdev_home>/bc4j/lib/datatags.jar.
2. If you use <jbo:DefinitionIterate> tags, replace them with
<jbo:AttributeIterate> tags.
3. If you use <jbo:FireEvent> tags, replace them with <jbo:FormEvent> tags.
4. If you use <jbo:OnEvent> tags, check to see if they have a target attribute. If so,
replace this attribute with ViewObject="VO", where VO is the name of your target view
object.
5. If you use component tags:
❍ Copy <jdev_home>/multi/system/templates/common/tagcomp/*.jsp
to <project_directory>/public.html.
❍ Add a <jbo:DataSource> tag to every page that uses component tags. This tag
should specify the view object to be used as a datasource.
❍ If your component tags have the attributes appid and viewobject, remove
these attributes and replace them with datasource="DS", where DS is the name
of the datasource created in the <jbo:DataSource> tag above.
6. If you use any data tags that have a TargetUrl attribute, add a <jbo:DataHandler>
tag to each JSP called as a TargetURL. For example, if foo.jsp contains a tag with
attribute TargetURL="bar.jsp", you should add a <jbo:DataHandler> tag to
bar.jsp.
1-29
Migrating Oracle9i JDeveloper Release Candidate
Projects to Oracle9i JDeveloper Production
1. Follow the instructions for migrating between installations of Oracle9i JDeveloper.
2. If you use business components deployed as CMT Service beans, be aware that the
functionality of oracle.jbo.server.ejb.sb.ContainerManagedServiceBean has changed.
See About Changes to CMT Service Beans for more information.
1-30
About Changes to CMT Service Beans
The implementation of business components service beans with container-managed
transactions has changed since the Oracle9i JDeveloper Release Candidate. These changes
only affect business components deployed as service beans with container-managed
transactions. They do not affect application module session beans (either CMT or BMT), and
they do not affect BMT service beans.
● When you end a transaction (by calling UserTransaction.commit() or

UserTransaction.rollback()), the database connection is automatically dropped.
If you do not want this behavior, override disconnectFromDataSource() with an empty
method in your generated service bean class (<ApplicationModule>Server.java):
protected void disconnectFromDataSource() { }

● When you create your service bean, you must pass the name of the datasource into
ContainerManagedServiceBean.useDataSource().
● You can now use the method
ContainerManagedServiceBean.connectToDataSource() to connect to your
datasource at any time.
● You can now use the method ContainerManagedServiceBean.postChanges() to
post changes to the database at any time.
Related Topics
About Business Components Service Beans

About Container-Managed and Bean-Managed Transactions
Using Client-Demarcated Transactions
1-31
Migrating Projects Between Different Installations of
Oracle9i JDeveloper
1. Open the source installation of Oracle9i JDeveloper.
2. Export your database connections.
3. Close all source views.
4. Close the source installation.
5. Copy <source_home>/mywork to <destination_home>/mywork.
6. If your projects reference any files outside the mywork directory, those files may need to
be copied so that they have the same relative path to <destination_home>/mywork
as they had to <source_home>/mywork.
For example, if your projects reference a file in <source_home>/.., this file must be
copied to <destination_home>/...
7. Copy the following files from <source_home>/system to
<destination_home>/system:
jbo.properties
libraries.xml
server.properties
XSQLConfig.xml
8. Open the destination installation of Oracle9i JDeveloper.
9. Import and test your database connections.
1-32
Getting Started with JDeveloper
● Getting Started with JDeveloper
❍ Starting a New Programming Project
❍ About JDeveloper
■ About Workspaces
■ About Projects
■ About Project Paths
■ About Setting Project Properties
■ About Packages
■ About Libraries
■ About J2SEs
■ About Layouts
■ About Connections
■ About Code Insight
■ About Browse Symbol
❍ Managing Your Work Using Workspaces and Projects

■ Creating a New Workspace
■ Creating a New Project

■ Creating a New Empty Class
■ Opening an Existing Workspace or Project
■ Importing Existing Files into a New JDeveloper Project
■ Adding Existing Files to an Existing Project
■ Setting Default Project Properties
■ Setting Properties for Individual Projects
■ Setting the Java Source Paths for a Project
■ Setting the HTML Document Root for a Project

■ Setting the Output Path for a Project
■ Setting the Classpath for a Project
■ Including Libraries in a Project
■ Removing or Deleting Libraries from a Project
2-1
■ Setting Additional Classpath Values for a Project
■ Setting the Target JDK for a Project

■ Setting Project Configurations
■ Creating a New Project Configuration
■ Renaming a Project Configuration

■ Changing the Active Project Configuration
■ Deleting a Project Configuration
■ Browsing Files Through JDeveloper

■ Inspecting the Contents of an Archive in JDeveloper
■ Viewing an Image File in JDeveloper
■ Saving a Workspace or Project
■ Saving a File
■ Relocating a Workspace or Project
■ Unloading a Workspace, Project, or Other File from Memory
■ Removing a File from a Project
■ Removing a Project from a Workspace
■ Removing a Workspace
■ Permanently Deleting a Workspace, Project, or Other File
❍ Editing Source Code

■ Editing Source Code in JDeveloper
■ Editing Source Code with an External Editor

■ Editing Classes Visually with the Class Editor
■ Managing Editor Windows with the Document Bar
❍ Designing the User Interface for a Java Project

❍ Common Programming Practices in JDeveloper
■ Implementing a Java Interface
■ Overriding Methods in a Superclass

■ Moving or Renaming Java Classes
2-2
❍ Configuring Database Connections
■ Defining Database Connections
■ Editing Database Connections

■ Exporting Database Connections
■ Importing Database Connections
■ Opening and Closing Database Connections
■ Deleting Database Connections
❍ Printing Source Files

❍ Customizing the IDE
■ Changing the Look and Feel of the IDE
■ Arranging Windows in the IDE

■ Docking Windows in the IDE
■ Floating Windows in the IDE

■ Hiding and Reopening Windows in the IDE
■ Working with Navigators in the IDE

■ Creating a New Navigator
■ Changing Views in the Navigator

■ Docking and Undocking Navigators
■ Opening and Closing Navigators
■ Working with Layouts in the IDE

■ Defining Custom Layouts
■ Activating Defined Layouts

■ Disabling Editor Layout Preferences
■ Renaming Layouts
■ Removing Layouts
■ Customizing the Component Palette

■ Adding a Page to the Palette
■ Adding a Component to the Palette

■ Removing a Page from the Palette
■ Removing a Component from the Palette
2-3
■ Customizing the IDE Environment
■ Customizing the General Environment for the IDE
■ Working with Keymaps in the IDE

■ Loading Preset Keymaps for the IDE
■ Viewing Current Accelerator Assignments in Keymaps

■ Defining Custom Accelerators for Keymaps
■ Customizing the Code Editor Environment

■ Setting Tabs for the Code Editor
■ Setting Scrolling Options for the Code Editor

■ Setting Display Options for the Code Editor
■ Setting Fonts for the Code Editor
■ Defining Syntax Highlighting for the Code Editor
■ Customizing Code Insight Options for the Code Editor
■ Defining Undo Behavior for the Code Editor
■ Defining Code Completion Templates for the Code Editor
❍ Related Reference Topics

■ Classic Keymapping
■ Default Keymapping
■ Default CDE Keymapping
■ Default KDE2 Keymapping
■ Emacs Keymapping
■ Visual C ++ Keymapping
■ Regular Expressions
■ JDeveloper's Connection Requirements for Oracle's Type 2 Drivers (OCI)
2-4
Getting Started with JDeveloper
To get started with JDeveloper, you'll want to master certain basic tasks, tasks that are
fundamental to getting around in JDeveloper, and making it work for you, no matter what sort of
programming project you are undertaking.
Once you've mastered the basics, you'll be ready to move onto more specific procedures. Or, if
you already know how to work with JDeveloper, use its opening topic to jump directly to the
specific support you need for individual projects.
The topics here are organized by task. If you are new to JDeveloper, or want a more formalized and
linear introduction to its capabilities, you consider working through some of its tutorials as well.
Topic Title Topic Description
Starting a New Programming Project A supertopic. Provides links into the entire helpset
to get you the specific info you need, based on the
project you are developing, quickly. The potential
starting point for all your work.
About JDeveloper A grouping of foundational conceptual topics to

support procedures central to getting started.
These are topics designed to be consulted on an as-
needed basis or read through more thoroughly, as
best suits your needs.
Managing Your Work Using Workspaces and Everything you need to know to get started with
Projects JDeveloper workspaces and projects. Creating
them, importing them, setting their properties,
closing them, removing them, deleting them.
Editing Source Code Editing source files in the Code Editor. Editing
source files simultaneously with an external editor
and JDeveloper's Code Editor. Editing classes
using the Class Editor's visual interface. Opening,
closing, and moving through active editor windows
using the document bar.
Designing the User Interface for a Java Project The springboard into topics supporting the
development of a Java UI.
2-5
Common Programming Practices in JDeveloper Implementing a Java interface, overriding methods
in a superclass, moving and renaming Java
classes.
Configuring Database Connections Defining, importing and exporting, editing, opening,

closing, and deleting database connections.
Printing Source Files The title says it all.
Customizing the IDE Changing the look and feel of the UI, working with
the System Navigator, creating custom navigators,
creating and working with layouts, customizing the
Component Palette, customizing the IDE,
customizing the Code Editor.
Related Reference A grouping of specific and diverse reference topics

to support various procedures, normally consulted
on an as-needed basis.
Related topics
Tutorial: Building a Simple Java Application
2-6
Starting a New Programming Project
Regardless of the type of application you decide to create, you will need to use workspaces
and projects to manage your files. What you do from there depends upon the type of program
you are building.
There are typically many ways of accomplishing a given task in JDeveloper. Since this is an
overview, only a single approach is described. For more information on individual procedures,
see the documentation as noted. For more information on any window, wizard, or dialog while
working in JDeveloper, press F1 for context-sensitive help.
In this overview, you will find the basics for accomplishing these tasks:
● Working with existing files

❍ Importing existing files into a new project
❍ Working with files from source control
❍ Working with files hosted on a WebDAV server
● Creating a new programming project

❍ Creating a UML model
■ Modeling activities and workflow
■ Modeling Java classes or Business Components
❍ Creating J2EE Business Components

■ Creating Enterprise JavaBeans (EJB)
■ Creating Business Components for Java (BC4J)
❍ Creating an empty class

❍ Defining a user interface
■ Creating JavaServer Pages (JSP)
■ Creating servlets
■ Creating an XSQL application
■ Creating a UIX application
■ Creating a Java application
■ Creating a Java applet
2-7
Working with Existing Files
You can import existing files of any type from a variety of sources into a new project. If you
want to import files from source control or from a WebDAV server, you first need to configure
JDeveloper to work with your source control system or your WebDAV server.
Importing Existing Files into a New Project
In JDeveloper, you use workspaces and projects to organize the files you need for your
application. To effectively work with a file in JDeveloper, you will want to add it to a project.
Workspaces are used to manage one or more projects. Therefore, if you have existing files you
want to use in JDeveloper, you will need to have a workspace and a project.
To create a new workspace:
1. Choose File | New from the JDeveloper main menu.

2. In the New Gallery, select Projects from the list of categories, and double-click
Workspace in the list of items.
3. In the New Workspace dialog, enter the name and location of your new workspace, and
make sure the Add a New Empty Project checkbox is not selected.
To import existing files into a new JDeveloper project:
1. Select the workspace in the Navigator, and then choose File | New from the JDeveloper
main menu.
2. In the New Gallery, select Projects from the list of categories, and double-click Project
with Existing Source in the list of items.
3. Follow the steps of the wizard to create the project and locate the files you want to
import.
You can also import files into an existing JDeveloper project by selecting the project in the
Navigator and choosing Project | Add to <project name> from the JDeveloper main menu.
For more information, refer to Managing Your Work Using Workspaces and Projects.
Working with Files from Source Control
2-8
JDeveloper provides support for Oracle9i Software Configuration Manager (SCM), Rational
ClearCase, and Concurrent Versions System (CVS). To work with files managed by one of
these source control systems, you simply need to configure JDeveloper to use your source
control system. JDeveloper also allows you to work with any other source control system by
writing your own source control addin.
To configure JDeveloper for your source control system:
1. Choose Tools | Preferences from the JDeveloper main menu, and select the Source
Control node in the Preferences dialog.
2. Select your source control system and enter the required parameters.
If you are using Oracle9i SCM, the next step is to create a new SCM connection:
1. Select Oracle9i SCM in the Connections node of the Navigator.

2. Right-click and choose New Connection from the context menu. Follow the steps in the
wizard to complete the connection.
JDeveloper is now configured to use source control. For more information, refer to Using
Source Control Support.
Working with Files Hosted on a WebDAV Server
Web-based Distributed Authoring and Versioning (WebDAV) is an extension to HTTP which

allows users to collaboratively edit and manage files on WebDAV-enabled servers. You use
WebDAV connections in JDeveloper to work with files hosted on WebDAV servers in the same
way as you would work with files on the local file system.
Important: Before using WebDAV Connections in Oracle9i JDeveloper, you must first install
the WebDAV addin from the Oracle Technology Network website. For more information, refer
to the Oracle9i JDeveloper Installation Guide for your operating system.
To access a WebDAV server outside of a firewall, you will first need to configure your proxy
server:
1. Choose Tools | Preferences from the JDeveloper main menu, and select the Proxy
Server node in the Preferences dialog.
2. Fill in the details for your proxy server.
2-9
To configure JDeveloper as a WebDAV client:

2. In the New Gallery, select Connections from the list of categories, and double-click
WebDAV Connection in the list of items.
3. Follow the steps in the wizard to complete the connection.
JDeveloper is now configured to access files on the WebDAV-enabled server. For more
information, refer to Using WebDAV Support.
Creating a New Programming Project
There are many different approaches you can take to coding and many types of programming
projects you can create in JDeveloper. This topic describes some of the more typical uses of
JDeveloper and how to get started with various projects.
Creating a UML Model
JDeveloper supports the following types of UML diagrams: activity modeling and class
modeling.
Modeling Activities and Workflow
The Activity Modeler fully supports UML activity modeling, allowing you to model a process
usings states and flows. It also has powerful features that enable you to integrate your
applications through asynchronous messaging. Once you've created a new workspace and
project, you can add an activity diagram to your project and begin modeling.
To create a new workspace and project:

make sure the Add a New Empty Project checkbox is selected.
4. In the New Project dialog, enter the name and location of your new project.
2-10
To add an activity diagram to your new project:
1. Right-click the new project in the Navigator, and choose New UML Diagram from the
context menu.
2. In the New Gallery, double-click Activity Diagram in the list of items.
3. In the Create New Activity Diagram dialog, enter the detail for your new diagram or
accept the defaults and click OK.
You have now created an activity diagram. For more information, refer to Modeling Activities.
Modeling Java Classes or Business Components
The Class Modeler allows you to create UML class diagrams for Java classes and Oracle
Business Components for Java. You can use the Class Modeler to create models for new
classes, or you can reverse engineer a model from existing classes. A model can be fully
synchronized with code. Once you've created a workspace and project, you can add a class
diagram to your project and begin modeling.

To add a class diagram to your new project:
1. Right-click the new project in the Navigator, and choose New UML Diagram from the
context menu.
2. In the New Gallery, double-click Class Diagram in the list of items.
3. In the Create New Class Diagram dialog, enter the detail for your new diagram or accept
the defaults and click OK.
You have now created a class diagram. For more information, refer to Modeling Java Classes.
2-11
Creating J2EE Business Components
JDeveloper is a J2EE development environment with end-to-end support for developing,

debugging, and deploying J2EE applications.
Creating Enterprise JavaBeans (EJB)
Enterprise JavaBeans are server-side components used to represent core business functions.
JDeveloper provides a productive environment in which to develop, debug, and deploy EJBs.
Once you've created a workspace and project, you can add an EJB of any of the EJB types
defined in the EJB 1.1 specification to your project.

To add an EJB to your project:
1. With your new project selected in the Navigator, choose File | New from the JDeveloper
main menu.
2. In the New Gallery, select Enterprise JavaBeans from the list of categories, and double-
click the type of EJB you want to create in the list of items.
3. Follow the steps in the wizard to finish creating your EJB.
You have now created an Enterprise JavaBean. For more information, refer to Developing
Enterprise JavaBeans.
Creating Business Components for Java (BC4J)
To simplify the development of scalable, high-performance J2EE applications, JDeveloper

offers an open and extensible J2EE framework called Business Components for Java (BC4J).
BC4J is an object-relational mapping tool that implements Sun's J2EE design patterns, allowing
developers to quickly build sophisticated J2EE applications.
2-12
You can create Business Components based on the definition of existing tables or you can
create the Business Components first and use JDeveloper to create the tables for you. Once
you've created a workspace, you can use the JDeveloper wizards to help you create a project
for your Business Components.

make sure the Add a New Empty Project checkbox is not selected.
To add a Business Components project to your workspace:
1. Right-click the new workspace in the Navigator, and choose New Business Components
from the context menu.
2. Follow the steps in the wizard to finish creating your Business Components. If you have
not yet defined a connection for the database containing the tables you are building
Business Components for, you can do so in the wizard.
You have now created a Business Components for Java project. For more information, refer to
Developing Business Components.
JDeveloper also simplifies the development of BC4J clients. Once you've defined the Business
Components, you can create essentially any type of user interface to use those business
components. JDeveloper provides wizards to help you quickly create a JSP or Java user
interface for Business Components.
To create a JSP user interface for your Business Components:
1. First, make sure the Business Components have been compiled by right-clicking on the
project containing your Business Components and choosing Build Project from the
context menu.
2. Right-click the workspace containing the BC4J project in the Navigator, and choose New
Empty Project from the context menu.
3. Enter the details for the new project and click OK.
4. Select the new project in the Navigator and choose File | New from the JDeveloper main
2-13
menu.
5. In the New Gallery, select BC4J JSP from the list of categories, and double-click one of
the form types (for example, Browse and Edit Form) in the list of items.
6. Follow the steps in the wizard to finish creating your JSP.
You have now created a JSP application for your Business Components. For more information,
refer to Working with Data-Bound BC4J JSP Pages.
To create a Java application or applet user interface for your Business Components:
1. First, make sure the Business Components have been compiled by right-clicking on the
project containing your Business Components and choosing Build Project from the
context menu.
2. Right-click the workspace containing the BC4J project in the Navigator, and choose New
Empty Project from the context menu.
3. Enter the details for the new project and click OK.
4. Select the new project in the Navigator and choose File | New from the JDeveloper main
menu.
5. In the New Gallery, select JClient Objects from the list of categories, and double-click
JClient Form in the list of items.
6. Follow the steps in the wizard to finish creating your JClient application or applet. Note
that if you have not yet created a JClient data model for the Business Components, you
can do so in the wizard.
You have now created a JClient application or applet for your Business Components. For more
information, refer to Working with JClient Applications.
Creating an Empty Class
You may want to create a new class and add it to your project so that you can define the
functionality of that class from scratch. Once you've created a workspace and project, you can
add a class to the project and begin defining the behavior of that class.

2-14
To add an empty class to your project:
1. Right-click the new project in the Navigator, and choose New Class from the context
menu.
2. Fill out the details for your new class in the New Class dialog and click OK when finished.
You have now created an empty class. For more information, refer to Creating a New Empty
Class. To help you define fields, methods and events for the class, you may want to use the
Class Editor to visually edit the class definition.
Defining a User Interface
JDeveloper simplifies the development of many types of user interfaces.
Creating JavaServer Pages (JSP)
JavaServer Pages run on a web server and dynamically generate content (usually HTML) for
clients. JDeveloper provides rich support for developing, debugging and deploying JSPs. Once
you've created a workspace and project, you can add a JSP to the project and begin defining
the behavior of that JSP.

To add a JSP to your project:
2-15
main menu.
2. In the New Gallery, select Web Objects from the list of categories, and double-click JSP
in the list of items.
3. Enter the details for your new JSP and click OK.
You have now created a JavaServer Page. For more information, refer to Working with JSP
Pages. You can also create databound JSP pages.
To add elements to your JSP page:
1. Make sure the Component Palette is displayed by selecting View | Component Palette
from the JDeveloper main menu.
2. In the JSP editor, place the cursor at the position where you want the JSP tag to be
added.
3. Click the tag you want to add in the Component Palette, and fill in the details in the
resulting dialog.
Creating Servlets
Java servlets run on a web server and dynamically generate content (usually HTML) for clients.
JDeveloper provides rich support for developing, debugging and deploying servlets. With
servlets, unlike JSP pages, all the content you wish to generate for the client is embedded in
Java code. Once you've created a workspace and project, you can add a servlet to the project
and begin defining the behavior of that servlet.

To add a servlet to your project:
2-16
main menu.
2. In the New Gallery, select Web Objects from the list of categories, and double-click HTTP
Servlet in the list of items.
3. Follow the steps in the wizard to complete your new servlet.
You have now created a servlet. For more information, refer to Working with Java Servlets.
Creating an XSQL Application
XSQL servlets offer a simple and productive way to get XML in and out of the database. Using
simple scripts developers can generate simple or complex XML documents, apply XSL
stylesheets to generate any text format, and parse XML documents and store the data in the
database. XSQL pages can also access data via Oracle Business Components Java. Once
you've created a workspace and project, you can add an XSQL page to the project and begin
defining the behavior of that XSQL page.

To add an XSQL page to your project:
main menu.
2. In the New Gallery, select Web Objects from the list of categories, and double-click
XSQL in the list of items.
You have now created an XSQL page. For more information, refer to Working with XSQL
Servlets.
To add elements to your XSQL page:
2-17
1. Make sure the Component Palette is displayed by choosing View | Component Palette
2. In the XML editor, place the cursor at the position where you want the XSQL tag to be
added.
resulting dialog.
Once you've defined your XSQL page, you may want to create an XSL stylesheet so that you
can transform the XML for clients.
To add an XSL stylesheet to your project:
main menu.
2. In the New Gallery, select Web Objects from the list of categories, and double-click XSL
in the list of items.
3. Once you have defined the XSL stylesheet, apply the stylesheet to an XSQL page by
making the appropriate reference to the stylesheet in the code of the XSQL page.
Creating a UIX Application
Oracle User Interface XML (UIX) is a set of technologies that constitute a framework for
building web applications based on the Oracle Browser Look and Feel. You can use
JDeveloper to build UIX applications directly in XML, or to build JSP pages with tags to invoke
UIX components. UIX applications can be used to access data via Oracle Business
Components for Java. Once you've created a workspace and project, you can add a UIX page
to the project and begin defining the behavior of that UIX page.

2-18
To add an XML-based UIX page to your project:
main menu.
2. In the New Gallery, select UIX XML from the list of categories, and double-click UIX with
Header, Footer, and Navigation in the list of items.
3. Follow the steps in the wizard to complete your new UIX XML page.
You have now created a UIX XML page. For more information, refer to Working with UIX XML
and UIX JSP Pages.
To add a JSP-based UIX page to your project:
main menu.
2. In the New Gallery, select UIX JSP from the list of categories, and double-click Starter
Form in the list of items.
You have now created a UIX JSP page. For more information, refer to Working with UIX XML
and UIX JSP Pages.
To add elements to your UIX JSP page:
1. Make sure the Component Palette is displayed by selecting View | Component Palette
2. In the JSP editor, place the cursor at the position where you want the UIX JSP tag to be
added.
resulting dialog.
Creating a Java Application
A Java application is a Java class with a main() method. It typically runs in the VM on the
client machine. Once you've created a workspace and project, you can add a Java application
to the project and begin defining the behavior of that application.
2-19
To add an application to your project:
main menu.
2. In the New Gallery, select Objects from the list of categories, and double-click
Application in the list of items.
3. In the New Application dialog, enter the details for your new application and click OK.
4. If you chose to add a Frame to your application, enter the details for the Frame and click
OK.
You have now created a Java application. For more information, refer to Developing Java GUI
Clients.
Creating a Java Applet
A Java applet is a Java class which extends javax.swing.JApplet or java.awt.Applet.

It typically runs in the VM provided by a web browser (or a plug in to the browser). Once you've
created a workspace and project, you can add a Java applet to the project and begin defining
the behavior of that applet.

2-20
To add an applet to your project:
main menu.
Applet in the list of items.
3. In the New Applet dialog, enter the details for your new applet.
You have now created a Java applet. For more information, refer to Working with Applets.
Once you have defined your applet, you will need to create an HTML page to launch the applet
and also to allow you to test the applet in JDeveloper.
To create an applet HTML page:
main menu.
Applet HTML in the list of items.
3. Follow the steps in the wizard to complete the applet HTML page.
Related topics
Compiling with JDeveloper

Compiling from the Command Line or Shell
Debugging Java Programs
Remote Debugging
2-21
About JDeveloper
The following topics will introduce you to fundamental JDeveloper concepts and functionality:
● About Workspaces
● About Projects
● About Project Paths
● About Setting Project Properties
● About Packages
● About Libraries
● About J2SEs
● About Layouts
● About Connections
● About Code Insight
● About Browse Symbol
Related topics
2-22
About Workspaces
In a sense, what a project is to its group of related files, a workspace is to a group of related
projects. Grouping your files by workspace and project enables you to sort your work logically
and hierarchically.
Just as you can display several projects at one time, so you can display several workspaces.
You can "tear off" workspaces into separate navigator windows, should you wish, or leave them
all displayed in the default System Navigator. Closing a workspace or project unloads those
files from memory. Removing a workspace or project from the IDE can help reduce clutter
when you are not working with a given set of files. Removing files from the IDE does not delete
them from where they reside. It only affects whether or not they are displayed in the Navigator.
The listing of files for a given workspace is stored in the workspace file, the .jws file in the
Navigator that acts as parent node for all the contained projects. You don't edit these
workspace files directly. Rather, whenever you save the files in your workspace, all of the
current open files are stored for you. Note that saving the .jws file is not the same as saving
all the files (choosing Save All) within the workspace.
Workspaces and packages also define where and how the files within a project are stored.
Related topics
About Projects
About Project Paths
About Packages
Managing Your Work Using Workspaces and Projects

Creating a New Workspace
Creating a New Project
2-23
About Projects
A project is a logical container for a set of files that define a JDeveloper program or portion of a
program. A project might contain files representing different tiers of a multi-tier application, for
instance, or different subsystems of a complex application. These files can reside in any
directory and still be contained within a single project.
All of the projects within a workspace are normally displayed below that workspace. You can
"tear off" workspaces, or even projects, into separate navigator windows, should you wish, or
leave them all displayed in the default System Navigator. Closing a workspace or project closes
all open editors or viewers for files in that workspace or project and unloads the files from
memory. Removing a workspace or project from the IDE can help reduce clutter when you are
not working with a given set of files. Removing files from the IDE does not delete them from
where they reside. It only affects whether or not they are displayed in the Navigator.
JDeveloper has the capability of recognizing many different file types, displaying each in its
appropriate viewer or editor when you double-click the file.
When adding a project to a workspace, you can choose to:
● Create a new project, with specific objects and attributes you define
● Create a new empty project, which inherits default project properties
● Open an existing set of files from outside JDeveloper into a new project
As soon as you create a new project or open an existing one, it is added to the workspace
selected.
Information about each project is stored in its project file, the .jpr file in the Navigator that acts
as parent node for all the files within the project. This .jpr file contains a listing of all the files
within the project, as well as all the settings for that project. When you set default project
settings for all newly created projects or alter those settings for an existing project, the
information is captured and stored in the .jpr file.
JDeveloper uses the information in the project file whenever you load, save, or build a project
and, in some cases, when you use a wizard. You'll never need to edit a project file directly: as
soon as you save any changes made after using the JDeveloper development environment to
add files or remove files, or to modify project settings, the .jpr file is automatically updated.
Workspaces and packages also define where and how the files within a project are stored.
2-24
Related topics
About Workspaces
About Project Paths
About Packages
About Setting Project Properties

2-25
About Project Paths
There are three paths for your Java files: the Java source path, the output root directory, and
the run/debug working directory. The Java source path is where all your source (.java) files
will be generated. The output root directory is where all the byte-compiled (.class) files will be
kept. The run/debug working directory is where temporary files needed for running and
debugging will be placed.
By default, JDeveloper stores all your files in a directory named mywork. In a single user
Windows environment, the mywork directory is located in the <JDEV_HOME>/jdev directory.
In a multiuser environment, it is located in a user-specific directory. Within mywork, project files
are grouped by project, with a src folder for all .java files and a classes folder for all
.class files. Package directories are preserved within the src and classes directory trees.
You can choose to store your files anywhere else on your machine or on a remote file system,
as long as you specify the project source path (for the .java files) and the output directory (for
the .class files) for the project or projects in question in the appropriate project setting
dialogs. Use the Default Project Settings dialog when the location you specify applies to all
projects. Use the Project Settings dialog when the location applies only to files within a given
project. If you redirect JDeveloper to HTML or HTML-based files, keep in mind that the HTML
root directory contains everything that needs to be accessible to the design-time web server.
Each file in a project is stored with either a relative or an absolute path to the location of the
project, as needed, which is recorded in the .jpr. When the project files are under the project
directory, if you move the entire project directory, JDeveloper will still be able to find files in the
project using the relative paths already designated.
You can specify multiple source root directories for a project. Typically you will do this when
you are working with a project that uses an existing source structure. But when JDeveloper
creates new files for this project, it uses the first entry in the source path to determine the
location for the new file.
Related topics
About Projects
About Packages
2-26
2-27
The project settings you specify in the Default Project Settings dialog apply to all subsequent
projects you create across workspaces. Those you specify in the Project Settings dialog apply
only to the current project.
When setting project-wide properties, if you change the option settings, you should fully
rebuild your packages or your entire project, and not just make them. The project options are
applied to any class being rebuilt, outside as well as inside the project tree. For example, if you
set obfuscation on some classes, compile those classes in one project, and then in another
project reference the same files without obfuscation, by doing a rebuild all, you will
unobfuscate them.
Related topics
About Projects
About Project Paths
Setting Default Project Properties

Setting Properties for Individual Projects
2-28
About Packages
Java uses packages as a mechanism for organizing classes. Related classes are usually
grouped together into a package, and related packages are themselves grouped together.
While Java does not require any particular association between directories and packages for
source files, JDeveloper assumes that source files will be located in directories that matcht the
packages of the classes in the files. If the directory structure does not match the package
structure, JDeveloper may not be able to correctly locate the source files when debugging or
browsing for symbols.
Related topics
About Projects
About Workspaces

2-29
About Libraries
JDeveloper uses libraries to encapsulate related classes. Each library can include a class path,
containing the class files associated with the library; a source path, containing the source files
corresponding to the library's classes; and a doc path, containing the Javadoc files for the
classes.
Libraries are provided for the various APIs and technologies installed with JDeveloper. These
libraries are defined as system libraries. System libraries are shared by all users of an install.
New libraries can be created as either system libraries or user libraries. User libraries are not
shared between users. Only the current user has access to the definitions. User libraries can
override system libraries—if a library with the same name exists as both a system and a user
library, JDeveloper will use the user library.
Related topics
Setting the Classpath for a Project

Including Libraries in a Project
Removing or Deleting Libraries from a Project
2-30
About J2SEs
JDeveloper uses J2SE definitions to describe an installed J2SE environment. This environment
can be either a JRE or an SDK. Note that if you are using a JRE, some features may not be
available. Every JDeveloper project uses a J2SE definition to determine what version of the
Java API to compile and run with.
Each J2SE definition encapsulates a Java executable, used for launching programs; a
classpath, containing the classes available within the J2SE environment; a source path,
containing the source files associated with the J2SE classes; and a doc path; containing the
Javadoc files for the J2SE classes.
JDeveloper creates a J2SE definition for the J2SE environment being used to run JDeveloper.
By default, this definition is used by all new projects. However, additional definitions can be
created from any available J2SE. These new definitions can be created in either the user
libraries or the system libraries. In a multiuser environment, J2SE definitions created in the user
libraries are user specific, while ones created in the system libraries are shared by all users.
Related topics
Setting the Target J2SE for a Project
2-31
About Layouts
Layouts are a feature of JDeveloper that enable you to arrange your work area as best suits
your habits, to save those arrangements for different situations, and to move fluidly between
them.
Design and Debug Modes
There are two modes of overall layout design in JDeveloper: Design mode and Debug mode.
In Design mode, layouts can be associated with editors. While working in Design mode, you
can choose to:
● Use the preferred layouts that individual editors are provided with
● Rearrange those preferred layouts to suit yourself
● Ignore layout changes between editors altogether and work within one current layout
(which remembers any changes you make), regardless of which editor is open
When editor preferences are in force, an editor without a preferred layout uses the generic
Design layout.
In Debug mode, layouts are associated with debugging tasks. While working in Debug mode,
you can use the originally defined preferred layout or design your own custom layouts.
Creating Layouts
In Design mode, you can create layouts based upon the editor that is open. In Debug mode,
you can create them based upon the specific debugging task. To use a custom layout
automatically, you must then activate it. In Design mode, although you can develop as many
layouts for each editor as you would like, you can activate only one per editor at a time. In
Debug mode, although you can develop as many layouts as you would like, based upon the
different debugging tasks you are engaged in, you can activate only one layout at a time.
In Design mode, once you have changed an editor's preferred layout, you can easily return to
its original out-of-the-box preferred layout should you wish. If you have never activated a new
layout, all editors in Design mode that have preferred layouts are automatically using those
originally defined preferences. Those without a preferred layout (the Code Editor, for instance)
are using the generic Design mode.
2-32
In Debug mode, to redefine the preferred layout, you must first create the new custom layout
and then activate it. If you have never activated a new layout for this mode, the original out-of-
the-box Debug layout applies.
Related topics
Working with Layouts in the IDE
2-33
About Connections
You create and manage your connections through the Connection Wizard and store them
under the Connections node in the System Navigator. All defined connections to external data
sources are stored under this node. All defined connections are accessible to any workspace or
project.
When you delete a connection, JDeveloper does not warn you that project may be dependent upon
it. For this reason, it is best to use caution when deleting connections.
Connection Descriptor Properties Location
The file system location for the connection descriptor definition information is
<JDEV_HOME>/system/IDEConnections.xml
where JDeveloper is the root directory in which JDeveloper is installed.
Connection Properties Deployment
A connections.xmlfile is included with JDeveloper deployments. This file contains the

connection information necessary for deployment and the runtime connection execution.
The Deploy Password checkbox in the Connection Wizard determines whether the password is
included in the deployed connections.xml file. Select the checkbox to add the password
information to the deployed connections.xml file. If this checkbox was not selected for the
deployed connection, a runtime user of that connection must enter a valid username and
password for the connection. Note that the password is stored in clear text on disk.
Related topics
Configuring Database Connections
About OC4J Data Sources
2-34
About Code Insight
Code Insight provides you with context-sensitive popup windows in the Code Editor which can
help you select class names, methods, and fields in your Java, JSP, HTML, and XML files.
Code Insight comes in two flavors: completion insight and parameter insight. Completion insight
provides you with a list of possible completions at the insertion point which you may use to auto-
complete Java code you are editing. This list is generated based on the code context found at
the insertion point. The contexts supported by completion insight are:
● Within package and import statements

● Within extends, implements, and throws clauses
● Within continue and break statements
● Within general code expressions
Parameter insight provides you with a listing of all possible methods that match the given name.
With each method is listed the parameter list that the method accepts.
You can enable or disable both completion and parameter insight, as well as set the time delay
for the popup windows, in the Code Insight page of the Preferences dialog. When you are
working in the Code Editor, the popup window for completion insight appears (with the delay
you define) once you type the period delimiter. You can also force its appearance. In the default
keymap, to force completion insight, press Ctrl-space. To force parameter insight, press Ctrl-
shift-space. You can change these accelerators in the Accelerators page of the Preferences
dialog.
If errors for the file appear in the Structure window, Code Insight may not work. If the class(es)
you are using are not in your project (that is, not on your classpath), Code Insight will not
appear. Please note that you may need to compile your src files in order for Code Insight to
have access to them.
Related topics
Customizing Code Insight Options
2-35
About Browse Symbol
Browse Symbol for Java allows you to jump immediately to the Java source code where the
identifier under the cursor is defined. If the source is not available, JDeveloper will "reverse-
engineer" the class file. You may browse imported classes and interfaces, member fields and
methods, and local variables. If you are browsing a method or constructor invocation, Browse
Symbol will resolve the types in order to determine the correct method or constructor
invocation.
To use Browse Symbol, right-click on the identifier you would like to browse and choose
Browse Symbol at Cursor. For instance, given the following code:
import javax.swing.JButton;
...
JButton b1 = new JButton();
...
b1.SetText ("OK");
evoking Browse Symbol at SetText brings up the source code for javax.swing.JButton,
with the @SetText() method displayed.
If the identifier cannot be browsed or if there is nothing at that cursor position, the Browse
command on the context-sensitive menu will be disabled. If Browse is activated but unable to
locate the appropriate location to jump to or if the identifier cannot be browsed due to access
restrictions (e.g. private members), the Code Editor's status bar will display a message
indicating so.
2-36
Managing Your Work Using Workspaces and
Projects
In JDeveloper, you use workspaces to organize the projects you'll use while developing your
programs. You use projects to organize the related files that together make up an application.
To begin organizing your work in JDeveloper, you'll typically want to know how to:
● Create a new workspace

● Create a new project
● Create a new empty class
● Open an existing workspace or project
● Import existing files into a new JDeveloper project
● Add existing files to an existing project
● Set default project properties
● Set properties for individual projects
● Browse files through JDeveloper
● Inspect the contents of an archive in JDeveloper
● View an image file in JDeveloper
● Save a workspace or project
● Save a file
● Relocate a workspace or project
● Close a workspace, project, or other file, unloading it from memory
● Remove a file from a project
● Remove a project from a workspace
● Remove a workspace
● Permanently delete a workspace, project, or other file
Related topics
2-37
Editing Source Code in JDeveloper
Editing Source Code with an External Editor
Designing the User Interface for a Java Project
About Workspaces
About Projects
2-38
In JDeveloper, you use workspaces to keep track of the projects (collections of related files)
you use while developing your application. You can have multiple workspaces open in the
Navigator, and an individual navigator for each workspace.
1. From the main menu, chooseFile | New or, with a workspace or project node selected,
right-click and choose New.
The New Gallery appears.
2. Select the Projects category and the Workspace item.

3. In the New Workspace dialog that appears, enter a directory path and a filename. You
can elect also to open the workspace in a new navigator or to populate it with a new
empty project.
Note that the default directory path stores workspace and project files in a folder entitled
mywork within the JDeveloper directory structure. You can also choose to store your
files outside of this structure, by specifying such in the dialog.
4. Click OK.
Alternately, to bypass the New Gallery, select the Workspaces node in the Navigator, right-click
and choose New Workspace.
Related topics
Managing Your Work Using Workspaces and Project

Saving a Workspace or Project
Unloading a Workspace, Project, or Other File from Memory
Creating a New Navigator
About Workspaces
About Projects
2-39
In JDeveloper, you use workspaces and projects to organize the files needed for an application.
You can create a variety of projects from existing source or containing new objects, or you can
create a new empty project. All projects inherit the settings currently specified in the Default
Project Settings dialog.
As soon as you create the project, it is added to the selected workspace.
To create a new empty project:
1. In the Navigator, select the workspace within which the project will appear.
2. From the main menu, choose File | New or right-click and choose New.
The New Gallery opens.
3. Select Project in the Categories list and Empty Project in the Items list.
4. Double-click Empty Project or click OK.
5. In the New Project dialog, enter the project's path and filename. To select an existing
directory, click Browse.
For more information, click Help.
6. Click OK.
A new empty project appears in the Navigator. It inherits whatever default properties
you've already set. To alter project properties for this particular project, right-click on the
filename and choose Project Settings.
Alternately, to bypass the New Gallery, select the workspace in the Navigator, right-click and
choose New Empty Project.
To create a new project, from specific source or containing specific objects:
1. In the Navigator, select the workspace within which the project will appear.

2-40
3. In the Categories list, select Project.
4. In the Items list, select whichever project wizard best suits the project you wish to build.
For general information on project types and project wizards, click Help from within the
New Gallery. In the help topic that appears, click on the Project category link.
5. Double-click the project wizard name or click OK.

6. Complete each wizard page.
For more information on individual fields or options, click OK from within the wizard.
7. On the Finish page, click OK.
A new project appears in the Navigator. It inherits whatever default properties you've
already set. To alter project properties for this particular project, right-click on the
filename and choose Project Settings.
Related topics

Removing a Project from a Workspace
Adding Existing Files to an Existing Project

About Workspaces
About Projects
2-41
Creating a New Empty Class
To create a new class with its initial attributes defined, use the New Gallery, as you would with
any other type of object. To create a new empty class, you can bypass the Gallery.
As soon as you create the class, it is added to the selected project.
To create a new empty class and add it to a project:
1. In the Navigator, select the project within which the class will appear.
3. Select Object in the Categories list and Class in the Items list.
4. Double-click Class or click OK.
5. In the New Class dialog, enter the class name, the package name, and the class
extended. Select attributes as needed.
6. Click OK.
A new empty class appears in the selected project.
Alternately, to bypass the New Gallery, select the project in the Navigator, right-click and
choose New Class.
Related topics

2-42
About Workspaces
About Projects
2-43
Opening an Existing Workspace or Project
You can create new workspaces and projects from scratch or open existing ones. As soon as
you create or import the workspace, it is added to the Workspaces node in the Navigator. As
soon as you create or import a project, it is added to the selected workspace.
By default, the files in your project appear in a flat file listing. Particularly for larger projects, you
may find the various category views more convenient.
To open an existing workspace and add it to the Navigator:
1. In the Navigator, select the Workspaces node.

2. Choose File | Open or click the Open icon.
3. In the Open or Create a File dialog, navigate to the workspace file. Be sure that the file
type field either specifies .jws files or allows all types to be displayed.
4. Click Open.
The workspace is now added to the list.
To open an existing project and add it to a workspace:
1. In the Navigator, select the workspace to which the project will be added.
3. In the Open or Create a File dialog, navigate to the project file. Be sure that the file type
field either specifies .jpr files or allows all types to be displayed.
4. Click Open.
The project is now added to the appropriate workspace.
Related topics

Importing Existing Files into a New JDeveloper Project
Changing Project Views in the Navigator
2-44
About Workspaces
About Projects
About Project Paths
2-45
Importing Existing Files into a New JDeveloper
Project
You can create new files of various types from scratch or open existing ones. When opening
existing files, you can import them, along with their file structure, into an existing project or build
a completely new project around them.
To open existing files and import them into a new JDeveloper project:
1. In the Navigator, select or create the workspace to which the new project will be added.
If creating a new workspace, be sure to deselect the Add a New Empty Project option.
2. With the workspace selected, choose File | New.

3. In the New Gallery, select the Projects category on the left and the Project with Existing
Java Source on the right.
4. In the New Project from Existing Source Wizard, accept the default directory path or
browse to select a new one. Enter a name for the new .jpr file. Click Next.
For more information on this or any other wizard page, click Help.
5. On the second page of the wizard, accept the default output directory or browse to select
a new one. Click Add Files to browse for the files you wish to import.
6. In the Select a Directory or Files dialog, navigate to your files in the directory tree on the
left. Select your files on the right. Click Open to close the dialog and display the files to
be imported in the wizard.
If you have selected a directory, the Directory Options dialog appears. You can choose
to recurse subdirectories and to add files of a particular extension type. Make your
selections and click OK.
7. In the wizard, the files you wish to add will be displayed. You can now further delete
individual files, if you wish, by selecting them and clicking Remove File.
8. When you have finished with the file list, click Next.
2-46
9. On the next page, enter or browse for a classpath and enter a default run target.
10. Click Next and then Finish.
The new project appears under the selected workspace node, populated with the
imported files.
Related topics

Changing Project Views in the Navigator
About Workspaces
About Projects
2-47
You can create new files of various types from scratch or open existing ones. When opening
existing files, you can import them, along with their file structure, into an existing project or build
a completely new project around them.
To open an existing file and add it to a project already in existence:
1. In the Navigator, select the project to which the file will be added.
3. In the Open or Create a File dialog, navigate to the file or files to be added. Be sure that
the file type field either specifies the appropriate file type or allows all types to be
displayed.
4. Be sure that the Add to project <project name> checkbox is selected.
5. Click Open to close the dialog and display the files to be imported in the wizard.
The files are now added to the appropriate project.
Alternately, you can select the project and choose Project | Add to Project (or click the Add to
Project icon at the top of the Navigator) to open the Add to Project dialog. In this case, there is
no specific checkbox for adding the files to a project, as the behavior is already implicit in the
dialog.
Related topics

2-48
Changing Views in the Navigator
About Workspaces
About Projects
2-49
You can set the project properties for all subsequently created projects or fine-tune the
properties for any individual project.
To view or change the default settings for all subsequent projects:
1. From the main menu, choose Project | Default Project Settings.

2. In the Default Project Settings dialog, select the appropriate node.
3. View or set the various properties as desired.
For more information on individual fields, click Help.
4. When finished, click OK.
Related topics

About Workspaces
About Projects
About Project Paths
2-50
You can set the project properties for all subsequent projects across workspaces, or fine-tune
the properties for any individual project. When you set project properties for an individual
project, you override the default values for that project alone.
For new projects, and in general, you will want to be sure to set the following general attributes:
● Set the appropriate Java source paths

● Set the HTML document root, if appropriate
● Set the appropriate output path
● Set the classpath
● Set the target J2SE
● Set project configurations
Additional project settings are also available, based upon specific tasks such as compiling,
debugging, or running CodeCoach.
Related topics

About Workspaces
About Projects
About Project Paths
2-51
Setting the Java Source Paths for a Project
Every project you create carries the JDeveloper project defaults or those you have supplied
yourself for all the projects across workspaces. You can also replace these defaults on a
project-by-project basis. Setting these properties is the same in either case: only the location,
and application, of the information differs.
To view or change the current Java source paths for an individual project:
1. In the Navigator, select the appropriate project.

2. Choose Project | Project Settings from the main menu, or right-click and choose Project
Settings.
The Project Settings dialog opens with the common input paths displayed or on the last
page that you viewed.
3. If not already selected, select the Input Paths node.

4. On the Input Paths page, change the Java source path (the root for default settings) as
desired by typing in the new value or by clicking Edit.
Related topics

Setting the HTML Document Root for a Project
Setting the Output Path for a Project
About Project Paths

2-52
To set the HTML document root for an individual project:

Settings.
3. If not already selected, select the Input Paths node.

4. On the Input Paths page, change the HTML root directory as desired by typing in the
new value or by clicking Browse.
Related topics

About Project Paths

2-53
To view or change the current output path for an individual project:

Settings.
3. Under Development, click the Paths node.

4. On the Paths page, change the output directory as desired by typing in the new values or
by clicking Browse.
Related topics

About Project Paths

2-54
In JDeveloper, what constitutes the classpath is defined in three places: the output path, any
libraries you include for the project, and (optionally) any additional classpath items you might
include.
When you define where your compiled .class files will be placed, you have set the output
path. That value also appears as the first entry in the classpath field. The next entry, or group of
entries, derives from any libraries you have included in the project. When you remove libraries,
those source paths are removed from the classpath. The final entry derives from any additional
classpath items you may need, or wish, to define.
To set the classpath:
1. Set the output path.

2. Include any libraries you would like for the project.
3. Alternately, remove libraries or delete them.
4. Optionally, add any additional classpath items not already defined elsewhere.
Related topics

About Libraries
2-55
Including Libraries in a Project
When you include libraries in a project, the source paths defined for those libraries
automatically become part of the project's classpath.
To view the current libraries for an individual project:

Settings.
3. Under Development, select the Libraries node.
The libraries both currently available to, and already included in, the project are
displayed.
To add an existing library to a project:
1. With the project selected in the Navigator, open the Project Settings dialog.
3. On the Libraries page, select the desired library or libraries from the Available Libraries
listing and click the single shuttle button to move them to the Selected Libraries listing.
To move the entire listing, click the double shuttle button.
4. If finished, click OK.
2-56
To create a new library and add it to a project:
3. On the Libraries page, click New.
4. In the New Libraries dialog, first enter a name for the new library and select its location.
5. To designate the library's class, source, and doc paths, enter values directly or click Edit
beside each field.
6. In each Edit Path dialog, click Add Entry or Add URL as appropriate. To remove a path,
or correct an addition, click Remove. To rearrange the order of entries, use the
reordering buttons to the right of the display area.
7. Once you have clicked either Add Entry or Add URL, in the resulting selection dialog
enter the filename or browse through the listing to select one. When your entry is
complete, click Select.
8. In the Edit Path dialog, click OK.
9. In the Edit Library dialog, click OK.
10. On the Libraries page, if finished click OK.
To edit an existing library in a project:
3. On the Libraries page, select the library to be altered from the Selected Libraries listing.
4. Click Edit.
5. In the Edit Libraries dialog, the appropriate library's name should appear in the first field.
Make any desired changes to the library name by typing directly into the field.
2-57
6. Next to each remaining field to be changed, click Edit.
7. In each Edit Path dialog, click Add Entry or Add URL as appropriate. To remove a path,
or correct an addition, click Remove. To rearrange the order of entries, use the
reordering buttons to the right of the display area.
8. Once you have clicked either Add Entry or Add URL, in the resulting selection dialog
enter the filename or browse through the listing to select one. When your entry is
complete, click Select.
9. In the Edit Path dialog, click OK.
10. In the Edit Library dialog, click OK.
11. On the Libraries page, if finished click OK.
Related topics

About Libraries
2-58
Removing or Deleting Libraries from a Project
When you remove libraries from a project, or delete them permanently, the source paths
defined for those libraries no longer form part of the project's classpath.
To remove a library from a project:
3. On the Libraries page, select the desired library or libraries from the Selected Libraries
listing and click the single shuttle button to return them to the Available Libraries listing.
To delete a library permanently:
3. On the Libraries page, select the library or libraries to be removed from the Selected
Libraries listing and click Delete.
4. In the confirmation dialog that appears, click Yes.
Related topics

2-59
About Libraries
2-60
Setting Additional Classpath Values for a Project
Add additional classpath entries as an alternative to creating a library for a project. Additional
classpath entries are relative to the project, while libraries are relative to the IDE. When a
project needs to use only a few other classes, and only this project will use these classes, it is
easier to add these classes through the additional classpath rather than creating a library to
contain them.
To set additional classpath values for a project:

Settings.
3. Under Development, click the Paths node.

4. On the Paths page, enter additional classpath values as desired by typing directly or by
clicking Edit to open the Edit Additional Classpath dialog. In this dialog, you can add,
delete, or rearrange entries.
Related topics

2-61
About Project Paths

2-62
and application, of the information differs. Setting the target J2SE specifies which J2SE
JDeveloper will use when compiling and running your project.
To view or change the current J2SE for an individual project:

Settings.
3. Under Development, click the Libraries node.

4. On the Libraries page, change the J2SE as desired by typing in the new value or by
clicking Define.
5. When finished, click OK
Related topics

About J2SEs
2-63
Setting Project Configurations
Configurations enable you to specify project settings for specific tasks (such as compiling or
debugging) in one place and to return to those settings as often as you like.
To manage your project configurations, you'll want to know how to:
● Create a new project configuration

● Rename a project configuration
● Change the active configuration
● Delete a project configuration
Related topics

2-64
Creating a New Project Configuration
To create a new project configuration:
1. In the Navigator, select the project for which the configuration will apply.
Settings.
3. Select the Configuration node.
For more information on this page, any of the other project settings pages, or in any
related dialogs, click Help.
4. On the Configuration page, click New.

5. In the New Configuration dialog, fill in a name for the configuration and indicate whether
it will be copied from an existing configuration or begun from scratch.
6. Click OK to return to the Project Settings dialog.
The newly created configuration displays now on the Configuration page as the currently
active configuration. It appears also in the tree view to the left, with each of the project
settings nodes beneath it.
7. To set the project settings for this configuration, select the various nodes in the tree
control to the left and alter the settings on those pages as desired.
Related topics
2-65
Renaming a Project Configuration
Changing the Active Configuration
Deleting a Project Configuration
2-66
To rename a project configuration:
1. In the Navigator, select the project associated with the configuration to be renamed.
Settings.
For more information on this page, any of the other project settings pages, or in any
related dialogs, click Help.
4. On the Configuration page, click Rename.

5. In the Rename Configuration dialog, enter the new configuration name.
6. Click OK to return to the Configuration page.
The renamed configuration is now the currently active configuration.
Related topics

2-67
Changing the Active Project Configuration
To change which project configuration is currently active:

Settings.

4. On the Configuration page, select the configuration to be made active from the Active
Configuration dropdown list.
5. Click OK.
Related topics

2-68
To change which project configuration is currently active:

Settings.
For more information on this page or in any related dialogs, click Help.
4. On the Configuration page, click Delete.

5. In the confirmation dialog, click Yes.
You are now returned to the Configuration page, where the configuration no longer
appears.
6. Click OK.
Related topics

2-69
Browsing Files Through JDeveloper
Sometimes, you may not want to add files directly to a project, but yet have them handy for
browsing. You can bring files into the JDeveloper IDE, without adding them to a project.
To bring files into JDeveloper, outside of any particular project:

2. In the Open or Create a File dialog, navigate to the file or files to be opened. Be sure that
the file type field either specifies the appropriate file type or allows all types to be
displayed.
3. Be sure that the Add to project <project name> checkbox is not selected.
If a project or any child node of that project has focus in the Navigator, this checkbox is
selected by default, so you may need to deselect it.
4. Click Open to close the dialog and display the files in the IDE.
The files now appear under a node named Miscellaneous Files, which appears as the
last node in the Navigator.
Related topics

About Workspaces
About Projects
2-70
Inspecting the Contents of an Archive in JDeveloper
You can easily inspect the contents of any archive in JDeveloper, after first opening the
archived file in JDeveloper.
To open an archive in JDeveloper and view its contents:
1. From the main menu, choose File | Open.
If the archived set of files is potentially to be added to a project, select that project first in
the Navigator. If not, you may be on any node in the Navigator, but be sure to deselect
the Add to project checkbox in the resulting Open or Create a File dialog.
2. In the Open or Create a File dialog, navigate to the file or files to be opened. Be sure that
the file type field either specifies all file types to be displayed.
3. When the archived file displays in the righthand pane, select it and click Open.
The archived file now either appears in the selected project or in a folder entitled
Miscellaneous Files and automatically opens in its default viewer.
To view an archive already opened in or imported into JDeveloper:
1. In the Navigator, select the archived file.

2. From the main menu, choose View | Display with | Archive Viewer or right-click and
choose Archive Viewer in one step.
Note that because the Archive Viewer is also the default viewer for this type of file, you
can simply double-click the archived file to open the viewer.
Related topics

2-71
About Workspaces
About Projects
2-72
Viewing an Image File in JDeveloper
You can easily view any .gif, .jpg, .jpeg, or .png file from within JDeveloper, after first
opening the image in JDeveloper.
To open an image in JDeveloper and view it:
1. From the main menu, choose File | Open.
If the image is potentially to be added to a project, select that project first in the
Navigator. If not, you may be on any node in the Navigator, but be sure to deselect the
Add to project checkbox in the resulting Open or Create a File dialog.
2. In the Open or Create a File dialog, navigate to the image or images to be opened. Be
sure that the file type field either specifies all file types or the image types.
3. When the image displays in the righthand pane, select it and click Open.
The image now either appears in the selected project or in a folder entitled
Miscellaneous Files and automatically opens in its default viewer. The image itself is
now displayed in the main working area of JDeveloper.
To view an image already opened in or imported into JDeveloper:
1. In the Navigator, select the image file.

2. From the main menu, choose View | Display with | Image Viewer or right-click and
choose Image Viewer in one step.
Note that because the Image Viewer is also the default viewer for any standard image
type, you can simply double-click the file to open the viewer.
Related topics

2-73
About Workspaces
About Projects
2-74
To save all the files across workspaces, including all projects:
● Choose File | Save All or click the Save All icon.
Saving the .jws or .jpr file alone does not save the individual files governed by that
workspace or project. Saving individual contained files does not save the workspace or project
container file. Each node is an independent entity and must be saved as such. Using Save All
takes care of changes to these container files, as well as all content files.
Similarly, using Save or Save As on a selected workspace or project node saves or duplicates
the .jws or .jpr file only: it does not save or duplicate the files contained within the node.
Note too that if you do a Save As on a workspace or a project, that workspace or project (the
actual .jws or .jpr file) is replaced by one with the new name. The files governed by the
workspace or project, however, within remain the same. Conversely, if you do a Save As on an
individual file, that file is duplicated.
Related topics

2-75
Saving a File
To save an individual file:
1. In the Navigator, select the file to be saved.

2. Choose File | Save or click the Save icon.
Saving individual files does not save the .jpr file. Saving the .jpr file does not save the
individual files contained within it. Saving individual files and the .jpr file does not save the
changed .jws file. Each node is an independent entity and must be saved as such. Using
Save All takes care of changes to these container (.jws, .jpr) files, as well as all content
files.
Note too that if you do a Save As on a workspace or a project, that workspace or project is
replaced with the new name. The files contained within remain the same. However, if you do a
Save As on an individual file, that file is duplicated.
Related topics

2-76
Relocating a Workspace or Project
By default, all workspaces and projects are created with their settings and files stored in one
directory. When you create a new project from existing source, or when you import files into a
project without changing their original location, you essentially enter pointers to these files in
your .jpr file. Even though the files or directories are not stored under JDeveloper's project
directory, the project settings are still created relative to the project.
When project files are all stored under the project directory, moving the directory preserves the
project structure and thus the project settings. But when the project files are stored elsewhere,
simply moving the directory does not preserve the structure of the files or directories with
respect to the .jpr file.
When you create a new workspace which references projects stored outside the workspace
directory, or add such projects to an existing workspace, a similar relationship holds.
To change the location of a project created with default settings, or of a workspace with all of its
files stored under the workspace directory:
1. Through the system Explorer, navigate to the directory jdev\bin\mywork.

2. Select the entire directory of the workspace or project to be moved and copy it to the new
location.
To change the location of a workspace or project that exists on one drive, while its files exist on
another:
1. Through the system Explorer, navigate to the directory jdev\bin\mywork.

2. Select the entire directory of the workspace or project to be moved and copy it to the new
location.
To change the location of a workspace or project when its files reside on the same drive, but not
under the workspace project directory:
1. In the Navigator, select the workspace or project to be relocated.

2. From the main menu, choose File | Save As.
3. In the Save As dialog, enter the new location of the workspace or project and click Save.
2-77
Related topics

About Workspaces
About Projects
2-78
Unloading a Workspace, Project, or Other File from
Memory
When you close a workspace, project, or file in the Navigator, that workspace or project is
unloaded from memory. When a workspace or project is closed, it appears in its unexpanded
form in the Navigator.
In addition, you can remove workspaces, projects, or files from the Navigator, which removes
them only from the listing, or you can delete them permanently, wherever they reside, from
within JDeveloper.
To close a workspace or project:
1. In the Navigator, select the workspace or project to be closed.

2. Choose File | Close.
If any files within that workspace or project were changed and not saved, you are
prompted to save them now.
3. If prompted to save the file, click Save Selected, Save None, or Cancel as appropriate.
Deselect any files you do not wish recent changes saved for.
The workspace or project now collapses and appears in the Navigator with the plus sign
indicating that is ready for expansion.
To close a file opened for viewing:
1. In the Navigator, select the individual file to be closed.

2. Choose File | Close.
If that file was changed and not saved, you are prompted to save it now.
The file now disappears from any viewer or editor modes.
Alternately, you can close a file opened in a viewer or editor by right-clicking on the document
2-79
name in the document bar and choosing Close Editor .
Related topics
Removing a File from a Project

Removing a Workspace
Permanently Deleting a Workspace, Project, or Other File
2-80
You can remove files from a project, which removes them only from the Navigator listing, or you
can delete them permanently, wherever they reside, from within JDeveloper.
To remove files from a project:
1. In the Navigator, select the file or files you wish removed.

If the file was not previously saved, or has changed since it last was saved, you will be
prompted now to save it. Saving it maintains it with any changes intact wherever it is
stored, even though it no longer appears in the Navigator. Not saving it means the entire
file disappears (if it was never saved) or the most recent changes are lost (if it changed
since being saved).
When deleting a number of files, you can choose to selectively save files by selecting or
deselecting the checkbox next to the filename.
Related topics

About Workspaces
About Projects
2-81
You can remove projects from the workspace, which removes them only from the Navigator
listing, or you can delete them permanently, wherever they reside, from within JDeveloper.
To remove a project from a workspace:
1. Select the project you wish removed.

If the project was not previously saved, or has changed since it last was saved, you will
be prompted now to save it. Saving it maintains it with any changes intact wherever it is
stored, even though it no longer appears in the Navigator. Not saving it means the entire
project disappears (if it was never saved) or the most recent changes are lost (if it
changed since being saved).
3. If prompted to save the project, click Save Selected, Save None, or Cancel as
appropriate.
You can choose to selectively save files by selecting or deselecting the checkbox next to
the filename.
Related topics

About Workspaces
About Projects
2-82
You can remove workspaces from the Workspace node, which removes them only from the
Navigator listing, or you can delete them permanently, wherever they reside, from within
JDeveloper.
To remove a workspace from the IDE:
1. In the Navigator, select the workspace you wish removed.

If the workspace was not previously saved, or has changed since it last was saved, you
will be prompted now to save it. Saving it maintains it with any changes intact wherever it
is stored, even though it no longer appears in the Navigator. Not saving it means the
entire workspace disappears (if it was never saved) or the most recent changes are lost
(if it changed since being saved).
You can choose to selectively save files by selecting or deselecting the checkbox next to
the filename.
Related topics

About Workspaces
About Projects
2-83
Permanently Deleting a Workspace, Project, or
Other File
You can permanently delete any file (workspace, project, or file within a project) that appears in
the Navigator, no matter where it resides, from within JDeveloper.
To permanently delete a workspace, project, or other file:
1. In the Navigator, select the file or files you wish deleted.

2. Choose File | Erase from Disk.
3. In the Erase from Disk dialog, note that the files you wish to delete are selected, and
click Erase Selected.
You can also elect not to delete one or more of the files listed.
Note that if you delete a workspace or a project, only the .jws or .jpr file is actually deleted.
The elements contained within the workspace or project remain on disk. To delete them from
disk through JDeveloper, you must do so explicitly.
Related topics

2-84
Editing Source Code
To edit code in JDeveloper, you'll want to know how to:
● Edit source code in JDeveloper

● Edit source code with an external editor
● Edit classes visually with the Class Editor
● Manage editor windows with the document bar
Related topics

Common Programming Practices in JDeveloper
About Workspaces
About Projects
2-85
JDeveloper provides a powerful code editor that will help you write different kinds of code
quickly and efficiently.
To edit your source code in its default editor:
● In the Navigator, double-click the file.
The default editor associated with that file type appears in the content area. If the editor
is already open on that file, the editor comes to the foreground.
To open your source code in an specific editor or viewer:
1. In the Navigator, select the file.

2. Choose View | Display with | <viewer/editor> or right-click and choose the viewer or
editor from the context menu.
Changes made in the source will be immediately reflected in other views of that file.
Related topics
Customizing the Code Editor Environment

Defining Code Completion Templates for the Code Editor
Editing Classes Visually with the Class Editor
Managing Editor Windows with the Document Bar
About Code Insight
Classic Keymapping
Default Keymapping
Emacs Keymapping
2-86
It is possible to edit source code that you have opened in JDeveloper with an outside editor,
should you wish to do so. When you return to JDeveloper's IDE, JDeveloper will detect the
changes you have made.
Before you edit a file externally, you should first save any changes made in JDeveloper. If you
do not, when you return to JDeveloper, you will be prompted with a dialog asking whether you
want to reload the changed file. If you click Yes, you will lose the unsaved changes made in
JDeveloper. If you click No, you will lose the changes made outside JDeveloper.
To edit source code with an external editor, with the file open in JDeveloper:
1. Save any changes made to the file open in JDeveloper.

2. Edit your file externally and save your changes to the disk.
3. Return to JDeveloper and to the file open in the Code Editor.
By default, the file is reloaded in JDeveloper without a confirmation beforehand. To

receive a confirmation dialog, deselect the Silently Reload When Buffer Is Unmodified
option on the Environment page of the Preferences dialog. For more information click
Help from within that dialog page.
Related topics

Classic Keymapping
Default Keymapping
Emacs Keymapping
2-87
You can choose to edit your classes visually, using the Class Editor, to edit the code by hand,
or to move fluidly between the two. The changes you make visually are instantly reflected in the
code and vice versa.
To open a class in the Class Editor:
1. In the Navigator, select the class to be edited.

2. From the main menu, choose View | Display with | Class Editor or right-click and choose
Class Editor.
The Class Editor appears, from which you can easily add, edit, or remove methods or
fields, or create or import event sets using the tabbed pages for fields, methods, and
events. From the General page, you can generate a BeanInfo class with the click of a
button.
For more information on the capabilities of the Class Editor, press F1 from within any of
its pages. For more information on any of the dialogs it summons, click Help from within
that dialog.
Related topics

Classic Keymapping
Default Keymapping
Emacs Keymapping
2-88
The document bar displays the files you have opened directly in editor windows (for example
directly from the Navigator or through the Open dialog), as well as any files called by those
editors as you work, for example, by debugging or browsing symbols.
Explicit documents are those you have opened yourself. Implicit documents are those opened
by editors as you work. Explicit documents are numbered, from 1 through 9, reflecting the order
in which you opened them, unless an earlier explicit document has been closed, leaving that
number available for the next explicitly opened document. Implicit documents are not
automatically numbered, although you can assign numbers to them should you wish. Once you
have done so, they are treated as explicit documents. For more information on document
numbering, put the focus on the document bar itself and press F1.
To toggle quickly through explicit documents:
● Press Alt-#, where # is the number assigned the document you wish to make active.
To reassign the number of an explicit document, or to assign a number to an implicit document:
● Select the document name in the bar and press Alt-Shift-#, where # is the number to be
assigned to the document.
To view all implicit and explicit documents in alphabetical order:
● Click on the double-arrow button in the far right of the bar. Select a document in this list
makes it active.
To close explicit or implicit documents individually:
● Right-click on the document name in the bar and choose Close Editor.
To close all implicit documents at once:
● Click on the double-arrow button in the far right of the bar and choose Close Implicit.
Alternately, you can choose Window | Close Implicit or use the accelerator Ctrl-Shift-F4.
2-89
To close all editor windows at once:
● Choose Window | Close All Editors.
Related topics

2-90
You can use the visual design tools in JDeveloper to quickly assemble a user interface (UI) for
a Java application or applet. First, construct the UI with JavaBeans (such as buttons, text
areas, lists, dialogs, and menus) from the Component Palette. Then set the values of the
component properties and attach event-handler code to the component events.
For detailed information, see Developing GUI Clients.
Related topics

Developing JavaBeans
2-91
JDeveloper provides you with some shortcuts for several common Java programming
practices.
You can take advantage of these shortcuts to:
● Implement a Java interface

● Override methods in a superclass
● Move or rename Java classes, either individually or in a group
Related topics
2-92
Implementing a Java Interface
You can use the Implement Interface dialog to create an interface framework. The method
signature framework is inserted at the end of the .java source for the class. You will then
need to write code that implements each method of the interface.
To implement an interface:
1. In the Navigator, select a .java file.

2. Choose Tools | Implement Interface.
The Implement Interface dialog is displayed.
3. In the Class list, select the name of the class you want to implement the interface.
4. In the Available Interfaces list, select the name of the interface you want to implement.
5. Click OK.
6. Display the class in the Code Editor and replace the commented lines with the desired
code.
Related topics
About JavaBeans
2-93
Overriding Methods in a Superclass
You override methods in a superclass when you want one of its subclasses to implement an
inherited method differently.
To override a method in a superclass:
1. Choose Tools | Override Methods.
The Override Methods dialog is displayed.
2. In the Class field, choose the name of the class you want to examine.
3. In the Inherited methods list box, choose the name of the method or methods you want
to override.
The list displays all methods in all inherited classes.
4. Click OK to create the code that override the method(s).

5. Open the class file in the Code Editor and place the code that implements the new
behavior at the position shown by the commented line below:
public java.lang.String getTitle() {

//TODO: override this java.awt.Frame method;
return super.getTitle();
}
2-94
Moving or Renaming Java Classes
Refactoring is the process of improving an application by reorganizing its internal structure
without changing its external behaviour. When you refactor an application, you may want to
move or rename individual classes, or to move groups of classes to a different package. In
JDeveloper, you can make these changes without breaking any dependent files on which your
project relies, as these files are automatically updated for you.
Your project must be compilable before you can refactor its classes in JDeveloper.
To move or rename a single Java class:
1. In the Navigator, select the class to be moved or renamed.

2. From the main menu, choose Tools | Refactor | Rename Class.
3. In the Rename Class dialog, enter the new, fully qualified package name.
The class will now be renamed and, if appropriate, moved into the appropriate package.
Any dependent files accessible to your project will also be updated.
To move a group of Java classes into a new package:
1. In the Navigator, select the class or classes to be moved.

2. From the main menu, choose Tools | Refactor | Move Classes.
3. In the Move Classes dialog, enter the new, fully qualified package name.
The classes will now be renamed and moved into the appropriate package. Any
dependent files accessible to your project will also be updated.
Related topics
2-95
For your projects to communicate with the Oracle database, you will need to set up database
connections.
To begin working with database connections, you'll want to know how to:
● Define database connections

● Edit database connections
● Import database connections
● Export database connections
● Open and close database connections
● Delete database connections
Related topics
Accessing the Database Using SQL*Plus
About Connections
2-96
Defining Database Connections
To create a new database connection:
1. From the main menu, choose File | New.
2. In the Gallery, select Connections in the Categories list and Database Connection in the
Items list.
3. Double-click Database Connection or click OK.
The Connection Wizard appears.
4. Click Next if the Welcome page appears.

5. On the Type page, enter a name for the connection and select a type from the dropdown
list.
For more information on this or subsequent pages, click Help.
6. Click Next.
7. On the Authentication page, enter a username, a password, and, optionally, a role.
8. Click Next.
9. On the Connection page, enter the connection details as requested.
The information you enter will be depend on which type of connection you are creating.
10. Click Next.

11. On the Test page, click Test Connection.
JDeveloper checks the connection using the information you provided. If the test
succeeds, a success message appears in the status text area. If the test does not
succeed, an error appears. Click Back and change any previously entered information as
needed to correct the error or check the error content to determine other possible
sources of the error.
2-97
The Test Connection button becomes the Cancel Test button during testing. Click
Cancel Test to cancel the connection test if necessary.
12. When the test succeeds, click Finish.
The Connection Wizard closes. The new connection name appears under the Database
node in the Navigator.
Alternately, to bypass the New Gallery, expand the Connections node in the Navigator, select
the Database node, right-click and choose New Connection.
Related topics

Editing Database Connections
Importing Database Connections
Exporting Database Connections
Opening and Closing Database Connections
Deleting Database Connections
About Connections
2-98
Once you have defined a connection, you can return to the wizard and edit its attributes.
To edit a database connection:
1. In the Navigator, expand the Connections, Database node and display the connection
that you want to modify.
2. Right-click the connection and choose Edit.
The Connection Wizard appears.
3. On the Type page, enter a new name for the connection or select a type from the
dropdown list.
For more information on this or subsequent pages, click Help.
4. Click on the Authentication tab.

5. On the Authentication page, change the username, password, and role.
6. Click on the Connection tab.
7. On the Connection page, change the connection details as needed.
8. Click on the Test Connection tab.
9. On the Test page, click Test Connection.
JDeveloper checks the connection using the new information you provided. The Test
Connection button becomes the Cancel Test button during testing. Click Cancel Test to
cancel the connection test.
10. When the test succeeds, click OK.
The Connection Wizard closes. If you change the connection name, the new name
appears under the Database node in the Navigator.
Related topics
2-99
Configuring Connections
Defining Connections
Opening and Closing Connections
Deleting Connections
About Connections
2-100
When you export connections, selected connection descriptors are copied to a text file, and can
subsequently be imported by other users.
To export a database connection:
1. In the Navigator, expand the Connections node and select the Database node.
2. Right-click, and choose Export Connections.
3. In the Export Connection Descriptors dialog, enter the filename or click Browse to
specify a location and name for the connection file.
4. Select the appropriate connections from the list box.
5. Click OK.
The connection information for the selected connections is saved in the file and can be
imported for use by others.
Related topics

2-101
You can import connection descriptors that have previously been exported.
To import a database connection:
1. In the Navigator, expand the Connections node and select the Database node.
2. Right-click and choose Import Connections.
3. In the Import Connection Descriptors dialog, enter the filename of your exported
connection file or click Browse to locate it.
4. Select the appropriate connections from the list box. You can import multiple connections
at one time.
5. Click OK.
The new connection name appears under the Database node in the Navigator.
Related topics

2-102
If a database connection that you previously created is not open, use the following procedure to
connect it to the target database. You can also close a connection in order to disconnect it from
the target database.
To open a database connection:
that you want to open.
2. Right-click the closed connection and choose Open Connection.
To close a database connection:
that you want to close.
2. Right-click the open connection and choose Close Connection.
Related topics

About Connections
2-103
Deleting connections removes them from the Connections, Database node in the Navigator
and the installation of JDeveloper.
When you delete a connection, JDeveloper does not warn you that a project may be dependent
upon it. For this reason, it is best to use caution when deleting connections.
To delete a database connection:
that you want to delete.
2. Right-click the connection and choose Delete Connection.
3. In the confirmation dialog, click Yes to delete the connection.
Deleting a connection deletes it for the whole JDeveloper installation, not just the current
workspace or project.
Related topics

Creating Database Connections
About Connections
2-104
Printing Source Files
To print a source file:
1. Display the file in an editor.

2. Choose File | Print.
3. In the Print dialog, select your print options.
4. Click OK.
Related topics

2-105
Customizing the IDE
You can customize the JDeveloper Integrated Development Environment (IDE), and arrange its
look, to better suit your project needs and individual work style.
To organize JDeveloper and its views to your individual taste, you'll want to know how to:
● Change the look and feel of the IDE

● Open, close, create, and manipulate navigators
● Define, activate, rename, and remove layouts
● Arrange the windows in the IDE
● Customize the Component Palette
● Customize the IDE environment, including the Code Editor
Related topics
Extending JDeveloper
2-106
Changing the Look and Feel of the IDE
To change the look and feel of the IDE:
1. Choose Tools | Preferences.

2. If the Environment node is not selected, select it.
3. On the Environment page, select a different look and feel from the Look and Feel
dropdown list.
4. Click OK.
5. Restart JDeveloper.
Related topics
Customizing the IDE environment
2-107
Arranging Windows in the IDE
You can move the various windows in the JDeveloper IDE to create a configuration most
comfortable for your use. Any changes you make to the arrangement of windows is
remembered, based upon the layout currently in use.
To arrange windows in JDeveloper, you'll need to know how to:
● Dock the windows along any edge in the IDE window

● Float the windows (detaching them from the IDE)
● Hide or reopen windows
Related topics
Customizing the IDE

Working with Layouts
2-108
Docking Windows in the IDE
The windows that appear, and the arrangement of those windows, varies depending upon the
layout currently active.
All of the tools available under the View menu—the System Navigator, the Structure window,
the Property Inspector, and so on—can be arranged to suit your work habits.
To dock any of these windows to another edge of the development area:
● Drag the title bar of the window against any edge.
If a window is already docked to that edge of the IDE window, you can position it on the top,
bottom, or side of the docked window by dragging the window to the corresponding edge of the
docked window.
You can dock several windows to one edge of the IDE. To save screen space, you can tab
together floating windows. To tab a window, drop it in the center of the docking window.
Related topics

Floating Windows in the IDE
Hiding and Reopening Windows in the IDE
2-109
You can float any window that's normally docked—the System Navigator, any custom
navigators, the Log window, the Property Inspector, the Component Palette. You can also
resize and position it wherever you would like within JDeveloper.
Generally, floating windows are best suited for a large screen with enough room for displaying
both the information windows and your source code. If you are using floating palettes on a
smaller screen they can sometimes be hidden by other information windows as you work.
To float any currently docked window:
● Drag the window away from its docked location, by grabbing the title bar area of the
window and holding the mouse button down as you drag the window.
Related topics

2-110
You can easily open and close the main elements of the JDeveloper IDE: the System
Navigator, Structure Window, Property Inspector, Component Palette, and Log window.
To open or close these windows:
● In the View menu, choose the name of the window.
To close any of these windows, you can also click the close box (the one with the x) in the
upper righthand corner of the window.
Related topics

2-111
Working with Navigators in the IDE
Just as you can have multiple workspaces in JDeveloper, you can also create custom
navigators to assist you in keeping your work organized.
To work with navigators in JDeveloper, you'll want to know how to:
● Create a new navigator

● Change views in the Navigator
● Dock and undock navigators
● Open and close navigators
Related topics
Customizing the IDE
2-112
In addition to having multiple workspaces in the System Navigator (the default navigator), you
can create new navigators for some container nodes in the System Navigator. The new custom
navigator then uses the selected container node as its root. You can create as many custom
navigators as you like, each being a subset of the System Navigator, not a duplicate.
To create a new navigator:
1. Select the appropriate node either in the default navigator or within any other custom
navigator.
2. Choose View | Display in New Navigator or click the Display in New Navigator icon in
the toolbar at the top of the Navigator window.
The node and everything it governs now comprise a new navigator, which appears in a
new tabbed window with the name of the top-level node on the tab. The default navigator
now also has a tab, entitled System.
You can tear off any of these custom navigators to form an independent window, either
floating or redocked elsewhere. If you close any of the custom navigators, to reopen it
you must re-create it. If you close the System Navigator, any tabbed custom navigators
that existed will not reappear.
If the menu option and icon are grayed out, you cannot create a new navigator with the
selected node as a starting point.
Related topics

Docking and Undocking Navigators
Opening and Closing Navigators
2-113
By default, the files in your project appear in a flat file listing. You can view these files by
category, and then, within category
Particularly for larger projects, you may find the various category views more convenient.
To change from flat to hierarchical file view:
1. Select the project node in the Navigator.

2. From the main menu, choose Project | Show Categories or click the Show Categories
icon at the top of the Navigator.
The files within the project are now displayed hierarchically, the exact hierarchy type
determined by source node. For more information, put the focus in the Navigator and
press F1.
To reorganize hierarchically displayed views:
1. Once the project is displayed hierarchically, select Sources node within it.
2. From the main menu, choose Project | Organize by | <category type>. Alternately, click
the icon just to the right of the Show Categories icon and select from its dropdown list.
The category display types vary depending upon the source file types. For more
information, put the focus in the Navigator and press F1.
To show all files within a hierarchical display:
1. Once the project is displayed hierarchically, select Sources node within it.
2. From the main menu, choose Project | Show All Files. Alternately, click the Show All
Files icon at the top of the Navigator.
Now all files in the directory display in the Navigator, even those not included in the
project. For more information, put the focus in the Navigator and press F1.
2-114
Related topics

2-115
When you first create a new custom navigator, it appears as a new tabbed window within the
System Navigator. You can elect to detach it and redock it anywhere else within the IDE.
To dock a floating navigator:
1. Click on the title area, which will either be darker or display "grab bars," and begin
dragging the window.
In a floating window, the title area will always be at the top.
2. Place the window up against the margin where you would like to dock it.
3. Release the mouse.
To undock a stationary navigator:
1. Click on the title area, which will either be darker or display "grab bars," and begin
dragging the window.
The title area may be either at the top or to the left side of the window.
2. Place the window where you would like it, either docked in another area or floating.
Note that whenever you move a navigator window to a new docked position, it resizes
accordingly to fit the space. Whenever you move a floating navigator window you have
expanded, it shrinks again to the default opening size.
To undock a custom navigator from the System Navigator:
1. Click on the navigator's tab and, with the mouse button still depressed, drag and drop the
window away from the System Navigator window to its new location.
To redock a custom navigator in the System Navigator:
2-116
1. Click on the title area of the independent navigator and hold, as you would when docking
or undocking any individual window.
2. Position the custom navigator in the center of the System Navigator window.
Related topics

2-117
In addition to having multiple workspaces in the System Navigator (the default navigator), you
can create new navigators for some container nodes in the System Navigator. These custom
navigators are subsets of, not replacements for, the System Navigator.
To view the System Navigator:
● If the System Navigator is currently not visible, choose View | System Navigator.
The System Navigator now appears, docked in whatever position you last left it. Any
previously created custom navigators tabbed within it are no longer displayed.
To close a navigator window (whether System or custom):
● Click the close box (the one with the x) in the upper righthand corner of the window.
Closing a Navigator window will close all navigators tabbed together in that window.
To close an individual navigator tab (System or custom) in a window:
● Right-click on the tab and choose Close.
The tabbed navigator is no longer displayed. The navigator or navigators remain grouped
in the window.
Note that if you close any custom navigator that exists in its own window, to reopen it you must
re-create it.
If you close a window which combines the System Navigator and custom navigator or
navigators, when you reopen the System Navigator the custom navigators no longer appear.
Related topics

2-118
2-119
Working with Layouts in JDeveloper
A layout defines a work area with the tools, or views, arranged so as best to support working on
the task at hand. JDeveloper comes with several layouts already defined for your use. You can
rearrange these layouts, if you wish, and define as many other custom layouts as you would
like.
To work with layouts in JDeveloper, you'll want to know how to:
● Define custom layouts

● Activate defined layouts
● Disable editor layout preferences
● Rename layouts
● Remove layouts
Related topics
About Layouts
2-120
Defining Custom Layouts
JDeveloper comes with one basic layout design for Design mode and one for Debug mode. In
addition, within Design mode, some editors have their own preferred layouts. You can use
these layouts as originally defined, you can alter them, or you can create your own custom
layouts.
Any changes you make to any of the originally provided layouts are remembered, and so you
can fine-tune these default layouts if you wish. You can also preserve the original layouts, if you
wish, and create as many of your own custom layouts as are useful.
To define a single new custom layout for all of Design mode, to be used regardless of which
editor is open:
1. Close all open editors.
If any editors remain open, when you return to the IDE after defining and activating a
layout for Design mode, that layout will not be visible. The editor's own preferred layout
will override other layouts while that editor is open.
2. From the main menu, choose Tools | Preferences.

3. In the Preferences dialog, select the Layouts node.
4. On the Layouts page, ensure that the option at the top of the dialog, Use Editor's
Preferred Layout, is selected and that the option below it, Use Active Layout as Current
Editor Preferred Layout, is deselected.
5. Under Available Layouts, select Design.
For more information on this or any other portion of the dialog, click Help.
6. Click New.
7. In the New Layout dialog, enter a name for the new layout and click OK.
8. If you want this to be the current active layout for Design mode, you must activate it now
by selecting it in the list and clicking Activate.
9. In the Preferences dialog, click OK.
As you return to JDeveloper, if you had any other layout previously open, it will be gone
and a new "vanilla" layout is instead opened for you to begin working with.
2-121
10. Open and arrange windows to create the new layout design that you want.
These changes are remembered. The next time that you work within this layout, it will
appear as you last left it.
To define and assign an individual custom layout to an editor in Design mode:
1. Open or put the focus on the editor that the new layout will be associated with.
4. On the Layouts page, ensure that both options at the top of the dialog are selected.
If the second option were deselected, the newly created layout would not be assigned to
the currently open editor. Its own current preferred layout would override the new layout.
5. Under Available Layouts, select Design.
6. Click New.
8. If you want this to be the current active layout for this editor, you must activate it now by
selecting it in the list and clicking Activate.
As you return to JDeveloper, if you had any other layout previously open, it will be gone
and a new "vanilla" layout is instead opened for you to begin working with. This layout
will be partnered with the editor currently open.
2-122
To define a new custom layout for Debug mode:
1. If you wish to see the layout as soon as you activate, change to Debug mode first.
You can ignore the two options at the top of the dialog. They do not apply to Debug
mode.
4. On the Layouts page, under Available Layouts select Debug.
5. Click New.
7. If you want this new custom layout to to be the current active layout for Debug mode, you
must activate it now by selecting it in the list and clicking Activate.
When you return to JDeveloper, as soon as you enter Debug mode you will see the new
layout. If you formerly had any other Debug layout previously open, it will be gone and a
new "vanilla" layout is instead opened for you to begin working with.
Related topics

Activating Defined Layouts
Disabling Editor Layout Preferences
Renaming Layouts
2-123
Removing Layouts
About Layouts
2-124
In Design mode, you can change which layout is "activated," or selected as the current
preference, for each individual editor. In Debug mode, you can change which layout is the
current preferred layout for debugging. You can activate a custom layout when you create it, or
activate it later.
To activate a single defined layout for Design mode:
1. Close all open editors.
If any editors remain open, when you return to the IDE after activating a layout for Design
mode, that layout will not be visible. The editor's own preferred layout will override other
layouts while that editor is open.

4. On the Layouts page, ensure that the option at the top of the dialog, Use Editor's
Preferred Layout, is selected and that the option below it, Use Active Layout as Current
Editor Preferred Layout, is deselected.
5. Under Available layouts, select the layout you wish to activate as the preferred layout for
Design mode. It should appear below Design.
All currently designated active layouts appear in bold. If the layout you wish to activate is
already activated, its label appears in bold and the Activate button is disabled. For more
information on this or any other portion of the dialog, click Help.
6. Click Activate.
7. Click OK.
To activate a layout for a particular editor in Design mode:
1. Open or put the focus on the editor that the layout will be associated with.
2-125
4. On the Layouts page, ensure that both options at the top of the dialog are selected.
the editor now open. It should appear below Design.
6. Click Activate.
7. Click OK.
To activate a layout for Debug mode:
1. Change to Debug mode within JDeveloper by beginning a debugging task.

You can ignore the two options at the top of the dialog. They do not apply to Debug
mode.
Debug mode. It should appear below Debug.
5. Click Activate.
6. Click OK.
Related topics
2-126
Renaming Layouts
Removing Layouts
About Layouts
2-127
By default, the editors in Design mode use their own preferred layouts. You can choose to
ignore layout preferences for any one editor or for all editors in Design mode, if you wish, and
to use only the one Debug layout. You will always have at least one Design and one Debug
layout.
To disable layout preferences for all editors in Design mode:
1. Open or put the focus on the editor involved.

4. On the Layouts page, deselect the Use Editor's Preferred Layout checkbox.
5. Click OK.
Related topics

Renaming Layouts
Removing Layouts
About Layouts
2-128
Renaming Layouts
Should you wish to rename a custom layout you've already defined, it is easy to do so. You
cannot rename JDeveloper's default layouts.
To rename a previously created custom layout:

3. On the Layouts page, under Available layouts select the layout you wish to rename and
click Rename.
4. In the Rename Layout dialog, alter the name of the layout and click OK.
Related topics

Removing Layouts
About Layouts
2-129
Removing Layouts
Should you wish to remove a custom layout created earlier, it is easy to do so. You cannot
remove JDeveloper's default layouts.
To remove a previously created custom layout:

3. On the Layouts page, under Available layouts select the layout you wish to rename and
click Delete.
Deletion is immediate. There is no confirmation dialog. For more information, click Help.
4. Click OK.
Related topics

Renaming Layouts
About Layouts
2-130
Customizing the Component Palette
When customizing the Component Palette, you can choose to:
● Add a page
● Add a component
● Remove a page
● Remove a component
Related topics
Customizing the IDE

Customizing the IDE Environment
Arranging the Windows in the IDE
2-131
Adding a Page to the Palette
To add a page to the Palette:
1. In the Navigator, select a component node.
If source files are open in editors or viewers, double-click the file to render it active.
2. From the main menu, choose Tools | Configure Palette.

3. In the Configure Component Palette dialog, click New Page .
4. In the New Palette Page dialog, enter the name of the new page and select a type from
the dropdown list.
5. Click OK to return to the Configure Component Palette dialog.

Related topics

Adding a Component to the Palette
Removing a Page from the Palette
Removing a Component from the Palette
2-132
The components you can add to the palette are dependent upon the type of node selected in
the Navigator.
To add a component to the Palette:

3. In the Configure Component Palette dialog, optionally select the page type you wish to
view.
4. In the Pages list box, select the page to which you wish to add a component, and click
Add Component.
Depending upon the page type selected, either the Add JavaBeans dialog or the
JavaServer Page Tag Libraries dialog now appears.
5. In the dialog, fill in the appropriate details for the new component.
6. Click OK to return to the Configure Component Palette dialog.

Related topics

2-133
Note that if you remove a page supplied by JDevelope, the only way to recover it again is to
restore the Component Palette settings from the defaults.
To remove a page from the Palette:

3. In the Configure Component Palette dialog, select the page to be removed and click
Delete Page.
If the page cannot be removed, an illegal request dialog appears.
4. In the Remove Palette Page dialog, click Yes to confirm removal.

5. In the Palette Properties dialog, click OK.
Related topics

2-134
To remove a component from the Palette:

3. In the Configure Component Palette dialog, select the page from which you wish to
remove a component, select the component to be removed, and click Remove
Component.
If the component cannot be removed, an illegal request dialog appears.
4. In the confirmation dialog, click Yes to confirm removal.

5. In the Configure Component Palette dialog, click OK.
Related topics

2-135
To customize the JDeveloper's IDE to best support your work habits, you'll want to know how
to:
● Customize its general environment

● Load, view, and customize keymaps
● Customize the Code Editor environment
Related topics
Customizing the IDE

Arranging the Windows in the IDE
About Code Insight
2-136
Customizing the General Environment for the IDE
To change the general environment settings for the IDE:

2. Select the Environment node if it is not already selected.
3. On the Environment page, select the options and set the fields as appropriate.
4. Click OK.
Related topics

Loading Preset Keymaps for the IDE
Defining Custom Accelerators for the IDE
2-137
To work effectively with keymaps, you'll want to know how to:
● Load preset keymaps

● View current accelerator assignments
● Define custom accelerators
Related topics
Classic Keymapping
Default Keymapping
Emacs Keymapping
2-138
You can take advantage of the several existing keymap sets in JDeveloper or begin with an
existing keymap and then customize it to suit your own coding style by changing which
keyboard shortcuts, or accelerators, map to which actions.
You can load a different keymap any time you would like. Note that if you load a preset keymap
after you have already customized another, your customization settings will be lost.
To load preset keymaps:

2. Select the Accelerators node.
3. On the Accelerators page, click Load Preset.
The Load Preset dialog appears, with the currently loaded keymapping highlighted.
4. In the Load Preset dialog, select the keymapping you wish to load and click OK.
5. On the Accelerators page, if you are finished, click OK.
Alternately, you can customize individual accelerators if you wish.
Related topics

Viewing Current Accelerator Assignments in Keymaps
Defining Custom Accelerators for Keymaps
2-139
Viewing Current Accelerator Assignments in
Keymaps
You can view the current accelerator assignments for any keymap and then alter those
assignments if you would like. Note that if you load a preset keymap after you have already
customized another, your customization settings will be lost.
To view the current assignment (if any) for an accelerator in a given keymap set:

3. On the Accelerators page, select All in the Category list and About in the Actions list.
4. With the focus on the New Accelerator field, enter the accelerator by pressing the key
combination on the keyboard.
If this accelerator is assigned in the current keymap, the command it is assigned to will
appear in the Currently Assigned To field. If this accelerator is not assigned, the field will
remain blank.
If you wish, you can assign a new action to this accelerator, whether or not it is currently
assigned. If you assign an action to an accelerator that previously had one associated
with it, the previous assignment is removed.
To view the accelerator assigned (if any) to a given action:

3. On the Accelerators page, select the appropriate category (or select All) and then select
the action you wish to check in the Actions listing just below.
If there is an accelerator currently assigned to this action, it now appears in the

Accelerators field. If no accelerator is assigned, the field remains blank.
If you wish, you can assign an accelerator to this action, whether or not it already has an
2-140
accelerator associated with it. If it already has an accelerator associated with it, the new
accelerator you add will not replace the existing assignment(s). Until you explicitly
remove any previously assigned accelerators, they too will remain in effect.
Related topics

2-141
You can define custom accelerators for any action within a keymap. Note that if you load a
preset keymap after you have already customized another, your customization settings will be
lost.
To define new accelerators for a command within a given keymap set:

3. On the Accelerators page, select the category for which you wish to define accelerators
and then select an action in the listing just below.
The accelerator currently assigned appears in the Accelerators field.
4. If you wish to assign a new accelerator to this action, enter that accelerator in the New
Accelerator field by putting the focus in the field and then pressing the key combination
on the keyboard.
If this proposed accelerator already has an action associated with it, that action will now
appear in the Currently Assigned To field below.
5. To add this accelerator to the action selected, click Add.
Note that the old accelerator is not removed. The new accelerator is simply added.
6. When you are finished, click OK.
To remove an existing accelerator from a keymap set:
1. Begin as you would for defining a new accelerator, navigating to the Accelerators page of
the Preferences dialog.
Existing accelerators appear in the Accelerators field for actions selected in the Actions
2-142
listing.
2. When the accelerator you wish to be rid of appears in the Accelerators field, select it and
click Remove.
3. Alternately, you can redefine it for another action and it will automatically disappear from
any existing listing.
Related topics

Viewing Current Accelerator Assignments in Keymaps
2-143
To customize the Code Editor to best support your work habits, you'll want to know how to:
● Set tabs
● Set scrolling options
● Set display options
● Set fonts
● Define syntax highlighting
● Customize Code Insight options
● Define undo behavior
● Define code completion templates
Additionally, you can customize options for editing XML, HTML, and JSP files.
Related topics

2-144
Setting Tabs for the Code Editor
To set the tabs for the Code Editor:

2. Select the Editor node.
3. On the Editor page, under Tab Settings, enter a margin for tabs and select the other tab
options as desired.
4. Click OK.
Related topics

2-145
Setting Scrolling Options for the Code Editor
To set scrolling options for the Code Editor:

2. Select the Editor node.
3. On the Editor page, under Miscellaneous Settings, select the desired combination of
options.
4. Click OK.
Related topics

2-146
Setting Display Options for the Code Editor
To set display options for the Code Editor:

2. Expand the Editor node.
3. Select the Display node.
4. On the Display page, enter a value for the right margin column.
5. Select or deselect the options for displaying a visible right margin and line numbers.
6. Click OK.
Related topics

2-147
Setting Fonts for the Code Editor
To set fonts for the Code Editor:

3. Select the Fonts node.
4. On the Fonts page, select a font type and size. Alter the sample text, if you wish. The
sample text display reflects your font changes.
By default, all your system fonts are loaded. To limit the fonts available on this page to
fixed-width fonts, select the Display Only Fixed-Width Fonts checkbox.
5. Click OK.
Related topics

2-148
Defining Syntax Highlighting for the Code Editor
To define syntax hightlighting for the Code Editor:

3. Select the Syntax Colors node.
4. On the Syntax Colors page, begin by selecting the appropriate category for the syntax
you wish to work with.
The display on the page changes to reflect the current settings for the first style listed in
this category, which is highlighted.
5. With the category displayed above, select any individual style in the Available styles
listing to view its current settings.
6. Select a font style and set the background and foreground color as desired. The sample
text changes accordingly.
7. Click OK.
Related topics

2-149
Customizing Code Insight Options for the Code
Editor
To customize Code Insight options for the Code Editor:

3. Select the Code Insight node.
4. On the Code Insight page, select the appropriate checkboxes to enable completion
insight or parameter insight and use the sliding bar to set the delay time for auto popup.
5. Click OK.
Related topics

About Code Insight
2-150
Defining Undo Behavior for the Code Editor
To define undo behavior for the Code Editor:

3. Select the Undo Behavior node.
4. On the Undo Behavior page, use the slider bar to set the number of actions of the same
type to be combined into one undo.
5. Select or deselect the options for combining insert and replace edits and for combining
the deletion of next and previous characters.
6. If you wish to be able to undo navigation-only changes, select the appropriate checkbox.
If you enable this setting, use the slide bar to set the number of navigation changes to be
combined into one undo.
7. Click OK.
Related topics

2-151
Defining Code Completion Templates for the Code
Editor
Code completion templates assist you in writing code more quickly and efficiently while you are
in the Code Editor. You can edit the existing completion templates or create your own. To
evoke the completion template while in the editor, press Ctrl-Enter after typing the beginning of
the line, as defined by the shortcut.
To view existing code completion templates:

3. Select the Code Templates node.
4. On the Code Templates page, scroll through the shortcuts, which represent the letters
typed before you can evoke a template.
5. Click on any shortcut to view its template code, displayed below the shortcuts under the
Code tab. If there are any imports associated with this template, they will be listed under
the Imports tab.
To edit existing code completion templates:

4. On the Code Templates page, make any changes to shortcuts that you would like,
adding or deleting the letters to be typed.
5. Make any changes to the code that you would like. Before saving changes, be sure to
place the cursor at the logical insertion point for new code, as it is remembered in the
template.
6. Make any necessary changes to the imports.
To define a new code completion template:
2-152
4. On the Code Templates page, click Add.
The cursor jumps to the bottom of the Shortcut listing and a new row is added.
5. Type in the name for the new shortcut and add a description in the listing next to it.
6. Click on the Code tab below and enter the code that defines this template. Note that
cursor position is a part of the template, representing the logical insertion point for new
code to be entered when the template is used.
7. Click on the Imports tab and enter any imports associated with this template.
8. Click OK.
Related topics

2-153
Related Reference Topics
You may find the following reference topics useful while editing source code and configuring
connections:
● Classic Keymapping
● Default Keymapping
● Default CDE Keymapping
● Default KDE2 Keymapping
● Emacs Keymapping
● Visual C++ Keymapping
● Regular Expressions
● JDeveloper's Connection Requirements for Oracle's Type 2 Drivers (OCI)
Related topics
Managing Your Work Using Workspaces and Project

Configuring Connections
2-154
Classic Keymapping
The classic keystroke mapping scheme provides keybindings that match the Delphi
programming environment.
Keymaps are loaded and customized from the Preferences dialog. With the classic keymap
loaded, from the same dialog you can individually check the assignment of any accelerator or
check whether a given action has an accelerator already assigned to it.
For your reference, listed here is the entire set of accelerator assignments for the classic
keymapping as defined in JDeveloper. In addition to the accelerators listed below, the keyboard
combination Alt+Minus opens the context menu for all dockable windows. Unlike the other
accelerators, this accelerator is not configurable.
Code Editor commands Accelerators

block-indent Ctrl+K, Ctrl+I
block-outdent Ctrl+K, Ctrl+U
cancel Escape
caret-backward Left
caret-backward Ctrl+S
caret-begin Ctrl+Home
caret-begin Ctrl+Q, Ctrl+R
caret-begin-line Home
caret-begin-line Ctrl+Q, Ctrl+S
caret-down Down
caret-down Ctrl+X
caret-end Ctrl+End
caret-end Ctrl+Q, Ctrl+C
caret-end-line End
caret-end-line Ctrl+Q, Ctrl+D
caret-forward Right
caret-forward Ctrl+D
caret-next-word-start Meta+Right
caret-next-word-start Ctrl+F
caret-next-word-start Ctrl+Right
caret-previous-word-start Alt+Left
caret-previous-word-start Ctrl+A
2-155
caret-previous-word-start Ctrl+Left
caret-up Up
caret-up Ctrl+E
completion-insight Ctrl+Space
copy-to-clipboard Ctrl+K, Ctrl+C
cut-to-clipboard Shift+Delete
cut-to-clipboard Ctrl+K, Ctrl+Y
delete-line Ctrl+Y
delete-next Delete
delete-next Ctrl+G
delete-next-word-start Ctrl+T
delete-previous Backspace
delete-previous-word-start Ctrl+Backspace
delete-until-eol Ctrl+Q, Ctrl+Y
delete-until-eol Ctrl+Enter
goto-matching-brace Ctrl+Q, Ctrl+]
goto-matching-brace Ctrl+Q, ]
goto-matching-brace Ctrl+Q, Ctrl+[
goto-matching-brace Ctrl+Q, [
insert-break Enter
insert-tab Tab
open-line Shift+Enter
page-down Page Down
page-down Ctrl+C
page-up Alt+V
page-up Ctrl+R
page-up Page Up
paste-from-clipboard Shift+Insert
paste-from-clipboard Ctrl+K, Ctrl+V
recenter-line Ctrl+M
reverse-tab Shift+Tab
scroll-line-down Ctrl+Down
scroll-line-down Ctrl+Z
scroll-line-up Ctrl+Up
scroll-line-up Ctrl+W
2-156
selection-backward Shift+Left
selection-begin Shift+Home
selection-down Shift+Down
selection-end Shift+End
selection-forward Shift+Right
selection-next-word-start Ctrl+Shift+Right
selection-page-down Shift+Page Down
selection-page-up Shift+Page Up
selection-previous-word-start Ctrl+Shift+Left
selection-up Shift+Up
set-local-tabsize-2 Ctrl+2
toggle-insert-mode Ctrl+V
toggle-insert-mode Insert
tooltip-insight Ctrl+Shift+Space
transpose-chars Ctrl+O, Ctrl+T
unselect Ctrl+K, Ctrl+H
Global commands Accelerators

CodeTemplate.EXPAND Ctrl+Enter
ComponentPaletteCommand Ctrl+Shift+P
ContextHelp F1
DebugCodeEditorToggleBreakpointCommand F5
DebugContinueStepCommand Shift+F8
DebugProjectCommand Shift+F9
DebugResetCommand Ctrl+F2
DebugResumeCommand F9
DebugRunToCursorCommand F4
DebugStepIntoCommand F7
DebugStepOutCommand Shift+F7
DebugStepOverCommand F8
DOCUMENT_1_CMD_ID Alt+1
2-157
DOCUMENT_ASSIGN_1_CMD_ID Alt+Shift+1
DOCUMENT_CLOSE_IMPLICIT_CMD_ID Ctrl+Shift+F4
Ide.BROWSE_SYMBOL_CMD_ID Ctrl+Minus
Ide.BROWSE_SYMBOL_CMD_ID Ctrl+O, Ctrl+B
Ide.CLOSE_EDITOR_CMD_ID Alt+F3
Ide.CLOSE_EDITOR_CMD_ID Ctrl+K, Ctrl+Q
Ide.CONTEXT_MENU_CMD_ID Shift+F10
Ide.COPY_CMD_ID Ctrl+K, Ctrl+C
Ide.COPY_CMD_ID Ctrl+Insert
Ide.CUT_CMD_ID Ctrl+K, Ctrl+Y
Ide.CUT_CMD_ID Shift+Delete
Ide.DELETE_CMD_ID Delete
Ide.EXIT_CMD_ID Ctrl+K, Ctrl+X
Ide.FIND_CMD_ID Ctrl+Q, Ctrl+F
Ide.GOTO_LINE_NUMBER_CMD_ID Ctrl+J
Ide.GOTO_LINE_NUMBER_CMD_ID Ctrl+O, Ctrl+G
Ide.INCREMENTAL_SEARCH_BACKWARD_CMD_ID Alt+Shift+B
Ide.INCREMENTAL_SEARCH_FORWARD_CMD_ID Ctrl+Shift+S
Ide.INSPECTOR_CMD_ID Ctrl+Shift+R
Ide.LOG_WINDOW_CMD_ID Ctrl+Shift+L
2-158
Ide.NAVIGATE_CMD_ID Alt+Home
Ide.NEW_NAVIGATOR_CMD_ID Alt+Shift+N
Ide.NEXT_EDITOR_CMD_ID Ctrl+F6
Ide.NEXT_EDITORFRAME_CMD_ID Ctrl+Tab
Ide.NEXT_EDITORFRAME_CMD_ID Ctrl+N
Ide.NEXTMSG_CMD_ID Alt+F8
Ide.OPEN_CMD_ID Ctrl+K, Ctrl+E
Ide.PASTE_CMD_ID Ctrl+K, Ctrl+V
Ide.PASTE_CMD_ID Shift+Insert
Ide.PREV_EDITORFRAME_CMD_ID Ctrl+Shift+Tab
Ide.PREV_EDITORFRAME_CMD_ID Ctrl+P
Ide.PREV_EDITORFRAME_CMD_ID Ctrl+Shift+F6
Ide.PREVMSG_CMD_ID Alt+F7
Ide.PRINT_CMD_ID Ctrl+K, Ctrl+P
Ide.REDO_CMD_ID Alt+U
Ide.REDO_CMD_ID Alt+Shift+Backspace
Ide.REPLACE_CMD_ID Ctrl+Q, Ctrl+A
Ide.SAVE_CMD_ID Ctrl+K, Ctrl+S
Ide.SAVE_CMD_ID F2
Ide.SEARCH_AGAIN_CMD_ID F3
Ide.SEARCH_AGAIN_CMD_ID Ctrl+L
Ide.SEARCH_BACKWARD_CMD_ID Shift+F3
Ide.SELECT_ALL_CMD_ID Ctrl+Shift+A
Ide.SYSTEM_CMD_ID Ctrl+Shift+N
Ide.UNDO_CMD_ID Ctrl+U
Ide.UNDO_CMD_ID Alt+Backspace
JCompiler.BUILD_PROJECT_CMD_ID Alt+F9
JCompiler.BUILD_SELECTED_CMD_ID Alt+Shift+F9
JCompiler.MAKE_PROJECT_CMD_ID Ctrl+F9
JCompiler.MAKE_SELECTED_CMD_ID Ctrl+Shift+F9
RunProjectCommand F11
SHOW_DROPDOWN_CMD_ID Alt+0
2-159
Related topics

2-160
Default Keymapping
The default keystroke mapping scheme provides keybindings that match the CUA standard.
Keymaps are loaded and customized from the Preferences dialog. With the default keymap
For your reference, listed here is the entire set of accelerator assignments for the default

block-indent Ctrl+Shift+I
block-outdent Ctrl+Shift+U
cancel Escape
caret-backward Left
caret-down Down
caret-end Ctrl+End
caret-end-line End
caret-forward Right
caret-up Up
copy-to-clipboard Copy
copy-to-clipboard Ctrl+C
cut-to-clipboard Cut
cut-to-clipboard Ctrl+X
delete-line Ctrl+Y
delete-next Delete
delete-previous Shift+Backspace
2-161
delete-until-eol Ctrl+Shift+Y
goto-matching-brace Alt+]
goto-matching-brace Alt+[
insert-break Shift+Enter
insert-break Enter
insert-tab Tab
page-down Page Down
page-up Page Up
paste-from-clipboard Paste
paste-from-clipboard Ctrl+V
select-all Ctrl+A
selection-begin Ctrl+Shift+Home
selection-begin-line Shift+Home
selection-end Ctrl+Shift+End
selection-end-line Shift+End
unselect Ctrl+\
2-162
ContextHelp F1
FindNextAtCursorCommand Ctrl+F3
FindPreviousAtCursorCommand Ctrl+Shift+F3
2-163
Ide.CLOSE_EDITOR_CMD_ID Ctrl+F4
Ide.CLOSE_NODE_CMD_ID Ctrl+W
Ide.COPY_CMD_ID Ctrl+C
Ide.CUT_CMD_ID Ctrl+X
Ide.EXIT_CMD_ID Alt+F4
Ide.EXPLORER_CMD_ID Ctrl+Shift+S
Ide.FIND_CMD_ID Ctrl+F
Ide.GOTO_LINE_NUMBER_CMD_ID Ctrl+G
Ide.INCREMENTAL_SEARCH_BACKWARD_CMD_ID Ctrl+Shift+E
Ide.INCREMENTAL_SEARCH_FORWARD_CMD_ID Ctrl+E
Ide.NEXT_EDITORFRAME_CMD_ID Ctrl+F6
Ide.OPEN_CMD_ID Ctrl+O
Ide.PASTE_CMD_ID Ctrl+V
Ide.PRINT_CMD_ID Ctrl+P
Ide.REDO_CMD_ID Ctrl+Shift+Z
Ide.REMOVE_FILE_CMD_ID Ctrl+Delete
Ide.REPLACE_CMD_ID Ctrl+R
Ide.SAVE_CMD_ID Ctrl+S
2-164
Ide.SELECT_ALL_CMD_ID Ctrl+A
Ide.UNDO_CMD_ID Ctrl+Z
ObjectGalleryCommand Ctrl+N
Related topics

2-165
The default CDE keystroke mapping scheme provides keybindings that emulate the CDE
editor.
Keymaps are loaded and customized from the Preferences dialog. With the default CDE
keymap loaded, from the same dialog you can individually check the assignment of any
accelerator or check whether a given action has an accelerator already assigned to it.
For your reference, listed here is the entire set of accelerator assignments for the default CDE

cancel Escape
caret-backward Left
caret-down Down
caret-end Ctrl+End
caret-end-line End
caret-forward Right
caret-up Up
delete-next Delete
2-166
insert-break Enter
insert-tab Tab
page-down Page Down
page-up Page Up
select-all Ctrl+A
unselect Ctrl+\
2-167
ContextHelp F1
ContextHelp Shift+F1
DebugCodeEditorWatchCommand Ctrl+F5
2-168
Ide.INSPECTOR_CMD_ID Ctrl+Shift+I
Ide.REDO_CMD_ID Ctrl+Y
2-169
Ide.SELECT_ALL_CMD_ID Ctrl+/
JCompiler.BUILD_PROJECT_CMD_ID Ctrl+Shift+B
JCompiler.BUILD_SELECTED_CMD_ID Ctrl+B
JCompiler.MAKE_PROJECT_CMD_ID Ctrl+Shift+M
JCompiler.MAKE_SELECTED_CMD_ID Ctrl+M
SQL commands Accelerators

SQL_ExecSql_Command Alt+Enter
SQL_ExpPl_Command Alt+Shift+Enter
Related topics

2-170
The default KDE2 keystroke mapping scheme provides keybindings that emulate the KDE2
editor.
Keymaps are loaded and customized from the Preferences dialog. With the default KDE2
keymap loaded, from the same dialog you can individually check the assignment of any
accelerator or check whether a given action has an accelerator already assigned to it.
For your reference, listed here is the entire set of accelerator assignments for the default KDE2

cancel Escape
caret-backward Left
caret-down Down
caret-end Ctrl+End
caret-end-line End
caret-forward Right
caret-up Up
delete-next Delete
2-171
insert-break Enter
insert-tab Tab
page-down Page Down
page-up Page Up
select-all Ctrl+A
unselect Ctrl+\
2-172
ContextHelp F1
ContextHelp Shift+F1
DebugCodeEditorWatchCommand Ctrl+F5
2-173
Ide.INSPECTOR_CMD_ID Ctrl+Shift+I
2-174
Ide.SELECT_ALL_CMD_ID Ctrl+/
JCompiler.BUILD_PROJECT_CMD_ID Ctrl+Shift+B
JCompiler.BUILD_SELECTED_CMD_ID Ctrl+B
JCompiler.MAKE_PROJECT_CMD_ID Ctrl+Shift+M
JCompiler.MAKE_SELECTED_CMD_ID Ctrl+M
SQL commands Accelerators

SQL_ExecSql_Command Alt+Enter
SQL_ExpPl_Command Alt+Shift+Enter
Related topics

2-175
Emacs Keymapping
The Emacs keystroke mapping scheme provides keybindings that match the Emacs standard.
Keymaps are loaded and customized from the Preferences dialog. With the Emacs keymap
For your reference, listed here is the entire set of accelerator assignments for the Emacs

cancel Ctrl+G
caret-backward Left
caret-backward Ctrl+B
caret-begin-line Ctrl+A
caret-down Down
caret-down Ctrl+N
caret-end-line Ctrl+E
caret-forward Right
caret-forward Ctrl+F
caret-next-word-end Ctrl+[, F
caret-next-word-end Escape, F
caret-next-word-end Meta+F
caret-next-word-end Alt+F
caret-next-word-end Meta+Right
caret-next-word-end Alt+Right
caret-next-word-end Ctrl+Right
caret-previous-word-start Ctrl+[, B
caret-previous-word-start Escape, B
caret-previous-word-start Meta+B
caret-previous-word-start Alt+B
caret-previous-word-start Meta+Left
caret-previous-word-start Alt+Left
2-176
caret-up Up
caret-up Ctrl+P
completion-insight Meta+Space
completion-insight Alt+Space
completion-insight Ctrl+[, Space
completion-insight Escape, Space
delete-next Delete
delete-next Ctrl+D
emacs-append-next-kill Meta+Ctrl+W
emacs-append-next-kill Ctrl+Alt+W
emacs-append-next-kill Ctrl+[, Ctrl+W
emacs-append-next-kill Escape, Ctrl+W
emacs-backward-kill-word Ctrl+Delete
emacs-backward-kill-word Ctrl+[, Backspace
emacs-backward-kill-word Meta+Backspace
emacs-backward-kill-word Alt+Backspace
emacs-backward-kill-word Escape, Backspace
emacs-capitalize-word Ctrl+[, C
emacs-capitalize-word Escape, C
emacs-capitalize-word Meta+C
emacs-capitalize-word Alt+C
emacs-caret-begin Meta+Shift+,
emacs-caret-begin Alt+Shift+,
emacs-caret-begin Meta+Less
emacs-caret-begin Alt+Less
emacs-caret-begin Ctrl+[, Shift+,
emacs-caret-begin Ctrl+[, Less
emacs-caret-begin Escape, Shift+,
emacs-caret-begin Escape, Less
emacs-caret-begin Home
emacs-caret-end Meta+Shift+.
2-177
emacs-caret-end Meta+Greater
emacs-caret-end Alt+Shift+.
emacs-caret-end Alt+Greater
emacs-caret-end Ctrl+[, Shift+.
emacs-caret-end Ctrl+[, Greater
emacs-caret-end Escape, Shift+.
emacs-caret-end Escape, Greater
emacs-caret-end End
emacs-delete-horizontal-space Alt+\
emacs-delete-horizontal-space Meta+\
emacs-delete-horizontal-space Ctrl+[, \
emacs-delete-horizontal-space Escape, \
emacs-downcase-region Ctrl+X, Ctrl+L
emacs-downcase-word Ctrl+[, L
emacs-downcase-word Escape, L
emacs-downcase-word Meta+L
emacs-downcase-word Alt+L
emacs-exchange-point-mark Ctrl+X, Ctrl+X
emacs-kill-line Ctrl+K
emacs-kill-region Shift+Delete
emacs-kill-region Ctrl+W
emacs-kill-ring-save Meta+W
emacs-kill-ring-save Alt+W
emacs-kill-ring-save Ctrl+[, W
emacs-kill-ring-save Escape, W
emacs-kill-ring-save Ctrl+Insert
emacs-kill-word Ctrl+[, D
emacs-kill-word Meta+D
emacs-kill-word Alt+D
emacs-kill-word Escape, D
emacs-mark-whole-buffer Ctrl+X, H
emacs-set-mark Ctrl+Shift+2
emacs-set-mark Ctrl+At
emacs-set-mark Ctrl+Space
emacs-upcase-region Ctrl+X, Ctrl+U
2-178
emacs-upcase-word Ctrl+[, U
emacs-upcase-word Escape, U
emacs-upcase-word Meta+U
emacs-upcase-word Alt+U
emacs-yank Shift+Insert
emacs-yank Ctrl+Y
emacs-yank-pop Meta+Y
emacs-yank-pop Alt+Y
emacs-yank-pop Ctrl+[, Y
emacs-yank-pop Escape, Y
insert-break Enter
insert-tab Tab
open-line Ctrl+O
page-down Page Down
page-down Ctrl+V
page-up Page Up
page-up Meta+V
page-up Alt+V
page-up Ctrl+[, V
page-up Escape, V
recenter-line Ctrl+L
selection-begin Shift+Home
selection-end Shift+End
selection-next-word-end Ctrl+Shift+Right
2-179
tooltip-insight Meta+Shift+Space
tooltip-insight Alt+Shift+Space
tooltip-insight Ctrl+[, Shift+Space
tooltip-insight Escape, Shift+Space
transpose-chars Ctrl+T

ContextHelp F1
2-180
Ide.CLOSE_EDITOR_CMD_ID Ctrl+X, K
Ide.GOTO_LINE_NUMBER_CMD_ID Alt+O, G
Ide.INCREMENTAL_SEARCH_BACKWARD_CMD_ID Ctrl+R
Ide.INCREMENTAL_SEARCH_FORWARD_CMD_ID Ctrl+S
Ide.OPEN_CMD_ID Ctrl+X, Ctrl+F
Ide.SAVE_ALL_CMD_ID Ctrl+X, S
Ide.SAVE_AS_CMD_ID Ctrl+X, Ctrl+W
Ide.SAVE_CMD_ID Ctrl+X, Ctrl+S
Ide.SELECT_ALL_CMD_ID Ctrl+X, H
Ide.UNDO_CMD_ID Ctrl+/
2-181
Ide.UNDO_CMD_ID Ctrl+Shift+Minus
Ide.UNDO_CMD_ID Ctrl+Underscore
ObjectGalleryCommand Alt+O, N
Related topics

2-182
The Visual C++keystroke mapping scheme provides keybindings that match the Visual C++
standard.
Keymaps are loaded and customized from the Preferences dialog. With the Visual C++ keymap
For your reference, listed here is the entire set of accelerator assignments for the Visual C++

ContextHelp F1
Ide.BROWSE_SYMBOL_CMD_ID Alt+F12
Ide.INCREMENTAL_SEARCH_BACKWARD_CMD_ID Ctrl+Shift+I
2-183
Ide.INCREMENTAL_SEARCH_FORWARD_CMD_ID Ctrl+I
Ide.INSPECTOR_CMD_ID Alt+Enter
Ide.LOG_WINDOW_CMD_ID Alt+2
Ide.NEXTMSG_CMD_ID F4
Ide.PREVMSG_CMD_ID Shift+F4
Ide.PROJECT_SETTINGS_CMD_ID Alt+F7
Ide.REPLACE_CMD_ID Ctrl+H
Ide.SYSTEM_CMD_ID Alt+0
Related topics

2-184
2-185
Regular Expressions
Regular expressions are characters that customize a search string. JDeveloper recognizes the
following expressions in all environments.
Character Description
^ A circumflex at the start of the string matches the start of a line.
A dollar sign at the end of the expressions matches the end of a

$
line.
. A period matches any character.
An asterisk after a string matches any number of occurrence of

* that string followed by any characters, including zero characters.
For example, bo* matches boo, booo, and bo but not be.
A plus sign after a string matches any number of occurrences of

+ that string followed by any characters. For example, bo+ matches
boo and booo, but not bo or be.
Characters in brackets match any one character that appears in

[]
the brackets, but no others. For example, [bot] matches b, o, or t.
A circumflex at the start of the string in brackets means "not."

[^ ]
Thus, [^bot] matches any characters except b, o, or t.
A hyphen within brackets signifies a range of characters. For

[-]
example, [b-o] matches any character from b through o.
Braces group characters or expressions. Groups can be nested,

with a maximum number of 10 groups in a single pattern. For the
Replace operation, the groups are referred to by a backslash and
{} a number according to the position in the "Text to find" expression,
beginning with 0. For example, given the text to find and
replacement strings Find: {[0-9]}{[a-c]*}, Replace: NUM\1, the
string 3abcabc is changed to NUMabcabc.
A backslash before a wildcard character tells the code editor to

\ treat that character literally, not as a wildcard. For example, \^
matches ^ and does not look for the start of a line.
2-186
JDeveloper's Connection Requirements for Oracle's
Type 2 JDBC Drivers (OCI)
When you create connections using Oracle's JDBC/OCI drivers, you must be
aware of the following details:
● You must have the required native libraries (.dll files on Windows, and
.so/.sl files on UNIX).
With the Oracle Type 2 driver (JDBC/OCI), the version of the JDBC driver must match
the version of the Oracle Home. For example, the Oracle JDBC Driver version 9.0.1
requires that the Oracle Home contain version 9.0.1 of the ocijdbc9.dll, as well as
the Oracle Network software and Required Support Files.
If you are connecting to a local database which is a different version from the JDBC
driver you are using, then you must install the Oracle client software into a separate
Oracle Home, and connect via the Oracle Net Listener.
● You must place the ORACLE_HOME directory in which the client-side file for the required
native libraries resides listed in your PATH environment variable.
❍ On Windows: List the %ORACLE_HOME%\bin directory in which the client-side DLL
file resides in your PATH environment variable.
If you have multiple Oracle Homes installed on your machine, use the Oracle
Home Switch utility to choose the correct Oracle Home.
❍ On UNIX: List the ${ORACLE_HOME}/lib directory in which the client-side

.so/.sl file resides in your PATH environment variable.
● If your Oracle Home for the OCI driver is not the same as the Oracle Home in which
JDeveloper is installed, you must either set the ORACLE_HOME environment variable or
edit {$ORACLE_HOME}/jdev/bin/jdev.conf with a line similar to the following,
replacing the path shown with the full path to your Oracle Home:
❍ On Windows: AddNativeCodePath C:/ORACLE/ORA90/BIN
❍ On UNIX: AddNativeCodePath /u01/app/oracle/product/9.0.1/lib
This command will allow JDeveloper to properly update the java.library.path in

2-187
which the Java VM searches for shared libraries.
Related topics
About Connections
2-188
Tutorials
● Tutorials
❍ Creating and Populating the Sample Schema Tables
❍ Creating a Connection to Use With the Online Help

❍ Building a Simple Java Application
■ Creating a New Workspace and Project
■ Creating a User Interface

■ Creating an Application for Your UI
■ Using the Debugger
■ Compiling and Running Your Application
❍ Modeling Java Classes

■ Creating a Model of Java Classes
■ Generating Java Source Code from the Class Model

■ Extending the Model by Reverse-Engineering
❍ Business Components Basic Tutorial

■ Creating a JDeveloper Workspace and Project
■ Creating a Database Connection

■ Creating a Class Diagram
■ Creating View Objects
■ Creating a Master-Detail View Link
■ Creating an Application Module
■ Testing the Business Logic Tier
❍ Business Components Programmatic Client Tutorial

■ Requirements
■ Creating a Business Components Project

■ Initializing the Batch Client
■ Finding and Displaying Data by Primary Key
■ Invoking a Custom Business Logic Method
■ Displaying Detail Data
3-1
■ Making and Committing Updates
■ Reviewing What You've Learned
❍ Creating JavaServer Pages with Data Tags

■ Requirements for Running the Tutorial

■ Creating a JSP Project
■ Creating a JSP Based on the Customers View
■ Creating a JSP Based on the Orders View
■ Creating a Form for Editing Orders
❍ Activity Modeling and eBusiness Integration Tutorial

■ Getting Started with Activity Modeling
■ Creating an Activity Diagram

■ Creating Swimlanes
■ Creating a Hub
■ Creating Activities
■ Creating Object Flow States
■ Creating Pseudostates
■ Creating Transitions
■ Changing Font and Color Preferences
■ Review the Defined E-Business Integration
■ Generating the Integration Point Messaging Code
■ Understanding the Generated Results
❍ Creating JClient Forms for Business Components

■ Creating a JClient Project

■ Creating a JClient Data Model
■ Creating a JClient Form Based on the Orders View
■ Modifying the JClient Form
❍ Creating and Using Web Services
3-2
■ Installing, Starting and Stopping OC4J
■ Creating a Java Class
■ Creating a J2EE Web Service
■ Connecting to Oracle9i Containers for J2EE
■ Using JDeveloper to create a J2EE Web Service

■ Deploying the J2EE Web Service
■ Testing the J2EE Web Service
■ Creating a SOAP Web Service

■ Connecting to the Oracle9i SOAP Server
■ Using JDeveloper to create a SOAP Web Service

■ Deploying and Registering the SOAP Web Service
■ Testing the SOAP Web Service
3-3
JDeveloper Tutorials
These tutorials are based on the new sample schemas, which are included with Oracle9i. If you
have a previous version of Oracle or have dropped those tables, see the topic Creating and
Populating the Sample Schema Tables. For tutorials that require a connection to the database,
see the topic Connecting to the Database.
Building a Simple Java Application
The purpose of this tutorial is to introduce you to some of the most commonly used features of
JDeveloper by creating a basic application with a user interface.
Modeling Java Classes
The exercises in this tutorial show how to model Java classes in Oracle9i JDeveloper Beta. The
ability to model Java classes graphically is new in JDeveloper, and this tutorial tells you how to
use the Class Modeler to capture the basic data requirements of a system in the form of
fundamental generic classes which can be grouped together to form business objects. It then
shows you how to generated the Java source code from the class model, and finally you learn
how to extend the modelby reverse-engineering an existing class.
Developing a Business Components Application
The Business Components Application tutorial steps you through creating a simple order-entry
application. You will create a default business logic tier and add three types of validation rules.
Upon completion you can test the application using a supplied client, the Business Components
Browser. This tutorial should take you approximately one hour to complete.
Business Components Programmatic Client Tutorial
In the Business Components Programmatic Client tutorial, you will create a client for a simple
business components project. In the process, you will learn how to navigate through queries,
display data, and invoke business logic methods from clients. Although the client you create will
be a batch client, you can use the knowledge you gain in this tutorial with any client, whenever
you need control over interaction with the business logic tier beyond what is automatically
provided by other client architectures.
Creating JavaServer Pages with Data Tags
3-4
The tutorial describes the process for building a master-detail set of JavaServer pages using
component tags and BC4J generation templates. In the tutorial example, you will create an
order entry application that lets you query and update records in a master-detail scenario that
also demonstrates the associated navigation functionality.
Activity Modeling and eBusiness Integration Tutorial
In this tutorial you learn how to create activity diagrams and diagram elements, and how to
generate eBusiness integration code for messaging.
Creating JClient Forms for Business Components
This tutorial shows how to use JDeveloper to create a Java client user interface from Swing
components and the JDeveloper JClient data models to interact with business components. In
this tutorial, you will build a Business Components project which manages the business rules,
validation, and database communication. The client, in this case, provides master-detail views
of the data that you can use to navigate between rows and interact with to create, delete, or
update data.
Creating and Using Web Services
The exercises in this tutorial will introduce you to the JDeveloper features that help you to write
and deploy Web services.
3-5
Creating and Populating the Sample Schema Tables
The JDeveloper tutorials and samples are based on the Oracle9i Sample Schemas which are
included with Oracle9i. If you are using Oracle 8i you will have to install the appropriate version
of the sample schemas. This topic shows you how to install them from Windows NT onto an
Oracle 8i database.
Note: If you have dropped the sample schemas from Oracle 9i or did not install them in the first
place, you should install the Oracle9i Sample Schemas using the Database Configuration Assistant.
For more information refer to the manual Sample Schemas which is part of the Oracle9i
documentation set. It is also available on OTN (Oracle Technology Network) at http://www.otn.com.
The sample schemas for Oracle 8i comprise the following interlinked schemas:
● Human Resources (HR8)

● Order Entry (OE8)
Requirements
You need to have SQL*Plus available on your local machine, and to have a connection to the
machine on which the database is running. You also need to know the passwords for the
system and sys users.
Installing the Sample Schemas
The installation scripts are in the file

\tutorials\sample_schema_scripts\HR8_OE8.zip, which you have to expand to a
suitable location.
When you run the mksample8.sql file the following tasks are accomplished:
● Any previously installed HR8 and OE8 schemas are erased. If the schemas is being
installed for the first time, you will see SQL error messages, which you can ignore, when
the drop statements that erase previously installed objects are run.
● The users HR8 and OE8 are created. You are prompted to enter passwords for them, and
the necessary privileges are granted.
● The schema user is connected to the database.
● The remaining scripts to create and populate objects for that schema are called.
3-6
Warning: Installing the sample schemas will destroy any previously installed schemas that use
the following user names: HR8 or OE8.
To install the sample schemas:
1. Expand the file HR8_OE8.zip into a suitable location.

2. Log files are saved by default to C:\TEMP\. If you are using UNIX, or want to save the
log files to another location, you must change the occurrences of C:\TEMP\ in
mksample8.sql and pm8_p_lob.dat to your new location.
3. At the command prompt navigate to the location into which you expanded the files, and
start SQL*Plus by typing
sqlplus system/<system_password>@<machinename>
where <system_password> is the password for the system user, and

<machinename> is the name of the machine where the database is.
4. Create the HR8 and OE8 schemas by running mksample8.sql. At the SQL*Plus
prompt type @mksample8.sql.
5. The commands in this file and in the other files it calls are executed. When prompted,
enter the password for the system user.
6. When prompted, enter a password for the user hr8.
7. When prompted, enter the password for the sys user.
8. When prompted, enter a password for the user oe8.
9. The scripts create the users oe8 and hr8 in the database using the passwords you have
defined for them. The tables in the schemas are also created. You can examine the
installation process in the log files mksample8hr8_main.log and
mksample8oe8_main.log which are either in C:\TEMP\ or the other location you
defined.
After you have installed the sample schemas, you can examine them and view their objects
from within JDeveloper by creating a connection to the database, and then double clicking on
the nodes in the Navigator.
Dropping the Sample Schemas
3-7
If you want to drop the sample schemas, you can use the hr8_drop.sql and oe8_drop.sql
files. When you run these files, all objects in the schemas are removed from the database.
To drop the sample schemas:
1. Connect to a SQL*Plus session as system/<system_password>@<machinename>.

2. Drop the schemas by running (in this order):
hr8_drop.sql
oe8_drop.sql
For information about the Oracle9i Sample Schemas on which these schemas are based, refer
to the Sample Schemas documentation which is available as part of the Oracle9i Database
documentation set and on OTN (Oracle Technology Network) at http://www.otn.com. From
OTN, navigate to Documentation. Select Oracle9i Database, then HTML & PDF Oracle9i
Database Online Documentation. From the List of books, find Sample Schemas.
3-8
Creating a Connection to Use With the Online Help
This topic describes how to create a JDBC connection to use with the JDeveloper tutorials and
samples.
To define a connection:
1. In the Navigator, expand the Connections folder.

2. Right click the Database folder and choose New Connection from the context menu.
3. In the Connection Wizard, review the information on the Welcome page and click Next.
4. In Connection Name type tutorial_jdbc_connection. Click Next.
5. On the Authentication page:
❍ In the Username and Password fields, type enter the username and password. If
you are using the sample schema scripts on an Oracle9i database, consult your
database administrator. If you are using the Oracle 8i sample schemas installed
following the instructions in Creating and Populating the Sample Schema Tables,
the username and password are both oe8.
❍ Select Deploy password.
❍ Click Next.
6. On the Connection page:

❍ In the Host name field, type the name (or IP address) of the computer where the
database is located.
❍ In the SID and Port fields, type the information for this connection. If you do not
know these values, check with your database administrator.
❍ Click Next.
7. Click Test Connection. If the database is available and the connection details are
correct, you will see the message "Success". If an error occurs, verify the settings with
your database administrator. Click Next.
8. Click Finish. The connection now appears below the Database connection node in the
Navigator.
You can reuse this connection any time that you need JDBC access to this database.
3-9
Building a Simple Java Application
The exercises in this tutorial will introduce you to some of the most commonly used features of
JDeveloper by teaching you how to create a basic application: first you will create a user
interface, then you will use JDeveloper to debug your application before compiling and running
it.
The application is based on the order status code found in the Orders table of the Order Entry
schema in the Oracle9i Sample Schemas. You are going to create a user interface that allows
a customer to look up the status of an order. When the customer selects one of eleven status
codes from a dropdown list, the interface will display a meaningful message about the status of
that order.
The eleven status codes are:
Status
Meaning of Status Code
Code
0 Not fully entered
1 Entered
2 Canceled - bad credit
3 Canceled - by customer
4 Shipped - whole order
5 Shipped - replacement items
6 Shipped - backlog on items
7 Shipped - special delivery
8 Shipped - billed
9 Shipped - payment plan
10 Shipped - paid
Goals of This Tutorial
It is the goal of this tutorial to introduce Oracle9i JDeveloper by demonstrating:
● How to perform basic tasks such as creating workspaces and projects

● How to use the UI Editor in conjunction with the Property Inspector and the Component
Palette to design a simple graphical user interface
● How to hook the user interface up to your application code
● How to run and debug the resulting application
3-10
Tasks You Will Complete
By working through this tutorial, you will:
1. Create a new workspace and project

2. Create a simple UI for the application
3. Create the application for the UI
4. Use the debugger
5. Compile and run your application
3-11
Creating a New Workspace and Project
In this section, you will be introduced to the JDeveloper integrated development environment.
In JDeveloper, the source code files that make up your programs can be organized into
projects. A project can contain one or more files representing different "tiers" of a multi-tier
application, or different subsystems of a very complex application. Projects, in turn, are
organized into workspaces. In JDeveloper, you can have more than one workspace open at
one time. A workspace might consist of multiple projects, all of which make up an entire
application.
When you launch JDeveloper for the first time, you should see the System Navigator docked on
the left. The Navigator is the main point of interaction with your source files. From it, you can
create new objects, launch editors for a specific object, and so on.
1. Select the Workspaces node in the Navigator, and from the main menu choose File |
New.
The New Gallery appears, containing objects and other source files or tools you create to
populate and manage your projects.
2. In the New Gallery, select Projects in Categories pane and Workspace in Items pane.
3. Click OK to launch the New Workspace dialog.
4. In the New Workspace dialog, note the defaults for the workspace directory and for the
workspace file. Make sure that Add a New Empty Project is selected.
By default, JDeveloper creates a folder entitled mywork within which it stores all your
project and workspace files. The directory structure is Workspacen/Projectn/src for
source files and Workspacen/Projectn/classes_g for compiled files. The .java
and .class files are stored by package, in src and classes_g respectively. The
actual workspace (.jws) file, at the first level within Workspacen, stores the
metainformation for the workspace, as does the project (.jpr) file, at the first level within
Projectn, for the project. You can also choose to save your files outside JDeveloper by
redirecting JDeveloper to this location. Every time you save your files, this directory,
whether inside or outside JDeveloper, is updated. But note that the .jws and .jpr files
do not update unless you explicitly save them or do a save on all files.
5. Click OK to accept the default values and launch the New Project dialog.
3-12
6. In the New Project dialog, click OK to accept the defaults for the project directory and the
project file.
The new workspace and its project are displayed in the Navigator.
Now that you have a skeletal workspace and project, you can create a user interface.
3-13
Creating a User Interface
In this section, you are going to create a user interface which contains a combo box, a text
field, and a button. When the user selects a status code from the dropdown list in the combo
box and clicks the button, the text field will update with the message associated with that status
code.
To create the UI, you will:
● Create a frame to contain the UI elements

● Add a combo box, text field and a button to the frame
● Edit the source code to add the status codes that appear in the combo box, and the
messages associated with each status code
● Add an event to the button so that when it is pressed, the text for the status code the
user has selected is displayed
To create a frame:
1. In the Navigator, click on the new project node, Project1.jpr, to select it. Right-click
and choose New from the context menu.
2. In the New Gallery, select Objects in the Categories pane and Frame in the Items pane
and click OK.
3. In the New Frame dialog, click OK to accept the default settings.
You can see that a new node for the frame class, Frame1.java, has been added to the
Navigator. The source code for the frame should be displayed in the Code Editor, open
now in the center portion of JDeveloper, to the right of the Navigator.
4. If the Code Editor is not visible then, with Frame1.java selected in the Navigator, right-
click and choose Code Editor from the context menu.
Take a look at the generated code and observe the classes that have been imported,
and the JFrame class that has been created.
5. With Frame1.java selected in the Navigator, right-click and choose UI Editor from the
context menu.
3-14
The UI Editor appears, displaying the empty frame that you have created. The Property
Inspector also appears, to the right of the editor.
The Property Inspector is part of the UI layout. It displays the current properties of the
selected item and allows you to use predefined attributes and methods for a class. To
open it explicitly when it has not already appeared, from the main menu choose View |
Property Inspector. If nothing that it can inspect is selected in the Navigator, and the UI
Editor is not active, it will open with an empty panel.
6. In the Structure window (below the Navigator) you can see the UI components of your
frame. Expand the tree by clicking on the + signs so that you can observe how it
changes as you add to your UI.
7. In the Property Inspector, find the title property and in the field to the right, type in
View Status Code.
Notice that when you press Enter or shift the focus, either to another property or outside
the Inspector altogether, the title bar of your UI updates to display this title. You can
change other properties of the frame, such as color or size, in the Property Inspector.
8. You are going to use the Component Palette to continue with the design of your UI. If the
Palette is not already visible, from the main menu, choose View | Component Palette. (If
the menu item is already checked, the Palette is open. Look for it above the Navigator.)
Notice the dropdown list in the Component Palette which allows you to select from the
list of available palettes.
9. If Swing is not the currently selected Palette, select it now from the dropdown list to build
your UI using Java Swing UI components.
10. In the Component Palette, you can choose to display just icons or to show the icons with
a text description. In this case, they are displayed in alphabetical order. To toggle
between the icon list views, right-click in the Palette and choose either Icon View or List
View from the context menu.
Next you will add some items to the UI.
To create a combo box, text field, and button:
1. From the Swing Component Palette, click the JComboBox icon and then click in the
frame in the UI Editor.
3-15
The combo box is now displayed in the frame at the point where you clicked.
2. Alternately, you can add components by first clicking on an icon in the Component
Palette and then clicking on the node for the UI (labeled this for the frame you are
creating) in the Structure window.
This method can be a more accurate way of creating a UI since not all components are
visible in the UI Editor.
3. Adjust the position and size of the combo box by clicking on it and dragging it until it
resembles the target example shown in Compiling and Running your Application.
To alter the position of the combo box, grab it in the middle and drag it. To alter its size,
click in it to display its grab bars and then click on any grab bar and resize smaller or
larger in one of the two directions shown by the cursor image.
4. Now you will add a text field to the frame. In the Component Palette, click the JTextField
icon and then click in the frame.
5. Once the text field appears, adjust its position and size as you did with the combo box,
again so that your frame begins to resemble the target example in Compiling and
Running your Application.
6. Now add a button to the UI. In the Component Palette, click JButton and then again
click in the frame. As you did with the other two components, adjust the position of the
button to match the target example.
7. Next you will create labels for the combo box. Click JLabel and then click in the
frame.
8. With the new JLabel selected in the frame, turn to the Property Inspector and change the
text for the label to Select Status Code:
To enter text for the label, type into the field to the right of the text property.
9. Now adjust the size and position of the label in the frame so that it is displayed to the left
of the combo box.
10. Repeat these last two steps to create a label for the text field, but this time change the
text property to Status Result:
11. Now you will change the text for the button. To do this, bring the Code Editor for
3-16
Frame1.java to the foreground (by clicking on its tab) and find the following line in the
code:
jButton1.setText("jButton1");
Change jButton1 to OK. Return to the UI Editor and note that the text on the button has
changed in the frame.
Next, you will edit the source code to add the status codes that are displayed in the combo box.
To add the status codes:
1. Return to the Code Editor and find the jbInit() function.

2. Click after the opening brace.
Notice that the opening brace appears in a different color. If you cannot see the closing
brace, which will be in the same color, scroll down until you come to it. Notice that it is
highlighted along with the opening curly brace. This brace-matching feature is very useful
if you have long or nested conditional statements or parentheses and you want to make
sure you have matched them all correctly. If the editor finds a mismatching brace or
parenthesis, it highlights the mismatch in a different color.
3. At the end, after the line this.getContentPane().add(jLabel2, null); add the

following code:
// Status Code
jComboBox1.addItem("0");
This is the code for the order status codes that will be displayed in the combo box. Notice
that the strings enclosed in quotes appear in one color in the editor and that the
3-17
comment line appears in a different color. This is an example of the Java syntax
highlighting provided by the editor. You can change these settings in the Syntax Colors
page of the Preferences dialog.
4. From the main menu, choose File | Save All to save your changes before going any
further.
Next, you will create an event so that when the user clicks OK, the message associated with
the status code is displayed.
To create the event:
1. Return to the UI Editor, select the OK button, and in the Property Inspector click the
Event tab.
2. Locate the actionPerformed event (at the top of the list), and type displayIt.
3. When you press Enter, the Code Editor should be displayed automatically with the cursor
in the correct place to add code between the curly braces of the displayIt() method.
If not, select the Code Editor tab and scroll down until you see the code for the method:
void displayIt(ActionEvent e)
{
4. Add the following code between the curly braces:
if (jComboBox1.getSelectedItem()== "0") {
jTextField1.setText("Not fully entered");
}
jTextField1.setText("Entered");
}
jTextField1.setText("Canceled - bad credit");
}
jTextField1.setText("Canceled - by customer");
}
3-18
jTextField1.setText("Shipped - whole order");
}
jTextField1.setText("Shipped - replacement items");
}
jTextField1.setText("Shipped - backlog on items");
}
jTextField1.setText("Shipped - special delivery");
}
jTextField1.setText("Shipped - billed");
}
jTextField1.setText("Shipped - payment plan");
}
jTextField1.setText("Shipped - paid");
}
5. Return to the UI Editor and select the text field.

6. In the Property Inspector locate the text property and delete the text jTextField1.
7. Locate the editable property and change it to False.
With the editable property set to False, the user will not be able to edit this field. For the
UI that you are designing this means that once the user has selected a status code from
the combo box, the next control that is enabled is the OK button.
8. Save your work before proceeding.
Now that you have created the user interface, the next task is to create an application from
which to run it. To do this, go on to Creating an Application.
3-19
Creating an Application for Your UI
Now that you have created your user interface, you have to create an application, that is, a
Java class with a main method. This is a standard requirement for a runnable Java application.
To create an application:
1. In the Navigator, select the project node, right-click, and choose New from the context
menu.
2. In the New Gallery, select Objects in the Categories pane and Application in the Items
pane, and click OK.
The New Application dialog is displayed.
3. In the dialog, for Optional Attributes, select Add Default Frame and Existing Frame, and
in the field for an existing frame type Frame1. Accept the other defaults and click OK.
Notice that the new class, Application1.java, has appeared in the Navigator.
The next task is to debug your application. Using the Debugger will show you how to use
JDeveloper's debugging features, and give you practice for debugging more complex
applications.
3-20
Using the Debugger
Now that you have created an application that will run your UI, you will practice some simple
debugging to give you a foundation for debugging more complex applications.
You do not need to set a breakpoint to use the debugger in JDeveloper, but in this task you will.
Setting a breakpoint in your source code tells the debugger explicitly where to stop.
If you do not set a breakpoint, you can:
● Start the debugger and then click Pause to stop it
Or
● Click Step Into , in which case the debugger will stop at the first executable line of
code in your program
Once you have paused the debugger, you can control specifically how you want it to reenter
your code, using the Debug menu, toolbar icons, or keyboard equivalents. The step operations
at your disposal are:
● Step Into will stop execution at the first executable line of a method called, if there is
one; otherwise it has the same behavior as Step Over .
● Step Over executes a method call and proceeds to the next executable line in the
current class.
● Step Out will finish executing a method call you have stepped into, and return to the
next executable line in the calling method.
You can also click Terminate in the toolbar at any time to exit the debugger session.
To set a breakpoint in your source code:
1. Open Frame1.java in the Code Editor.
If the file is closed, a quick way of doing this is to double-click it in the Navigator. Double-
clicking a source node in the Navigator always opens that node in its default editor.
3-21
Your source code should still be open. If it is, you can double-click its node in the
Navigator to bring it to the foreground, you can cascade your editor windows and then
select the one you want, or you can open the document bar and navigate your editor
windows that way. To open the document bar, choose View | Document Bar. Now any
files you have open display in the order you opened them. Click Frame1.java in the
document bar to open it or bring it to the foreground.
2. In the gray margin of the editor, you will see line numbers. Click on the number beside
the first line containing an if statement.
Notice that a red dot appears in place of the line number. This indicates that a breakpoint
has been set at this line in the source code. To remove a breakpoint, just click on the red
dot, and the line number appears again.
3. Display the Breakpoints window by choosing View | Debug Windows | Breakpoints. This
allows you to see information about all the breakpoints set for this workspace or project.
To run the debugger on your source code:
1. Click Debug icon to start the debugger.
Note: If the Default Run Target dialog is displayed, you have to select a Java class with a
main method to use as the default. This is the Application1.java class you created
earlier. Click Browse and navigate to \Workspace1\Project1\src\package1. Select the
file Application1.java and click Open. On the Default Run Target dialog, click OK, and
debugging continues.
A number of things now happen:
❍ A new tab opens in the log window for the debugger process, indicating that the
debugger has connected to the local process.
❍ A number of new windows are displayed:
Data—In the lower right corner of JDeveloper, this window shows local variables
and arguments that have been encountered so far. You may have to click on the
Data tab to see it.
Stack—A window below the Navigator which shows the current execution point of
the debugger in your source code.
3-22
2. When your application runs, select a status code from the combo box and click OK.
Nothing happens because the code to display the status text in the text field is never
executed. In the Code Editor, a red arrow icon appears in the margin at the line where
you set your breakpoint. This indicates the current execution point.
3. Click Step Over to step to the next line of code. The red arrow icon moves to the
next if statement. The icon at the breakpoint location is a red dot with a blue checkmark
by it, indicating that your breakpoint is now validated.
If you continue clicking Step Over, you will continue moving through the code to the next
executable line, stepping over, rather than into, the method calls.
4. In the Smart Data window, expand the this and this$0 nodes. You can see each of
the components and the classes they are based on. If you expand these further, you can
see their properties and the property values.
5. Click Resume to continue running the rest of the program.
If you had set another breakpoint, the program would continue to that point. Without
breakpoints, the debugging process will complete when you close the application being
debugged.
Once your program has completed, the debugger will exit. When you close the
application, a message to this effect appears in the Log tab of the Log window.
Now that you have debugged your application, you can compile and run it.
3-23
Compiling and Running Your Application
Now that you have finished debugging your application you can compile and run it, observe any
error messages that are displayed, and see the results of your work.
To compile and run your application:
1. In the Navigator, right-click Frame1 and choose Make from the context menu.
The Log window appears across the bottom of the JDeveloper. If any errors are
encountered during the compiling process, these appear now listed in the Compiler tab.
All other status messages appear in the Message tab.
2. Again in the Navigator, right-click Application1 and choose Run Application1.java

Your application is run and the user interface you have created is displayed.
What you see displayed should look similar to this:
3-24
Congratulations!
You should now be able to use the basic features of JDeveloper to create Java programs and
simple user interfaces. To continue exploring JDeveloper functionality, you might try clicking
through one of the more advanced tutorials or investigating the online help.
3-25
Modeling Java Classes Tutorial
The ability to model Java classes graphically is new in this release of JDeveloper. This tutorial
tells you how to use the Class Modeler to capture the basic data requirements of a system in
the form of generic classes. It then shows you how to generate the Java source code from the
class model, and finally you learn how to extend the model by reverse-engineering an existing
class. You should expect to take about 45 minutes to complete this tutorial. To work through
this tutorial you will need an installed copy of Oracle9i JDeveloper.
You have been asked to design a Java application to manage part of an order entry system,
and to present your design as a class model of the required Java classes.
The tutorial guides you through the following tasks:
● Creating a Model of Java Classes, which guides you through the steps necessary to
create a class diagram and populate it with class diagram elements.
● Generating Java Source Code from the Class Model, which shows you how to generate
Java source code from the class diagram you have created.
● Extending the Model by Reverse-Engineering an Existing Class, which describes how to

extend the model by adding an existing class to the project and adding it to the diagram.
3-26
Creating a Model of Java Classes
This task takes you through the steps required to create a class model from within JDeveloper. First, you create
a workspace and project for your work, and once you have created these you create a class diagram that you
populate with diagram elements.
To create a class diagram:
1. First create a new workspace by right-clicking the Workspaces node in the Navigator pane, then choosing
New Workspace.
2. In the New Workspace dialog, you can use the default directory or navigate to a different directory to store
your work. Name your workspace file classmodeling.jws, and make sure that the Add a new empty
project box is checked.
3. In the New Project dialog, navigate to the directory you want to use, and change the project name to
OrderEntry.jpr.
4. In the Navigator, notice that a new node labeled classmodeling.jws appears under Workspaces, and the
new project OrderEntry.jpr is underneath it. They appear in italics because they have not yet been saved.
Click the Save All button to save them, and remember to save your work from time to time.
The Structure pane also shows information about the contents of the class diagram. This can be useful if,
for example, you want to see quickly how many classes there are in a diagram and what their names are.
5. With OrderEntry.jpr highlighted in the Navigator, create the class model by invoking the New... dialog:
choose File | New.
6. In the Object Gallery, select UML Diagrams in the Categories pane, and Class Diagram in the Items
pane.
7. In the Create New Class Diagram dialog, change the package name to orderentry, and the default
class name to OEClassDiagram.
You now have a new empty class diagram displayed in the content pane. The Class Diagram Component
Palette, which contains icons to help you create your diagram, is displayed either as a floating window or
docked below the button bar. To dock or undock the Component Palette, click on the title bar and drag it
to its new position.
You can choose to display the Component Palette as just icons, or as icons with a description. Toggle
between these by selecting either Icon View or List View from the Component Palette context menu.
8. Once you have created an empty class diagram, you can start to add the various class diagram elements.
First, model an interface on the class diagram. Click the Java Interface icon on the Component
Palette to select it, then click on the class diagram.
9. Type OrderObservable as the name for the Java interface, and press Enter.
When you work with UML diagrams, you may occasionally see an ellipse(...) on an diagram element, for
example, a class. This means that there is additional information that is not displayed because of the size
of the element. To view it, resize the element.
10. Now create an operation for this interface. Move the cursor to the operations compartment of the Java
interface (just below the second line) and click. In the highlighted area type observeOrder and press
Enter.
Notice that when you create a diagram element it is displayed at the default size. To change the size, click
on the object then drag one of the handles. To move it to a new position, click on the selected element
and drag it to the new position.
3-27
11. Model a Java class on the diagram by clicking on the Java Class icon , then click on the class diagram.
Enter Order as the name of the class, and add attributes orderRef and customerContact in the
attributes compartment (just below the first line), and the operations doInvoice and doShip in the
operations compartment (just below the second line).
12. Model a realization between Order and OrderObservable. Click the Realization icon and click first
on the Order class, then on the OrderObservable interface.
13. Model the Java class MyOrder and the operation overrideMethod.
Another way of adding attributes and operations to a modeled Java class is to double-click on the class,
and enter attributes on the Attributes tab and operations on the Operations tab. Try this method so that
you become familiar with it, and while it is displayed have a look at the other properties that you can enter
or change in this dialog.
14. Model a generalization between Order and MyOrder. Click on the Generalization icon and click first
on Order and then on MyOrder.
15. Another way of modeling a Java class is to create it using a dialog. Right-click the OrderEntry project
(OrderEntry.jpr) in the Navigator, then choose New Class. In the New Class dialog enter the Name as
OrderEntrySystem and enter the Package as orderentry. Make sure that Generate default
constructor and Generate main method are not selected.
When you click OK the Java class is displayed in the Navigator, and the text of the class is displayed in
the Editor window. Edit the class in the Code Editor to add an attribute currentOrder of type Order and
an operation getCurrentOrder with a return type of Order.
16. Now add this Java class to the class diagram. Click the OEClassDiagram tab in the Editor window to
display the diagram, then click on OrderEntrySystem in the Navigator and drag it onto the diagram.
17. Associate OrderEntrySystem to Order. Click the Association icon and click first on
OrderEntrySystem and then on Order.
18. Model a Java interface called OrderListener and give it the attribute orderChanged.
19. Model a weakly aggregated association between Order and OrderListener. Click the Association
icon and click first on Order then on OrderListener. With the association highlighted press Enter
to display the Properties dialog. Select the Association Ends tab then select Aggregate (Weak) from the
Aggregate drop-down box. This defines the 'from' end of the association as weakly aggregated.
Another way of displaying the Properties dialog for a diagram element is by selecting Properties from the
context menu.
20. Model a Java interface called OrderFactory with an operation OrderEntry.
21. Model the Java classes HomeOrderFactory and BusinessOrderFactory.
22. Model a realization between HomeOrderFactory and OrderFactory, and between
BusinessOrderFactory and OrderFactory.
23. Model an association between OrderEntrySystem and OrderFactory.
24. Model the Java classes Cleared, Packed, Shipped and Invoiced.
25. Model the class OrderState, and make Cleared, Packed, Shipped and Invoiced inner classes of
OrderState. To make Cleared an inner class of OrderState, double-click Cleared to display the
Properties dialog. Click the button next to the Namespace field to display the Select Element dialog.
3-28
In the Include dialog, expand the UML Container node until you find OrderState which is the owning class,
and select it.
Notice that the namespace of Cleared now appears as orderentry::OrderState, and that
Cleared appears in the inner classes compartment of OrderState.
Repeat this for Packed, Shipped and Invoiced.
26. Model a dependency between OrderFactory and MyOrder using the Dependency icon .
27. Create a note stating that OrderFactory creates MyOrder, and attach it to the dependency. To attach
the note click the Attach icon , then click on the note and then on the dependency.
Your class diagram should now be similar to that illustrated below, but with less detail. If you like, spend some
more time working on the class diagram to add additional attributes and operations. For example, you could add
the operation isCleared to the Java class Order. You can change the return type to boolean by editing the
default of void on the class diagram.
3-29
Now that you have created the class diagram, you are ready to proceed to the next task, Generating Java
Source Code from the Class Model, which shows you how to generate Java source code from the class diagram
you have created.
3-30
Generating Java Source Code from the Class Model
This task takes you through the steps required to generate Java source code from the class
model you have created. Once you have generated the Java source code you will update the
code and observe the effect this has on the diagram. This shows how JDeveloper synchronizes
the code and class model.
To generate source code from a class diagram:
1. First you will generate Java source code for the Java interface OrderObservable and
the Java class Order. Select OrderObservable, and holding down the CTRL key,
select Order so that they both have visible handles. Choose Generate | Java from the
context menu. Notice that these Java classes now appear in the Navigator as
OrderObservable.java and Order.java.
2. Next, examine the Java source code that has been generated for these classes by
double-clicking the file's node in the Navigator.
3. In the code view of the Order Java class, add the operation isPacked(), and make the
return type boolean. Go back to the class diagram and see how this change is reflected
in the diagram.
Now that you have generated source code from the class diagram, you are ready to proceed to
the last part of the tutorial, Extending the Model by Reverse-Engineering an Existing Class,
which describes how to extend the model by adding an existing class to the project and adding
it to the diagram.
3-31
Extending the Model by Reverse-Engineering an
Existing Class
This final task shows you how to extend the model by adding an existing class to the project
and adding it to the diagram.
To extend the class model:
1. Right-click the project node in the Navigator pane and choose New Class.
OR
Click the project node in the Navigator pane, choose New, then choose Class from the
Objects category of the New Gallery.
2. Enter the name of the class as OrderItem.
3. Enter the package name as orderEntry.
4. Deselect the Generate default constructor checkbox.
5. Click OK.
The new OrderItem class is opened in the Code Editor.
6. Complete the OrderItem class so that it is defined as follows:
package orderEntry;
public class OrderItem

{
public OrderItem()
{
int comment;
int orderId;
int quantity;
}
int toString()
{
return 0;
}
}
7. Click the Save icon on the toolbar, or choose File | Save to save these changes to
OrderItem.java.
8. Drag the OrderItem class from the from the Navigator pane, and drop on the diagram.
3-32
9. Model a strongly aggregated association between OrderItem and Order and examine the
changes that appear in the Java source code of OrderItem.java and Order.java.
This concludes the tutorial of the Java class modeling features in Oracle9i JDeveloper.
Now that you have practiced using the Java class modeling features, you can continue learning
about modeling Java classes from the UML Modeling section of the JDeveloper help.
Related Topics:
Class Diagram Notation
3-33
Business Components Tutorial
Business Components for Java (BC4J) is a programming framework that enables productive
development, deployment, and flexible customization of multi-tier, database-savvy applications
from reusable components. This tutorial steps you through the Business Components for Java
development process, highlighting some of the key concepts.
Objectives
By the end of this tutorial, you will have learned the proper way to develop a business
components application. This includes:
● How to create entity objects and associations using a UML class diagram
● How to create view objects and application modules
● How to create master-detail view links
● How to use the Business Components Browser for iterative testing
Requirements
The tutorial will take approximately one hour to complete. You will need the following:
● Oracle9i JDeveloper
● The tables in the Order Entry (OE) schema. This schema is included in the Oracle9i
distribution. If you are working with a previous version or have dropped those tables, see
Creating and Populating the Sample Schema Tables.
Tutorial Scenario
The scenario for this tutorial is that you are a developer who has been given the task of
creating a Business Components for Java application from an existing application. The existing
application is an order entry application for a company that sells computer products: monitors,
printers, software, etc. This application has been a maintenance nightmare and runs only an a
thick-client front end.
Your mission is to create an order entry application that can be deployed to multiple platforms,
and can use any type of client. To accomplish this task you'll need to create a business logic
tier that is independent of a user interface.
3-34
There are a couple things that will make your task easier. For one, you're modifying an existing
application, which means you'll be able to use the existing Order Entry schema. Also, the user
interface will be coded later in the cycle, so you can use a generic client provided with
JDeveloper, the Business Components Browser, for all your testing needs.
Application Development
When you develop a business components application, the proper development procedure is to
create your entity objects from the bottom up, and your view objects from the top down.
● Bottom-up development starts with a UML class diagram, in which entities and
relationships are described. From the UML class diagram the business components that
are used for persistence, entity objects, are generated.
● Top-down development starts by describing a task the user wants to accomplish. This is
usually represented by a user interface form. The fields on the form map to the attributes
of one or more view objects. When you create view objects, you'll do so with an idea of
what data elements (controls) are present on the UI.
In this tutorial, the development process follows these high-level steps:
1. Create a new JDeveloper workspace and project

2. Create a database connection
3. Create a UML class diagram, entity objects, and associations
4. Create view objects
5. Create a master-detail view link
6. Create an application module
7. Test the business logic tier
3-35
Creating a JDeveloper Workspace and Project
The first step is to create a new workspace and project. Putting all your business component
files into one project makes browsing packages easier and simplifies deployment.
1. In JDeveloper, choose File | New...

2. Click on the Projects category and select Workspace. Click OK.
3. In the New Workspace dialog box, leave the path the same, but rename the workspace
directory to tutorials and rename the workspace file to tutorials. Click OK.
4. In the New Project dialog box, leave the path the same, but rename both the directory
name and the project name to bc. Click OK. Your new workspace and project appear in
the System Navigator.

5. Right-click on your project (bc.jpr) and choose Project Settings.
6. In the Project Settings dialog box, change the name in the Default Package field to
onlineOrders.
7. Click OK.
Your next step is to create a database connection.
3-36
Creating a Database Connection
Before you can create business components, you need a connection to the database. For this
application you'll be using the Order Entry (OE) schema. If you do not have access to the OE
schema, see the topic, Creating and Populating the Sample Schema Tables.
To create a connection to the OE schema:
1. In the System Navigator, right-click on the Connections node and choose New Database
Connection.
The Connection Wizard opens.
2. Review the information on the Welcome page and click Next.
3. On the Type page, In the Connection name field, enter tutorial_jdbc_connection
and click Next.
4. On the Authentication page, type OE for both the name and password, and select the
checkbox to Deploy Password. Click Next.
5. On the Connection page, enter the Host name, JDBC port, and SID of the database you
are connecting to and click Next.
If you do not know these values, contact your database administrator.
6. On the Test page, click Test Connection. You should see the message "Success". If you
get an error, verify your connection data with your database administrator.
7. Click Finish to create your connection.
In the System Navigator, under your Connections node, you'll see a new folder for database
connections, and within that, your OrderEntry connection. Expand the folders and navigate to
the tables in the OE schema, as in the following picture:
3-37
In the next step you will drag and drop these tables to create a class diagram.
3-38
Creating a Class Diagram
In this step, you will create a UML class diagram of the OE schema. This will allow you to see the
entities and their relationships to each other. This step will also create a business components
package containing default-generated business components: an entity object for each table, and an
association for each relationship.
To generate the class diagram:
1. Right click on your project node (bc.jpr) and choose New UML Diagram from the popup menu.
2. In the New dialog, select Class Diagram and click OK.
3. In the Create New Class Diagram dialog box, enter oe_diagram and then click OK.
A blank class diagram pane appears on the right.
4. In the System Navigator click on the CUSTOMERS table and drag and drop it onto the class
diagram.
You may experience some delay while the UML class diagram is being created.
5. In a similar manner, drag and drop ORDER_ITEMS and ORDERS.
Note: For simplicity, you will only use these three entities. In a real-world application, your UML
diagram would have many more entities.
Your completed class diagram should contain the entities in the figure below. (Notice that you can
rearrange and resize the entities for better organization.) Entity objects are created for each UML
entity, while associations are created for each foreign-key relationship, shown as an arrow connecting
the entities.
In the System Navigator, notice that you have two new package nodes named onlineOrders. The first
one contains the class diagram, the second one contains business components. You won't need to
use the class diagram further in this tutorial, so you can collapse the top node.
3-39
In this step you created a class diagram, which generated business components for you. And while
your business logic tier has all the necessary components to persist (store) data, you'll need
components that will be accessible by the UI, view objects.
In the next step you will create view objects.
3-40
Creating View Objects
As mentioned previously, view objects are usually developed from the top down. This means
that an idea of what the UI looks like exists before the view objects are created. For this
application, we'll imagine that the Art Department has not yet created a final sketch of the UI
which you are to work from, but the fields are defined in a table.
Some of the fields are read-only (such as the Date), while some of the fields require the user to
enter data (such as Quantity). Each of the fields in the UI maps to a view object attribute. To
illustrate this, the following table lists the UI field, the view object and attribute, and some notes
on the type of the attribute.
UI Field View Object Attribute This attribute is a....

Line Item Number OrderItemsView OrderItemId composite primary key with OrderId
Product ID OrderItemsView ProductID read-only attribute on this form
Price OrderItemsView UnitPrice read-only attribute on this form
Quantity OrderItemsView Quantity number entered by the user
primary key generated by a DB
Order Number OrdersView OrderId
sequence
Date OrdersView OrderDate date generated in Java code
Mode OrdersView OrderMode a string, either "direct" or "online"
Customer OrdersView CustomerId foreign key from Customers entity
Status OrdersView OrderStatus number from 0-10
Total OrdersView OrderTotal calculated attribute
First Name OrdersView CustFirstName related field from Customers
Last Name OrdersView CustFirstName related field from Customers
First you'll create a view object for OrderItems, and then you'll create one for Orders.
To create the OrderItemsView view object:
1. In the System Navigator, right click your package node and choose New View Object
from the popup menu.
2. On the Welcome page, click Next.
3. On the Name page, enter OrderItemsView and click Next.
4. In the Entity Objects page, OrderItems in the Available pane and shuttle it to the
Selected pane. Click Next.
3-41
5. In the Available pane, shuttle all the attributes under OrderItems to the Selected Pane.
6. Click Finish.
Your OrderItems view object now contains all the attributes from the OrderItems entity object.
This previous exercise may lead you to believe that view objects are based 1:1 on entity
objects. This is not the case. View objects can get their attributes from multiple entity objects
(or even other sources of data). In the following exercise, you'll create an OrdersView view
object, specifying that it contains the CustFirstName and CustLastName from the Customers
entity object. This way, when you look at an order, you'll get a customers first and last name,
not just an ID number.
To create the OrdersView view object:
1. In the System Navigator, right click your package node (onlineOrders) and choose New
View Object from the popup menu.
2. On the Welcome page, review the information there and click Next.
3. On the Name page, enter OrdersView in the Name field and click Next.
4. On the Entity Objects page, select the Orders entity object in the Available pane and
shuttle it to the Selected pane.
5. Click Customers in the Available pane and shuttle it to the Selected pane.
Notice that the checkboxes for Read Only and Reference are both selected. After the first
entity object has been added, the framework makes all subsequent entity object's read-
only and dynamically referenceable by default. Since this is the behavior we desire in this
application, we don't need to change anything. (For more information on these features,
click Help.)
6. Click Next.
7. On the Attributes page, in the Available pane, shuttle all the attributes under Orders to
the Selected Pane. You can shift-click to select more than one item.
8. In the Available pane, under the Customers node, shuttle CustFirstName and
CustLastName to the Selected pane.
Notice that the primary key attribute, CustomerId, is brought into the selected pane as
well. This is required for the join condition between Orders and Customers.
9. Click Finish.
Your OrdersView view object now appears under your package node in the System
Navigator.
3-42
Your business logic tier now contains two view objects that can be accessed from a user
interface. The OrdersView view object contains information about the order, such as the
OrderId, the OrderDate, and the OrderTotal, as well as the customer's name. The
OrderItemsView view object contains information about the individual line items in an order. If
you were to create a client to access the business logic tier right now, you would be able to see
information about an order, or information about a single line item in an order. But what you
really want to see is information about an order and the details of all the line items that order
contains. To implement this you need to define a master-detail relationship using a view link.
In the next step, you will create a master-detail view link.
3-43
Creating a Master-Detail View Link
A view link connects view objects using key values (usually a foreign key). In this next step you
will create a master-detail view link between Orders and OrderItems. This will allow the user to
see an order and all the order items (line items) that order contains.
To create a master-detail view link between OrdersView and OrderItemsView:
1. In the System Navigator, right click your package node and choose New View Link from
the popup menu.
2. On the Welcome page, review the information there and click Next.
3. On the Name page, enter a name of OrdersViewLink.
4. On the View Objects Page, select OrdersView as the Source View Object and
OrderItemsView as the Destination View Object. Click Next.
5. On the Source Attributes page, in the lower pane of Available Associations, shuttle
OrderItemsOrderIdFkAssoc to the Selected Attributes pane.
You can use the associations defined in the database to create view links.
6. Click Next. On the Destination Attributes page, notice that OrderId is the attribute that the
view link is based on, which is a foreign key in OrderItemsView. Therefor, you don't need
to choose any additional attributes to link on.
7. Click Next and then click Finish.
Now that you have your view objects coordinated in a meaningful way, you need to be able to
make them accessible to client applications. The business component responsible for this is the
application module.
In the next step, you will create an application module.
3-44
Creating an Application Module
An application module represents a task you want to accomplish within a single transaction,
such as entering a new customer to the database, or creating an online order. The application
module contains all the elements the UI might need to display or manipulate to complete this
task. The objects necessary to perform a particular task are organized in the application
module's data model. A data model is a graphical representation of the objects needed to
perform a particular task, and how they are related.
In the following step, you'll create a new application module, OrderModule. This application
module will contain only those views that are required to place an order. In the data model,
you'll add the master-detail view link that you created, which coordinates Orders and
OrderItems. This way, when you select an order, you'll see all the line items contained by the
order.
To create a new application module:
1. In the System Navigator, right-click your package node and choose New Application
Module.
The Application Module Wizard opens.
3. On the Name page, enter OrderModule and click Next.
4. In the Available View Objects pane, select OrdersView and shuttle it to the Data Model
pane.
5. In the Data Model Pane, click OrdersView to select it.
6. In the Available View Objects pane, select OrderItemsView via OrdersViewLink.
7. Click the shuttle button to move it to the Data Model pane.
8. Click Finish.
Your new OrderModule application module now contains the view objects necessary to create
a new order. While your business logic tier is far from being complete, you can already run a
client to test what you've done.
In the next step, you will use the Business Component Browser to test the business logic tier.
3-45
Testing the Business Logic Tier
The Business Components Browser is a Java client provided with JDeveloper. The client allows
you to view and update data, without having to code a custom client and GUI. This is an
integral part of iteratively developing and testing your business logic tier.
To test the application module:
1. In the System Navigator, right-click the OrderModule application module and choose
Test.
JDeveloper compiles your project.
2. In the Connect dialog click Connect. (You may experience some delay while JDeveloper
compiles your project.)
The Business Components Browser appears. Its Navigation pane displays the view
objects and view links in the application module's data model.
3. Right-click OrdersView and choose Show.
The OrdersView view object instance displays in the right pane. This view object shows
you the orders that exist in the database. Notice the CustFirstName and CustLastName
attributes that you added from the Customers entity object are included as read-only
fields. You can use the controls to scroll through orders.
4. Right-click OrderItemsView and choose Show.
The OrderItemsView shows you the order items (line items) for a particular order.
5. Right-click OrderViewLink and choose Show.
This view link shows the OrdersView and OrderItemsView view object instances display
in the right pane, linked in a master-detail relationship. So you see information about an
order, and under it, the order items that are contained by the order. (You can resize the
panes to see more of the Orders information.)
6. In the right pane, click the Insert a record button (it looks like a plus sign).
The Business Components Browser creates a new order. Notice that there are no values
in any of the fields. In the following steps you will add business logic that creates default
values whenever you create a new order.
7. Choose File | Exit to close the Tester.
Reviewing What You've Learned
The key concepts illustrated in this tutorial are the following:
● Entity objects are developed from the bottom up.
3-46
● View objects are developed from the top down.
● View objects can get their attributes from more than one entity object.
● View links are used to describe master-detail relationships.
● Application modules are task-specifc, containing only those views that are required by
the task at hand.
3-47
Business Components Programmatic Client Tutorial
In this tutorial, you will create a client for a simple business components project. In the process,
you will learn how to navigate through queries, display data, and invoke business logic methods
from clients. Although the client you create will be a batch client, you can use the knowledge
you gain in this tutorial with any client, whenever you need control over interaction with the
business logic tier beyond what is automatically provided by other client architectures.
Before completing this tutorial, we recommend that you gain a basic familiarity with the
business components framework by completing the Business Components Basic Tutorial.
● Requirements
● Creating a Business Components Project
● Initializing the Batch Client
● Finding and Displaying Data by Primary Key
● Invoking a Custom Business Logic Method
● Displaying Detail Data
● Making and Committing Updates
● Reviewing What You've Learned
3-48
Requirements
To complete the Business Components Programmatic Client Tutorial, you will need the
following:
● The common schema loaded into your Oracle database, as described in Creating and
Populating the Sample Schema Tables
● A connection to the database, as described in Creating a Connection to Use with the
Online Help
3-49
Creating a Business Components Project
In this section of the Business Components Batch Client Tutorial, you create a business
components project for the business logic your client will access. This is a very simple business
components project. For information on creating more complex business components projects,
see the Business Components Tutorials.
To create a new business components project:
1. Choose File | New. The New dialog opens.

2. Select Projects from the Categories list and Workspace from the Items list. Click OK.
3. In the New Workspace dialog, enter bcbatch as the directory name and bcbatch.jws
as the file name.
4. Check Add a new empty project and click OK to create the workspace.
5. In the New Project dialog, enter OnlineOrders as the directory name and
OnlineOrders.jpr as the project name.
6. Click OK to create a project for your business components.
7. In the Navigator, right-click the OnlineOrders.jpr file and choose New Business
Components.
8. The Business Components Project Wizard appears. If the Welcome page appears,
review the information there and click Next.
9. On the Connection page, in the Connection Name field, select tutorial_jdbc_connection.
Click Next.
10. On the Package Name page, enter the name OnlineOrders. Click Next.
11. On the Business Components page, select the following tables:
❍ CUSTOMERS
❍ ORDERS
12. Click Finish to generate your business components.

13. Choose File | Save All to save your project.
14. Choose Project | Build OnlineOrders.jpr to compile your project.
Now you are ready to initialize the batch client.
3-50
Initializing the Batch Client
In this section of the Business Components Batch Client Tutorial, you create a project and class for
your batch client and instantiate the OnlineOrdersModule application module and
CustomersView view object.
Before you complete this section, make sure you have created your business components project.
First, create a project for your batch client, and add all needed libraries to the project's classpath.
To create a project for your batch client:
1. In the Navigator, right-click bcbatch.jws and choose New Empty Project.

2. In the New Project dialog, enter batchclient for the project directory name and
batchclient.jpr for the project file name.
3. In the Navigator, right-click batchclient.jpr and choose Project Settings.
4. In the Project Settings dialog, in the tree, select Libraries.
5. Shuttle the following libraries from the Available libraries list to the Selected libraries list:
❍ BC4J Runtime
❍ BC4J Oracle Domains

❍ Oracle JDBC
❍ Connection Manager
6. In the tree, select Paths.

7. In the Additional Classpath field, enter
<Oracle_home>/jdev/mywork/bcbatch/OnlineOrders/classes.
8. Click OK to close the Project Settings dialog.
Next, create an empty class that will become your batch client.
To create a class for your batch client:
1. In the Navigator, right-click batchclient.jpr and choose New.

2. In the New dialog, select Objects from the Categories list and Application from the Items list.
Click OK to open the New Application dialog.
3. In the Name field, enter Batch.
4. In the Package field, enter bcbatch.
3-51
5. Select Do not add a default frame.
6. Click OK to generate the Batch class and display its source code.
Now you should import the business components tier-independent interfaces and classes you need.
Note that you should not import the server-side only classes in oracle.jbo.server: Even though you're
going to run your batch client in local mode, using only tier-independent interfaces and classes will
keep your application independent of deployment configuration.
To import business components tier-independent interfaces and classes:
● Add the following code after the line package bcbatch;
import oracle.jbo.*;
import oracle.jbo.client.*;
import oracle.jbo.domain.Number;
Next, add a method called show() to display data. show() is simply a convenient delegator to
System.out.println().
To add a show() method:
● Add the following code right before the final } of the file:
private static void show(String s) {

System.out.println(s);
} // end show()
Now, add code to the main() method of your client to instantiate OnlineOrdersModule and
CustomersView.
To instantiate the application module and a view object:
1. Add the following code to the main() method:
ApplicationModule am_Ord =
Configuration.createRootApplicationModule("OnlineOrders.OnlineOrdersModule",
"OnlineOrdersModuleLocal", null);
This creates an instance of OnlineOrdersModule in local mode, using the connection

3-52
information stored in the configuration OnlineOrdersModuleLocal. If you deploy your
business components to another platform (for example, an EJB session bean), JDeveloper
creates another configuration for you to use here.
2. Add the following code immediately after the code you just entered:
ViewObject vo=am_Ord.findViewObject("CustomersView");
This searches the data model of OnlineOrdersModule for a view object useage named
CustomersView.
Now you are ready to use your batch client to find a row of CustomersView by primary key.
3-53
Finding and Displaying Data by Primary Key
In this section of the Business Components Batch Client Tutorial, you find a row of the
CustomerView view object by its CustomerId attribute and display the CustomerId and
Email attributes from that row.
Before you complete this section, make sure you have initialized the batch client.
The CustomerId you use will be provided as a command-line argument to the batch client. First,
create an object of type oracle.jbo.Key based on the command-line argument.
To retrieve the CustomerId from the command line and base a key on it:
1. Check to make sure a command-line argument is provided using the following code.
Insert the code at the very beginning of your main() method.
if (args.length==0) {
show("Customer ID is required.");
System.exit(0);
}
2. Create an oracle.jbo.Key based on the command-line argument. Insert the following

code right after the code that instantiates the CustomersView view object.
Key custKey = new Key(new Object[] {args[0]});
Although this key has only one part, the Key constructor takes an array of objects to
accomodate multi-part keys.
Next, retrieve the row associated with this key. This row is an object that implements the
oracle.jbo.Row interface.
To find the row associated with custKey:
1. Find the array of rows associated with custKey using the findByKey() method. Insert
the following code right after you define custKey.
Row[] customersFound = vo.findByKey(custKey,1);
3-54
Since custKey contains all components of the primary key, it will have only one
associated row, but findByKey() returns an array of rows to allow for keys with
unspecified attributes. The first argument of findByKey is the key; the second is the
maximum number of rows to return.
2. Check to make sure a row was actually returned. Insert this code right after the code you
just inserted:
if (customersFound.length==0) {
show("Customer " + args[0] + " not found.");
}
3. Otherwise, retrieve the first (and only) row in customersFound. Insert the following
code right after the above if statement.
else {
Row row_Cust = customersFound[0];
}
Now you can display attributes in row_Cust using the getAttribute() method. Note that,
since row_Cust is a generic Row, we can use getAttribute() only because it is a method
on the generic Row interface. You'll see how to call custom methods in the next section of this
tutorial.
To display the customer's ID and email address:
1. Inside the else block you just created, after the declaration of row_Cust, enter the
following code to display formatting.
show("Customer");
show("========");
2. Right after those two lines of code, enter the following line to display the customer's ID.
show("ID: " + row_Cust.getAttribute("CustomerId"));
3. Enter the following line to display the customer's email address.

3-55
show("Email: " + row_Cust.getAttribute("CustEmail"));
Although you will continue to enhance the batch client, this simple version is ready to run.
To run and save the prototype batch client:
1. In the Navigator, right-click batchclient.jpr and choose Project Settings.

2. In the Project Settings dialog, in the tree, under Configurations and Development, select
Runner.
3. In the Program arguments field, enter 101.
This will pass 101 to the batch client as a command-line argument.

4. In the Default Target dropdown, make sure Batch.java is selected.
5. Click OK to close the Project Settings dialog.
6. Choose Run | Run batchclient.jpr.
The Message View displays the program's output.

Next, you will create and invoke a custom business logic method.
3-56
Invoking a Custom Business Logic Method
In this section of the Business Components Batch Client Tutorial, you create a custom row
method for the CustomerView view object and invoke it for your client.
Before you complete this section, make sure your batch client can find a row of
CustomerView by primary key.
You will create a method that concatenates the first and last names of a customer. Since this
method applies only to one row of CustomerView's rowset, rather than the entiry rowset, you
will create the method on a view row class.
To generate a view row class for CustomerView and add a method:
1. In the Navigator, in the OnlineOrders project, right-click CustomersView and choose Edit
CustomersView.
2. In the View Object Editor, select the Java tab.
3. Under View Row Class: CustomersViewRowImpl, select Generate Java File.
4. Click OK to generate the file CustomersViewRowImpl.java.
5. In the Navigator, double-click CustomersViewRowImpl.java to open it in the Source
editor.
6. Enter the following code right before the final } in the file.
public String getCustFullName()

{
StringBuffer fullName = new StringBuffer(40);
fullName.append(getAttributeInternal("CustFirstName"));
fullName.append(" ");
fullName.append(getAttributeInternal("CustLastName"));
return fullName.toString();
}
You should not directly invoke CustomersViewRowImpl.getCustFullName() from your

client. Even though you're going to run your batch client in local mode, using only tier-
independent interfaces (as opposed to the server-side CustomersViewRowImpl) will keep
your application independent of deployment configuration.
You can invoke this method from your client and maintain tier-independence by generating a
3-57
client row interface.
To generate a client row interface for CustomersView:
1. In the Navigator, right-click CutomersView and choose Edit CustomersView.

2. In the View Object Editor, select the Client Row Methods tab.
3. Shuttle getCustFullName from the Available list to the Selected list.
4. Click OK.
5. Choose Project | Build OnlineOrders.jpr.
JDeveloper generates an interface called CustomersViewRow. This interface is implemented

by CustomersViewRowImpl and exposes getCustFullName(). Unlike
CustomersViewRowImpl, which is in the server-side package OnlineOrders,
CustomersViewRow is in the package OnlineOrders.common, which you would deploy with
your client in a multi-tier environment.
Now you can invoke getCustFullName() from the client in a tier-independent manner.
To invoke getCustFullName() from the client:
1. In the Navigator, double-click Batch.java to edit its source code.

2. Add the following statement to the import block near the top of the file.
import OnlineOrders.common.*;
3. Find the line
Row row_Cust = customersFound[0];
and replace it with
CustomersViewRow row_Cust = (CustomersViewRow) customersFound[0];
By casting row_Cust to a CustomersViewRow, you can call methods on

CustomersViewRow that aren't on the generic oracle.jbo.Row interface.
3-58
4. After the line where you display the customer's email address, add the line
show("Name: " + row_Cust.getCustFullName());
You can run the batch client to see the changes you've made.
To run and save this version of the batch client:
Next, you will traverse a view link to retrieve and display detail data.
3-59
Displaying Detail Data
In this section of the Business Components Batch Client Tutorial, you traverse a view link to retrieve detail data
and iterate through the detail rowset to display each of its rows.
Before you complete this section, make sure you have created and invoked a custom business logic method.
Because CustomersView has a view link accessor to the OrdersView view object, you can retrieve the orders
for any customer by passing the view link accessor name to the getAttribute() method on the
CustomersView view row.
To retrieve the orders for the customer:
1. In the Navigator, double-click Batch.java to open it in the Source viewer.

2. Add the following code right after the line where you display the customer's name.
RowSet rowset_Orders = (RowSet)row_Cust.getAttribute("OrdersView");
Now you can iterate through the rowset and display data from each row.
To iterate through the rowset:
1. Enter the following code right after the line you just added.
if (rowset_Orders == null) {
show("No orders for this customer");
}
This handles the case where getAttribute("OrdersView") retrieves no orders.
2. Enter the following code right after the if block.
else {
while (rowset_Orders.hasNext()) {
Row row_Order = rowset_Orders.next();
}
}
hasNext() checks to make sure there are more rows in rowset_Orders, and next() returns the next
row and sets that row to current.
3. Enter the following code inside the while block, right after the declaration of row_Order.
show(" Order # " + row_Order.getAttribute("OrderId") + " " +

row_Order.getAttribute("OrderDate"));
3-60
This displays the OrderId and the OrderDate for the current row in the iteration.
You can run the batch client to see the changes you've made.
To run and save this version of the batch client:
Next, you will update data with your batch client.
3-61
Making and Committing Updates
In this section of the Business Components Batch Client Tutorial, you update the status for all
of a customer's orders and commit the changes to the database.
Before you complete this section, make sure you have retrieved the orders for the customer.
To update the status of each order and then commit the changes:
1. Add the following code inside the while loop, right after you show the OrderId and
OrderDate.
show(" Setting Status to 2: Canceled - bad credit");

row_Order.setAttribute("OrderStatus", new Number(2));
Note that the value assigned to OrderStatus is an oracle.jbo.domain.Number

(which matches the attribute type) rather than an int. Business components attributes
must be objects, not primitives.
2. Enter the following code after the end of the while block.
am_Ord.getTransaction().commit();
The application module owns the Transaction object, which getTransaction()

returns. This object can be used to commit or rollback changes.
This is the final version of the batch client.
To run and save the completed batch client:
Congratulations, you have completed the Business Components Batch Client Tutorial. For a
3-62
quick review of the concepts and techniques you've learned, see Reviewing What You've
Learned. For other tutorials in the JDeveloper documentation set, please see JDeveloper
Tutorials.
3-63
Reviewing What You've Learned
In the Business Components Programmatic Client Tutorial, you accomplished the following
tasks:
● Adding business components runtime libraries to a client project

● Importing client-side business components packages into a client
● Instantiating an application module using
Configuration.createRootApplicationModule()
● Finding a view object in the data model using
ApplicationModule.findViewObject()
● Finding a row by primary key using ViewObject.findByKey()
● Retrieving attributes using Row.getAttribute()
● Creating, exporting, and invoking a custom business logic method
● Traversing a view link using Row.getAttribute()
● Iterating through a rowset using ViewObject.next()
● Updating data using Row.setAttribute()
● Committing a transaction using Transaction.commit()
3-64
Creating JavaServer Pages with Data Tags
This tutorial describes how to create typical JavaServer Pages. It shows how you can create
light-weight web applications using JDeveloper's Business Components for Java framework
and the BC4J tag library. The client, in this case, displays customer and order information
based on the Order Entry business components data model.
The goal of this tutorial is to teach you how to build JavaServer pages using component tags
and BC4J generation templates. In the tutorial example, you will create JavaServer pages that
let you query and update records and also view associated navigation functionality.
In this tutorial, you will learn how to do the following:

● Create a new Business Components project
● Create a new project for your JSP application
● Create JSP pages based on a view
● Use the Data Page Wizard
● Utilize the Component Palette
● Use BC4J Connection Tags
● Use BC4J Component Tags
● Create a JSP Edit Form
After completing the tutorial requirements referenced in the related topic below, open the first
tutorial topic, Creating a Business Components Project, to get started.
Related topic
Requirements for Running the Tutorial
3-65
Requirements for Running the Tutorial
To complete the JSP Data Tags tutorial, you will need the following:
● The common schema loaded into your Oracle database, as described in Creating and
Populating the Sample Schema Tables
● A connection to the database, as described in Creating a Connection to Use with the
Online Help
When you are ready to begin, open the first tutorial topic, Creating a Business Components
Project.
3-66
In order to create a JSP application based on an Application Module, you'll need to first create
a project to contain the business components.
To create a new business components project:
1. Choose File | New to create a workspace for your files.

2. In the New dialog, select Projects from the Categories and Workspace from the Items
list, then click OK.
3. In the New Workspace dialog, enter jsptags as the directory name and jsptags.jws as the
file name.
4. Check Add a new empty project and click OK to create the workspace.
5. In the New Project dialog enter business as the directory name and business.jpr as the
project filename and click OK to create the project.
6. Right-click the business.jpr file in the navigator and choose New Business Components.
The Business Components Project wizard launches.
7. Click Next on the Welcome page to begin.

8. Select the Connection Name that you created, tutorial_jdbc_connection, and click Next.
This was described in Creating a Connection to Use with the Online Help.
9. If prompted, click OK to log in.
10. Enter the Package Name jsptags and click Next.
11. Select the OE schema from the list of schemas.
12. Select the Tables and Views objects options if they are not already selected.
13. Select the customers and orders tables in the Available list and click the right arrow
button to move those selections to the Selected list.
JDeveloper will create entity objects and associations for the selected tables and views.
14. Click Next to continue, and verify your package names, entities, and view objects.
15. Click Finish to create the business components project.
16. Choose Project | Build business.jpr to compile the project.
Notice that the Message window displays the compilation information.

3-67
17. Choose File | Save All to save all your work thus far.
The next step is to create a JSP project in the jsptags.jws workspace, as described in Creating
a JSP Project.
3-68
Creating a JSP Project
Now create another project in the same workspace, which will contain the files you create for
your JSP application. You will be creating a JSP application containing three JavaServer
pages: a JSP for browsing customers, a JSP for browsing customer orders, and a form for
editing those orders.
To create a new project for your JSP application:
1. With the workspace jsptags.jws selected in the Navigator, create another new project by
choosing File | New.
2. In the New dialog, select Projects from the Categories and Empty Project from the Items
list, then click OK.
3. In the New Project dialog enter jsp as the directory name and JSP.jpr as the project file
name and click OK to create the project.
The empty project JSP.jpr appears in the Navigator.
Now you can create JSP pages based on the views created in your Business Components
project when you ran the Business Components Project wizard, as described in Creating a JSP
Based on the Customers View.
3-69
Creating a JSP Based on the Customers View
The following steps show you how to create a Business Components based JavaServer Page
using the Data Page Wizard, creating a form that displays data from the Customers view.
To create a JSP based on the Customers View:
1. With the JSP project JSP.jpr selected in the Navigator, create a JavaServer Page for
browsing by choosing File | New.
The New dialog opens.
2. Select BC4J JSP from the Categories, then select Browse Form from the Items list and
click OK.
3. When the Data Page wizard opens, click Next if the Welcome page displays.
4. In the Application Module folder, expand JsptagsModule if necessary and select the
CustomersView object. Then click Next.
5. Click Finish to create the CustomersView_Browse.jsp, which displays in the Navigator.
You now have a simple, working JavaServer Page (named CustomersView_Browse.jsp)

for browsing the Customer view object. Notice that three additional files are added to
your project. There is an errorpage.jsp for processing errors, and three component tag
pages, DataTableComponent.jsp, DataScrollerComponent.jsp, and
DataHandlerComponent.jsp. These files include data tags which help you modify the
layout and design of a JSP application, without requiring you to modify each JSP within
the application.
6. Choose Project | Build JSP.jpr to compile the file.

8. Select CustomersView_Browse.jsp in the Navigator and choose Run | Run
CustomersView_Browse.jsp to run the file in your browser.
You should see your JSP file in your default browser with the Customers' data displayed
in a table. On the top right you will see Next and Previous links that let you browse
through customer data.
9. Close the browser window before moving on to the next step.
3-70
You could also choose Run | Terminate | Embedded OC4J Server if you were not going
to continue with the tutorial and wanted to terminate the server, which was automatically
launched. However this step is not necessary. It will be automatically terminated and
restarted if you make changes to the product and you will be prompted to terminate it
when you exit JDeveloper, if it is running.
The next step, Creating a JSP Based on the Orders View, shows you how to use the
Component Palette tags instead of a wizard to create a JSP page for browsing.
3-71
Creating a JSP Based on the Orders View
The following steps show you how to create a detail JSP page for browsing the Orders view
object. The procedure shows you how to use the Component Palette tags instead of a wizard to
add the data tags that were included automatically by the wizard.
To create a JSP based on the Orders View:
1. With the JSP project JSP.jpr selected in the Navigator, create another JavaServer Page
by selecting File | New.
2. In the New dialog, select Web Objects from the Categories, then select JSP from the
Items list and click OK.
3. Name the file Orders.jsp, accept the default directory, and click OK.
You now have another JavaServer Page that is opened in the Code Editor. Next, you will
add an Application Module data tag and a Data Source data tag to bind your JSP to an
application module and view objects.
4. Place your cursor after the </P> tag on line 15 in the Orders.jsp file and press Enter to
add a new line.
5. Choose View | Component Palette to open the Component Palette, if it is not displayed.
6. Select BC4J Connections from the drop-down list in the Component Palette.
7. Select the Application Module data tag.
8. In the Application Module dialog, verify the Business Components project you created
earlier is selected and click Next.
9. Click Finish to accept default row locking for this application.
10. In the ApplicationModule tag in Orders.jsp, replace id="JsptagsModule" with id="am".
The edited ApplicationModule tag should look like this:
<jbo:ApplicationModule id="am"
configname="jsptags.JsptagsModule.JsptagsModuleLocal" releasemode="Stateful" />
11. In the Orders.jsp file, create a new line for the next tag before the </BODY> tag.
12. Select the DataSource tag from the Component Palette.
13. In the DataSource dialog, select OrdersView from the View Object pane then click Next.
14. Enter dsOrders for the id and enter 5 as the rangesize. After entering the values, click
Finish.
3-72
15. In the Orders.jsp file, create a new line for the next tag below the DataSource tag.
Next, add a component tag to display a table bound to a view object and link it to a form
you will create later.
16. Select BC4J Component Tags from the drop-down list in the Component Palette and
select the DataTable component tag.
17. Select dsOrders as the datasource and enter OrdersView_Edit.jsp as the edittarget,
then click Finish.
Next, add navigation to the JSP.
18. Add a new line below the DataTable component tag and select the DataScroller
component from the BC4J Component Tags palette.
19. Select dsOrders as the datasource, then click Finish.
20. Select Orders.jsp in the Navigator and choose Project | Build Orders.jsp to compile the
file.
22. Choose Run | Run Orders.jsp to run the file in your browser.
You should see your JSP file in your browser with the current date and the order details
for five orders displayed. You can click Next to scroll to the next group of 5 records and
Previous to scroll backwards. Notice also that the New, Delete and Edit links were
created because we specified an edittarget in the DataTable tag of the Orders.jsp. These
links do not work yet; you will create working links as part of the next step.
23. Close the browser window before moving on to the next step.
24. You may also want to close the Code Editor by choosing File | Close.
The next step, Creating a Form for Editing Orders shows you how to create a form for editing
orders.
3-73
Creating a Form for Editing Orders
Now you can create an OrdersView_Edit.jsp that can be used for editing orders, using the Data
Page Wizard again.
To create a form for editing orders:
1. With the JSP.jpr project selected, choose File | New to create a JSP for editing.
2. In the New dialog, select BC4J JSP from the Categories, then select Browse & Edit
Form from the Items list and click OK.
3. When the Data Page wizard appears, click Next.
4. In the Application Module folder, expand JsptagsModule and select the OrdersView
object. Then click Next.
5. Click Finish to create the OrdersView_Edit.jsp and OrdersView_BrowseEdit.jsp, which
display in the Navigator.
6. Click Yes when you are prompted to overwrite existing files. You will see this prompt
several times.
7. Build and test the application. Choose Project | Build JSP.jpr to compile the project files.
9. Select OrdersView_BrowseEdit.jsp in the Navigator and choose Run | Run
OrdersView_BrowseEdit.jsp to open the form in your browser.
Notice that you can click the New link and the Edit links next to each row to get to the
OrdersView Edit Form. On the Edit Form, you can change information; for example, you
can change the date by selecting a date from the calendar and clicking Update. You will
return to the OrdersView Browse Form after clicking Update. You also have the option to
use Commit or Rollback, on the upper right of this page. Next open the Order Browse
form and use the link to open the Order Edit form.
10. Select Orders.jsp in the Navigator and choose Run | Run Orders.jsp to open the form in
your browser.
Notice that you can click the New link and the Edit links next to each row to get to the
Order Edit form.
You now have three working JavaServer pages built both manually and using wizards, which
incorporate the new JDeveloper component tags, as well as BC4J connection tags.
3-74
3-75
Activity Modeling for E-Business Integration
In this tutorial you learn how to create activity diagrams and diagram elements, and how to generate e-business
integration code for messaging. The tutorial is not meant to be exhaustive in demonstrating all of the
functionality of the activity modeler and its integration code generation. Its purpose is to guide you through many
of the tasks that you must perform when using the tool.
Modeling a Simple Integration Point
The topics in this module guide you through creating a diagram of a simple integration point. The scenario used
for this module is more simple than you would ever encounter in real life, however, it serves to introduce the
basic steps that you would follow to create any diagram and generate messaging code, regardless of the
complexity.
The following topics describe how to model, define an integration point, from which you then generate
messaging code.
● Getting Started with Activity Modeling

● Creating an Activity Diagram
● Creating Swimlanes
● Creating a Hub
● Creating Activities
● Creating Object Flow States
● Creating Pseudostates
● Creating Transitions
● Reviewing the Defined E-Business Integration
● Generating the Integration Point Messaging Code
● Understanding the Generated Results
A Simple Business Scenario
As described above, this module uses a very simple business scenario to demonstrate how to use the activity
modeler and its code generating capabilities:
In our company, customers place orders with a clerk. On placement of an order, the clerk sends a message to
the Shipping department to fill the order. Our company wishes to automate this process, such that, once an
order is taken it is sent immediately to the Shipping department.
The business analysts examined this enterprise and used the activity modeler in JDeveloper to diagram it. Their
results are shown below. They then used the code generation capabilities of the modeler to create messaging
code to integrate the two systems.
3-76
The objective of this tutorial is to retrace the analysts' steps in building the diagram and generating the code.
Diagram for a Simple Business Scenario
Activity diagram containing four swimlanes: Orders, Shipping, Inventory and Hub. Orders swimlane contains: the
INITIAL pseudostate, the Take Order activity with a transition from the INITIAL pseudostate to the Take Order activity.
Shipping swimlane contains: the Order [received] object flow state, an OR pseudostate and the Ship Order activity. There
is a transition with a channel and an [order.stockCode ‹ 9000] guard condition from the OR pseudostate to the Ship Order
activity, a transition with a chnnel from the Take ORder activity to the Order [new] object flow state and a transition from
the Order [new] object flow state and the OR pseudostate. Inventory swimlane contains: the Back Order activity. There is a
transition with a channel and an [order.stockCode ›= 9000] guard condition from the OR pseudostate Back Order activity,.
The Hub swimlane is defined as the Hub and is empty.
After creating activity diagrams, defining integration points and generating e-business integration files, you can
deploy the generated e-business integration files. For more information on deploying, see Deploying Generated
E-Business Integration Files.
3-77
Getting Started with Activity Modeling
Before you create an activity model and generate messaging code, there is some setup you
need to do first:
Define Database Connections (Required for Code Generation)
If you want to generate messaging code from the diagram you create in this tutorial, you must
define a database connection for each swimlane in the diagram. In this tutorial, you will create
four swimlanes. To generate messaging code, then you must create four database
connections. These do not have to be valid connections to real database servers—you can use
arbitrary data to define the connections. The only time you need valid database connections is
when you deploy messaging code.
To be consistent with the examples in this tutorial, name the database connections:
● hub_connection
● orders_connection
● shipping_connection
● inventory_connection
Create a New Empty Project in a New Workspace (Recommended)
As you create the activity diagram and diagram elements, JDeveloper populates the Navigator
window with the results of your actions. Although you can create an activity diagram and
generate messaging code in an existing project and workspace, the results of the tutorial steps
will be easier to see in the Navigator window if you create a new, empty project in a new
workspace.
Choose Default Fonts and Colors (Optional)
If you wish, you can set the default fonts and colors of activity model elements before you
begin. To do this, choose Tools | Preferences in the JDeveloper menu bar to open the
Preferences dialog, then open the UML Diagram | Activity Diagram tree control. You can then
select the default font and color preferences for the diagram elements.
After setting up the connections and project, go on to Creating an Activity Diagram.
3-78
Creating an Activity Diagram
Start the tutorial by creating an activity diagram in a new, empty project.
To create a new activity model:
1. Select a new empty project in a new workspace in the JDeveloper Navigator pane.
2. Right-click the project in the JDeveloper Navigator and choose New UML Diagram to
open the New dialog.
3. In the New dialog, select Activity Diagram in the Items column, then click OK.
4. In the Create New Activity Diagram dialog, accept the default package name, enter
SimpleIntegration as the name of the activity diagram, and click OK. An empty
diagram opens in JDeveloper.
5. Select File | Save All from the JDeveloper menu bar to save your changes.
After creating an activity diagram, go on to Creating Swimlanes.
3-79
Creating Swimlanes
Swimlanes typically correspond to the separate systems in your enterprise. The business
analysts who have examined the enterprise, concluded that there are three systems: Order
Entry, Shipping and Inventory.
The following steps will create the swimlanes which represent the Order Entry and Shipping
systems.
To create the Order Entry system:
1. Click the Swimlane icon in the Component Palette.

2. Click in the diagram to create a generic swimlane.
3. Right-click the swimlane to the left of the vertical line and choose Properties to open the
Swimlane Properties dialog.
4. In the General tab, enter Order Entry in the Name field.
5. In the Channels/Adapters tab, define an OUT channel for the swimlane. Ensure that
Channel is selected in the drop-down list. Click New to create an editable field in the
Name list. Enter outchannel in the field. Define the properties of the channel:
❍ In the Queue name field, enter orders_queue. This will be the name of the
queue on which outgoing messages will be placed.

❍ In Implementation type, open the drop-down list and select AQ, if it is not already
selected, as the name of the queuing mechanism.
❍ In the Queue table field enter orders_queue_table. This will be the name of
the table where messages will be stored.
❍ In Direction, open the drop-down list and select Out. This is because the activity
that you will be defining for the Order Entry system is a sending activity.
❍ In the Protocol field, open the drop-down list and select HTTP/HTTPS.
❍ In this tutorial module, adapter generation is not used, so proceed to the Instances
tab. Note that it is not always necessary to generate an adapter. For example, you
would not have to generate an adapter if a pre-built adapter already exists for the
application.
6. In the Instances tab define an instance of the Order Entry system. Click New to create a
field in the Name list. Enter orders_instance1 in the field. Define the properties of the
instance:
In the Connection name field, enter the name of the connection to the Order Entry
3-80
database: orders_connection. If you have already defined the connection, you can
select it from the drop-down list. Note: if you want to generate messaging code, this
connection must be defined.
Since we are using Oracle AQ for the queuing mechanism, enter the name of the AQ
Servlet URL: http://www.ourOrders.com.
7. Click OK to commit your changes.
To create the Shipping system:

2. Click in the diagram below the Order Entry swimlane to create a generic swimlane.
3. Right-click the swimlane to the left of the vertical line, and choose Properties to open the
4. In the General tab, enter Shipping in the Name field.
5. In the Channels/Adapters tab, define an IN channel for the swimlane: Ensure that
Name list. Enter inchannel in the field. Define the properties of the channel:
❍ In the Queue name field, enter shipping_queue. This will be the name of the
queue on which incoming messages will be placed.

❍ In the Queue table field enter shipping_queue_table. This will be the name of
the table where messages will be stored.
❍ In Direction, open the drop down list and select In, if it is not already selected.
This is because the activity that you will be defining for the Shipping system is a
receiving activity.
❍ In the Protocol field, open the drop down list and select HTTP/HTTPS.
6. In the Instances tab define an instance of the Shipping system. Click New to create a
field in the Name list. Enter shipping_instance1 in the field. Define the properties of
the instance:
In the Connection name field, enter the name of the connection to the Orders database:
shipping_connection. If you have already defined the connection, you can select it
from the drop-down list. Note: if you want to generate messaging code, this connection
must be defined.
3-81
Since we are using AQ for the queuing mechanism, enter the name of the AQ Servlet
URL: http://www.ourShipping.com.
To create the Inventory system:

2. Click in the diagram below the Shipping swimlane to create a generic swimlane.
3. Right-click the swimlane to the left of the vertical line, and choose Properties to open the
4. In the General tab, enter Inventory in the Name field.
5. In the Channels/Adapters tab, define an IN channel for the swimlane: Ensure that
Name list. Enter inchannel_2 in the field. Define the properties of the channel:
❍ In the Queue name field, enter inventory_queue. This will be the name of the
queue on which incoming messages will be placed.

❍ In the Queue table field enter inventory_queue_table. This will be the name
of the table where messages will be stored.
❍ In Direction, open the drop down list and select In, if it is not already selected.
This is because the activity that you will be defining for the Inventory system is a
receiving activity.
❍ In the Protocol field, open the drop down list and select HTTP/HTTPS.
6. In the Instances tab define an instance of the Shipping system. Click New to create a
field in the Name list. Enter inventory_instance1 in the field. Define the properties of
the instance:
In the Connection name field, enter the name of the connection to the Orders database:
inventory_connection. If you have already defined the connection, you can select it
from the drop-down list. Note: if you want to generate messaging code, this connection
must be defined.
URL: http://www.ourInventory.com.
3-82
8. Choose File | Save All from theJDeveloper menu bar to save your changes.
If you wish, use Visual Properties to change the default font and color of your swimlanes.
After creating swimlanes, go on to Creating a Hub.
3-83
Creating a Hub
A hub represents a central server which acts as the focal point for the communications between
applications. The applications which communicate through the hub can be thought of as spokes
connected to the hub. Messages that are sent from one application are routed to the hub
instead of being sent directly to their intended destination. When the hub receives a message, it
consults its subscription list and then routes the message to its appropriate destination. To
perform message routing, Oracle Workflow must be installed on the server to be used as the
hub.
In the activity modeler, the hub can be thought of as a specialized swimlane. You can create an
empty swimlane to be used exclusively as a hub or you can select an existing swimlane to act
as a hub.
● If you create an empty swimlane to act as the hub, you must provide a name for the hub
swimlane, an instance, a connection, and AQ servlet URL (if it uses the AQ messaging
mechanism).
● If you designate an existing swimlane for the hub, you must additionally provide any
channel and adapter information required by the business process being modeled.
The business analysts who have examined the enterprise decide that it would be more efficient
to run the messages through a hub system rather than implement point-to-point
communications.
In the following steps, a new swimlane will be created and designated as a hub.
To create a hub:

2. Click in the diagram below the Inventory swimlane to create a generic swimlane.
3. Right-click in the swimlane to the left of the vertical bar and choose Select as Hub. The
icon in the swimlane panel changes to .
4. Right-click the swimlane to the left of the vertical bar again and choose Properties to
open the Swimlane properties dialog.
In the General tab, enter Hub in the Name field.
Since an empty swimlane is being used as the hub, no channel or adapter information is
required.
3-84
In the Instances tab define an instance of the hub system. Click New to create a field in
the Name list. Enter hub_instance1 in the field. Define the properties of the instance:
In the Connection name field, enter the name of the connection to the hub database:
hub_connection. If you have already defined the connection, you can select it from the
drop-down list. Note: if you want to generate messaging code, this connection must be
defined.
URL: http://www.ourHub.com.

6. Choose File | Save All from the JDeveloper menu bar to save your changes.
If you wish, use Visual Properties to change the default font and color of your hub swimlane.
After creating a hub, go on to Creating Activities.
3-85
Creating Activities
An activity is a process that is performed in a business or system. The business analysts who
have examined the enterprise, determine that there are three activities: Take Order, Ship Order
and Back Order.
The following steps will create the Take Order and Ship Order activities in the diagram.
To create the Take Order activity:
1. Click the Activity icon in the Component Palette, then click in the Order Entry
swimlane to the right of the vertical bar. The element will appear on the diagram panel.
Note that the default name of the activity is highlighted.
2. Rename the activity: overtype the default name with Take Order and press RETURN.
You can now create the following activity in the same way:
● Create an activity called Ship Order in the Shipping swimlane, to the right of the
position of the Take Order activity.
● Create an activity called Back Order in the Inventory swimlane, below the Ship
Order activity.
If you wish, use Visual Properties to change the default font and color of your activities.
After creating activities, go on to Creating Object Flow States.
3-86
Creating Object Flow States
An object flow state represents an event or message that is passed between activities. The
business analysts who have examined the enterprise, determined that there is one message, a
new order (Order[new]), that is being passed between the Take Order and Ship Order
activities and the Take Order and Back Order activities.
The following steps will create the Order[new] object flow state.
To create an object flow state:
1. Click the Object Flow State icon in the Component Palette, then click on the diagram
below the Take Order activity in the Shipping swimlane. The object flow state is
created on the diagram with name of the object highlighted.
2. Rename the object flow state: overtype the default object name (the name at the top of
the shape) with Order and press RETURN. Overtype the default classifier in state name
(the name at the bottom of the shape) with new and press RETURN.
If you wish, use Visual Properties to change the default font and color of your object flow state.
After creating an object flow state, go on to Creating Pseudostates.
3-87
Creating Pseudostates
Pseudostates are used in activity diagramming for combining or splitting up transitions to
indicate possible parallel (concurrent) and/or mutually exclusive (alternative) paths through the
activities of the model. They also indicate the initial and final states of a diagram.
The following steps will create the INITIAL and OR states in the diagram.
To create INITIAL and OR states:
1. Click the INITIAL state icon in the Component Palette and click to the left of the Take
Order activity in the Order Entry swimlane.
2. Click the OR state icon in the Component Palette and click in the diagram to the right
of the Order object flow state in the Shipping swimlane.
After creating pseudostates, go on to Creating Transitions.
3-88
Creating Transitions
A transition indicates the relationship between elements in an activity diagram: the object at the
source end of the transition will perform certain specified actions, and will then enter the
destination end when a specified event occurs or when certain conditions are satisfied. These
conditions are known as "guard conditions".
Guard conditions must be specified on a transition if you are generating code for a decision
point.
To create transitions:
1. Hold down Shift and click the Transition icon in the Component Palette.
2. Click the INITIAL pseudostate, then click the Take Order activity.
3. Click the Take Order activity, then click the Order[new] object flow state.
4. Click the Order[new] object flow state, then click the OR pseudostate.
5. Click the OR pseudostate, then click the Ship Order activity.
6. Click the OR pseudostate, then click the Back Order activity.
7. Click the Select icon on the Component Palette to stop creating transitions.
To enter transition properties:
Identify the guard conditions and channel information for the transitions that lead out from the
sending activity and in to the receiving activity. In this case, these are the transitions from Take
Order to Order[new], from Order[new] to Ship Order and from Order[new] to Back
Order.
1. Double-click (or right-click and select Properties) the transition from Take Order to
Order[new].
In the General tab of the propeties dialog, enter order taken in the Guard Condition
field.
In the Integration tab, open the Channel drop-down list and select outchannel.
Click OK to commit your changes and dismiss the transitions dialog.
2. Double-click (or right-click and select Properties) on the transition from the OR
3-89
pseudostate to Ship Order.
In the General tab of the propeties dialog, enter order.stockCode < 9000 in the
Guard Condition field.
In the Integration tab, open the Channel drop-down list, select inchannel.
3. Double-click (or right-click and select Properties) on the transition from the OR
pseudostate to Back Order.
In the General tab of the propeties dialog, enter order.stockCode >= 9000 in the
Guard Condition field.
In the Integration tab, open the Channel drop-down list, select inchannel_2.
After creating transitions, go on to Changing the Font and Color Preferences.
3-90
Changing Font and Color Preferences
If you wish, you can change the default colors and fonts used to display activity model
elements.
1. Right-click the model element, or right-click in the swimlane to left of the vertical line (that
is, the swimlane panel) and select Visual Properties.
2. Select the font and color for the element:
❍ Click Font in the left panel of the Visual Properties dialog, then select your font
preferences
❍ Click Colors in the left panel of the Visual Properties dialog, then select your font
preferences.
3. Click OK to apply your changes.

4. Select File | Save All to save your changes.
After changing font and color preferences, go on to Reviewing the Defined E-Business
Integration.
3-91
Review the Defined E-Business Integration
When all the definitions required for e-business integration have been defined, you can now
review the required e-business integration properties before generating the e-business
integration files.
Note: You can define all the properties required for generating e-business integration files using the
E-Business Integration Wizard, but for the purpose of this tutorial the e-business integration
properties were defined against each element individually to give a better overall view of the creation
of an activity model for e-business integration.
To review the defined e-business integration properties:
1. Choose Model | Generate | E-Business Integration.

2. Step through the wizard, and review all the e-business integration properties you have
set on each element.
Note: All the properties must have the Defined check next to them before you can
generate.
3. Click Finish.
4. Click No.
After reviewing the defined e-business integration properties, go on to Generating the

Integration Point Messaging Code.
3-92
Generating the Integration Point Messaging Code
Once you have constructed the diagram and entered all of the properties for all of the elements,
you can generate messaging code.
Note: The e-business integration code generator requires a database connection to be defined
for each swimlane for which you are generating messaging code. These do not have to be valid
connections to real database servers—you can use arbitrary data to define the connections.
The only time you need valid database connections is when you deploy the generated files.
If you do not have a database connection defined for a swimlane, the generator will return an
error in the JDeveloper Log window and will not generate code.
To generate messaging code:

2. Click Next to continue to the Overview page.
3. Select the Generate checkbox next to the integration point you want to generate.
4. Click Finish.
5. Click YES to start code generation.
A progress monitor opens and tracks the file generation. The progress is also recorded in the
log window. If prompted whether to add the project to the source path, click Yes. Click OK to
dismiss the alert box that opens when generation is complete. The generator creates a
Generated EBI Files folder in the Navigator window and stores the generated files under it.
Select File | Save All from the JDeveloper menu bar to save the generated files.
For a description of the generator output, see Understanding the Generated Results.
3-93
Understanding the Generated Results
When the activity modeler generates the integration files, it stores them in the file system and
displays them in the JDeveloper Navigator window. The generation produces a three-deep
hierarchy of folders.
At the top level, the generator creates a Generated EBI Files folder for the project. This folder
contains a folder for each swimlane that has been defined in the project. Each swimlane folder
contains a folder for each diagram in which it is used. Each diagram folder contains the
generated integration files that will enable messaging between the systems.
For diagram created in this tutorial, the integration generator creates the Generated EBI Files
top-level folder. Beneath this, it creates a Swimlane Hub, a Swimlane Shipping, a Swimlane
Inventory and a Swimlane Order Entry folder. Beneath each of these folders is a folder for
each diagram in which the swimlane is used. In this case, the swimlanes are used in only one
diagram: SimpleIntegration.
In the diagram created in this tutorial, the Shipping, Order Entry and Inventory swimlanes
represent systems that act as the spokes in a hub-and-spoke architecture. For these systems
the generator creates an instanceInformation.xml file and an AQDefinitions.xml file.
As its name suggests, the instanceInformation.xml file contains the information that you
entered in the Instances tab of the Swimlane Properties dialog which is specific to each
instance belonging to the system. This XML file contains the system name and ID, instance
name and ID, and connection information for each instance defined for the system.
The AQDefinitions.xml file contains the information that you entered for the system in the
Channels tab of the Swimlane Properties dialog: the direction of the channel communications,
the communications protocol, and the name of the AQ queue and queue table in which it
should be stored. All other properties of the queue will be defaulted when the queue is created.
AQDefinitions.xml uses the instance information file to find the name of the database
connection that it will use to access the target system.
The Hub swimlane, as its name suggests, represents the system that acts as the hub in a hub-
and-spoke architecture. The Hub system will receive any messages which are sent between
the systems and route them to their appropriate targets.
In addition to an instanceInformation.xml and AQDefinitions.xml file, the integration

generator creates three additional files for the Hub system and stores them in the Swimlane
Hub folder. The BESDefinitions.xml file is created for the hub because it controls the
routing of messages between systems. This file stores the names of the systems, agents,
3-94
events, and event subscriptions that will be used in messaging between the hub and the other
systems. During deployment, only events are deployed without modification.
BESDefinitions.xml uses the instance information file to make the following modifications
to system, agent, and event subscription information for deployment:
● one system definition is assigned for each system instance

● one agent for each instance is assigned to each channel
● one event subscription is assigned to each instance of a target system.
The presence of a hub will force a workflow WorkflowDefinitions.wft file to be generated

for the simple integration point. Although there is no complex routing or decision making in this
example, workflow interprets any integration point as an event, regardless of whether it is a
simple integration point or a more complex case, such as a decision point. The workflow file
can be displayed in Oracle Workflow Builder.
3-95
Creating JClient Forms for Business Components
This tutorial shows you how to use JDeveloper to create a Java client that uses JClient forms to
interact with business components. The client, in this case, provides order-entry services based
on the Order Entry business components data model. You can run the JClient application after
completing the tutorial.
The goal of this tutorial is to teach you how to build a master-detail forms using JClient
component and Business Components for Java. In the tutorial example, you will create an
order entry application that lets you query and update records in a master-detail scenario that
also demonstrates the associated navigation functionality.
In this tutorial, you will learn how to do the following:

● Create a new Business Components project
● Create a new project for your JClient application
● Create a JClient master and detail form based on a view
● Utilize the Component Palette
● Utilize the UI Editor to modify a form
● Bind Swing components to an JClient application
● View JClient elements in the Structure Pane
After completing the tutorial requirements referenced in the related topics below, open the first
tutorial topic Creating a Business Components Project to get started.
Related topics
Requirements for Completing the Tutorial
3-96
In order to create a JClient application based on a Business Components application module,
you'll need to first create a project to contain the business components. This procedure shows
you how to use the Business Components Project Wizard.
To create a new Business Components project:
1. With Workspaces selected in the Navigator, right click and choose New Workspace to
create a workspace for your files. In the dialog box, rename the directory name
Workspace1 to JClientMasterDetailForm. Enter JClientOrders.jws as the file name.
2. In the New Project dialog box rename the project directory name Project1 to
BusinessComponents,enter the project filename BusinessComponents.jpr and click OK.
3. With BusinessComponents.jpr selected in the Navigator, right click and and choose New
Business Components....
The Business Components Project Wizard launches.
4. Click Next on the Welcome page to begin.

5. Select the Connection Name that you created for the Order Enter (OE) schema, for
example, tutorial_jdbc_connection, and click Next.
6. Enter the Package Name JClientOrders if it is not already entered and click Next.
7. Select the OE schema from the list of schemas.
8. Select the Tables option if it is not already selected.
9. Select the ORDERS and ORDER_ITEMS tables in the Available list and click the Move
move
buttonbutton to move those selections to the Selected list.
JDeveloper will create entity objects and associations for the selected tables and views.
10. Click Next to continue, and verify your package names and entity and view objects.
11. Click Finish to create the Business Components project.
12. Choose Project | Build Project BusinessComponents.jpr to compile the project.
Notice that the Message Log displays the compilation information.
The next step is to create a JClient project in the JClientOrders.jws workspace, as described in
3-97
Creating a JClient Project.
Related topics
Creating a JClient Project
3-98
Creating a JClient Project
Now create another project in the same workspace, which will contain the files you create for
your JClient application. You will be creating a JClient application containing a master-detail
form: A master for browsing customer orders and a detail for editing those orders.
To create a new project for your JClient application:
1. With the workspace JClientOrders.jws selected in the Navigator, create a new project by
selecting File | New....
2. With the Empty Project item selected from the New dialog click OK.
3. In the New Project dialog box rename the project directory name Project1 to
JClientMDForm,enter the project filename JClientMDForm.jpr and click OK.
4. Choose File | Save All to save all the files.
The next step is to create the JClient configuration that contains your client project's data model
definition, as described in Creating a Client Data Model Definition.
Related topics
Creating a Client Data Model Definition
3-99
Before you can create a JClient form, you must add a client data model definition to your
JClient project. The definition you create specifies which BC4J application module to use from
the business components project and how to connect to the application module. The
application module you choose defines the view objects and view object relationships available
to your data form.
To create a JClient data model:
1. With the JClient project JClientMDForm.jpr selected in the Navigator, create the data
model by selecting File | New....
2. Select the JClient Objects Category, then select JClient Data Model from the Items list
and click OK.
The JClient Data Model Wizard launches.
3. Click Next to step past the Welcome page.

4. Accept the default application module and configuration selection and click Next.
5. Enter the name OrderEntryDataModel for the name of the JClient data model and click
Finish.
JDeveloper will add the JClient configuration file (.cpx) to the JClient project. The file
contains one or more data model definitions.
The next step is to create the master-detail form, as described in Creating a JClient Form
Based on the Orders View.
Related topics
Creating a JClient Form Based on the Orders View
3-100
Creating a JClient Form Based on the Orders View
The following steps show you how to create a JClient master-detail form for browsing the
Orders view object. The procedure shows you how to use the JClient Form Wizard.
To create a JClient master-detail form based on the Orders View:
1. With the JClient project JClientMDForm.jpr selected in the Navigator, create a form by
selecting File | New....
2. Select the JClient Objects Category, then select JClient Form from the Items list and
click OK.
The JClient Form Wizard launches.
3. Click Next to step past the Welcome page.

4. In the Form Type page, select Master-Detail Tables as the kind of form and click Next.
5. In the Form Layout page, accept the default layout options and click Next.
6. In the Data Model page, accept the JClient data model you previously created and click
Next.
7. In the Panel Views page, accept OrdersView for the master view object and
OrderItemsView1 for the detail view object and click Next.
8. In the Attribute Selection page for master view object attributes, select the OrderMode
remove
attribute from the Selected Attributes list and click the Remove button to move this
button
selection to the Available Attributes list. Remove also CustomerId, OrderStatus, and
SalesRepId.
9. The Selected Attributes list should now show only OrderId, OrderDate, and OrderTotal.
Click Next.
10. In the Attribute Selection page for detail view object attributes, select the ProductId
remove
attribute and click the Remove button to move this selection to the Available
button
Attributes list.
11. The Selected Attributes list should now show only OrderId, LineItemId, UnitPrice, and
Quantity. Click Next.
12. In the File Names page, accept the default package and file names and click Next then
click Finish to create the JClient files.
3-101
14. Choose Project | Build Project JClientMDForm.jpr to compile the project.
Notice that the Message Log displays the compilation information.
The next step, Modifying the JClient Form, shows you how to use JClient to bind standard
Swing components to your JClient data model.
Related topics
Modifying the JClient Form
3-102
Modifying the JClient Form
The following steps show how to edit the JClient form in the UI Editor. You will also learn how
to bind standard Swing components to the JClient data model.
To edit the JClient form in the UI Editor:
1. With the PanelOrdersView.java file selected in the Navigator, right click and choose UI
Editor.
The UI Editor opens with the panel displayed.
2. Click the label element OrderId in the UI Editor, then choose View | Property Inspector if
the Inspector is not already visible.
3. In Property Inspector, edit the text property: change OrderId to Order Id.
4. In the UI Editor, select the label element OrderDate and edit its text property: change
OrderDate to Order Date.
5. In the UI Editor, select the label element OrderTotal and edit its text property: change
OrderTotal to Order Total.
7. Choose Project | Build JClientMDForm.jpr to compile the file.
8. Right click the FrameOrdersViewOrderItemsView1 frame class in the Navigator and
choose Run FrameOrdersViewOrderItemsView1.java to run the application.
You should see your JClient application with the orders data displayed in a table. On the
top you will see Next and Previous navigator buttons that let you browse through orders
data.
9. Close the application window or choose Run | Terminate

FrameOrdersViewOrderItemsView1.java before moving on to the next step.
To add a Swing component to the JClient form in the UI Editor:
1. If the Component Palette is not already visible, choose View | Component Palette.
2. With the PanelOrdersView.java displayed in the UI Editor choose Swing from the
Component Palette menu located directly above the UI Editor.
3-103
The Component Palette displays the Swing components.
3. Select the JTextField jtextfield

icon in the Component Palette, then click inside the
icon
PanelOrderView.java displayed in the UI Editor to add the component to the panel.
4. With the new text field element selection in the UI Editor, locate the document property
in the Property Inspector and click the field to display the list of available models. Choose
...JClient Attribute Binding to open the Document Property Editor for the JClient model.
Note: The document property is used for data binding only in JTextField controls. You
will use the model property to bind other Swing components.
5. In the Property Inspector, select the OrdersView view object and select OrderId from the
attributes list.
6. Click OK to update the Document property with the OrdersView.OrderId data definition.
8. Choose Project | Build JClientMDForm.jpr to compile the file.
9. Right click the FrameOrdersViewOrderItemsView1 frame class in the Navigator and
choose Run FrameOrdersViewOrderItemsView1.java to run the application.
You should see your JClient application with the the new databound order id text field
displayed. On the top you will see Next and Previous navigator buttons that let you
browse through orders data.
10. Close the application window or choose Run | Terminate

FrameOrdersViewOrderItemsView1.java.
This completes the JClient application tutorial. Run the completed application as described in
Running the Completed JClient Tutorial Application.
3-104
Creating and Using Web Services
Web services promise to revolutionize business computing by providing an easy way for
organizations to develop and reuse applications, connect business processes, and share
information with partners and customers. The exercises in this tutorial introduce you to the
JDeveloper features that help you to write and deploy Web services.
Following this tutorial you will write a simple Java class containing a method that returns the
date and time that you will expose:
● as a J2EE Web service deployed on Oracle9iAS Containers for J2EE (OC4J). This is the
simplest kind of Web service to create and deploy, and it conforms to the emerging J2EE
Web services standards that will be published in J2EE 1.4.
● as a Web service deployed to a SOAP server. JDeveloper can create Web services for
deployment to Oracle9i SOAP Servers and Apache 2.2 SOAP servers.
After you have deployed each Web service you will use JDeveloper to create a stub to the Web
service so that you can use it in a simple application to check that it works correctly.
Goals of this Tutorial
This tutorial will show you how to:
● Use Oracle9i JDeveloper's Web services features.

● Install the Oracle9iAS Containers for J2EE (OC4J) that comes with JDeveloper as a
standalone instance.
● Use the Web Service Publishing Wizard to write a J2EE Web service starting with a
simple Java class.
● Connect to OC4J and deploy the J2EE Web service to OC4J's Web services container.
● Use the Web Service Stub/Skeleton Wizard to generate a Java stub for an application
that uses this Web service.
● Use the Web Service Publishing Wizard to write a SOAP Web service starting with a
simple Java class.
● Connect to OC4J's SOAP server, deploy your SOAP Web service to it and register the
service.
● Use the Web Service Stub/Skeleton Wizard to generate a Java stub for an application
that uses this Web service.
3-105
You should expect to spend 45 minutes completing this tutorial. When you are ready to begin,
go to the first tutorial topic, Installing, Starting and Stopping OC4J.
Related topics
Web Services
3-106
Installing, Starting and Stopping OC4J
JDeveloper includes the Oracle9iAS Containers for Java2 Enterprise Edition (J2EE) or "OC4J"
for short. OC4J includes containers for the J2EE APIs which enable users to run their J2EE-
based applications entirely in the standard Java Development Kit (JDK) executing on the Java
Virtual Machine (JVM).
JDeveloper contains an embedded OC4J server which is used to help you develop EJBs, JSPs
and so on. This topic describes how to run it as a standalone instance to which you can deploy
your J2EE Web service (to the Web Services container) and your SOAP Web service (to the
Oracle9i Release 2 SOAP Server).
First you have to install OC4J, and then start it. You can use a browser to test that it is running
correctly. This topic also tells you how to stop OC4J.
To install OC4J:
1. From the Command Prompt, navigate to <JDeveloper_home>\j2ee\home.

2. Type start java -jar oc4j.jar -install
3. When prompted, enter an admin password.
Once you have installed OC4J, you can start it and leave it running in the background.
To start OC4J:

2. Type start java -jar oc4j.jar
You can test that OC4J is running by following the instructions below.
To test that OC4J is running:
● Enter the following URL in a browser, where <hostname> is the IP address of your local
machine.
http://<hostname>:8888
3-107
If you have installed and started OC4J correctly, you will see the following
message:
Oracle9iAS Containers for J2EE 9.0.2.0.0 - Up and running
followed by links that provide more information about Oracle9iAS. This is the
connection to which you deploy your J2EE Web service.
To test that the SOAP Server in OC4J is running:
● Enter the following URL in a browser, where <hostname> is the IP address of your local
machine.
http://<hostname>:8888/soap/servlet/soaprouter
If you have installed and started OC4J correctly, you will see the following
message:
SOAP Server
Sorry, I don't speak via HTTP GET- you have to use HTTP POST
to talk to me.
This is the connection to which you deploy your SOAP Web service.
Now that you have installed and started OC4J, you can continue to Creating a Java Class.
To stop OC4J follow the instructions below.
To stop OC4J:

2. Type java -jar admin.jar ormi://<hostname> <admin_password> -
shutdown, where <admin_password> is the password you entered when you installed
OC4J.
Related topics
3-108
About Deploying on Oracle9i Application Server
Web Services
3-109
Creating a Java Class
The basis of your Web service is the Java class that defines a public method for each method
that want to expose as a Web service.
First, you will create a workspace and project to contain your files, then you will create a Java
class which contains a method that returns the current date and time.
To create the Java class:
1. With the Workspaces node selected in the Navigator pane, choose File | New.
2. In the New Gallery, choose Projects in the Categories pane and Workspace in the Items
pane.
3. In the New Workspace dialog, enter WebService as the directory name, and
DateTimeService.jws as the file name. Make sure Add a new empty project is
selected.
4. In the New Project dialog, enter a project file name of DateTimeServProj and a
project file name of DateTimeServProj.jpr. The new workspace and its project are
displayed in the Navigator pane.
5. With the project selected in the Navigator pane, right click and choose New Class from
the context menu.
6. In the New Class dialog, enter a class name of DateTimeService. Change the
package name to datetimeservicepackage. Leave the Optional Attributes at their
default values. When you click OK, the new class is displayed in the Navigator pane, and
the file is opened in the Code Editor.
7. Add a method which will return the date and time when called:
public static String getDate()

{
return (new java.util.Date()).toString();
8. You can specify that a method to be exposed as a Web service is automatically selected
by the Web service Publishing Wizard by using the @webmethod Javadoc tag. Before
the method add the following:
/**
3-110
* @webmethod
*/
9. Remember to save your work. Your DateTimeService class should now look like:
package datetimeservicepackage;
public class DateTimeService

{
public DateTimeService()
{
}
/**
* @webmethod
*/
{
}
}
You have now created the class containing the method on which your Web service will be
based. Next, you are going to use the Web Service Publishing Wizard to create the files you
need to deploy the service. You are going to create and deploy a J2EE Web service. After you
have tested that it works correctly, you will deploy a Web service based on the same class to a
SOAP server and test it.
Proceed to Creating a J2EE Web service.
Related topics
Creating a New Empty Class
Web Services
3-111
3-112
Creating a J2EE Web Service
You are going to create a J2EE Web service from your Java class.
First you will create the connection to Oracle9i Containers for J2EE (OC4J). Next, you will use
JDeveloper's Web Service Publishing Wizard to create a J2EE Web service from your Java
class, and after that you will deploy your Web service to this server.
Related topics
Web Services
3-113
Connecting to Oracle9i Containers for J2EE
In this tutorial you are using the standalone instance of OC4J. For information about deploying
to Oracle9i Application Server, refer to About Deploying on Oracle9i Application Server.
To connect to OC4J:
1. Expand the Connections node in the Navigator, and choose New Connection from the
Application Server context menu. The Connection Wizard is displayed.
2. If the Welcome page is displayed, click Next.
3. Enter WSTutiASConnection as the connection name and click Next.
4. The Authentication page is displayed. Leave the default Username of Admin, and enter
the Password you used when you installed OC4J. Leave the Role blank, and check
Deploy Password. Click Next.
5. The Connection page is displayed. The connection information for OC4J running on your
local machine are:
❍ URL - ormi://<hostname>, where <hostname> is that of your local machine.
❍ Target Web Site - http-web-site

❍ Local Directory Where admin.jar for Oracle9iAS is Installed -
<JDeveloper_home>\j2ee\home
Click Next.
6. The Test page is displayed. Click Test. The results of the test are displayed. If the test
succeeds, click Finish.
Now that you have an OC4J connection, you can use JDeveloper's Web Service Publishing
Wizard to create your J2EE Web service.
Related topics
Creating a Connection to Oracle9iAS Containers for J2EE (OC4J)
Web Services
3-114
3-115
Using JDeveloper to create a J2EE Web service
You are going to use JDeveloper's Web Service Publishing Wizard to create a J2EE Web
service from the Java class you created earlier.
To create a J2EE Web service:
1. With the project selected in the Navigator pane, choose File | New.
2. In the New Gallery, choose Web Services in the Categories pane and Web Service in the
Items pane. The Web Service Publishing Wizard is displayed.
4. Select the class you created by clicking Browse and navigating to the
datetimeservicepackage, and then selecting the DateTimeService class.
5. A default Web Service Name is displayed which you can leave unchanged.
6. Leave the Deployment Platform as the default of Oracle J2EE Web Server and click
Next.
7. On the Exposed Methods page of the wizard you can see the methods available to
publish as a Web service. Because you used the @webmethod Javadoc tag the
getDate() method is already selected. Click Next.
8. On the File Locations page, select the connection you defined to OC4J as the
Application Server Endpoint.
9. Click Finish.
Because you left the targetNamespace as the default a warning message is displayed.
The default targetNamespace is composed from http://tempuri.org followed by
generated and then the package name and class name of the service. This is fine for
this tutorial, but before you publish the Web service you should edit the deployment
container so that the targetNamespace is unique. Click Yes to ignore the message.
10. The following files are generated and displayed in the Navigator:
❍ WSDL document is displayed in the
urn:datetimeservicepackage.DateTimeService container
❍ WebService.deploy deployment profile. This is a J2EE Web Module deployment
profile and it is created at project level. If you generate more Web services in the
same project, the appropriate files in this profile are updated.
❍ web.xml file. When there is already a web.xml file in a project, it is just updated
with information about the J2EE Web service.
3-116
Next, you will deploy the J2EE Web service.
Related topics
About J2EE Web Modules in JDeveloper
Web Services
3-117
Deploying the J2EE Web Service
Now that you have used the Web Service Publishing Wizard to create the files needed for your
Web service, you now have to deploy the Web service.
To deploy the Web service:
1. With WebServices.deploy selected in the Navigator, right click and select Deploy to
from the context menu. Select the connection to OC4J that you defined earlier,
WSTutiASConnection.
2. You can see the progress in the log windows at the bottom of your screen. If these are
not visible, you can display them by choosing View, Log Window.
You have now created and deployed a J2EE Web service. The only difference between what
you have done here and developing a Web service to publish is that when you ran the Web
Service Publishing Wizard, you would have entered a unique targetNamespace, for example
one based on your your organization's Web domain.
The final topic shows you how to create a Web service stub that uses your Web service. See
Testing the J2EE Web Service.
Related topics
Web Services
3-118
Testing the J2EE Web Service
This topic shows you how to test your new J2EE Web service by creating an application that
uses it. The first step is to create a stub for the Web service using JDeveloper's Web Service
Stub/Skeleton Wizard, then you will write a simple class that uses the method exposed in the
stub.
To create a stub:
1. With the project selected in the Navigator pane, choose New.

2. In the New Gallery, choose Web Services in the Categories pane and Web service
Stub/Skeleton in the Items pane. The Web Service Stub/Skeleton Wizard is displayed. If
the Welcome page is displayed, click Next.
3. Browse to the WSDL file of the Web service you have just created and click Open to
enter it in Enter the URL of the Web service Description (WSDL).
4. In Generation Options, make sure that Generate Client-Side Stubs is selected, and that
the other options are not selected. Click Next.
5. The DateTimeService method is shown on the Exposed Methods page. Because you
used the @webmethod Javadoc comment, the method is automatically selected.
6. Click the DateTimeService method to see the defaults for the package and class name.
7. To generate the stub, click Finish. The file DateTimeServiceStub.java is generated
and displayed in the Code Editor.
Next, you are going to write a simple application that returns the date and time.
To use the Web service:
1. Create a new class by selecting the DateTimeClient.jpr project in the Navigator,

and choosing New Class from the context menu.
2. In the New Class dialog, enter the name as DateTimeClient and select Generate
Main Method.
3. The new class is displayed in the Code Editor. Add the appropriate code so that the
class looks like the following:
package datetimeservicepackage;
public class DateTimeClient
3-119
{
public DateTimeClient()
{
}
public static void main(String[] args) throws Exception

{
DateTimeServiceStub d = new DateTimeServiceStub();
System.out.println("The date and time is " + d.getDate());
}
}
4. With the project selected in the Navigator, choose Build Project.

5. Choose DateTimeClient.java in the Navigator. Right click and choose Run
DateTimeClient.java. The log windows displays the results, and shows the current date
and time returned by your J2EE Web service running on OC4J. If the log windows are
not visible, choose View, Log Window.
Now that you have seen how easy it is to use JDeveloper to create and deploy a J2EE Web
service and incorporate it into an own application, you can try creating a SOAP Web service
starting from the same Java class. Go to Creating a SOAP Web Service.
Related topics
Web Services
3-120
Creating a SOAP Web Service
Now that you have created a J2EE Web service, you are going to create a Web service from a
similar Java class and deploy on a SOAP Server.
Start by using creating a new workspace and folder, and creating the Java class to that folder.
1. In JDeveloper, select the workspaces node in the Navigator. Right click and choose New
Workspace from the context menu.
2. In the New Workspace dialog, enter SOAPWebService as the directory name, and
SOAPDateTimeService.jws as the file name. Make sure Add a new empty project is
selected.
3. In the New Project dialog, enter a project file name of SOAPDateTimeServProj and a
project file name of SOAPDateTimeServProj.jpr. The new workspace and its project
are displayed in the Navigator pane.
4. With the project selected in the Navigator pane, right click and choose New Class from
the context menu.
5. In the New Class dialog, enter a class name of SOAPDateTimeService. Change the
package name to soapdatetimeservicepackage. Leave the Optional Attributes at
their default values. When you click OK, the new class is displayed in the Navigator
pane, and the file is opened in the Code Editor.
6. Add the same code as you did earlier so that your DateTimeService class looks like:
package soapdatetimeservicepackage;
public class SOAPDateTimeService

{
public SOAPDateTimeService()
{
}
/**
* @webmethod
*/
{
}
}
3-121
Now you are ready to create the connection to the SOAP Server. Next, you will use
JDeveloper's Web Service Publishing Wizard to create a SOAP Web service from your Java
class, and after that you will deploy your Web service to the SOAP server.
Related topics
Web Services
3-122
Connecting to the Oracle9i SOAP Server
This shows you how to connect to the Oracle9i Release 2 SOAP Server, which part of the
standalone OC4J instance.
To connect to the Oracle9i SOAP Server:
1. Expand the Connections node in the Navigator, and choose New Connection from the
SOAP Server context menu. The SOAP Server Connection Wizard is displayed.
3. Enter WSTutSOAPConnection as the connection name.
4. Enter the SOAP servlet URL
5. http://<hostname>:8888/soap/servlet/soaprouter
where <hostname> is the IP address of your local machine, then click Next.
6. The Authentication page is displayed. Leave these fields blank. Click Next.
7. The Test page is displayed. Click Test. The results of the test are displayed.
8. If the test succeeds, click Finish.
Now that you have a connection to a SOAP server, you can proceed to Using JDeveloper to
create a SOAP Web service.
Related topics
Configuring SOAP Server Connections
Web services
3-123
Using JDeveloper to Create a SOAP Web Service
You are going to use JDeveloper's Web Service Publishing Wizard to create a SOAP Web
service from the Java class you created earlier.
To create the SOAP Web service:
1. With the project SOAPDateTimeServProj.jpr selected in the Navigator pane, choose

File | New.
2. In the New Gallery, choose Web services in the Categories pane and Web service in the
Items pane. The Web Service Publishing Wizard is displayed.
4. Select the class you created by clicking Browse and navigating to the
soapdatetimeservicepackage, and then selecting the SOAPDateTimeService
class.
5. A default Web Service Name is displayed which you can leave unchanged.
6. Change the Deployment Platform to Oracle9iAS Release 2/Apache 2.2 SOAP
Server and click Next.
7. On the Exposed Methods page of the wizard you can see the methods available to
publish as a Web service. Because you used the @webmethod Javadoc tag the
getDate() method is already selected.
8. Leave the Options unchanged, and click Next.
9. On the File Locations page, select the connection you defined to the SOAP server as the
Web Service Endpoint. If the connection is not listed, go back to Step 1 of the wizard
and check that you have selected the correct Deployment Platform.
10. Click Finish. Because you left the targetNamespace as the default a warning message is
displayed. Click Yes to ignore the message and generate the service.
11. The WSDL document and deployment descriptor file are generated and displayed in the
Navigator pane in the urn:datetimepackage.DateTimeService container.
The next step is to deploy and register the Web service.
Related topics
3-124
Web Services
3-125
Deploying and Registering the SOAP Web Service
Now that you have used the Web Service Publishing Wizard to create the files needed for your
Web service, you have to create a deployment profile and deploy the archive to the appropriate
location. Finally, you will register the service to make it available.
To deploy the Web service:
1. With the project selected in the Navigator pane, choose File | New.
2. In the New Gallery, choose Deployment Profiles in the Categories pane and JAR File -
Simple Archive in the Items pane. The Save Deployment Profile -- JAR File - Simple
Archive dialog is displayed.
3. Change the name of the file to soapDateTimeService.deploy and click Save.
4. The JAR Deployment Profile Settings dialog is displayed. Click OK.
5. Right click on soapDateTimeService.deploy in the Navigator, and select Deploy to
from the context menu. The Deploy to Java Archive (JAR) File dialog is displayed
6. Change the default location to
<JDeveloper_home>\soap\webapps\soap\soap\WEB-INF\lib. This puts the file
in the classpath automatically, and the server does not need to be stopped and restarted.
To register the Web service:
● With the Web service container

urn:soapdatetimepackage.SOAPDateTimeService selected in the Navigator
select Register with from the context menu, and choose the connection
WSTutSOAPConnection.
You have now created and deployed the Web service. Expand the WSTutSOAPConnection
node under the SOAP Server connection node in the Navigator to see it listed.
The only difference between what you have done here and developing a Web service to
publish is that when you ran the Web Service Publishing Wizard, you would have entered a
unique targetNamespace, for example one based on your your organization's Web domain.
The final topic shows you how to create a Web service stub that uses your Web service. See
Testing the SOAP Web service.
3-126
Related topics
Web Services
3-127
Testing the SOAP Web Service
This topic shows you how to test your new Web service by creating an application that uses it to return the
date and time. The first stage is to create a stub for the Web service, then you will use the copy of the
class that uses the method exposed in the stub.
To create a stub:
1. With SOAPDateTimeServProj.jpr selected in the Navigator pane, right click and choose New
from the context menu. In the New Gallery, choose Web Services in the Categories pane and Web
Service Stub/Skeleton in the Items pane. The Web Service Stub/Skeleton Wizard is displayed. If
the Welcome page is displayed, click Next.
2. Browse to the WSDL file of the Web service you have just created, and click Open to enter it in
Enter the URL of the Web service Description.
3. In Generation Options, make sure that Generate Client-Side Stubs is selected, and that the other
options are not selected. Click Next.
4. The SOAPDateTimeService method is shown on the Exposed Methods page. Because you used
the @webmethod Javadoc comment, the method is automatically selected.
5. Click SOAPDateTimeService, and see the defaults for the package and class name.
6. To generate the stub, click Finish. The file SOAPDateTimeServiceStub.java is generated and
displayed in the Code Editor.
Finally, you are going to write a simple application that returns the date and time.
To use the Web service:
1. Create a new class by selecting the SOAPDateTimeClient.jpr project in the Navigator, and
choosing New Class from the context menu.
2. In the New Class dialog, enter the name as SOAPDateTimeClient and select Generate Main
Method.
3. The new class is displayed in the Code Editor. Add the appropriate code so that the class looks like
the following:
package soapdatetimeservicepackage;
public class SOAPDateTimeClient

{
public SOAPDateTimeClient()
{
}
public static void main(String[] args) throws Exception

{
3-128
SOAPDateTimeServiceStub s = new SOAPDateTimeServiceStub();
System.out.println("The date and time is " + SOAPDateTimeService.getDate());
}
}
4. With the project selected in the Navigator, choose Build Project.

5. Choose SOAPDateTimeClient.java in the Navigator. Right click and choose Run
SOAPDateTimeClient.java. The log windows displays the results, and shows the current date and
time returned by your Web service running on a SOAP server. If the log windows are not visible,
choose View, Log Window.
Now that you have seen how easy it is to use JDeveloper to create and deploy a J2EE Web service, and
a Web service deployed to a SOAP Server, you can try creating more complex examples, for example,
you could try publishing the remote interface of a stateless EJB session bean as a Web service.
Related topics
Web Services
3-129
● Developing Web Applications (J2EE Web Modules)
❍ About J2EE Web Modules in JDeveloper
■ About Web Module Directory Structure
■ About J2EE Application Server Requirements
■ About Web Module Runtime Configuration
❍ Working with Java Servlets
■ About Java Servlets
■ About HTTP Servlets
■ Generating an HTTP Servlet
■ Implementing Basic Methods for an HTTP Servlet
■ Using the HTTPServletRequest Object
■ Using the HTTPServletResponse Object
■ Configuring Servlet Runtime Properties for the Web Deployment Descriptor
■ Testing and Debugging a Servlet
■ Deploying Java Servlets
❍ Working with JSP Pages
■ About JavaServer Pages
■ About JSP Pages and JDeveloper Tools
■ Creating a Simple JSP Page
■ Generating a Web Application from an Existing WAR File
■ Inserting JSP Tags Using the Component Palette
■ Inserting HTML and JSP Tags Using Code Insight
■ Editing JSP Pages Using the Code Editor
■ Configuring JSP Runtime Properties in the Web Deployment Descriptor
■ Testing and Debugging JSP Pages
■ Deploying JSP Pages
❍ Working with JSP Tag Libraries
■ About JSP Tags
■ About Custom Tag Libraries in JDeveloper
■ Creating a Custom JSP Tag Library in JDeveloper
■ Registering a Custom Tag Library in JDeveloper
■ Adding Pages and JSP Tags to the Component Palette
❍ Working with Data Bound BC4J JSP Pages
■ About JSP Pages and Business Components
■ About BC4J JSP Page Templates
■ About BC4J Data Tags
■ About BC4J Component Data Tags
■ About BC4J Form Input Data Tags
4-1
■ About BC4J Multimedia Data Tags
■ About Rendering Data with BC4J Data Tags
■ About Creating Rows Using BC4J Data Tags
■ About Editing Rows Using BC4J Data Tags
■ About Control Hints for Business Components Clients
■ About JSP Pages and BC4J Application Module Pooling
■ About BC4J Configuration Properties for a JSP Project
■ About Web Beans
■ Defining Business Component Runtime Properties in the bc4j.xcfg File for Web
Applications
■ Customizing the UI Using Control Hints
■ Defining a Formatter and Format Masks for the UI
■ Ways to Generate Data Bound BC4J JSP Pages
■ Generating JSP Pages Based on BC4J View Objects
■ Generating a JSP Application Based on a BC4J Application Module
■ Working with BC4J Data Tags
■ Adding Data Tags to a BC4J JSP Page
■ Specifying an Application Module for JSP Pages
■ Managing Application Module State Using Data Tags
■ Rendering Multimedia Content Using Data Tags
■ Locating a Row Using Data Tags
■ Creating Rows Using Data Tags
■ Updating Rows Using Data Tags
■ Handling Database Transactions Using Data Tags
■ Working with BC4J Component Tags
■ Adding Component Tags to a BC4J JSP Page
■ Customizing BC4J Component Tags
■ Working with Web Beans
■ Adding Web Beans to a BC4J JSP Page
■ Creating a Custom Web Bean
■ Reference: BC4J Data Tags Library
■ Reference: Web Bean Classes
■ Web Bean Classes
■ Data Web Bean Classes
❍ Working with OJSP Tag Libraries

■ About Oracle Caching Support for Web Applications
■ Working with JESI Tags for Edge Side Includes
■ Reference: OC4J JESI Tag Library
4-2
■ Working with Web Object Cache Tags
■ Reference: OC4J Web Object Cache Tag Library
■ Working with Data-Access Tags

■ About Data-Access Tags
■ Reference: OC4J Data-Access Tag Library
■ Working with JSP Utility Tags

■ About JSP Utility Tags
■ Reference: OC4J EMail Tag Library
■ Reference: OC4J File Access Tag Library
■ Reference: OC4J EJB Tag Library
■ Reference: OC4J Utility Tag Library
■ Working with XML and XSL Tags

■ About Integration with XML and XSQL
■ Reference: OC4J XML Tag Library
4-3
Developing Web Applications (J2EE Web Modules)
These topics describe how JDeveloper helps you to develop J2EE compliant web modules. For
details about J2EE support in JDeveloper, see About J2EE Web Modules in JDeveloper.

Working with Java Servlets Describes the JDeveloper tools to create, edit, and debug your
Java Servlets. Topics describe how to use the HTTP Servlet
Wizard to generate servlets that can process client HTTP
requests.
Working with JSP Pages Use JDeveloper tools to create, edit, and debug your JSP pages.
Topics describe how to add a single JSP page to your project and
design the page with JSP elements that you insert yourself.
Working with JSP Tag Libraries Use JDeveloper tools to simplify the task of creating new JSP
custom tag libraries as well as importing and registering custom
tag libraries from another source.
Working with Data Bound BC4J JSP Pages Use the BC4J Data Tags custom tag library to create data bound
JSP pages that access BC4J datasources. Topics describe how
to use the wizards to generate data bound JSP applications and
individual data bound JSP pages, or to design individual pages
with elements that you insert yourself.
Working with UIX XML and UIX JSP Pages Use JDeveloper tools to create, edit, and debug your UIX XML
and UIX JSP pages. Topics describe how to use wizards to
generate data bound UIX and JSP applications and pages, and to
create individual pages and templates.
Working with the XSQL Servlets Use JDeveloper tools to create XSQL servlet clients that access
the database and use the Business Components XSQL action
handlers. Topics describe how to use XSQL tags, view raw XML
data, and format XSQL pages with an XSL stylesheet.
UIX Developer's Guide Provides a technical introduction to UIX and its underlying
technologies. Topics describe how to develop all aspects of an
application using the services provided by UIX.
4-4
UIX Element Reference Describes each element available with UIX, including: UIX
component elements, UIX BC4J elements, UIX controller
elements, and UIX style. Each reference topic includes an
example demonstrating the element usage.
Related topics
About Web Module Directory Structure

About J2EE Application Server Requirements
About Web Module Runtime Configuration
Creating and Deploying a J2EE Web Module (WAR)
4-5
The Java 2 Platform, Enterprise Edition (J2EE) provides a common standard that helps
developers build enterprise level multi-tier applications using Java. Oracle9i JDeveloper
provides complete support for the development of enterprise applications. This section
discusses JDeveloper's support for building J2EE Web modules, which are a key component of
any enterprise Java application.
Oracle9i JDeveloper supports J2EE 1.2 standards, including JSP 1.1 and Servlet 2.2. The
JDeveloper development environment provides the ability to productively develop, test and
deploy these J2EE Web modules:
● Java servlets
● HTTP servlets
● JavaServer Pages (JSP) pages
About J2EE Web Modules
A J2EE Web module is a deployable J2EE web application. A Web module contains a
complete Web application with a defined directory structure and a Web deployment descriptor
file (web.xml). When a Web module is packaged into a Web module archive (WAR) file it can
then be deployed to any J2EE-compliant application server.
A J2EE Web application typically consists of a set of Web components, JavaBeans

components, and other static Web content such as HTML, images, and css.
Web components are Java entities that provide a response to an HTTP request. The J2EE
platform specifies two types of Web components: Servlets and JSP pages. J2EE Web modules
are deployed to a Web container, which is the runtime environment for Servlets and JSPs and
resides on the Web tier.
About Development of J2EE Web Modules in JDeveloper
All the components which make up J2EE Web applications can be built and integrated in
JDeveloper. In addition to JavaBeans and HTML elements, JDeveloper provides specific
support for developing:
● Web components, including HTTP servlets and JSP pages

● Custom JSP tag libraries
4-6
JSP and servlet application developers will benefit from these features:
● Quick creation wizards for both HTTPServlet generation and JSP (can be data bound)
generation
● Support for creating custom tag libraries, which enable productive development and
deployment of JSP custom tag libraries
● JSP tag insight and Java code insight in JSP and servlet files
● JSP source level debugging and servlet debugging (including remote debugging)
● Web Module Archive (WAR) deployment support
Additionally, JDeveloper offers a productive data bound JSP development environment. Many
products have basic support for building JSP and servlet applications but lack a framework for
creating data bound JSP pages, such as Oracle Business Components for Java (BC4J)
included with JDeveloper. The BC4J framework greatly enhances the productivity and power of
a database developer. The BC4J Data Tags custom tag library and powerful BC4J Component
Tags extend the power of BC4J to JSP application development without sacrificing ease of use.
About Testing and Debugging of J2EE Web Modules in JDeveloper
For testing and debugging of both Web components and EJBs, JDeveloper contains an
embedded Oracle9iAS Containers for J2EE (OC4J). This allows for complete design, testing,
and debugging of JSP, servlets, and EJBs in a J2EE compliant runtime environment.
Deployment of J2EE Web Modules in JDeveloper
JDeveloper also has the ability to package Web applications and deploy them as J2EE Web
modules on any J2EE application server. JDeveloper also provides additional integration with
Oracle9i Application Server with one-click deployment.
For Enterprise Applications using the Business Components for Java (BC4J) framework,
JDeveloper provides additional integration in the form of custom tag library and JSP code
generation wizards.
JDeveloper also allows for the development and deployment of Web modules which use
technologies including: the Oracle XML Developers Kit, Oracle XSQL servlet, and Oracle User
Interface XML (UIX).
4-7
Related topics

See also
For more information on J2EE terminology and architecture, see the J2EE blueprints:
http://java.sun.com/j2ee/blueprints/
4-8
The J2EE Web module has a clearly defined directory structure which allows it to be completely
portable to any J2EE-compliant application server. The following is the directory structure of a
J2EE Web module.
A Web module is contained within a single root directory, which corresponds to the HTML root
of the application with specific sub-directories.
/root directory
This directory can contain files, including .html and .jsp (the HTML and JSP pages),
along with other files that must be visible to the client browser (such as JavaScript,
stylesheet files, and images) for your application. In larger applications, you may choose
to divide these files into a subdirectory hierarchy, but for smaller applications, it is
generally much simpler to maintain only a single directory for these files.
Note: On some J2EE application servers the root directory name serves as the "Web context
root". In Oracle9i JDeveloper and OC4J, this is configurable as a project property.
/WEB-INF/ subdirectory
The /WEB-INF/ subdirectory contains the required Web Application Deployment
Descriptor (web.xml) and the optional /WEB-INF/classes/ subdirectory, and /WEB-
INF/lib/ subdirectory.
/WEB-INF/web.xml
The Web Application Deployment Descriptor for your application. This is an XML file
describing the servlets and other components that make up your application, along with
any initialization parameters and container-managed security constraints that you want
the server to enforce for you. This file is discussed in more detail in About Web Module
Runtime Configuration.
/WEB-INF/classes/
This directory contains any Java class files (and associated resources) required for your
application, including both servlet and non-servlet classes, that are not combined into
JAR files. If your classes are organized into Java packages, you must reflect this in the
directory hierarchy under /WEB-INF/classes/. For example, a Java class named
com.mycompany.mypackage.MyServlet would need to be stored in a file named /WEB-
INF/classes/com/mycompany/mypackage/MyServlet.class.
/WEB-INF/lib/
4-9
This directory contains JAR files that contain Java class files (and associated resources)
required for your application, such as third party class libraries or JDBC drivers.
Related topics

See also
For more information on the J2EE Web Module directory structure, consult the Servlet API
specification:
http://java.sun.com/products/servlet/
4-10
Oracle9i JDeveloper provides development support for J2EE 1.2 or specifically, servlet 2.2,
JSP 1.1 and EJB 1.1. Your deployment application server must support JSP 1.1, servlet 2.2
and EJB 1.1 or above.
Note: A J2EE 1.3 based application server is also a compatible platform.
Related topics
4-11
The Web Module runtime configuration is governed by the Web Application Deployment
Descriptor (web.xml).
This file is an XML document which defines everything about your application that a server
needs to know (except the root context path, which is assigned by JDeveloper or the system
administrator when the application is deployed). Typical runtime settings include: Servlet
runtime and initialization parameters, custom tag library location, and security settings.
Related topics

Configuring Servlet Runtime Properties in the Web Deployment Descriptor
Configuring JSP Runtime Properties in the Web Deployment Descriptor
See also
The complete syntax and semantics for the deployment descriptor is defined in the Servlet API
Specification:
4-12
Working with Java Servlets
JDeveloper provides a complete development environment to simplify the task of developing
servlets:
● Generating a simple HTTP servlet
● Implementing basic HTTP servlet methods
● Configure runtime properties for the Web Deployment Descriptor
● Testing and debugging
● Remote debugging
● Deploying servlets
Related topics
About Java Servlets

About HTTP Servlets
4-13
About Java Servlets
A servlet is a platform-independent, server-side Java component used to extend the
capabilities of a web server. Using servlets, you can dynamically tailor content, function, and
the look and feel of your web pages. Servlets process client requests and can respond by
returning any MIME type to the requesting client, including images, XML, and HTML. Servlets
run inside web servers, so they do not require a graphical user interface. They are typically
used to dynamically generate HTML content and present it to the requesting client. You can
think of a servlet as the server-side counterpart to an applet.
Servlets are based on a standard API and protocol defined by JavaSoft. To run a servlet, your
environment needs a web server that supports the JavaSoft servlet API, such as the
Oracle9iAS Containers for J2EE (OC4J), JavaSoft Java Server, and Apache Tomcat, among
others.
For additional information about servlets, see the JavaSoft Servlet Home Page.
Related topics
Generating an HTTP Servlet

Implementing Basic Methods for an HTTP Servlet
Configuring Servlet Runtime Properties for the Web Deployment Descriptor
Testing and Debugging a Servlet
Creating and Deploying a J2EE Web Module Deployment Profile (WAR)
Deploying a BC4J Web Application
See also
For more information on Java Servlet technology, go to this java.sun.com web page:
http://java.sun.com/products/servlet/index.html
4-14
About HTTP Servlets
Servlets are often used to process HTTP requests submitted by a client, and to provide
dynamic content by returning results of a database query to a client. This type of Java servlet is
known as an HTTP servlet. A typical runtime scenario for an HTTP servlet is as follows:
1. A client sends an HTTP request to the servlet. The client could be a web browser or
some other application or applet.
2. The servlet processes the request and responds by returning data to the client. In the
case of HTML servlets, these servlets generate and send dynamic HTML content back to
the client. If the servlet is designed to do so, it may request data from a database server
on behalf of the client, then package and return the results to the client in an HTML form.
This can be done using JDBC or by working with the Business Components for Java
(BC4J) framework.
3. The client user can then interactively view and respond to the generated HTML content,
perhaps making additional requests through the generated HTML form.
Related topics

See also
For more information on Java Servlet technology, go to this java.sun.com web page:
http://java.sun.com/products/servlet/index.html
4-15
1. In the Navigator, select the project in which you want to create the new servlet.
2. Choose File | New to open the New Gallery dialog.
3. Select the Web Object folder.
4. Double-click the HTTP Servlet icon in the Items list to display the HTTP Servlet Wizard.
This will start the HTTP Servlet Wizard which will create the servlet for you based on
information you specify, including the methods and parameters for the servlet. Click the
Help button to obtain context-sensitive help in the wizard panels.
A simple servlet is generated and appears in your active project. The deployment descriptor file
web.xml is also added to your project. The deployment descriptor file is used by JDeveloper's
embedded web server when you run the servlet.
Related topics

About HTTP Servlets
4-16
When you use the HTTP Servlet Wizard to create an HTTP servlet, the wizard creates a Java
class for the servlet. This class contains an initialization method and the HTTP methods you
specified for the servlet when using the wizard. To customize the servlet, you must implement
the servlet's HTTP methods.
The following methods are available from the HTTP Servlet Wizard:
● doGet handles GET, conditional GET, and HEAD requests

● doPost handles POST requests
● doPut handles PUT requests
● doDelete handles DELETE requests
JDeveloper creates skeleton code for these methods. These methods take two objects as
arguments: HttpServletRequest and HttpServletResponse.
You can also pass in additional parameters and get them programmatically by calling the
ServletRequest.getParameter method within your servlet's Java code.
Related topics
Using the HTTPServletRequest Object

Using the HTTPServletResponse Object
About HTTP Servlets
4-17
The first HTTP argument in a basic servlet method is an HttpServletRequest object. This object
provides methods to access:
● HTTP header data, including cookies found in the request

● The HTTP method used to make the request
● The arguments sent by the client as part of the request
The methods you call when implementing your servlet methods depends on the kind of HTTP
request the servlet will receive. The following table summarizes the relationship between the
possible kinds of HTTP requests and the corresponding methods you should use when
implementing your servlet methods.
Possible Kinds of Client HTTP Requests Corresponding Client Data Access Methods and
Techniques to Use in Your Servlet Code
Any HTTP request Use the getParameter method to get the value of a named
parameter. Use the getParameterNames method to get
the parameter names. Alternatively, you can manually
parse the request. You should use either the
getParameter method or one of the methods that allow
you to parse the data yourself. You can not use them
together in a simple request. To retrieve cookies from the
request, you can use the getCookies method.
HTTP GET request Use the getQueryString method to return a String to be
parsed.
HTTP POST, PUT, and DELETE requests In general, use the BufferedReader returned by the
getReader method for text data. For binary data, use the
ServletInputStream returned by the getInputStream
method.
Related topics

4-18
About HTTP Servlets
4-19
The second HTTP argument in a basic servlet method is an HttpServletResponse object. This object
encapsulates the information from the servlet to be returned to the client. This object supports the
following ways of returning data to the client:
● A writer for text data (via the getWriter method)

● An output stream for binary data (via the getOutputStream method)
You can also send a cookie in the response using the addCookie method.
Changing the HTTP Response Type
By default, the HTTP Servlet Wizard creates a servlet that dynamically generates HTML content (MIME
type: text/html). You can change to another MIME type by selecting the desired type from the Generate
Content Type dropdown in the HTTP Servlet Wizard. The wizard adds the setContentType method in the
servlet's Java file with the selected type to set. For example, if you choose the XML content type, the
wizard generates:
public class HelloWorld extends HttpServlet

{
private static final String CONTENT_TYPE = "DOC_TYPE";
public void init(ServletConfig config) throws ServletException
{
super.init(config);
}
public void doGet(HttpServletRequest request, HttpServletResponse response) throws
ServletException, IOException
{
try
{
}
catch(Exception e)
{
e.printStackTrace();
}
response.setContentType(CONTENT_TYPE);
...
Related topics
4-20
About HTTP Servlets
4-21
Configuring Servlet Runtime Properties for the Web
Deployment Descriptor
JDeveloper adds the web.xml file to your project folder the first time you create a servlet.
JDeveloper's embedded web server uses the generated web.xml file to run the servlet. You can
edit the web.xml file in JDeveloper to customize the deployment descriptor:
Editing Deployment Descriptors (XML)
Related topics

About J2EE Applications and How They Are Packaged and Deployed
See also
Specification:
4-22
Testing and debugging an HTTP servlet in JDeveloper is similar to testing and debugging any
other type of application:
● Running a servlet
● Debugging a servlet
● Remote debugging in OC4J
Related topics
About Java Servlets

About HTTP Servlets
4-23
Deploying Java Servlets
JDeveloper supports deploying your Servlet applications on any J2EE application server
through the creation of a Web Module Archive (WAR). There is additional support for
deployment to Oracle9iAS Containers for J2EE (OC4J) as described in this topic:
● Creating and Deploying a J2EE Web Module Deployment Archive (WAR)
Related topics

About the Deployment Process
About JSP Applications and JDeveloper Tools
4-24
Working with JSP Pages
JSP pages:
● Create a simple JSP page
● Generate a web application from an existing WAR file
● Insert JSP tags from the Component Palette
● Insert HTML and JSP tags using Code Insight
● Edit JSP pages using the code editor
● Configure runtime properties for the Web Deployment Descriptor
● Run JSP pages using JDeveloper's embedded OC4J JSP container
● Debug JSP pages with breakpoints and watches
● Remote debug JSP pages
● Deploy JSP pages
Related topics
Working with Data Bound BC4J JSP Pages
About JSP Pages and JDeveloper Tools

About JavaServer Pages
See also
4-25
For more information on JavaServer Pages technology, go to this java.sun.com web page:
http://java.sun.com/products/jsp/index.html
4-26
JavaServer Pages (JSP) technology is based on Java Servlets and, like Java Servlets, JSP is a
server-side technology. A key difference between JSP pages and servlets is that JSP pages
keep static page presentation and dynamic content generation separate. JSP web page
designers use:
● HTML tags to design and format the dynamically generated web page
● JSP standard tags or Java-based scriptlets to call other components that generate the
dynamic content on the page
● JSP tags from custom tag libraries that generate the dynamic content on the page
A JSP page has the extension .jsp. This extension notifies the web server that the page should
be processed by a JSP container. The JSP container interprets the JSP tags and scriptlets,
generates the content required, and sends the results back to the client as an HTML or XML
page.
Since JavaServer Pages technology cleanly separate dynamic application logic from static
HTML content, page designers who have limited or no Java programming expertise can modify
the appearance of the JSP page without affecting the generation of its content.
Related topics
About JSP Pages and Business Components
See also
4-27
JDeveloper provides a complete environment for the creation, editing, and debugging of JSP
pages. These features in JDeveloper simplify the development of JSP pages:
● Embedded Oracle9iAS Containers for J2EE (OC4J) that lets you run JSP pages in
JDeveloper
● Integrated debugger with JSP source-level debugging that lets you set breakpoints in
JSP pages and stop inside the JSP page rather than the compiled source code
● Remote debugging for testing deployed JSP pages on web servers
● Page creation wizards that help you to integrate JSP pages with a Business Components
application to produce data-bound JSP applications and JSP pages
● Simple to use BC4J Data Tags custom tag library that provides complete access to
Business Components
● Background JSP compiler that operates when you run JSP pages
Related topics
See also
4-28
Creating a Simple JSP Page
1. In the Navigator, select the project in which you want to create the new JSP.
2. Choose File | New to open the New Gallery dialog.
3. Select the Web Object folder.
4. Double-click the JSP icon in the Items list to display the New JSP dialog.
5. In the Name of JSP field, enter the name of the JSP file you want to generate. Leave the
Directory field unchanged to save your work in the directory JDeveloper expects to find
web application files.
A simple JSP is generated and appears in your active project. The deployment descriptor
file web.xml is also added to your project. The deployment descriptor file is used by
JDeveloper's embedded web server when you run the JSP.
You can customize the JSP by inserting:
● HTML tags that you use to create your own page design
● Standard JSP tags and scriplet code defined in the Sun Microsystems "JSP Developer's
Guide"
● JSP tags from registered tag libraries that appear on JDeveloper's Component Palette
● JDeveloper's BC4J Data Tags that use you to access Business Components for Java
(BC4J) datasources
● Custom tag libraries that you create
● JDeveloper's predefined HTML and data web beans that you insert into your JSP page
using BC4J Data Tags
4-29
● Custom web beans that you create
Related topics
Inserting JSP Tags from the Component Palette

Inserting HTML and JSP Tags Using Code Insight
Editing JSP Pages Using the Code Editor
Running a JSP
Debugging a JSP
Remote Debugging a JSP

4-30
Generating a Web Application from an Existing
WAR File
1. Choose File | New to display the New Gallery dialog window.
2. Select the Projects folder.
3. Double-click the Project from Existing WAR icon in the Items list. The New Project from
WAR File Wizard appears.
4. Follow the steps of the New Project from WAR File Wizard.
For detailed help in using the wizard, press F1 or click Help from within the wizard.
4-31
Inserting JSP Tags Using the Component Palette
You edit JSP pages using the JDeveloper code editor. While you edit JSP files, you can use
the Component Palette to insert:
● JSP tags and component tags from the BC4J Data Tags custom tag library
● JSP tags from the OC4J JSP container custom tag libraries
● JSP tags from other tag libraries that you have registered in JDeveloper
As an alternative, you can insert JSP tags for registered tag libraries using the Code Insight
popup list in the code editor. If you use the Component Palette, JDeveloper will display an
attribute dialog that you must complete to insert the tag. Whereas, when you use Code Insight
to insert a tag, you can view the attributes from a popup list on that tag as you type.
To insert tags from the Component Palette:
1. In the Navigator, right-click a .jsp file and choose Code Editor.

2. Position your cursor inside the file where you want the tag to appear.
3. Choose the desired tag library page from the Component Palette dropdown list.
Note: In order to view the JSP-specific pages of the Component Palette dropdown list,
the Code Editor must currently display a JSP file. Once you open the JSP file, the palette
will display only the pages that you can use with JSP files.
4. Click the tag to insert it into the file.

5. If the tag has attributes, you will be required to supply attribute values for the tag in the
attribute editor JDeveloper displays. For information about the attributes, click the Help
button in the tag attribute editor.
Note: If you prefer not to work with the attribute editors, use Code Insight to insert the
tag instead.
6. If the tag you selected has no attributes, JDeveloper will insert the tag directly into the
.jsp file. In order to display the help topic for a tag without attributes, right-click the tag on
the Component Palette and choose Help (available for all tags on the Component
Palette). It is also possible to display help for any tag by searching for the tag name in
the main help.
4-32
Related topics

Registering a Custom Tag Library
Running a JSP
Debugging a JSP
4-33
When you edit HTML and JSP files, you can use Code Insight (referred to in this document as
Tag Insight) when you want to insert:
● HTML tags and their attributes

● JSP tags and their attributes
Tag Insight displays a popup list based on what appears on the current line of the code editor.
Tag Insight is the only way to choose HTML tags to insert into the JSP page; whereas, you can
choose JSP tags from either the Tag Insight popup list or the Component Palette in
JDeveloper.
To enable/disable Code Insight:
1. Choose Tools | Preferences | Editor | Code Insight to view the tag and parameter popup
option.
2. To disable Code Insight for tags, unselect Enable auto-popup for completion insight.
3. To disable Code Insight for tag attributes, unselect Enable auto popup for parameter
insight.
To display a list of HTML tags in the code editor:
1. In the Navigator, right-click a .html or .jsp file and choose Code Editor.
2. While you are typing, you can invoke Tag Insight for HTML tags by pausing after typing
the < (opening bracket).
3. Tag Insight opens a list with valid HTML tags and attributes, based on the tag library
prefix you typed.
To display a list of JSP tags from a particular tag library in the code editor:
1. In the Navigator, right-click a .jsp file and choose Code Editor.

2. While you are typing, you can invoke Tag Insight for JSP tags by pausing after typing the
< (opening bracket) together with the prefix of the desired tag library (for example, jbo)
followed by a colon (:).
3. Tag Insight opens a list with valid tags, based on the tag library prefix you typed.
4-34
To display a list of the current tag's attributes in the code editor:
1. In the Navigator, right-click a file and choose Code Editor.

2. Either type the tag name or use Tag Insight to insert the tag name, then type a space
after the tag name.
Note: There must be no space between the prefix and the tag name. For example,
<jbo:ApplicationModule is valid, but <jbo: ApplicationModule is not.
3. Tag Insight opens a list with valid attributes, based on the tag name on the line. The
attributes displayed may be for an HTML tag or a JSP tag.
These features are also available while you are using the code editor with JSP or HTML files:
● As an alternative to pausing after typing a tag or attribute name in the code editor, press
Ctrl plus space (if you are using the default keymapping) to open a list of all tags or
attributes.
● You can display the help file for a tag by typing the tag name (or use Tag Insight to insert
the tag name), then type a space after the tag name, then press the F1 key to invoke the
help. You must have typed a space after the tag name before you press the F1 key to
display the help file.
● If Code Insight is enabled in the Code Insight Preferences panel (choose Tools |
Preferences | Editor | Code Insight), you can adjust the amount of time you must pause
before the auto-popup appears in the code editor. This is controlled by the same panel
used to enable Code Insight.
● If End tag completion is checked in the HTML and JSP Preferences panel (choose
Tools | Preferences | Editor | HTML and JSP), the end tag will be automatically inserted.
Related topics

Running a JSP
Debugging a JSP
4-35
4-36
You edit JSP pages using the JDeveloper code editor. The editor supports:
● Syntax highlighting of tag names, attribute names, and attribute values

● Tag (Code) Insight when you want to insert HTML tags or JSP tags from a popup list you
display
● Java Insight for JSP scriplet expressions
● Tag completion when you want the code editor to insert end tags to close a tag you
insert
● Structure Window view of the page
To customize tag syntax highlighting:
1. Choose Tools | Preferences | Editor | Syntax Colors to view the current syntax color
settings.
2. To change highlighting for tags, select Default element name from the list of Available
styles and set the font style and foreground color.
3. To change highlighting for tag attributes, select Default attribute name from the list of
Available styles and set the font style and foreground color.
4. To change highlighting for tag attribute values, select Default attribute value from the list
of Available styles and set the font style and foreground color.
To customize the Code Insight delay period for the completion of tags and attributes:
1. Choose Tools | Preferences | Editor | Code Insight to view the current Code Insight
settings.
2. To change the delay for tags, drag the thumb for auto-completion of the tag completion
popup list to specify the desired period.
3. To change the delay for tag attributes, drag the thumb for auto-completion of the
parameter popup list to specify the desired period.
To enable/disable end tag completion:
1. Choose Tools | Preferences | Editor | HTML and JSP to view the end tag completion
option.
4-37
2. Select or unselect the End tag completion as desired.
To view the structure of the JSP or HTML file in the Structure window:
1. If the Structure window is not visible below the Navigator, choose View | Structure
Window to open the Structure window.
2. In the Navigator, right-click a JSP or HTML file and choose Code Editor.
3. As you insert a tag into the file, the Structure window adds the tag to the appropriate
node in the page structure.
The Structure window will also report malformed HTML and JSP syntax errors.
Related topics

Running a JSP
Debugging a JSP
4-38
Configuring JSP Runtime Properties in the Web
Deployment Descriptor
JDeveloper adds the web.xml file to your project folder the first time you create a JSP file.
JDeveloper's embedded web server uses the generated web.xml file to run the JSP. You can
edit the web.xml file in JDeveloper to customize the deployment descriptor:
Related topics
See also
Specification:
4-39
Testing and Debugging JSP Pages
Testing and debugging JSP pages in JDeveloper is similar to testing and debugging any other
type of application:
● Running a JSP
● Debugging a JSP
● Remote debugging in OC4J
Related topics

4-40
Deploying JSP Pages
JDeveloper supports deploying Web applications on any J2EE application server through the
creation of a Web Module Archive (WAR). There is additional support for deployment to
Oracle9iAS Containers for J2EE (OC4J) as described in this topic:
● Creating and Deploying a J2EE Web Module Deployment Archive (WAR)
Related topics

About JSP Applications and JDeveloper Tool
4-41
Working with JSP Tag Libraries in JDeveloper
JDeveloper provides several tools to simplify the task of creating and registering JSP tag
libraries:
● Create custom tag libraries and JSP tags.

● Register custom tag libraries in order to invoke tag insight for the tags while you are
editing JSP pages in the Code Editor.
● Add customized pages to the Component Palette to display the available tags on the
Component Palette while you are editing JSP pages.
Related topics
About Custom Tag Libraries in JDeveloper

About JSP Tags
4-42
About JSP Tags
A JavaServerPages (JSP) Tag is a Java class that encapsulates functionality, such as: conditional logic,
database access, or scriplet code that you want to reuse across multiple pages. The use of tags in JSP
pages makes it easy to interface with business logic in a transparent way. It also keeps the JSP pages
manageable and easy to read. Instead of writing a lot of inline Java code, a simple call to a tag can be
made. Tag libraries makes authoring JSP pages easier -- both for the Web page author and for tools that
expose the functionality encapsulated by the library to the author.
JSP 1.1 supports custom tag libraries. This means that you can write your own sets of tags and call
them in your JSP page's. In order to use these custom tag libraries, the corresponding Java classes and
Tag Library Descriptor ( or .tld ) need to be placed in a location where the JSP container can find and
execute them. The Tag Library Descriptor file defines tag names, tag attributes and class file locations.
Furthermore, a taglib directive needs to be issued in the JSP before calls to the custom tag(s) are made.
Here is an example of the use of a custom JSP tag from JDeveloper's own BC4J Data Tags custom tag
library:
<%@ taglib uri="/webapp/DataTags.tld" prefix="jbo" %>

<HTML>
<BODY>
<jbo:ApplicationModule id="MypackageModule"
configname="mypackage.MypackageModule.MypackageModuleLocal" releasemode="Stateful" />
</BODY>
</HTML>
You declare that a JSP page will use tags defined in a tag library by including a taglib directive in the page
before any custom tag is used. The uri attribute refers to a URI that uniquely identifies the tag library. This
URI can be relative or absolute. If it is relative, it must be mapped to an absolute location in the taglib
element of a web application deployment descriptor, the configuration (web.xml) file associated with web
applications developed according to the Java Servlet and JavaServer Pages specifications. The prefix
attribute defines the prefix that distinguishes tags provided by a given tag library from those provided by
other tag libraries.
When the user requests a JSP page you created using the custom tags, the web server will attempt to
expand the tags with data using HyperText Transfer Protocol (HTTP) methods that operate on Request
and Response objects it creates at runtime. This means that in order for your JSP pages to be able to
generate dynamic content, they must work in the expected request-response mode. You may want to
read more on these subjects for background.
If you are not already familiar with HTML coding or the HTTP Request and Response objects, refer to
these links at the World Wide Web Consortium's (W3C) site for detailed information:
● For the HTML specification
4-43
● For information about defining HTML forms
● For information about HTTP method
For example, in the HTML body, the custom tag "jbo:ApplicationModule" is called when the JSP is
requested from the server. The JSP container will recognize tags with the prefix jbo are to be handled
according to the specified .tld file. The Java class that corresponds with the tag that is being called will, in
this case, generate an instance of a Business Components for Java application module. If the tag renders
some data, the generated HTML will in turn be added to the existing HTML and the combined result will
be seen by the end user.
What is important is that the internal workings of the Java class that contains the custom tag's
functionality, is not coded inside the JSP page, instead there are just some simple tags that any web
developer can easily use.
Related topics

Creating a Custom JSP Tag Library
Adding Pages and JSP Tags to the Component Palette

See also
4-44
JSP 1.1 supports custom tag libraries, which enable the development of reusable modules
called custom actions. Form processing, accessing databases or email, and flow control are
examples of tasks that can be performed by custom actions. To invoke a custom action, you
use a custom tag inside a JSP page. A collection of custom tags forms a custom tag library. A
tag library descriptor file (TLD) is an XML document that describes your tag library and each
tag in it.
JDeveloper provides several tools to simplify the task of creating new JSP custom tag libraries
as well as importing and registering custom tag libraries from another source. Custom tag
libraries are supported by JDeveloper's code (tag) insight and can be added to the Component
Palette. When working with custom tag libraries in JDeveloper, you can:
● Create custom tag libraries and JSP tags.

● Register custom tag libraries in order to invoke tag insight for the tags while you are
editing JSP pages in the Code Editor.
● Add customized pages to the Component Palette to display the available tags on the
Component Palette while you are editing JSP pages.
After you create a custom tag library, you and other developers with whom you work can reuse
it in other applications you are developing. JDeveloper will include a tag library as part of a
deployment descriptor when you use it in an application.
For information about deploying a tag library, see Creating and Deploying a Tag Library for JSP
1.1.
For complete information about JSP tag libraries, see the JavaServer Pages Tag Libraries
documentation from Sun Microsystems at http://java.sun.com.
Related topics
About JSP Tags
4-45
JDeveloper provides several tools to help you create a custom JSP tag library and add JSP
tags. To create a custom tag library, you will create the tag library descriptor file and then
create simple tags or component tags. A tag library descriptor file (TLD) is an XML document
that describes your tag library and each tag in it. It is used by a JSP container to validate the
tags. Once you create tags, you can add attributes and scripting variables to them.
To create a custom JSP tag library:
1. In the Navigator, select the project you want to use for your JSP tag library.
2. Choose File | New to open the New dialog.
3. Select the Web Objects folder in the Categories pane, then select Tag Library from the
Items list and click OK.
The JavaServer Page Tag Library dialog opens. For detailed help about the fields in this
dialog, press F1 or click Help from within the dialog.
4. After completing the required information for creating a new tag library, click OK.
The new JSP tag library descriptor (TLD) file is added to the project. To later modify the
information you have entered, you can right-click the TLD file and choose Customize.
The next step is to add tags.
To add a tag to the TLD file:
1. In the Navigator, select the new TLD file you just created.
2. Right-click the file and choose Add Tag or Add Component Tag, depending on the kind
of tag you want to create.
The New JSP Tag dialog opens if you choose Add Tag. The New Web Tag dialog opens
if you choose Add Component Tag. For detailed help about the fields in this dialog, press
F1 or click Help from within the dialog.
3. After completing the required information for creating a new tag, click OK.
The new Tag.java or WebTag.java file is added to the TLD file.
4-46
You now have a new JSP tag library with one JSP tag. You can add as many additional tags as
you like using the Add Tag or Add Component Tag command. You can edit the new tag library
descriptor file and tag in the Code Editor. You can also add attributes and scripting variables to
the tags you've created. Attributes customize the behavior of a tag. Scripting variables you
define in a tag can be used in scripts within a page.
To add an attribute to a tag:
1. In the Navigator, select the Tag.java or WebTag.java file.

2. Right-click the tag and choose Add Attribute.
The JSP Tag Attribute wizard opens. For detailed help about the fields in this dialog,
press F1 or click Help from within the dialog.
3. After completing the required information for adding a tag attribute, click OK.
The new attr1.java file that defines the attributes is created and opened in the Code
Editor.
You can add additional attributes with the Add Attribute command or add a scripting variable to
the tag.
To add a scripting variable to a tag:
1. In the Navigator, select the Tag.java or WebTag.java file.

2. Right-click the tag and choose Add Scripting Variable.
The Add New Tag Scripting Variable opens. For detailed help about the fields in this
3. After completing the required information for adding a scripting variable, click OK.
The new variable.java file that defines the attributes is created and opened in the Code
Editor.
You can continue adding variables with the Add Scripting Variable command. To complete
your tag library, repeat the steps to add additional tags with attributes and scripting variables to
the TLD file.
4-47
After you finish creating the tag library, you can add a new page to the Component Palette to
display your tags.
documentation and tutorial from Sun Microsystems at http://java.sun.com.
Related topics

Registering a Custom Tag Library in JDeveloper
Creating and Deploying a Tag Library for JSP 1.1
4-48
You can register a custom tag library in JDeveloper in order to use the tags in your JSP pages.
You can register both custom JSP tag libraries you create and libraries you obtain from an
outside source. Once you register the tag library, tag insight will be available while you are
editing JSP pages in the Code Editor. However, the tags will not be added to the Component
Palette until you add them in the Add Component dialog.
Tip: Follow the steps in Adding Pages and JSP Tags to the Component Palette to register the library
and add the tags to the Component Palette in one procedure.
To register a JSP custom tag library:
1. Choose Tools | Configure Palette to open the Configure Component Palette dialog.
2. Select JSP as the Page Type.
3. Click Add Component to open the Add Component dialog.
4. Click Add Library to open the Add JSP Tag Library dialog.
Use this dialog to specify the location of the JAR file that contains the custom tag library
descriptor (TLD) file that you want to register. For detailed help about the fields in this
5. After completing the required information for adding a new tag library, click OK.
The new JSP tag library descriptor file is added to the JSP Libraries tree.
6. Select the tag library name in the tree and click OK to close the Add Component dialog,
then click No when you see the Install tags? prompt.
7. Click OK to close the Configure Component Palette dialog.
1.1.
4-49
Related topics

4-50
Adding Pages and JSP Tags to the Component
Palette
You can add pages to the Component Palette in JDeveloper to include the tags from a custom
JSP tag library you created or one you have imported. You must create a new page for each
tag library you want to include on the Component Palette; if the tag library is large, you may
want to include several new pages on which to organize the additional tags.
To add pages and JSP tags to the component palette:
1. Choose Tools | Configure Palette to open the Configure Component Palette dialog.
2. Click New Page to open the New Palette Page dialog.
3. Enter a Page Name and select JSP as the Page Type, then click OK.
Your new page name is added to the bottom of the list of Pages in the Configure
Component Palette dialog.
4. Select the new page name in the Pages panel and click Add Component to open the
Add Component dialog.
5. Click Add Library to open the Add JSP Tag Library dialog.
Use this dialog to specify the location of the JAR file that contains the custom tag library
descriptor (TLD) file that you want to register and add to the Component Palette. For
detailed help about the fields in this dialog, press F1 or click Help from within the dialog.
6. After completing the required information for adding a new tag library, click OK.
The new JSP tag library descriptor file is added to the JSP Libraries tree.
7. Under Select a tag to add, in the JSP libraries node select the tag library that you want
to add or expand the tag library node to display the tags included in it.
You can add all the tags in the library to the Component Palette or select an individual
tag to add.
8. To add all the tags, select the tag library name in the tree and click OK. To add an
individual tag, select a single tag name in the tree and click OK.
4-51
You can add also click Use Default or Select Image to select the Icon that will display for
an individual tag on the Component Palette, before you click OK.
9. Click Yes when you see the Install tags? prompt.

10. After adding tags, click OK to close the Configure Component Palette dialog.
The name of the library you added displays in the drop down list in the Component Palette. All
the tags you added display with < brackets > as the icon, if you accepted the default icon. If you
do not see any tag names on the palette, right-click in the palette and choose List View.
1.1.
Related topics

4-52
Working with Data Bound BC4J JSP Pages
These JSP topics describe techniques for developing server-side Java applications that can
dynamically generate data bound HTML content for presentation on a web page. For details
about data bound JSP applications, see About JSP Pages and Business Components.
● Defining runtime properties for your business components

● Customizing the UI using control hints for the business component client
● Defining a formatter and format masks for the business component client
● Ways to generate data bound BC4J JSP pages
● Working with BC4J data tags to build data bound JSP pages
● Working with BC4J component tags to build data bound JSP pages
● Working with web beans to to access business components or to create your own web
beans
Related topics

About JSP Tags
About BC4J Data Tags
About BC4J Component Tags
About Control Hints for Business Component Clients
About Web Beans
Reference: BC4J Data Tags

Reference: Web Bean Classes
4-53
JDeveloper provides facilities to develop a special kind of web application based on a
combination of JSP technology and Oracle's Business Components for Java (BC4J)
framework. We call this kind of web application a Business Components JSP application—or
BC4J JSP application for short.
A BC4J JSP application consists of a set of JSP pages that can use:
● JDevelopers's BC4J data tags from the provided-BC4J Data Tags custom tag library to
embed dynamic content in HTML formatted pages
● JDeveloper's BC4J component tags from the provided-BC4J Data Tags custom tag
library to generate dynamic content together with predefined HTML formatting
A BC4J JSP application uses the Business Components for Java (BC4J) framework to browse
and update a database. Specifically, a BC4J JSP application communicates with a business
components application module and its associated view objects. When you generate a BC4J
JSP application using one of the JDeveloper Data Page wizards or the Business Components
JSP Application Wizard, you choose which of several JSP page templates to use to generate
for the view objects. Each of the JSP page templates consists of one or more JSP pages built
using JDeveloper-provided JSP tags from the BC4J Data Tags custom tag library.
The tag-based approach to building JSP web applications with Business Components does not
require extensive Java programming and is very much like coding an HTML page. When you
want to create your own BC4J JSP pages rather than generated them from the wizards, you
can
● Add BC4J data tags from the Component Palette when you need maximum
customization of JSP pages at a low level
● Add BC4J component tags from the Component Palette when you want to work with
reusable components that provide predefined HTML formatting
About the JDeveloper JSP Wizards
You use JDeveloper's JSP-related wizards to generate JSP pages. You can create pages
individually or as a collection of pages:
● New JSP dialog generates a simple "Hello World" JSP page

4-54
● BC4J Data Page Wizards which generate data bound JSP pages based on a page
template you select and a single Business Components view object
● Business Components JSP Application Wizard generates a JSP application based on a

Business Components application module and its contained view objects
Additionally, you can insert these individual JSP elements into your JSP page:
● JSP tags from any tag library that has been registered in JDeveloper
● WebBean or DataWebBean data tag (from the provided BC4J Data Tags library) when
you want to work with web bean classes in your JSP page
Related topics
About JavaServer Pages and JDeveloper

About BC4J JSP Page Templates
About Control Hints for Business Components Clients
About BC4J Component Data Tags
About BC4J Form Input Data Tags
About BC4J Multimedia Data Tags
About Rendering Data with BC4J Data Tags
About Creating Rows Using BC4J Data Tags
About Editing Rows Using BC4J Data Tags
About JSP Pages and BC4J Application Module Pooling
About BC4J Configuration Properties for a JSP Project
About Web Beans

Ways to Generate Data Bound BC4J JSP Pages
4-55
When you generate a BC4J JSP application using one of the BC4J Data Page Wizards or the
Business Components JSP Application Wizard, you choose which of several JSP page
templates to generate for the view objects, including:
● Browse form
● Browse and edit form
● Query form
Each of these JSP page templates consists of one or more JSP pages built using JDeveloper-
provided JSP tags from the BC4J Data Tags custom tag library. The type of JSP page template
you select determines which data tags will be used. For each type of component tag that
appears in the generated JSP pages, there will be an associated JSP file that provides the
component tag's specific action.
Note: Do not delete the component tag JSP files (DataXxxComponent.jsp) associated with the
component tags from your JSP project. The component tag JSP files appear in the deployment
profile generated with the JSP project and are dynamically included into the wizard-generated BC4J
JSP application pages.
The JSP page templates you can select when using the various BC4J JSP wizards include:
Browse Form
Use this form to browse records from a data source represented by a view object. A
Browse Form consists of a single JSP page named viewobject_Browse.jsp where
viewobject is the name of the view object for which the Browse Form was generated.
Browse and Edit Form
Use this form to browse and edit records from a data source represented by a view
object. A Browse and Edit Form consists of two JSP pages named viewobject_Edit.jsp
and viewobject_BrowseEdit.jsp where viewobject is the name of the view object for
which the forms were generated.
Query Form
Use this form to define a query to a data source represented by a view object. A query
form consists of a single JSP named viewobject_QueryView.jsp where viewobject is the
name of the view object for which the query form was generated. The
viewobject_QueryView.jsp renders a standard HTML form with text input fields, which
4-56
correlate with the view object's attributes. The Search action is also handled by
viewobject_QueryView.jsp, where viewobject_QueryView.jsp performs the following
functions:
❍ Processes the incoming HTML parameters

❍ Sets the Where clause based on the parameter values
❍ Issues a query via the RowsetIterate tag and renders all the rows which
correspond to the Where clause
Note: The processing code in viewobject_QueryView.jsp serves as a basic example of how

to process HTML form parameters and set Where clauses using the BC4J data tags.
Advanced parameter parsing will require additional coding enhancements to the generated
viewobject_QueryView.jsp page.
The user executes a query by:
1. Entering values in the view criteria field for the attributes they want to match. The
entered value must include the appropriate comparison symbol (>, <, =). All values
in the same view criteria are AND'ed together.
2. Optionally, click Add Criteria to specify a new view criteria that is automatically
OR'ed to any preceding view criteria.
3. Click Search in the query form to display the results.
To create a JSP page with one of the BC4J JSP wizards, you must:
● Choose a configuration definition that describes the Business Components application

module you want your JSP page to use.
● Select the view object you want your JSP page to use.
Related topics

4-57
4-58
JDeveloper provides set of JSP 1.1 compliant custom tags known as Business Components for
Java (BC4J) Data Tags. The BC4J Data Tags custom tag library allows for simplified
interaction with business components based on the Business Components for Java framework.
The tag-based approach to building JSP web applications with business components does not
require extensive Java programming and is very much like coding an HTML page. The tags
provide complete access to business components and allow viewing, editing, navigating, and
full DML control.
For a complete list of the BC4J Data Tags, view the tag summary table available in the Help
system. The tag summary table provides links to reference information for each BC4J data tag:
● Reference: BC4J Data Tags Library
In addition to the tag summary table in the Help system, the JDeveloper IDE lets you display
reference information for individual tags in a variety of ways. You can view the help file for a
specific tag:
● On the Component Palette, by right-clicking the desired tag and choosing Help.
● In the Attribute Editor for the tag whose attributes you are defining, by clicking the Help
button.
● In the Code Editor, by typing the tag name (for example, <jbo:ApplicationModule )
followed by a space character, and then pressing the F1 key.
● In the Help System, by selecting the Search tab and typing the tag name without the tag
library's prefix (in this case "jbo") in the search field (for example, "ApplicationModule").
Currently, these functional categories of BC4J Data Tags have usage documentation in the
Help system:
● About BC4J component tags

● About BC4J form input tags
● About BC4J multimedia tags
These additional topics describe operations you can perform on business components using
the BC4J Data Tags:
4-59
● About creating rows in the business components cache
● About editing rows in the business components cache
● About rendering data from the business components cache
Related topics
About JSP Tags


Working with BC4J Data Tags
Working with BC4J Component Tags
This is the reference for the BC4J Data Tags custom tag library:
Reference: BC4J Data Tags Library
4-60
Component tags belong to the BC4J Data Tags custom tag library. The components tags
function much like the other BC4J data tags in that they operate on a Business Components
datasource to access and manipulate data from the database. The component tags differ in
that they provide prebuilt functionality much like a web bean does. The complete set of prebuilt
components includes:
● DataTable displays a grid of data (rows by attributes) of a view object.

● DataRecord displays the content of one row.
● DataNavigate displays a grid of data (rows by attributes) with user-selectable links to
First, Next, Previous and Last rows.
● DataScroller similar to DataNavigate but instead of changing the currency, it scrolls the
range in view up and down through the set of records. It is used with the DataTable
component.
● DataEdit builds an edit form.
● DataQuery inserts a query form to edit and process view criteria on a bound datasource.
● DataHandler handles business component-specific events.
● DataTransaction renders user selectable links to commit or rollback database
transactions.
Prebuilt component tags are available to insert into your JSP file from the BC4J Component
Tag page of the Component Palette.
When you insert a component tag into your JSP file, JDeveloper adds an extra file in your JSP
project. The added JSP file is responsible for implementing the component tag behavior. When
your page executes, the JSP page associated with the component tag is executed through a
dynamic include. For example, assume you decide to use the BC4J Data Tags to create an
HTML table which displays as a grid the first 10 rows of a datasource. You might try to reuse
this data bound grid in another JSP page by copying and pasting. The component tags provide
several advantages over this type of reuse:
● They encapsulate data tag behavior and can be customized in one single source
● They accept a Business Components datasource as an attribute
● Unlike dynamic includes, component tags perform parameter checking on the
datasource attribute
● You can easily select the component tag from the Component Palette and you can view
4-61
a help file for the tag
Whereas, if you were to create an include for a single JSP page and call it with dynamic binding
information, none of the above benefits would be available. Additionally, when you use
component tags that dynamically include the associated JSP page, the origin URL of the JSP
that contains the component tag is passed to the associated JSP. This allows the component
tags to deal appropriately with the calling JSP upon execution.
About the HtmlServices.getParameters Method
Each component tag will pass request parameters to its corresponding component
implementation .jsp file in order to execute the tag's behavior. However, due to a limitation with
the request.getParameters method, a static method from the Oracle BC4J HtmlServices class
is provided to retrieve submitted request parameter values of any type. Specifically, the
HtmlServices class permits the component implementation .jsp files to retrieve HTTP
parameters submitted in a multi-part encoded HTML form.
You can also use the HttpServices.getParameters method in your own JSP pages when you
need to work with HTML form input that require multi-part encoding, such as file input. See any
of the DataXxxComponent.jsp files for an example.
Related topics
About BC4J JSP Tags
Adding Component Tags to a BC4J JSP Page

Customizing BC4J Component Tags
This is the reference for the BC4J Component Tags:
4-62
The Input data tags fall into these three groups:
● Basic text input useful to edit attributes that require the user to type a value.
● Selected input that display multiple values and allow the user to select from a list queried from the database.
● Specialized input useful when you want to provide a date input control or a password control.
In order to bind the rendered controls to a particular attribute of the BC4J datasource, each Input data tag has
these tag attributes in common:
● Datasource identifies the BC4J view object to be updated.

● DataItem identifies the attribute in the datasource to be updated.
Important: The values you specify for the Input data tag datasource and dataitem are case sensitive. To avoid a JSP
runtime exception, match the BC4J view object and attribute names exactly as they appear in the BC4J project.
If you want to create a form which permits users to make multiple selections from the values of a single attribute, your
submit JSP page must include JSP scriptlet code to process multiple HTTP request parameters. This issue is discussed
in the introduction to the Selected Input section below.
UI Control Equivalents
The BC4J Input data tags provided with the JDeveloper BC4J data tag library render various UI controls that
operate on the data of new or existing rows. Input actions provided by the <jbo:InputXxx... /> data tags are
equivalent to these typical UI controls:
Control Type BC4J Data Tag

<jbo:InputText .../>
Basic Text Input
<jbo:InputTextArea .../>
Multi-line Text Input Area
<jbo:InputSelect multiple = no ... />

Single Selection Combobox
<jbo:InputSelect multiple = yes .../>

Multiple Selection Combobox
<jbo:InputSelectLOV .../>
LOV Selection Input
<jbo:InputSelectGroup> multiple = no .../>

Single Selection Radio Button Group
<jbo:InputSelectGroup multiple = yes .../>

Multiple Selection Checkbox Group
4-63
<jbo:InputDate .../>
Date Selection Input
<jbo:InputPassword .../>
Password Input
<jbo:InputHidden .../>
Hidden Input
<jbo:InputRender .../>
InputRender Input
When your JSP renders the <jbo:InputXxx... /> data tags inside an HTML form you create, the source HTML
generated by the control appears as standard HTML form elements. For example, the InputText data tag used to
display row data for a customer name would generate this static HTML input element, which defines a name-value
pair:
<INPUT TYPE="TEXT" NAME="CUSTNAME" VALUE="John" ROWS="1" SIZE="20" />

<INPUT TYPE="HIDDEN" NAME="_CUSTNAME" VALUE="John" />
The difference between updating a row using <jbo:InputXxx... /> data tags and updating a row using static HTML
form elements is that the BC4J data tags allow you to display default values from the datasource. Additionally,
because you bind your Input data tags to a BC4J datasource, if you rely on HTML form elements, you will lose the
benefits of default sizing, formatting, and possible data validation that the BC4J datasource provides.
Basic Text Input
These controls when rendered display the current value of a specific attribute giving the user the ability to edit the
value. When submitted, it assigns the updated value to the named attribute.
● InputText - Renders a standard input control:
Usage example:
<jbo:InputText datasource="custDataSource" dataitem="Name"

/>
This example will generate a standard HTML text input with the value equal to the Name attribute of the
customer (custDataSource) datasource.
● InputTextArea - Renders a multiline input control:
Usage example:
4-64
<jbo:InputTextArea datasource="custDataSource"
dataitem="Comment" rows="10" cols="20" />
This example will generate a multiline HTML text input of up to ten rows and twenty characters wide. The
data is rendered from the Comment attribute of the customer (custDataSource) datasource.
Selected Input
These controls allow for user selection from a list of choices queried from the database. They rely on two different
datasources: one to display the selection list and one to receive the update. Several of the selected input tags
render differently depending on whether you want to allow single selection (multiple="no") or multiple selection lists
(multiple="yes").
Important: If you specify multiple="yes" for any of the selected input tags, then your submit JSP page must include JSP
scriptlet code to process multiple HTTP request parameters. To get the values from your data input JSP form, use the
getParameterValues() method of the ServletRequest interface. Use the built-in request object of your submit JSP page
as follows, where the String passed to getParameterValues() is the value of the control's dataitem attribute:
<% String params[] = request.getParameterValues("MyDataItemValue"); for

( int i=0; i< params.length; i++) out.println(params[i]); %>
The selected input tags share a common set of attributes that define what the user sees, as well as what gets
updated:
These tag attributes identify the datasource and attribute that the control will use to display possible user
selections. The datasource and attribute names are case-sensitive and must match the BC4J names
exactly.
● DisplayDataSource identifies the datasource used to display the values.

● DisplayDataItem identifies the attribute used to display the values.
This tag attribute specifies the data the control passes to your processing page to update the datasource
whose row the user is editing. (In most cases, the user does not see this value.)
● DisplayValueDataItem identifies the attribute (from the same the datasource which displays the value) used
to pass for processing as an HTTP request parameter.
These tag attributes identify a different datasource and attribute to update. The attribute you identify is from
the rows you want the user to edit:
● Datasource identifies the datasource to be updated.

● DataItem identifies the attribute in the datasource to be updated.
The two datasources you specify for the selected input tags must be unique. The following diagram illustrates the
4-65
interaction of the attributes using two distinct datasources.
The update resulting from the user's selection follows this sequence:
1. The insert JSP page renders a dropdown list using the <jbo:InputSelect ...> data tag. The rendered control
displays the employee names using the DisplayDataItem (Name) attribute of the DisplayDataSource.
2. The user selects an employee name from the list.
3. The user clicks Send.
4. The insert JSP page passes an HTTP parameter using the DisplayValueDataItem (EmpNo) as the name-
value pair to the submit JSP page (not shown), which updates the DataItem (EmpNo) in the DataSource.
While the Input data tag specifies the names of two datasources, the source HTML generated by the control
appears as a standard <SELECT> element. The source HTML in this example looks like:
<SELECT NAME="Name" CLASS="vrSelectField" >

<OPTION SELECTED VALUE="Abbey">Abbey
<OPTION VALUE="Rose">Rose
<OPTION VALUE="Jones">Jones
</SELECT>
The named datasources merely provide the <SELECT> element with data that the form passes as HTTP
parameter name-value pairs.
● InputSelect - Renders a simple single-selection dropdown list or a multiple-selection combobox, depending

on whether the attribute multiple is set to "yes" or "no". However, if you specify multiple="yes", then your
submit JSP page must include JSP scriptlet code to process multiple HTTP request parameters; see the
introduction to the Selected Input section for a sample. The two versions of this control render like this:
4-66
Usage example:
<jbo:InputSelect multiple="no|yes"
datasource="custDataSource" dataitem="Transhistory" displaydatasource="transDataSource"
displaydataitem="Tdesc" displayvaluedataitem="Tcode" />
By setting these attributes, we are choosing to update the customer (custDataSource) datasource with data
from a lookup datasource (transDataSource) that contains a list of transaction descriptions. The transaction
descriptions (Tdesc) will be displayed in either the dropdown list or combobox and the customer's
transaction history (Transhistory) will be updated by the transaction identification codes (Tcode).
● InputSelectGroup - Renders either a single-selection radio button group or a set of multiple-selection

checkboxes depending on whether the attribute multiple is set to "yes" or "no". However, if you specify
multiple="yes", then your submit JSP page must include JSP scriptlet code to process multiple HTTP
request parameters; see the introduction to the Selected Input section for a sample. The two versions of the
rendered control looks like this:
Single-selection group usage example:
<jbo:InputSelectGroup
multiple="no" datasource="custDataSource" dataitem="Custstatus"
displaydatasource="statusDataSource"
displaydataitem="Sname" displayvaluedataitem="Scode" />
In this single-selection group example, we are updating the customer (custDataSource) datasource with data
from a lookup datasource (statusDataSource) that contains status codes. The status name (Sname) will be
displayed in a radio button group (because multiple is set to "no") and the customer's status (Custstatus) will
be updated by the status code (Scode).
4-67
Multiple-selection group usage example:
multiple="yes" datasource="custDataSource" dataitem="Custshippref"
displaydatasource="shipserviceDataSource"
displaydataitem="SSname" displayvaluedataitem="SScode" />
In this multiple-selection group example, we are updating the customer (custDataSource) datasource with
data from a lookup datasource (shipserviceDataSource) that contains the names of shipping services. The
shipping services' name (SSname) will be displayed in a set of checkboxes (because multiple is set to "yes")
and the customer's shipping preferences (Custshippref) will be updated by the shipping service's code
(SScode).
InputSelectLOV- Renders an input control with a button that opens an LOV window. The LOV window
allows the user to select a single value. Since this control uses JavaScript to launch the LOV window and
assign the selected value to the input control, the InputSelectLOV data tag requires the HTML form name as
an attribute. Unlike the other selection controls, the LOV window displays a search field that lets the user
limit the selection choices displayed by the LOV list by entering a value that matches the display attributes of
the LOV. The user can type the percent symbol "%" to return the full list to the LOV display. The rendered
control looks like this:
Usage example:
<jbo:InputSelectLOV datasource="custDataSource"
dataitem="Custrepname" displaydatasource="repDataSource" displaydataitem="Mgr"
displayvaluedataitem="Repname" formname="form1" />
This sample allows for the update of the customer (custDataSource) datasource with data from the
representatives (repDataSource) datasource. The customer representatives' manager (Mgr) will be
displayed in the popup LOV and the customer's representative's name (Custrepname) will be updated by the
representative's name (Repname). The form name (form1) refers to the name of the HTML form element
that contains the InputSelectLOV data tag.
Limitation: Currently, this control displays the value from the displayvaluedataitem
(displayvaluedataitem="Repname") attribute in the input control after the selection. In a future release, you
will be able to specify which value to display in the input control.
Specialized Input
These controls have specialized purposes: such as allowing for a date selection or accepting a password input.
● InputDate - Renders an input control with a button that opens a Date Picker popup window. The window
allows the user to select a date from a calendar. Since this control uses JavaScript to launch the Date Picker
window and assign the date selection to the input control, the InputSelectLOV data tag requires the HTML
form name as an attribute. The rendered control looks like this:
4-68
Usage example:
<jbo:InputDate datasource="empDataSource" dataitem="Hiredate" formname="form1"

/>
After the date is selected, the input control will show the selection. The form name (form1) refers to the
name of the HTML form element which contains the InputDate data tag.
● InputPassword - Renders an input control that displays input text as asterisk symbols (*). The rendered
control looks like this:
Usage example:
<jbo:InputPassword datasource="empDataSource"
dataitem="Password" cols="9" />
When entered, the value of password will be obscured.
Related topics

About Creating Rows Using BC4J Data Tag
Updating Rows Using Data Tags

Creating Rows Using Data Tags
4-69
About BC4J Multimedia Data Tags
Oracle9i interMedia Audio, Image, Video, and Document enables Oracle9i database to manage
audio, image, video, and document in an integrated fashion with other enterprise information,
through object types. An instance of these object types consists of attributes, including
metadata and the media data, and methods. Media data is the actual audio, image, video, or
document.
The BC4J Data Tags custom tag library provides a complete set of tags to support media data
retrieval, rendering, and upload of content stored in Oracle9i database as interMedia objects.
This set of data tags, available on the BC4J interMedia page of the Component Palette, work
with a set of Java classes in the BC4J framework that automatically recognize Oracle9i
interMedia object types and help map these object types into correspondent Java classes.
Specifically, BC4J interMedia data tag operations include:
● Display an embedded image in the browser

● Use an embedded player to play video in the browser
● Use an embedded player to play audio in the browser
● Render the content in your own way
● Insert an image to a new row
● Update an image in an existing row
When you use the interMedia data tags with the interMedia ORDIMAGE attribute, the default
interMedia display renderer (oracle.ord.html.OrdBuildURLRenderer) outputs an <IMG> HTML
tag so that the browser displays the image. The default interMedia edit renderer
(oracle.ord.im.OrdUploadFileRenderer) displays an <INPUT TYPE="FILE"> HTML tag for file
upload. For the attributes of other interMedia types, the default interMedia display renderer
outputs an HTML Anchor tag; and the default interMedia edit renderer outputs an <INPUT
TYPE="FILE"> HTML tag for file uploading.
Supported Media Formats
● Image: JPG and GIF

● Audio: AIF, AU, WAV and MP3
● Video: MOV, AVI, MPEG
4-70
Related topics

About Multimedia BC4J Data Tags
Rendering Multimedia Content Using Data Tags
For a complete list of the BC4J interMedia data tags, see:
Reference: BC4J Data Tags.
4-71
About Rendering Data with BC4J Data Tags
There are two types of HTML renderer for the business components datasources:
● Display Renderer displays the value of the attribute in the JSP page
● Edit Renderer displays an edit field in the JSP page to let the user input a value for the attribute
The BC4J data tags make use of these HTML renders when you:
● Create JSP forms using the BC4J input tags

● Display multimedia content using the BC4J interMedia data tags
● Display data in your JSP page from BC4J attributes using the RenderValue data tag
Note: The ShowValue data tag provides an alternative to using the HTML renders to display attribute data.
The ShowValue data tag displays simple text BC4J data; whereas, the RenderValue data tag displays any
kind of data such as dates or object.
Support for Custom HTML Renderers
You can write a custom HTML renderer class to customize the rendering of a specific attribute. The custom
HTML renderer class should extend oracle.jdeveloper.html.HTMLFieldRendererImpl class. After the custom
HTML renderer class is created, the user should bind this renderer class to the attribute that he wants to
render.
Levels of Renderer-Attribute Binding
There are five different types of the renderer-attribute binding:
● BC4J Data Tag level binding

● View object level binding
● Entity object level binding
● HTTP session level binding
Each level of binding takes offers a unique level of precedence and scope:
● BC4J data tag level binding both take the highest precedence. They don't interfere with each other.
● View object level binding takes higher precedence to entity object level binding. The bindings at these
two levels bind HTML renderer classes to BC4J attributes.
● HTTP session level binding takes the lowest precedence. It binds HTML renderer classes to BC4J
domain classes.
4-72
According to your requirements, you can choose to bind the renderer class in any of these levels.
HTTP Session Level Binding
HTTP session level binding takes the lowest precedence. But it has the widest scope. BC4J framework puts
the default bindings for attribute types in this level. The default binding of interMedia renderer classes and
interMedia types is defined in this level. The rule of binding is this:
The name field of the binding is the attribute class name plus the renderer key ("Renderer" or
"EditRenderer"). The value field of the binding is the renderer class name. In the name field of the binding,
use "_" to replace "." in the full class name, then append "_Renderer" for display renderer or "_EditRenderer"
for edit renderer.
For example:
"oracle_ord_im_OrdImageDomain_Renderer"/"oracle.ord.html.OrdBuildURLRenderer"
This is a name/value pair stored in the HTTP session object. This means the display renderer of
oracle.ord.im.OrdImageDomain object is an object of oracle.ord.html.OrdBuildURLRenderer.
Another example:
"oracle_ord_im_OrdImageDomain_EditRenderer"/"oracle.ord.html.OrdUploadFileRenderer"
This means that the edit renderer of oracle.ord.im.OrdImageDomain object is an object of

oracle.ord.html.OrdUploadFileRenderer.
If there is no preceding level binding, when the BC4J framework needs to render an
oracle.ord.im.OrdImageDomain object, the framework uses a oracle.ord.html.OrdBuildURLRenderer for
display renderer and oracle.ord.html.OrdUploadFileRenderer for edit renderer, regardless of the attribute
belonging to VO or EO.
You can set the custom renderer class by modify the name/value pair in the HTTP session object. The
following code snippet sets the display renderer of oracle.ord.im.OrdImageDomain to user.CustomRenderer:
session.putValue("oracle_ord_im_OrdImageDomain_Renderer", "user.CustomRenderer");
Entity Object Level Binding
Entity object level binding takes higher precedence to HTTP session level binding. However, the scope of the
binding becomes smaller. The binding only affects the attribute defined in the entity object.
For example, in the HTTP session level, OrdBuildURLRenderer is bound to OrdImageDomain as the display
renderer. In the entity object level, CustomRenderer is bound to the "photo" attribute of the Emp entity object.
The "photo" attribute is of OrdImageDomain type. When the JSP page displays the "photo" attribute, BC4J
runtime picks CustomRenderer to render the OrdImageDomain object. However, if there is a "picture"
attribute in the Product entity object. BC4J runtime still uses OrdBuildURLRenderer to render the "picture"
4-73
attribute.
To set the entity object level binding, the user needs to follow the procedures:
1. Click on the entity object in the Navigator.
You will notice that the lower portion of the Navigator (the Structure window) shows the list of attributes.
2. Right-click on the attribute and choose Edit.

3. Click the Properties tab.
4. For display renderer, type Renderer in the Name field, type user.CustomRenderer in Value field. For
edit renderer, type EditRenderer in the Name field, type user.CustomRenderer in the Value field. Click
Add.
5. Click Finish. You'll see the entry was added into the entity object xml file.
View Object Level Binding
View object level binding takes higher precedence to entity object level binding. However, the scope of the
binding becomes even smaller. The binding only affects the attribute defined in the view object.
For example, there are two view objects based on Emp entity object: Emp1View and Emp2View. In the view
object level, CustomRenderer1 is bound to "photo" attribute of the Emp1View view object. In the entity object
level, CustomRenderer2 is bound to "photo" attribute of the Emp entity object. "photo" attribute is of
OrdImageDomain type. When the JSP page displays the "photo" attribute of the Emp1View, BC4J runtime
picks CustomRenderer1 to render the OrdImageDomain object. However, if there is a "picture" attribute in the
Emp2View view object. BC4J runtime still uses CustomRenderer2 to render the "picture" attribute.
To set the view object level binding, the user needs to follow the procedures:
1. Click the view object in the Navigator.
You will notice that the lower portion of the Navigator (the Structure window) shows the list of attributes.
2. Right-click on the attribute and choose Edit.

4. For display renderer, type Renderer in the Name field, type user.CustomRenderer in Value field. For
the edit renderer, enter EditRenderer in the Name field, enter user.CustomRenderer in the Value field.
Click Add.
5. Click Finish. You'll see the entry was added into the view object xml file.
BC4J Data Tag Level Binding
Because BC4J data tags use a DataSource object to access data and the HTML renderer object, you can use
4-74
the DataSource to set the HTML renderer. The DataSource object has HTTP REQUEST scope. Data tag
level binding takes higher precedence to view object, entity object, and HTTP session level binding. It affects
all the data tags that use this DataSource object in the current HTTP REQUEST scope.
public interface DataSource {

public void setDisplayFieldRenderer(AttributeDef attrDef, HTMLFieldRenderer rdr);
public void setDisplayFieldRenderer(int nIndex, HTMLFieldRenderer rdr);
public void setEditFieldRenderer(AttributeDef attrDef, HTMLFieldRenderer rdr);
public void setEditFieldRenderer(int nIndex, HTMLFieldRenderer rdr);
}
The following is an example on how to set a custom HTML renderer called user.CustomRenderer to a BC4J
RenderValue data tag. The JSP page is DataTableComponent.jsp. This JSP page is used by the DataTable
tag to display the records. You need to set the HTML renderer object to the DataSource object used by the
RenderValue tag. In this example, the RenderValue tag uses a DataSource object called dsBrowse so that
we set the renderer object to this dsBrowse DataSource object.
<%@ page language="java" import = "oracle.jbo.html.*" %>

<%@ taglib uri="/webapp/BC4J data tags.tld" prefix="jbo" %>
<%
RequestParameters params = HtmlServices.getRequestParameters(pageContext);
String appidParam = params.getParameter("appid");
String voParam = params.getParameter("viewobject");
String editTargetParam = params.getParameter("edittarget");
String originURLParam = params.getParameter("originURL");
%>
<jbo:DataSource id="dsBrowse" appid="<%=appidParam%>" viewobject="<%=voParam%>"/>

<%
oracle.jbo.html.DataSource cacheDS = (oracle.jbo.html.DataSource)
pageContext.findAttribute("dsBrowse");
cacheDS.setDisplayFieldRenderer(1, new user.CustomRenderer());
%>
<jbo:OnEvent name="delete">
<jbo:Row id="delrow" datasource="dsBrowse" rowkeyparam="RowKey"
action="Delete" />
<jbo:Commit appid="<%=appidParam%>"/>
</jbo:OnEvent>
<table class="clsTable" cellspacing="1" cellpadding="3">

<tr class="clsTableRow">
<% if (editTargetParam != null && !editTargetParam.equalsIgnoreCase("null"))
{ %>
<th class="clsTableHeader">&nbsp</th>
<th class="clsTableHeader"><a href="<jbo:UrlEvent targeturlparam='edittarget'
event='Create' datasource='dsBrowse' extraparameters='<%="originURL=" +
params.getParameter("originURL")%>'/>">New</a></th> <%
} %>
<jbo:AttributeIterate id="df" datasource="dsBrowse">
4-75
<th title="<jbo:ShowHint hintname='TOOLTIP'/>" class="clsTableHeader"><jbo:ShowHint
hintname="LABEL">##Column</jbo:ShowHint></th>
</jbo:AttributeIterate>
</tr>
<jbo:RowsetIterate datasource="dsBrowse" changecurrentrow="false" >

<% if (editTargetParam != null && !editTargetParam.equalsIgnoreCase("null"))
{ %>
<td> <a href="<jbo:UrlEvent targeturlparam='originURL' event='Delete'
datasource='dsBrowse' addrowkey='true'/>">Delete</a> </td>
<td> <a href="<jbo:UrlEvent targeturlparam='edittarget' event='Edit'
datasource='dsBrowse' addrowkey='true'
extraparameters='<%="originURL=" +
params.getParameter("originURL")%>'/>">Edit</a> </td> <%
}
%>
<jbo:AttributeIterate id="dfv" datasource="dsBrowse">
<td title="<jbo:ShowHint hintname='TOOLTIP'/>" >
<jbo:RenderValue datasource="dsBrowse">##Cell</jbo:RenderValue>
</td>
</tr>
</jbo:RowsetIterate>
</table>
Related topics

About Multimedia BC4J Data Tags
4-76
About Creating Rows Using BC4J Data Tags
To allow users to insert rows, you typically create two JSP pages that work together:
● A data input JSP page that includes your choice of BC4J Input data tags or static HTML
form elements to render controls that can accept the user's input. This JSP page posts the
data as HTTP parameters to another page for processing.
● A submit JSP page to accept the incoming HTTP parameters and update the datasource.
Note: JDeveloper provides the DataPage Wizard to help you quickly generate Insert and Submit
JSP pages that will allow users to insert rows into a BC4J datasource. The wizard is available in
the New Object gallery: to launch the wizard select File-New, select the Web Objects tab and
double-click the DataPage icon.
Role of the BC4J Input Tags
You can use the BC4J data tags including <jbo:InputXxx... /> in an HTML form element and
<jbo:Row... /> to create JSP forms that let the user:
● Display a new record that is either empty or displays default values
● Edit the record and insert it as a new row into a BC4J datasource
Important: When you create an insert JSP page from scratch, you may mix BC4J Input data tags and
static HTML form elements on the same page. However, the choice of whether to use BC4J Input data
tags or HTML form elements depends on your application needs and your tolerance of a few
restrictions.
The insert JSP page rendered by the web server must contain:
● Form elements that specify name-value pairs, where the name matches the name of the
attribute to be inserted
● The row key object to identify the datasource and row being inserted
The BC4J Input data tags take care of the first requirement when you set the tag's "dataitem" for
the datasource attribute to insert. An HTML hidden input element that you assign a value using the
BC4J ShowValue data tag and the special view object attribute RowKey takes care of the second.
The browser posts this information, which it collects from the JSP form elements, as HTTP input
4-77
parameters to your submit JSP page for processing.
Role of the Input and Submit JSP Pages
The BC4J Input data tags allow you to easily render controls with default values that the
datasource obtains. However, inserting a row using the Input data tags requires that you have
created an empty row in the datasource before the user can send the data to the submit JSP
page. This requirement means your insert JSP page will have created a row whether the user
sends the data or not. Although this is not typically a problem since the datasource will
automatically rollback the empty row after the HTTP session times out, users may see the empty
row in other JSP forms before the timeout occurs.
If you do not want to risk displaying am empty row in your JSP pages, you can choose instead to
use static HTML form elements in your insert JSP page. In this case, you are responsible for
coding default selections as the controls will not be bound to a datasource. Additionally, you will
lose the benefits of default sizing, formatting, and possible data validation that BC4J Input data
tags working with BC4J datasources provide.
Thus, you can either use data bound controls and accept that users may not complete the page
(thereby chancing a visible empty row associated with your datasource), or you can rely on a more
limited set of static HTML form elements and code them to display values.
Keeping these two contrasting approaches in mind, the data input (insert) JSP page contains:
1. BC4J data tags that specify an application module connection and a valid view object
datasource.
2. A BC4J ApplicationModule data tag with the releasemode attribute set to reserved to
preserve the state of the application module until processing is completed. Specifying
reserved mode prevents the datasource from being modified until the user completes the
insert operation.
3. The HTML <form> element with an "action" reference to the submit JSP page.
Tip: It is recommended to use HTTP POST requests to pass row values to your submit JSP
page. This protocol ensures that the browser can pass parameter values of any length. If
you omit method="post" from the <form> tag, the browser will use HTTP GET to pass the
parameter values appended to the URL of the submit JSP page and URLs longer than 255
characters can be problematic. To use POST requests, your <form> tag might look like this:
<form name="DataInput_form" method="post" action="submit.jsp">
If you are not familiar with the HTTP methods defined by the HTTP protocol, refer to the
World Wide Web Consortium (W3C) for details:
4-78
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3.
4. If you decide to create the row before the user submits the data, then your page contains:
❍ A BC4J Row data tag to create the row to be inserted in the datasource and,
optionally, specify a default value.
❍ The desired BC4J Input data tags to render the default value of a specific attribute in
the datasource and give the user the ability to edit the value. Your form uses these to
generate HTTP request parameters that contain the value of the attributes to be
inserted.
❍ A hidden HTML input element to generate a control that contains the row key for the
datasource attributes to be inserted. Your form uses this control to generate another
HTTP request parameter for the row to be inserted.
OR
If you decide to create the row after the user submits the data, then your page will contain
the desired static HTML form elements to render the controls whose default values (if any)
you supply. Your form uses these to generate the HTTP request parameters that contain
the value of the attributes to be inserted.
The submit JSP page contains:
1. BC4J data tags that specify the same application module connection and view object
datasource as the insert JSP page.
2. A BC4J ApplicationModule data tag with the releasemode attribute set to stateless to
release the state of the application module once the data is committed.
3. If you decide to create the row before the user submits the data, then your page contains a
BC4J Row data tag with the Update action. This action allows the Row data tag to match
the datasource row and attributes to update with the HTTP request parameters submitted
by the insert JSP page.
OR
If you decide to create the row after the user submits the data, then your page contains a
BC4J Row data tag with the Create action. This action merely creates a new row in the
datasource. You then need to add a BC4J SetAttribute data tag to match the datasource
row and attributes to update with the HTTP request parameters posted by the insert JSP
page.
4-79
4. BC4J data tags to commit (or rollback) the row to the database.
5. An HREF that returns the user to the insert JSP page for further row inserts.
Using the BC4J Row Tag to Create and Update a Row
If you choose to use BC4J Input data tags to let users insert a new row into the datasource, you
need to create an empty row prior to presenting the insert form. This will allow the new row to
display default attribute values from the datasource. The default values may have been obtained
using sequences on BC4J-specific domains.
The BC4J Row data tag with the action "Create" serves this purpose:
<jbo:Row id="myrow" datasource="custDataSource" action="Create" />
The datasource (custDataSource) of the Row data tag is the same datasource identified by the
Input data tags.
If you want the JSP control to render with a value already selected for the user, you can use the
BC4J SetAttribute data tag to specify the selected value for individual row attributes:
<jbo:Row id="myrow" datasource="custDataSource" action="Create" >

<jbo:SetAttribute dataitem="Id" value="23" /> <jbo:SetAttribute dataitem="Name"
value="Steve" /> </jbo:Row>
The dataitem (Id and Name) of each SetAttribute data tag corresponds to the dataitem of the Input
data tag that you want to render with a selected value.
Note:If the user never clicks the Send button of the insert JSP page, a new row is left in the
datasource. If the user shuts down the browser, the HTTP session will eventually time out and any
pending changes to the datasource cache will be rolled back. If you want users to be able to delete the
row, your application needs to provide a user interface for causing the row to be deleted.
Using the BC4J Input Tags to Supply Input Parameters
In order to generate the HTTP input parameters, the BC4J Input data tags require that you specify
a datasource and dataitem. The datasource identifies the BC4J view object to update and the
dataitem identifies the attribute in the view object which is to receive the inserted value. The input
4-80
parameter combines the value the user enters with the name you specify for the dataitem to form
a name-value pair.
For example, this is how a basic InputText data tag looks when used to update the customer
number (CustNo) attribute of an customer (custDataSource) datasource:
<jbo:InputText datasource="custDataSource" dataitem="CustNo" />
Note that you can use object notation on the dataitem when it is of type Object:
<jbo:InputText datasource="custDataSource" dataitem="Address.City" />
Using the BC4J ShowValue Tag to Obtain a Row Key
After you have bound the BC4J Input data tags to the desired datasource attributes, you must
identify the datasource row currently being inserted by the user. To uniquely identify the row
displayed in your insert JSP page, you use a special attribute of the view object datasource to
obtain the row's row key value. You then post the row key value using an HTML hidden input
element. For example, in order to generate a row key for the current row, your insert form needs to
include an element such as this:
<input name="RowKeyValue" type="hidden" value="<jbo:ShowValue

datasource="custDataSource" dataitem="RowKey"/>" />
This code uses the BC4J ShowValue data tag to render the string representation of the row key
using the value of the special view object attribute RowKey to identify the current row within a
datasource. The name of the input HTTP parameter (RowKeyValue) is your choice. However, the
value of the ShowValue dataitem must be "RowKey" in order to match this attribute name in the
datasource. The datasource (custDataSource) of the ShowValue data tag must match the
datasource named by the Input data tags.
Note: You can also use the ShowValue data tag and the row key to generate an HREF anchor for any
row when you want to perform a BC4J Row data tag "Find" action.
Continuing with the customer example--after the user enters a customer number and sends the
form data, the browser will generate an HTTP request object based on the entered value and the
row key.
4-81
Using the BC4J Row Tag to Update a Row
You use the submit JSP page to retrieve the HTTP parameters and initiate the update action on
the specified row. The Row data tag with the action "Update" serves this purpose:
<jbo:Row id="myrow" datasource="custDataSource" rowkeyparam="RowKeyValue"

action="Update" > </jbo:Row>
Input data tags in your insert or edit JSP page. You identify the specific row to receive the update
by assigning the user-defined name of the insert JSP page's hidden input element (RowKeyValue)
to the Row data tag's rowkeyparam attribute. The Row data tag uses the rowkeyparam tag
attribute to obtain the row key value from the HTTP request object. Using the row key to locate the
target row in the BC4J datasource, the Row data tag implicitly performs a set attribute operation
on the incoming HTTP parameters, which contain the attribute name-value pairs obtained from the
rendered form controls. Because you specified the name of the datasource attribute to update in
the dataitem of the Input data tag, the Row data tag receives the correct attribute to update.
Using the BC4J Row Tag to Create and Update a Row
You use the submit JSP page to retrieve the HTTP parameters and create a row that the JSP
page updates. The Row data tag with the action "Create" serves this purpose:
<jbo:Row id="myrow" datasource="custDataSource" action="Create" >

<jbo:SetAttribute dataitem="*" /> </jbo:Row>
The datasource (custDataSource) of the Row tag is the one receiving the new row. The BC4J
SetAttribute data tag allows your processing page to receive the HTTP name-value pairs. By
specifying the wildcard symbol (*) for the SetAttribute dataitem, the tag will update the new row's
attributes by matching the name it receives with the row attribute names in the datasource. If you
were careful to name your form elements to match the Row attribute names, the SetAttribute data
tag will perform the update on the newly created row for all incoming HTTP parameters.
Related topics
About BC4J Form Input Tags

4-82
4-83
To allow users to edit rows, you typically create two JSP pages that work together:
● A data input JSP page that includes the BC4J Input data tags to render data bound
controls that can accept the user's input for single rows in your view object datasource.
This JSP page submits the data, together with a row identifier, as HTTP parameters to
another page for processing.
● A submit JSP page to accept the incoming HTTP parameters and update the datasource
on the identified row.
Note: JDeveloper provides the DataPage Wizard to help you quickly generate Edit and
Submit JSP pages that will allow users to edit rows in a BC4J datasource. The wizard is
available in the New Object gallery: to launch the wizard select File-New, select the Web
Objects tab and double-click the DataPage icon.
Role of the BC4J Input Tags
You can use the BC4J data tags including <jbo:InputXxx... /> in an HTML form element and
<jbo:Row... /> to create JSP forms that let the user:
● Display an existing record and its values
● Edit the record values and update the corresponding row in the BC4J datasource
In order for your submit JSP page to process row data, the edit JSP rendered by the web
server page must contain:
● Form elements that specify name-value pairs, where the name matches the name of the
attribute to update
● The row key object to identify the datasource and row being edited
The BC4J Input data tags take care of the first requirement when you set the tag's "dataitem"
for the datasource attribute to update. An HTML hidden input element that you assign a value
using the BC4J ShowValue data tag and the special view object attribute RowKey takes care of
the second. The browser posts this information, which it collects from the JSP form elements,
4-84
as HTTP input parameters to your submit JSP page for processing.
Role of the Edit and Submit JSP Pages
The data input (edit) JSP page contains:
1. BC4J data tags that specify an application module connection and a valid view object
datasource.
2. A BC4J ApplicationModule data tag with the releasemode attribute set to stateful to
preserve the state of the application module until processing is completed. The state
recommended for edit operations is "Stateful". Specifying stateful mode allows you
datasource to be preserved until the user completes the operation.
3. The HTML <form> element with an "action" reference to the submit JSP page.
Tip: It is recommended to use HTTP POST requests to pass row values to your submit
JSP page. This protocol ensures that the browser can pass parameter values of any
length. If you omit method="post" from the <form> tag, the browser will use HTTP GET to
pass the parameter values appended to the URL of the submit JSP page and URLs
longer than 255 characters can be problematic. To use POST requests, your <form> tag
might look like this:
<form name="DataInput_form" method="post" action="submit.jsp">
If you are not familiar with the HTTP methods defined by the HTTP protocol, refer to the
World Wide Web Consortium (W3C) for details:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3.
4. JSP scriptlet code that permits the user to browse the datasource's existing rows.
Whether the edit JSP page displays one row or multiple rows, the JSP interaction
requires the user to edit and submit one row at a time.
5. The desired BC4J Input data tags to render the current value of a specific attribute in the
datasource and give the user the ability to edit the value. Your form uses these to
generate HTTP request parameters that contain the value of attributes to be updated.
6. A hidden HTML input element to generate a control that contains the row key for the
datasource attributes to be updated. Your form uses this control to generate another
HTTP request parameter for the row to be updated.
4-85
The submit JSP page contains:
1. BC4J data tags that specify the same application module connection and view object
datasource as the edit JSP page.
2. A BC4J ApplicationModule data tag with the releasemode attribute set to stateless to
release the state of the application module once the data is committed.
3. A BC4J Row data tag to match the datasource row and attribute to update with the HTTP
request parameters submitted by the edit JSP page.
4. BC4J data tags to commit (or rollback) the row to the database.
5. An HREF that returns the user to the edit JSP page for further row edits.
Using the BC4J Input Tags to Supply Input Parameters
In order to generate the HTTP input parameters, the BC4J Input data tags require that you
specify a datasource and dataitem. The datasource identifies the BC4J view object to update
and the dataitem identifies the attribute in the view object which is to receive the edited value.
The input parameter combines the value the user enters with the name you specify for the
dataitem to form a name-value pair.
For example, this is how a basic InputText data tag looks when used to update the customer
number (CustNo) attribute of a customer (custDataSource) datasource:
<jbo:InputText datasource="custDataSource" dataitem="CustNo" />
Note that you can use object notation on the dataitem when it is of type Object:
<jbo:InputText datasource="custDataSource" dataitem="Address.City" />
Using the BC4J ShowValue Tag to Obtain a Row Key
After you have bound the Input data tags to the desired datasource attributes, you must identify
the datasource row currently being edited by the user. To uniquely identify the row displayed in
your edit JSP page, you use a special attribute of the view object datasource to obtain the row's
4-86
row key value. You then post the row key value using an HTML hidden input element. For
example, in order to generate a row key for the current row, your edit form needs to include an
element such as this:
<input name="RowKeyValue" type="hidden" value="<jbo:ShowValue

datasource="custDataSource" dataitem="RowKey"/>" />
This code uses the BC4J ShowValue data tag to render the string representation of the row key
using the value of the special view object attribute attribute RowKey to identify the current row
within the datasource. The name of the input HTTP parameter (RowKeyValue) is your choice.
However, the value of the ShowValue dataitem must be "RowKey" in order to match this
attribute name in the datasource. The datasource (custDataSource) of the ShowValue datatag
must match the datasource named by the Input data tags.
Note: You can also use the ShowValue data tag and the row key to generate an HREF anchor for
any row when you want to perform a BC4J Row data tag "Find" action.
Continuing with the customer example--after the user enters a customer number and sends the
form data, the browser will generate an HTTP request object based on the entered value and
the row key.
Using the BC4J Row Tag to Update a Row
You use the submit JSP page to retrieve the HTTP parameters and initiate the update action on
the specified row. The Row data tag with the action "Update" serves this purpose:
<jbo:Row id="myrow" datasource="custDataSource" rowkeyparam="RowKeyValue"

action="Update" > </jbo:Row>
Input data tags in your insert or edit JSP page. You identify the specific row to receive the
update by assigning the user-defined name of edit JSP page's hidden input element
(RowKeyValue) to the Row data tag's rowkeyparam attribute. The Row data tag uses the
rowkeyparam tag attribute to obtain the row key value from the HTTP request object. Using the
row key to locate the target row in the BC4J datasource, the Row data tag implicitly performs a
set attribute operation on the incoming HTTP parameters, which contain the attribute name-
value pairs obtained from the rendered form controls. Because you specified the name of the
datasource attribute to update in the dataitem of the Input data tag, the Row data tag receives
the correct attribute to update.
4-87
Note: The update operation performed by the Row data tag works efficiently to prevent needless
attribute updates. The Row data tag will skip the set attribute operation unless the value of the
request parameter that contains the user's input value differs from the original value (visible in a
hidden input element in the rendered JSP).
Related topics

4-88
About Control Hints for Business Components
Clients
Applications that interact with business components rely on the Oracle Business Components
for Java (BC4J) framework to access the database. The Business Components tier of this type
of data-access application provides mechanisms for retrieving data from the database and
converting the database types to Java types for consumption by the Java client application tier.
The Business Component tier also provides a centralized mechanism for any Business
Components data item to be rendered in a consistent manner across all client types. This
mechanism, known as control hints, permits business components developers to:
● Centralize certain UI settings across clients and thereby control many aspects of the way
the UI interacts with the data item
● Reduce the amount of UI coding in the client tier
● Permit JDeveloper client application wizards to generate a customized UI for a particular
business components project
JDeveloper supports these specific client applications with the built-in capability to interact with
the business components and utilize control hints:
● Java GUI clients through the JClient MVC architecture

● JSP Web applications through the BC4J Data Tags JSP tag library
● UIX-style Web applications through the BC4J UIX JSP tag library
About the Control Hints Mechanism in Business Components
The Business Components tier is an assemblage of cooperative objects which work together to
provide a transactional environment for client applications that access the database. Business
components clients interact with the BC4J framework through the high-level application module
object. To initiate database access, the client obtains an instance of the application module,
which defines the state of the application data and provides a connection to the database. For
each application module, the business components developer creates these objects in the
business components project:
● Entity objects to map tables and their columns to the Java object representation
● View objects to define the particular usage of the Java object representation for the
clients
4-89
● Attribute objects to define the Java type of a particular data item
In addition to the basic functions these business components provide, the business
components provide numerous other functions that serve the business components tier. One of
these functions is to store control hint information to define how a client UI should render
particular attribute values.
The important point about the usage of control hints in the business components project is that
control hints are properties of the defining object and as such can be inherited by other
business components. For example, any control hint property the developer sets on the entity
object level will be propagated to any view object that references the entity object. On the other
hand, it is also possible to set up control hints at the view object level to override entity-level
control hint property definitions. The ability to inherit and override control hint properties by view
objects allows the business components developer to:
● Setup global control hints at the entity object level

● Define UI specific control hints at the view object level
About Control Hint Properties
All control hints are grouped by the Locale setting in the Control Hints panel. When you select a
language for the locale, you can specify different control hint for each language. Typically, you
will use the Locale to specify the label text and tooltip text in the language appropriate for the
chosen locale.
The control hints mechanism supports these control hint properties:
● Label Text is the text used in prompts or table headers that precede the value of a data
item.
● Tooltip Text is the text used in tooltips or fly-over text. In Web applications, it appears as
the value of the HTML ALT attribute.
● Format Type defines the formatter to use when the data item is displayed. Formatters
are basically a collection of format masks that you can define in the
JDeveloper/system/formatinfo.xml file.
● Format is the particular format mask used by the selected formatter.
● Display Hint determines whether the attribute will be displayed or not. In the JClient
design-time wizards, you can override this attribute.
● Control Type selects the control type used to display the data item in the client UI: Edit
makes the control editable, Date displays a calendar picker, and default is interpreted by
4-90
the client to select the most appropriate control.
● Display Width defines the character width of the control that displays the data item.
● Display Height defines the number of character rows of the control that displays the data
item.
● Form Type determines whether the attribute will be displayed in Detail mode or
Summary mode. The detail mode is a long form, whereas, Summary mode is a short
form.
About Design-time Support for Control Hints
Design-time support for control hints is provided at two levels:
● Editing control hints through property editors

● Visualizing control hints in the client through the UI Editor
● Visualizing control hints in the UI of the Business Components Tester
The JDeveloper business components design-time wizards provide the mechanisms for setting
and editing control hints on the attributes of both entity objects and view objects. To edit
controls hints for an attribute, you display the attributes of the desired entity or view object
displayed in the Structure window and right-click to open the attribute in the attribute editor.
In the Entity Attribute and View Attribute Editor control hints are visible as properties of the
current attribute. You can use the Control Hints tab to easily edit the control hints properties.
Once set in the Control Hints tab, you can click the Properties tab to view which hints are
added for the attribute.
The following table lists the control hints and whether the various business components clients
pick them up.
Hint Name BC4J Data Tags BC4J UIX Tags JClient Java UI
Label Text yes yes yes
Tooltip Text yes no yes
Formatter and Format Mask yes yes yes
4-91
Display Hint yes yes yes
Control Type yes yes yes
Display Width and Height yes yes yes
Form Type Not applicable. Not applicable. yes
About Runtime Support for Control Hints
Runtime support for control hints is provided at two levels:
● Automatically using control hints to render the UI of a business components client

● Accessing control hint definitions and displaying them through the control hints API
During runtime, business components clients automatically make use of the control hints to
determine how to render the attribute value. If the control hint property is supported for your
particular business components client (see above table), no further action is required to
customize the UI. Customization of the UI, in this case, takes place in the centralized control
hints of the business components themselves.
In the case of Web applications, the BC4J Data Tags custom JSP tag library provides the
<jbo:ShowHint> data tag to directly access the control hint definitions for a particular attribute.
Additionally, all the rendering data tags will automatically use the various control hints. For
example, the <jbo:InputRender> data tag will use the Control Type hint to decide which control
to render at runtime. The rest of the input data tags will use the formatting hints to format the
output of the attribute value. Support for control hints is built into the HTML field renderers, so
both BC4J data tags and data web beans can make use of the control hints support. The
<jbo:ShowValue> data tag is useful when you want to display an attribute value without the
extra formatting provided by control hints. For example, you may want to construct an HTML
table to display the values of data items, but not want to render the data items with control
hints.
In the case of Java GUI clients, the control hints API gives the UI developer direct access to the
control hint definitions. Although control hints are properties of the attribute object, it is not
recommended to use the getProperty() method to retrieve a particular control hint. Instead, it is
recommended to use the convenience methods of the control hints API. For example, the UI
developer accesses labels, tooltips, and control types for a particular locale by these methods
of the AttributeHints interface:
4-92
import oracle.jbo.*
ViewObject vo = am.findViewObject("DeptView");
AttributeDef aDef = vo.findAttribute("DeptNo");
LocaleContext locale = am.getSession().getLocaleContext();
String sLabel = aDef.getUIHelper().getLabel(locale);

String sTooltip = aDef.getUIHelper().getTooltip(locale);
Int nControlType = aDef.getUIHelper().getControlType(locale);
About the Format Type Control Hint
The formatting control hints Format Type and Format give the business components developer
the ability to make use of attribute formatters through business components domain classes. In
the business components project, developers can map their formatter to a business component
domain when they want to:
● Define a new formatter in addition to the default Number and Currency formatters
● Add an format mask to an existing formatter
Each domain class can have any number of formatters. A formatter can support any number of
masks. In the attribute editor, you will be presented with lists of available formatters and their
corresponding value masks from which to choose. The mapping of the domain type to its
available formatters is maintained in the JDeveloper/system/formatinfo.xml file. The business
components developer uses the Domain Wizard to create the domain, but currently JDeveloper
does not support autogeneration of domain formatter and masks in the formatinfo.xml file.
Developers who create a new domain type and want to add the format to the list of available
formatters must hand edit the contents of this file.
Related topics
Customizing the UI Using Control Hints

Defining a Formatter and Format Masks for the UI
4-93
Data bound BC4J JSP pages access business components through instances of the application module. You
can decide how application module instances are allocated during the JSP session, whether their state is
preserved, and whether there is failover support from the database. The application module pooling
implementation in the Business Components for Java (BC4J) framework supports three modes:
● Stateless
● Stateful (the default mode for all JSP pages)
● Reserved
The mode you select for your JSP page will depend on the type of Web application you create. The following
sections describe the options and the role they play in Web applications that access data cached by business
components.
About Application Module State Management in Data Bound BC4J JSP Applications
During page processing, the HTTP requests for a page share a limited pool of instances of each application
module. In a stateless JSP application, access to a specific instance of the application module is maintained
only for the duration of the page requests. Then, when the ApplicationModule data tag with Stateless option is
processed, the application module instance must be released back to the pool of instances of that application
module.
When you select the Stateless option for individual JSP pages or the entire JSP application, the data tags do
not necessarily access the same application module instance each time a new page is invoked during a
specific HTTP session and, therefore, cannot depend on a view object's rowset remaining the same from one
invocation to the next. This behavior is desirable when your JSP pages work independently from one another,
and do not represent a single task that requires state to be maintained. Permitting the majority of your JSP
pages to release the application module instance statelessly reduces the overhead that managing application
module state entails and ensures that your JSP application will operate at the highest level of performance
possible.
If you allow the default Stateful option for the ApplicationModule data tag, the data tags of a JSP application
also do not access the same application module instance each time they are invoked. However, unlike
stateless JSP pages, Business Components for Java saves the application module state to the database, a
file, or memory (depending on the value of the passivationstore parameter) when the application module is
released, and allows a view object's rowset to remain the same from one invocation to the next. Stateful
mode is the preferred choice when:
● You want to preserve information across a series of JSP pages that users interact with to complete a
single task
● You want to preserve changes submitted by the user from one page to the next
In stateful mode, Business Components for Java provides failover support from the database, and permits the
4-94
application module pool to be used efficiently. The application module pool manager manages the application
state including the current position and all dynamic application information that needs to be passed from one
JSP page to the next. Stateful mode is useful whether or not the user submits changes to the data: it is easier
and more efficient to let Business Components for Java manage restoring queries to the previous HTTP
request than performing these tasks programmatically using the Business Components for Java API.
Important: If you do permit users to modify data in stateful or reserved mode, you must use the Commit data tag to
submit the changes to the database as described in About Database Transactions in Data Bound BC4J JSP
Applications below.
When you select the Reserved option for the ApplicationModule data tag, once a data tag has connected to
an application module, all subsequent connections to that application module from any data tag during the
same HTTP session involve the same instance of the application module. This holds true whether a
subsequent connection is from another JSP page or from a new invocation of the same JSP page. This mode
is similar to the stateful application, but it does not provide failover support, nor does it permit application
modules to be recycled. Reserved mode is useful in an intranet type environment.
About Database Transactions in Data Bound BC4J JSP Applications
When the web application user modifies data through data bound BC4J JSP pages and clicks Submit in the
JSP page to process the data, the web application framework (basically Business Components for Java)
handles the database transaction differently depending on the state of the application module when it is
released:
Release Mode Database transactions and user actions

The web application framework automatically posts and commits any changes because the
application module state is not maintained between requests in stateless mode. The user is not
Stateless
expected to initiate the commit in stateless mode: the Commit and Rollback buttons are disabled in
the JSP page.
The web application framework merely saves the application module state, including the data
changes, to the database at the end of a page request. In this mode, the user is expected to initiate
the commit by clicking the Commit button in the process JSP page. Once the user clicks the Commit
Stateful button, the framework will immediately initiate a post and commit (together, as one step) on the
database. Optionally, the user can click the Rollback button to prevent their changes from entering
the database without ever initiating a post. Because the application module state is preserved, the
user can initiate the Commit or Rollback at any point during the HTTP session.
The web application framework automatically posts any changes to the database (and initiates DML-
specified database triggers on the effected tables). In this mode, the user is expected to click either
Reserved the Commit button or Rollback button in the process JSP page. Because the application module itself
is not released for the duration of the HTTP session, the user can initiate the Commit or Rollback at
any point.
Application Module Pool Naming in Oracle9i JDeveloper
In JDeveloper 3.2, if you created JSP pages with data tags, your data bound JSP files would define an
application module in a line like this:
4-95
<jbo:ApplicationModule configname="bc4j1.Bc4j1Module.Bc4j1Module9iAS"
id="Bc4j1Module" />
JDeveloper 3.2 used the value of id for the name of the application module pool. Starting in Oracle9i
JDeveloper the value of config is used as the name of the pool. When you migrate your JDeveloper 3.2 JSP
applications to Oracle9i JDeveloper you will need to edit Java references to the pool name. For instance, the
following Java code would return a NullPointerException in Oracle9i JDeveloper for the application module
definition shown in the above data tag:
<%
oracle.jbo.common.ampool.PoolMgr mgr = oracle.jbo.common.ampool.PoolMgr.getInstance();
oracle.jbo.common.ampool.ApplicationPool pool = mgr.getPool("Bc4j1Module");
pool.commitAndSyncCache(ds1.getRowSet().getApplicationModule());
%>
Edit the getPool() method to use the configname value instead:
oracle.jbo.common.ampool.ApplicationPool pool = mgr.getPool("bc4j1.Bc4j1Module.Bc4j1Module9iAS");
Synchronizing Application Module Usage for Separate Web Applications
When you want to deploy multiple Web applications that access the same business components running on a
single server, you do not want business components clients to share the same instance of the application
module. The application pool manager can prevent an application pool instance from being shared between
applications when you declare that BC4J is running inside of an OC4J instance with the property
jbo.server.in_oc4j set to true. To specify this property, at the OC4J command line enter:
java -D jbo.server.in_oc4j=true -jar oc4j.jar
Synchronizing Application Module Usage for Multi-Frame Style Web Applications
A runtime error can occur when a web application user accesses the same application module instance
through different JSP pages during a single HTTP session. This can occur when the user runs JSP pages in
separate frames: each frame is handed the same application module to use. Hence, once one of the JSP
pages finishes with the same view object, it will close the result set on the other view object and create a
runtime exception.
There are two possible ways to avoid this problem:
Solution 1:
1. Create two view objects in the Business Components project that are identical.
2. Set up one JSP page to use the first view object and the other JSP page to use the second view object.
Solution 2:
4-96
1. Use only one view object, but at runtime force the JSP pages to obtain the data locally using:
RowSet rs = vo.getRowSet();
OR
Row[] rows = vo.getAllRowsInRange();
2. Then you can iterate through a local copy of the data.
Related topics

About Application Module Pooling
Defining Business Component Runtime Properties in the bc4j.xcfg File for Web Applications
Specifying an Application Module for JSP Pages
Managing Application Module State Using Data Tags
4-97
About BC4J Configuration Properties for a JSP
Project
Data bound BC4J JSP applications that connect to deployed business components relies on a
bc4j.xcfg configuration file to define the server connection information. The file defines all of the
deployment configurations of a particular application module in the Business Components
project and permits data tags and data web beans to access a specific view object belonging to
the application module.
You can edit the configuration file:
● To update the connection information that the <jbo:ApplicationModule> data tag use to
identify the Business Components application module's deployment scenario
● To modify the mode in which your JSP application runs (stateless, stateful, or reserved)
Note: If you edit a configuration in the bc4j.xcfg file and change the deployment platform (Middle
Tier Server Type option), you will need update your business components project to add the libraries
for the new platform. Choose Deploy to projectname.jar on the Common and Middle Tier archives
for the deployment archive your created in your Business Components project.
The Contents of a Configurations File
A configurations file contains the following information that is important to JSP client
applications.
Information
Properties Values
About
The application Application_Name The name of the application module package and application module.
module
accessed by
the JSP
application
The application DeploymentPlatform The server platform you can choose from includes Local, VisiBroker,
module's Oracle9iAS EJB, or WebLogic EJB.
connection
information
4-98
ConnectionName The name of the application module's server connection definition. What
you specify depends on your deployment platform:
● For Oracle9iAS EJB deployment, the connection information is

automatically populated in the Configuration Manager based on
your database connection information if you are using JDBC
URL. Or, you can specify a JDBC DataSource that matches the
name you used when creating the deployment profile for a BC4J
application deployed as an EJB session bean .
● For WebLogic EJB deployment, you can specify the JDBC URL
or JDBC DataSource for distributed transactions.
● For Local or web module deployment, you can use a JDBC URL
or a JDBC data source. However, make sure that you rebuild the
Middle Tier BC4J project to make the configuration available to
the JSP client. You'll also need to edit the
x:\<ORACLE_HOME>\j2ee\home\config\data-sources.xml file to
include a matching <location> value that you are using in your
BC4J project. By default, local or web module deployments use
the JDBC URL connection.
● For VisiBroker, you can use JDBC URL or JDBC DataSource.
See Deploying CORBA Objects on VisiBroker.
Whether the RELEASE_MODE Stateful when you want the application module instance's state to be
JSP Application preserved between requests. This is the default mode.
is stateful or Stateless when you do not require the application module instance's
stateless state to be preserved between requests.
Reserved when you want the application module instance to be
allocated for the duration of the browser session. The browser receives
an application module instance when a JSP page is encountered, and
releases it at the end of the session.
Note: See About JSP Pages and BC4J Application Module Pooling for further details about
releasing application module resources in your JSP pages.
Configuration Name
The Configuration Manager dialog in JDeveloper lets you generate a configuration with the
name:
<ApplicationModulePackageName>.<ApplicationModuleName>.<ConfigurationName>
● where <Application Module Package> is the fully qualified name of the package
containing the application module but with all periods replaced by underscores
4-99
● where <Application Module Name> is the name of the application module
● where <ConfigurationName> is the name of the configuration you specified in the
Configuration Manager dialog
For example, a JSP-specific configuration you create for an application module named
OnlineOrdersModule in a package called OnlineOrders would be named:
OnlineOrders.OnlineOrdersModule.OnlineOrdersConfig
Configuration File
JDeveloper places the bc4j.xcfg file in a common directory in the business component package
it generates in myclasses. For example, a bc4j.xcfg file that you generate for a business
component package named OnlineOrders would appear in:
<JDeveloper>/myclasses/OnlineOrders/common/bc4j.xcfg
Note: If you modify the configuration file that the JSP client application uses, you must rebuild
the business component project to make the configuration available to the JSP client.
You do not deploy the configuration file when you deploy a Web application. The person
responsible for deploying the business components application module will automatically
deploy the bc4j.xcfg file as subdirectory of the application module classes directory. You need
only be sure that the deployed bc4j.xcfg file contains a configuration that you specify for use
with your BC4J data tags and that the configuration information is correct. In JDeveloper you
can create and edit the configurations using the Configuration Manager by right-clicking on the
application module node in the Navigator and selecting Configurations.
Related topics

About Business Components for Java (BC4J) Deployment
4-100
About Web Beans
In releases prior to Oracle9i JDeveloper, a set of predefined web-enabled JavaBeans, or web
beans, were available for use directly in JSP pages. Starting in Oracle9i JDeveloper, web bean
technology in JSP pages is now accessed entirely through two JSP tags in the BC4J Data Tags
custom tag library:
● <jbo:WebBean/>
● <jbo:DataWebBean/>
Note: Although JDeveloper still supports custom web beans or working the predefined web beans in
JSP pages, it is recommended to use the JSP tag counterparts known as BC4J component tags
provided by the BC4J Data Tags custom tag library.
Web beans in JDeveloper are components that the JSP developer can use to output HTML
directly from the bean. Web beans have access to the HttpRequest and HttpResponse objects
of the JSP page and are used to generate content dynamically. Because web beans are
reusable objects, they simplify the development of JSP pages where a consistent look and feel
is desired. You can:
● Use web beans with your JSP page by inserting the DataWebBean or WebBean data tag
from the Component Palette
All web beans implement, either directly or indirectly, JDeveloper's WebBean interface. Web
beans fall into two groups:
● Data web beans that are bound to business component datasources represented by
view objects
● HTML web beans that are not data bound and serve as visual or UI web beans
About Data Web Beans
Data web beans provide access to datasources represented by a view object defined in a
Business Components project. The data web beans don't implement the DataWebBean
interface directly; they instead extend the class DataWebBeanImpl, which provides
implementations of both the WebBean interface and the DataWebBean interface. The data web
beans implementation makes it easy to create reusable JSP page elements that can access
data encapsulated in business components.
4-101
For example, you can use data web beans to:
● Create master-detail forms

● Represent complex data in the form of charts and trees
The data web beans include:
● NavigatorBar
● RowSetBrowser
● EditCurrentRecord
● ViewCurrentRecord
● FindForm
● XMLDataGenerator
● RowSet Navigator
● Chart
About HTML Web Beans
The HTML or non-data bound web beans:
● Implement the WebBean interface directly
● Extends a class, such as HTMLToolbar, which renders an HTML object and in turn
extends the class HTMLElementContainer
For example, the toolbar web bean generates an HTML toolbar just as its parent HTMLToolbar
does but, unlike its parent, stores references to some of the JSP's implicit objects within its
member variables. A JSP page's implicit objects are accessible to JSP elements such as Java
scriptlets.
The HTML web beans include:
● Toolbar
● TableControl
4-102
● EditForm
Web Bean Source
A knowledge of JDeveloper's web bean classes is important to understand how to use

JDeveloper's predefined web beans and how to create your own web beans.
The source code for these classes and interfaces is located in the ZIP file
<JDeveloper>\src\bc4jhtmlsrc.zip, where <JDeveloper> is the directory in which JDeveloper is
installed.
The predefined web beans inherit from:
● WebBean
● WebBeanImpl
● DataWebBean
● DataWebBeanImpl
● HTMLToolbar
● HTMLTable
● HTMLForm
● HTMLElementContainer
● HTMLElement
Known Issues with Web Beans
● qView Instance Variable is Not Supported on Data Web Beans
In releases prior to Oracle9i JDeveloper, the Web Bean Wizard generated an instance
variable qView that let you work with a view object rowset. In Oracle9i JDeveloper, this
instance variable is not supported. In order to continue to develop your web application in
JDeveloper, you need to specifically change:
qView to getRowSet()
For example:
qView.setRangeSize(-1);
4-103
qView.first();
Must be changed to:
getRowSet().setRangeSize(-1);
getRowSet().first();
● populateForm() method not available to render web beans since JDeveloper 3.2
Users need to implement the renderToString() method. This change was made to make
the HTML field renderers accessible to both data web beans and BC4J Data Tags.
Please refer to the oracle.jdeveloper.HTMLFieldRendererImpl class in jbohtmlsrc.zip.
Related topics

Working with Web Beans
4-104
Defining Business Component Runtime Properties
in the bc4j.xcfg File for Web Applications
When you want to access business components through data bound BC4J JSP pages, you
must create a configuration that specifies the runtime application module connection for the
JSP page. You will choose the runtime configuration you create:
● In the Business Components JSP Application Wizard when you generate JSP pages
based on an application module you choose
● When you insert an ApplicationModule data tag into your JSP page from the Component
Palette
Later, you can edit the application module configuration for your data-enabled JSP project:
● To update the connection information that the JSP data tags and data web beans use to
identify the Business Components application module's deployment scenario
● To modify the mode in which your JSP application runs (stateless, stateful, or reserved)
Note: If you do not create an application module runtime configuration, the bc4j.xcfg file in your
business components project defines a default configuration that lets you run JSP pages within
JDeveloper. The default configuration local is also known as local mode deployment because it
assumes the the business components and the web application run in the same VM. However, for a
local or an Oracle9iAS EJB deployment, you can also choose to specify a JDBC DataSource which
matches the <location> value in the x:\<ORACLE_HOME>\j2ee\config\data-sources.xml file. See
About OC4J Data Sources for more information.
To create a configuration:
1. In the Navigator, under your business components project, right-click the application
module node and choose Configurations to display the Configurations Manager dialog.
2. Click New.
3. Choose the middle-tier server type and a previously defined JDBC URL connection or
specify the JDBC DataSource as described in the F1 Help for the Application Module tab.
4-105
4. If you want to change the JSP page-resource release mode for the application module,
click the Properties tab and edit the RELEASE_MODE field, as described in the F1 Help
for the Properties tab.
To edit a configurations file:
2. To edit a configuration in the Configurations Editor dialog, select the configuration to edit
from the list and click Edit.
3. Choose the middle-tier server type and a previously defined JDBC URL connection or
specify the JDBC DataSource as described in the F1 Help for the Application Module tab.
4. If you want to change the JSP page-resource release mode for the application module,
click the Properties tab and edit the RELEASE_MODE field, as described in the F1 Help
for the Properties tab.
5. If you changed the deployment platform specified by the configuration file by choosing a
different Middle Tier Deployment Type option in the Configuration Editor dialog, then you
must update the Business Components project to add the libraries for the new platform:
1. Create a deployment archive for your business components project.

2. In the Navigator, expand the deployment archive folder.
3. To update the libraries, choose Deploy to projectname.jar on the Common and
Middle Tier archives.
6. Compile the Business Components project.
Related topics

Ways to Generate Data Bound JSP Pages
Inserting JSP Elements into a JSP Page
4-106
Editing JSP Pages Using Code Insight
Running a JSP
Debugging a JSP

4-107
To create global control hints:
1. Create a project for your Business Components.
In order to define global control hints for your business components client application,
you must first create a project with business components entity objects.
2. In the Navigator, expand the business components Package node and select the Entity
Object node whose attributes you want to define control hints.
3. If the Structure Window is not yet visible, choose View | Structure Window to view the
list of attributes for the entity object.
4. In the Structure Window, expand the Attributes folder and right-click the attribute on
which you want to define control hints and choose Edit attributeName.
5. In the Entity Attribute Editor, click the Control Hints tab to view the list of control hint
properties for the current attribute.
To create view-specific control hints:
In order to define view-specific control hints for your business components client
application, you must first create a project with business components entity objects.
2. In the Navigator, expand the business components Package node and select the View
Object node whose attributes you want to define control hints.
3. If the Structure Window is not yet visible, choose View | Structure Window to view the
list of attributes for the view object.
4-108
4. In the Structure Window, expand the Attributes folder and right-click the attribute on
which you want to define control hints and choose Edit attributeName.
5. In the View Attribute Editor, click the Control Hints tab to view the list of control hint
properties for the current attribute.
Related topics
4-109
To map a formatter to a domain for use with Control Hints:
1. Create a new formatter class by extending the oracle.jbo.format.Formatter class.
Alternatively, you can customize one of the default formatters provided in the oracle.jbo.format
package. The default formatters provided with JDeveloper aggregate the formatters provided in
the java.text package.
2. Optionally, in the Domain Wizard, create a new domain class on which you want to map the
formatter.
It is not necessary to create new domain to map a formatter. You may use an existing domain
when the business components project contains a domain of the same data type as the
formatter. For a list of available default domain classes, see the
JDeveloper/system/formatinfo.xml file.
3. Edit the formatinfo.xml file in the JDeveloper/system/ folder to map the formatter class to a
domain class. The XML definition of the formatter must include a DOMAIN CLASS (which can
be a new or existing one), the FORMATTER, which includes the name and class, and the list of
FORMAT definitions the formatter class specifies.
To add a format mask to a formatter for use with Control Hints:
1. Edit the formatinfo.xml file in the JDeveloper/system/ folder to add the format mask to a
formatter. The XML definition of the format mask belongs to a FORMATTER and a DOMAIN
CLASS and includes the text specification of the mask as it will appear in the Control Hints
Format dropdown menu.
To use the new formatter or format mask as a control hints:
In order to define control hints for your business components client application, you must have a
project with business components entity objects and view objects.
2. In the Entity Attribute or View Attribute Editor, edit the attribute on which you want to set the
format.
The attribute you edit must be of the same type as the class implemented by the formatter or
4-110
the new formatter will not be visible in the Format Type dropdown list.
To format an attribute in your client application using the API:
The Control Hints API lets you format attribute values when the business components client do not
automatically use the Format Type control hint. Typically, this includes Java UI clients. In that case,
you need to:
1. Define the Control Hint for the attribute in the attribute editor
2. Obtain the formatted attribute using the getFormattedAttribute() method on the attribute object:
import java.util.Locale;
AttributeDef aDef = rs.getViewObject().findAttributeDef(sName);

Row row = rs.getCurrentRow();
Locale locale = rs.getApplicationModule().getSession().getLocale();
if(aDef.getUIHelper().hasFormatInformation(locale))
obj = aDef.getUIHelper().getFormattedAttribute(row, locale);
3. Strip off the formatting from the attribute using the parseFormattedAttribute() method:
4. Display the attribute value:
if(aDef.getUIHelper().hasFormatInformation(locale))
Object value = aDef.getUIHelper().parseFormattedAttribute(sValue, locale);
Related topics
4-111
When you want to create JSP pages that access business components you can either generate
a single data bound BC4J JSP page or an entire data bound BC4J JSP application:
● Generating JSP pages based on a single business components view object
● Generating an entire JSP application based on a business components application

module
Related topics

Configuring a BC4J Datasource for JSP Pages
Inserting JSP Page Elements from the Component Palette
Running a JSP
Debugging a JSP
4-112
Generating JSP Pages Based on BC4J View Objects
You can use the JSP data page wizards to generate data bound JSP pages for specific view
objects of an existing Business Components for Java (BC4J) project. You use this set of
wizards to add browse, browse and edit, or query JSP pages to your JSP application. All
generated data pages use JDeveloper's component tags from the BC4J custom data tag library
and the page template associated with the data page wizard you select.
To create a Business Component project:
In order to use business components with your BC4J JSP application, you must first
create a project with a Business Components application module.
To generate a BC4J JSP data page:
1. Select the project in the Navigator in which you want to create the new BC4J JSP data
page.
3. Select the BC4J JSP folder.
4. Select type of page template you want to use to generate the JSP page by double-
clicking the desired Form icon. The Data Page Wizard appears.
For detailed help about completing the wizard, press F1 or click Help from within the
wizard.
When you finish, your project contains:
● The new data bound JSP page
● One JSP page for each BC4J component tag used in the data bound JSP page
4-113
● A BC4J archive file (bc4j.ear) used to deploy the entire BC4J JSP application
● A WAR deployment profile (projectName_War) used to create a WAR file for the JSP
application
● A deployment descriptor (web.xml) used to run the JSP pages using JDeveloper's
embedded OC4J container
You're ready to run the JSP application—or you may wish to customize it first.
Related topics
Generating a JSP Application Based on a BC4J Application Module


Running a JSP
Debugging a JSP
4-114
Generating a JSP Application Based on a BC4J
Application Module
You can use the Business Components JSP Application Wizard to generate an entire data
bound JSP application, based on the view objects of an existing Business Components for
Java (BC4J) project. The wizard lets you generate a set of data bound browse, browse and
edit, and query JSP pages. All generated pages use JDeveloper's component tags from the
BC4J custom data tag library and the page templates you select in the wizard.
To create a Business Component project:
In order to use business components with your BC4J JSP application, you must first
create a project with a Business Components application module.
To create a BC4J JSP application based on an application module:
It is recommended to create a separate project for your BC4J JSP application. This new project
must be in the same workspace as the business component's project in order for the Business
Components JSP Application Wizard to find your application module.
1. Select the workspace in the Navigator in which you want to create the JSP project.
2. Create an empty project for your BC4J JSP application.
3. With the new project selected in the Navigator, choose File | New to open the New
Gallery dialog box.
4. Select the BC4J JSP folder.
5. Double-click the Business Components JSP Application icon in the Items list. The
Business Components JSP Application Wizard appears.
For detailed help about any of the following steps, press F1 or click Help from within the
wizard.
6. Name your JSP application, specify the document root directory of your web server to
contain your JSP application files, and name the WAR file used to deploy your
4-115
application. Click Next.
7. Select the application module you want your JSP application to use and provide
information about its deployment.
8. Accept the default local-mode configuration that your JSP application uses to connect to
the application module. Click Next.
The default configuration accesses business components in local mode, which requires
the business components and the JSP application to run in the same VM. Local-mode
configuration also lets you run your JSP application using JDeveloper's embedded OC4J
container. You can view configuration settings by right-clicking the application module in
the Business Components project and choosing Configurations.
9. By default, the wizard will generate JSP pages for every view object that the application
module defines. From the displayed list of view objects, select the ones you do not want
your JSP application to use and unselect Generate page.
10. Optionally, edit the File Name field when you don't want to use the name of the view
object to uniquely identify generated pages that use the same page template. Click Next.
11. By default, the wizard will generate JSP pages for every view link between view objects
that the application module defines. From the displayed list of view links, select the ones
you do not want your JSP application to use and unselect Generate page. The view-links
generated JSP pages, let you browse between master and detail related view objects.
Click Next and complete the wizard.
● The new data bound JSP pages
● One JSP page for each BC4J component tag used in the data bound JSP pages
● A BC4J archive file (bc4j.ear) used to deploy the entire BC4J JSP application
● A WAR deployment profile (projectName_War) used to create a WAR file for the JSP
application
● A deployment descriptor (web.xml) used to run the JSP pages using JDeveloper's
embedded OC4J container
4-116
You're ready to run the JSP application—or you may wish to customize it first.
Related topics


Running a JSP
Debugging a JSP
4-117
Working with BC4J Data Tags
JDeveloper provides a set of JSP 1.1 compliant custom tags known as data tags. In
JDeveloper, data tags provide a simple tag-based approach to accessing and manipulating
business components datasources in JSP pages. For more details, see About BC4J Data
Tags.
You use the data tags to:
● Establish a connection from a JSP page to a BC4J application module instance
● Manage JSP application module state
● Display and render multimedia content
● Locating a row in the BC4J cache
● Create rows in the BC4J cache
● Updating rows in the BC4J cache
● Synchronize the database and the BC4J cache
Related topics

About JSP Tags
4-118
Adding Data Tags to a BC4J JSP Page
1. If the Component Palette is not visible in JDeveloper, choose View | Component Palette
to open the Component Palette.
2. In the Navigator, right-click a JSP file and choose Code Editor.
4. Choose the desired BC4J page from the Component Palette dropdown list.
For a complete list of the BC4J data tags, see Reference: BC4J Data Tags.

tag instead.
7. If the tag you selected has no attributes, JDeveloper will insert the tag directly into the
.jsp file. In order to display the help topic for a tag without attributes, right-click the tag on
the Component Palette and choose Help (available for all tags on the Component
Palette). It is also possible to display help for any tag by searching for the tag name in
the main help.
4-119
Starting with a simple JSP file that you add to your JSP project, you can create a data bound
BC4J JSP to interact with BC4J datasources. When you want to create BC4J JSP pages, you
can insert JSP tags from the BC4J Data Tags custom tag library to:
● Establish a connection to an business components application module instance

● Create an instance of a view object from the business components data model to use as
the BC4J JSP datasource
● Trigger the release of the application module instance at the end of the JSP processing
Note: The BC4J JSP wizards help you to quickly generate data bound JSP pages based on BC4J
JSP page templates that you select. If you need to create a JSP page that is not based on a BC4J
browse, browse and edit, navigation, or query page template, the following procedure describes how
to add BC4J data tags to a JSP page that is initially not data bound.
To create a BC4J JSP page without using a BC4J page template:
1. Create a simple JSP page.

2. In the JSP file, click after the <BODY> tag and press Return to position the insertion
point for the first BC4J data tag.
3. Use the Component Palette to insert the ApplicationModule data tag from the BC4J
Connections page.
4. In the Application Module dialog, select the Business Components Project and the
Application Module that contains the view objects you want to access in your JSP page.
5. From the Configuration dropdown, choose the configuration you want to use to access
the application module. Click Next.
6. In the attributes dialog, you are not required to enter any values. The releasemode
attribute is set to stateful by default. You can change the state by clicking in the field and
choosing from the dropdown menu.
For detailed help about any of the JSP tag's attributes, press F1 or click Help from within
the dialog. This is the help topic for the ApplicationModule data tag.
7. Click Finish to insert the ApplicationModule data tag and corresponding

ReleasePageResources data tag into your JSP page.
4-120
Note: The <jbo:ReleasePageResource/> data tag releases the application module
instance after your JSP page has executed all BC4J data tags. For this reason, the
ReleasePageResources data tag must be the last BC4J data tag in your page. Do not
remove the ReleasePageResources data tag or place any BC4J data tags after the
ReleasePageResources tag.
8. Create an insertion point for the next BC4J data tag by adding a new line in the JSP file
immediately after the inserted <jbo:ApplicationModule/> data tag.
9. Select the DataSource data tag from the Component Palette.
10. In the Data Source dialog, select the Application Id that contains the view objects you
want to access in your JSP page and select a View Object from the displayed data
model. Click Next.
11. In the attribute dialog, enter the required Values for the datasource. After you enter the
values, click Finish to insert the <jbo:DataSource/> data tag into your JSP page.
This is the help topic for the DataSource data tag.
You now have a data bound BC4J JSP page and you can insert other JSP tags to interact with
the BC4J datasource. For example, you can quickly assemble browse, browse and edit,
navigation, or query type BC4J JSP pages using the BC4J component tags. Alternatively, you
can work further with the low-level BC4J data tags from the Component Palette. For complete
information about the individual BC4J data tags, refer to the F1 help in JDeveloper or refer to
the Reference: BC4J Data Tags to access the tag help topics.
Related topics

About BC4J Components Tags
About JSP Pages and Application Module Pooling
4-121
Managing Application Module State Using Data
Tags
You can decide how application module instances are allocated during the JSP session,
whether their state is preserved, and whether there is failover support from the database. The
default application module pooling implementation in the Business Components for Java
(BC4J) framework supports three modes:
● Stateful (the default mode for all JSP pages)

● Stateless
● Reserved
In a JSP application you can control the manner in which a data bound JSP page releases its
application module instance at two levels:
● At the level of the entire JSP application by setting the RELEASE_MODE property in the
configuration you create for an application module
● At the level of individual JSP pages by setting the releasemode attribute for the
ApplicationModule data tag
Note: The mode you specify for the ApplicationModule data tag overrides the JSP application
release mode at the level of individual JSP pages.
The ReleasePageResources data tag provides a marker for the JSP page that triggers the
release of the application module instance. For this reason, each data bound BC4J JSP page
you create must end with this tag.
For complete details about the purpose of each releasemode attribute option, see About JSP
Pages and Application Module Pooling.
Related topics

About JSP Pages and Application Module Pooling
4-122
4-123
To display an embedded image in the browser
Suppose you have a database table created by the following SQL statement:
create table images (id number primary key, pic ordsys.ordimage, description varchar2(200));
You build a Business Components project on top of this table. This sample code displays the image data
stored in the table.
<%@ page language="java" errorPage="errorpage.jsp" contentType="text/html" %>
<jbo:ApplicationModule id="am" configname="images.ImagesModule.ImagesModuleLocal"

releasemode="Stateless" />
<jbo:DataSource id="ds" appid="am" viewobject="Images1View" rangesize="3"/>
<jbo:EmbedImage datasource="ds" mediaattr="Pic"

whereclause="id = 2" alt="family reunion picture" />
<jbo:ReleasePageResources />
To use an embedded player to play video in the browser
You can choose one of three media players to play the video: Windows Media Player, RealMedia Player, and
QuickTime Player. You have to use Internet Explorer to render the video correctly.
<jbo:ApplicationModule id="am" configname="videos.VideosModule.VideosModuleLocal"

<jbo:DataSource id="ds" appid="am" viewobject="Videos1View" rangesize="3"/>
<jbo:EmbedVideo helperapp="QuickTimePlayer" datasource="ds"

mediaattr="Clip" whereclause="id = 2" />
To use an embedded player to play audio in the browser
You can choose one of three media players to play the audio: Windows Media Player, RealMedia Player, and
QuickTime Player. You have to use Internet Explorer to render the audio correctly.
4-124
<jbo:ApplicationModule id="am" configname="audios.AudiosModule.AudiosModuleLocal"

<jbo:DataSource id="ds" appid="am" viewobject="Audios1View" rangesize="3"/>
<jbo:EmbedAudio helperapp="QuickTimePlayer" datasource="ds"

mediaattr="Clip" whereclause="id = 2" />
To render the content in your own way
The following sample displays an image. When the mouse moves over the image, the text "vacation photo"
will be displayed on the status bar of the browser.
<jbo:ApplicationModule id="am" configname="images.ImagesModule.ImagesModuleLocal"

<jbo:DataSource id="ds" appid="am" viewobject="Images1View" rangesize="3"/>
<jbo:MediaUrl id="urlBuilder" datasource="ds" mediaattr="Pic"

whereclause="id = 15" >
<IMG SRC="<%= urlBuilder.getOrdDomainURL() %>"
ALT="vacation photo." onMouseover="window.status='vacation photo'; return true" >
</jbo:MediaUrl>
To insert an image to a new row
The following two JSP sample pages show how to insert an image to a new row.
first.jsp
<form ACTION="second.jsp" METHOD="POST" ENCTYPE="multipart/form-data">

pic id: <INPUT TYPE=TEXT NAME="Id"><br>
pic: <INPUT TYPE=FILE NAME="Pic"><br>
<input type="submit" text="submit">
</form>
second.jsp

<jbo:ApplicationModule configname="images.ImagesModule.ImagesModuleLocal"
4-125
id="AlbumModule" username="scott" password="tiger"
<jbo:DataSource id="second" appid="AlbumModule" viewobject="Images1View" >

</jbo:DataSource>
<jbo:Row id="setdata" datasource="second" action="Create" >

<jbo:SetAttribute dataitem="*" usemultipartformat="yes" />
<jbo:EmbedImage datasource="second" mediaattr="Pic" />
</jbo:Row>
<jbo:Commit appid="AlbumModule" />

To update an image in an existing row
The first JSP file contains:
<form ACTION="second.jsp" METHOD="POST" ENCTYPE="multipart/form-data">

pic id: <INPUT TYPE=TEXT NAME="Id"><br>
pic: <INPUT TYPE=FILE NAME="Pic"><br>
<input type="submit"
text="submit">
</form>
The second JSP file contains these data tags:
<%@ page import="oracle.jbo.html.HtmlServices" %>

<%@ page import="oracle.jbo.html.RequestParameters" %>

<jbo:ApplicationModule configname="images.ImagesModule.ImagesModuleLocal"
id="AlbumModule" username="scott" password="tiger" releasemode="Stateless" />
<jbo:DataSource id="second" appid="AlbumModule" viewobject="Images1View"

whereclause="<%= \"id = \" +
((RequestParameters)HtmlServices.getRequestParameters(pageContext)).getParameter(\"Id\")
%>" >
</jbo:DataSource>
<jbo:RowsetNavigate datasource="second" action="First" />
<jbo:Row id="setdata" datasource="second" action="Current" >

<jbo:SetAttribute dataitem="*" usemultipartformat="yes" />
<jbo:EmbedImage datasource="second" mediaattr="Pic" />
</jbo:Row>
<jbo:Commit appid="AlbumModule" />

4-126
Locating a Row Using Data Tags
This topic covers the row-seeking functionality provided by the BC4J runtime and how the BC4J Data Tags
work with it. The BC4J Data Tags provide a number of ways to navigate a BC4J view object:
● You can use the RowsetNavigate data tag to navigate to First, Next, Previous and Last rows.
● In certain application scenarios it’s necessary to jump to a particular record based on a URL.
Generating a URL that contains the Row Key
A row key is a unique identifier for a Row within a Rowset. The key is an opaque object that can later be
used to retrieve the row within the Rowset. In the following snippet, the RowsetIterate tag is used to iterate
over all the rows in a Rowset (defined by the DataSource data tag).
<jbo:ApplicationModule configname="myPackage.MyPackageModule.MyPackageModuleLocal"
id="MyPackageModule" releasemode="Stateful" />
<jbo:DataSource id="dsMaster" appid="MyPackageModule"

viewobject="DeptView">
</jbo:DataSource>
<table border="1">
<jbo:RowsetIterate datasource="dsMaster" >
<TR>
<TD><a href="detail.jsp?RowKeyValue=<jbo:ShowValue datasource='dsMaster'
dataitem='RowKey'/>">See this record</a>
</TD>
<TD>Department Name:</TD>
<TD><jbo:ShowValue datasource="dsMaster" dataitem="Dname">
</jbo:ShowValue>
</TD>
</TR>
</table>
The important part of the master page is in the HREF with ShowValue tag:
<a href="submit.jsp?RowKeyValue=<jbo:ShowValue datasource='dsMaster'

dataitem='RowKey'/>">See this record</a>
Generates the anchor for invoking submit.jsp and passes in the RowKeyValue HTTP parameter (you can
choose any name for "RowKeyValue" specific to your application). The code uses the ShowValue tag to
render the string representation of the row id using the special attribute value RowKey.
Locating a Row based on the Row Key HTTP parameter
4-127
In the detail page, you use the RowKeyValue HTTP parameter in order to locate the row that was clicked on
the master page. You will use the Row tag for this purpose. This tag will automatically find the right row
based on the name of an HTTP parameter that contains the key value. Here is the syntax of the detail page:
<jbo:ApplicationModule configname="myPackage.MyPackageModule.MyPackageModuleLocal"
id="MyPackageModule" releasemode="Stateless" />
<jbo:DataSource id="dsMaster" appid="MyPackageModule" viewobject="DeptView" >

</jbo:DataSource>
<jbo:RefreshDataSource datasource="dsMaster" />
<jbo:Row id="masterRow" datasource="dsMaster" action="Find" rowkeyparam="RowKeyValue" >

</jbo:Row>
<jbo:DataSource id="dsDetail" appid="Package17Module" viewobject="EmpView" >

</jbo:DataSource>
<h2>Employees for Department: <jbo:ShowValue datasource="dsMaster"

dataitem="Dname" >
</jbo:ShowValue>
</h2>
<table border="1">
<jbo:RowsetIterate datasource="dsDetail" >
<TR>
<TD>Employee Name</a>
</TD>
<TD><jbo:ShowValue datasource="dsDetail" dataitem="Ename">
</jbo:ShowValue>
</TD>
</TR>
</table>
The important part of the receiving page is in the Row tag:

</jbo:Row>
This line does the work of locating the right row and setting the currency to point to it. You need to make
sure that your parameter names match up.
Note: If you are using the application module in Stateful release mode (default), you need to refresh the data
source prior to seeking the row using the row key. You can refresh the datasource by using:
4-128
The JSP page responsible for inserting a new row in a BC4J datasource can follow one of two
approaches. You can:
● Create the row in the insert JSP page and use BC4J Input data tags
OR
● Create the row in the submit JSP page but use static HTML form elements instead
If you create the row when the user displays the insert JSP page, your rendered JSP page
must pass two things through the HTTP request object to the submit page for processing:
● The HTTP parameter name-value pairs for the datasource row attributes being inserted
● The row key object to identify the datasource and row being inserted
If you create the row after the user sends the row data to the submit JSP page, you only need
to pass the HTTP parameter name-value pairs for the datasource row attributes being inserted
since no row exists from which to obtain a row key.
In general, to accomplish this for an application module instance and view object datasource,
you create two JSP page:
Insert JSP Page
1. When you want to insert a new row, decide whether you want to create a row to insert
when the user displays the insert page or create the row on the server processing-side
after the user submits the data.
2. Depending on where you decide to create the row, add either static HTML form elements
or the BC4J Input data tags inside an HTML <form> tag.
Note: The BC4J Input data tags will automatically render controls bound to default
attributes of a view object datasource; however, should the user display the insert page
but not send the data, the created row will remain in the datasource until the HTTP
session times out.
4-129
3. If you use the BC4J Input data tags (instead of static HTML form elements):
a. Add a BC4J Row tag with the Create action to create a new row in the datasource.
b. Add a hidden input element to your form and add the BC4J ShowValue data tag to
obtain a row key as input.
4. If you use static HTML form elements (instead of BC4J Input tags), be sure to specify the
exact name of the datasource row attribute to update in the form control's name attribute.
The names are case-sensitive.
Submit JSP Page
1. Add a BC4J Row data tag on the same datasource specified in the data input page and,
depending on where you decide to create the row, use either a Create action or an
Update action.
The Create action requires you to process the HTTP request object using the BC4J
SetAttribute data tag; whereas, the Update action will allow the Row data tag to process
the HTTP request object without the SetAttribute data tag.
2. Add BC4J Post and/or Commit data tags to apply the changes made on the datasource
to the database.
The application module object, which the JSP pages access during the update task, should be
accessed in reserved mode until the submit JSP page completes the update. The releasemode
attribute of the BC4J ApplicationModule data tag that you add to your JSP page controls this
behavior.
Related topics
About Creating Rows Using BC4J Data Tag

4-130
The JSP page responsible for updating a row in a BC4J datasource must post two things
through the HTTP request object to the submit page for processing:
● The HTTP parameter name-value pairs for the datasource row attributes being edited
● The row key object to identify the datasource and row being edited
To accomplish this for an application module instance and view object datasource, you create
two JSP page with these BC4J data tags:
Edit JSP Page
1. When you want to edit an existing row, add JSP scriptlet code to pass the desired rowset
browse action (First, Next, Previous, or Last) to the RowsetNavigate data tag.
2. Add the desired BC4J Input data tags to an HTML form element. The data tags will
render form elements bound to specified attributes of a view object datasource.
3. Add a hidden input element to your form and add the BC4J ShowValue data tag to obtain
a row key as input.
Submit JSP Page
1. Add a BC4J Row data tag using the Update action to process the HTTP request object
on the same datasource specified in the data input page.
2. Add BC4J Post and/or Commit data tags to apply the changes made on the datasource
to the database.
The application module object, which the JSP pages access during the update task, should be
accessed in stateful mode until the submit JSP page completes the update. The releasemode
attribute of the BC4J ApplicationModule data tag that you add to both JSP pages controls this
behavior.
4-131
Related topics

4-132
Handling Database Transactions
Data bound BC4J JSP pages that you design with BC4J Data Tags require that you initiate
post or commit operations on the database when the user modifies data. Only JSP pages that
release the application module resource in stateless mode automatically post and commit data.
When you specify JSP pages that use the stateful or reserved mode, you must handle the
database transaction yourself.
In order to apply row updates from the datasource to the database, you can either post or
commit the changes using these data tags:
● <jbo:PostChanges />
● <jbo:Commit />
You can use this tag to prevent changes from being saved to the database:
● <jbo:Rollback/>
Posting the changes does not permanently update the database; permanently entering data is
only performed by commiting. You can use the post operation in order to synchronize changes
to the datasource with the database. This typically occurs when your application permits users
to update the same datasource multiple times to complete a given activity. By posting after
each row update, you will ensure that any changed data is visible to the user's datasource and
any other datasource that uses the sample application module. If the user exits the form, all the
posted changes can still be rolled back, and thus prevented from being saved in the database.
Or, when the user completes the activity on the single datasource and approves their changes,
the application can commit the changes to the database.
If your application posts data from the datasource, be sure to eventually either rollback or
commit the changes to the database. You do this by including these data tags after the Row
data tag:
<jbo:PostChanges appid="myappmodule"/>
<jbo:Commit appid="myappmodule"/>
4-133
Working with BC4J Component Tags
Component tags belong to the BC4J Data Tags custom tag library. The components tags
function much like the other BC4J data tags in that they operate on a Business Components
datasource to access and manipulate data from the database. The component tags differ in
that they provide prebuilt functionality much like a web bean does. For more details, see About
BC4J Component Tags.
You work with component tags in this way:
● Add BC4J component tags to your JSP page
● Customize BC4J component tags
Related topics

About JSP Tags
4-134
1. If the Component Palette is not visible in JDeveloper, choose View | Component Palette
to open the Component Palette.
2. In the Navigator, right-click a JSP file and choose Code Editor.
4. Choose the BC4J Component Tags page from the Component Palette dropdown list.
For a complete list of the BC4J component tags, see Reference: BC4J Data Tags.

tag instead
Related topics
About BC4J JSP Tags

4-135
Each component tag in the BC4J Data Tags custom tag library has an associated .jsp file that
implements the behavior of the actual component tag you insert into a JSP page. For example,
when you insert the component tag <jbo:DataTable>, JDeveloper adds the file
DataTableComponent.jsp to your project.
When you want to customize the behavior of a component tag, you need to rename and
customize the component implementation .jsp file that corresponds to the component tag. To
accomplish this, JDeveloper makes it easy to add renamed component implementation files to
your project through the attribute dialog of each component tag. After you have created a
custom component implementation .jsp file, future component tags that you insert into a JSP
page can reference this file.
To customize the behavior of a BC4J component tag:
1. Open any JSP file into which you can insert a component tag.
2. In the BC4J Component Tags page of the Component Palette, click the component tag
whose implementation .jsp file you want to customize.
3. In the attribute dialog, edit the name shown in the attribute relativeUrlPath to create a
new component implementation .jsp file. You can specify a relative path to an existing
subdirectory in the project directory site (in the mywork folder) to save your custom
component .jsp files there.
For example, to create the custom component implementation file

MyDataTableComponent.jsp in a subdirectory of the site folder called components, then
the value of relativeUrlPath would be /components/MyDataTableComponent.jsp.
4. Click Ok to insert the component tag to your open JSP file. JDeveloper adds the
renamed component implementation .jsp file to your project folder. Open the new file in
JDeveloper and customize it as desired.
You can delete the inserted component tag in the open JSP file or you leave it there,
where it references the new component implementation .jsp file as described below.
To reference a custom component implementation .jsp file in a component tag:
1. Open the JSP file into which you want to insert a component tag with a custom
implementation .jsp file reference.
4-136
2. In the BC4J Component Tags page of the Component Palette, click the desired
component tag.
3. In the attribute dialog, edit the name shown in the attribute relativeUrlPath to the name of
the previously created custom component implementation .jsp file. If you have saved
your custom component .jsp files in a subdirectory of the project directory site (in your
mywork folder), then you must supply a relative path for the component .jsp file.
For example, to reference the custom component implementation .jsp file

MyDataTableComponent.jsp in a subdirectory of the site folder called components, then
the value of relativeUrlPath would be /components/MyDataTableComponent.jsp.
Related topics
About BC4J JSP Tags
4-137
JDeveloper lets you create JSP pages that use your own custom web beans or available web
beans. You insert web beans into your JSP using the <jbo:DataWebBean/> or <jbo:WebBean/>
data tags from the BC4J Data Tags custom tag library:
● Adding web bean tags to a JSP page
● Working with custom web beans
Related topics
About Web Beans
Reference: Web Bean Classes
4-138
Adding Web Bean Tags to a BC4J JSP Page
1. Create a JSP file and open the JSP file in a viewer window within JDeveloper.
2. Click the position in the source code where you want to insert the web bean.
The insertion point you choose must be before the </BODY> tag.
3. Select the BC4J Web Beans page from the Component Palette.
4. Click the desired BC4J data tag depending on whether you want to work with a data web
bean (bound to BC4J datasource) or an HTML web bean.
5. In the web bean dialog, select the web bean to insert and click Next.
6. Enter the data tag properties in the attribute dialog and click Finish.
For details about each web bean, see the JavaDoc in the oracle.jbo.html.webbeans
package.
Related topics
About Web Beans

DataWebBean data tag
WebBean data tag
4-139
Creating a Custom Web Bean
In addition to JDeveloper's provided web beans, you can also create your own custom web
beans. This topic describes how to create a web bean using the Web Bean Wizard.
Note: If you have an existing web bean file with a syntax error and you attempt to subclass it as
another web bean, JDeveloper will not permit you to save the file. In this case, you will receive a
parse error in JDeveloper unless you web bean is a well-formed class.
To open the Web Bean Wizard:
2. Select the Web Objects folder.
3. Double-click the Web Bean icon in the Items list. The Web Bean Wizard opens.
4. Follow the Web Bean Wizard to create the web bean.
For detailed help in using the Web Bean Wizard, press F1 or click Help from within the
wizard.
When you finish the Web Bean Wizard, it generates the code for your new web bean class. If
you create a data web bean, the code includes sample HTML-rendering code and supports
connection to a data source.
You should use the Web Object Manager to expose the web bean's properties before you
inserting it in a JSP page.
This procedure assumes that you are subclassing a web bean that has already been registered
with the Web Object Manager. The JDeveloper-provided web beans are all registered; to
register a web bean, see exposing a custom web bean's properties below.
To create a web bean as a subclass of an existing web bean:
1. Choose Tools | Web Object Manager.
2. In the Web Object Manager, open either the Data Web Beans or the Web Beans folder,
depending on whether or not you are subclassing a data web bean.
4-140
3. Select the web bean you want to subclass.
4. Click SubClass.
5. In the Package field, enter a package for your new web bean. Alternately, click Browse
to browse for a package.
6. In the Class Name field, enter the class name for your new web bean.
7. In the Web Bean Name field, enter the registered name for your web bean.
This is the name the Web Object Manager will use to describe your web bean.
Your new web bean will start out registered with exactly the same properties as its parent. If
you want to add or alter these properties, you must expose the web bean properties using the
Web Object Manager.
Only some of the properties of a web bean are exposed to JSPs that include it. When you
create a new web bean, only the id and scope properties are exposed. You can add new
properties to a web bean, just as you can add new properties to any JavaBean. You can
expose these new properties or unexposed predefined properties with the Web Object
Manager.
To expose a web bean's properties:
1. Choose Tools | Web Object Manager.
2. Open the Data Web Beans or Web Beans folder, depending on whether or not your web
bean is a data web bean.
3. Select your web bean.
4. Click Edit.
5. Select the Properties tab.

6. Click Add.
7. Select the properties you want to add.

8. Click OK.
4-141
To edit an exposed property of a web bean:
1. Still in the Web Object Manager Properties tab, select the property you want to edit.
2. Click Edit.
3. To force a JSP to provide a value for the property when it calls the web bean, select
Requires a value.
4. To require the specification of the value to be enclosed in quotation marks, select Needs
to be quoted.
5. To give the property a default value, enter the value in the Default value field.
6. To limit the range of legal values, select User must select from the following options
and enter the list of legal values, separated by spaces.
Related topics
About Web Beans
4-142
Library Syntax
Syntax usage:
Tag attributes shown in italic font may use runtime expressions. Tag attributes in square
brackets ([]) are not required. The tag body, when used, is indicated by the type content the tag
accepts (JSP content).
Tag Groupings
BC4J Component Tags

BC4J Connections
BC4J Data Access
BC4J Events
BC4J Forms
BC4J interMedia
BC4J Web Beans
BC4J Component Tags

Name Syntax
<jbo:DataEdit
DataEdit - A component tag that displays a form to edit a datasource
record bound to a datasource. [targetURL]
[relativeUrlPath] />
<jbo:DataHandler
DataHandler - A component tag that handles JSP business
appid
component-specific events. [relativeUrlPath] />
<jbo:DataNavigate
DataNavigate - A component tag that displays a navigation datasource
bar bound to a datasource. [targetURL]
4-143
<jbo:DataQuery
DataQuery - A component tag that performs a search on a datasource
datasource. [targetURL]
<jbo:DataRecord
DataRecord - A component tag that displays a single record
datasource
bound to a datasource.
<jbo:DataScroller
DataScroller - A component tag that displays a record scroller datasource
bound to a datasource. [targetURL]
<jbo:DataTable
DataTable - A component tag that displays a table bound to a datasource
datasource. [edittarget]
<jbo:DataTransaction
DataTransaction - A component tag that renders database
appid
transaction operations.
[targetURL] />
BC4J Connections
Name Syntax
<jbo:ApplicationModule
id
[definition]
ApplicationModule - Creates an application [configname]
module instance to service HTTP requests and [username]
determines how the session cookie releases the [password]
application module.
[lock]
[waittimeout]
[releasemode] />
Commit - Applies changes made on a datasource <jbo:Commit
to the database. appid />
<jbo:CreateViewObject
CreateViewObject - Creates a dynamic view appid
object from a business components application name
module. [rangesize] > JSP content
</jbo:CreateViewObject>
4-144
<jbo:DataSource
id
appid
viewobject
DataSource - Creates a JSP page datasource
[whereclause]
based on a view object.
[orderbyclause]
[rangesize]
[forwardonly] > JSP content
</jbo:DataSource>
<jbo:DataSourceRef
DataSourceRef - Creates a datasource variable id
based on a datasource. reference > JSP content
</jbo:DataSourceRef>
PostChanges - Posts changes made on a <jbo:PostChanges
datasource to the database. appid />
RefreshDataSource - Reexecutes a datasource's <jbo:RefreshDataSource
data from the database. datasource />
ReleasePageResources - Provides a marker for <jbo:ReleasePageResources
the JSP page that triggers the release of the [releasemode]
application module instance. This tag must appear
[appid] />
at the end of a data bound BC4J JSP page.
RollBack - Prevents current datasource changes <jbo:RollBack
from entering into the database. appid />
BC4J Data Access

Name Syntax
<jbo:AttributeIterate
id
datasource
AttributeIterate - Iterates through the
[displayattributes]
datasource attribute definition.
[hideattributes]
[queriableonly] > JSP content
<jbo:Criteria
Criteria - Sets a WHERE-clause value defining
dataitem
criteria on a criteria row.
value />
<jbo:CriteriaRow
id
CriteriaRow - Sets a WHERE-clause defining [index]
criteria row on a view criteria. [uppercolumns]
[clearall] > JSP content
</jbo:CriteriaRow>
4-145
<jbo:ExecuteSQL
ExecuteSQL - Executes a SQL statement
appid > tagdependent content
using the application's database connection. </jbo:ExecuteSQL>
<jbo:RenderValue
RenderValue - Displays an attribute using a [datasource]
field renderer. [dataitem] > JSP content
</jbo:RenderValue>
<jbo:Row
id
datasource
Row - Retrieves a row instance and performs
action
an operation on the row.
[rowkeyparam]
[rowkey] > JSP content
</jbo:Row>
<jbo:RowsetIterate
datasource
RowsetIterate - Iterates through the rows of
[changecurrentrow]
the specified datasource.
[userange] > JSP content
<jbo:RowsetNavigate
RowsetNavigate - Moves the currency or the
datasource
viewing range of a datasource.
[action] />
<jbo:SetAttribute
[datasource]
SetAttribute - Updates an attribute in a row. [dataitem]
[value]
[usemultipartformat] />
<jbo:ShowCriteria
ShowCriteria - Displays the criteria of a
[dataitem] > tagdependent
dataitem in a criteria row. content </jbo:ShowCriteria>
<jbo:ShowDefinition
[datasource]
ShowDefinition - Displays the metadata of an
[dataitem]
attribute.
definition > tagdependent
content </jbo:ShowDefinition>
<jbo:ShowHint
[datasource]
ShowHint - Displays available UI hints of an
[dataitem]
attribute.
hintname > tagdependent content
</jbo:ShowHint>
4-146
<jbo:ShowValue
ShowValue - Displays an attribute value [datasource]
without using a field renderer. [dataitem] > tagdependent
content </jbo:ShowValue>
<jbo:ViewCriteria
id
ViewCriteria - Sets a search view criteria on a
datasource
datasource.
[action] > JSP content
</jbo:ViewCriteria>
<jbo:ViewCriteriaIterate
ViewCriteriaIterate - Iterates through all the
datasource > JSP content
criteria rows of a view criteria. </jbo:ViewCriteriaIterate>
BC4J Events
Name Syntax
<jbo:FormEvent
FormEvent - Adds a JSP event to the request event
object of the submitting page's HTML FORM [datasource]
element. [viewobject]
[addrowkey] />
<jbo:OnEvent
[name]
OnEvent - Handles a JSP event submitted by
[list]
the <jbo:UrlEvent> or <jbo:FormEvent> data
[datasource]
tags.
[viewobject] > JSP content
</jbo:OnEvent>
<jbo:UrlEvent
[targeturl]
[targeturlparam]
UrlEvent - A convenience tag that constructs a event
URL to submit an event. [datasource]
[viewobject]
[addrowkey]
[extraparameters] />
BC4J Forms
Name Syntax
4-147
<jbo:InputDate
[datasource]
InputDate - Inserts an Input date field into a [dataitem]
page. formname
[readonly] > JSP content
</jbo:InputDate>
<jbo:InputHidden
InputHidden - Inserts a hidden Input field into a [datasource]
page. [dataitem] > JSP content
</jbo:InputHidden>
<jbo:InputPassword
[datasource]
InputPassword - Inserts a password Input field [dataitem]
into a page. [cols]
[maxlength] > JSP content
</jbo:InputPassword>
<jbo:InputRender
[datasource]
InputRender - Inserts an Input field with a field
[dataitem]
render into a page.
[formname] > JSP content
</jbo:InputRender>
<jbo:InputSelect
[multiple]
[datasource]
InputSelect - Inserts an Input field that supports [dataitem]
single or multiple selections into a page. displaydatasource
displaydataitem
displayvaluedataitem > JSP
content </jbo:InputSelect>
[multiple]
[datasource]
InputSelectGroup - Inserts an Input field group [dataitem]
(radio button or checkbox) into a page. displaydatasource
displaydataitem
displayvaluedataitem > JSP
content </jbo:InputSelectGroup>
4-148
<jbo:InputSelectLOV
[datasource]
[dataitem]
InputSelectLOV - Inserts an List Of Values displaydatasource
Input field into a page. displaydataitem
displayvaluedataitem
formname > JSP content
</jbo:InputSelectLOV>
<jbo:InputText
[datasource]
[dataitem]
InputText - Inserts an Input field into a page. [cols]
[maxlength]
</jbo:InputText>
<jbo:InputTextArea
[datasource]
[dataitem]
InputTextArea - Inserts a multi-line Input field
[rows]
into a page.
[cols]
</jbo:InputTextArea>
<jbo:SetDomainRenderer
domain
SetDomainRenderer - Overwrites the field
classname
renderer for attributes of the same domain.
fieldtype
scope />
<jbo:SetFieldRenderer
[datasource]
SetFieldRenderer - Overwrites the field
[dataitem]
renderer defined for a dataitem.
fieldtype
classname />
<jbo:SetHtmlAttribute
SetHtmlAttribute - Adds HTML attributes to a
name
BC4J Input tag.
[value] />
BC4J interMedia
Name Syntax
4-149
<jbo:AnchorMedia
datasource
mediaattr
AnchorMedia - Inserts a HTML Anchor tag for
[rowkey]
an interMedia object to a page.
[whereclause]
[retrievepath] > JSP content
</jbo:AnchorMedia>
<jbo:EmbedAudio
datasource
mediaattr
[rowkey]
[whereclause]
[retrievepath]
[width]
EmbedAudio - Inserts a HTML OBJECT tag for [height]
an interMedia ORDAUDIO object to a page. [alt]
[altattr]
[title]
[helperapp]
[showcontrols]
[autoplay]
[loop]
[standby] />
<jbo:EmbedImage
datasource
mediaattr
[rowkey]
[whereclause]
[retrievepath]
EmbedImage - Inserts a HTML IMAGE tag for
[width]
an interMedia ORDIMAGE object to a page.
[height]
[border]
[align]
[alt]
[altattr]
[longdesc] />
4-150
<jbo:EmbedVideo
datasource
mediaattr
[rowkey]
[whereclause]
[retrievepath]
[width]
EmbedVideo - Inserts a HTML OBJECT tag for [height]
an interMedia ORDVideo object to a page. [alt]
[altattr]
[title]
[helperapp]
[showcontrols]
[autoplay]
[loop]
[standby] />
<jbo:FileUploadForm
FileUploadForm - Inserts a HTML FORM tag
action > JSP content
for file upload. </jbo:FileUploadForm>
<jbo:MediaUrl
id
datasource
MediaUrl - Inserts a URL string for an mediaattr
interMedia object to a page. [rowkey]
[whereclause]
[retrievepath] > JSP content
</jbo:MediaUrl>
BC4J Web Beans

Name Syntax
<jbo:DataWebBean
id
DataWebBean - A tag to use a data web bean
datasource
in your JSP.
wbclass > JSP content
</jbo:DataWebBean>
<jbo:WebBean
WebBean - A tag to use a web bean in your id
JSP. wbclass > JSP content
</jbo:WebBean>
4-151
Reference: Web Beans
JDeveloper provides a set of JSP 1.1 compliant web-enabled JavaBeans known as web beans.
In JDeveloper, there are two types of web beans:
● Data web beans that you use to access and manipulate Business Components for Java
(BC4J) datasources
● HTML web beans that are not data bound, but allow you to output HTML directly from the
bean
In JDeveloper you insert web beans into your JSP files using the <jbo:DataWebBean/> or
<jbo:WebBean/> data tags from the BC4J Data Tags custom tag library.
Related topics
About Web Beans

4-152
Web Bean Classes
When you want to create a JSP page that produces dynamic HTML using non-data bound web
beans, insert any of these web beans into your JSP page using the <jbo:WebBean/> data tag
from the BC4J Data Tags custom tag library:
● Toolbar web bean
● TableControl web bean
● EditForm web bean
Related topics
About Web Beans

4-153
Data Web Bean Classes
When you want to create a JSP page that let users navigate through query results represented
by a view object you select from your Business Components project, insert any of these web
beans into your JSP page using the <jbo:DataWebBean/> data tag from the BC4J Data Tags
custom tag library:
● NavigatorBar web bean
● FindForm web bean
When you want to create JSP pages that display query results, you can bind any of these data
web beans to a view object defined in an existing Business Components project:
● RowSetBrowser web bean
● EditCurrentRecord web bean
● ViewCurrentRecord web bean
● RowSetNavigator web bean
● Chart web bean
● XMLDataGenerator web bean
Related topics
About Web Beans

4-154
Working with OJSP Tag Libraries in JDeveloper
JDeveloper includes JSP tag libraries supplied with the OC4J JSP container that are
implemented according to industry standards and are generally portable to other JSP or servlet
environments:
● Working with JESI tags for Edge Side Includes in order to work with Edge Side Includes
for Web caching.
● Working with Web Object Cache Tags in order to capture, store, reuse, post-process,
and maintain the partial and intermediate results generated by a dynamic Web page.
● Working with Data-Access tags in order to access the Oracle9i database or middle-tier
database cache.
● Working with JSP Utility tags in order to send email, upload and download files, use
EJBs, and use miscellaneous utilities.
● Working with XML and XSL tags in order to specify that all or part of a JSP page should
be transformed through an XSL stylesheet, to perform caching, perform SQL operations,
or take XML objects as input or send them as output.
Related topics
About JSP Tags

About Oracle Caching Support for Web Applications
About Data-Access Tags
About JSP Utility Tags
About Integration with XML and XSQL
Reference: OC4J JESI Tag Library

Reference: OC4J Web Object Cache Tag Library
Reference: OC4J Data-Access Tag Library
Reference: OC4J EMail Tag Library
Reference: OC4J File Access Tag Library
Reference: OC4J EJB Tag Library
Reference: OC4J Utility Tag Library
Reference: OC4J XML Tag Library
4-155
About Oracle Caching Support for Web
Applications
This topic provides the following information:
● an introduction to caching features supported by the Oracle9i Application Server in

general and the OC4J JSP container in particular
● a discussion of the role of the OC4J Web Object Cache in relation to other Oracle9i
Application Server caching components
● a summary of the tag libraries relating to caching features
Oracle9i Application Server and JSP Caching Features
The Oracle9i Application Server and OC4J provide the following caching features:
● Oracle9iAS Web Cache
This is an HTTP-level cache, maintained outside the application, providing very fast
cache operations. It is a pure, content-based cache, capable of caching static data (such
as HTML, GIF, or JPEG files) or dynamic data (such as servlet or JSP results). Given
that it exists as a flat content-based cache outside the application, it cannot cache
objects (such as Java objects or XML DOM objects) in a structured format. In addition, it
has relatively limited post-processing abilities on cached data.
The Oracle9iAS Web Cache provides an ESI processor to support Edge Side Includes,
an XML-style markup language that allows dynamic content assembly away from the
Web server. This technology allows you to break cacheable pages into separate cached
objects, as desired. OC4J supports this technology through its JESI tag library.
For additional information about the Oracle9iAS Web Cache, see the Oracle9iAS Web
Cache Administration and Deployment Guide.
● OC4J Web Object Cache
This is an application-level cache, embedded and maintained within a Java Web

application. It is a hybrid cache, both Web-based and object-based. A custom tag library
4-156
or API allows you to define page fragment boundaries and to capture, store, reuse,
process, and manage the intermediate and partial execution results of JSP pages and
servlets as cached objects. Each block can produce its own resulting cache object. The
produced objects can be HTML or XML text fragments, XML DOM objects, or Java
serializable objects. These objects can be cached conveniently in association with HTTP
semantics. Alternatively, they can be reused outside HTTP, such as in outputting cached
XML objects through Simple Mail Transfer Protocol (SMTP), Java Messaging Service
(JMS), Advanced Queueing (AQ), or Simple Object Access Protocol (SOAP).
● Oracle9i Application Server Java Object Cache
The Oracle9i Application Server Java Object Cache is a general-use cache to manage
Java objects within a process, across processes, and on local disk. By managing local
copies of objects that are difficult or expensive to retrieve or create, the Java Object
Cache significantly improves server performance. By default, the OC4J Web Object
Cache uses the Oracle9i Application Server Java Object Cache as its underlying cache
repository.
Role of the JSP Web Object Cache
It is important to understand the role of the OC4J Web Object Cache in the overall setup of a
Web application. It works at the Java level and is closely integrated with the HTTP environment
of servlet and JSP applications. By contrast, the Oracle9i Application Server Java Object
Cache works at the Java object level, but is not integrated with HTTP. As for the Oracle9iAS
Web Cache, it is well integrated with HTTP and is an order of magnitude faster than the Web
Object Cache, but it does not operate at the Java level. For example, it cannot apply a
stylesheet to a cached DOM object or reuse the cached result in other protocols.
The Web Object Cache is not intended for use as the main Web cache for an application. It is
an auxiliary cache embedded within the same Java virtual machine that is running your servlets
and JSP pages. Because the retrieval path for cached results in the Web Object Cache
includes the JVM and the JSP and servlet engines, it generally takes much longer to serve a
page from the Web Object Cache compared to the Oracle9iAS Web Cache.
The Web Object Cache does not replace or eliminate the need for either the Oracle9iAS Web
Cache or the Oracle9i Application Server Java Object Cache--it is a complementary caching
component in the overall framework of a Web application and should be used together with the
other caching products, as appropriate. In fact, the Web Object Cache uses the Java Object
Cache as its default repository. And through combined use of the OC4J JESI tags and Web
Object Cache tags, you can use the Web Object Cache and Oracle9iAS Web Cache together
in the same page.
4-157
Web Object Cache Versus Oracle9iAS Web Cache
You can think of the Oracle9iAS Web Cache as the primary caching component. It serves
cached pages directly to HTTP clients and can handle large volumes of HTTP traffic quickly,
fitting the requirements of most Web sites. You can use the Oracle9iAS Web Cache to store
complete Web pages or partial pages (through use of the JESI tags). Cached pages can be
customized, to a certain extent, before being sent to a client, including cookie-replacement and
page fragment concatenation, for example.
It is advisable to use the Oracle9iAS Web Cache as much as possible to reduce the load on the
Web application server and back-end database. The caching needs of a large percentage of
Web pages can be addressed by the Oracle9iAS Web Cache alone.
As a complement to the Oracle9iAS Web Cache, you can use the Web Object Cache to
capture intermediate results of JSP and servlet execution, and subsequently reuse these
cached results in other parts of the Java application logic. It is not beneficial to use the Web
Object Cache in your Web application unless you are doing a significant amount of post-
processing on cached objects between the time they are cached and the time they are served
to a client.
Web Object Cache Versus Oracle9i Application Server Java Object Cache
In comparison to the Oracle9i Application Server Java Object Cache, the Web Object Cache
makes it much easier to store and maintain partial execution results in dynamic Web pages.
The Java Object Cache, being a pure object-based framework for any general Java application,
is not aware of the HTTP environment in which it may be embedded. For example, it does not
directly depend on HTTP cookies or sessions. When you directly use the Java Object Cache
within a Web application, you are responsible for creating any necessary interfacing. The Java
Object Cache does not provide a way to specify maintenance policies declaratively.
Summary of JESI Tag Library
OC4J provides the JESI tag library as a convenient interface to ESI tags and Edge Side
Includes functionality for Web caching. Developers have the option of using ESI tags directly in
any Web application, but JESI tags provide additional convenience in a JSP environment.
Summary of Web Object Cache Tag Library
The OC4J Web Object Cache is a mechanism that allows Web applications written in Java to
capture, store, reuse, post-process, and maintain the partial and intermediate results generated
4-158
by a dynamic Web page, such as a JSP or servlet. For programming interfaces, it provides a
tag library (for use in JSP pages) and a Java API (for use in servlets).
4-159
Working with JESI Tags for Edge Side Includes
This chapter describes the JESI (JSP to ESI) tag library that is supplied with OC4J. These
portable tags are layered on top of an Edge Side Includes (ESI) framework available in the
Oracle9iAS Web Cache to provide ESI caching functionality in a JSP application.
The chapter includes the following topics:
● Overview of Edge Side Includes Technology and Processing

● Overview of JESI Functionality
● Oracle JESI Tag Descriptions
Overview of Edge Side Includes Technology and Processing
This section provides background information about some of the underlying technology upon
which the Oracle JESI tags are based.
JESI tags, which are used to break down dynamic content of JSP pages into cacheable
components, are based upon the Edge Side Includes architecture and ESI markup language.
Although the use of JESI tags is not dependent upon any particular ESI processor or caching
system, it is reasonable to assume that most Oracle customers would use the Oracle9iAS Web
Cache and its ESI processor.
This section covers the following topics:
● Edge Side Includes Technology

● Oracle9iAS Web Cache and ESI Processor
This discussion provides only a brief overview of the ESI architecture and language. For additional
information about ESI technology, refer to the following Web site:
http://www.edge-delivery.org
Edge Side Includes Technology
4-160
This section introduces the features of ESI technology and the concept of ESI "surrogates".
Introduction to ESI
Edge Side Includes is an XML-style markup language that allows dynamic content assembly away
from the origin Web server--at the "edge" of the network--and is designed to take advantage of
available tools such as Web caches and content delivery networks (CDNs) to improve
performance for end users.
ESI provides a means of reducing the load on Web and application servers by promoting
processing on intermediaries, known as surrogates or reverse proxies, that understand the ESI
language and act on behalf of the Web server. ESI content is intended for processing somewhere
between the time it leaves the originating Web server and the time it is displayed in the end user's
browser. A surrogate is commanded through HTTP headers. Such a surrogate can be referred to
as an "ESI processor" and may be included as part of the functionality of a Web cache.
ESI lends itself to a partial-page caching methodology, where each dynamic portion of a Web
page can be cached individually and retrieved separately and appropriately.
Using the ESI markup tags, a developer can define aggregate Web pages and the cacheable
components that are to be retrieved and assembled, as appropriate, by the ESI processor for
viewing in the HTTP client. You can think of an aggregate page, which is the resource associated
with the URL that an end user specifies, as simply a container for assembly, including retrieval and
assembly instructions that are specified through the ESI tags.
Note:
Bear in mind that a JESI user does not have to (and would typically not want to) use ESI
tags directly. JESI tag handlers translate JESI tags to ESI tags behind the scenes.
More About Surrogates
Because surrogates act on behalf of Web servers, where page content is owned, they allow
content owners to have sufficient control over their behavior. In this way, they offer greater
potential for performance improvements than would otherwise be available.
The caching process in surrogates operates similarly to the caching process in HTTP in general,
using similar freshness and validation mechanisms as the foundation. However, surrogates also
possess additional control mechanisms.
Key ESI Features
4-161
Version 1.0 of the ESI language includes the following key areas of functionality:
● inclusion
An ESI processor assembles fragments of dynamic content, retrieved from the network, into
aggregate pages to output to the user. Each fragment can have its own meta data to control
its caching behavior.
● support of variables
ESI supports the use of variables based on HTTP request attributes. ESI statements can
use variables during processing or can output them directly into the processed markup.
● conditional processing
ESI allows use of boolean comparisons for conditional logic in determining how pages are
processed.
● error handling and alternative processing
Some ESI tags support specification of a default resource and/or an alternative resource,
such as an alternate Web page, if the primary resource cannot be found.
Oracle9iAS Web Cache and ESI Processor
This section introduces the Oracle9iAS Web Cache and its ESI processor. See the Oracle9iAS
Web Cache Administration and Deployment Guide for more information.
Introduction to Oracle9iAS Web Cache
Oracle offers Oracle9iAS Web Cache to help e-businesses manage Web site performance issues.
Oracle9iAS Web Cache is a content-aware server accelerator, or reverse proxy server, that
improves the performance, scalability, and availability of Web sites that run on the Oracle9i
Application Server.
By storing pages from frequently accessed URLs in memory, Oracle9iAS Web Cache eliminates
the need to repeatedly process requests for those URLs on the application Web server. Unlike
legacy proxy servers that handle only static documents, Oracle9iAS Web Cache caches both
4-162
static content and dynamically generated content from one or more application Web servers. As
the result of more frequent cache hits, Oracle9iAS Web Cache offers greater performance
enhancement than legacy proxies and greatly reduces the load on application servers.
Conceptually, the Oracle9iAS Web Cache is positioned in front of application Web servers,
caching their content and providing that content to Web browsers that request it. When Web
browsers access the Web site, they send HTTP protocol or HTTPS protocol requests to
Oracle9iAS Web Cache, which, in turn, acts as a virtual server for the application Web servers. If
the requested content has expired or been invalidated or is no longer accessible, Oracle9iAS Web
Cache retrieves the new content from the application Web servers. The application Web servers
may retrieve their content from an Oracle database.
Steps in Oracle9iAS Web Cache Usage
Here are the steps for typical browser interaction with Oracle9iAS Web Cache:
1. A browser sends a request to a company's Web site.
This request, in turn, generates a request to the Domain Name System (DNS) for the IP
address of the Web site.
2. DNS returns the IP address of Oracle9iAS Web Cache.

3. The browser sends the request for the Web page to Oracle9iAS Web Cache.
4. If the requested content is in its cache, Oracle9iAS Web Cache sends the content directly to
the browser. This is known as a cache hit.
5. If Oracle9iAS Web Cache does not have the requested content, or the content is stale or
invalid, then the Web cache hands off the request to the application Web server. This is
known as a cache miss.
6. The application Web server sends the content through Oracle9iAS Web Cache.
7. Oracle9iAS Web Cache sends the content to the client and makes a copy of the page in
cache.
Note:
A page that is stored in the cache is removed when it becomes invalid or outdated.
Oracle9iAS Web Cache ESI Processor
4-163
Oracle9iAS Web Cache includes an ESI processor to support the use of the Edge Side Includes
markup language in caching. (See "Edge Side Includes Technology".)
A Web developer in an Oracle9iAS Web Cache environment can use the ESI language directly in
his application; however, for JSP developers, there are a number of reasons to use the JESI tag
library that is provided as a convenient JSP interface to the ESI language. (See "Motivation for
JESI Tags".)
Overview of JESI Functionality
This section introduces JESI functionality and the Oracle implementation, covering the following
topics:
● Motivation for JESI Tags

● Overview of JESI Tags Implemented by Oracle
● JESI Usage Models
● Invalidation of Cached Objects
● Personalization of Cached Pages
You can access the proposed JESI specification at the following Web site:
http://www.edge-delivery.org
Motivation for JESI Tags
OC4J provides the JESI tag library as a convenient interface to ESI tags and Edge Side Includes
functionality for Web caching. Developers have the option of using ESI tags directly in any Web
application, but JESI tags provide additional convenience in a JSP environment. Here are the
main advantages in using JESI tags instead of using ESI tags directly:
● standard JSP framework and convenient features
For developers accustomed to using JSP pages or working in a JSP IDE environment, JESI
tags allow use of the familiar and convenient features of JSP programming. For example,
you can reference included pages by page-relative or application-relative syntax instead of
the complete URL or file path.
4-164
● JESI shortcut syntax
JESI tags support convenient syntax and tag attributes for specifying meta data information
(such as expiration for cached pages), explicitly invalidating pages as appropriate, and
personalizing pages using cookie information.
● application-level configuration files
The JESI tag library can use application-level configuration files for convenient specification
of deployment-time parameters and application default settings that are appropriate to a
particular environment. In this way, you can deploy to different environments that have
diverse needs and set appropriate defaults without changing application code.
For example, you can use such a configuration file to preset the cache server URL, user
name, and password for invalidation requests.
Overview of JESI Tags Implemented by Oracle
The Oracle JESI tag library, a standard JavaServer Pages tag library implementation, is included
in the ojsputil.jar file.
The Oracle implementation of JESI is layered on top of the standard ESI framework.
Because the JESI tag library is a standard implementation, note the following:
● You can use it in any standard JSP environment--it does not depend on the OC4J JSP
container.
● Even though this document discusses the Oracle9iAS Web Cache and its ESI processor in
particular, the JESI tag library does not depend on any particular caching environment and
can work with any ESI processor that conforms to the ESI 1.0 specification.
The Oracle JESI tag library supports the following tags:
● JESI control, JESI include, JESI template, and JESI fragment for page setup and
content
● JESI invalidate (and subtags) for explicit invalidation of cached objects when
appropriate
4-165
● JESI personalize for page personalization
Included with the tag library are the following:
● tag handler classes for these tags

● a standard tag library description file (TLD) for these tags
JSP developers use these tags (such as JESI include) instead of corresponding ESI tags (such
as esi:include). The usefulness and convenience of this is discussed previously, in "Motivation
for JESI Tags".
Note:
The Oracle JESI tag library is a standard library. For general information about the standard
JavaServer Pages tag library framework, refer to the Oracle9iAS Containers for J2EE
Support for JavaServer Pages Reference.
JESI Usage Models
There are two models for how to use JESI tags to define aggregate pages and their cacheable
components:
● the control/include model

● the template/fragment model
This section describes these models, and concludes with some special notes about the JESI
include tag.
Control/Include Model
4-166
One JESI tag approach is a modular one, typically bringing most (or all) cacheable content into the
aggregate page as included pages. Generally use this model as follows:
● Use the JESI control tag in the top-level page to set caching parameters for content
outside of the included content, if appropriate.
● Use JESI include tags to bring in dynamic content.
● Use a JESI control tag inside each included page to set caching parameters for those
pages, as appropriate.
This document refers to this modular approach as the control/include model. It is particularly
convenient in a situation where you are developing new pages.
Each included file is a distinct cacheable object (although caching may be disabled according to
tag settings), and any additional content in the aggregate page is also a distinct object.
Both tags are optional, depending on the situation. A page can have a JESI control tag without
any JESI include tags. In fact, this is a simple way to convert an existing page for JESI use.
There is also no requirement for a JESI control tag in a page that uses JESI include tags.
For any page, either top-level or included, that does not specify cacheability through a JESI
control tag, its cacheability depends on configuration settings of the ESI processor. This applies
if the page has no JESI control tag, or if it has a JESI control tag that does not set the cache
attribute.
Notes:
The JESI control tag in the aggregate page has no effect on included pages. An included
page without its own JESI control tag uses default cache settings.
See the following sections for tag syntax and examples:
● "JESI control Tag"

● "JESI include Tag"
● "Examples--Control/Include Model"
4-167
Template/Fragment Model
The other JESI tag approach is one where content is in the aggregate page itself, and you split the
page into separately cacheable fragments as desired. Use the JESI template tag to enclose the
aggregate of all cacheable content. This tag sets caching parameters for the aggregate page
outside the fragments. Use JESI fragment tags as desired to define fragments within the
aggregate, to be cached separately.
This document refers to this scenario as the template/fragment model. It is particularly convenient
in a situation where you are converting existing pages for JESI use. There can optionally be JESI
include tags as well, either at the template level or the fragment level.
The JESI template tag and JESI fragment tag are always used together. If you do not need
separate fragments in a page, use JESI control instead of JESI template.
Each fragment is a distinct cacheable object, and dynamic content at the template level, outside of
any fragments, is a distinct cacheable object. Any included page is also a distinct cacheable
object. The cacheability of the template code outside the fragments depends on the cache
attribute setting, if any, of the JESI template tag. The cacheability of any fragment depends on
the cache attribute setting, if any, of the JESI fragment tag. The cacheability of an included
page depends on the cache attribute setting of the JESI control tag (if any) within that page.
For any template, fragment, or included page that does not specify a cache attribute setting, its
cacheability depends on configuration settings of the ESI processor.
Because the template and fragments are independent cacheable objects, they may expire at
different points in time in the ESI processor. When a cache miss occurs or an object that has
expired is requested, the ESI processor will make a request to the origin server (OC4J in the case
of Oracle9iAS) for a fresh copy. If a requested object is a JESI template, the JSP engine will
execute the template code; that is, all code in the page that is outside any fragments. In output
generated by the JSP translator, the translator will also place ESI markup that designates where
all the fragments should be included. The code contained in the JESI fragments will not be
executed at that time.
When a fragment expires, the ESI processor will make a request to the origin server for that
particular fragment. In order to execute a fragment, the OC4J JSP container will execute the
template code (all code outside of the fragments) plus the code of the fragment being requested.
In the resulting page, there will be the output of the template, ESI markers for the inclusion of the
other fragments, and the results of the requested fragment. These fragment results will be inserted
("inlined") into the page at the appropriate point. Upon receiving the response, the ESI processor
will find the inlined fragment in the page and cache the updated copy of that fragment. The Oracle
ESI processor will discard the rest of the page. (Behavior may differ in other ESI processors.) The
4-168
Oracle9iAS Web Cache does not update the template when it requests a fresh fragment.
Keep this behavior in mind when choosing expiration policies for your templates and fragments. In
order to divide a page into template and fragments correctly and efficiently, it is important to
remember what portion of a JSP page is executed during any particular update request. For
example, because the template code is executed in every update request, try not to place an
expensive computation at the template level, unless it must be executed every time. It is usually
preferrable to place expensive computation in a fragment that has as long an expiration time as
possible.
Also be aware that no two fragments are ever executed during the same request. Therefore, you
should not declare or set the value of a scriplet variable in one fragment and depend on that
variable or the set value in another fragment. If a variable is needed in more than one fragment, it
should be declared and set in the template code. Similarly, but perhaps less obviously, do not set
a request or session attribute in one fragment and then try to read it in another fragment. Such
"page global logic" should also be placed at the template level.
Important:
In Oracle9iAS release 9.0.2, you cannot use the JESI template/fragment model and explicit
ESI markup (such as <esi:inline> for example) within the same HTTP response.
For example, Oracle9iAS Web Cache errors will occur if there is a JSP page that uses
<jesi:template> and <jesi:fragment> tags and also includes a servlet that
generates HTML with <esi:inline> tags.
See the following sections for tag syntax and examples:
● "JESI template Tag"

● "JESI fragment Tag"
● "JESI include Tag"
● "Examples--Template/Fragment Model"
Notes About JESI Includes
In using either model, be aware of the following notes regarding the JESI include statement:
4-169
● Nested "includes" are supported, either as a JESI include statement that includes a page
that in turn has its own JESI include statement, or as a JESI include statement inside a
fragment defined with JESI fragment.
In the latter case, for example, the ESI processor would first request content of the
aggregate page, would next request content of the fragment, and finally would request
content of the included page within the fragment.
● Despite conceptual similarities between JESI include and jsp:include, JESI include
is not a perfect substitute for jsp:include when you convert a JSP page for caching.
Because the ESI processor uses separate HTTP requests, you are unable to pass an HTTP
request or response object between an aggregate page and a page it includes through a
JESI include tag. If the code in the included page needs access to the request or
response object of the aggregate page, you can put the code in a JESI fragment tag
(within the JESI template tag of the aggregate page) instead of in an included page.
Invalidation of Cached Objects
There may be situations where cached objects must be explicitly invalidated due to external
circumstances, such as changes to relevant data in a database. There may also be situations
where execution of one page may invalidate the data of cached objects corresponding to another
page.
For this reason, JESI provides the JESI invalidate tag and several subtags. These tags allow
you to invalidate pages based on appropriate combinations of the following:
● a full URI or URI prefix

● a cookie name-value pair (optional)
● an HTTP/1.1 request header name-value pair (optional)
Invalidation messages are in an XML-based format, and specify the URLs to be invalidated. These
messages are initiated by the JSP container when it executes the JESI invalidate tag, and
transmitted to the cache server over HTTP using a POST method. The cache server then replies
with an invalidation response, sent back over HTTP.
4-170
See "Tag and Subtag Descriptions for Invalidation of Cached Objects" for tag syntax and
examples.
Personalization of Cached Pages
Dynamic Web pages frequently display personalized information tailored to each individual user.
For example, a welcome page may display the user's name and a special greeting, or current
quotes for stocks the user owns.
For this sort of tailored output, the Web page depends on cookie information, which can be
provided through the JESI personalize tag. Without this tag to inform the ESI processor of this
dependency, the Web page cannot be shared by multiple users at the ESI level.
See "Tag Description for Page Personalization" for tag syntax and examples.
Note:
Do not confuse this tag with the Oracle Personalization tag library, which encompasses
much more functionality. JESI personalization consists of the ESI processor simply replacing
place holders in a cached page with dynamic strings that come from cookies sent in a
request or response. This enables different users to share the same cached page. Oracle
Personalization, using data mining on the back end, is much more dynamic. It produces
output that changes automatically according to user activity.
Oracle JESI Tag Descriptions
This section describes the syntax and attributes for the JESI tags provided with OC4J, followed by
usage examples. Discussion is organized into the following categories:
● Tag Descriptions for Page Setup and Content

● Tag and Subtag Descriptions for Invalidation of Cached Objects
● Tag Description for Page Personalization
● JESI Tag Handling and JESI-to-ESI Conversion
To use the JESI tag library, the tag library description file, jesitaglib.tld, must be deployed
with the application. In an Oracle9iAS installation, this file is in the [Oracle_Home]/j2ee/tlds
4-171
directory.
In your JSP pages, you must use a taglib directive such as the following:
<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %>
Notes:
● The prefix "jesi:" is used in the tag syntax here. This is by convention but is not
required. You can specify any desired prefix in your taglib directive.
● Except where noted otherwise, default settings are determined by the ESI processor.
In the case of the Oracle9iAS Web Cache ESI processor, this is according to the
Oracle9iAS Web Cache configuration file.
Tag Descriptions for Page Setup and Content
This section summarizes the use of the following tags and documents their syntax and attributes:
● JESI control
● JESI include
● JESI template
● JESI fragment
This section also provides examples of both the control/include model and the template/fragment
model.
Summary of Page Setup and Usage Models
As "JESI Usage Models" explains, there are two scenarios in using JESI tags in a JSP page:
● control/include--Use a JESI control tag to specify cache settings for a page, and use JESI
include tags to bring in dynamic pages that are separate cacheable objects (or non-
cacheable, depending on tag settings).
4-172
● template/fragment--Use a JESI template tag to set up caching and specify cache settings
in the aggregate page, and use nested JESI fragment tags to specify individual cacheable
(or non-cacheable) objects within the aggregate page (specifying alternative cache settings
as desired). You can use JESI include tags within fragments or within the overall template
as well.
JESI control Tag
The JESI control tag controls caching characteristics for JSP pages in the control/include usage
model. You can use a JESI control tag in the top-level page or any included page, but it is not
mandatory. For any page without a JESI control tag, or with a JESI control tag that has no
cache attribute setting, cacheability is according to the configuration settings of the ESI
processor. (See "JESI Usage Models".)
The JESI control tag should appear as early as possible in the page, before any other JESI tags
or any buffer flushes in the page.
Be aware of the following:
● Do not use multiple JESI control tags in a single JSP page. Also do not use additional
JESI control tags in pages that are included, through jsp:include functionality, into the
same response object. In either case, an exception would result.
● Do not use a JESI control tag and a JESI template tag in the same page, or in separate
pages that are included into the same response object. An exception would result.
● The JESI control tag of the aggregate page has no effect on included pages. Use a JESI
control tag in each included page as well, as necessary.
● If a page with a JESI control tag depends on request parameters, consider whether you
must cache the page with parameters (as opposed to without parameters) in the ESI server.
Another alternative is to not cache the page at all (set cache="no"), if you anticipate that
too many different request parameter values will result in too many cached entries for the
page.
Syntax
<jesi:control
4-173
[expiration = "value"]
[maxRemovalDelay = "value"]
[cache = "yes" | "no" | "no-remote"] />
Note:
The proposed JESI specification includes a control attribute for the JESI control, JESI
template, and JESI fragment tags. This attribute is for setting parameters of ESI control
headers directly. The current Oracle implementation, however, supports setting only the
control header max-age parameter. Setting this is unnecessary, though, because setting the
expiration and maxRemovalDelay attributes of JESI control serves the same
purpose. Therefore, in this release, the control attribute is not documented. (Future
releases will likely support setting additional ESI control header parameters, at which time
the control attribute will be documented here.)
Attributes
● expiration--Specifies the lifetime, in seconds, of the cached object. If you do not specify
a setting, it defaults to 300.
● maxRemovalDelay--Specifies the maximum time, in seconds, that the ESI processor can
store the cached object after it has expired. If you do not specify a setting, it defaults to 0,
for immediate removal.
● cache--Specifies whether the object corresponding to the tag is cacheable. Set cache to
yes to enable caching. Alternatively, you can set cache to no for the object to not be
cacheable, or to no-remote for it to be cacheable only on the closest cache, instead of on
a remote ESI processor or content delivery network. If you do not set the cache parameter,
then cacheability depends on the configuration settings of the ESI processor.
One reason to make a page non-cacheable, for example, is if you are using a JESI
include tag with copyparam enabled. See "JESI include Tag" below.
JESI include Tag
The JESI include tag, like a standard jsp:include tag, dynamically inserts output from the
included page into output from the including page. Additionally, it is directing that the included
page be processed and assembled by the ESI processor. Each included page is a separate
cacheable object (or non-cacheable, depending on settings).
You can use this tag in both the control/include model and the template/fragment model, in any of
the following scenarios:
4-174
● by themselves, without a JESI control tag or JESI template/fragment tags
● after a JESI control tag
● within a JESI template tag, outside of any fragments
● within a JESI fragment tag
(See "JESI Usage Models".)
The cacheability of an included page depends on the cache attribute setting of the JESI control
tag (if any) within that page. If there is no cache setting, then cacheability depends on
configuration settings of the ESI processor.
Although the JESI include tag has similarities in usage to jsp:include, its different semantics
make it unsuitable for page inclusions where request or response objects must be passed
between the originating page and the included page.
Syntax
<jesi:include page = "uri"

[alt = "alternate_uri"]
[ignoreError = "true" | "false"]
[copyparam = "true" | "false"]
[flush = "true" | "false"] />
Attributes
● page (required)--Specifies the URI of the JSP page to be included, using either page-
relative or application-relative syntax. (Refer to the Oracle9iAS Containers for J2EE Support
for JavaServer Pages Reference for information about page-relative versus application-
relative syntax.) A full "http://..." or "https://..." URL is supported as well.
● alt--Specifies a URI for an alternate page, to be included if the page that is specified in the
page attribute cannot be accessed. Syntax is the same as for the page attribute.
● ignoreError--Set this to true for processing of the including page to continue even if no
included page (neither the page page nor alt page) can be accessed.
● flush--This attribute is ignored, but is supported to ease migration from jsp:include
syntax.
4-175
Notes:
Future releases may support a JESI param subtag, conceptually similar to the
jsp:param subtag used with jsp:include.
● copyparam--If the included page makes use of request parameters, set this to true to
copy parameters and their values from the HTTP request string of the including page to the
included page.
If request parameters are significant to the included page and copyparam="true", then
either the including page should not be cached (cache="no" in the JESI control, JESI
template, or JESI fragment tag), or, in the ESI server, the included page should be
cached with parameters (as opposed to without parameters). As an example, you should
generally avoid scenarios such as the following:
<jesi:control cache="yes"/>
...
<jesi:include page="arf.jsp" copyparam="true" />
The reason is that if you serve a copy of this including page from the cache, the page will
not execute on the server or have a chance to properly copy parameters into arf.jsp.
This would result in clients being served arf.jsp generated from incorrect parameters.
However, this scenario would not be problematic in certain circumstances, such as:
❍ The arf.jsp page does not use the request parameters. In this case, though, it is
advisable to remove the copyparam attribute or set it to "false".
or:
❍ The arf.jsp page is cached in the ESI server with URL parameters. See the
Oracle9iAS Web Cache Administration and Deployment Guide for more information.
Examples--Control/Include Model
This section provides examples of JESI tag usage in the control/include model.
4-176
Example 1: Control/Include
The following example employs default cache settings; no JESI control tag is necessary. The
JESI include tags specify no alternate files, and a "file not found" error will halt processing. The
flush attribute is permissible but ignored.

<html>
<body>
<jesi:include page="stocks.jsp" flush="true" />
<p>
<hr>
<jesi:include page="/weather.jsp" flush="true" />
<p>
<hr>
<jesi:include page="../sales.jsp" flush="true" />
</body>
</html>
This example uses the JESI control tag to specify non-default cache settings for
maxRemovalDelay and expiration. In addition, it explicitly enables caching of the page,
though this is already enabled by default. The first JESI include tag specifies an alternate page
in case order.jsp cannot be retrieved by the ESI processor, and specifies that processing
continue even if neither page can be retrieved. The second JESI include tag specifies no
alternate page, and processing will halt if the page cannot be retrieved.
As you can see, the HTML tags that "Example 1: Control/Include" uses are not actually required.
<jesi:control maxRemovalDelay="1000" expiration="300" cache="yes"/>

<jesi:include page="order.jsp" alt="alt.jsp" ignoreError="true"/>
<jesi:include page="commit.jsp" />
This is an example of an aggregate page whose output is conditional. A cookie represents the
identity of a customer. If no cookie is found, the user will see a generic welcome page with general
product information. If a cookie is found, the user will see a list of products according to the user
profile. This list is brought into the page through a JESI include statement.
The JESI control tag also sets non-default values for maxRemovalDelay and expiration,
4-177
and explicitly enables caching for the page.
<jesi:control maxRemovalDelay="1000" expiration="300" cache="yes"/>

<%
String customerId=CookieUtil.getCookieValue(request,"customerid");
if (customerId==null) {
// some unknown customer

%>
<jesi:include page="genericwelcome.jsp" />
<%
}
else {
// a known customer; trying to retrieve recommended products from profiling
String recommendedProductsDescPages[]=
ProfileUtil.getRecommendedProductsDescURL(customerId);
for (int i=0; i < recommendedProductsDescPages.length; i++) {

%>
<jesi:include page="<%=recommendedProductsDescPages[i]%>" />
<%
}
}
%>
This example illustrates the use of JESI include statements with request parameters. Assume
the main page is accessed through the following URL:
http://host:port/application1/main.jsp?p2=abc
The main page takes the parameter setting p2=abc. Here is the page:

<html>
<jesi:control cache="no" />
<jesi:include page="a.jsp?p1=v1" />
<h3>hello ...</h3>
<jesi:include page="b.jsp" />
<h3>world ...</h3>
<jesi:include page="c.jsp?p1=v2" copyparam="true" />
4-178
</html>
The a.jsp page takes the parameter setting p1=v1. The c.jsp page takes the setting p1=v2 as
well as the setting p2=abc (as a result of the copyparam setting and the p2 setting in the URL for
the main page).
Additionally, this page is non-cacheable, according to the cache="no" setting. In fact, remember
that you should use the copyparam setting only in non-cacheable pages, because the request
attributes may change from one request to the next. Remember, too, that the cache="no" setting
has no effect on the included pages--they are still cacheable by default. (In other words, they are
cacheable unless any of them also have a JESI control tag with cache="no" for some reason.)
JESI template Tag
Use the JESI template tag to specify caching behavior for the aggregate page, outside any
fragments, in the template/fragment usage model. (See "JESI Usage Models".) The corresponding
HTTP header will be set according to the edge architecture specification. The aggregate content
(outside the fragments) is a cacheable object, and each fragment set aside with a JESI fragment
tag is a separate cacheable object.
Place the JESI template start tag as early in the page as possible--it must appear before any
other JESI tags or any buffer flushes in the page. Place the JESI template end tag as late in the
page as possible--it must appear after any other JESI tags in the page.
If a JESI template tag does not set the cache attribute, then cacheability of the corresponding
object is according to configuration settings of the ESI processor.
The JESI template tag is always used together with JESI fragment tags. If you have no need
for separate fragments, use a JESI control tag instead of a JESI template tag.
Be aware of the following:
● Do not use multiple JESI template tags in a single JSP page. Also do not use additional
JESI template tags in pages that are included, through jsp:include functionality, into
the same response object. In either case, an exception would result.
● Do not use a JESI control tag and a JESI template tag in the same page, or in separate
pages that are included into the same response object. An exception would result.
● The JESI template tag settings have no effect on the enclosed fragments; fragments must
provide their own settings.
● If a page with a JESI template tag depends on request parameters, consider whether you
must cache the page with parameters (as opposed to without parameters) in the ESI server.
Another alternative is to not cache the page at all (set cache="no"), if you anticipate that
4-179
too many different request parameter values will result in too many cached entries for the
page.
The JESI template tag has the same attributes, with the same usage, as the JESI control tag.
Syntax
<jesi:template
[cache = "yes" | "no" | "no-remote"] >
...page content, jesi:fragment tags, jesi:include tags...
</jesi:template>
Attributes
For attribute descriptions, see "JESI control Tag".
Note:
If request parameters are significant to the fragment, then either the enclosing template
should not be cached (cache="no" in the JESI template tag), or, in the ESI server, the
fragment should be cached with parameters (as opposed to without parameters). In the
background, a fragment, like a page included through a JESI include tag, involves an
additional request. Request parameters (if any) are always passed from the template to the
fragment, equivalent to JESI include tag functionality with a setting of
copyparam="true".
JESI fragment Tag
Use one or more JESI fragment tags within a JESI template tag, between the JESI template
start and end tags, in the template/fragment model. (See "JESI Usage Models".) The JESI
fragment tags defines separate fragments of JSP code, as desired, for caching behavior. Each
fragment is a separate cacheable object.
4-180
When a particular fragment is requested through the ESI mechanism, the ESI processor will
retrieve only that fragment.
Each JESI fragment tag specifies its own instructions to the ESI processor. If the cache attribute
is not set, then cacheability of the corresponding object is according to the configuration settings of
the ESI processor. The settings of the surrounding JESI template tag have no effect on the
fragments.
The JESI fragment tag has the same attributes, with the same usage, as the JESI control and
JESI template tags.
Syntax
<jesi:fragment
[cache = "yes" | "no" | "no-remote"] >
...JSP code fragment...
</jesi:fragment>
Attributes
For attribute descriptions, see "JESI control Tag".
Examples--Template/Fragment Model
This section contains examples of JESI tag usage in the template/fragment model.
Example 1: Template/Fragment
This is a general example showing use of the JESI template and JESI fragment tags. Because
only the expiration attribute is set in any of the tags, all other settings are according to defaults.
The aggregate content (outside the fragments), according to the JESI template tag, uses an
expiration of 3600 seconds. This applies to all the HTML blocks because they are all outside the
fragments. JSP code block #1 is cached with an expiration setting of 60; JSP code block #2 is
cached with the default expiration setting; and JSP code block #3 is cached with an expiration
setting of 600.

4-181
<jesi:template expiration="3600">
...HTML block #1...
<jesi:fragment expiration="60">
...JSP code block #1...
</jesi:fragment>
...HTML block #2...
<jesi:fragment>
</jesi:fragment>
...HTML block #3...
</jesi:fragment>
...HTML block #4...
</jesi:template>
Example 2: Template/Fragment
This example employs JESI include tags inside the fragments. The following are the cacheable
objects for this page:
● each included page

● each fragment, outside of its included page
● the aggregate of the HTML blocks, which are all at template level (outside the fragments)

<jesi:template expiration="3600">
...HTML block #1...
<jesi:include page="stocks.jsp" />
</jesi:fragment>
...HTML block #2...
<jesi:fragment>
<jesi:include page="/weather.jsp" />
</jesi:fragment>
...HTML block #3...
4-182
<jesi:include page="../sales.jsp" />
</jesi:fragment>
...HTML block #4...
</jesi:template>
Tag and Subtag Descriptions for Invalidation of Cached Objects
Use the JESI invalidate tag and the following subtags, as appropriate, to explicitly invalidate
cached objects in the ESI processor:
● JESI object
● JESI cookie (subtag of JESI object)
● JESI header (subtag of JESI object)
See "Invalidation of Cached Objects" for an overview.
JESI invalidate Tag
You can use the JESI invalidate tag with its JESI object subtag to explicitly invalidate one or
more cached objects.
Use the subtags as follows:
● Use the required JESI object subtag to specify what to invalidate according to URI or URI
prefix.
● Optionally use the JESI cookie subtag or JESI header subtag of JESI object to specify
further criteria for what to invalidate, according to cookie or HTTP header information.
Syntax
<jesi:invalidate
[url = "url"
username = "username"
password = "password"]
[config = "configfilename"]
4-183
[output = "browser"] >
Required subtag (described in "JESI object Subtag"):
<jesi:object ... >
Optional subtag of JESI object (described in "JESI cookie Subtag"):
<jesi:cookie ... />
Optional subtag of JESI object (described in "JESI header Subtag"):
<jesi:header ... />
</jesi:object>
</jesi:invalidate>
Either specify the user, password, and URL all through their individual tags, or all in the
configuration file referred to in the config tag.
Note:
It is permissible to have multiple object tags within an invalidate tag.
Attributes
● url--Specifies the URL of the cache server. If this attribute is omitted, you must specify the
URL in the JESI configuration file.
● username--Specifies the user name for logging in to the cache server. If this attribute is
omitted, you must specify the user name in the JESI configuration file.
● password--Specifies the password for logging in to the cache server. If this attribute is
omitted, you must specify the password in the JESI configuration file.
● config--Specifies a JESI configuration file. You can use this file to provide the cache
server URL, user name, and password information instead of using the corresponding tag
attributes. Specify the location in application-relative syntax, starting with "/". Refer to the
Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for general
information about application-relative syntax.
● output--Optionally sets an output device to receive the invalidation response from the
4-184
cache server. Currently, the only supported setting is browser, to show the message in the
user's Web browser. If you do not set this parameter, the confirmation message will not be
displayed at all.
Example: Configuration File
Following is an example of a configuration file that is used instead of the url, username, and
password attributes to set the URL and login information:
<?xml version="1.0" ?>

<ojsp-config>
<web-cache>
<url>http://yourhost.yourcompany.com:4001</url>
<username>invalidator</username>
<password>invpwd</password>
</web-cache>
</ojsp-config>
JESI object Subtag
Use the required JESI object subtag of the JESI invalidate tag to specify cached objects to
invalidate, according to either the complete URI or a URI prefix. Optionally use its JESI cookie
subtag or JESI header subtag to specify further criteria for invalidation, based on cookie or HTTP
header information.
Specify either the complete URI or the URI prefix in the uri attribute setting. Whether this field is
interpreted as a full URI or as a prefix depends on the setting of the prefix attribute.
Syntax
<jesi:object uri = "uri_or_uriprefix"

maxRemovalDelay = "value"
[prefix = "yes" | "no"] >
Optional subtag (described in "JESI cookie Subtag"):
<jesi:cookie ... />
Optional subtag (described in "JESI header Subtag"):
4-185
<jesi:header ... />
</jesi:object>
or (if not using either subtag):
<jesi:object
[uri = "uri_or_uriprefix"]
[prefix = "yes" | "no"]
[maxRemovalDelay = "value"] />
Note:
● It is permissible to have multiple object tags within an invalidate tag.

● It is permissible to have multiple cookie tags or header tags within an object tag.
Attributes
● uri--Specifies either the complete URI of the page whose corresponding cached object is
to be invalidated (if prefix="no"), or a URI prefix that specifies objects for multiple pages
to be invalidated according to location (if prefix="yes").
If a prefix is specified, then cached objects for all pages under that location are invalidated.
For example, for a prefix setting of /abc/def, cached objects for all pages in the
corresponding directory and any subdirectories are invalidated.
● prefix--Set this to yes if the uri attribute is to be interpreted as a URI prefix only, and to
no if uri is to be interpreted as a complete URI.
● maxRemovalDelay--Specifies the maximum time, in seconds, that the ESI processor can
store the cached object after it has been invalidated. This is 0 by default, for immediate
removal.
JESI cookie Subtag
4-186
Use the JESI cookie subtag of the JESI object tag (which is a subtag of JESI invalidate) to
use cookie information as a further criterion for invalidation. This is used in addition to the URI or
URI prefix setting in the JESI object tag, and possibly in addition to a JESI header tag as well.
Syntax
<jesi:cookie name = "cookie_name"

value = "cookie_value" />
Note:
It is permissible to have multiple cookie tags within an object tag.
Attributes
● name (required)--The name of the cookie.

● value (required)--The value of the cookie.
For a cached object to be invalidated, it would have to have a cookie that matches this name and
value.
JESI header Subtag
Use the JESI header subtag of the JESI object tag (which is a subtag of JESI invalidate) to
use HTTP/1.1 header information as a further criterion for invalidation. This is in addition to the
URI or URI prefix setting in the JESI object tag, and possibly in addition to a JESI cookie tag
as well.
Syntax
<jesi:header name = "header_name"

value = "header_value" />
4-187
Note:
It is permissible to have multiple header tags within an object tag.
Attributes
● name (required)--The name of the HTTP/1.1 header.

● value (required)--The value of the HTTP/1.1 header.
For a cached object to be invalidated, it would have to have a header that matches this name and
value.
Examples--Page Invalidation
This section provides examples of page invalidation using the JESI invalidate tag, its JESI
object subtag, and the JESI cookie subtag of the JESI object tag.
Example 1: Page Invalidation
This example invalidates a single object in the ESI processor, specified by its complete URI. (By
default, uri specifies a full URI, not a URI prefix.) The JESI invalidate tag also specifies the
URL for the cache server and the user name and password for login, and it specifies that the
invalidation response from the cache server should be displayed in the user's browser.
...
<jesi:invalidate url="http://yourhost.yourcompany.com:4001"
username="invalidator" password="invpwd"
output="browser">
<jesi:object uri="/images/logo.gif"/>
</jesi:invalidate>
...
This is equivalent to Example 1: Page Invalidation, but uses a configuration file to specify the
cache server URL and login information.
...
4-188
<jesi:invalidate config="myconfig.xml" output="browser">
<jesi:object uri="/images/logo.gif"/>
</jesi:invalidate>
...
The JESI invalidate uses page-relative syntax for the configuration file, so myconfig.xml is
presumably in the same directory as the JSP page. As an example, assume that it has the
following content:
<?xml version="1.0" ?>

<ojsp-config>
<web-cache>
<url>http://yourhost.yourcompany.com:4001</url>
<username>invalidator</username>
<password>invpwd</password>
</web-cache>
</ojsp-config>
This example invalidates all objects in the ESI processor, according to the URI prefix "/". It does
not specify that the invalidation confirmation message be displayed in the browser, so it will not be
displayed at all.
...
username="invalidator" password="invpwd">
<jesi:object uri="/" prefix="yes"/>
</jesi:invalidate>
...
This example invalidates a single object but allows it to be served stale for up to 30 minutes (1800
seconds). Also, the invalidation message sent by the JSP container to the cache server will
include supplementary system information indicating that the operating system is UNIX.
...
<jesi:object uri="/images/logo.gif" maxRemovalDelay="1800"/>
</jesi:invalidate>
...
4-189
This example specifies the same object for invalidation as Example 1: Page Invalidation, but
specifies that it should be invalidated only if it has a cookie named user_type with value
customer.
...
<jesi:object uri="/images/logo.gif">
<jesi:cookie name="user_type" value="customer"/>
</jesi:object>
</jesi:invalidate>
...
Tag Description for Page Personalization
To allow page personalization when sharing the same cached page between multiple users, the
ESI processor must be informed of dependencies by the page on cookie and session information.
Cookie value replacement, for example, occurs in the ESI processor instead of the Web server.
JESI personalize Tag
Use the JESI personalize tag to allow page personalization, by informing the ESI processor of
dependencies on cookie and session information.
Syntax
<jesi:personalize name = "cookie_name"

[value = "default_value"] />
Attributes
● name (required)--Specifies the name of the cookie whose value is used as the basis for
personalizing the page.
● value--An optional default value in case the cookie is not found. This allows the ESI
processor to avoid having to go back to the Web server to look for the cookie.
Example--Page Personalization
4-190
Following is an example showing use of the JESI personalize tag:
<jesi:personalize name="user_id" value="guest" />
The corresponding ESI tag that is generated allows the ESI processor to find the necessary
information. In this case, it looks for a cookie named user_id and retrieve its value. If it cannot
find the cookie, it uses a default value of guest. Handling this cookie-value replacement in the
ESI processor avoids having to send a request to the Web server.
JESI Tag Handling and JESI-to-ESI Conversion
JESI tag handler classes, supplied as part of the JESI tag library with OC4J, provide the bridge
from JSP functionality to ESI functionality. Tag handlers translate JESI tags into ESI tags and, as
appropriate, generate HTTP requests for invalidation, set HTTP response headers, and so on. Be
aware, however, that there is not always a simple one-to-one mapping between JESI tags and ESI
tags, or between JESI tag attributes and ESI tag attributes.
Example: JESI-to-ESI Conversion for Included Pages
As an example of JESI-to-ESI conversion, consider the following JSP code:
<p>BEGIN</p>
<jesi:include page="stocks.jsp" flush="true" />
<p>
<hr>
<jesi:include page="/weather.jsp" copyparam="true" flush="true" />
<p>
<hr>
<jesi:include page="../sales.jsp?tax=local" copyparam="true" flush="true" />
<p>END</p>
Assume that this JSP code is part of a page with the following URL:
http://host:port/application1/top.jsp
Further assume the following request:
http://host:port/application1/top.jsp?city=Washington_DC
In this case, the JESI include tag handler generates ESI code such as in the following response.
4-191
In the response header:
Surrogate-Control: content="ESI/1.0",max-age=300+0
In the response body:
<p>BEGIN</p>
<esi:include src="/application1/stocks.jsp"/>
<p>
<hr>
<esi:include src="/weather.jsp?city=Washington_DC"/>
<p>
<hr>
<esi:include src="/sales.jsp?tax=local&city=Washington_DC"/>
<p>END</p>
This response is read by the ESI processor before being delivered to the client. A Surrogate-
Control header alerts the ESI processor that the response body contains ESI code; therefore,
the caching mechanism will look inside the response body for <esi:> tags. In addition, the
Surrogate-Control header sets the cache expiration and maximum delay interval for the page,
in this case using the default expiration of 300 and the default maximum delay of 0 because there
is no JESI control tag to specify otherwise.
In response to each of the three esi:include tags, the ESI processor makes an additional
request to the URL specified. Each response will be included into the top-level page, and only
after that is the assembled page delivered to the client. Note that the client receives one response,
but the cache makes four requests to obtain it. This may seem like a lot of overhead; however, the
overall efficiency will be improved if many additional requests also use the same included pages,
such as weather.jsp. No requests for these pages would be required, because they are cached
separately on the ESI server.
Example: JESI-to-ESI Conversion for a Template and Fragment
Suppose that when an employee connects to a corporate intranet site, the content of his or her
pages is dynamic, except for a few features that are present in every response. In particular, there
is always a footer displaying the stock chart and latest business headlines for the company, and
the business headlines are obtained from an external business news site. Because all returned
pages will have to include the same information, and it is expensive to obtain, it is more efficient to
cache the footer on the ESI server.
The remainder of the page response is dynamic, incorporating the stock fragment in a slightly
4-192
different way each time. To avoid having to rewrite the page, you can mark the footer as a JESI
fragment and the enclosing page as a JESI template.
Also assume that a charity campaign is in progress, and that the organizers want to display a bar
chart showing their goal amount and the current donation amount as part of all corporate pages.
This information is stored in a special database and is updated twice a day. The chart is a good
candidate to be an additional JESI fragment.
Therefore, you would add a JESI template tag at the top of the page, and use JESI fragment
tags to enclose the fragments that are to be cached as separate entities.
Assume the URL to the corporate page is as follows:
http://www.bigcorp.com/employee_page.jsp
Further assume you have modified the page as follows:

<jesi:template cache="no" >
<p>BEGIN</p>
... some dynamic page content...
<jesi:fragment>
This_is_the_body_of_Charity_Chart
</jesi:fragment>
... some more dynamic content...
<jesi:fragment>
This_is_the_body_of_the Business_Footer
</jesi:fragment>
<p>END</p>
When the page is requested, an HTTP response is generated as follows.
In the response header:
Surrogate-Control: content="ESI/1.0",max-age=300+0,no-store
In the response body:
<p>BEGIN</p>
... some dynamic page content...
<esi:include src="/employee_page.jsp?__esi_fragment=1"/>
... some more dynamic content...
<esi:include src="/employee_page.jsp?__esi_fragment=2"/>
4-193
<p>END</p>
As with the JESI include example in "Example: JESI-to-ESI Conversion for Included Pages", the
ESI server is alerted by the Surrogate-Control response header. Note the no-store
directive, generated because of the cache="no" setting in the JESI template tag. Also, the
default expiration of 300 and the default maximum delay of 0 are used, because the JESI
template tag does not specify otherwise.
The ESI server makes two additional requests, where it fetches and caches the two fragments.
After that, the composite page is returned to the employee. When the employee works with the
page again, the dynamic content will be newly generated, but the chart and the footer will be
served from the cache.
Note:
Surrogate-Control headers are consumed by the ESI server and are not seen in the
final response to the client.
4-194
Reference: OC4J Java Edge Side Include Tags
Library Syntax
<%@ taglib uri="jesitaglib.tld" prefix="JESI" %>
Syntax usage:
JESI Tag Library
Name Syntax
<JESI:control
[control]
control - The jesi:control tag controls caching [cache]
characteristics for aggregate pages. [expiration]
[maxRemovalDelay] > JSP content
</JESI:control>
cookie - The jesi:cookie subtag of the <JESI:cookie
jesi:invalidate tag is used to specify which name
cached cookies and related objects to value > JSP content
invalidate. </JESI:cookie>
<JESI:fragment
[control]
fragment - The jesi:fragment subtag within the
[cache]
jesi:template tag defines separate cacheable
[expiration]
objects.
</JESI:fragment>
header - The jesi:header subtag of the <JESI:header
jesi:invalidate tag is used to specify which name
cached HTTP header info and related objects value > JSP content
to invalidate. </JESI:header>
4-195
<JESI:include
page
[ignoreError]
include - The jesi:include tag dynamically
[alt]
inserts output from the included page.
[copyparam]
[flush] > JSP content
</JESI:include>
<JESI:invalidate
[url]
invalidate - The jesi:invalidate tag explicitly [username]
invalidates cached objects in the ESI [password]
processor. [config]
[output] > JSP content
</JESI:invalidate>
<JESI:object
object - The jesi:object subtag of the uri
jesi:invalidate tag is used to specify which maxRemovalDelay
cached objects to invalidate. [prefix] > JSP content
</JESI:object>
<JESI:personalize
personalize - The jesi:personalize tag allows
name
page personalization, using cookie and
[value] > JSP content
session information.
</JESI:personalize>
<JESI:template
[control]
template - The jesi:template tag controls [cache]
caching characteristics for aggregate pages. [expiration]
</JESI:template>
4-196
Working with Web Object Cache Tags
This chapter describes the Oracle Web Object Cache, an application-level caching mechanism
supplied with OC4J. For Web applications written in Java, you can use the Web Object Cache in
conjunction with the Oracle9iAS Web Cache for increased speed and scalability.
This chapter includes the following topics:
● Overview of the Web Object Cache
● Key Functionality of the Web Object Cache
● Attributes for Policy Specification and Use
● Web Object Cache Tag Descriptions
● Web Object Cache Servlet API Description
● Cache Policy Descriptor
● Cache Repository Descriptor
Overview of the Web Object Cache
The OC4J Web Object Cache is a mechanism that allows Web applications written in Java to
capture, store, reuse, post-process, and maintain the partial and intermediate results generated by
a dynamic Web page, such as a JSP or servlet. For programming interfaces, it provides a tag
library (for use in JSP pages) and a Java API (for use in servlets).
The Web Object Cache works at the Java level and is closely integrated with the HTTP
environment of JSP and servlet applications. Cached objects might consist of HTML or XML
fragments, XML DOM objects, or Java serializable objects.
Through the Web Object Cache programming interfaces, you can decide how to split Web pages
into page blocks that define separate cache objects for finer control of caching. (The terms block
and object can be used somewhat interchangeably in this sense.) In this way, the application itself
can control life span and other behavior of individual cache entities during runtime. Application
developers have the best understanding of the life cycle patterns of their application Web pages,
4-197
so are best suited to determine how to split pages into cache blocks. You can specify maintenance
policies for partial results either declaratively in an external file (the cache policy descriptor), or
programmatically within the application itself.
● Benefits of the Web Object Cache
● Web Object Cache Components
● Cache Policy and Scope
Benefits of the Web Object Cache
Note:
The Web Object Cache is useful in particular scenarios and does not replace the need for
other caching mechanisms, including the Oracle9iAS Web Cache.
Using the Web Object Cache can significantly reduce the amount of time spent in constructing
page blocks or Java objects in dynamic applications, such as those with expensive intermediate
operations like querying a database and formatting or transforming the results. Subsequent
queries pull the information out of the cache, so the query and formatting do not have to be
repeated.
Furthermore, developers can closely control the cache programmatically, through API calls or
custom JSP tags. This can include controlling when cache entries are created, what they are
named, when they expire, which users can see which cached data, and what operations can be
applied to cached data before the results are served to the user.
Some kinds of Web applications benefit more than others by using the Web Object Cache,
depending on the nature and use of their data. For example, applications such as catalog and
directory browsing, delayed stock quotes, and personalized portals would particularly benefit.
Applications such as real-time stock trading or real-time stock quotes, however, would not benefit,
because the data has to be updated so frequently that the overhead of the caching operations
would outweigh the benefits. (In these circumstances, however, the Oracle9iAS Web Cache might
still be useful because of its lighter overhead.)
In general, the Web Object Cache is most useful in the following situations:
4-198
● for special post-processing on cached data objects, such as XSLT or XML DOM operations
● for sharing data in a non-HTTP situation, such as reusing cached XML data or Java objects
and sending the data to others through SMTP, JMS, AQ, or SOAP
● for special storage needs, such as storing cached data in a file system or database for
persistent storage of data with a long lifetime
● for application-specific authorization, allowing different users to have different access rights
to different data items, such as for a Web-based groupware application
The application can have its own authorization scheme. The Web Object Cache is
embedded within Java authorization logic.
Using the Web Object Cache in JSP pages, as opposed to servlets, is particularly convenient. JSP
code generation can save much of the development effort.
Web Object Cache Components
The Web Object Cache consists of two main components:
● the cache repository
● the cache programming interfaces
This section also provides a brief introduction to the Oracle9i Application Server Java Object
Cache, which the Web Object Cache uses as its default cache repository.
Cache Repository
The cache repository is the component that is responsible for data storage, data distribution, and
cache expiration. Generally speaking, there can be multiple repository implementations for a
programmable Web cache (such as the Web Object Cache), depending on the tier and platform.
For example, the file system might be used for secondary storage in the middle tier, and database
tables for primary storage in the database tier.
The Web Object Cache uses the Oracle9i Application Server Java Object Cache as its default
repository. This is a general-purpose caching service and API designed for Java application use,
with objects being accessible by name.
4-199
The Java Object Cache is a powerful and flexible programming facility. There are no restrictions
on the types of objects that can be cached or the original source of the objects--the management
of each object is easily customizable. Each object has a set of attributes such as the following:
● how the object is loaded into the cache
● where the object is stored (in memory, on disk, or both)
● the lifetime, also known as the time-to-live, of the object
● whom to notify when the object is invalidated
Objects can be invalidated as a group or individually.
For more information, see the Oracle9i Application Server Java Object Cache Developer's Guide.
Notes:
Web Object Cache sample applications include configuration notes for a file system cache
repository or for the Oracle9i Application Server Java Object Cache.
Cache Programming Interfaces
The front-end caching interfaces are used through JSP pages and servlets to handle HTTP
processing and to direct the semantics relating to the cache policy (rules and specifications
determining how the cache works).
Generally speaking, the OC4J Web Object Cache programming interfaces can be further divided
as follows:
● Web Object Cache tag library
This is a convenient wrapper, using JSP custom tag functionality, for the Web Object Cache
API. Use custom tags in a JSP page to control the caching, with the API being called
through the underlying tag handler classes.
● Web Object Cache servlet API
4-200
This is the common layer across servlets and JSP pages, dealing with the HTTP semantics
and cache policy. This layer communicates with the cache repository.
This chapter describes these programming interfaces and their interaction with the cache
repository. Equivalent cache tags are described in "Web Object Cache Tag Descriptions". The
underlying cache policy API is described in "Web Object Cache Servlet API Description". In
servlets, you will use the underlying API; in JSP pages, you will typically use the more convenient
tags.
Cache Policy and Scope
The cache policy is a set of specifications determining details of the cache and how it will behave.
This includes the following:
● cache scope
● cache block naming rules
● data expiration rules
● cache repository name
You can set cache policy specifications (per "Attributes for Policy Specification and Use") through
any of the following:
● cache tag attributes (for JSP pages)
See "Web Object Cache Tag Descriptions".
● cache policy methods (for servlets)
See "Web Object Cache Servlet API Description".
● external cache policy descriptor files (for JSP pages or servlets)
See "Cache Policy Descriptor".
4-201
A cache policy object--an instance of the oracle.jsp.jwcache.CachePolicy class--is
created with policy settings based on these inputs. Because the expiration policy is part of the
cache policy, each CachePolicy object includes an attribute that is an instance of the
oracle.jsp.jwcache.ExpirationPolicy class.
Cache data can be of either session scope, where it is available to only the current HTTP session,
or application scope, where it is available to all users of the application.
For example, consider an online banking application that caches the account balance. Only the
current user is interested in this information, so session scope is appropriate.
By contrast, consider an online store with a welcome page that issues the same general product
recommendations to all users. In this case, it is appropriate for the page to use a cache that has
application scope.
Key Functionality of the Web Object Cache
This section discusses key areas of functionality of the Web Object Cache, covering the following:
● Cache Block Naming--Implicit Versus Explicit
● Cache Block Runtime Functionality
● Data Invalidation and Expiration
Cache Block Naming--Implicit Versus Explicit
A cache block is associated with a cache block name, which can be determined either implicitly by
the caching policy (generally advisable), or explicitly by your application code. For retrieval, to
avoid regenerating the page fragment in question, there is a lookup of the cache block name.
For implicit naming, there are two inputs:
● the cache policy
A cache policy API layer performs naming logic.
● the HTTP request object
4-202
The caching logic borrows corresponding semantics from the standard Java servlet API.
For most situations, implicit naming will result in names that are sufficiently informative, because
the HTTP request usually includes all the inputs to the Web application (inputs that determine
what the application should generate).
Explicit naming might be desirable in some cases, however, such as when a group of users needs
to share the same data. In this case, relevant identification information may not be available
directly from the user's HTTP request, so an implicit cache name would not be useful. Instead, you
can write code to explicitly generate a cache name that identifies the group. (Preferably, the name-
generation logic should still use only request parameters as input, not other states existing inside
the application. This makes the semantics easier to follow and the code easier to debug.)
Following is an example of explicit naming. In the cache tag, note the name attribute with a JSP
expression that calls someMethod() to set the cache block name:
<ojsp:cache policy="/WEB-INF/policy1.cpd"
name="<%= someObj.someMethod() %>" >
...static text...
<% // dynamic content ... %>
</ojsp:cache>
In the following example, because there is no name attribute in the cache tag, the cache block
name will be determined implicitly according to the HTTP request and the cache policy:
<ojsp:cache policy="/WEB-INF/policy2.cpd" >

...static text...
<% // dynamic content ... %>
</ojsp:cache>
See "More About Cache Block Naming and the autoType Attribute" for more information.
Note:
Cache blocks can be nested. In this case, the logic of the inner cache block will be executed
only when the content of the outer block must be regenerated.
Cloneable Cache Objects
4-203
The OC4J Web Object Cache provides an interface,
oracle.jsp.jwcache.CloneableCacheObj, that you can implement in serializable cache
objects that you want to be cloneable. For mutable objects that are cached without being
serialized, cloning is useful in providing a complete and hierarchical copy of the cache object. This
section explains the usefulness of cloneability, first covering some necessary background
information.
Memory-Oriented Repositories Versus Secondary Storage Repositories
There are two categories of repositories that can be used as the back end of the Web Object
Cache:
● secondary storage cache repository (such as a file system repository)
● memory-oriented cache repository (such as the Oracle9i Application Server Java Object
Cache, the default repository of the Web Object Cache)
A secondary storage repository requires Java serialization during cache operations. During
storage to the cache, objects are serialized into the repository; during retrieval from the cache,
they are deserialized into memory. Therefore, as a result of the serialization/deserialization
process, a complete and distinct copy of the cache object is automatically created during each
cache operation.
This is not the case when you store or retrieve cache objects to or from a memory-oriented
repository. With a memory-oriented repository, the identical object in the user application will be
stored to the cache, or the identical object in the cache will be retrieved for the user. By default, no
copy is made. If there are multiple retrievals, all retrievals share the same object.
Advantages in Cloning Copies of Cache Objects
In many cases in your applications, you will want to ensure that different retrievals use different
copies of a cache object. There are two key reasons for this:
● If the identical cache object is shared across multiple retrievals, changes made to the data
in one place may unintentionally affect values retrieved and used elsewhere.
● If the identical cache object is shared across multiple retrievals, then multiple Java threads
may access the same object simultaneously. This would result in thread safety issues if the
original object design was not thread-safe. (Perhaps, for example, the object was originally
intended for page-scope or request-scope usage only, where there could be only one thread
per object. This thread-behavior assumption would be violated.)
4-204
To avoid these possible problems, you should use complete and hierarchical copies when you
store and retrieve generic Java serializable data to or from a memory-oriented repository.
"Complete and hierarchical" means copying not just the direct members referenced by the object,
but also any indirect variables that are referenced. For example, assume an object Y has a
java.util.Vector instance as a member variable. Cloning a complete and hierarchical copy
involves copying not just the Vector instance itself, but also all mutable objects or elements
referenced by the Vector instance.
Use of the CloneableCacheObject Interface
If you implement the CloneableCacheObject interface and its cloneCacheObj() method in

your cache objects, then the Web Object Cache will automatically call cloneCacheObj() to
make a complete and hierarchical copy of each cache object whenever it is stored to or retrieved
from a memory-oriented cache repository.
Cache Block Runtime Functionality
During runtime, when a Web Object Cache cache tag is encountered, the tag handler checks
whether a corresponding cache object exists and was created recently enough to reuse. If so, the
code in the body of the tag is not executed; instead, the cache object is reused. But if the cache
object does not exist or is too old, the tag body code will be executed to generate a new object
(page fragment, XML DOM object, or Java serializable object). Then this freshly generated object
will be captured (such as through special buffer writing or object passing) and stored into the
cache.
If computations in content generation are costly (such as for a complicated database query) and
the life span of the cache is appropriate (so that the cached data is reusable), the Web Object
Cache can save significant amounts of time and system resources. Application speed and
throughput will be greatly improved.
Data Invalidation and Expiration
Cache blocks can be set up to expire after a specified duration or at a specified time, or can be
invalidated explicitly by a method call or tag invocation.
Cache Block Expiration
Because cache blocks mainly consist of semi-static fragments of information, the Oracle
implementation does not require a tightly coherent expiration model. A looser model typically
provides acceptable results and requires less synchronization overhead.
4-205
There are two categories of expiration for data in Web Object Cache blocks:
● duration (time-to-live)--expiration occurs after data has been in the cache for a specified
amount of time
● fixed time/day--expiration occurs regularly at a set time, such as at a specified time each
day or on a specified day each week
Expiration details are determined by the settings of attributes in an instance of the

oracle.jsp.jwcache.ExpirationPolicy class. This ExpirationPolicy object is an
attribute of the CachePolicy object associated with the cache block. See "Expiration Policy
Attributes".
In JSP pages, you can set ExpirationPolicy attributes through attributes of the Web Object
Cache cache tags (such as cache, cacheXMLObj, or useCacheObj). See "Web Object Cache
cache Tag".
In servlets, you can use methods of the ExpirationPolicy object directly. See
"ExpirationPolicy Methods".
Alternatively, you can set ExpirationPolicy attributes through a cache policy descriptor. See
"Cache Policy Descriptor".
Cache Block Invalidation
Instead of depending on expiration to invalidate a cache, you can invalidate it explicitly in one of
the following ways:
● Use the invalidateCache tag. See "Web Object Cache invalidateCache Tag".
● Use the overloaded invalidateCache(), invalidateCacheLike(), or

invalidateCacheOtherPathLike() method of a CachePolicy instance to explicitly
invalidate one or more cache blocks. See "CachePolicy Methods".
Attributes for Policy Specification and Use
This section describes cache policy attributes--specifically, attributes of the CachePolicy and
ExpirationPolicy classes. You can set these attributes through custom tags in JSP pages,
4-206
directly through the provided Java API in servlets, or through a cache policy descriptor file.
Cache Policy Attributes
Cache policies, introduced in "Cache Policy and Scope", consist of the details that determine how
cache blocks behave. You can set cache policy attributes in several ways, as described in
subsequent sections:
● in JSP pages through custom tags
● in servlets through method calls
See "CachePolicy Methods".
● through a cache policy descriptor file
Specification of cache policy settings results in the creation of a cache policy object, which
includes an expiration policy object as one of its attributes. Following is abbreviated code for the
CachePolicy class (in package oracle.jsp.jwcache), for illustration purposes only, showing
the names of the cache policy attributes:
class CachePolicy
{
boolean ignoreCache;
int scope;
int autoType;
String selectedParameters[];
String selectedCookies[];
Date reusableTimeStamp;
long reusableDeltaTime;
ExpirationPolicy expirationPolicy;
String cacheRepositoryName;
boolean reportException;
}
4-207
Note:
The names documented below for integer constants are for servlet usage. Different names
may be used for the Web Object Cache tags. See "Web Object Cache cache Tag".
Attribute Descriptions
Table 7-1 describes cache policy object attributes.
Table 7-1 Cache Policy Attribute Descriptions
Attribute Type Description

ignoreCache boolean This is intended for use during development only. When making
frequent code changes, set this to true to disable the cache, typically
so that results that were generated prior to your changes will not be
returned.
default: false
scope int Specifies the scope of the cache. Use the integer constant
SCOPE_SESSION (for the cache block to be accessible only to the
current HTTP session) or SCOPE_APP (for the cache block to be
accessible to all HTTP sessions of the application).
default: application
autoType int Specifies whether the cache block is named explicitly or implicitly, and
how properties of the HTTP request are used in cache block naming
(for implicit naming). The name is relevant in determining when the
cache is reused for subsequent requests. See "More About Cache
Block Naming and the autoType Attribute".
selectedParameters[] String [] Selected request parameter names used in cache block naming; used
in conjunction with autoType. See "More About Cache Block Naming
and the autoType Attribute".
default: null
selectedCookies[] String[] Selected cookie names used in cache block naming; used in
conjunction with autoType. See "More About Cache Block Naming
and the autoType Attribute".
default: null
4-208
reusableTimeStamp java.util.Date An absolute time limit for cache usability, where any cache block
created prior to that time will not be reused. Instead, data is
regenerated, but the cache block is unaltered. See "More About
reusableTimeStamp and reusableDeltaTime".
Note the following regarding reusableTimeStamp:
● It can be expressed as milliseconds between midnight,

January 1, 1970 and the desired absolute time limit, or as a
java.util.Date instance. Additional convenient formats are
available through the cache tag--see "Web Object Cache Tag
Descriptions".
● It takes precedence over reusableDeltaTime.
● If its value is set as the integer constant REUSABLE_ALWAYS or

the string constant REUSABLE_IGNORED, then cache entries
are always reusable, for as long as they remain in the cache.
● It is not available through the XML cache policy descriptor file.
default: always reusable

reusableDeltaTime long A relative time limit for cache usability, where a cache block is not
reused if the difference between cache block creation time and current
time is greater than reusableDeltaTime. Instead, data is
regenerated, but the cache block is unaltered. See "More About
reusableTimeStamp and reusableDeltaTime".
Note the following regarding reusableDeltaTime:
● It is specified in seconds.
● The reusableTimeStamp attribute overrides it.
● If its value is set as the integer constant REUSABLE_ALWAYS or

the string constant REUSABLE_IGNORED, then cache entries
are always reusable, for as long as they remain in the cache.
default: always reusable
4-209
ExpirationPolicy ExpirationPolicy An expiration policy object (an instance of
oracle.jsp.jwcache.ExpirationPolicy), which specifies
circumstances under which the repository will remove cache blocks
from storage.
default: the default expiration policy object
For information about expiration policy objects, parameters, and

defaults, see "Expiration Policy Attributes".
cacheRepositoryName String The name of the cache repository. Each cache policy can use its own
repository.
The configurations of cache repositories are defined in the /WEB-

INF/wcache.xml file.
default: "DefaultCacheRepository"
reportException boolean A false setting results in most cache operation failures being silent,
without any exception being reported to the browser.
Default: true
More About Cache Block Naming and the autoType Attribute
As discussed in "Cache Block Naming--Implicit Versus Explicit", cache blocks can be named
either implicitly, sometimes called auto-naming, or explicitly, sometimes called user-naming.
More specifically, there are six ways for cache blocks to be named. Explicit naming is the first way.
Specify this with an autoType setting of TYPE_USERSPECIFIED (an integer constant).
The other five ways are variations of implicit naming:
● implicit naming with only the request URI being used in the name
Specify this with an autoType setting of TYPE_URI_ONLY.
● implicit naming according to the following:
request URI + query string + selected cookies
Specify this with an autoType setting of TYPE_URI_QUERYSTR. Specify the cookies in the
selectedCookies[] attribute.
4-210
request URI + all parameters + selected cookies (default)
Specify this with an autoType setting of TYPE_URI_ALLPARAM. Specify the cookies in the
request URI + selected parameters + selected cookies
Specify this with an autoType setting of TYPE_URI_SELECTEDPARAM. Specify the

parameters in the selectedParameters[] attribute and the cookies in the
request URI + all but excluded parameters + selected cookies
Specify this with an autoType setting of TYPE_URI_EXCLUDEDPARAM. Specify the cookies

in the selectedCookies[] attribute, and specify the excluded parameters in the
selectedParameters[] attribute.
As an example, assume that you have developed a JSP page, welcome.jsp, with a personalized
greeting for each user. The data with the personalized greeting is the only cache block in the
page. Further assume that you have specified "request URI + selected parameters + selected
cookies" naming, with user as the only selected parameter for cache block naming and no
selected cookies for naming.
Now assume the page is requested as follows:
http://host:port/a.jsp?user=Amy
In this case, a.jsp?user=Amy becomes the cache block name.
Now assume that the page is later requested by another user, as follows:
http://host:port/a.jsp?user=Brian
4-211
This will not reuse the "Amy" cache, because the value of user is different. Instead, a new cache
block is created with a.jsp?user=Brian as the name.
Now assume a later request by the first user, as follows:
http://host:port/a.jsp?mypar=3&user=Amy
Because the user is again Amy, this request will reuse the first cache, displaying Amy's
personalized information without having to regenerate it. The mypar parameter is irrelevant to the
caching mechanism because you did not include it in the selectedParameters[] list of the
cache policy object (presumably because you determined that the value of mypar is not relevant
in terms of cachable page output).
Now assume the following subsequent request:
http://host:port/a.jsp?yourpar=4&user=Brian&hello=true&foo=barfly
Because the user is again Brian, this request will reuse the second cache, displaying Brian's
personalized information without having to regenerate it. The yourpar, hello, and foo
parameters are irrelevant to the caching mechanism because you did not include them in the
selectedParameters[] list of the cache policy object.
More About reusableTimeStamp and reusableDeltaTime
Be aware that the concept of reusable is different than the concept of time-to-live (TTL), and is
intended for more advanced use. Time-to-live, which controls the general lifetime of a cache, is
described in "Expiration Policy Attributes". Usually time-to-live is all that is required in terms of
appropriately limiting the use of cached data.
The attributes for reusability--reusableTimeStamp and reusableDeltaTime--are intended for

more specialized use and do not affect the expiration or invalidation of cached data. As an
example, consider a situation where different users have different requirements for how up-to-date
a Web report is. Assume that most users can accept a report produced anytime within the past
day, and that they all want to be looking at the same version so they can compare figures. An
appropriate TTL value, then, would be one day.
Also presume, however, that there is a small group of privileged users for whom the data is much
more time-sensitive. They want to have information that is no more than one hour old.
4-212
In this case, while TTL is set to one day for all users, there can be a reusableDeltaTime
setting of one hour for the privileged users, which will result in the cache not being used for them if
the data is more than one hour old. Remember, though, that reusableTimeStamp and
reusableDeltaTime do not expire the cache or otherwise affect it--the cached data can still be
used for non-privileged users, according to the time-to-live.
It is up to the application logic to set appropriate values of reusableTimeStamp and/or

reusableDeltaTime for the privileged user group.
Expiration Policy Attributes
Expiration policies are introduced in "Data Invalidation and Expiration". Expiration policies contain
the details that determine when cache blocks expire, at which point their data should no longer be
used and the data should be regenerated instead. (Note that for most discussion, you can think of
the expiration policies as being part of the cache policies.) ExpirationPolicy attributes, as with
CachePolicy attributes, can be set in several ways:
● in JSP pages through custom tags
● in servlets through method calls
See "ExpirationPolicy Methods".
● through a cache policy descriptor file
The following abbreviated code for the ExpirationPolicy class (in package
oracle.jsp.jwcache), provided for illustration purposes only, shows the names of the
expiration policy attributes:
class ExpirationPolicy
{
int expirationType;
long TTL;
long timeInaDay;
int dayInaWeek;
4-213
int dayInaMonth;
boolean writeThrough;
}
Table 7-2 describes the expiration policy object attributes.
Note:
The names documented below for integer constants are for servlet usage. Different names
may be used for the Web Object Cache tags. See "Web Object Cache cache Tag".
Table 7-2 Expiration Policy Attribute Descriptions
Attribute Type Description

expirationType int The type of expiration policy--one of the following (the TYPE_XXX values are integer
constants):
● time-to-live, specified with an expirationType setting of TYPE_TTL (also

see the TTL attribute below)
● daily (expire within a day, at a specified time), specified with an

expirationType setting of TYPE_DAILY (also see the timeInaDay
attribute below)
● weekly (expire within a week, on a specified day at a specified time), specified

with an expirationType setting of TYPE_WEEKLY (also see the
timeInaDay and dayInaWeek attributes below)
● monthly (expire within a month, on a specified date at a specified time),

specified with an expirationType setting of TYPE_MONTHLY (also see the
timeInaDay and dayInaMonth attributes below)
default: time-to-live
TTL long Time-to-live--the amount of time the cache block is good for, expressed in seconds.
default: 300 (5 minutes)
4-214
timeInaDay long The time of day used for daily, weekly, or monthly expiration, expressed in seconds
from midnight--0 is 00:00:00 (midnight); 86399 is 23:59:59.
default: 300 (00:05:00); ignored if expirationType=TYPE_TTL
dayInaWeek int The day of the week for weekly expiration (at the specified timeInaDay)--
WEEKLY_SUNDAY, WEEKLY_MONDAY, WEEKLY_TUESDAY, WEEKLY_WEDNESDAY,
WEEKLY_THURSDAY, WEEKLY_FRIDAY, or WEEKLY_SATURDAY (integer constants).
default: Wednesday; ignored unless expirationType=TYPE_WEEKLY
dayInaMonth int The date of the month for monthly expiration (such as 10 for the 10th of each month, at
the specified timeInaDay). The maximum setting is the number of days in the month
when the cache block is created. For example, if a cache block is created in June and
dayInaMonth has a setting of 31, then its effective value will be 30.
default: 10; ignored unless expirationType=TYPE_MONTHLY
writeThrough boolean A flag specifying whether the cache repository should treat the cache entry as a write-
through cache, writing it immediately into secondary storage (such as a file system or
database). Set this to true for write-through mode. A write-through cache will survive
a server restart or power failure.
With a false setting, the cache entry is treated as a delayed-write cache, which is
appropriate for caches that have a short life span (such as 5 or 10 minutes) and are
not overly expensive to recompute.
default: true
Note: some cache repositories may not support write-through mode; others may
always use write-through mode.
Web Object Cache Tag Descriptions
From JSP pages, you can specify cache policy settings, expiration policy settings, and explicit
invalidation through custom tags provided with OC4J. Discussion is organized into the following
categories:
● Cache Tag Descriptions
● Cache Invalidation Tag Description
To use the Web Object Cache tags, the tag library description file, jwcache.tld, must be
deployed with the application in the location specified in the taglib directives of your JSP pages,
such as in the following example:
4-215
<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %>
In an Oracle9i Application Server installation, the tag library description file is located in the
[Oracle_Home]/j2ee/tlds directory.
Notes:
● The prefix "ojsp:" is used in the tag syntax here. This is by convention but is not
● The Web Object Cache tag library is a standard library. For general information
about the standard JavaServer Pages tag library framework, refer to the Oracle9iAS
Containers for J2EE Support for JavaServer Pages Reference.
Cache Tag Descriptions
This section describes the following tags:
● cache
This is for general character-based caching (HTML or XML fragments).
● cacheXMLObj
This is for caching XML objects; its parameters comprise a superset of the cache tag
parameters. Because the Web Object Cache is particularly useful when post-processing
XML documents, you will likely use the cacheXMLObj tag more often than the cache tag.
● useCacheObj
This is for general caching of Java serializable objects. Some of the semantics and syntax
are patterned after the standard jsp:useBean tag.
● cacheInclude
4-216
This tag combines the functionality of the cache tags (cache and cacheXMLObj) and the
standard JSP include tag.
This section also describes conditional execution of code within the cache tags, possible resulting
problems, and the workaround of dividing cache blocks into individual JSP pages and, optionally,
using the cacheInclude tag to combine the pages together appropriately.
Web Object Cache cache Tag
This section documents the syntax and attributes of the cache tag, which you can use to set up
general caching, as opposed to caching of XML objects or Java serializable objects, in a JSP
application.
Note:
For caching XML objects, use the cacheXMLObj tag instead. For caching Java serializable
objects, use the useCacheObj tag. These tags supports all the cache tag attributes
described here. See "Web Object Cache cacheXMLObj Tag" and "Web Object Cache
useCacheObj Tag".
Syntax
<ojsp:cache
[ policy = "filename" ]
[ ignoreCache = "true" | "false" ]
[ invalidateCache = "true" | "false" ]
[ scope = "application" | "session" ]
[ autoType = "user" | "URI" | "URI_query" | "URI_allParam" |
"URI_selectedParam" | "URI_excludedParam" ]
[ selectedParam = "space-delimited_string_of_parameter_names" ]
[ selectedCookies = "space-delimited_string_of_cookie_names" ]
[ reusableTimeStamp = "yyyy.mm.dd hh:mm:ss z" |
"yyyy.mm.dd hh:mm:ss" | "yyyy.mm.dd"| "ignored" ]
[ reusableDeltaTime = "number" | "ignored" ]
[ name = "blockname" ]
[ expirationType = "TTL" | "daily" | "weekly" | "monthly" ]
[ TTL = "number" ]
[ timeInaDay = "number" ]
[ dayInaWeek = "Sunday" | "Monday" | "Tuesday" | "Wednesday" |
"Thursday" | "Friday" | "Saturday" ]
[ dayInaMonth = "number" ]
4-217
[ writeThrough = "true" | "false" ]
[ printCacheBlockInfo = "true" | "false" ]
[ printCachePolicy = "true" | "false" ]
[ cacheRepositoryName = "name" ]
[ reportException = "true" | "false" ] >
...Code for cache block...
</ojsp:cache>
Notes:
● This tag can optionally be in the form of a single tag with no body: <ojsp:cache
... />
● Key default values are as follows: TTL defaults to 300 seconds; dayInaMonth
defaults to 10 (10th of the month); cache repository name defaults to
DefaultCacheRepository.
Attributes
Most of the parameters of the cache tag correspond to attributes in the CachePolicy or
ExpirationPolicy class, described earlier in this chapter (as referenced below).
● policy--Optionally use this to specify a cache policy descriptor, whose settings would be
used in defining the cache policy. You can use a cache policy descriptor instead of using
the various individual cache tag attribute settings, or to establish default values that you can
optionally override through tag attribute settings.
Specify the descriptor file name according to JSP 1.1 application-relative syntax. You can
refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for
information about application-relative syntax.
Here is a simple example of a cache policy descriptor:

<cachePolicy scope="application">
4-218
<expirationPolicy expirationType="TTL" TTL="25" timeInaDay="00:10:00"
writeThrough="true" />
</cachePolicy>
See "Cache Policy Descriptor" for more information.
● ignoreCache--See "Cache Policy Attributes".
● invalidateCache--Enable this flag for the corresponding cache block (any pre-existing
cache block with the same name) to first be invalidated. This is particularly useful where
implicit cache block naming is used, but can also be used for explicit names by specifying
the cache block name in the name attribute of the cache tag.
Note:
Do not confuse this attribute with the more general-purpose invalidateCache tag.
See "Web Object Cache invalidateCache Tag". The invalidateCache attribute is
for more specialized or advanced use to invalidate individual cache blocks.
● scope--See "Cache Policy Attributes".
● autoType--See "Cache Policy Attributes". The correspondence between tag attribute

settings and class attribute values (integer constants) is as follows:
❍ user is equivalent to TYPE_USERSPECIFIED.
❍ URI is equivalent to TYPE_URI_ONLY.
❍ URI_query is equivalent to TYPE_URI_QUERYSTR.
❍ URI_allParam is equivalent to TYPE_URI_ALLPARAM.
❍ URI_selectedParam is equivalent to TYPE_URI_SELECTEDPARAM.
❍ URI_excludedParam is equivalent to TYPE_URI_EXCLUDEDPARAM.
4-219
● selectedParam--See "Cache Policy Attributes".
● selectedCookies--See "Cache Policy Attributes".
● reusableTimeStamp--See "Cache Policy Attributes".
● reusableDeltaTime--See "Cache Policy Attributes".
● name--Where explicit cache-block naming is used, use the name parameter to specify the
block name.
● expirationType--See "Expiration Policy Attributes".
● TTL--See "Expiration Policy Attributes".
● timeInaDay--See "Expiration Policy Attributes".
● dayInaWeek--See "Expiration Policy Attributes".
● dayInaMonth--See "Expiration Policy Attributes".
● writeThrough--See "Expiration Policy Attributes".
● printCacheBlockInfo (for debugging)--Enabling this parameter results in printing of the

internal cache name, creation time, and expiration time of the cache block (within
HTML/XML comment constructs).
● printCachePolicy (for debugging)--Enabling this parameter results in printing of the

values of all cache policy attributes for this cache block (within HTML/XML comment
constructs).
● cacheRepositoryName--See "Cache Policy Attributes".
● reportException--See "Cache Policy Attributes".
4-220
Usage Notes
● The name attribute is relevant only when autoType is set to user.
● The selectedParam attribute is relevant only when autoType is set to

URI_selectedParam or URI_excludedParam.
● The selectedCookies attribute is not relevant when autoType is set to user or URI.
● The timeInaDay attribute is not relevant when expirationType is set to TTL.
● The dayInaWeek attribute is relevant only when expirationType is set to weekly.
● The dayInaMonth attribute is relevant only when expirationType is set to monthly.
Example: cache Tag
This example lists and caches a set of items, using the cache tag.

<title>listitem.jsp</title>
<%
String itemid=request.getParameter("itemid");
if (itemid==null) {
out.println("Please select a category from the above drop down box.");
return;
}
%>
<% long l1=(new java.util.Date()).getTime(); %>
<ojsp:cache autoType="URI_selectedParam" selectedParam="itemid"
printCacheBlockInfo="true" printCachePolicy="true"
policy="/WEB-INF/test-policy.cpd"
>
Item List: <b><%= itemid %></b><br>
Time: <%= new java.util.Date() %>
<br>
<jsp:useBean class="java.util.Hashtable" id="table" scope="application" />
<hr>
<%
Vector list=(Vector) table.get(itemid);
4-221
if (list==null) {
out.println("No such item!");
}
else {
for (int i=0; i<list.size(); i++) {
%>
<%= list.elementAt(i) %><br>
<%
}
}
%>
timestamp:<%= new java.util.Date() %>
<br>
</ojsp:cache>
Time for general cache operation:<%= l2-l1 %>
<br>
Web Object Cache cacheXMLObj Tag
Generally speaking, use the cacheXMLObj tag instead of the cache tag if you are caching XML
DOM objects.
The cacheXMLObj tag supports all the cache tag attributes described in "Web Object Cache
cache Tag", as well as the following.
Syntax (in addition to that of the cache tag)
<ojsp:cacheXMLObj
...
[ fromXMLObjName = "objectname" ]
[ toXMLObjName = "objectname" ]
[ toWriter = "true" | "false" ] >
</ojsp:cacheXMLObj>
4-222
Notes:
● This tag can optionally be in the form of a single tag with no body:
<ojsp:cacheXMLObj ... />
● For convenience, this tag is duplicated in the XML tag library, in the xml.tld tag
library description file.
● This tag can act as both an XML producer and an XML consumer. Do not use
fromXMLObjName and toXMLObjName if the XML object is being passed implicitly.
(See "XML Producers and XML Consumers".)
Attributes (in addition to those of the cache tag)
● fromXMLObjName--For explicit passing, specify the name of the XML input object being
passed to the cache (from the PageContext object).
● toXMLObjName--For explicit passing, specify the name of the XML output object being
passed from the cache (to the PageContext object).
● toWriter--Set this to true to write the XML object to a JSP writer to output directly to the
user's browser.
Note:
The cacheXMLObj tag is one of several custom tags supplied with OC4J that are
XML-related, meaning these tags sometimes (or always) take an XML object as input
or create one as output. Other such tags include the SQL library dbQuery tag, which
can output query results as an XML DOM object, and the XML library transform tag,
which can take an XML object as input and use XSLT transformation to create another
XML object or a JSP writer as output. These tags are consistent in having a
fromXMLObjName attribute and a toXMLObjName attribute for explicit passing of
XML data. For general information, see "XML Producers and XML Consumers".
Example: cacheXMLObj Tag
4-223
This example uses Web Object Cache tags, JESI tags, and tags from the XML and SQL tag
libraries. (For JESI tag descriptions, see "Oracle JESI Tag Descriptions". For a description of the
XML transform tag, see "XML Utility Tags". For SQL tag descriptions, see "SQL Tags for Data
Access".)
The sql:dbOpen and sql:dbQuery tags connect to the database and execute a query. The
cacheXMLObj tag caches the XML DOM object produced by the query--in subsequent executions
(for output through different stylesheets, for example), the query does not have to be re-executed
because the DOM object can be retrieved from the Web Object Cache. The XML transform tag
outputs the query results according to an XML stylesheet (specified through a variable). The
jesi:fragment tag encloses HTML output to be cached (which does not require application-
level caching). The jesi:template tag disables caching outside the fragment (through the
cache="no" setting).
<jesi:template cache="no">
<% String userStyleLoc="style/rowset.xsl"; %>
<h3>Transform DBQuery Tag Example</h3>
<h4>Current Time=<%= new java.util.Date() %></h4>

<h4>Cached Time=<%= new java.util.Date() %></h4>
<sql:dbOpen connId="conn1" URL="<%= connStr %>"
user="scott" password="tiger" />
<xml:transform href="<%= userStyleLoc %>" >
<%-- The XML DOM object is produced by dbQuery
And, the DOM object is cached in Oracle Web Object Cache.
XSLT is performed on the cached object. --%>
<ojsp:cacheXMLObj TTL="60" toWriter="false">
<sql:dbQuery connId="conn1" output="xml" queryId="myquery" >
select ENAME, EMPNO from EMP
</sql:dbQuery>
</ojsp:cacheXMLObj>
</xml:transform>
<sql:dbCloseQuery queryId="myquery" />
<sql:dbClose connId="con1" />
</jesi:fragment>
</jesi:template>
Web Object Cache useCacheObj Tag
Use the useCacheObj tag to cache any Java serializable object.
4-224
The useCacheObj tag supports all the cache tag attributes described in "Web Object Cache
cache Tag", as well as the following.
Syntax (in addition to that of the cache tag)
<ojsp:useCacheObj
...
type="classname"
id = "instancename"
[ cacheScope = "application" | "session" ] >
</ojsp:useCacheObj>
Notes:
● This tag can optionally be in the form of a single tag with no body:
<ojsp:useCacheObj ... />
● The id and type attributes are not request-time attributes, so cannot be set using
JSP runtime expressions.
Attributes (in addition to those of the cache tag)
● type (required)--Specify the class name of the Java object to cache.
● id (required)--Specify the instance name of the Java object to cache.
● cacheScope--This has the same usage as the scope attribute in the cache and
cacheXMLObj tags. See "Cache Policy Attributes".
The type and id attributes here are used similarly to the type (or class) and id attributes in a
standard jsp:useBean tag.
Example: useCacheObj Tag
4-225
<ojsp:useCacheObj id="a2" policy="/WEB-INF/test-policy.cpd"
type="examples.RStrArray" >
<%
// create a temp writeable array
WStrArray tmpa2=new WStrArray(3);
tmpa2.setStr(2,request.getParameter("testing4"));
tmpa2.setStr(1,"def");
tmpa2.setStr(0, (new java.util.Date()).toString() );
// create a readonly copy for the cache
a2=new RStrArray(tmpa2);
// storing the a2 into pagecontext
// so useCacheObj tag can pick it up
pageContext.setAttribute("a2",a2);
%>
</ojsp:useCacheObj>
Conditional Execution of Code Inside the Cache Tags
Be aware that code inside a cache tag (cache, cacheXMLObj, or useCacheObj) is executed
conditionally. In particular:
● Any code inside a cache tag is executed only when the associated cache block is not
reused.
Consider the following example:
<% String s=null; %>

<% ojsp:useCacheObj ... >
<% s = "abc"; //...more Java code...%>
</ojsp:useCacheObj>
<% out.print(s.length()); // May cause null pointer exception
If the cache is available and reused, the code to properly initialize the string s would not be
executed.
● If you put a method-based variable declaration inside a cache tag, the variable will not be
available outside the tag.
Consider the following example:
<ojsp:useCacheObj ... >

<% String s = "abc"; //...more Java code...%>
4-226
</ojsp:useCacheObj>
<% // String s will not be available here %>
If you are using a the cache tag (not cacheXMLObj or useCacheObj), it might be helpful to
break your cache blocks into separate JSP pages so that you would be less likely to fall into this
type of situation. In this case, each cache block would be represented by its own URI, and you
could use dynamic include functionality to combine the pages together as desired.
To make this more convenient, Oracle also provides the cacheInclude tag, described in "Web
Object Cache cacheInclude Tag" below.
Web Object Cache cacheInclude Tag
The cacheInclude tag combines functionality of the cache tag (but not the cacheXMLObj tag
or useCacheObj tag) and the standard jsp:include tag.
There are a number of advantages in putting cache blocks into separate pages and using
cacheInclude, including general considerations of modularity and clarity as well as the issues
discussed in "Conditional Execution of Code Inside the Cache Tags" above.
Be aware of the following limitations, however:
● You cannot use a runtime JSP expression in the cacheInclude tag.
● You must use implicit cache-block naming for the cache block.
● There is no flush parameter (unlike for the standard jsp:include tag).
If any of these limitations presents a problem, then use separate cache and include tags.
Also be aware of an important difference between the cacheInclude tag and the
jesi:include tag. (See "JESI include Tag" for information about that tag.) Because the
Oracle9iAS Web Cache is in a different caching layer than the Web Object Cache, the including
page and included page for a jesi:include tag cannot share the same request object. There is
no such limitation with the cacheInclude tag, however--the including page and included page
share the same request object, so beans and attributes of request scope can be passed
between the two pages.
4-227
Syntax
<ojsp:cacheInclude
policy = "filename"
page = "URI"
[ printCacheBlockInfo = "true" | "false" ]
[ reportException = "true" | "false" ] >
</ojsp:cacheInclude>
Note:
For the cacheInclude tag, policy and page are not request-time attributes, so you do
not have the option of determining their values through JSP expressions. (Be aware that
policy is a request-time attribute for the cache, cacheXMLObj, and useCacheObj tags.)
Attributes
● policy (required)--You must use a cache policy descriptor file to specify cache policy
settings (individual parameter settings are not supported).
● page (required)--Use the page attribute to specify the URI of the page to dynamically
include (as with a standard jsp:include tag).
● printCacheBlockInfo (for debugging)--See "Web Object Cache cache Tag".
Usage Notes
Consider the following cacheInclude tag usage:
<ojsp:cacheInclude page="anotherPage.jsp" policy="foo.cpd" >
This is equivalent to the following:
4-228
<ojsp:cache policy="foo.cpd" >
<% pageContext.include("anotherPage.jsp"); %>
</ojsp:cache>
or the following:
<jsp:include page="anotherPage.jsp" flush="true" />
where anotherPage.jsp consists of the following:
<ojsp:cache policy="foo.cpd" >

...anotherPage.jsp contents...
</ojsp:cache>
Cache Invalidation Tag Description
This section describes how to use the invalidateCache tag.
Web Object Cache invalidateCache Tag
To explicitly invalidate a cache block through program logic, you can use the invalidateCache
tag. This section documents the syntax and attributes of this tag.
Notes:
● The invalidateCache tag does not accept new cookies; it can only use existing
cookies of the current HTTP request. (For information about inputting new cookies,
see "CachePolicy Methods".)
● Do not confuse the invalidateCache tag with the invalidateCache attribute of

the cache tags. The attribute is for more limited use--to invalidate the pre-existing
cache object.
Syntax
<ojsp:invalidateCache
4-229
[ policy = "filename" ]
[ ignoreCache = "true" | "false" ]
[ scope = "application" | "session" ]
[ autoType = "user" | "URI" | "URI_query" | "URI_allParam" |
"URI_selectedParam" | "URI_excludedParam" ]
[ selectedParam = "space-delimited_string_of_parameter_names" ]
[ selectedCookies = "space-delimited_string_of_cookie_names" ]
[ name = "blockname" ]
[ invalidateNameLike = "true" | "false" ]
[ page = "URI" ]
[ autoInvalidateLevel = "application" | "page" | "param" | "cookie" ]
[ cacheRepositoryName = "name" ]
[ reportException = "true" | "false" ] />
Note:
The default for autoInvalidateLevel depends on specifics of the page URI. See "Use of
page and autoInvalidateLevel" below.
Attributes
Most parameters of the invalidateCache tag also exist in the cache and cacheXMLObj tags
and are used in the same way, as described earlier in this chapter (and as referenced below).
● policy--See "Web Object Cache cache Tag".
● scope--See "Cache Policy Attributes".
● autoType--See "Cache Policy Attributes". The correspondence between tag attribute

settings and class attribute values (integer constants) is as follows:
❍ user is equivalent to TYPE_USERSPECIFIED.
❍ URI is equivalent to TYPE_URI_ONLY.
❍ URI_query is equivalent to TYPE_URI_QUERYSTR.
4-230
❍ URI_allParam is equivalent to TYPE_URI_ALLPARAM.
❍ URI_selectedParam is equivalent to TYPE_URI_SELECTEDPARAM.
❍ URI_excludedParam is equivalent to TYPE_URI_EXCLUDEDPARAM.
● selectedParam--See "Cache Policy Attributes".
● selectedCookies--See "Cache Policy Attributes".
● name--Use this with invalidateNameLike to invalidate one or more cache blocks that
were named through explicit cache-block naming, according to the instructions in "Use of
name and invalidateNameLike" below.
● invalidateNameLike--Use this with name to invalidate one or more cache blocks that
were named through explicit cache-block naming, according to the instructions in "Use of
name and invalidateNameLike" below.
● page--Specify a page-relative or application-relative URI. Use this with

autoInvalidateLevel to invalidate one or more cache blocks that were named through
implicit cache-block naming, according to the instructions in "Use of page and
autoInvalidateLevel" below.
● autoInvalidateLevel--Use this with page to invalidate one or more cache blocks that
were named through implicit cache-block naming, according to the instructions in "Use of
page and autoInvalidateLevel" below.
● cacheRepositoryName--See "Cache Policy Attributes".
Use of name and invalidateNameLike
To invalidate one or more cache blocks that were named through explicit cache-block naming, use
the name and invalidateNameLike attributes together, as follows:
4-231
If invalidateNameLike="false", then use the name parameter to specify the name of a
single cache block to invalidate.
If invalidateNameLike="true", and the underlying cache repository supports wild card

characters, then you can use the wildcard "*" character in the name parameter to invalidate
multiple cache blocks whose names fit the criteria. (The Oracle9i Application Server Java Object
Cache currently does not support wild card characters.)
Use of page and autoInvalidateLevel
To invalidate one or more cache blocks that were named through implicit cache-block naming, use
the page and autoInvalidateLevel attributes together, as follows:
Use the page attribute to specify the appropriate URI of the Web page. (With implicit naming,
cache block names are based on Web page URIs.)
Use autoInvalidateLevel to specify the scope of invalidation--application scope, page scope,

parameter scope, or cookie scope--as follows:
● If autoInvalidateLevel="application", then all cache blocks associated with the

application that the page belongs to will be invalidated.
For example, if there is an application under the /mycontext context path, and
autoInvalidateLevel="application", then all cache entries of all pages under
http://host:port/mycontext will be invalidated.
Here is a corresponding usage example:
<ojsp:invalidateCache page="/" autoInvalidateLevel="application" />
● If autoInvalidateLevel="page", then all cache block entries associated with the page
will be invalidated.
For example, if autoInvalidateLevel="page" and the request is the following:
http://host:port/mycontext/mypage01.jsp?foo=bar
then all cache entries of mypage01.jsp will be invalidated, regardless of what request
4-232
parameters and cookies they are associated with. This includes cache blocks associated
with the following, for example:
http://host:port/mycontext/mypage01.jsp?p1=v1
Here is a corresponding usage example:
<ojsp:invalidateCache page="/mypage01.jsp" autoInvalidateLevel="page" />
● If autoInvalidateLevel="param", then all cache entries of the page that have the
identical selected parameter names and values will be invalidated, regardless of what
cookies they are associated with.
For example, consider the following:
<ojsp:invalidateCache policy="/WEB-INF/c1.cpd"
page="/mypage01.jsp?foo=bar"
autoInvalidateLevel="param" />
In this case, cache blocks associated with the following, for example, will not be invalidated:
http://host:port/mycontext/mypage01.jsp?foo=bar2
But cache blocks associated with the following will be invalidated, regardless of what
cookies they are associated with:
http://host:port/mycontext/mypage01.jsp?foo=bar
Continuing this example, consider the following:
http://host:port/mycontext/mypage01.jsp?foo=bar&p1=v1
Cache blocks associated with this request will be invalidated if c1.cpd selects the foo
HTTP request parameter only, and the cache blocks are stored under the same cache
policy, c1.cpd. However, the cache objects will not be invalidated if they were not stored
4-233
under c1.cpd, or if c1.cpd also selects the p1 parameter.
● If autoInvalidateLevel="cookie", then the only cache entries invalidated are those

associated with the same page, same selected parameters and values, and same cookies.
Note:
If the page URI includes a question mark, then the default value of
autoInvalidateLevel is param. If there is no question mark, then the default
value is page.
Example--Use of Cache Invalidation Tag
Example: invalidateCache Tag
The following page adds an item to list of items previously cached, then invalidates the cache.
(The list will presumably be re-cached later with the new item.)

<title>added.jsp</title>
<jsp:useBean class="java.util.Hashtable" id="table" scope="application" />
<%
String itemid=request.getParameter("itemid");
String addItem=request.getParameter("addItem");
Vector list=(Vector) table.get(itemid);
if (list==null) {
list=new Vector();
table.put(itemid,list);
}
list.addElement(addItem);
%>
<b><%= addItem %></b> was added into category <b><%= itemid %></b>.<br>
<% String viewPage="listitem.jsp?itemid="+itemid; %>
<ojsp:invalidateCache page="<%= viewPage %>" autoInvalidateLevel="param"
policy="/WEB-INF/test-policy.cpd"
/>
Existing cache entry has been invalidated. <br>
Invalidation took <%= l2-l1 %> milliseconds.
<br>
<jsp:include page="<%= viewPage %>" flush="true" />
<br>
4-234
<a href="seeitems.jsp" >Select items</a>
or
<a href="additem.html" >Add items</a>
<br>
Web Object Cache Servlet API Description
From servlets (or JSP scriptlets), you can use CachePolicy methods to modify cache policy
settings or to invalidate a cache block, and ExpirationPolicy methods to modify expiration
settings. This requires creating a cache policy object and retrieving its expiration policy object
attribute (which the JSP cache tag handlers do automatically).
This section discusses the following:
● Cache Policy Object Creation
● CachePolicy Methods
● Expiration Policy Object Retrieval
● ExpirationPolicy Methods
● CacheBlock Methods
● Sample Servlet Using the Web Object Cache API
For more information about the classes, interfaces, and methods described in this section, see the
Javadoc that is supplied with OC4J.
Cache Policy Object Creation
There are two approaches to creating a CachePolicy object:
● Use the static lookupPolicy() method of the CacheClientUtil class.
● Use one of the public CachePolicy constructors.
4-235
Note:
Cache policy objects are not resource objects (such as database connections or
cursors), so you can manipulate them without life-cycle or resource management
concerns.
Using the lookupPolicy() Method
In most situations, the most convenient way to create a CachePolicy object is through the static
lookupPolicy() method of the CacheClientUtil class, provided with OC4J, as in the
following example:
CachePolicy cachePolicyObject = oracle.jsp.jwcache.CacheClientUtil.lookupPolicy

(servletConfig, request, "/WEB-INF/foo.cpd");
Input a servlet configuration object (a javax.servlet.ServletConfig instance), a request

object (a javax.servlet.http.HttpServletRequest instance), and the URI path (relative
to the application root) of an XML cache policy descriptor file.
Here is a simple example of a cache policy descriptor file:

</cachePolicy>
See "Cache Policy Descriptor" for more information.
Using a CachePolicy Constructor
The oracle.jsp.jwcache.CachePolicy class has the following public constructors--a simple

constructor requiring only a servlet configuration object, a "copy" constructor that copies another
CachePolicy object, and a "copy" constructor with a given servlet configuration object:
public CachePolicy(javax.servlet.ServletConfig config)
4-236
public CachePolicy(CachePolicy cPolicy)
public CachePolicy(javax.servlet.ServletConfig config,

CachePolicy cPolicy)
CachePolicy Methods
A number of utility methods are available in CachePolicy objects, as well as getter and setter
methods for key attributes.
CachePolicy Method Signatures and Common Parameters
The following abbreviated code, for illustration purposes only, contains signatures for key methods
available in CachePolicy objects.
See "Cache Policy Attributes" for a discussion of relevant attributes.
class CachePolicy
{
boolean isRecent(CacheBlock block);
void putCache(Object data, HttpServletRequest req, SectionId sectionId);
void putCache(Object data, HttpServletRequest req, String specifiedName);
void putAutoCacheForOtherPath(Object data, HttpServletRequest req,
String otherPath, StringSectionid sectionId);
void putAutoCacheForOtherPath(Object data, HttpServletRequest req,
String otherPath, Cookie[] newCookies, StringSectionid sectionId);
CacheBlock getCache(HttpServletRequest req, SectionId sectionId);
CacheBlock getCache(HttpServletRequest req, String specifiedName);
CacheBlock getAutoCacheForOtherPath(HttpServletRequest req,
String otherPath, StringSectionId sectionId);
CacheBlock getAutoCacheForOtherPath(HttpServletRequest req,
String otherPath, Cookie[] newCookies, StringSectionId sectionId);
void invalidateCache(HttpServletRequest req, SectionId sectionId);
void invalidateCache(HttpServletRequest req, String specifiedName);
void invalidateCacheLike(HttpServletRequest req, String specifiedName);
void invalidateCacheLike(HttpServletRequest req, int autoInvalidateLevel);
void invalidateCacheLike(HttpServletRequest req, String specifiedName,
int autoInvalidateLevel);
void invalidateCacheOtherPathLike(HttpServletRequest req, String otherPath);
void invalidateCacheOtherPathLike(HttpServletRequest req, String otherPath,
Cookie[] newCookies, int autoInvalidateLevel);
Date getCurrentTime();
}
4-237
These methods use several common parameters:
● req, a javax.servlet.http.HttpServletRequest instance
This is the current HTTP request object.
● newCookies, a javax.servlet.http.Cookie[] array
This is an array of new cookies. If you pass in new cookies, they are used in cache
operations that use the otherPath parameter (such as the
putAutoCacheForOtherPath() method), assuming the cache policy selects some
cookies and invalidation is at the cookie level. If you do not pass in new cookies, then
cookies of the current HTTP request would be used instead.
● specifiedName, a Java string
For explicit cache-block naming, this is the name--either the desired cache block name if
you are creating a new cache block, or the existing cache block name if you are retrieving
an existing cache block.
● sectionId, an oracle.jsp.jwcache.SectionId instance (specifically,

StringSectionId or NumberSectionId)
For implicit cache-block naming, this is a counter that is used in tracking cache blocks. In
JSP pages it is used, incremented, and maintained by JSP cache tag handlers. It is stored
in the JSP PageContext object.
SectionId is an interface that is implemented by two classes--StringSectionId and

NumberSectionId. Where StringSectionId is specified in a method signature, you
must use an instance of that class. Where SectionId is specified, you can use an
instance of either class. Typically you should use StringSectionId, however.
NumberSectionId is primarily intended for use by tag handlers in JSP pages.
In a servlet, you must create a section ID instance manually. "Sample Servlet Using the
Web Object Cache API" demonstrates the use of a StringSectionId instance.
4-238
Note:
When you construct a StringSectionId instance, the string must begin with an
alphabetic (not numeric) character.
● otherPath, a Java string
The URI of another JSP page that has an associated cache block that you want to store,
retrieve, or invalidate.
● autoInvalidateLevel, an integer
For implicit cache-block naming, you can use this to specify a level of invalidation--
application, page, parameter, or cookie. Use the CachePolicy integer constant
AUTO_INVALIDATE_APP_LEVEL, AUTO_INVALIDATE_PAGE_LEVEL,
AUTO_INVALIDATE_PARAM_LEVEL, or AUTO_INVALIDATE_COOKIE_LEVEL.
CachePolicy Method Descriptions
The CachePolicy methods function as follows:
● isRecent()
This method checks the timestamp of the specified cache block and determines whether it
is recent enough, given the current time and the values of the cache policy
reusableTimeStamp and reusableDeltaTime attributes.
● putCache()
Use this method to place an object into the cache repository. The data parameter is any
serializable Java object you want to cache that will not require any further modification or
mutation. In JSP pages, the JSP cache tag handler calls putCache() to cache a
BodyContent instance. The cacheXMLObj tag handler calls it to cache an XML DOM
object. In a servlet or useCacheObj tag, the cache target object can be any Java
serializable object.
You must also provide an HTTP request object and a cache block name (for explicit
naming) or a section ID (for implicit naming).
4-239
Note:
The putCache() method does nothing if the cache policy ignoreCache attribute is
true.
● putAutoCacheForOtherPath()
Place an object into the cache repository according to a specified string-based section ID
and a specified page path. The cache policy must not use explicit naming (in other words,
must not have autoType=TYPE_USERSPECIFIED).
● getCache()
Use this method to retrieve a cached item from the repository, in the form of an
oracle.jsp.jwcache.CacheBlock instance. You can specify the cache block name
(for explicit naming) or the section ID (for implicit naming). You must also provide an HTTP
request object.
Note:
The getCache() method does nothing if the cache policy ignoreCache attribute is
true.
● getAutoCacheForOtherPath()
Retrieve a cached item from the repository according to a specified string-based section ID
and a specified page path. The cache policy must not use explicit naming (in other words,
must not have autoType=TYPE_USERSPECIFIED); otherwise, an exception is thrown).
● invalidateCache()
Use this method to invalidate a single cache block, according to the HTTP request object
and the specified cache block name (for explicit naming) or the section ID (for implicit
naming).
4-240
● invalidateCacheLike()
Use this method to invalidate multiple cache blocks. If you use explicit cache-block naming
and the cache repository supports wild-card naming, you can input the specifiedName
parameter with "*" wild card characters. (The Oracle9i Application Server Java Object
Cache currently does not support wild card characters.)
If you use implicit cache-block naming, you must specify the autoInvalidateLevel
parameter to determine, in combination with the HttpServletRequest object, what
cache blocks are invalidated. The autoInvalidateLevel parameter has the same
functionality as in a JSP invalidateCache tag, as explained in "Web Object Cache
invalidateCache Tag" (using information from the request object, as opposed to using
information from the page parameter of the invalidateCache tag).
● invalidateCacheOtherPathLike()
Use this method to invalidate cache blocks associated with the URI you provide in the
otherPath parameter. In the signature taking only a request object and the URI, the
autoInvalidateLevel parameter is set automatically according to the URI--to param
level if there is a question mark ("?") in the URI; to page level otherwise.
The detailed signature of this method allows you to specifically control the
autoInvalidateLevel setting and the cookies used in invalidation.
● getCurrentTime()
Retrieve the current time value, as a java.util.Date instance, of the underlying cache
repository specified in this cache policy.
CachePolicy Getter and Setter Methods
You can use the following methods to retrieve or alter CachePolicy object attributes.
See "Cache Policy Attributes" for a discussion of these attributes.
● boolean getIgnoreCache()
● void setIgnoreCache(boolean ignoreCache)
4-241
● void setIgnoreCache(String ignoreCacheStr)
● int getScope()
● void setScope(int scope)
For scope values, the integer constants SCOPE_APP and SCOPE_SESSION are available.
● int getAutoType()
● void setAutoType(int autoType)
For autoType values, the integer constants TYPE_USERSPECIFIED, TYPE_URI_ONLY,

TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM, and
TYPE_URI_EXCLUDEDPARAM are available.
● String[] getSelectedParam()
● void setSelectedParam(String[] selectedParameters)
● void setSelectedParam(String selectedParamStr)
● String[] getSelectedCookies()
● void setSelectedCookies(String[] selectedCookies)
● void setSelectedCookies(String selectedCookiesStr)
● Date getReusableTimeStamp()
● void setReusableTimeStamp(Date reusableTimeStamp)
● void setReusableTimeStamp(long reusableTimeStamp)
For reusableTimeStamp values, the integer constant REUSABLE_ALWAYS is available,

4-242
indicating that the cache is always reusable.
● long getReusableDeltaTime()
● void setReusableDeltaTime(long reusableDeltaTime)
For reusableDeltaTime values, the integer constant REUSABLE_ALWAYS is available,

● ExpirationPolicy getExpirationPolicy()
● void setExpirationPolicy(ExpirationPolicy
expirationPolicy)
● String getCacheRepositoryName()
● void setCacheRepositoryName(String repoName)
● boolean getReportException()
● void setReportException (boolean reportException)
● void setReportException (String reportExceptionStr)
The following methods are also available, but are primarily intended for use by the Web Object
Cache tags:
● void setScope(String scopeStr)
For scope values, the string constants SCOPE_APP_STR and SCOPE_SESSION_STR are
available.
● void setAutoType(String autoTypeStr)
● void setReusableTimeStamp(String reusableTimeStampStr)
4-243
For reusableTimeStamp values, the string constant REUSABLE_IGNORED is available,
● void setReusableDeltaTime(String reusableDeltaTimeStr)
For reusableDeltaTime values, the string constant REUSABLE_IGNORED is available,

Expiration Policy Object Retrieval
Each CachePolicy object has an ExpirationPolicy attribute. If you want to set expiration
policies for a cache block, you can use the getExpirationPolicy() method of its
CachePolicy object, as in the following example:
CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy

(config, request, "/WEB-INF/mypolicy.cpd");
ExpirationPolicy expPolicyObj = cachePolicyObj.getExpirationPolicy();
ExpirationPolicy Methods
The ExpirationPolicy class has getter and setter methods for its attributes, as follows. For
descriptions of these attributes, see "Expiration Policy Attributes".
● int getExpirationType()
● void setExpirationType(int expirationType)
● void setExpirationType(String expirationTypeStr)
● long getTTL()
● void setTTL(long ttl)
● long getTimeInaDay()
● void setTimeInaDay(long timeInaDay)
4-244
● void setTimeInaDay(String timeInaDayStr)
● int getDayInaWeek()
● void setDayInaWeek(int dayInaWeek)
● void setDayInaWeek(String dayInaWeekStr)
● int getDayInaMonth()
● void setDayInaMonth(int dayInaMonth)
● boolean getWriteThrough()
● void setWriteThrough(boolean writeThrough)
● void setWriteThrough(String writeThroughStr)
Additionally, the ExpirationPolicy class has the following utility method:
● long getExpirationTime(long createTime)
Given the creation time of a cache block (in terms of milliseconds since midnight January 1,
1970), this method calculates and returns the expiration time (also in milliseconds since
midnight January 1, 1970). That is, the timestamp when expiration should occur, according
to the expiration policy.
The ExpirationPolicy class also defines the following integer constants for the
expirationType attribute:
● TYPE_TTL
● TYPE_DAILY
4-245
● TYPE_WEEKLY
● TYPE_MONTHLY
And the following integer constants are defined for the dayInaWeek attribute:
● WEEKLY_SUNDAY
● WEEKLY_MONDAY
● WEEKLY_TUESDAY
● WEEKLY_WEDNESDAY
● WEEKLY_THURSDAY
● WEEKLY_FRIDAY
● WEEKLY_SATURDAY
CacheBlock Methods
You can use the getCache() method of a CachePolicy object to retrieve the associated
CacheBlock object (as documented in "CachePolicy Methods" and shown in "Sample Servlet
Using the Web Object Cache API" below).
The following abbreviated code shows the key methods of the

oracle.jsp.jwcache.CacheBlock class:
class CacheBlock
{
long getCreationTime();
long getExpirationTime();
Serializable getData();
}
4-246
Here are brief descriptions of these methods:
● getCreationTime()--Returns the timestamp from when the cache block was created.
● getExpirationTime()--Returns the timestamp for the expiration time of the cache block.
● getData()--Returns the cache block data. Use of this method is also shown in "Sample
Servlet Using the Web Object Cache API" below.
Note:
Creation time and expiration time are expressed in milliseconds since midnight,
January 1, 1970.
Sample Servlet Using the Web Object Cache API
The following sample servlet uses the Web Object Cache. The code is followed by notes about
some of its operations.
Sample Code--DemoCacheServlet.java
package demoPkg;
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.CharArrayWriter;
import oracle.jsp.jwcache.CachePolicy;
import oracle.jsp.jwcache.ExpirationPolicy;
import oracle.jsp.jwcache.StringSectionId;
import oracle.jsp.jwcache.CacheBlock;
import oracle.jsp.jwcache.CacheClientUtil;
public class DemoCacheServlet extends HttpServlet{
public void service(HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException
{
// standard writer object from servlet engine
4-247
PrintWriter out=response.getWriter();
ServletConfig config=getServletConfig();
try {
CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy(config,request,
"/WEB-INF/test-policy.cpd" ); // Note A
StringSectionId sectionId=new StringSectionId("s1");
CacheBlock cacheBlockObj=null;
cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B

if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C
CharArrayWriter newOut=new CharArrayWriter();
PrintWriter pw=new PrintWriter(newOut);
// actual logic within a cache block

pw.println("fragment#1");
pw.println(new java.util.Date());
// which generates content into the "out" object
if (cacheBlockObj == null) { // Note E

cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId);
// Note F
}
out.write(newOut.toCharArray());
// writing out newly created data back to the original writer
}
else {
out.write((char[])cacheBlockObj.getData());
// writing the existing cached data to the writer
}
sectionId=new StringSectionId("s2");
long timeToLive = 15; // now set TTL to 15 on this block
ExpirationPolicy expirationPolicy = cachePolicyObj.getExpirationPolicy();
expirationPolicy.setTTL(timeToLive);
cachePolicyObj.setExpirationPolicy(expirationPolicy);
cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B
if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C
CharArrayWriter newOut=new CharArrayWriter();
PrintWriter pw=new PrintWriter(newOut);
// actual logic within a cache block

pw.println("fragment#2");
pw.println(new java.util.Date());
// which generates content into the "out" object
if (cacheBlockObj == null) { // Note E

cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId);
// Note F
4-248
}
out.write(newOut.toCharArray());
// writing out newly created data back to the original writer
}
else {
out.write((char[])cacheBlockObj.getData());
// writing the existing cached data to the writer
}
} catch (Throwable th) {

// your exception handling code here
th.printStackTrace(out);
}
}
}
Code Notes
The following notes describe some of the key functionality of the preceding example:
● The cache policy object is created in the lookupPolicy() call, with attribute settings
according to the cache policy descriptor test-policy.cpd.
● The section ID is created for each cache block, as required for implicit cache-block naming.
See "CachePolicy Methods" for information about section IDs.
● The cache block is retrieved from the repository through the getCache() method of the
cache policy object, and placed into the repository through the putCache() method
(according to the section ID in each case).
● The isRecent() call determines if the cache block is recent enough to use. If so, the
cached data is retrieved through the getData() method of the cache block. (See
"CacheBlock Methods".) If not, a special PrintWriter object is created to buffer the
output and save it back to the cache repository. If the cache block object is not found (is
null), then the putCache() method of the cache policy object is called to create a new
cache block.
Cache Policy Descriptor
You can optionally use an XML-style cache policy descriptor to specify attribute settings for the
4-249
CachePolicy and ExpirationPolicy objects. In any JSP pages or servlets that you use, you
would then specify the cache policy descriptor through the policy attribute of a cache,
cacheXMLObj, useCacheObj, cacheInclude, or invalidateCache tag.
This section provides the cache policy descriptor DTD, a sample cache policy descriptor, and
information about loading and refreshing the cache policy descriptor.
Cache Policy Descriptor DTD
This section provides a listing of the Web Object Cache cache policy descriptor DTD,
cachepolicy.dtd. For an example of a cache policy descriptor, see "Sample Cache Policy
Descriptor".



<!ELEMENT cachePolicy (
selectedParam*, selectedCookie*,
reusableTimeStamp?, reusableDeltaTime?,
cacheRepositoryName?, expirationPolicy? ) >
<!ATTLIST cachePolicy ignoreCache (true | false) "false" >

<!ATTLIST cachePolicy scope (application | session) "application" >
<!ATTLIST cachePolicy autoType
(user | URI | URI_query |
URI_allParam | URI_selectedParam | URI_excludedParam )
"URI_allParam" >
<!ATTLIST cachePolicy reportException (true | false) "true" >
<!ELEMENT selectedParam (#PCDATA) >

<!ELEMENT selectedCookie (#PCDATA) >
<!ELEMENT reusableTimeStamp (#PCDATA) >
<!ELEMENT reusableDeltaTime (#PCDATA) >
<!ELEMENT cacheRepositoryName (#PCDATA) >
<!ELEMENT expirationPolicy EMPTY >

4-250
<!ATTLIST expirationPolicy expirationType (TTL | daily | weekly | monthly)
"TTL" >
<!ATTLIST expirationPolicy TTL CDATA "300" >
<!ATTLIST expirationPolicy timeInaDay CDATA #IMPLIED >
<!ATTLIST expirationPolicy dayInaWeek
(Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday)
"Wednesday" >
<!ATTLIST expirationPolicy dayInaMonth CDATA "10" >
<!ATTLIST expirationPolicy writeThrough (true | false) "true" >
Sample Cache Policy Descriptor
This section provides an example of a simple cache policy descriptor that sets the TTL and
timeInaDay attributes. For the DTD, see "Cache Policy Descriptor DTD".

</cachePolicy>
Cache Policy Descriptor Loading and Refreshing
To create a CachePolicy object from an XML cache policy descriptor file, there must be a call to
the static lookupPolicy() method of the oracle.jsp.jwcache.CacheClientUtil class.
For JSP pages, this is handled automatically. For servlets, you must include the
lookupPolicy() call in your code--see "Sample Servlet Using the Web Object Cache API".
If the caching policy has not been previously loaded, then the lookupPolicy() method results
in the XML descriptor being parsed and used in constructing a new CachePolicy object (and an
ExpirationPolicy attribute of this object). See "Cache Policy Object Creation" for information
about the lookupPolicy() method.
The CachePolicy object is stored indirectly under the ServletContext object associated with
your application. When the same caching policy is requested again, the stored policy object will be
returned without the descriptor being re-read or re-parsed. For performance reasons, because the
cache policy descriptor files are seldom changed, as well as for security reasons, OC4J does not
provide descriptor auto-reloading functionality. The resulting cache policy object is stored in the
4-251
middle-tier JVM for faster access.
The CachePolicy object will be valid until the servlet context is destroyed or someone calls the
static refreshPolicy() method of the CacheClientUtil class. This method has the same
calling sequence as the lookupPolicy() method. For example:
oracle.jsp.jwcache.CacheClientUtil.refreshPolicy
(servletConfig, request, "/WEB-INF/foo.cpd");
When you alter and refresh the caching policy, active cache blocks are not affected.
Cache Repository Descriptor
Use an XML-style cache repository descriptor to specify what to use as the back-end cache
repository for the Web Object Cache, and how to configure it. This section supplies the DTD for
cache repository descriptors, as well as a sample cache repository descriptor.
Note:
By default, the Web Object Cache uses the Oracle9i Application Server Java Object Cache
as its cache repository.
Cache Repository Descriptor DTD
This section provides a listing of the Web Object Cache cache repository descriptor DTD,
wcache.dtd. For an example of a cache repository descriptor, see "Sample Cache Repository
Descriptor" below.



<!ELEMENT wcache-config (cache-repository*)>
<!ELEMENT cache-repository
(cache-repository-name,cache-repository-class,init-param*)>
<!ELEMENT cache-repository-name (#PCDATA)>

<!ELEMENT cache-repository-class (#PCDATA)>
<!ELEMENT init-param (param-name,param-value)>

<!ELEMENT param-name (#PCDATA)>
<!ELEMENT param-value (#PCDATA)>
Sample Cache Repository Descriptor
This section lists the cache repository descriptor provided with OC4J. For the DTD, see "Cache
Repository Descriptor DTD" above.
Note:
The DTD does not include reporoot, which is a specific-use parameter that only a file
system cache implementation requires.
<wcache-config>
<cache-repository>
<cache-repository-name>DefaultCacheRepository</cache-repository-name>
<cache-repository-class>
oracle.jsp.jwcache.repository.impl.OCSRepoImpl
</cache-repository-class>
</cache-repository>
<cache-repository>
<cache-repository-name>SimpleFSRepo</cache-repository-name>
<cache-repository-class>
oracle.jsp.jwcache.repository.impl.SimpleFSRepositoryImpl
</cache-repository-class>
<init-param>
<param-name>reporoot</param-name>
<param-value>/tmp/reporoot</param-value>
</init-param>
4-253
</cache-repository>
</wcache-config>
4-254
Reference: OC4J Web Object Cache Tags
Library Syntax
<%@ taglib uri="jwcache.tld" prefix="jwcache" %>
Syntax usage:
JWCache Tag Library
Name Syntax
<jwcache:cache
[policy]
[ignoreCache]
[invalidateCache]
[scope]
[autoType]
[selectedParam]
[selectedCookies]
[reusableTimeStamp]
[reusableDeltaTime]
cache - Web Object Cache tag for char- [name]
based data. [expirationType]
[TTL]
[timeInaDay]
[dayInaWeek]
[dayInaMonth]
[writeThrough]
[printCacheBlockInfo]
[printCachePolicy]
[cacheRepositoryName]
[reportException] > JSP content
</jwcache:cache>
4-255
<jwcache:cacheInclude
policy
cacheInclude - web object cache tag for page
included page (char-based) [printCacheBlockInfo]
[reportException] />
<jwcache:cacheXMLObj
[policy]
[ignoreCache]
[invalidateCache]
[scope]
[autoType]
[selectedParam]
[selectedCookies]
[reusableTimeStamp]
[reusableDeltaTime]
[name]
[expirationType]
cacheXMLObj - The Web Object Cache tag
[TTL]
for XML DOM object.
[timeInaDay]
[dayInaWeek]
[dayInaMonth]
[writeThrough]
[printCachePolicy]
[fromXMLObjName]
[toXMLObjName]
[toWriter]
</jwcache:cacheXMLObj>
<jwcache:invalidateCache
[policy]
[ignoreCache]
[scope]
[autoType]
[selectedParam]
invalidateCache - This tag invalidates web
[selectedCookies]
object cache.
[name]
[invalidateNameLike]
[page]
[autoInvalidateLevel]
[reportException] />
4-256
<jwcache:useCacheObj
[policy]
[ignoreCache]
[invalidateCache]
[cacheScope]
[autoType]
[selectedParam]
[selectedCookies]
[reusableTimeStamp]
[reusableDeltaTime]
[name]
useCacheObj - web object cache tag for [expirationType]
generic Java serializable object [TTL]
[timeInaDay]
[dayInaWeek]
[dayInaMonth]
[writeThrough]
[printCachePolicy]
[reportException]
id
type > JSP content
</jwcache:useCacheObj>
4-257
Working with Data-Access Tags
This chapter describes JSP tags and portable JavaBeans provided with OC4J for use in
accessing a database from servlets and JSP pages.
The chapter is organized as follows:
● SQL Tags for Data Access
● JavaBeans for Data Access
SQL Tags for Data Access
The OC4J product includes a set of tags you can use in JSP pages to execute SQL commands
to access a database. This section, organized as follows, describes the tags:
● Introduction to Data-Access Tags
● Data-Access Tag Descriptions
Note:
The tags described in this section use the beans described in "JavaBeans for Data
Access".
Introduction to Data-Access Tags
OC4J supplies a custom tag library for SQL functionality (separate from the JML custom tag
library).
The following tags are provided:
● dbOpen--Open a database connection. This tag also supports data sources and
connection pooling. See "Data-Access Support for Data Sources and Pooled
4-258
Connections" for related information.
● dbClose--Close a database connection.
● dbQuery--Execute a query.
● dbCloseQuery--Close the cursor for a query.
● dbNextRow--Process the rows of a result set.
● dbExecute--Execute any SQL statement (DML or DDL).
● dbSetParam--Set a parameter to bind into a dbQuery or dbExecute tag.
● dbSetCookie--Set a cookie.
Note the following requirements for using SQL tags:
● You will need the appropriate JDBC driver file, such as classes12.zip for JDK 1.2 or
higher, installed and in your classpath.
● Install the file ojsputil.jar and include it in your classpath. This file is provided with
the OC4J installation.
● Make sure the tag library description file, sqltaglib.tld, is deployed with the
application and is in the location specified in the taglib directives of your JSP pages,
such as in the following example:
<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %>
In an Oracle9i Application Server installation, the tag library description file is located in
the [Oracle_Home]/j2ee/tlds directory.
For general information about JSP 1.1 tag library usage, including tag library description files
4-259
and taglib directives, refer to the Oracle9iAS Containers for J2EE Support for JavaServer
Pages Reference.
Data-Access Tag Descriptions
This section provides detailed syntax for the data-access tags, an example using dbOpen and
dbQuery tags with a data source, and a listing of the tag library description file:
● SQL dbOpen Tag
● SQL dbClose Tag
● SQL dbQuery Tag
● SQL dbCloseQuery Tag
● SQL dbNextRow Tag
● SQL dbExecute Tag
● SQL dbSetParam Tag
● SQL dbSetCookie Tag
● Example: Using dbOpen and dbQuery with a Data Source
Notes:
● The prefix "sql:" is used in the tag syntax here. This is by convention but is not
SQL dbOpen Tag
4-260
Use the dbOpen tag to open a database connection, for subsequent SQL operations through
such tags as dbQuery and dbExecute. You can accomplish this by specifying a data source
location, in which case connection caches are supported, or by specifying the user, password,
and URL individually. See "Data-Access Support for Data Sources and Pooled Connections" for
information about how to set up a data source in OC4J.
The implementation uses oracle.jsp.dbutil.ConnBean instances. For simple

connections, but not connection caches, you can optionally set ConnBean properties such as
stmtCacheSize, preFetch, and batchSize to enable those Oracle JDBC features. See
"ConnBean for a Database Connection" for more information.
Syntax
<sql:dbOpen
[ connId = "connection_id" ]
[ scope = "page" | "request" | "scope" | "application" ]
[ dataSource = "JNDI_name" ]
[ user = "username"
password = "password"
URL = "databaseURL" ]
[ commitOnClose = "true" | "false" ] >
...
</sql:dbOpen>
Nested code that you want to execute through this connection can go into the tag body,
between the dbOpen start and end tags.
4-261
Note:
You must either set the dataSource attribute, or set the user, password, and URL
attributes. Optionally, you can use a data source to specify a URL, then use the dbOpen
tag user and password attributes separately.
When a data source is used, and is for a cache of connections, the first use of the cache
initializes it. If you specify the user and password through the dbOpen tag user and
password attributes, that will initialize the cache for that user and password. Subsequent
uses of the cache will expect the same user and password.
Attributes
● connId--Optionally use this to specify an ID name for the connection. You can then
reference this ID in subsequent tags such as dbQuery or dbExecute. Alternatively, you
can nest dbQuery and dbExecute tags inside the dbOpen tag. You can also reference
the connection ID in a dbClose tag when you want to close the connection.
You can still specify a connection ID if you nest dbQuery or dbExecute tags inside the
dbOpen tag. In this case, the connection will be found through the connection ID. With
the scope attribute, it is possible to have multiple connections using the same
connection ID but different scopes.
If you specify a connection ID, then the connection is not closed until you close it
explicitly with a dbClose tag. Without a connection ID, the connection is closed
automatically when the dbOpen end tag is encountered.
● scope (used only with a connId)--Use this to specify the desired scope of the
connection instance. The default is page scope.
If you specify a scope setting in a dbOpen tag, then you must specify the same scope
setting in any other tag--dbQuery, dbExecute, or dbClose--that uses the same
connection ID.
● dataSource (required if you do not set the user, password, and URL attributes)--
Optionally use this to specify the JNDI name of a data source for database connections.
First set up the data source in the OC4J data-sources.xml file--see "Data-Access
4-262
Support for Data Sources and Pooled Connections". The dataSource setting should
correspond to the location name or pooled-location name in a data-source tag
in data-sources.xml.
A data source must specify a URL setting, but does not have to specify a user/password
pair--you can use the dbOpen tag user and password attributes instead.
This attribute is supported only in OC4J environments.
● user (required if no user/password pair is specified through a data source)--This is the

user name for a database connection.
If a user name is specified through both a data source and the user attribute, the user
attribute takes precedence. It is advisable to avoid such duplication, because conflicts
could arise if the data source is a pooled connection with existing logical connections
using a different user name.
● password (required if no user/password pair is specified through a data source)--This is

the user password for a database connection.
Note that you do not have to hardcode a password into the JSP page, which would be an
obvious security concern. Instead, you can get the password and other parameters from
the request object, as follows:
<sql:dbOpen connId="conn1" user=<%=request.getParameter("user")%>

password=<%=request.getParameter("password")%> URL="url" />
As with the user attribute, if a password is specified through both a data source and the
password attribute, the password attribute takes precedence.
● URL (required if no data source is specified)--This is the URL for a database connection.
If a URL is supplied through a data source, the dbOpen tag URL attribute is ignored.
● commitOnClose--Set this to "true" for an automatic SQL commit when the connection
is closed or goes out of scope. Otherwise, an automatic rollback is executed. The
default is "false", for rollback.
4-263
As a convenience, if you want to specify automatic commit or rollback behavior on an
application-wide basis, you can set the parameter name commit-on-close in the
application web.xml file, as in the following example:
<context-param>
<param-name>commit-on-close</param-name>
<param-value>true</param-value>
</context-param>
The commitOnClose setting in a dbOpen tag takes precedence over the commit-on-
close setting in web.xml.
Note:
In previous releases, the behavior was always to commit automatically when the
connection is closed. The commitOnClose attribute offers backwards compatibility
to simplify migration.
SQL dbClose Tag
Use the dbClose tag to close a connection associated with the optional connId parameter
specified in a dbOpen tag. If connId is not used in the dbOpen tag, then the connection is
closed automatically when the dbOpen end tag is reached; no dbClose tag is required.
Note that by using the JspScopeListener utility provided with OC4J, you can have the
connection closed automatically with session-based event-handling. You can refer to "JSP
Event-Handling--JspScopeListener" for information.
Syntax
<sql:dbClose connId = "connection_id"

[ scope = "page" | "request" | "scope" | "application" ] />
Attributes
4-264
● connId (required)--The ID for the connection to be closed, specified in the dbOpen tag
that opened the connection.
● scope--This is the scope of the connection instance. This attribute is not necessary for
page scope, but if the dbOpen tag specified a scope other than page, then you must
specify that same scope in the dbClose tag.
SQL dbQuery Tag
Use the dbQuery tag to execute a query, outputting the results either as a JDBC result set,
HTML table, XML string, or XML DOM object. Place the SELECT statement (one only) in the tag
body, between the dbQuery start and end tags.
This tag uses an oracle.jsp.dbutil.CursorBean object for the cursor, so you can set
properties such as the result set type, result set concurrency, batch size, and prefetch size if
desired. See "CursorBean for DML and Stored Procedures" for information about CursorBean
functionality.
For XML usage, this tag acts as an XML producer. See "XML Producers and XML Consumers"
for more information. Also see "Example Using the transform and dbQuery Tags".
Syntax
<sql:dbQuery
[ queryId = "query_id" ]
[ output = "HTML" | "XML" | "JDBC" ]
[ maxRows = "number" ]
[ skipRows = "number" ]
[ bindParams = "value" ]
[ toXMLObjName = "objectname" ] >
...SELECT statement (one only)...
</sql:dbQuery>
4-265
Important:
● In the current release, do not terminate the SELECT statement with a semi-colon.
This would result in a syntax error.
● The dbQuery tag does not currently support LOB columns. This support is
expected in a future release.
Attributes
● queryId--You can use this to specify an ID name for the cursor. This is required if you
want to process the results using a dbNextRow tag.
If the queryId parameter is present, then the cursor is not closed until you close it
explicitly with a dbCloseQuery tag. Without a query ID, the cursor is closed
automatically when the dbQuery end tag is encountered. This is not a request-time
attribute, meaning it cannot take a JSP expression value.
● connId--The ID for a database connection, according to the connId setting in the

dbOpen tag that opened the connection. If you do not specify connId in a dbQuery tag,
then the tag must be nested within the body of a dbOpen tag and will use the connection
opened in the dbOpen tag. This is not a request-time attribute.
page scope, but if the associated dbOpen tag specified a scope other than page, then
you must specify that same scope in the dbQuery tag. This is not a request-time
attribute.
● output--This is the desired output format:
❍ HTML puts the result set into an HTML table (default).
❍ XML puts the result set into an XML string, or an XML DOM object if an object
name is specified in the toXMLObjName attribute.
4-266
❍ JDBC puts the result set into a JDBC ResultSet object that can be processed
using the dbNextRow tag to iterate through the rows.
● maxRows--This is the maximum number of rows of data to display.
● skipRows--This is the number of data rows to skip in the query results before displaying
results.
● bindParams--Use this to bind a parameter into the query. The following example is from
an application that prompts the user to enter an employee number, using bindParams
to bind the specified value into the empno field of the query:
<sql:dbQuery connId="con1" bindParams="empno">

select * from EMP where empno=?
</sql:dbQuery>
Alternatively, you can set a parameter value with the dbSetParam tag to bind it in
through the bindParams attribute. See "SQL dbSetParam Tag".
● toXMLObjName--Specify an XML object name, and set output to "XML", if you want to
output the results as an XML DOM object.
SQL dbCloseQuery Tag
Use the dbCloseQuery tag to close a cursor associated with the optional queryId parameter
specified in a dbQuery tag. If queryId is not specified in the dbQuery tag, then the cursor is
closed automatically when the dbQuery end tag is reached; no dbCloseQuery tag is
required.
Syntax
<sql:dbCloseQuery queryId = "query_id" />
Attributes
4-267
● queryId (required)--The ID for the cursor to be closed, specified in the dbQuery tag
that opened the cursor.
SQL dbNextRow Tag
Use the dbNextRow tag to process each row of a result set obtained in a dbQuery tag and
associated with the specified queryId. Place the processing code in the tag body, between
the dbNextRow start and end tags. The body is executed for each row of the result set.
To use the dbNextRow tag, the dbQuery tag must set output to "JDBC" and specify a
queryId for the dbNextRow tag to reference.
The result set object is created in an instance of the tag-extra-info class of the dbQuery tag.
Refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for
information about the standard JSP tag library framework and tag-extra-info classes.
Syntax
<sql:dbNextRow queryId = "query_id" >
...Row processing...
</sql:dbNextRow >
Attributes
● queryId (required)--The ID for the cursor containing the results to be processed,

specified in the dbQuery tag that opened the cursor.
Example
The following example shows the combined use of a dbOpen, dbQuery, and dbNextRow tag.
<sql:dbOpen connId="con1" URL="jdbc:oracle:thin:@myhost:1521:816"

user="scott" password="tiger">
</sql:dbOpen>
<sql:dbQuery connId="con1" output="jdbc" queryId="myquery">
select * from EMP
4-268
</sql:dbQuery>
<sql:dbNextRow queryId="myquery">
<%= myquery.getString(1) %>
</sql:dbNextRow>
SQL dbExecute Tag
Use the dbExecute tag to execute any DML or DDL statement (one only). Place the statement
in the tag body, between the dbExecute start and end tags.
This tag uses an oracle.jsp.dbutil.CursorBean object for the cursor. See "CursorBean
for DML and Stored Procedures" for information about CursorBean functionality.
Syntax
<sql:dbExecute
[ scope = "page" | "request" | "scope" | "application" ]
[ output = "yes" | "no" ] >
[ bindParams = "value" ] />
...DML or DDL statement (one only)...
</sql:dbExecute >
Important:
● In the current release, do not terminate the DML or DDL statement with a semi-
colon. This would result in a syntax error.
● The dbExecute tag does not currently support LOB columns. This support is
expected in a future release.
Attributes
4-269
● connId--The ID for a database connection, according to the connId setting in the
dbOpen tag that opened the connection. If you do not specify connId in a dbExecute
tag, then the tag must be nested within the body of a dbOpen tag and will use the
connection opened in the dbOpen tag.
page scope, but if the dbOpen tag specified a scope other than page, then you must
specify that same scope in the dbExecute tag.
● output--If output="yes", then for DML statements the HTML string "number row[s]
affected" will be output to the browser to notify the user how many database rows were
affected by the operation. For DDL statements, the statement execution status will be
printed. The default setting is no.
● bindParams--Use this to bind a parameter into the SQL statement. The following
example is from an application that prompts the user to enter an employee number,
using bindParams to bind the specified value into the empno field of the DELETE
statement:
<sql:dbExecute connId="con1" bindParams="empno">

delete from EMP where empno=?
</sql:dbExecute>
Alternatively, you can set a parameter value with the dbSetParam tag to bind it in
through the bindParams attribute. See "SQL dbSetParam Tag" below.
SQL dbSetParam Tag
You can use this tag to set a parameter value to bind into a query, through the dbQuery tag, or
into any other SQL operation, through the dbExecute tag.
Syntax
<sql:dbSetParam name = "param_name"

value = "param_value"
4-270
Attributes
● name-- The name of the parameter to set.
● value-- The desired value of the parameter.
● scope--This is the scope of the bind parameter. This attribute is not necessary for page
scope.
Example
The following example uses a dbSetParam tag to set the value of a parameter named id2.
This value is then bound into the SQL statement in the dbExecute tag.
<sql:dbSetParam name="id2" value='<%=request.getParameter("id")%>'

scope="session" />
Result:
<HR>
<sql:dbOpen URL="<%= connStr %>" user="scott" password="tiger">
<sql:dbExecute output="yes" bindParams="id2 name job sal">
insert into emp(empno, ename, deptno, job, sal)
values (?, ?, 20, ?, ?)
</sql:dbExecute>
</sql:dbOpen>
<HR>
SQL dbSetCookie Tag
You can use this tag to set a cookie. The dbSetCookie tag wraps functionality of the standard
javax.servlet.http.Cookie class.
Syntax
<sql:dbSetCookie name = "cookie_name"

[ value = "cookie_value" ]
[ domain = "domain_name" ]
[ comment = "comment" ]
[ maxAge = "age" ]
4-271
[ version = "protocol_version" ]
[ secure = "true" | "false" ]
[ path = "path" ] />
Attributes
● name (required)--This is the name of the cookie.
● value--This is the desired value of the cookie. Because it is permissible to have a null-
value cookie, this attribute is not required.
● domain--This is the domain name for the cookie. The form of the domain name is
according to the RFC 2019 specification.
● comment--This is an optional comment describing the purpose of the cookie.
● maxAge--This is the maximum allowable age of the cookie, in seconds. Use a setting of -
1 for the cookie to persist until the browser is shut down.
● version--This is the version of the protocol that the cookie complies with.
● secure--This informs the browser whether the cookie should only be sent using a
secure protocol, such as HTTPS or SSL.
● path--This specifies a file system path for the cookie, the location to which the client
should return the cookie.
Example
<sql:dbSetCookie name="cId" value='<%=request.getParameter("id")%>'

maxAge='800000' />
Example: Using dbOpen and dbQuery with a Data Source
This section provides a sample JSP page that uses a dbOpen tag with a data source to open a
4-272
connection, then uses a dbQuery tag to execute a query.

<HTML>
<BODY>
<sql:dbOpen dataSource="<%=request.getParameter("datasource") %>"
connId="con1">
</sql:dbOpen>
<sql:dbQuery connId="con1">
SELECT * FROM emp ORDER BY ename
</sql:dbQuery>
</BODY>
</HTML>
JavaBeans for Data Access
The OC4J product includes a set of JavaBeans you can use to access a database. This
section, organized as follows, describes the beans:
● Introduction to Data-Access JavaBeans
● Data-Access Support for Data Sources and Pooled Connections
● Data-Access JavaBean Descriptions
Note:
The JavaBeans described here are used by the tags discussed in "SQL Tags for
Data Access".
Introduction to Data-Access JavaBeans
OC4J supplies a set of custom JavaBeans for accessing an Oracle database or middle-tier
database cache (either is referred to simply as "the database" in the discussion below). The
following beans are included in the oracle.jsp.dbutil package:
4-273
● ConnBean opens a database connection. This bean also supports data sources and
connection pooling. See "Data-Access Support for Data Sources and Pooled
Connections" for related information.
● ConnCacheBean uses the Oracle JDBC connection caching implementation for

database connections. This requires JDBC 2.0.
● DBBean executes a database query. It also has its own connection mechanism, but does
not support data sources.
● CursorBean provides general DML support for queries; UPDATE, INSERT, and DELETE
statements; and stored procedure calls.
This section presumes a working knowledge of Oracle JDBC.
Notes:
● The Oracle data-access JavaBeans implement the Oracle JspScopeListener

interface for event notification. You can refer to "JSP Event-Handling--
JspScopeListener" for information about this interface.
● To use the data-access JavaBeans, install the file ojsputil.jar and include it
in your classpath. This file is provided with the OC4J installation. For XML-related
methods and functionality, you will also need file xsu12.jar (for JDK 1.2.x) or
xsu111.jar (for JDK 1.1.x), which is provided with Oracle9i.
Data-Access Support for Data Sources and Pooled Connections
The data-access JavaBeans, as well as the data-access tag library, supports the use of data
sources to specify connection properties. This is also how support for connection pooling is
implemented. This mechanism supports both Oracle connection objects and OC4J connection
objects.
To use a data source in a JSP page, you must define the data source, its JNDI name, and its
4-274
connection and pooling properties. In OC4J, do this in a data-source tag in the data-
sources.xml file. Here is an example:
<data-source
class="oracle.jdbc.pool.OracleDataSource"
name="jdbc/pool/OracleDS"
location="jdbc/ConnectionDS"
pooled-location="jdbc/pool/OracleDS"
url="jdbc:oracle:thin:@myhost:1521:orcl"
username="scott"
password="tiger"
min-connections="3"
max-connections="50"
wait-timeout="10"
inactivity-timeout="30" />
See the Oracle9iAS Containers for J2EE User's Guide more information about the data-
sources.xml file and data-source tag.
Data-Access JavaBean Descriptions
This section describes attributes and methods of the data-access JavaBeans--ConnBean,

ConnCacheBean, DBBean, and CursorBean--and concludes with an example that uses a
data source:
● ConnBean for a Database Connection
● ConnCacheBean for Connection Caching
● DBBean for Queries Only
● CursorBean for DML and Stored Procedures
● Example: Using ConnBean and CursorBean with a Data Source
ConnBean for a Database Connection
Use oracle.jsp.dbutil.ConnBean to establish a simple database connection (one that
4-275
uses no connection pooling or caching).
Notes:
For queries only, if you do not require a data source, it is simpler to use DBBean, which
has its own connection mechanism.
ConnBean has the following properties. The user, password, and URL properties are not
required if you use a data source.
● dataSource (JNDI name for a data source location)
This is valid only for an environment that supports data sources. See "Data-Access
Support for Data Sources and Pooled Connections" for information about how to set up a
data source in OC4J.
● user (user ID for database schema)
● password (user password)
● URL (database connection string)
● stmtCacheSize (cache size for Oracle JDBC statement caching)
Setting stmtCacheSize enables Oracle JDBC statement caching.
● executeBatch (batch size for Oracle JDBC update batching)
Setting executeBatch enables Oracle JDBC update batching.
● preFetch (number of statements to prefetch in Oracle JDBC row prefetching)
Setting preFetch enables Oracle JDBC row prefetching.
4-276
● commitOnClose (true or false to execute commit when connection is closed)
The value of this property indicates whether an automatic commit should be executed
when the connection is closed. A "true" setting results in a commit; a "false" setting
results in a rollback. In previous releases, an automatic commit was always
executed, but in Oracle9iAS release 2 the default is an automatic rollback. The
commitOnClose property allows for backwards compatibility to ease migration.
Be aware that there can be an application-wide commit-on-close setting in the

application web.xml file, but the setting of the ConnBean property is not automatically
dependent on that setting. If a JSP pages uses ConnBean instead of a dbOpen tag, the
value of the commit-on-close context parameter should be retrieved and then
explicitly set as the commitOnClose value in the ConnBean instance. For reference,
here is a sample web.xml entry that sets the commit-on-close context parameter:
<context-param>
<param-name>commit-on-close</param-name>
</context-param>
Note:
The Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference
provides brief overviews of statement caching, update batching, and row
prefetching.
ConnBean provides the following setter and getter methods for these properties:
● void setDataSource(String)
● String getDataSource()
● void setUser(String)
4-277
● String getUser()
● void setPassword(String)
● String getPassword()
● void setURL(String)
● String getURL()
● void setStmtCacheSize(int)
● int getStmtCacheSize()
● void setExecuteBatch(int)
● int getExecuteBatch()
● void setPreFetch(int)
● int getPreFetch()
● void setCommitOnClose(String)
● String getCommitOnClose()
Note:
As with any JavaBean you use in a JSP page, you can set any of the ConnBean
properties with a jsp:setProperty action instead of using the setter method
directly.
4-278
Use the following methods to open and close a connection, or to verify its status:
● void connect()--Establish a database connection using ConnBean property settings.
● void close()--Close the connection and any open cursors.
● boolean isConnectionClosed()--Determine if the connection is closed.
Use the following method to open a cursor and return a CursorBean object:
● CursorBean getCursorBean(int, String)
or:
● CursorBean getCursorBean(int)
Input the following:
❍ one of the following int constants to specify the type of JDBC statement you
want: CursorBean.PLAIN_STMT (for a Statement object),
CursorBean.PREP_STMT (for a PreparedStatement object), or
CursorBean.CALL_STMT (for a CallableStatement object)
❍ a string specifying the SQL operation to execute (optional; alternatively, the SQL
operation can be specified in the CursorBean method call that executes the
statement)
See "CursorBean for DML and Stored Procedures" for information about CursorBean
functionality.
ConnCacheBean for Connection Caching
Use oracle.jsp.dbutil.ConnCacheBean to use the Oracle JDBC connection caching

mechanism, using JDBC 2.0 connection pooling, for your database connections. You can refer
to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for a brief
4-279
overview of connection caching.
Notes:
● To use data sources or simple connection objects, use ConnBean instead.
● ConnCacheBean extends OracleConnectionCacheImpl, which extends

OracleDataSource (both in Oracle JDBC package oracle.jdbc.pool).
ConnCacheBean has the following properties.
● maxLimit (maximum number of connections allowed by this cache)
● minLimit (minimum number of connections existing for this cache)
If you are using fewer than this number, then there will also be connections in the "idle
pool" of the cache.
● stmtCacheSize (cache size for Oracle JDBC statement caching)
Setting stmtCacheSize enables the Oracle JDBC statement caching feature. You can
refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for
a brief overview of Oracle JDBC statement caching features and limitations.
● cacheScheme (type of cache, indicated by one of the following int constants):
❍ DYNAMIC_SCHEME--New pooled connections can be created above and beyond
4-280
the maximum limit, but each one is automatically closed and freed as soon as the
logical connection instance that it provided is no longer in use.
❍ FIXED_WAIT_SCHEME--When the maximum limit is reached, any new connection

waits for an existing connection object to be released.
❍ FIXED_RETURN_NULL_SCHEME--When the maximum limit is reached, any new

connection fails (null is returned) until connection objects have been released.
The ConnCacheBean class supports methods defined in the Oracle JDBC

OracleConnectionCacheImpl class, including the following getter and setter methods for
its properties:
● String getURL()
● void setMaxLimit(int)
● int getMaxLimit()
● void setMinLimit(int)
● int getMinLimit()
4-281
● void setStmtCacheSize(int)
● int getStmtCacheSize()
● void setCacheScheme(int)
Specify ConnCacheBean.DYNAMIC_SCHEME,
ConnCacheBean.FIXED_WAIT_SCHEME, or
ConnCacheBean.FIXED_RETURN_NULL_SCHEME.
● int getCacheScheme()
Returns ConnCacheBean.DYNAMIC_SCHEME,
ConnCacheBean.FIXED_WAIT_SCHEME, or
ConnCacheBean.FIXED_RETURN_NULL_SCHEME.
The ConnCacheBean class also inherits properties and related getter and setter methods from
the oracle.jdbc.pool.OracleDataSource class. This provides getter and setter methods
for the following properties: databaseName, dataSourceName, description,
networkProtocol, portNumber, serverName, and driverType.
Note:
As with any JavaBean you use in a JSP page, you can set any of the ConnCacheBean
properties with a jsp:setProperty action instead of using the setter method directly.
Use the following methods to open and close a connection:
● Connection getConnection()--Get a connection from the connection cache using

ConnCacheBean property settings.
● void close()--Close all connections and any open cursors.
4-282
Although the ConnCacheBean class does not support Oracle JDBC update batching and row
prefetching directly, you can enable these features by calling the
setDefaultExecuteBatch(int) and setDefaultRowPrefetch(int) methods of the
Connection object that you retrieve from the getConnection() method. Alternatively, you
can use the setExecuteBatch(int) and setRowPrefetch(int) methods of JDBC
statement objects that you create from the Connection object (update batching is supported
only in prepared statements). You can refer to the Oracle9iAS Containers for J2EE Support for
JavaServer Pages Reference for brief overviews of these features.
Notes:
● ConnCacheBean has the same functionality as

OracleConnectionCacheImpl.
● Unlike ConnBean, when you use ConnCacheBean, you use normal Connection
object functionality to create and execute statement objects.
DBBean for Queries Only
Use oracle.jsp.dbutil.DBBean to execute queries only.
Notes:
● DBBean has its own connection mechanism but does not support data sources. If
you require a data source, use ConnBean instead. If you do not require a data
source, ConnBean is not required.
● Use CursorBean for any other DML operations (UPDATE, INSERT, DELETE, or
stored procedure calls).
DBBean has the following properties.
4-283
DBBean provides the following setter and getter methods for these properties:
● String getURL()
Note:
As with any JavaBean you use in a JSP page, you can set any of the DBBean
properties with a jsp:setProperty statement instead of using the setter method
directly.
Use the following methods to open and close a connection:
● void connect()--Establish a database connection using DBBean property settings.
● void close()--Close the connection and any open cursors.
4-284
Use either of the following methods to execute a query:
● String getResultAsHTMLTable(String)--Input a string that contains the SELECT

statement.
This method returns a string with the HTML commands necessary to output the result set
as an HTML table. SQL column names (or aliases) are used for the table column
headers.
● String getResultAsXMLString(String)--Input a string with the SELECT

statement.
This method returns the result set as an XML string, using SQL names (or aliases) for
the XML tags.
CursorBean for DML and Stored Procedures
Use oracle.jsp.dbutil.CursorBean for SELECT, UPDATE, INSERT, or DELETE

operations or stored procedure calls on a simple connection. It uses a previously defined
ConnBean object for the connection.
You can specify a SQL operation in a ConnBean object getCursorBean() call, or through a
call to one of the create(), execute(), or executeQuery() methods of a CursorBean
object as described below.
Note:
To use connection caching, use ConnCacheBean and normal Connection object

functionality. Do not use CursorBean.
CursorBean has the following properties.
● executeBatch (batch size for Oracle JDBC update batching)
Setting this property enables Oracle JDBC update batching.
4-285
● preFetch (number of statements to prefetch in Oracle JDBC row prefetching)
Setting this property enables Oracle JDBC row prefetching.
● queryTimeout (number of seconds for the driver to wait for a statement to execute
before issuing a timeout)
● resultSetType (scrollability of the result set, as indicated by one of the following int
constants):
❍ TYPE_FORWARD_ONLY (default)--A result set that can scroll only forward (using
the next() method) and cannot be positioned.
❍ TYPE_SCROLL_INSENSITIVE--A result set that can scroll forward or backward

and can be positioned, but is not sensitive to underlying data changes.
❍ TYPE_SCROLL_SENSITIVE--A result set that can scroll forward or backward, can

be positioned, and is sensitive to underlying data changes.
● resultSetConcurrency (updatability of the result set, as indicated by one of the

following int constants):
❍ CONCUR_READ_ONLY (default)--A result set that is read-only (cannot be updated).
❍ CONCUR_UPDATABLE--A result set that is updatable.
You can set these properties with the following methods to enable Oracle JDBC features, as
desired:
● void setExecuteBatch(int)
● int getExecuteBatch()
● void setPreFetch(int)
4-286
● int getPreFetch()
● void setQueryTimeout(int)
● int getQueryTimeout()
● void setResultSetConcurrency(int)
Specify CursorBean.CONCUR_READ_ONLY or CursorBean.CONCUR_UPDATABLE.
● int getResultSetConcurrency()
Returns CursorBean.CONCUR_READ_ONLY or CursorBean.CONCUR_UPDATABLE.
● void setResultSetType(int)
Specify CursorBean.TYPE_FORWARD_ONLY,
CursorBean.TYPE_SCROLL_INSENSITIVE, or
CursorBean.TYPE_SCROLL_SENSITIVE.
● int getResultSetType()
Returns CursorBean.TYPE_FORWARD_ONLY,
CursorBean.TYPE_SCROLL_INSENSITIVE, or
CursorBean.TYPE_SCROLL_SENSITIVE.
Note:
As with any JavaBean you use in a JSP page, you can set any of the CursorBean
properties with a jsp:setProperty action instead of using the setter method
directly.
To execute a query once a CursorBean instance has been defined in a jsp:useBean
4-287
statement, you can use CursorBean methods to create a cursor in one of two ways. You can
use the following methods to create the cursor and supply a connection in separate steps:
● void create()
● void setConnBean(ConnBean)
Or you can combine the process into a single step:
● void create(ConnBean)
Set up the ConnBean object as described in "ConnBean for a Database Connection".
Then use the following method to specify and execute a query. (This uses a JDBC plain
Statement object behind the scenes.)
● ResultSet executeQuery(String)
Input a string that contains the SELECT statement.
Alternatively, if you want to format the result set as an HTML table or XML string, use either of
the following methods instead of executeQuery():
● String getResultAsHTMLTable(String)
Returns a string with HTML statements to create an HTML table for the result set.
Specify a string with the SELECT statement.
● String getResultAsXMLString(String)
Returns the result set data in an XML string. Specify a string with the SELECT statement.
To execute an UPDATE, INSERT, or DELETE statement once a CursorBean instance has

been defined in a jsp:useBean action, you can use CursorBean methods to create a cursor
in one of two ways. You can use the following methods to create the cursor (specifying a
statement type as an integer and SQL statement as a string) and supply a connection:
4-288
● void create(int, String)
● void setConnBean(ConnBean)
Or you can combine the process into a single step:
● void create(ConnBean, int, String)
(Set up the ConnBean object as described in "ConnBean for a Database Connection".)
The int input takes one of the following constants to specify the type of JDBC statement you
want: CursorBean.PLAIN_STMT (for a Statement object), CursorBean.PREP_STMT (for a
PreparedStatement object), or CursorBean.CALL_STMT (for a CallableStatement
object).
The String input is to specify the SQL statement.
Then use the following method to execute the INSERT, UPDATE, or DELETE statement. (You
can ignore the boolean return value.)
● boolean execute()
Or for update batching, use the following method, which returns the number of rows affected.
(See below for how to enable update batching.)
● int executeUpdate()
Note:
Specify the SQL operation either during statement creation or during statement
execution, but not both. The execute() and executeUpdate() methods can
optionally take a string to specify a SQL operation. This is also true of the
create() call, as well as the getCursorBean() call in ConnBean
4-289
Additionally, CursorBean supports Oracle JDBC functionality such as
registerOutParameter() for callable statements, setXXX() methods for prepared
statements and callable statements, and getXXX() methods for result sets and callable
statements.
Use the following method to close the database cursor:
● void close()
Example: Using ConnBean and CursorBean with a Data Source
This section provides a sample JSP page that uses ConnBean with a data source to open a
connection, then uses CursorBean to execute a query.
<%@ page import="java.sql.*, oracle.jsp.dbutil.*" %>

<jsp:useBean id="cbean" class="oracle.jsp.dbutil.ConnBean" scope="session">
<jsp:setProperty name="cbean" property="dataSource"
value="<%=request.getParameter("datasource")%>"/>
</jsp:useBean>
<% try {
cbean.connect();
String sql="SELECT ename, sal FROM scott.emp ORDER BY ename";
CursorBean cb = cbean.getCursorBean (CursorBean.PREP_STMT, sql);
out.println(cb.getResultAsHTMLTable());
cb.close();
cbean.close();
} catch (SQLException e) {
out.println("<P>" + "There was an error doing the query:");
out.println("<PRE>" + e + "</PRE>\n<P>"); }
%>
4-290
About Data-Access Tags
OC4J supplies a set of custom JavaBeans for use in accessing the Oracle9i database or
middle-tier database cache. The following beans are provided in the oracle.jsp.dbutil package:
● ConnBean opens a database connection. This bean also supports data sources and
connection pooling.
● ConnCacheBean uses Oracle's connection caching implementation for database

connections. (This requires JDBC 2.0.)
● DBBean executes a database query.
● CursorBean provides general DML support for queries; UPDATE, INSERT, and DELETE
statements; and stored procedure calls.
For JSP programmers, OC4J also provides a custom tag library for SQL functionality, wrapping
the functionality of the JavaBeans.
4-291
Reference: OC4J Data-Access Tag Library
Library Syntax
<%@ taglib uri="sqltaglib.tld" prefix="database" %>
Syntax usage:
OC4J SQL Tag Library
Name Syntax
<database:dbClose
dbClose - The dbClose tag closes the connId
connection specified with a connection id. [scope] />
dbCloseQuery - The dbQueryClose tag
<database:dbCloseQuery
closes the query cursor specified with a query queryId />
id.
<database:dbExecute
[connId]
dbExecute - The dbExecute tag executes non- [scope]
query statements (DDl and DML). [output]
[bindParams] > JSP content
</database:dbExecute>
<database:dbNextRow
dbNextRow - The dbNextRow tag obtains the
queryId > JSP content
next row from the JDBC result set. </database:dbNextRow>
<database:dbOpen
[connId]
[user]
[password]
dbOpen - The dbOpen tag establishes a
[URL]
database connection via url or data source.
[dataSource]
[scope]
[commitOnClose] > JSP content
</database:dbOpen>
4-292
<database:dbQuery
[queryId]
[connId]
[scope]
dbQuery - The dbQuery tag performs a query [output]
using an established connection. [maxRows]
[skipRows]
[bindParams]
[toXMLObjName] > JSP content
</database:dbQuery>
<database:dbSetCookie
name
[value]
[domain]
dbSetCookie - The dbSetCookie tag sets a
[comment]
cookie value.
[maxAge]
[version]
[secure]
[path] />
<database:dbSetParam
dbSetParam - The dbSetParam tag sets a name
bind parameter in a SQL statement. value
[scope] />
4-293
Working with JSP Utility Tags
This chapter documents a variety of general utility features available with OC4J for use in JSP pages,
including the following:
● JSP Event-Handling--JspScopeListener
● Mail JavaBean and Tag
● File-Access JavaBeans and Tags
● EJB Tags
● Utility Tags
These features are implemented according to JSP and servlet standards and are generally portable to
other JSP environments.
JSP Event-Handling--JspScopeListener
In standard servlet and JSP technology, only session-based events are supported. Oracle extends this
support to page-based, request-based, and application-based events through the
JspScopeListener interface and JspScopeEvent class in the oracle.jsp.event package.
● General Use of JspScopeListener
● Use of JspScopeListener in OC4J and Other Servlet 2.3 Environments
● Examples Using JspScopeListener
General Use of JspScopeListener
For Java objects in your application, implement the JspScopeListener interface in the appropriate
class, then attach objects of that class to a JSP scope using tags such as jsp:useBean.
When the end of a scope is reached, objects that implement JspScopeListener and have been
4-294
attached to the scope will be so notified. The JSP container accomplishes this by sending a
JspScopeEvent instance to such objects through the outOfScope() method specified in the
JspScopeListener interface.
Properties of the JspScopeEvent object include the following:
● the scope that is ending (one of the constants PAGE_SCOPE, REQUEST_SCOPE,

SESSION_SCOPE, or APPLICATION_SCOPE)
● the container object that is the repository for objects at this scope (one of the implicit objects
page, request, session, or application)
● the name of the object that the notification pertains to (the name of the instance of the class that
implements JspScopeListener)
● the JSP implicit application object
This event listener mechanism significantly benefits developers who want to always free object
resources that are of page or request scope, regardless of error conditions. It frees these developers
from having to surround their page implementations with Java try/catch/finally blocks.
Use of JspScopeListener in OC4J and Other Servlet 2.3 Environments
JspScopeListener uses different mechanisms to support the different scopes, though all are
implemented according to servlet and JSP standards.
For pages running in an OC4J environment, there is also an OC4J-specific runtime implementation for
page scope, for convenience.
● Requirements for JspScopeListener
● Runtime and Tag Implementations to Support Page Scope
● Servlet Filter Implementation to Support Request Scope
● Listener Class Implementation to Support Application Scope
4-295
● Integration with HttpSessionBindingListener to Support Session Scope
Requirements for JspScopeListener
The JspScopeListener implementation requires the following:
● the oracle.jsp.event.JspScopeListener interface and JspScopeEvent class, and the

classes of the oracle.jsp.event.impl package, all of which are supplied in the ojsp.jar
file
● a servlet 2.3 environment
Runtime and Tag Implementations to Support Page Scope
For OC4J and JServ environments, there is support for page scope through an Oracle-specific runtime
implementation. No configuration or special steps on your part are required.
For portability to other environments, there is also an implementation to support page scope through a
special tag, checkPageScope. Put the appropriate code between the checkPageScope start-tag
and end-tag. This tag, with no attributes, is defined as follows:


<tag>
<name>checkPageScope</name>
<tagclass>oracle.jsp.jml.tagext.CheckPageScopeListenerTag</tagclass>
<bodycontent>JSP</bodycontent>
<info>
to provide the notification of logic any
JspScopeListener stored in page scope
This tag is not needed on
JServ or OC4J.
</info>
</tag>
Here is an example of its use:
<%@ taglib uri="/WEB-INF/jml.tld" prefix="jml" %>

<jml:checkPageScope>
pagescope.jsp
<jsp:useBean id="tb" class="testpkg.TestData" />
<%
/* testpkg.TestData implements oracle.jsp.event.JspScopeListener
checkPageScope tag will provide the notification of logic any
4-296
JspScopeListener stored in page scope
This tag is not needed on JServ
or OC4J.
*/
// some more JSP / code here ...
%>
<%= new java.util.Date() %>
</jml:checkPageScope>
Note:
The checkPageScope tag is currently part of the Oracle JML tag library, which is included in
the ojsputil.jar file and requires the jml.tld tag library description file.
Servlet Filter Implementation to Support Request Scope
Objects of request scope are supported through a servlet filter. The filtering applies to any servlets
matching a specified URL pattern.
For support of event-handling for request-scope objects, add an entry such as the following to the
web.xml file for your application. To ensure proper operation of the JspScopeListener
functionality, this setting must be after any other filter settings.
<filter>
<filter-name>Request Filter</filter-name>
<filter-class>oracle.jsp.event.impl.RequestScopeFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>Request Filter</filter-name>
<url-pattern>/jsp/*</url-pattern>
</filter-mapping>
Note:
In this particular example, "/jsp/*" is the URL pattern covered by the filter. Users may choose
other patterns instead, such as "/*.jsp" or "/*".
Listener Class Implementation to Support Application Scope
4-297
Objects with application scope are supported through a servlet context listener implementation
class, in accordance with the servlet 2.3 specification.
For support of event-handling for application-scope objects, add an entry such as the following to the
web.xml file for your application. To ensure proper operation of the JspScopeListener
functionality, this setting must be after any other listener settings.
<listener>
<listener-class>oracle.jsp.event.impl.AppScopeListener</listener-class>
</listener>
For an application-scope object, in addition to notification upon the conclusion of the application and
servlet context, there is notification when an attribute is replaced in the servlet context or removed from
the servlet context. For example, the listener outOfScope() method of an application-scope object is
called in either of the following circumstances, assuming a servlet context object ctx:
ctx.setAttribute("name", "Smith");
...
ctx.setAttribute("name, "Jones");
or:
ctx.setAttribute("name", "Smith");
...
ctx.removeAttribute("name");
Note:
This functionality was not available prior to Oracle9iAS release 9.0.2.
Integration with HttpSessionBindingListener to Support Session Scope
For session-scope objects, you can write a class that implements both the JspScopeListener
interface and the standard javax.servlet.http.HttpSessionBindingListener interface. This
would give you the flexibility of supporting instances of this class for other scopes as well. If instances
would never be used outside of session scope, however, there is no need to implement
JspScopeListener.
In the integration scenario, the valueUnbound() method, specified in the
4-298
HttpSessionBindingListener interface, should call the outOfScope() method, specified in the
JspScopeListener interface.
Following is a basic example:
import oracle.jsp.event.impl.*;
class SampleObj implements HttpSessionBindingListener,JspScopeListener

{
public void valueBound(HttpSessionBindingEvent e)
{
System.out.println("The object implements the JspScopeListener also");
}
public void valueUnBound(HttpSessionBindingEvent e)

{
try
{
outOfScope(new JspScopeEvent(null,(Object)e.getSession(),
e.getName(),javax.servlet.jsp.PageContext.SESSION_SCOPE));
} catch (Throwable e) {}
...........
}
public void outOfScope(JspScopeEvent e)
{...}
}
Examples Using JspScopeListener
This section provides two examples of JspScopeListener usage--first a JSP page and
accompanying JavaBean, and then a servlet.
Example: JSP Page Using JspScopeListener
This example consists of a JavaBean, ScopeDispatcher, that implements the JspScopeListener

interface, and a JSP page that uses ScopeDispatcher instances for request-scope and application-
scope functionality.
bookcatalog.jsp
The bookcatalog.jsp page allows users to search for a book in the catalog or insert a new book
entry. The catalog is kept in a hashtable that is initially read from the local file stream.
4-299
At the end of a request, if a new book has been submitted it is entered into the application-level
catalog hashtable, and the book count is incremented.
At the end of execution of the application, the catalog hashtable is sent back to the local file stream,
the number of newly inserted books is shown, and query results are displayed if there was a book
search.
<%@ page import="java.util.*" %>

<%@ page import="java.io.*" %>
<%! static int newbookCount = 0; %>
<%! static Hashtable catalog; %>
<%! boolean bookAdded = false; %>
<html>
<head>
<title> BookStore Price catalog </title>
</head>
<body bgcolor="white">
<font size=5 color="red">
<table color="#FFFFCC" width="100%" border="1" cellspacing="0" cellpadding="0" >
<tr>
<td>
<form action="bookcatalog.jsp">
<b> BookName </b>
<input type="text" name="bookname">
<input type="submit" value="Get the Price">
</form>
</td>
<td>
<form action="bookcatalog.jsp">
<b>BookName</b>
<input type="text" name="new_book">
<br>
<b>Price</b>
<input type="text" name="price">
<input type="submit" value="Add to Catalog">
</form>
</td>
</tr>
</table>
<%
String bookname = request.getParameter("bookname");
catalog = (Hashtable) application.getAttribute("pricelist");
if (catalog == null)
{
try{
ObjectInputStream oin = new ObjectInputStream
(new FileInputStream("bookcatalog.out"));
Object obj = oin.readObject();
4-300
catalog = (Hashtable) obj;
oin.close();
}
catch(Exception e) {
catalog = new Hashtable();}
application.setAttribute("pricelist",catalog);
}
if (bookname != null)
{
String price = (String) catalog.get(bookname.trim());
if (price != null)
{
out.println("<h2>Book : " +bookname+ "</h2>");
out.println("<h2>Price: "+price +"</h2>");
}
else
out.println("<h2> Sorry, the Book : " + bookname + " is not available in
the catalog</h2>");
}
%>
<%-- declare the event dispatchers --%>

<jsp:useBean id = "requestDispatcher"
class = "oracle.jsp.sample.event.ScopeDispatcher"
scope = "request" >
<jsp:setProperty name = "requestDispatcher" property = "page"
value = "<%= this %>" />
<jsp:setProperty name = "requestDispatcher" property = "methodName"
value = "request_OnEnd" />
</jsp:useBean>
<jsp:useBean id = "appDispatcher"
class = "oracle.jsp.sample.event.ScopeDispatcher"
scope = "application" >
<jsp:setProperty name = "appDispatcher" property = "page"
value = "<%= this %>" />
<jsp:setProperty name = "appDispatcher" property = "methodName"
value = "application_OnEnd" />
</jsp:useBean>
<%!
// request_OnEnd Event Handler
public void request_OnEnd(HttpServletRequest request) {
// acquire beans
String newbook = request.getParameter("new_book");
bookAdded = false;
if ((newbook != null) && (!newbook.equals("")))
{
catalog.put(newbook,request.getParameter("price"));
newbookCount++;
bookAdded = true;
}
4-301
}
%>
<%!
public void application_OnEnd(ServletContext application)

{
try
{
ObjectOutputStream os = new ObjectOutputStream(
new FileOutputStream("bookcatalog.out"));
os.writeObject(catalog);
os.flush();
os.close();
}
catch (Exception e)
{}
}
%>
<%
if (bookAdded)
out.println("<h2> The New book is been added in the catalog </h2>");
%>
<%-- Page implementation goes here --%>
<h2> Total number of books added is <%= newbookCount %></h2>
</font>
</body>
</html>
ScopeDispatcher.java
package oracle.jsp.sample.event;
import java.lang.reflect.*;
import oracle.jsp.event.*;
public class ScopeDispatcher extends Object implements JspScopeListener {
private Object page;

private String methodName;
private Method method;
public ScopeDispatcher() {
}
public Object getPage() {

return page;
}
4-302
public void setPage(Object page) {
this.page = page;
}
public String getMethodName() {

return methodName;
}
public void setMethodName(String m) throws NoSuchMethodException,

ClassNotFoundException {
method = verifyMethod(m);
methodName = m;
}
public void outOfScope(JspScopeEvent ae) {

int scope = ae.getScope();
if ((scope == javax.servlet.jsp.PageContext.REQUEST_SCOPE ||
scope == javax.servlet.jsp.PageContext.APPLICATION_SCOPE)
&& method != null) {
try {
Object args[] = {ae.getContainer()};
method.invoke(page, args);
} catch (Exception e) {
// catch all and continue
}
}
}
private Method verifyMethod(String m) throws NoSuchMethodException,

ClassNotFoundException {
if (page == null) throw new NoSuchMethodException(
"A page hasn't been set yet.");
// Don't know whether this is a request or page handler so try one then
// the other
Class c = page.getClass();
Class pTypes[] = {Class.forName("javax.servlet.ServletContext")};
try {
return c.getDeclaredMethod(m, pTypes);
} catch (NoSuchMethodException nsme) {
// fall through and try the request signature
}
pTypes[0] = Class.forName("javax.servlet.http.HttpServletRequest");
return c.getDeclaredMethod(m, pTypes);
}
}
4-303
Example: Servlet Using JspScopeListener
This section contains a sample servlet that uses JspScopeListener functionality for a request-
scope object. The nested class DBScopeObj implements the JspScopeListener interface.
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Enumeration;
import oracle.jsp.event.*;
import oracle.jsp.event.impl.*;
public class RequestScopeServlet extends HttpServlet {
PrintWriter out;
public void doGet(HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException
{
out = response.getWriter();
out.println("<html>");
out.println("<body>");
out.println("<head>");
out.println("<title> RequestScopeServlet! </title>");
out.println("</head>");
response.setContentType("text/html");
DBScopeObj aobj = new DBScopeObj();
request.setAttribute("dbcon",aobj);
request.setAttribute("name","scott");
request.setAttribute("company","oracle");
request.setAttribute("city","sanmateo");
Enumeration en = request.getAttributeNames();
out.println("<BR> Request Attributes : <BR> <BR>");
while (en.hasMoreElements()) {
String key = (String)en.nextElement();
Object value = request.getAttribute(key);
out.println(key + " : " + value+"<BR>");
}
out.println("</body>");
out.println("</html>");
}
class DBScopeObj implements JspScopeListener

{
public void initDBConnection()

{
// can create a minimum number of predefined
4-304
// DBConnections
DBScopeObj()
{
// if DBconnection is available in the connection
// pool then pickup from the pool and give the handle.
public void outOfScope(JspScopeEvent e)

{
ServletContext ctx = e.getApplication();
out.println
("<BR>*****************************************************");
out.println("<BR> JspScopeEvent <BR>");
out.println("<BLINK>");
out.println
("<BR> In outOfScope method for the Request Attribute <BR>");
out.println("Name = " +e.getName() + "<BR>");
out.println("</BLINK>");
out.println
("*****************************************************<BR>");
// logging in the context also
ctx.log("*****************************************************");
ctx.log(" JspScopeEvent ");
ctx.log(" In outOfScope method for the Request Attribute ");
ctx.log("Name = " +e.getName());
ctx.log("*****************************************************");
returnDBConnection();
}
public void returnDBConnection()
{
//Can return the handle to the connection pool
}
}
}
Mail JavaBean and Tag
It is often useful to be able to send e-mail messages from a Web application, based on Web site status
or user actions. Sun Microsystems has specified a platform-independent and protocol-independent
framework for this through its javax.mail package and subpackages, known as the JavaMail API.
For further convenience, Oracle supplies a JavaBean and JSP custom tag, based on the JavaMail
4-305
API, to use in providing e-mail functionality through your servlets or JSP pages. The bean and tag, like
other JavaBeans and custom tags supplied with OC4J, are implemented according to JSP and servlet
standards.
This section, organized as follows, describes the JavaBean and tag:
● General Considerations for the Mail JavaBean and Tag
● SendMailBean Description
● The sendMail Tag Description
Note:
In Oracle9iAS, the mail JavaBean and tag require the OC4J (not the JServ) environment.
For more information about the JavaMail API, you can refer to the following Sun Microsystems Web
site:
http://java.sun.com/products/javamail/1.2/docs/javadocs/index.html
General Considerations for the Mail JavaBean and Tag
Be aware of the following points, which apply to use of either the mail JavaBean (SendMailBean) or
the mail tag (sendMail):
● The files mail.jar, containing the JavaMail packages, and jaf.jar, for the JavaBeans
Activation Framework, must be in your classpath for mail functionality. These files are provided
with OC4J.
● The JavaBean and tag currently do not support mail attachments. This support is expected in a
future release.
● There is no particular limit to the size of an e-mail message, other than limits of the JVM, system
memory, or mail server.
● Setting up default mail sessions is specific to the particular Web server. The current
implementations of the mail bean and tag do not support automatic use of the default mail
4-306
session. This feature may be added in a future release. Until then, if you wish, you can write
your own code to obtain the default mail session if one exists for your platform, and make it
available to the mail bean or tag.
● The JavaBean or tag can currently handle only a moderate number of requests. If too many are
received, it may happen that not enough mail transport objects can be created and an exception
will result. This limitation may be addressed in a future release.
SendMailBean Description
The oracle.jsp.webutil.email.SendMailBean JavaBean is supplied with OC4J to support e-

mail functionality from servlet or JSP applications. To use it in a JSP page, you can instantiate it
through the standard jsp:useBean tag. (However, for JSP applications, you may want to use the
sendMail tag instead--see "The sendMail Tag Description".)
SendMailBean Requirements
When you use SendMailBean, you must provide the following:
● the message sender
Use the setSender() method to specify the sender.
● the primary recipient(s) of the message
Use the setRecipient() method to specify the primary recipient(s).
● a valid JavaMail session object (javax.mail.Session), either directly or indirectly
There are three ways to supply a JavaMail session:
❍ You can use the setHost() method to specify a host system. In this case, a JavaMail
session object will be created automatically.
❍ You can use the setMailSession() method to provide a JavaMail session object
directly.
❍ For JSP applications, you can use the setSession() method to specify the name of a
JavaMail session object that already exists and is accessible through a "session string,
javax.mail.Session object" pair in the JSP page context. In this case, you must
supply the page context instance as an input parameter when you call the
4-307
sendMessage() method to send the e-mail message.
All other SendMailBean attributes are optional.
SendMailBean Method Descriptions
This section lists and describes SendMailBean methods to send mail messages, close mail sessions,
and set (or get) bean attributes.
Note:
As according to the JavaBean specification, SendMailBean has a no-argument constructor.
Here are the public SendMailBean methods:
● void sendMessage()
● void sendMessage(javax.servlet.jsp.PageContext)
Use the sendMessage() method to send the e-mail message.
If you use the setSession() method to supply a JavaMail session, then you must use the
sendMessage(PageContext) signature and provide the page context instance that holds the
specified mail session instance.
If you use the setMailSession() or setHost() method to supply a JavaMail session, then
you do not have to provide a page context in using the sendMessage() method.
Also be aware, however, that specifying a page context instance may be relevant in determining
the character set of an e-mail message with a "text" content type. If you provide no page context
when invoking the sendMessage() method, then the default character set is ISO-8859-1. If
you do provide a page context, then the default character set is that of the response object of
the page context. Also note that you can specify the content type and character set directly
through the setContentType() method.
● void close()
Use this method if you want to release the resources of the JavaMail session instance from the
4-308
SendMailBean instance. This method does not actually close the session.
● void setBcc(String s)
Specify a space-separated or comma-separated list of any IDs (e-mail addresses or aliases) to

receive "blind" copies of the message. These IDs will be suppressed from the message "cc"
field.
There is also a corresponding String getBcc() method.
● void setCc(String s)
Specify a space-separated or comma-separated list of any IDs (e-mail addresses or aliases) to

receive copies of the message. These IDs will appear in the message "cc" field.
There is also a corresponding String getCc() method.
● void setContent(String s)
Specify the contents of the e-mail message.
There is also a corresponding String getContent() method.
● void setContentEncoding(String s)
Specify the content encoding of the e-mail message. Specify "base64" or "B" for base64
encoding, "quoted-printable" or "Q" for quoted-printable encoding, "7bit" for seven-bit encoding,
or "8bit" for eight-bit encoding. These content encodings are part of the JavaMail and RFC 2047
standards. Entries are case-insensitive.
The content encoding setting defaults to null, in which case the encoding of the message and
headers will be determined by the content. If most characters to be encoded are in ASCII, then
quoted-printable encoding will be used; otherwise, base64 encoding will be used.
There is also a corresponding String getContentEncoding() method.
● void setContentType(String s)
Specify the MIME type and optionally the character set of the message, such as in the following
examples:
4-309
setContentType("text/html");
setContentType("text/html; charset=US-ASCII");
You cannot specify a character set without specifying one of the text/xxxx MIME types.
The default MIME type is "text/plain".
The default character set depends on whether you provide a JSP page context instance when
you call the sendMessage() method to send the e-mail message. If you provide no page
context, then the default character set is ISO-8859-1. If you do provide a page context, then the
default character set is that of the response object of the page context.
There is also a corresponding String getContentType() method.
● void setHost(String s)
One of the ways to supply a JavaMail session is to specify a mail server host name, in which
case SendMailBean will obtain a session automatically. Use the setHost() method for this
purpose, providing a mail host name such as "gmail.oraclecorp.com".
There is also a corresponding String getHost() method.
See "SendMailBean Requirements" for an overview of supplying the JavaMail session.
● void setMailSession(javax.mail.Session sessobj)
One of the ways to supply a JavaMail session is to provide the session object directly. Use the
setMailSession() method for this purpose, providing a javax.mail.Session instance.
There is also a corresponding javax.mail.Session getMailSession() method, which

returns a JavaMail session that you had previously set.
● void setRecipient(String s)
Specify a space-separated or comma-separated list of IDs (e-mail addresses or aliases) of the

primary recipients of the message. These IDs will appear in the "to" field of the message. You
must specify at least one recipient.
4-310
There is also a corresponding String getRecipient() method.
● void setSender(String s)
Specify the ID (e-mail address or alias) of the message sender. This ID will appear in the "from"
field of the message. You must specify the sender.
There is also a corresponding String getSender() method.
● void setSession(String s)
One of the ways to supply a JavaMail session is to provide the name of a

javax.mail.Session instance that already exists in the JSP page context object. Use the
setSession() method for this purpose, specifying the name of the session instance.
In this case, when you use the sendMessage() method to send the e-mail message, you must
provide the javax.servlet.jsp.PageContext instance as input.
There is also a corresponding String getSession() method.
● void setSubject(String s)
Specify the subject line of the message.
There is also a corresponding String getSubject() method.
The sendMail Tag Description
As a convenience for JSP developers, OC4J supplies the sendMail tag to provide e-mail functionality
for a JSP page. This section describes the tag, including the following topics:
● The sendMail Tag Syntax
● The sendMail Tag Attribute Descriptions
● sendMail Tag Sample Application
4-311
In the current implementation, the sendMail tag has its own TLD file, email.tld, located in the
OC4J /j2ee/tlds directory. To use the tag, you must include a taglib directive, such as the
following, to reference this TLD file in your JSP page:
<%@ taglib uri="/WEB-INF/email.tld" prefix="mail" %>
The sendMail Tag Syntax
The sendMail tag has the following syntax:
<mail:sendMail host = "SMTP_host_name" | session = "JavaMail_session_name"

sender = "sender_address"
recipient = "primary_recipient_IDs"
[ cc = "cc_recipient_IDs" ]
[ bcc = "bcc_recipient_IDs" ]
[ subject = "subject_line" ]
[ contentType = "MIME_type; [charset=charset]" ]
[ contentEncoding = "B"|"base64"|"Q"|"quoted-printable"|
"7bit"|"8bit" ] >
...
E-mail body
...
</mail:sendMail>
Notes:
● The sender and recipient attributes are required, and either the host or session
attribute is required.
● Multiple recipients, cc targets, or bcc targets are space-separated or comma-separated.
● The e-mail body can contain JSP syntax, which will be processed by the JSP translator.
● Attributes used by the tag are typically input by the user in form fields.
● The prefix "mail:" is used in the tag syntax here. This is by convention but is not required.
You can specify any desired prefix in your taglib directive.
The sendMail Tag Attribute Descriptions
4-312
The sendMail tag supplies the following attributes:
● host (required if session is not specified)--The appropriate mail host name, such as
"gmail.oraclecorp.com". This is used in creating a JavaMail session object for the mail message.
Alternatively, you can determine a JavaMail session through the session attribute.
● session (required if host is not specified)--The name of an existing JavaMail session object
that can be retrieved from the JSP page context. Alternatively, you can determine a JavaMail
session through the host attribute.
● sender (required)--The ID (e-mail address or alias) of the sender of the message. This ID will
appear in the "from" field of the message.
● recipient (required)--A space-separated or comma-separated list of IDs of the primary

recipients of the message. These IDs will appear in the "to" field of the message.
● cc -- A space-separated or comma-separated list of IDs to receive a copy of the message.

These IDs will appear in the "cc" field of the message.
● bcc --A space-separated or comma-separated list of IDs to receive a "blind" copy of the
message. These IDs will be suppressed from the "cc" field.
● subject--The subject line of the message.
● contentType--The MIME type of the message, and optionally a character set as well, such as
in the following examples:
contentType="text/html"
contentType="text/html; charset=US-ASCII"
You cannot specify a character set without specifying one of the text/xxxx MIME types.
The default MIME type is "text/plain". The default character set is that of the response object of
the JSP page context.
● contentEncoding--Specify "B" or "base64" for base64 encoding, "Q" or "quoted-printable" for

quoted-printable encoding, "7bit" for seven-bit encoding, or "8bit" for eight-bit encoding. These
are standard JavaMail and RFC 2047 encodings. Entries are case-insensitive.
4-313
The content encoding setting defaults to null, in which case the encoding of the message and
headers will be determined by the content--if most characters to be encoded are in ASCII, then
quoted-printable encoding will be used; otherwise, base64 encoding will be used.
sendMail Tag Sample Application
This sample application illustrates use of the sendMail tag. During the first execution cycle through
the page, before the user has specified the sender (or anything else), the HTML form is displayed for
user input. During the next execution cycle through the page, after the user has sent the input, the
sendMail tag is executed. This page also uses an error page, error.jsp (shown below), to display
any exceptions that are thrown.
<%@ page language="java" errorPage="error.jsp" %>

<%@ taglib uri="/WEB-INF/email.tld" prefix="mail" %>
<%
if (request.getParameter("sender")==null) {
%>
<HTML>
<HEAD><TITLE>SendMail Sample</TITLE></HEAD>
<FORM METHOD=post>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="20%">
<TR><TD>Host:</TD><TD><INPUT TYPE="text" name="host" ></TD></TR>
<TR><TD>From:</TD><TD><INPUT TYPE="text" name="sender" ></TD></TR>
<TR><TD>To:</TD><TD><INPUT TYPE="text" name="recipient" ></TD></TR>
<TR><TD>Cc:</TD><TD><INPUT TYPE="text" name="cc" ></TD></TR>
<TR><TD>Bcc:</TD><TD><INPUT TYPE="text" name="bcc" ></TD></TR>
<TR><TD>Subject:</TD><TD><INPUT TYPE="text" name="subject"
VALUE="Hi"></TD></TR>
</TABLE><br>
<TEXTAREA name="body" ROWS=4 COLS=30>"How are you!"</TEXTAREA><br><br>
<INPUT TYPE="submit" value="Send">
</FORM>
<%
}
else{
%>
<BODY BGCOLOR="#FFFFFF">
<P>Result:
<HR>
<mail:sendMail host='<%=request.getParameter("host")%>'
sender='<%=request.getParameter("sender")%>'
recipient='<%=request.getParameter("recipient")%>'
cc='<%=request.getParameter("cc")%>'
bcc='<%=request.getParameter("bcc")%>'
subject='<%=request.getParameter("subject")%>'>
<%=request.getParameter("body")%>
</mail:sendMail>
4-314
Sent out Successfully!
<HR>
</BODY>
<%
}
%>
</HTML>
Here is the error page, error.jsp:
<%@ page language="java" isErrorPage="true"%>

<HTML>
Error: <%= exception.getMessage() %>
</HTML>
When you run this application, you will initially see the following default screen:
4-315
And here is sample user input for a message from brian.wright@oracle.com to
blodney.treehut@oracle.com through the host gmail.oraclecorp.com:
File-Access JavaBeans and Tags
OC4J provides a portable tag library and JavaBeans that add convenient file upload and file download
functionality for JSP pages and servlets. Files can be uploaded to or downloaded from a file system or
database.
This section documents these features and is organized as follows:
● Overview of OC4J File-Access Functionality
4-316
● File Upload and Download Tag Descriptions
● File Upload and Download JavaBean and Class Descriptions
Notes:
● In Oracle9iAS, the file-access JavaBeans and tags require the OC4J (not the
JServ) environment.
● Multibyte file names are not currently supported.
Overview of OC4J File-Access Functionality
Developers have the option of using either custom tags or JavaBeans to program applications that
allow users to upload or download files. In either case, the application is presumably programmed so
that users specify through the browser where files come from on the client system for uploading, or
where they go to on the client system for downloading. For JSP pages for uploading, OC4J supplies a
convenience tag, httpUploadForm, to create a form for this purpose.
For processing an upload, including specifying the destination file system or database location, use the
HttpUploadBean JavaBean or the httpUpload tag. For processing a download, including
specifying the source file system or database location, use HttpDownloadBean or the
httpDownload tag. The beans extend HttpFileAccessBean, which is not intended for public use.
All of the beans are in the oracle.jsp.webutil.fileaccess package.
Overview of File Uploading
For user specification of where uploaded files will come from, you can use the httpUploadForm tag
to create a form. This tag lets users select the files for uploading, and creates the necessary multipart
HTTP request. You also have the option of using a standard HTML form to create the request.
Use the HttpUploadBean JavaBean or the httpUpload tag to receive and process the multipart
form-encoded data stream and write the files to the appropriate location, either in the file system or a
database. There is functionality to let you decide whether previous data will be overwritten if the target
file or database row already exists.
4-317
Note:
The maximum file size for any upload is 2 GB.
File System Destination
If the destination is in a file system, you must provide a properties file that designates a base directory.
The properties file must be named fileaccess.properties, must be located in the /WEB-INF
directory of your application, and must have a fileaccess.basedir entry such as the following (this
example is for a Microsoft Windows system):
fileaccess.basedir=C:\tmp
Under the base directory, there should be subdirectories as appropriate--for example, a subdirectory
for each authorized user. Destination subdirectories under the base directory must be specified
through an attribute of the upload bean or tag. All directories and subdirectories must already exist and
be writable; they cannot be created or made writable through OC4J functionality.
Database Destination
If the destination is in a database, you can optionally use a default table, fileaccess, that you create
through the supplied fileaccess.sql script, or you can use any other previously existing table
containing the required column types. In either case, you must provide a connection to the database,
as an instance of either oracle.jsp.dbutil.ConnBean or the standard java.sql.Connection.
You can provide a ConnBean instance either explicitly, or, in a JSP page, implicitly as a result of
nesting the httpUpload tag inside a dbOpen tag. (For information about the ConnBean JavaBean
and dbOpen tag, see Chapter 4, "Data-Access JavaBeans and Tags".)
It is also required that you specify a "destination" through an attribute of the upload bean or tag. The
destination is simply a Java string value that will be placed in the prefix column of the database table.
The prefix is equivalent to a file system path.
File data is written to a database as either a BLOB or a CLOB (specify which through an upload bean
or tag attribute).
If you do not use the default fileaccess table, you must use attributes of the upload bean or tag to
specify the database table name, and the names of the columns that will contain the file data, the file
prefix, and the file name. Any other table you use must follow the pattern of fileaccess:
● It must have a concatenated unique key consisting of the column that holds the file name and
the column that holds the prefix.
4-318
● It must have a BLOB or CLOB column for the file data.
● Any column other than the file data column must allow null data.
Notes:
● If you use a ConnBean instance, the connection will be closed automatically at the
end of the scope designated in the jsp:useBean tag that invokes it. There is no
such functionality for a Connection instance.
● ConnBean uses and requires the JspScopeListener interface. See "JSP Event-
Handling--JspScopeListener" for information about that utility.
Security Considerations for Uploading
For uploading to a database, the database table does not have a column to indicate a particular
authorized user for any given file. Therefore, without precaution, each user can see files that were
uploaded by other users, without having to know the file prefixes. To prevent this, you can prepend an
appropriate user name to each prefix.
Overview of File Downloading
Use the HttpDownloadBean JavaBean or the httpDownload tag as follows:
● to allow users to specify the file system source directory or the database prefix to match for file
retrieval
Note the following:
❍ Matching the prefix for downloads from a database is case-sensitive.
❍ Matching the source directory for downloads from a file system is case-sensitive in case-
sensitive operating systems (such as UNIX).
❍ There is currently no support for specifying file names, either partial or complete.
● to obtain and display a list of the files that are available for download
4-319
Once presented with a list of available files, the user can download them one at a time from the
list.
There is also functionality to specify whether you want recursive downloading, where files in
subdirectories or with additional database prefix information will also be available for download. For
database downloading, a prefix is equivalent to a file system path and can be used to group files into a
hierarchy. As an example of recursive downloading from a database, assume you have specified
/user as the prefix. Recursive downloading would find matches for files with any prefixes starting with
/user, such as /user/bill and /user/mary, and also such as /user1, /user2, /user1/tom,
and /user2/susan.
If downloading files from a file system, use the mechanism described in "Overview of File Uploading"--
use the fileaccess.properties file to specify a base directory, and use attributes in the download
bean or tag to specify the rest of the file path.
If downloading files from a database, as with uploading files to a database, you must provide an
instance of oracle.jsp.dbutil.ConnBean or java.sql.Connection. Also, if you are not using
the default fileaccess table (that you can create using the supplied fileaccess.sql script), you
must provide all the necessary information about the database table and columns. Specify this
information through attributes of the download bean or tag.
The actual downloading of the files is accomplished by DownloadServlet, supplied with OC4J. In
using the download tag, you specify the path of this servlet through a tag attribute. For a file system
source, hyperlinks are automatically created to the servlet so that the user can click on a link for each
file in order to download the file. For a database source, the servlet will fetch the selected CLOB or
BLOB data that forms the file contents. (Also see "The DownloadServlet".)
Security Considerations for Downloading
For downloading, you may want to consider limiting the users' ability to see what is in the source
(server-side) file system or database. Without precaution, the following scenarios are possible:
● For file system downloading, a source value of "*" (perhaps specified through user input) would
mean that all directories under the base directory would be available for downloading, with the
names of all the files presumably being displayed for the user to choose from.
● For recursive downloading from a database, all files having a prefix beginning with the source
string (perhaps specified through user input) would be available for downloading, with the
names of all these files presumably being displayed. A source of "*" matches all prefixes.
If this is of concern, you can consider protective measures such as the following:
4-320
● not accepting source values of "*" when downloading from file systems
● not allowing recursive downloading from databases
● automatically prepending the source value with a partial directory path or prefix string, such as
a user name, to restrict the areas to which users have access.
File Upload and Download JavaBean and Class Descriptions
This section describes attributes and methods of the file upload and download JavaBeans provided
with OC4J--HttpUploadBean and HttpDownloadBean, respectively.
There is also brief discussion of DownloadServlet, provided with OC4J to perform the actual file
downloading, and the class FileAccessException that is used by the file-access JavaBeans for
exceptions relating to file uploads and downloads.
As according to the JavaBean specification, the file upload and download JavaBeans provide no-
argument constructors.
The HttpUploadBean
The oracle.jsp.webutil.fileaccess.HttpUploadBean JavaBean provides numerous setter

methods for specifying information used for the uploading. It also includes most corresponding getter
methods. Once you have set all the required and appropriate attributes, use the upload() method to
perform the upload. There is also a method to display the names of the files that were uploaded,
typically so you can provide an informative message to the browser.
HttpUploadBean, like HttpDownloadBean, extends HttpFileAccessBean, which itself is not

intended for public use.
See "Overview of File Uploading" for related information.
Summary of Required Attributes
● always required: destination
● also required for uploads to a database: destinationType, Connection
● also required for uploads to a database table other than the default fileaccess table: table,
prefixColumn, fileNameColumn, dataColumn
4-321
● also required for uploads to a database table using a CLOB column for file data: fileType
Also, for an upload to a file system, you must call the setBaseDir() method to provide a servlet
context and HTTP request object so the bean can find the fileaccess.properties file that
specifies the base directory.
Methods
Here are descriptions of the public methods of HttpUploadBean.
Note:
Many of the attributes and setter methods for HttpUploadBean are the same as for
HttpDownloadBean.
● void upload(javax.servlet.http.HttpServletRequest req)

throws FileAccessException
Once all required and appropriate bean attributes have been set, use this method for the upload.
The req parameter is the servlet request instance containing the multipart form-encoded files.
For a JSP page, use the implicit request object.
● void setBaseDir(javax.servlet.ServletContext sc
javax.servlet.http.HttpServletRequest req)
For an upload to a file system, use this method to determine what to use as a base directory. It
gets this information from the fileaccess.properties file in your application /WEB-INF
directory, which it finds through the servlet context input parameter. The baseDir setting,
together with the destination setting, specifies the absolute path to the upload directory.
The req parameter is the servlet request instance to use in requesting the base directory
information. For JSP pages, use the implicit request object.
This is not relevant for database uploads.
● void setDestination(String destination)
This is always required.
4-322
For an upload to a file system, destination, together with the base directory, specifies the
absolute path to the upload directory.
For an upload to a database, destination is used as the file prefix (there is no "base
directory"). The prefix is equivalent to a file system path and can be used to group files into a
hierarchy. It is permissible to include separator characters such as "." and "/" in the destination
string.
Note:
Typically, the destination value will be based at least partially on user input.
● void setDestinationType(String destinationType)

● void setDestinationType(int destinationType)

Use the overloaded setDestinationType() method to specify whether the upload is to a file
system or a database.
To upload to a database, set destinationType to the string "database", the defined String
constant FileAccessUtil.DATABASE, the int value 1, or the defined int constant
FileAccessUtil.LOCATION_TYPE_DATABASE.
Uploading to a file system is the default, but if you want to specify this explicitly, set
destinationType to the string "filesystem", the defined String constant
FileAccessUtil.FILESYSTEM, the int value 0, or the defined int constant
FileAccessUtil.LOCATION_TYPE_FILESYSTEM. FileAccessUtil is in the
oracle.jsp.webutil.fileaccess package.
There is also a corresponding getter method (string version only):
String getDestinationType()
● void setOverwrite(String overwrite)

4-323
● void setOverwrite(boolean overwrite)
Use the overloaded setOverwrite() method to overwrite existing files or update rows with
the same file name and prefix. This is relevant for both file system and database uploads.
Overwriting is enabled by default, but you can enable it explicitly with an overwrite setting of
the string "true" or the boolean value true. Disable overwriting with a setting of the string "false"
or the boolean value false. String settings are case-insensitive. No settings are accepted other
than those listed here.
● void setFileType(String fileType)

● void setFileType(int fileType) throws FileAccessException
For an upload to a database, use the overloaded setFileType() method to specify whether
the data is to be stored in a BLOB for binary data (the default) or a CLOB for character data. For
a CLOB, set fileType to the string "character", the defined String constant
FileAccessUtil.CHARACTER_FILE, or the int value 1. To explicitly specify a BLOB, set
fileType to the string "binary", the defined String constant
FileAccessUtil.BINARY_FILE, or the int value 0. String settings are case-insensitive. No
settings are accepted other than those listed here. FileAccessUtil is in the
String getFileType()
● void setTable(String tableName)
For an upload to a database table other than the default fileaccess table, use this method to
specify the table name.
There is also a corresponding getter method:
String getTable()
● void setPrefixColumn(String prefixColumnName)
4-324
specify the name of the column containing the file prefix. (In fileaccess, this column name is
fileprefix.) The destination value will be written into this column.
String getPrefixColumn()
● void setFileNameColumn(String fileNameColumnName)
specify the name of the column containing the file name. (In fileaccess, this column name is
filename.) File names will include any file name extensions.
String getFileNameColumn()
● void setDataColumn(String dataColumnName)
specify the name of the BLOB or CLOB column containing the file contents. (In fileaccess,
this column name is data.)
String getDataColumn()
● void setConnection(ConnBean conn)
● void setConnection(java.sql.Connection conn)
For an upload to a database table (default table or otherwise), use this method to provide a
database connection. You can provide an instance of either oracle.jsp.dbutil.ConnBean
or the standard java.sql.Connection type. For information about the ConnBean JavaBean,
see "ConnBean for a Database Connection".
If you use a Connection instance, you must explicitly open and close it. For a ConnBean
4-325
instance, this is handled automatically.
● java.util.Enumeration getFileNames()
This method returns an Enumeration instance containing the names of the files that were
uploaded.
Note:
This functionality is not available through the httpUpload tag.
Example:
This example uses a plain HTML form to specify a file to upload to a file system, then uses a JSP page
that employs HttpUploadBean for the upload.
Here is the HTML form, which specifies beanUploadExample.jsp for its action and will generate the
multipart upload stream.
<html><body>
<form action="beanUploadExample.jsp" ENCTYPE="multipart/form-data" method=POST>
<br> File to upload: <INPUT TYPE="FILE" NAME="File" SIZE="50" MAXLENGTH="120" >
<br><INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Send"> </form>
</body></html>
And here is the beanUploadExample.jsp page.
<%@ page language="java" import="java.util.*, oracle.jsp.webutil.fileaccess.*"

%>
<html><body>
<% String userdir = "fileaccess"; %> // user's part of the upload directory
<jsp:useBean id="upbean"
class="oracle.jsp.webutil.fileaccess.HttpUploadBean" >
<jsp:setProperty name="upbean" property="destination" value="<%= userdir %>"
/>
</jsp:useBean>
<% upbean.setBaseDir(application, request);
upbean.upload(request);
Enumeration fileNames = upbean.getFileNames();
while (fileNames.hasMoreElements()) { %>
<br><%= (String)fileNames.nextElement() %>
<% } %>
4-326
<br>Done!
</body></html>
The HttpDownloadBean
The oracle.jsp.webutil.fileaccess.HttpDownloadBean JavaBean provides numerous

setter methods for specifying information used for downloading. It also includes most corresponding
getter methods. Once you have set all the required and appropriate attributes, use the listFiles()
method to list the files available for download. The actual downloading is accomplished through
DownloadServlet, supplied with OC4J, one file at a time. Also see "The DownloadServlet".
Note:
You must construct the URL for DownloadServlet in your application code.
HttpDownloadBean, like HttpUploadBean, extends HttpFileAccessBean, which itself is not

intended for public use.
See "Overview of File Uploading" for related information.
Summary of Required Attributes
● always required: source
● also required for uploads to a database: sourceType, Connection
● also required for downloads from a database table other than the default fileaccess table:
table, prefixColumn, fileNameColumn, dataColumn
● also required for downloads from a database table using a CLOB column for file data:
fileType
Also, for a download from a file system, you must call the setBaseDir() method to provide a servlet
context and HTTP request object so the bean can find the fileaccess.properties file that
specifies the base directory.
Methods
4-327
Here are descriptions of the public methods of HttpDownloadBean.
Note:
Many of the attributes and setter methods for HttpDownloadBean are the same as for
HttpUploadBean.
● void listFiles(javax.servlet.http.HttpServletRequest req)

Once all required and appropriate bean attributes have been set, use this method to list the files
available for download. These are files in the source directory or matching the source database
prefix. The req parameter is the servlet response instance. For a JSP page, use the implicit
request object.
For use from the file list, you can create HREF links to DownloadServlet, passing it each file
and file prefix, allowing the user to click on the link for each file they want to download.
Note:
The listFiles() method writes the file names to memory and to the JSP page or
servlet. If you later want to access the file names again, use the getFileNames()
method, which reads them from memory.
● java.util.Enumeration getFileNames()
This method returns an Enumeration instance containing the names of the files that are
available for download. It requires that the listFiles() method was already called--
listFiles() writes the file names to memory and to the JSP page or servlet;
getFileNames() reads them from memory.
● void setBaseDir(javax.servlet.ServletContext sc
javax.servlet.http.HttpServletRequest req)
For a download from a file system, use this method to determine what to use as the base
directory. It gets this information from the fileaccess.properties file in your application
/WEB-INF directory, which it finds through the servlet context input parameter. The baseDir
setting, together with the source setting, specifies the absolute path to the directory from which
4-328
files will be downloaded.
The sc parameter is the servlet context instance for the application. For JSP pages, use the
implicit application object.
The req parameter is for the servlet request instance to use in requesting the base directory
information. For JSP pages, use the implicit request object.
A base directory is not relevant for downloads from a database.
● void setSource(String source)
This is always required.
For a download from a file system, source, together with the base directory, specifies the
absolute path to the directory from which files will be downloaded. If source is set to "*", then
all directories under the base directory will be available for downloading.
For a download from a database, source is used as the file prefix (base directory is not
relevant). The prefix is equivalent to a file system path and can be used to group files into a
hierarchy. If recurse is enabled, "%" will be appended onto the source value, and the WHERE
clause for the query will contain an appropriate LIKE clause. Therefore, all files with prefixes
that are partially matched by the source value will be available for download. If you want to
match all rows in the database table, set source to "*".
Note:
Typically, the source value will be based at least partially on user input.
● void setSourceType(String sourceType)

● void setSourceType(int sourceType)

Use the overloaded setSourceType() method to specify whether the download is from a file
system or a database.
To download from a database, set sourceType to the string "database", the defined String
4-329
constant FileAccessUtil.DATABASE, the int value 1, or the defined int constant
FileAccessUtil.LOCATION_TYPE_DATABASE.
Downloading from a file system is the default, but if you want to specify this explicitly, set
sourceType to the string "filesystem", the defined String constant
FileAccessUtil.FILESYSTEM, the int value 0, or the defined int constant
FileAccessUtil.LOCATION_TYPE_FILESYSTEM. FileAccessUtil is in the
String getSourceType()
● void setRecurse(String recurse) throws FileAccessException
● void setRecurse(boolean recurse)
Use the overloaded setRecurse() method to enable or disable recursive downloading, where
files in file system subdirectories or with additional database prefix information will also be
available for downloading. As an example of recursive downloading from a database, assume
source is set to "/user". Recursive downloading would also find matches for files with prefixes
such as /user/bill and /user/mary, and also such as /user1, /user2, /user1/tom,
and /user2/susan.
Recursive downloading is enabled by default, but you can enable it explicitly with a recurse
setting of the string "true" or the boolean true. Disable recursive downloading with a setting of
the string "false" or the boolean false. String settings are case-insensitive. No settings are
accepted other than those listed here.
Note:
Practically speaking, recursive downloading is of limited value for a file system download.
To parallel the server subdirectory structure when downloading files to the client, the
subdirectories would have to already exist. HttpDownloadBean cannot create the client
subdirectories automatically.
● void setFileType(String fileType)

4-330
● void setFileType(int fileType) throws FileAccessException
For a download from a database, use the overloaded setFileType() method to specify
whether the data is stored in a BLOB for binary data (the default) or a CLOB for character data.
For a CLOB, set fileType to the string "character", the defined String constant
FileAccessUtil.CHARACTER_FILE, or the int value 1. To explicitly specify a BLOB, set
fileType to the string "binary", the defined String constant
FileAccessUtil.BINARY_FILE, or the int value 0. String settings are case-insensitive. No
settings are accepted other than those listed here. FileAccessUtil is in the
String getFileType()
● void setTable(String tableName)
For a download from a database table other than the default fileaccess table, use this
method to specify the table name.
String getTable()
● void setPrefixColumn(String prefixColumnName)
method to specify the name of the column containing the file prefix. (In fileaccess, this
column name is fileprefix.)
String getPrefixColumn()
● void setFileNameColumn(String fileNameColumnName)
method to specify the name of the column containing the file name. (In fileaccess, this
4-331
column name is filename.) The file name includes any file name extension.
String getFileNameColumn()
● void setDataColumn(String dataColumnName)
method to specify the name of the BLOB or CLOB column that holds the file contents. (In
fileaccess, this column name is data.)
String getDataColumn()
● void setConnection(ConnBean conn)
● void setConnection(java.sql.Connection conn)
For a download from a database table (default table or otherwise), use this method to provide a
database connection. You can provide an instance of either oracle.jsp.dbutil.ConnBean
or the standard java.sql.Connection type. For information about the ConnBean JavaBean,
see "ConnBean for a Database Connection".
If you use a Connection instance, you must explicitly open and close it. For a ConnBean
instance, this is handled automatically.
Example
This example is a JSP page that uses HttpDownloadBean for a download from a file system. Note
that the page must construct the URL for the download servlet.
<%@ page language="java" import="java.util.*, oracle.jsp.webutil.fileaccess.*"

%>
<html><body>
<% String servletPath = "/servlet/download/"; // path to the download servlet
String userDir = "fileaccess/"; // user part of download directory
%>
<jsp:useBean id="dbean"
4-332
class="oracle.jsp.webutil.access.HttpDownloadBean" >
<jsp:setProperty name="dbean" property="source" value='<%=userDir %>' />
</jsp:useBean>
<% dbean.setBaseDir(application, request);
dbean.listFiles(request); %>
The following files were found:
<% Enumeration fileNames = dbean.getFileNames();
while (fileNames.hasMoreElements()) {
String name = (String)fileNames.nextElement(); %>
<br><a href="<%= servletPath + name %>" > <%= name %></a>
<% } %>
<br>Done!
</body></html>
The DownloadServlet
To use download functionality, through either HttpDownloadBean or the httpDownload tag, you
must have DownloadServlet available in your Web server. Its class file name is as follows:
oracle.jsp.webutil.fileaccess.DownloadServlet.class
Its mapping in your Web server must be reflected in your servlet path settings, either through the
servletPath attribute if you use the httpDownload tag, or in your application code if you use
HttpDownloadBean. For an example of how to configure it in your Web server, see the /WEB-
INF/web.xml file for the OC4J demos.
The OC4J demos, for example, expect to find DownloadServlet mapped to the servlet name
download in the servlet zone servlets. That is, it must be accessible by the following relative path,
unless you edit the demos:
/servlet/download
DownloadServlet also requires the files ojsputil.jar and ojsp.jar to be available to your
Web server.
FileAccessException Class
The oracle.jsp.webutil.fileaccess.FileAccessException class is a convenience class

supplied with OC4J for file-access exception-handling. It wraps the functionality of the standard
java.sql.SQLException and java.io.IOException classes. It handles exceptions from either
of the file-access beans in addition to handling SQL and I/O exceptions.
4-333
File Upload and Download Tag Descriptions
For file uploading, OC4J supplies the httpUpload tag. This tag, in turn, uses HttpUploadBean. For
convenience, you can also use the httpUploadForm tag in programming the form through which
users specify the files to upload, or you can code the form manually.
For file downloading, OC4J provides the custom httpDownload tag.This tag uses
HttpDownloadBean.
This section describes these tags and their attributes.
The tag library description file for the file access tags is fileaccess.tld, located in the OC4J
/j2ee/tlds directory. To use the library, you will need a taglib directive such as the following:
<%@ taglib uri="/WEB-INF/fileaccess.tld" prefix="fileaccess" %>
Notes:
● The prefix "fileaccess:" is used in the tag syntax here. This is by convention but is not
The httpUploadForm Tag
For convenience, you can use the httpUploadForm tag to create a form in your application, using
multipart encoded form data, that allows users to specify the files to upload.
Syntax
<fileaccess:httpUploadForm formsAction = "action"

[ maxFiles = "max_number" ]
[ fileNameSize = "file_input_box_num_chars" ]
[ maxFileNameSize = "max_file_name_num_chars" ]
[ includeNumbers = "true" | "false" ]
[ submitButtonText = "button_label_text" ] />
4-334
Note:
The httpUploadForm tag can optionally use a body. For example, the body might consist of a
user prompt.
Attributes
● formsAction (required)--This is to indicate the action that will be performed after the form is
submitted. For example, formsAction could be the name of a JSP page that uses
HttpUploadBean or the httpUpload tag.
● maxFiles--Use this if you want to specify the number of input lines you want to appear in the
form. The default is 1.
● fileNameSize--Use this if you want to specify the character-width of the file name input
box(es). The default is 20 characters.
● maxFileNameSize--Use this if you want to specify the maximum number of characters allowed
in a file name. The default is 80 characters.
● includeNumbers--Set this to "true" if you want the file name input boxes to be numbered.
● submitButtonText--Use this if you want to specify the text that appears on the "submit"
button of the form. The default is "Send".
The httpUpload Tag
This tag wraps the functionality of the HttpUploadBean JavaBean, paralleling its attributes. See
"Overview of File Uploading" and "The HttpUploadBean" for related information.
Syntax
<fileaccess:httpUpload destination = "dir_path_or_prefix"

[ destinationType = "filesystem" | "database" ]
[ connId = "id" ]
[ scope = "request" | "page" | "session" | "applicaton" ]
[ overwrite = "true" | "false" ]
[ fileType = "character" | "binary" ]
[ table = "table_name" ]
4-335
[ prefixColumn = "column_name" ]
[ fileNameColumn = "column_name" ]
[ dataColumn = "column_name" ] />
Note:
For uploads to a file system, the base directory is automatically retrievable by the tag handler
from the JSP page context.
Attributes
● destination (required)--For uploading to a file system, this indicates the path, beneath the
base directory supplied in the /WEB-INF/fileaccess.properties file, of the directory into
which files will be uploaded. For uploading to a database, destination indicates the file
prefix, conceptually equivalent to a file system path.
Note:
Typically, the destination value will be based at least partially on user input.
● destinationType--Set this to "database" for uploading to a database. The default is to upload

to a file system, but you can also explicitly set it to "filesystem". These values are case-
insensitive.
● connId--For uploading to a database, you can use this to provide a ConnBean connection ID
for the database connection to be used. Or, alternatively, you can use the httpUpload tag
inside a dbOpen tag to implicitly use the dbOpen connection. For information about the
ConnBean JavaBean and dbOpen tag provided with OC4J, see Chapter 4, "Data-Access
JavaBeans and Tags".
● scope--For uploading to a database, you can use this to specify the scope of the ConnBean
instance for the connection. The scope setting here must match the scope setting when the
ConnBean instance was created, such as in a dbOpen tag. If the httpUpload tag is nested
inside a dbOpen tag, then there is no need to specify connId or scope--that information will be
taken from the dbOpen tag. Otherwise, the default scope setting is page.
● overwrite--Set this to "false" if you do not want to overwrite existing files that have the same
4-336
paths and names as the files you are uploading, or do not want to update rows with the same
file name and prefix for database uploading. In this case, an error will be generated if a file
already exists. By default, overwrite is set to "true" and httpUpload overwrites files.
● fileType--For uploading to a database, set this to "character" for character data, which will be
written into a CLOB. The default setting is "binary" for binary data, which will be written into a
BLOB.
● table--For uploading to a database table other than the default fileaccess table, use this to
specify the table name.
● prefixColumn--For uploading to a database table other than the default fileaccess table,
use this to specify the name of the column containing file prefixes. This column is where the
destination values will be written.
● fileNameColumn--For uploading to a database table other than the default fileaccess

table, use this to specify the name of the column containing file names.
● dataColumn--For uploading to a database table other than the default fileaccess table, use
this to specify the name of the column containing file contents.
Example
This example has a page that uses the httpUploadForm tag to create the HTML form for specifying
files to upload. The httpUploadForm tag specifies httpUploadExample.jsp as its forms action.
The httpUploadExample.jsp page uses the httpUpload tag to upload to the default
fileaccess table in a database.
Here is the page for the HTML form.
<%@ page language="java" import="java.io.*" %>

<%@ taglib uri="/WEB-INF/fileaccess.tld" prefix="upload" %>
<html> <body>
<upload:httpUploadForm
formsAction="httpUploadExample.jsp"
maxFiles='<%= request.getParameter("MaxFiles") %>'
includeNumbers="true" fileNameSize="50" maxFileNameSize="120" >
<br> File:
</upload:httpUploadForm>
</body> </html>
4-337
And here is the httpUploadExample.jsp page. Note that the httpUpload tag gets its database
connection as a result of being inside a dbOpen tag.
<%@ page language="java" %>

<%@ taglib uri="/WEB-INF/fileaccess.tld" prefix="upload" %>
<% String connStr=request.getParameter("connStr"); // get the connection string
if (connStr==null) { connStr=(String)session.getValue("connStr"); }
else { session.putValue("connStr",connStr); }
if (connStr==null) { %>
<jsp:forward page="setconn.jsp" />
<% } %>
<html><body>
<sql:dbOpen URL="<%= connStr %>" user="scott" password="tiger" >
<upload:httpUpload destinationType = "database" destination="tagexample" />
</sql:dbOpen>
Done! </body></html>
The httpDownload Tag
This tag wraps the functionality of the HttpDownloadBean JavaBean, paralleling its attributes. See
"Overview of File Downloading" and "The HttpDownloadBean" for related information.
Syntax
<fileaccess:httpDownload servletPath = "path"

source = "dir_path_or_prefix"
[ sourceType = "filesystem" | "database" ]
[ connId = "id" ]
[ scope = "request" | "page" | "session" | "applicaton" ]
[ recurse = "true" | "false" ]
[ fileType = "character" | "binary" ]
[ table = "table_name" ]
[ prefixColumn = "column_name" ]
[ fileNameColumn = "column_name" ]
[ dataColumn = "column_name" ] />
4-338
Notes:
● The httpDownload tag can optionally use a body. For example, the body might consist
of a user prompt.
● For downloads from a file system, the base directory is automatically retrievable by the
tag handler from the JSP page context.
Attributes
● servletPath (required)--The path to the Oracle DownloadServlet, which executes the

actual download of each file. For example, if DownloadServlet has been installed in the
application app and mapped to the name download, then use "/app/download/", with leading
and trailing slashes, as the servletPath setting. The httpDownload tag handler uses this
path in constructing the URL to DownloadServlet.
See "The DownloadServlet" for more information about this servlet.
● source (required)--For downloading from a file system, this indicates the path, beneath the
base directory supplied in the file /WEB-INF/fileaccess.properties, of the directory from
which files are retrieved. A value of "*" results in all directories under the base directory being
available.
For downloading from a database, this indicates the file prefix, conceptually equivalent to a file
system path. If recurse is enabled, "%" will be appended onto the source value, and the
WHERE clause for the query will contain an appropriate LIKE clause. Therefore, all files with
prefixes that are partially matched by the source value will be available for download. If you want
to match all rows in the database table, set source to "*".
Note:
Typically, the source value will be based at least partially on user input.
● sourceType--Set this to "database" for downloading from a database. The default is to

download from a file system, or you can explicitly set this to "filesystem".
● connId--For downloading from a database, you can use this to provide a ConnBean connection
4-339
ID for the database connection to be used. Or, alternatively, you can use the httpDownload
tag inside a dbOpen tag to implicitly use the dbOpen connection. For information about the
ConnBean JavaBean and dbOpen tag provided with OC4J, see Chapter 4, "Data-Access
JavaBeans and Tags".
● scope--For downloading from a database, you can use this to specify the scope of the
ConnBean instance for the connection. The scope setting here must match the scope setting
when the ConnBean instance was created, such as in a dbOpen tag. If the httpDownload tag
is nested inside a dbOpen tag, then there is no need to specify connId or scope--that
information will be taken from the dbOpen tag. Otherwise, the default scope setting is page.
● recurse--Set this to "false" if you do not want recursive downloading, where files in file system
subdirectories or with additional database prefix information will also be available for download.
As an example of recursive downloading from a database, assume you have set source to
"/user". Recursive downloading would also find matches for files with prefixes such as
/user/bill and /user/mary, and also such as /user1, /user2, /user1/tom, and
/user2/susan. The default is recursive downloading, or you can enable it explicitly with a
setting of "true".
● fileType--For downloading from a database, set this to "character" for character data, which
will be retrieved from a CLOB. The default is "binary" for binary data, which will be retrieved from
a BLOB.
● table--For downloading from a database table other than the default fileaccess table, use
this to specify the table name.
● prefixColumn--For downloading from a database table other than the default fileaccess
table, use this to specify the name of the column containing file prefixes, which is where source
values are stored.
● fileNameColumn--For downloading from a database table other than the default fileaccess
table, use this to specify the name of the column containing file names. File names include any
file name extensions.
● dataColumn--For downloading from a database table other than the default fileaccess
table, use this to specify the name of the column that stores the file contents.
Example
4-340
This example is a JSP page that uses the httpDownload tag to download from the default
fileaccess table of a database. The tag body content ("<br>:") will be output before each file name
in the list of files available for download. Note that the DownloadServlet servlet path must be
specified in the httpDownload tag; the tag handler will use it in constructing the URL to
DownloadServlet, which performs the actual downloading.
<%@ page language="java" %>

<%@ taglib uri="/WEB-INF/fileaccess.tld" prefix="download" %>
<% String connStr=request.getParameter("connStr");
if (connStr==null) { connStr=(String)session.getValue("connStr");}
else { session.putValue("connStr",connStr);}
<jsp:forward page="setconn.jsp" />
<% } %>
<html> <body>
<% String servletPath = "/servlet/download/"; %>
<sql:dbOpen URL="<%= connStr %>" user="scott" password="tiger" >
<download:httpDownload sourceType = "database"
source="tagexample" servletPath = `<%= servletPath %>' >
<br>:
</download:httpDownload>
</sql:dbOpen>
<br>Done!
</body> </html>
EJB Tags
OC4J provides a custom tag library to simplify the use of Enterprise JavaBeans in JSP pages.
The functionality of the OC4J EJB tags follows the J2EE specification. The tags allow you to instantiate
EJBs by name, using configuration information in the web.xml file. One of the tags is a useBean tag,
with functionality similar to that of the standard jsp:useBean tag for invoking a regular JavaBean.
The rest of this section is organized as follows:
● EJB Tag Configuration
● EJB Tag Descriptions
● EJB Tag Examples
4-341
EJB Tag Configuration
Use an <ejb-ref> element in your application web.xml file for each EJB you will use, as in the
following example:
<ejb-ref>
<ejb-ref-name>ejb/DemoSession</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>ejbdemo.DemoSessionHome</home>
<remote>ejbdemo.DemoSession</remote>
</ejb-ref>
The <ejb-ref> element and its subelements are used according to the Sun Microsystems Servlet
Specification, Version 2.2. Briefly, this is as follows:
● The <ejb-ref-name> subelement specifies a reference name that can be used by other
components of a J2EE application to access this component. For example, this name could be
used in a location value.
● The <ejb-ref-type> subelement specifies the category of EJB.
● The <home> subelement specifies the package and type of the EJB home interface.
● The <remote> subelement specifies the package and type of the EJB remote interface.
These values are reflected in attribute values of the EJB tags.
EJB Tag Descriptions
This section provides syntax and attribute descriptions for the OC4J EJB tags.
The tag library description file for the EJB tags is ejbtaglib.tld, located in the OC4J /j2ee/tlds
directory. To use the library, you will need a taglib directive such as the following:
<%@ taglib uri="/WEB-INF/ejbtaglib.tld" prefix="ejb" %>
4-342
Notes:
● The prefix "ejb:" is used in the tag syntax here. This is by convention but is not required.
The following tags are available:
● EJB useHome Tag
● EJB useBean Tag
● EJB createBean Tag
● EJB iterate Tag
When first creating an EJB instance, you will have to use a useHome tag to create a home interface
instance, then the following as appropriate:
● to create a single EJB instance: a useBean tag, and either the useBean tag value attribute or
a nested createBean tag
● to create a collection of EJB instances and iterate through them (more typical for entity beans):
an iterate tag
After an EJB instance is created, it is placed in the appropriate scope object, and you will need only a
useBean tag to access it subsequently.
EJB useHome Tag
The useHome tag looks up the home interface for the EJB and creates an instance of it.
Syntax
<ejb:useHome id = "home_instance_name"
type = "home_interface_type"
location = "home_lookup_name" />
4-343
This tag uses no body.
Attributes
● id (required)--Specify a name for the home interface instance. The instance is accessible from
the start tag to the end of the page.
● type (required)--This is for the name (Java type) of the home interface.
● location (required)--This is a JNDI name used to look up the home interface of the desired
EJB within the application.
Example
<ejb:useHome id="aomHome" type="com.acme.atm.ejb.AccountOwnerManagerHome"

location="java:comp/env/ejb/accountOwnerManager" />
EJB useBean Tag
Use the EJB useBean tag for instantiating and using the EJB. The id, type, and scope attributes are
used as in a standard jsp:useBean tag that instantiates a regular JavaBean.
You can use one of two mechanisms when you first instantiate the EJB:
● the value attribute
or:
● a nested EJB createBean tag
When using a createBean tag, the EJB instance is implicitly returned into the value attribute of the
parent useBean tag. Once the EJB is instantiated, value attributes and nested createBean tags are
unnecessary for subsequent useBean tags using the same EJB instance.
4-344
Note:
See "EJB iterate Tag" for how to use a collection of EJB instances.
Syntax
<ejb:useBean id = "EJB_instance_name"
type = "EJB_class_name"
[ value = "<%=Object%>" ]
[ scope = "page" | "request" | "session" | "application" ] >
... nested createBean tag for first instantiation (if no value attribute) ...
</ejb:useBean>
Attributes
● id (required)--Specify an instance name for the EJB.
● type (required)--This is the class name for the EJB.
● value--When first instantiating the EJB, if you do not use a nested createBean tag, you can
use the value attribute to return an EJBObject instance to narrow. This is a mechanism for
instantiating the EJB.
● scope--Specify the scope of the EJB instance. The default is page scope.
Example
This example shows the use of an EJB that has already been instantiated.
<ejb:useBean id="bean" type="com.acme.MyBean" scope="session" />
EJB createBean Tag
For first instantiating an EJB, if you do not use the value attribute of the EJB useBean tag, you must
nest an EJB createBean tag within the useBean tag to do the work of creating the EJB instance.
This will be an EJBObject instance. The instance is implicitly returned into the value attribute of the
4-345
parent useBean tag.
Syntax
<ejb:createBean instance = "<%=Object%>" />
Attributes
● instance (required)--This is to return the EJB, a created EJBObject instance.
Example
In this createBean tag, the create() method of the EJB home interface instance creates an
instance of the EJB.
<ejb:useBean id="bean" type="com.acme.MyBean" scope="session">

<ejb:createBean instance="<%=home.create()%>" />
</ejb:useBean>
EJB iterate Tag
Use this tag to iterate through a collection of EJB instances. This is more typical for entity beans,
because standard finder methods for entity beans return collections.
In the start tag, obtain the collection through finder results from the home interface. In the tag body,
iterate through the collection as appropriate.
Note:
● This tag has the same semantics as the more general iterate utility tag, discussed in
"Utility iterate Tag". It is copied into the EJB tag library for convenience.
● See "EJB useBean Tag" for how to use a single EJB instance.
Syntax
4-346
<ejb:iterate id = "EJB_instance_name"
type = "EJB_class_name"
collection = "<%=Collection%>"
[ max = "<%=Integer%>" ] >
... body ...
</ejb:iterate>
The body is evaluated once for each EJB in the collection.
Attributes
id (required)--This is an iterator variable, the EJB instance name for each iteration.
type (required)--This is the EJB class name.
collection (required)--This is to return the EJB collection.
max--Optionally specify a maximum number of beans to iterate through.
Example
<ejb:iterate id="account" type="com.acme.atm.ejb.Account"

collection="<%=accountManager.getOwnerAccounts()%>"
max="100">
<jsp:getProperty name="account" property="id" />
</ejb:iterate>
EJB Tag Examples
This section provides examples of EJB tag usage, one using a session bean and one use an entity
bean.
EJB Tag Session Bean Example
This example relies on the following configuration in the application web.xml file:
<ejb-ref>
<ejb-ref-name>ejb/DemoSession</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>ejbdemo.DemoSessionHome</home>
<remote>ejbdemo.DemoSession</remote>
4-347
</ejb-ref>
Here is the sample code:
<%@ page import="ejbdemo.*" %>

<html>
<head> <title>Use EJB from JSP</title> </head>
<body>
<ejb:useHome id="home" type="ejbdemo.DemoSessionHome"

location="java:comp/env/ejb/DemoSession" />
<ejb:useBean id="demo" type="ejbdemo.DemoSession" scope="session" >
<ejb:createBean instance="<%=home.create()%>" />
</ejb:useBean>
<heading2> Enterprise Java Bean: </heading2>
<p><b> My name is "<%=demo.getName()%>". </b></p>
</body>
</html>
This accomplishes the following:
● Creates the home instance of the EJB home interface. Note that the type value of the useHome
tag matches the <home> value of the <ejb-ref> element in the web.xml file, and that the
location value of useHome reflects the <ejb-ref-name> value of the <ejb-ref> element.
● Uses the home.create() method to create the demo instance of the EJB. Note that the type
value of the useBean tag matches the <remote> value of the <ejb-ref> element in the
web.xml file.
● Uses the demo.getName() method to print a user name.
EJB Tag Entity Bean Example
This example relies on the following configuration in the application web.xml file:
<ejb-ref>
<ejb-ref-name>ejb/DemoEntity</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>ejbdemo.DemoEntityHome</home>
<remote>ejbdemo.DemoEntity</remote>
</ejb-ref>
4-348
Here is the sample code:
<%@ page import="ejbdemo.*" %>

<html>
<head> <title>Iterate over EJBs from JSP</title> </head>
<body>
<ejb:useHome id="home" type="ejbdemo.DemoEntityHome"

location="java:comp/env/ejb/DemoEntity" />
<% int i=0; %>
<ejb:iterate id="demo" type="ejbdemo.DemoEntity"
collection="<%=home.findAll()%>" max="3" >
<li> <heading2> Bean #<%=++i%>: </heading2>
<b> My name is "<%=demo.getName()+"_"+ demo.getId()%>". </b> </li>
</ejb:iterate>
</body>
</html>
This accomplishes the following:
● Creates the home instance of the EJB home interface. Note that the type value of the useHome
tag matches the <home> value of the <ejb-ref> element in the web.xml file, and that the
location value of useHome reflects the <ejb-ref-name> value of the <ejb-ref> element.
● Uses the home.findAll() method to return a collection of EJBs. Note that the type value in
the iterate tag matches the <remote> value of the <ejb-ref> element in the web.xml file.
● Iterates through the collection, always using demo for the current instance, and using the
demo.getName() and demo.getId() methods to output information from each EJB.
Utility Tags
OC4J provides a number of utility tags to perform various operations. This section documents these
tags and is organized as follows:
● Display Tags
● Other Utility Tags
4-349
The tag library description file for the utility tags is utiltaglib.tld, located in the OC4J
/j2ee/tlds directory. To use the library, you will need a taglib directive such as the following:
<%@ taglib uri="/WEB-INF/utiltaglib.tld" prefix="util" %>
Notes:
● The prefix "util:" is used in the tag syntax here. This is by convention but is not required.
Display Tags
This section documents the following tags:
● Utility displayCurrency Tag
● Utility displayDate Tag
● Utility displayNumber Tag
Utility displayCurrency Tag
This tag displays a specified amount of money, formatted as currency for the locale. If no locale is
specified, then the request object will be searched for a locale. If none is found there, the system
default locale is used.
Syntax
<util:displayCurrency amount = "<%=Double%>"

[ locale = "<%=Locale%>" ] />
Attributes
● amount (required)--Specify the amount to format.
4-350
● locale--Optionally specify a locale (java.util.Locale).
Example
<util:displayCurrency amount="<%=account.getBalance()%>"
locale="<%=account.getLocale()%>" />
Utility displayDate Tag
This tag displays a specified date, formatted appropriately for the locale. If no locale is specified, the
system default locale is used.
Syntax
<util:displayDate date = "<%=Date%>"

Attributes
● date (required)--Specify the date to format (java.util.Date).
● locale--Optionally specify a locale (java.util.Locale).
Example
<util:displayDate date="<%=account.getDate()%>"
locale="<%=account.getLocale()%>" />
Utility displayNumber Tag
This displays the specified number, for the locale and optionally in the specified format. If no locale is
specified, the system default locale is used.
Syntax
<util:displayNumber number = "<%=Double%>"

[ locale = "<%=Locale%>" ]
4-351
[ format = "<%=Format%>" ] />
Attributes
● number (required)--Specify the number to format.
● locale--Optionally specify the locale (java.util.Locale).
● format--Optionally specify a format (java.text.Format).
Example
<util:displayNumber number="<%=shoe.getSize()%>" />
Other Utility Tags
This section documents the following tags:
● Utility iterate Tag
● Utility ifInRole Tag
● Utility lastModified Tag
Utility iterate Tag
Use this tag to iterate through a collection. Obtain the collection in the start tag; iterate through it in the
body.
Syntax
<util:iterate id = "instance_name"
type = "class_name"
collection = "<%=Collection%>"
[ max = "<%=Integer%>" ] >
... body ...

4-352
</util:iterate>
The body is evaluated once for each element in the collection.
Attributes
id (required)--This is an iterator variable, the instance name for each iteration.
type (required)--This is the class name; the collection is a set of instances of this type.
collection (required)--This is for the collection itself.
max--Optionally specify a maximum number of elements to iterate through.
Example
<util:iterate id="contact" type="com.acme.connections.Contact"

collection="<%=company.getContacts()%>" >
<jsp:getProperty name="contact" property="name"/>
</util:iterate>
Utility ifInRole Tag
Use this tag to evaluate the tag body and include it in the body of the JSP page, depending on whether
the user is in the specified application role. The tag handler executes the isUserInRole() method of
the request object.
The concept of "role" is according to the Sun Microsystems Java Servlet Specification, Version 2.2.
Roles are defined in <role> elements in the application web.xml file.
Syntax
<util:ifInRole role = "<%=String%>"

[ include = "true" | "false" ] >
... body to include ...
</util:ifInRole>
Attributes
4-353
● role (required)--Check to see if the user is in this specified role.
● include--Use a "true" setting (the default) to include the body only if the user is in the role. Use
a "false" setting to include the body only if the user is not in the role.
Example
<util:ifInRole role="users" include="true">

Logged in as <%=request.getRemoteUser()%><br>
<form action="logout.jsp">
<input type="submit" value="Log out"><br>
</form>
</util:ifInRole>
<util:ifInRole role="users" include="false">
<form method="POST">
Username: <input name="j_username" type="text"><br>
Password: <input name="j_password" type="password"><br>
<input type="submit" value="Log in">
</form>
</util:ifInRole>
Utility lastModified Tag
This tag displays the date of the last modification of the current file, appropriately for the locale. If no
locale is specified, then the request object will be searched for a locale. If none is found there, the
system default locale is used.
Syntax
<util:lastModified
Attributes
● locale--Optionally specify the locale (java.util.Locale).
Example
<util:lastModified />
4-354
About JSP Utility Tags
OC4J provides utility tags to accomplish the following from within Web applications:
● Sending e-mail messages
● Uploading and downloading files
● Using EJBs
● Using miscellaneous utilities
For sending e-mail messages, you can use the sendMail tag or the
oracle.jsp.webutil.email.SendMailBean JavaBean.
For uploading files, you can use the httpUpload tag or the
oracle.jsp.webutil.fileaccess.HttpUploadBean JavaBean. For downloading, there is the
httpDownload tag or the HttpDownloadBean JavaBean.
For using EJBs, there are tags to create a home instance, create an EJB instance, and iterate
through a collection of EJBs.
There are also utility tags for displaying a date, displaying an amount of money in the
appropriate currency, displaying a number, iterating through a collection, evaluating and
including the tag body depending on whether the user belongs to a specified role, and
displaying the last modification date of the current file.
4-355
Reference: OC4J EMail Tags
Library Syntax
<%@ taglib uri="email.tld" prefix="email" %>
Syntax usage:
EMail Tag Library
Name Syntax
<email:sendMail
[host]
sender
recipient
[cc]
sendMail - This email tag sends the tag
[bcc]
body as an email.
[subject]
[session]
[contentType]
[contentEncoding] > JSP content
</email:sendMail>
4-356
Reference: OC4J File Access Tags
Library Syntax
<%@ taglib uri="fileaccess.tld" prefix="fileaccess" %>
Syntax usage:
File Access Tag Library
Name Syntax
<fileaccess:httpDownload
source
[sourceType]
servletPath
[connId]
[scope]
httpDownload - This tag downloads files
[table]
from a server to the client.
[prefixColumn]
[fileNameColumn]
[dataColumn]
[fileType]
[recurse] > JSP content
</fileaccess:httpDownload>
4-357
<fileaccess:httpUpload
destination
[destinationType]
[connId]
[scope]
httpUpload - This tag uploads files from the [table]
client to a server. [prefixColumn]
[fileNameColumn]
[dataColumn]
[fileType]
[overwrite] > JSP content
</fileaccess:httpUpload>
<fileaccess:httpUploadForm
formsAction
[maxFiles]
httpUploadForm - This tag creates a form for [fileNameSize]
inputting files to upload. [maxFileNameSize]
[includeNumbers]
[submitButtonText] > JSP content
</fileaccess:httpUploadForm>
4-358
Reference: OC4J Enterprise Java Beans Tags
Library Syntax
<%@ taglib uri="http://xmlns.oracle.com/jsp/taglibs/ejbtaglib.tld"

prefix="EJB" %>
Syntax usage:
OC4J EJB Tag Library
Name Syntax
<EJB:createBean
createBean - Create a bean instance.
instance />
<EJB:iterate
id
iterate - Iterate over the finder result from a type
home. collection
[max] > jsp content
</EJB:iterate>
<EJB:useBean
id
type
useBean - Look up and narrow a bean.
[value]
[scope] > jsp content
</EJB:useBean>
<EJB:useHome
id
useHome - Look up an EJB home.
type
location />
4-359
Reference: OC4J Utility Helper Tags
Library Syntax
<%@ taglib uri="http://xmlns.oracle.com/jsp/taglibs/utiltaglib.tld"

prefix="util" %>
Syntax usage:
OC4J Utility Tag Library
Name Syntax
<util:displayCurrency
displayCurrency - Formats a given amount as
amount
currency for a given Locale.
[locale] />
<util:displayDate
displayDate - Formats a given Date for a given
date
Locale.
[locale] />
<util:displayNumber
displayNumber - Displays a number in a [locale]
formatted way. number
[format] />
<util:ifInRole
ifInRole - Includes the body if the user is in the role
specified role. [include] > jsp content
</util:ifInRole>
<util:iterate
id
type
iterate - Iterates over a Collection.
collection
[max] > jsp content
</util:iterate>
lastModified - Displays when a JSP page was <util:lastModified
last modified. [locale] />
4-360
Working with XML and XSL Tags
This chapter describes tags provided with OC4J that you can use for XML data and XSL
transformation, and summarizes additional XML functionality in other OC4J tags. These tags are
implemented according to JSP specifications.
The chapter is organized as follows:
● Overview of Oracle Tags for XML Support
● XML parsexml Tag to Convert from Input Stream
Note:
See the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for
additional information about XML-related functionality for JSP pages.
Overview of Oracle Tags for XML Support
This section provides an overview of tags supplied with OC4J that have XML functionality. This
includes tags that can take XML DOM objects as input, generate XML DOM objects as output,
transform XML documents according to a specified stylesheet, and parse data from an input
stream to an XML DOM object. The following topics are covered:
● XML Producers and XML Consumers
● Summary of OC4J Tags with XML Functionality
XML Producers and XML Consumers
An XML-related operation can be classified as either of the following, or as both:
● an XML producer, which outputs an XML object
● an XML consumer, which takes an XML object as input
4-361
Similarly, an XML-related tag can be classified as an XML producer or consumer or both. XML
producers can pass XML objects to XML consumers either explicitly or implicitly; the latter is also
known as anonymous passing.
For explicit passing between XML-related tags, there is a toXMLObjName attribute in the producer
tag and a fromXMLObjName attribute in the consumer tag. Behind the scenes, the passing is
done through the getAttribute() and setAttribute() methods of the standard JSP
PageContext object. The following example uses explicit passing:
<sql:dbQuery output="XML" toXMLObjName="foo" ... >

...SQL query...
</sql:dbQuery>
...
<ojsp:cacheXMLObj fromXMLObjName="foo" ... />
For implicit passing between XML-related tags, do not use the toXMLObjName and
fromXMLObjName attributes. The passing is accomplished through direct interaction between the
tag handlers, typically in a situation where the tags are nested. The following example uses implicit
passing:
<ojsp:cacheXMLObj ... >

<sql:dbQuery output="XML" >
...SQL query...
</sql:dbQuery>
</ojsp:cacheXMLObj>
Here the XML produced in the dbQuery tag is passed to the cacheXMLObj tag directly, without
being stored to the PageContext object.
For a tag to be able to function as a consumer with implicit passing, the tag handler implements
the OC4J ImplicitXMLObjConsumer interface:
interface ImplicitXMLObjConsumer
{
void setImplicitFromXMLObj();
}
Summary of OC4J Tags with XML Functionality
4-362
For the tag libraries supplied with OC4J, table Table 5-1 summarizes the tags that can function as
XML producers or consumers.
Table 5-1 OC4J Tags with XML Functionality
Producer /
Tag Library Consumer Related Attributes Tag Information
transform / styleSheet XML both fromXMLObjName "XML transform and
toXMLObjName styleSheet Tags for
XML/XSL Data
Transformation"
parsexml XML producer toXMLObjName "XML parsexml Tag to

Convert from Input Stream"
cacheXMLObj Web Object both fromXMLObjName "Web Object Cache

Cache (and toXMLObjName cacheXMLObj Tag"
XML)
dbQuery SQL producer toXMLObjName "SQL dbQuery Tag"
Notes:
● The XML transform and styleSheet tags are equivalent and produce identical
results.
● For convenience, the cacheXMLObj tag is defined in the XML tag library (xml.tld)
as well as the Web Object Cache tag library (jwcache.tld).
XML Utility Tags
This section describes XML utility tags supplied with OC4J, and is organized as follows:
● XML Utility Tag Descriptions
● XML Utility Tag Examples
In an Oracle9i Application Server installation, the tag library description file for XML utility tags,
xml.tld, is located in the [Oracle_Home]/j2ee/tlds directory. To use this TLD file, you will
need a taglib directive such as the following:
4-363
<%@ taglib uri="/WEB-INF/xml.tld" prefix="xml" %>
The XML tag library requires the ojsputil.jar file to be installed and in your classpath. This file
is supplied with OC4J.
Notes:
● The prefix "xml:" is used in the tag syntax here. This is by convention but is not
XML Utility Tag Descriptions
This section describes the following utility tags:
● XML transform and styleSheet Tags for XML/XSL Data Transformation
● XML parsexml Tag to Convert from Input Stream
Important:
Tag attributes are request-time attributes, meaning they can take JSP expressions as
input, unless otherwise noted.
XML transform and styleSheet Tags for XML/XSL Data Transformation
Many uses of XML and XSL for dynamic JSP pages require an XSL transformation to occur in the
server before results are returned to the client. Oracle provides two synonymous tags in the XML
library to simplify this process. You can output the result directly to the HTTP client or,
alternatively, you can output to a specified XML DOM object. Use either the transform tag or the
styleSheet tag, as described and shown in this section. The two tags are synonymous, having
identical effects.
Each tag acts as both an XML producer and an XML consumer. They can take as input either of
the following:
4-364
● an XML DOM object
● the tag body, containing JSP commands and static text that produce the XML code
And the tags can output to either or both of the following, with the specified stylesheet being
applied in either case:
● an XML DOM object, in which case no stylesheet is necessary
● the output writer to the browser, in which case the specified stylesheet is applied
Each tag applies to what is inside its body, between its start-tag and end-tag. You can have
multiple XSL transformation blocks within a page, with each block bounded by its own transform
or styleSheet tag set, specifying its own href pointer to the appropriate stylesheet.
Syntax
<xml:transform href="xslRef"
[...body...]
</xml:transform >
or:
<xml:styleSheet href="xslRef"
[...body...]
</xml:styleSheet >
Attributes
4-365
● href (required)--Specify the XSL stylesheet to use for the XML data transformation. This is
required whether you are outputting to an XML object (where you can have transformation
without formatting) or to the browser.
Note the following regarding the href attribute:
❍ It can refer to either a static XSL stylesheet or a dynamically generated one. For
example, it can refer to a JSP page or servlet that generates the stylesheet.
❍ It can be a fully qualified URL (http://host[:port]/path), an application-

relative JSP reference (starting with "/"), or a page-relative JSP reference (not starting
with "/"). You can refer to the Oracle9iAS Containers for J2EE Support for JavaServer
Pages Reference for information about application-relative and page-relative paths.
❍ Its value can be a static Java string constant literal, or it can be dynamically specified
through a standard JSP request-time expression.
● fromXMLObjName--Use this to specify an input XML DOM object if input is from a DOM
object instead of from the tag body.
If there is both a tag body and a fromXMLObjName specification, fromXMLObjName takes

precedence.
● toXMLObjName--Use this to specify the name of an output XML DOM object if output is to a
DOM object, instead of or in addition to going to the JSP writer object for output to the HTTP
client. This is not required if there is an implicit XML consumer, such as a tag within which
the transform or styleSheet tag is nested.
● toWriter--This is "true" or "false" to indicate whether output goes to the JSP writer object
for output to the HTTP client. This can be instead of or in addition to output to a DOM
object. The default is "true" for backwards compatibility. (In earlier releases this was the only
output choice; there was no toXMLObjName attribute.)
XML parsexml Tag to Convert from Input Stream
The XML tag library supplies an XML producer utility tag, parsexml, that converts from an input
stream to an XML DOM object. This tag can take input from a specified resource or from the tag
body.
4-366
Syntax
<xml:parsexml
[ resource = "xmlresource" ]
[ validateResource = "dtd_path" ]
[ root = "dtd_root_element" ] >
[...body...]
</xml:parsexml >
Attributes
● resource--Use this to specify an XML resource if input is from a resource instead of from
the tag body. For example:
resource="/dir1/hello.xml"
If there is both a tag body and a specified resource, the resource takes precedence.
● toXMLObjName--Specify the name of the XML DOM object where the output will go. This is
not required if there is an implicit XML consumer, such as a tag within which the parsexml
tag is nested.
● validateResource--For XML validation, you can specify the path to the appropriate DTD.
Alternatively, the DTD can be embedded in the XML resource. This is not a request-time
attribute.
● root--If validating, specify the root element in the DTD for validation. This is not a request-
time attribute. If you specify validateResource without specifying root, the default root
is the top-level of the DTD.
XML Utility Tag Examples
This section provides the following examples:
● Example Using the transform Tag
4-367
● Example Using the transform and dbQuery Tags
● Examples Using the transform and parsexml Tags
Example Using the transform Tag
This section provides a sample XSL stylesheet and a sample JSP page that uses the transform
tag to filter its output through the stylesheet. This is a simplistic example--the XML in the page is
static. A more realistic example might use the JSP page to dynamically generate all or part of the
XML before performing the transformation.
Sample Stylesheet: hello.xsl
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="page">
<html>
<head>
<title>
<xsl:value-of select="title"/>
</title>
</head>
<body bgcolor="#ffffff">
<xsl:apply-templates/>
</body>
</html>
</xsl:template>
<xsl:template match="title">
<h1 align="center">
</h1>
</xsl:template>
<xsl:template match="paragraph">
<p align="center">
<i>
</i>
</p>
</xsl:template>
</xsl:stylesheet>
4-368
Sample JSP Page: hello.jsp
<%@ page session = "false" %>

<xml:transform href="style/hello.xsl" >
<page>
<title>Hello</title>
<content>
<paragraph>This is my first XML/XSL file!</paragraph>
</content>
</page>
</xml:transform>
This example results in the following output:
Example Using the transform and dbQuery Tags
This example returns a result set from a dbQuery tag, using a transform tag to filter the query
results through the XSL stylesheet rowset.xsl. It uses a dbOpen tag to open a connection, with
the connection string being obtained either from the request object or through the setconn.jsp
4-369
page. Data passing from the dbOpen tag to the transform tag is done implicitly.
The file rowset.xsl is also listed below.
<%@ page import="oracle.sql.*, oracle.jdbc.driver.*, oracle.jdbc.*, java.sql.*"

%>
<%
String connStr=request.getParameter("connStr");
if (connStr==null) {
connStr=(String)session.getValue("connStr");
} else {
session.putValue("connStr",connStr);
}
<jsp:forward page="../../sql/setconn.jsp" />
<%
}
%>
<h3>Transform DBQuery Tag Example</h3>
<xml:transform href="style/rowset.xsl" >
<sql:dbOpen connId="conn1" URL="<%= connStr %>"
user="scott" password="tiger">
</sql:dbOpen>
<sql:dbQuery connId="conn1" output="xml" queryId="myquery" >
select ENAME, EMPNO from EMP order by ename
</sql:dbQuery>
<sql:dbClose connId="conn1" />
</xml:transform>
rowset.xsl
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>

<xsl:template match="ROWSET">
<html><body>
<h1>A Simple XML/XSL Transformation</h1>
<table border="2">
<xsl:for-each select="ROW">
<tr>
<td><xsl:value-of select="@num"/></td>
<td><xsl:value-of select="ENAME"/></td>
<td><xsl:value-of select="EMPNO"/></td>
4-370
</tr>
</xsl:for-each>
</table>
</body></html>
</xsl:template>
</xsl:stylesheet>
Examples Using the transform and parsexml Tags
This section provides two examples that take output from a parsexml tag and filter it through a
transform tag, using the XSL stylesheet email.xsl. In each case, data is collected by
parsexml from a specified resource XML file, then passed explicitly from the parsexml tag to
the transform tag through the toxml1 XML object.
The first example uses the XML resource email.xml and a separate DTD, email.dtd. No
root attribute is specified, so validation is from the top-level element, email.
The second example uses the XML resource emailWithDtd.xml, which has the DTD
embedded in the file. The root attribute explicitly specifies that validation is from the element
email.
The files email.xml, email.dtd, emailWithDtd.xml, and email.xsl are also listed below.
Example 1 for transform and parsexml

<h3>XML Parsing Tag Email Example</h3>
<xml:transform fromXMLObjName="toxml1" href="style/email.xsl">
<xml:parsexml resource="style/email.xml" validateResource="style/email.dtd"
toXMLObjName="toxml1">
</xml:parsexml>
</xml:transform>
Example 2 for transform and parsexml

<h3>XML Parsing Tag Email Example</h3>
<xml:transform fromXMLObjName="toxml1" href="style/email.xsl">
<xml:parsexml resource="style/emailWithDtd.xml" root="email"
toXMLObjName="toxml1">
</xml:parsexml>
</xml:transform>
4-371
email.xml
<email>
<recipient>Manager</recipient>
<copyto>jsp_dev</copyto>
<subject>XML Bug fixed</subject>
<bugno>BUG 1109876!</bugno>
<body>for reuse tag and checked in the latest version!</body>
<sender>Developer</sender>
</email>
email.dtd
<!ELEMENT email (recipient,copyto,subject,bugno,body,sender)>

<!ELEMENT recipient (#PCDATA)>
<!ELEMENT copyto (#PCDATA)>
<!ELEMENT subject (#PCDATA)>
<!ELEMENT bugno (#PCDATA)>
<!ELEMENT body (#PCDATA)>
<!ELEMENT sender (#PCDATA)>
emailWithDtd.xml
<!DOCTYPE email [
<!ELEMENT email (recipient,copyto,subject,bugno,body,sender)>
<!ELEMENT recipient (#PCDATA)>
<!ELEMENT copyto (#PCDATA)>
<!ELEMENT subject (#PCDATA)>
<!ELEMENT bugno (#PCDATA)>
<!ELEMENT body (#PCDATA)>
<!ELEMENT sender (#PCDATA)>]>
<email>
<recipient>Manager</recipient>
<copyto>jsp_dev</copyto>
<subject>XML Bug fixed</subject>
<bugno>BUG 1109876!</bugno>
<body>for reuse tag and checked in the latest version!</body>
<sender>Developer</sender>
</email>
email.xsl
4-372
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
<xsl:template match="email">
<html><body>
To: <xsl:value-of select="recipient"/>
CC: <xsl:value-of select="copyto"/>
Subject: <xsl:value-of select="subject"/> ...
<xsl:value-of select="body"/> !!
Thanks <xsl:value-of select="sender"/>
</body></html>
</xsl:template>
</xsl:stylesheet>
4-373
About Integration with XML and XSL
You can use JSP syntax to generate any text-based MIME type, not just HTML code. In
particular, you can dynamically create XML output. When you use JSP pages to generate an
XML document, however, you often want a stylesheet applied to the XML data before it is sent
to the client. This is difficult in JavaServer Pages technology, because the standard output
stream used for a JSP page is written directly back through the server.
OC4J provides special tags to specify that all or part of a JSP page should be transformed
through an XSL stylesheet before it is output. Input can be from the tag body or from an XML
DOM object, and output can be to an XML DOM object to the browser.
You can use these tags multiple times in a single JSP page if you want to specify different style
sheets for different portions of the page. Note that these tags are portable to other JSP
environments.
There is additional XML support as well:
● There is a utility tag to convert data from an input stream to an XML DOM object.
● There are several tags, for such features as caching and SQL operations, that now can
take XML objects as input or send them as output.
There is also information about Oracle-specific XML support in the Oracle9iAS Containers for
J2EE Support for JavaServer Pages Reference.
4-374
Reference: OC4J XML Tags
Library Syntax
<%@ taglib uri="xml.tld" prefix="XML" %>
Syntax usage:
OC4J XML Tag Library
Name Syntax
<XML:cacheXMLObj
[policy]
[ignoreCache]
[invalidateCache]
[scope]
[autoType]
[selectedParam]
[selectedCookies]
[reusableTimeStamp]
[reusableDeltaTime]
[name]
[expirationType]
cacheXMLObj - This tag in the Web Object
[TTL]
Cache is designed to cache XML objects.
[timeInaDay]
[dayInaWeek]
[dayInaMonth]
[writeThrough]
[printCachePolicy]
[fromXMLObjName]
[toXMLObjName]
[toWriter]
4-375
</XML:cacheXMLObj>
<XML:parsexml
[resource]
parsexml - Parse the specified resource or [toXMLObjName]
tag body as XML. [validateResource]
[root] > JSP content
</XML:parsexml>
<XML:styleSheet
href
styleSheet - Transform the body of the tag [fromXMLObjName]
using a stylesheet. [toXMLObjName]
[toWriter] > JSP content
</XML:styleSheet>
<XML:transform
href
transform - Transform the body of the tag [fromXMLObjName]
using a stylesheet. [toXMLObjName]
[toWriter] > JSP content
</XML:transform>
4-376
Working with XML Files
● Working with XML Files
❍ Using the XML Editor
❍ Importing and Registering XML Schemas
5-1
Working with XML Files
JDeveloper includes an XML Editor, which is a specialized schema-driven editor for editing
XML languages including UIX, UIT, XSQL, XSL, XHTML and WSDL files. You can add new
XML schemas by registering them using the XML Schemas panel.
● Using the XML Editor

● Importing and Registering XML Schemas
● Working with UIX XML Pages
● Working with UIX XML Templates
● Working with XSQL Servlets
● Creating an XSL Stylesheet for XSQL Files
5-2
Using the XML Editor
The XML Editor is a specialized schema-driven editor for editing XML languages including UIX,
UIT, XSQL, XSL, XSD, XHTML and WSDL files. The editor supports syntax highlighting,
Structure Window view, and the Property Inspector. If the XML language has an XML schema
associated with it, Tag (Code) Insight and End Tag Completion are also provided. You can add
new XML schemas by registering them using the XML Schemas panel reached by choosing
Tools | Preferences.
To use the XML Editor:
1. In the Navigator, right-click a file and choose XML Editor.

2. While you are typing, you can invoke tag insight by pausing after typing the < (opening
bracket) or by pressing Ctrl Space (if you are using the default keymapping). Tag Insight
opens a list with valid tags and attributes, based on the schema.
These features are also available while you are using the XML Editor:
● If End Tag Completion is checked in the XML Preferences panel (choose Tools |
Preferences | Editor | XML to display XML Preferences), the end tag will be automatically
inserted.
● If Required Attribute Insertion is checked in this panel, the required attributes of an
element will also be inserted for you. You can invoke it for attributes by entering a space
after selecting a tag. Invoke it repeatedly for additional attributes by entering additional
spaces.
● A file's elements and tags are displayed hierarchically in the Structure Window, which
also displays any XML syntax errors found as you type and edit. You can double click on
an element, attribute, or error to edit it in the XML Editor.
● The Property Inspector displays attributes of elements and tags in the file. You can edit
the values of attributes in the Property Inspector to update your file.
Tip: You can also right-click on the file in the Navigator and choose Check XML Syntax to
check the syntax and display the results in the XML Syntax tab of the message window.
Related topics
5-3
Importing and Registering XML Schemas
Previewing UIX XML Pages
5-4
You can use the XML Schemas page in the Preferences dialog to view all the currently
registered XML schemas, add new schemas to support additional namespaces and elements,
remove existing schemas, and unload schemas from memory. If an XML language has a XML
schema associated with it in this dialog, Tag Insight and validation are provided in the XML
Editor. To import and register a schema that is not included with JDeveloper, add it in this
dialog.
To import and register an XML schema:

3. Select the XML Schemas node.
4. Click Add to open the Add Schema dialog where you can specify a new schema to add
to the list of User Schemas.
5. Enter the name and location of the XML schema file you are adding in the Add a Schema
from the file system or a URL field.
6. Enter the file extension to register the schema for a specific file type in the Extension
field.
7. Check Validate Schema to have JDeveloper automatically validate the schema when you
add it.
8. Click OK.
9. Confirm that the new schema has been added to the list of User Schemas for XML
Editing and click OK.
Related topics
Creating a Simple UIX XML Page

5-5
Working with UIX XML and UIX JSP Pages
● About UIX
● About UIX XML and UIX JSP Similarities and Differences
❍ About Databinding in UIX XML Pages
❍ Creating a Simple UIX XML Page

❍ Generating UIX XML Pages
❍ Working with UIX XML Templates
❍ Generating a Databound UIX XML Form
❍ Generating a UIX XML Application Based on a BC4J Project
❍ Previewing UIX XML Pages
❍ Running UIX XML Pages
❍ Deploying UIX XML Web Modules
● Working with UIX JSP Pages

❍ About UIX JSP Page Structure
❍ About UIX JSP Tags

❍ About Databinding in UIX JSP Pages
❍ About BC4J Tags and UIX JSP Pages
❍ Creating a Simple UIX JSP Page
❍ Generating a Databound UIX JSP Form
❍ Generating a UIX JSP Application Based on a BC4J Project
❍ Editing JSP Pages with UIX JSP Tags
❍ Viewing JSP Pages Rendered from UIX JSP Tags
❍ Testing and Debugging a UIX JSP Page
❍ Deploying UIX JSP Web Modules
❍ UIX Tag Library Reference
❍ BC4J UIX Tag Library Reference
6-1
6-2
UIX XML and UIX JSP pages:
● Create a simple UIX XML page

● Work with a UIX XML template
● Use the XML editor
● Preview a UIX XML page
● Run a UIX XML page
● Create a simple UIX JSP page
● Edit JSP pages with UIX JSP tags
● View JSP pages rendered from UIX JSP tags
● Run JSP pages using JDeveloper's integrated JSP container
● Deploy a BC4J UIX application
Related topics
UIX Developer's Guide Table of Contents

UIX Developer's Guide Introduction
6-3
About UIX
Oracle User Interface XML (UIX) is a set of technologies that constitute a framework for
building Web applications. The main focus of the UIX technologies is the user presentation
layer of an application, with additional functionality provided for managing events and for
managing the state of the application flow. UIX is designed to create applications with page-
based navigation, such as an online human resources application, rather than full-featured
applications requiring advanced interaction, such as an integrated development environment
(IDE).
Please refer to the UIX Developer's Guide included in the JDeveloper Help for complete
information on UIX technologies:
● UIX Developer's Guide Table of Contents

● UIX Developer's Guide Introduction
Please refer to the following topics for information about using JDeveloper to build UIX XML
and UIX JSP pages:

Related topics
About UIX XML and UIX JSP Differences
6-4
About UIX XML and UIX JSP Similarities and
Differences
UIX XML provides a declarative way to build web applications where UIX controls can be
specified in an XML document and interpreted by a runtime UIX Servlet. The UIX HTML
controls are a collection of beans that implement the Oracle browser look and feel. These
beans generate the HTML to render tabs, buttons, tables, headers, and other layout and
navigational components. Working with UIX XML files in JDeveloper means that you can
declaratively define a web application with the UIX components in an XML file using the
schema-driven XML editor, and then test it and run it. JDeveloper provides wizards to help you
build individual UIX XML pages, and UIX template (UIT) files for quicker development, as well
as a BC4J UIX application wizard. Additionally, UIX XML supports data binding to any source,
not just a Business Components for Java project.
If you are interested in creating UIX XML applications, please see:
UIX JSP provides a tag library that invokes UIX controls via a set of tags from a JSP 1.1
compliant tag library. The JSP tags generate the HTML to render tabs, buttons, tables,
headers, and other layout and navigational components that implement the Oracle Browser
Look and Feel. Working with UIX JSP files in JDeveloper means that you can take advantage
of our JSP features such as the Component Palette, JSP Tag Insight, and the Data page
Wizard to create web applications, including applications based on a Business Components for
Java project, then test, debug and run them. JDeveloper provides wizards to generate
databound UIX JSP pages based on templates. The template pages include all the basic HTML
and UIX JSP layout and formatting tags for building Oracle browser look and feel applications
as well as JDeveloper's data tags that enable you to browse and edit data.
If you are interested in creating UIX JSP applications, please see:
As you can see, JDeveloper provides data page wizards, application wizards, data binding, tag
insight, and other editing features for both technologies.
Some of the key differences are:
● UIX XML exposes a larger set of functionality, as the UIX JSPs are a JSP interface to a
6-5
subset of the UIX UI Components. The JSP tags only implement a subset of the UIX
elements and a subset of the attributes.
● UIX JSP includes special UIX BC4J tags that make it easy to bind to a business
components project through the middle tier. Although both have mechanisms for
connecting to the middle tier, these mechanisms are slightly different.
● UIX XML provides additional databinding power that is not provided in UIX JSPs.
● UIX XML provides more powerful templating mechanisms. You can create your own
templates in JDeveloper and then build your application pages based on these
templates.
Related topics
UIX Basics: Data Binding

Business Components for Java Integration
6-6
Working with UIX XML Pages
UIX XML pages:
● Create a simple UIX XML page

● Work with a UIX XML template
● Generate a databound UIX XML form
● Generate a UIX XML application based on a BC4J project
● Use the XML editor
● Preview a UIX XML page
● Run a UIX XML page
Related topics
Generating UIX XML Pages

Deploying UIX XML Web Modules
Deploying a BC4J UIX Application
6-7
About Databinding in UIX XML Pages
You can make your UIX XML pages dynamic by using the UIX language's data binding
elements and the UIX Components BoundValue interface. The BC4J UIX application wizard
allows you to create a BC4J bound UIX application, generating pages for viewing, creating, and
updating each BC4J View selected.
Some of the more advanced features in the BC4J UIX technology integration are:
● UIX form element metadata is bound to BC4J metadata, such as "readOnly" bound to
inverse of "isUpdateable", "required" bound to "mandatory"
● Integration with UIX client-side validation mechanisms, such as "mandatory" form
elements getting a popup error window when not filled in
● BC4J server-side validation errors presented inline with the form element causing the
problem
● Repopulation of valid and invalid form values in page when any validation failure occurs
and page is redisplayed with errors
● "automatic" mode for region of form elements and table
● Implicit release of SessionCookie after web request has ended
● All BC4J usage information centralized in the "bc4j:registryDef" section of the UIX page
giving a single point of change for a developer
● 100% declarative definition of data binding to BC4J as well as updating BC4J data
sources
Please refer to the UIX Developer's Guide included in the JDeveloper Help and additional UIX
topics for complete information on databinding in UIX XML pages.
● UIX Basics: Data Binding

● Business Components for Java Integration
● Generating a Databound UIX XML Form
● Generating a UIX XML Application Based on a BC4J Project
Related topics
6-8
About UIX XML and UIX JSP Similarities and Differences
6-9
You can create a single UIX XML page with only the basic UIX page framework included for
data providers, page layout, and event handlers. After creating this file, you can add UIX
elements to build Oracle browser look and feel applications.
To create a UIX XML file:
1. In the Navigator, select the project you want to use for your UIX XML page.
2. Choose File | New to open the New dialog box.
3. Click the UIX XML folder in the Categories pane.
4. Double click the Empty UIX icon in the Items list.
Your project contains a basic UIX XML file named untitled#.uix. You can customize the file
using the schema-driven XML editor in which the file opens.
Tip: You can generate the page with the UIX page wizard instead of creating an empty page and
editing it, if you want to quickly create a UIX XML file with the following elements:
● Page title
● Corporate branding
● Product branding
● Navigation
● Privacy information
● Copyright information
Related topics

Generating a Databound UIX XML Form
Generating a UIX XML Application Based on a BC4J Project
Working with UIX XML templates
6-10
Running UIX XML Pages
6-11
You can generate a page with the UIX page wizard to quickly create a UIX XML file with the
following elements:
● Page title
● Navigation (first and second-level tabs and global buttons)
Tip: If you want to create a number of similar pages with these elements, first create a template with
the UIX Template wizard and then create all the pages based on your template.
To create a UIX XML file without using a template:
1. In the Navigator, select the project you want to use for your UIX application.
4. Double click the UIX with header, footer and navigation icon in the Items list.
The UIX Page Wizard appears. For detailed help about any of the steps, press F1 or
click Help from within the wizard.
5. Follow the steps on each wizard page, and click Next when you are done.
When you finish, your project contains a basic UIX XML file with the file name and elements
you specified. You can customize the file using the schema-driven XML editor in which the file
opens.
To create a UIX XML file using a UIT (template) file you previously created:
Note: When you use the UIX Template Customizer wizard, you must select a template that was
created with the UIX Template wizard, as JDeveloper looks for specific structure and content within
the UIT file.
6-12
4. Double click the UIX based on existing UIT page layout icon in the Items list.
The UIX Template Customizer wizard appears. For detailed help about any of the steps,
press F1 or click Help from within the wizard.
When you finish, your project contains a basic UIX XML file with the file name and elements
from the template on which it was based. You can customize the file using the schema-driven
XML editor in which the file opens. Repeat these steps to create additional pages based on the
template.
Related topics

6-13
Working with UIX XML Templates
If you want to create a number of similar UIX pages, you can first create a UIX Template (UIT) file
and then create all the UIX pages based on your template. You can create a UIT file by either
starting with an empty UIT file and adding individual UIX elements or generating a template with the
UIX Template wizard. If you use the wizard, your template contain the following elements:
● Page title
● Navigation (first and second-level tabs and global buttons)
Note: If you want to use a wizard to create UIX pages based on your template, you must create the
template with the UIX Template wizard; do not begin with the empty UIT file and create it manually.
To create an empty UIX template (UIT) file without using a wizard:
4. Double click the Empty UIT icon in the Items list.
Your project contains a UIX template (UIT) definition file named untitled#.uit. You can
customize the file using the schema-driven XML editor in which the file opens.
To create a UIX template (UIT) file using the UIX Template wizard:
4. Double click the Template (UIT) with header, footer and navigation icon in the Items list.
The UIX Template wizard appears. For detailed help about any of the steps, press F1 or
click Help from within the wizard.
6-14
When you finish, your project contains a UIT file upon which you can base all the UIX files in
your project. You can customize the UIT file using the schema-driven XML editor in which it
opens.
Related topics

6-15
You can generate a databound UIX XML page that includes all the basic HTML and UIX XML
layout and formatting tags for building Oracle browser look and feel applications and
JDeveloper's data tags that enable you to browse and edit data. The Data Page Wizard can
generate UIX XML forms for specific view objects of the application module you choose.
To create a databound UIX XML form:
1. In the Navigator, select the project you want to use for your UIX XML page.
3. Click the UIX XML folder in the Categories pane, then select BC4J Browse/Edit Pages
from the Items list and click OK.
The wizard creates forms to browse and edit records from a data source represented by
a view object.
4. Click Next on the Welcome page.

5. In the Business Application page, select a Business Components project, Application
Module and View Object and click Next.
wizard.
6. Click Finish in the Finish page.
The wizard creates UIX XML pages and other files that make up your application. You're ready
to run the UIX XML pages, or you can edit these pages in the XML Editor.
Related topics

6-16
6-17
Generating a UIX XML Application Based on a BC4J
Project
The Business Components UIX Application Wizard can create a BC4J bound UIX application,
generating pages for viewing, creating, and updating each BC4J view object selected
Note: Before you can generate a UIX XML application, you must have an application module and a
configuration that specifies its usage. If you don't have a Business Components project that contains
an application module, follow the tutorial on building business components to create a new project
containing an application module.
To create a UIX XML application project:
You should create a separate project for your UIX XML application just as you did for your
application module. It's a good idea to keep the files for different tiers in separate projects. This
new project must be in the same workspace as the application module's project in order for the
Business Components UIX XML Application Wizard to find your application module.
1. In the Navigator, select the workspace you want to use for your UIX XML application.
3. Click the Projects folder in the Categories pane.
4. Double click the Empty Project icon in the Items list. The New Project dialog appears.
For detailed help in the New Project dialog, press F1 or click Help from within the dialog.
5. Enter the directory name and file name and click OK.
When you finish, the Project Wizard creates the new project in your workspace.
To create the UIX XML business components application in an existing project:
1. In the Navigator, select the project you created for your UIX XML application.
6-18
4. Double click the Business Components UIX XML Application icon in the Items list. The
Business Components Application Wizard appears.
5. In the Welcome page, click Next.
wizard.
6. Name your Web application. JDeveloper uses this name for the UIX XML application's
property file.
7. Specify the document root directory of your web server and a directory within it to contain
your UIX XML application files. JDeveloper places these files within the specified
directory, so the directory must be accessible to JDeveloper. Accept the default
document root directory to use JDeveloper's built-in web server. Also enter the War
name file and a description. Click Next.
8. Select the application module you want your UIX XML application to use and provide
9. Choose the configuration that your want your UIX XML application to use to connect to
the deployed application module. You can view configuration parameters by right-clicking
the application module in the Business Components project and choosing
Configurations. Click Next.
10. By default, the wizard will generate UIX XML pages for every view object that the
application module defines. From the displayed list of view objects, select the ones you
do not want your application to use and unselect Generate page.
11. By default, the wizard will generate all the links for the view objects you leave selected.
For each view link, specify which forms you do not want generated by unselecting the
checkbox for the form. Click Next.
12. Click Finish.
● The new UIX XML pages

6-19
● The UIX XML application properties (web.xml) file
● Other files that make up your UIX XML application
You're ready to run the UIX XML pages, or you can edit these pages in the XML Editor.
Related topics

6-20
The UIX Preview window provides a read-only view of a UIX file as it will appear in a browser.
To preview a UIX XML file:
1. In the Navigator, right-click the UIX file and select UIX Preview.
As you edit your UIX file, JDeveloper updates the UIX Preview window for you in real
time, so you can see how your changes and additions will appear. You cannot test your
links in this viewer, as all links are disabled.
Tip: Right-click the UIX file and select Run to run the file and test your links in the browser.
You cannot directly modify the UIX source file in the UIX Preview window. To modify the UIX
source, edit the file in the XML Editor.
Related topics

6-21
After you have added elements to your UIX file, you should build or make the file, and then run
it.
To run a UIX file:
1. Select the UIX file in the Navigator and choose Project | Build (filename) to compile the
file.
JDeveloper will compile the UIX file, find any errors, and display the results in the
Message window.
2. If the UIX file compiles successfully, right-click the file and select Run.
JDeveloper starts its built-in OC4J webserver, launches your default web browser, and displays
the output of the file in the browser.
Related topics

6-22
Deploying UIX XML Web Modules
Deploying your UIX XML applications, or any other J2EE applications in Oracle9iAS with
JDeveloper is a completely automated process:
● Deploying a BC4J UIX Application

● About Deploying on Oracle9i Application Server
● About the Deployment Process
● About J2EE Applications and How They Are Packaged and Deployed
● About Business Components for Java (BC4J) Deployment
● Creating and Deploying a J2EE Web Module Deployment Profile (WAR)
Related topics

6-23
Working with UIX JSP Pages
UIX JSP pages:
● Create a simple UIX JSP page

● Generate a databound UIX JSP form
● Generate a UIX JSP application based on a BC4J project
● Edit JSP pages with UIX JSP tags
● Insert JSP tags using Code Insight
● View JSP pages rendered from UIX JSP tags
● Run JSP pages using JDeveloper's integrated JSP container
● Deploy a BC4J UIX application
Related topics
UIX JSP Tag Reference

BC4J UIX JSP Tag Reference
6-24
About UIX JSP Page Structure
compliant tag library. The UIX JSP tags are a JSP interface to a subset of the UIX UI
Components. To simplify page and application development with UIX JSP tags, you can use
one of the wizards included in the UIX JSP category of the New Gallery. These will help you
generate pages that browse and edit data using UIX JSP tags.
information on page structure in UIX. It describes what a page means to the UIX technologies,
as well as how to create pages and ultimately transform them into user interfaces for your
target audience.
● UIX Basics: Creating Pages in UIX
Related topics
About UIX JSP Tags

UIX Developer's Guide Introduction
Editing JSP Pages with UIX JSP Tags
Viewing JSP Pages Rendered from UIX JSP Tags
6-25
About UIX JSP Tags
compliant tag library. The JSP tags generate the HTML to render tabs, buttons, tables,
headers, and other layout and navigational components that implement the Oracle browser
look and feel.
The tags are included on several palette pages: UIX Page, UIX Layout, UIX Table, UIX Form,
UIX Border Layout, and BC4J UIX. These support page layout, table layout, form layout, border
layout, and databinding to a business components project.
Some UIX JSP tags are highly contextual, which means you cannot insert the tag anywhere in
a page to achieve the desired results. Contextual tags must be inside a specific container like a
table or a form. This is specified in the individual tag reference topics.
To simplify application development with UIX JSP tags, you can use one of the wizards
included in the UIX JSP category of the New Gallery. These will help you generate pages that
browse and edit data using UIX JSP tags.
Related topics
About UIX JSP Page Structure

Running a JSP
Debugging a JSP
6-26
About Databinding in UIX JSP Pages
Databinding in UIX JSP Pages is supported for Business Components projects through BC4J
data tags and specialized BC4J UIX convenience tags that simplify the presentation of data.
UIX JSP pages rely on a default BC4J name space that gets the datasource from the BC4J
application module/datasource definition. BC4J UIX tags are populated by the rowset and
attribute value from the data object list returned by the BC4J dataprovider instance. This is
defined when you insert an ApplicationModule data tag from the component palette into your
UIX JSP page, run the Business Components Application wizard, or run one of the UIX JSP
form wizards.
● Specifying an Application Module for JSP Pages

● Working with BC4J Databound JSP Pages
● About BC4J Tags and UIX JSP Pages
● Generating a Databound UIX JSP Form
● Generating a UIX JSP Application Based on a BC4J Project
information on Databinding with UIX.
● UIX Basics: Data Binding

● Business Components for Java Integration
Related topics

6-27
About BC4J Tags and UIX JSP Pages
UIX JSP pages can include both BC4J data tags and BC4J UIX convenience tags that simplify
the presentation of data.
The BC4J UIX convenience tags rely on an ApplicationModule data tag to get the datasource
from the BC4J application module. In addition to the BC4J UIX tags listed below, you can use
the (non-UIX) BC4J tags in your UIX JSP pages.
● <bc4juix:table>
● <bc4juix:tableDetail>
● <bc4juix:addTableRow>
● <bc4juix:navigationBar>
● <bc4juix:styledText>
● <bc4juix:labelStyledText>
● <bc4juix:renderValue>
Related topics
About Databinding in UIX JSP Pages

Working with BC4J Databound JSP Pages
6-28
Creating a Simple UIX JSP Page
With JDeveloper, you can easily develop and execute an individual UIX JSP page that includes
all the basic HTML and UIX JSP layout and formatting tags for building Oracle browser look
and feel applications.
To create a UIX JSP file:
1. In the Navigator, select the project you want to use for your UIX JSP page.
3. Click the UIX JSP folder in the Categories pane.
4. Double click the Starter Form icon in the Items list.
When you finish, your project contains a basic UIX JSP file named uixpage#.jsp. You can
customize the file using the Code Editor.
Related topics

6-29
Generating a Databound UIX JSP Form
You can generate a databound UIX JSP page that includes all the basic HTML and UIX JSP
layout and formatting tags for building Oracle browser look and feel applications and
JDeveloper's data tags that enable you to browse and edit data. The Data Page Wizard can
generate UIX JSP forms for specific view objects of the application module you choose.
To create a databound UIX JSP form:
1. In the Navigator, select the project you want to use for your UIX JSP page.
3. Click the UIX JSP folder in the Categories pane, then select either Browse Edit Form or
Browse Form (with Hide/Show) from the Items list and click OK.
Both items launch a wizard that creates forms to browse and edit records from a data
source represented by a view object. Choose Browse Form (with Hide/Show) if you want
to create a form that provides a means of toggling a group of UINodes between being
displayed or hidden. Choose Browse Edit Form to create a form without the hide/show
functionality.

5. In the Business Application page, select a Business Components project, Application
Module and View Object and click Next.
wizard.
6. Click Finish in the Finish page.
The wizard creates three UIX JSP pages named UixBrowseEdit.jsp (or
UixBrowseHideShow.jsp), UixEdit.jsp, and UixHelp.jsp, along with additional JSP and project
pages. You're ready to run the UIX JSP pages, or you can edit these pages in the Code Editor.
Related topics
Generate a UIX JSP Application Based on a BC4J Project
6-30
Generating a JSP Application Based on BC4J Page Templates
About Configurations Properties for a JSP Project
6-31
Generating a UIX JSP Application Based on a BC4J
Project
The Business Components JSP Application Wizard can generate a set of UIX JSP forms for
each of the application module's view objects. You choose which JSP forms (if any) to generate
for each view object. These forms use JDeveloper's Component Tags from the Business
Components for Java tag library and UIX JSP tags for building Oracle browser look and feel
applications.
Note: Before you can generate a UIX JSP application, you must have an application module and a
configuration that specifies its usage. If you don't have a Business Components project that contains
an application module, follow the tutorial on building business components to create a new project
containing an application module.
To create a UIX JSP application project:
You should create a separate project for your UIX JSP application just as you did for your
application module. It's a good idea to keep the files for different tiers in separate projects. This
new project must be in the same workspace as the application module's project in order for the
Business Components UIX JSP Application Wizard to find your application module.
1. In the Navigator, select the workspace you want to use for your UIX JSP application.
3. Click the Projects folder in the Categories pane.
4. Double click the Empty Project icon in the Items list. The New Project dialog appears.
For detailed help in the New Project dialog, press F1 or click Help from within the dialog.
5. Enter the directory name and file name and click OK.
When you finish, the new project is added to your workspace.
To create the UIX JSP business components application in an existing project:
1. In the Navigator, select the project you created for your UIX JSP application.
6-32
3. Click the UIX JSP folder in the Categories pane.
4. Double click the Business Components JSP Application icon in the Items list. The
Business Components JSP Application Wizard appears.
5. In the Welcome page, click Next.
wizard.
6. Name your JSP application. JDeveloper uses this name for the JSP application's
property file.
7. Specify the document root directory of your web server and a directory within it to contain
your JSP application files. JDeveloper places these files within the specified directory, so
the directory must be accessible to JDeveloper. Accept the default document root
directory to use JDeveloper's built-in web server. Also enter the War name file and a
description. Click Next.
8. Select the application module you want your JSP application to use and provide
9. Choose the configuration that your want your JSP application to use to connect to the
deployed application module. You can view configuration parameters by right-clicking the
application module in the Business Components project and choosing Configurations.
Click Next.
10. By default, the wizard will generate JSP forms for every view object that the application
module defines. From the displayed list of view objects, select the ones you do not want
your JSP application to use and unselect Generate page.
11. By default, the wizard will generate all the JSP forms for the view links you leave
selected. For each view link, specify which JSP forms you do not want generated by
unselecting the checkbox for the form. Click Next.
12. Click Finish.
6-33
● The new UIX JSP pages
● The UIX JSP application properties (web.xml) file
● Other files that make up your UIX JSP application
You're ready to run the UIX JSP pages, or you can edit these pages in the Code Editor.
Related topics
Generating a JSP Application Based on BC4J Page Templates

6-34
As with all JSP pages, you can edit JSP pages with UIX JSP tags in the Code Editor, which
supports syntax highlighting, Structure pane view, and the Property Inspector. You can also
select tags from the Component Palette to insert in your pages while you are editing.
To edit JSP pages with UIX JSP tags:
1. In the Navigator, right-click a file and choose Code Editor.

2. Choose View | Component Palette to open the Component Palette and select one of the
UIX tags pages from the drop-down list in the Component Palette. You can select UIX
JSP tags from the palette.
3. While you are typing, you can invoke tag insight by pausing after typing the < (opening
bracket) or by pressing Ctrl Space (if you are using the default keymapping). Tag Insight
opens a list with valid tags and attributes.
These features are also available while you are using the Code Editor to edit JSP pages with
UIX JSP tags:
● If End Tag Completion is checked in the HTML and JSP Preferences panel (choose
Tools | Preferences | Editor | HTML and JSP to open the Preferences panel), the end tag
will be automatically inserted.
also displays any JSP or HTML syntax errors found as you type and edit. You can
double click on an element, attribute, or error to edit it in the Code Editor.
Related topics

6-35
After creating a JSP file and adding UIX JSP tags, you can view the rendered page by running
the file.
To view a JSP page rendered from UIX JSP tags:
1. Select the JSP file in the Navigator, right-click and choose Run to display the file in your
web browser.
JDeveloper starts its built-in OC4J webserver, launches your default web browser, and
displays the page in the browser.
Related topics

Running a JSP
Debugging a JSP
6-36
Testing and Debugging a UIX JSP Page
Testing and debugging UIX JSP pages in JDeveloper is similar to testing and debugging any
other type of application:
● Running a JSP
● Debugging a JSP
Related topics

Deploying a BC4J Web Application to Oracle9iAS
6-37
Deploying UIX JSP Web Modules
Deploying your UIX JSP applications, or any other J2EE applications in Oracle9iAS with
JDeveloper is a completely automated process:

Related topics

Running a JSP
Debugging a JSP
6-38
UIX JSP Tag Library Reference
Library Syntax
<%@ taglib uri="http://xmlns.oracle.com/uix/ui" prefix="uix" %>
Syntax usage:
Tag Groupings
UIX Border Layout

UIX Form
UIX Layout
UIX Page
UIX Table
UIX Validation
UIX Border Layout

Name Syntax
borderLayout - Lays out all of its indexed <uix:borderLayout> JSP
children consecutively in its middle, and </uix:borderLayout>
supports twelve other named children.
bottom - Specifies the border to be rendered
below the indexed children and any <uix:bottom> JSP </uix:bottom>
innerBottom child.
innerBottom - Specifies the border to be <uix:innerBottom> JSP
rendered below the indexed children and above </uix:innerBottom>
any bottom child.
innerEnd - Specifies the border to be rendered
<uix:innerEnd> JSP </uix:innerEnd>
to the right of the indexed children.
innerLeft - Specifies the border to be rendered
to the left of the indexed children and to the <uix:innerLeft> JSP </uix:innerLeft>
right of any left child.
innerRight - Specifies the border to be <uix:innerRight> JSP
rendered to the right of the indexed children </uix:innerRight>
and to the left of any right child.
6-39
innerStart - Specifies the border to be <uix:innerStart> JSP
rendered to the left of the indexed children and </uix:innerStart>
to the right of any left-appearing child.
innerTop - Specifies the border to be rendered
above the indexed children and below any top <uix:innerTop> JSP </uix:innerTop>
child.
left - Specifies the border to be rendered below
the indexed children and above any bottom <uix:left> JSP </uix:left>
child.
right - Specifies the border to be rendered to
<uix:right> JSP </uix:right>
the right of the indexed children.
top - Specifies the border to be rendered
above the indexed children and any innerTop <uix:top> JSP </uix:top>
child.
UIX Form
Name Syntax
<uix:checkBox
[text]
value
[checked]
name
checkBox - Creates a standard browser input
[disabled]
check box field in a form.
[readOnly]
[onFocus]
[onBlur]
[accessKey]
[selectedValue] />
<uix:choice
name
[required]
[disabled]
choice - Displays a menu-style list of items [readOnly]
from which the user can select. [onFocus]
[onBlur]
[selectedIndex]
[selectedValue] > JSP content
</uix:choice>
6-40
<uix:dateField
name
[text]
[maximumLength]
[required]
dateField - Creates a text field for entering [columns]
dates and a button for selecting dates from a [disabled]
calendar. [readOnly]
[onFocus]
[onBlur]
[onChange]
[onSelect] > JSP content
</uix:dateField>
fileUpload - Adds a widget for uploading a file, <uix:fileUpload
and requires that the form use multi-part as name
the mime type. [columns] />
<uix:form
name
[destination]
[usesUpload]
form - Creates an HTML form inside the page.
[method]
[onSubmit]
[targetFrame] > JSP content
</uix:form>
<uix:formValue
formValue - Adds a value that will be name
submitted with a form, but not displayed. [value]
[valueBinding] />
<uix:list
name
[multiple]
[size]
[disabled]
list - Displays a defined list of items from
[readOnly]
which the user can select.
[onFocus]
[onBlur]
[selectedIndex]
[selectedValue] > JSP content
</uix:list>
6-41
<uix:lovField
name
[text]
[maximumLength]
[required]
[rows]
[columns]
lovField - Creates a text field with an [wrap]
associated button for launching a List of [secret]
Values (LOV) dialog. [disabled]
[readOnly]
[onFocus]
[onBlur]
[onChange]
[onSelect]
[destination] > JSP content
</uix:lovField>
<uix:option
option - Creates a single option input field that text
the user may select from a set of options. value
[selected] />
<uix:radioButton
name
[text]
[selected]
[value]
radioButton - Inserts a standard browser
[disabled]
radio button input field.
[readOnly]
[onFocus]
[onBlur]
[accessKey] > JSP content
</uix:radioButton>
6-42
<uix:radioGroup
[id]
name
[onChange]
[required]
[selectedIndex]
radioGroup - Creates a set of radio buttons,
[selectedValue]
laid out vertically.
[type]
[disabled]
[readOnly]
[onFocus]
[onBlur] > JSP content
</uix:radioGroup>
<uix:resetButton
resetButton - Creates a push button that
[text]
resets the content of a form.
[formName] />
<uix:submitButton
[name]
submitButton - Creates a push button that [text]
allows submission of a form. [formName]
[value]
[unvalidated] />
<uix:textInput
name
[text]
[maximumLength]
[required]
[rows]
[columns]
textInput - Creates either a single-line text [wrap]
field or multi-line text area. [secret]
[disabled]
[readOnly]
[onFocus]
[onBlur]
[onChange]
[onSelect] > JSP content
</uix:textInput>
UIX Layout
Name Syntax
6-43
flowLayout - Lays out each of its children <uix:flowLayout> JSP
horizontally, wrapping as needed. </uix:flowLayout>
stackLayout - Lays out each of its children <uix:stackLayout> JSP
vertically, wrapping as needed. </uix:stackLayout>
UIX Page
Name Syntax
<uix:body
body - Creates the container for the body to be [onLoad]
used inside of Document tag. [onUnload] > JSP content
</uix:body>
<uix:breadCrumbs
breadCrumbs - Inserts a trail of links back to the
[orientation] > JSP content
site home page. </uix:breadCrumbs>
<uix:buildTree
buildTree - Builds a UIX tree and saves it to the
nodeID > JSP content
page context so it can be re-used. </uix:buildTree>
<uix:button
[name]
[destination]
text
[selected]
button - Insert a button to trigger some action in
[accessKey]
response to a click.
[disabled]
[longDesc]
[onBlur]
[targetFrame]
[onFocus] />
<uix:case
case - Defines one of the possible rendered
name > JSP content
children for the Switcher tag. </uix:case>
cobranding - Creates the cobranding section of <uix:cobranding> JSP
the page layout that typically contains a logo of a </uix:cobranding>
non-owning company.
<uix:contentContainer
[width]
contentContainer - Places ancillary information [text]
on a page, offset by color. [icon]
[background] > JSP content
</uix:contentContainer>
6-44
<uix:contentFooter
contentFooter - Creates a horizontal separator
[width] > JSP content
with a curved right corner. </uix:contentFooter>
contents - Inserts a container for indexed
<uix:contents> JSP </uix:contents>
children inside a pageLayout tag.
copyright - Creates the copyright section of a <uix:copyright> JSP
page layout. </uix:copyright>
corporateBranding - Creates the corporate <uix:corporateBranding> JSP
branding section of the page layout. </uix:corporateBranding>
<uix:dataScope
dataScope - Registers UIX Component
id > JSP content
DataProviders for a UINode subtree. </uix:dataScope>
document - Generates the root tags for a page. <uix:document> JSP </uix:document>
end - Specifies the end named child container in
a page layout or the border to be rendered to the <uix:end> JSP </uix:end>
right of the indexed children in a border layout.
footer - Inserts footer links at the bottom of
<uix:footer> JSP </uix:footer>
pages.
<uix:globalButton
text
destination
[icon]
[selected]
[source]
globalButton - Inserts a button to provide
[accessKey]
access to globally available functionality.
[disabled]
[longDesc]
[name]
[onBlur]
[targetFrame]
[onFocus] />
globalButtonBar - Displays a set of global <uix:globalButtonBar> JSP
buttons inserted with the globalButton tag. </uix:globalButtonBar>
globalButtons - Wraps the global buttons <uix:globalButtons> JSP
section of the page layout. </uix:globalButtons>
<uix:globalHeader
globalHeader - Adds a blue banner under the
[text]
tabs that optionally can contain a series of links
[selectedIndex] > JSP content
for site navigation.
</uix:globalHeader>
6-45
<uix:header
[shortText]
header - Places a label and icon at the top of a [text]
section, and indents the contents. [icon]
[size] > JSP content
</uix:header>
<uix:image
source
[destination]
[borderWidth]
image - Inserts a specified image in the page. [hAlign]
[height]
[longDescURL]
[width]
[accessKey] />
<uix:inlineMessage
[longDescURL]
[message]
[messageType]
[prompt]
inlineMessage - Inserts a component that wraps
[required]
another, adding a label, and optionally an icon
[targetFrame]
with a message.
[tip]
[vAlign]
[anchor]
[accessKey] > JSP content
</uix:inlineMessage>
<uix:labeledFieldLayout
[columns]
labeledFieldLayout - Lays out its indexed
[fieldWidth]
children in a series of columns, displaying one
[labelWidth]
set for the labels and the other set for the fields.
</uix:labeledFieldLayout>
largeAdvertisement - Creates the large <uix:largeAdvertisement> JSP
advertisement section of the page layout. </uix:largeAdvertisement>
leading - Creates the leading list of the shuttle. <uix:leading> JSP </uix:leading>
leadingFooter - Creates the footer of buttons <uix:leadingFooter> JSP
and images under the leading list in a shuttle. </uix:leadingFooter>
6-46
<uix:link
[text]
[destination]
[selected]
[accessKey]
[disabled]
link - Inserts a text link to a target.
[longDesc]
[name]
[onBlur]
[targetFrame]
[onFocus] > JSP content
</uix:link>
location - Creates the location section of the
page layout that typically contains either a Train <uix:location> JSP </uix:location>
or BreadCrumbs.
mediumAdvertisement - Creates the medium <uix:mediumAdvertisement> JSP
advertisement section of the page layout. </uix:mediumAdvertisement>
<uix:messageBox
[message]
[messageType]
messageBox - Inserts important messaging [text]
information at the top of a page. [automatic]
[dataName]
[dataNamespace] > JSP content
</uix:messageBox>
<uix:messagePrompt
messagePrompt - Displays the prompt portion [messageType]
of an inline message. [prompt]
[required] />
<uix:messageStyledText
[anchor]
[longDescURL]
[message]
[messageType]
messageStyledText - Combines the styledText
[prompt]
and inlineMessage tags.
[required]
[targetFrame]
[tip]
[vAlign] > JSP content
</uix:messageStyledText>
6-47
<uix:navigationBar
[blockSize]
[destination]
navigationBar - Displays the current position [maxValue]
among a larger set of steps or records and [minValue]
provides links to additional steps and records. [name]
[value]
[formSubmitted]
[formName] />
pageButtonBar - Displays a set of buttons <uix:pageButtonBar> JSP
inserted with the Button tag. </uix:pageButtonBar>
pageHeader - Inserts a container at the top of a <uix:pageHeader> JSP
page in a page layout that typically contains a </uix:pageHeader>
GlobalHeader.
<uix:pageLayout
pageLayout - Applies a template to the entire [title]
page, wrapping all page elements. [quickLinksShown] > JSP
content </uix:pageLayout>
privacy - Creates the privacy section of the page
<uix:privacy> JSP </uix:privacy>
layout.
productBranding - Creates the product <uix:productBranding> JSP
branding section of the page layout that typically </uix:productBranding>
contains the product logo.
quickSearch - Creates the quick search section <uix:quickSearch> JSP
of the page layout. </uix:quickSearch>
<uix:rawText
[text]
rawText - Supports outputting of unescaped text
[preText]
generated in HTML in a UIX hierarchy.
[postText] > JSP content
</uix:rawText>
<uix:ref
ref - Re-uses a UIX tree saved by the buildTree
refID > JSP content
tag. </uix:ref>
<uix:renderingContext
renderingContext - Introduces the UIX
id > JSP content
Rendering context. </uix:renderingContext>
separator - Inserts a line that acts as a
<uix:separator/>
horizontal separator anywhere within the page.
6-48
<uix:shuttle
shuttle - Provides a mechanism for moving items name
between two lists and reordering one of these [reorderable]
lists. [size] > JSP content
</uix:shuttle>
sideNav - Creates a series of linked items down <uix:sideNav
the left side of the page, each defined by a link [selectedIndex] > JSP content
node. </uix:sideNav>
<uix:spacer
spacer - Inserts a fixed amount of space in an [width]
HTML layout. [height] > JSP content
</uix:spacer>
start - Specifies the start named child container
in a page layout or the border to be rendered <uix:start> JSP </uix:start>
above the indexed children in a border layout.
styleSheet - Inserts a CSS stylesheet into page. <uix:styleSheet/>
<uix:styledText
[text]
[styleClass]
styledText - Applies a style class to text or a text
[textBinding]
link.
[accessKey]
[destination] > JSP content
</uix:styledText>
<uix:switcher
switcher - Used to switch between one of a set
childName > JSP content
of items. </uix:switcher>
<uix:tabBar
tabBar - Creates a series of tabbed items, each
defined by a link node. </uix:tabBar>
tabs - Specifies the tabs region of the page that
<uix:tabs> JSP </uix:tabs>
typically contains a TabBar.
<uix:tip
tip - Inserts a graphical and textual component
[text] > JSP content
that highlights text intended as a hint to the user. </uix:tip>
trailing - Creates the trailing list of the shuttle. <uix:trailing> JSP </uix:trailing>
trailingFooter - Creates the footer of buttons <uix:trailingFooter> JSP
and images under the trailing list in a shuttle. </uix:trailingFooter>
<uix:train
train - Inserts a visual indicator on the page that
shows where a user is in a multi-step process. </uix:train>
UIX Table
6-49
Name Syntax
<uix:addTableRow
addTableRow - Causes a special TableRow to [text]
be rendered that lets users click a button to add [rows]
one or more rows of data. [destination] > JSP content
</uix:addTableRow>
<uix:cellFormat
[hAlign]
[height]
cellFormat - Adds formatting, such as vertical [rowSpan]
alignment, width, or colspan, to cells in a [columnSpan]
rowLayout tag. [vAlign]
[width]
[wrappingDisabled] > JSP
content </uix:cellFormat>
column - Supports encapsulating all of the <uix:column
rendering and formatting information for a table id > JSP content
column into a single tag. </uix:column>
columnFooter - Renders the table footer inside <uix:columnFooter> JSP
of a Table tag. </uix:columnFooter>
columnHeader - Used to render the column <uix:columnHeader> JSP
header inside of a table column. </uix:columnHeader>
columnHeaderStamp - Renders each column <uix:columnHeaderStamp> JSP
header inside a table. </uix:columnHeaderStamp>
<uix:hideShow
id
[destination]
[disclosed]
hideShow - Toggles a page section between
[disclosedText]
being disclosed or undisclosed.
[formName]
[undisclosedText]
[formSubmitted] > JSP content
</uix:hideShow>
<uix:multipleSelection
multipleSelection - Causes a table to render [text]
both a selection column for multiple selection of [disabled]
rows and a control bar surrounding the table
[selected] > JSP content
contents.
</uix:multipleSelection>
6-50
<uix:rowLayout
[hAlign]
rowLayout - Defines a row within a tableLayout
[vAlign]
tag or on its own.
</uix:rowLayout>
<uix:singleSelection
singleSelection - Causes a table to render both [text]
a selection column and a control bar surrounding [disabled]
the table contents. [selectedIndex] > JSP content
</uix:singleSelection>
<uix:sortableHeader
[anchor]
[value]
[longDescURL]
sortableHeader - Stamps column headers that
[messageType]
allow sorting in a table.
[required]
[targetFrame]
[vAlign] > JSP content
</uix:sortableHeader>
<uix:table
id
[alternateText]
[blockSize]
[destination]
[formSubmitted]
[height]
[width]
table - Supports the editing, display, and [maxValue]
formatting of tabular data in a table. [minValue]
[name]
[nameTransformed]
[proxied]
[summary]
[tableDataBinding]
[text]
</uix:table>
tableDetail - Used to stamp below every table <uix:tableDetail> JSP
row that is disclosed. </uix:tableDetail>
6-51
<uix:tableLayout
[borderWidth]
[cellPadding]
tableLayout - Contains a series of row layout
[cellSpacing]
elements.
[hAlign]
</uix:tableLayout>
<uix:tableSelection> JSP
tableSelection - Turns on selection in the table.
</uix:tableSelection>
<uix:totalRow
totalRow - Inserts a special table row and button [destination]
that lets users see the updated totals of the data [readOnly]
in one or more columns. [text] > JSP content
</uix:totalRow>
UIX Validation
Name Syntax
<uix:date
date - Adds a date validator as a child of [pattern]
onSubmit or onBlur tags. [dateStyle]
[timeStyle] />
decimal - Adds a decimal validator as a child of
<uix:decimal/>
onSubmit or onBlur
onBlurValidater - Inserts a parent tag for client- <uix:onBlurValidater> JSP
side field validaters. This tag should be a child </uix:onBlurValidater>
tag of TextInput, DataField or LOVField
onSubmitValidater - Inserts a parent tag for <uix:onSubmitValidater> JSP
client-side form validators. This tag should be a </uix:onSubmitValidater>
child tag of TextInput, DataField or LOVField
regExp - Adds a regular expression validator as <uix:regExp
a child of onSubmit or onBlur tags. pattern />
wml - Defines a client validater using WML <uix:wml
patterns, which is the only pattern capable of pattern />
validating on both HTML and WML.
6-52
BC4J UIX JSP Tag Library Reference
Library Syntax
<%@ taglib uri="http://xmlns.oracle.com/uix/ui/bc4j" prefix="bc4juix"

%>
Syntax usage:
Tag Groupings
BC4J UIX
BC4J UIX
Name Syntax
<bc4juix:AddTableRow
AddTableRow - Renders a special TableRow [text]
which lets users add rows of data to the [rows]
datasource. [destination] > JSP content
</bc4juix:AddTableRow>
<bc4juix:InputRender
InputRender - Renders an Input field from a
datasource
datasource to a page.
[dataitem] />
<bc4juix:LabelStyledText
[datasource]
LabelStyledText - Binds styled text labels to [dataitem]
the datasource automatically. [styleClass]
[destination]
[labeledNodeId] />
NavigationBar - Binds the navigation bar to <bc4juix:NavigationBar
the datasource automatically. [datasource] />
RenderValue - Displays data of special data <bc4juix:RenderValue
types, such as images, audio, or video, using a datasource
field render specific to the data object type. dataitem />
6-53
<bc4juix:StyledText
[datasource]
[dataitem]
StyledText - Binds styled text to the
[styleClass]
datasource automatically.
[accessKey]
[destination]
[labeledNodeId] />
<bc4juix:Table
datasource
[alternateText]
[destination]
[formSubmitted]
[height]
Table - Binds a table to the datasource [width]
automatically. [name]
[nameTransformed]
[proxied]
[summary]
[text]
</bc4juix:Table>
TableDetail - Causes the detail column from <bc4juix:TableDetail> JSP
the datasource to be displayed. </bc4juix:TableDetail>
6-54
Working with XSQL Servlets
● About XSQL Servlet Clients

● Creating an XSQL File
● Adding XSQL Tags
● Creating XSQL Servlet Clients that Access the Database
● Creating XSQL Servlet Clients for Business Components
● Running XSQL Servlet Clients
● Viewing Output from Running XSQL Files as Raw XML Data
● Formatting XML Data with a Stylesheet
● Modifying the XSQL Configuration File
● Creating a Custom Action Handler for XSQL
● Using XML Metadata Properties in XSQL Files
● XSQL Tag Reference
7-1
XSQL Servlet applications.
● About XSQL Servlet Clients

● Creating an XSQL File
● Adding XSQL Tags
● Creating XSQL Servlet Clients that Access the Database
● Creating XSQL Servlet Clients for Business Components
● Running XSQL Servlet Clients
● Viewing Output from Running XSQL Files as Raw XML Data
● Formatting XML Data with a Stylesheet
● Modifying the XSQL Configuration File
● Creating an Action Handler for XSQL
● Using XML Metadata Properties in XSQL Files
● Reference: XSQL Tags
Related topics
7-2
About XSQL Servlet Clients
JDeveloper provides support for XSQL Servlet with these features:
● Provides XSQL tags on the Component Palette

● Lets you automatically create XSQL pages
● Includes XSQL Libraries
● Provides XSQLConfig.xml on the classpath; you can modify it as needed
● Provides business component action handler tags so XSQL pages can use a business
logic tier to access data
What is XSQL Servlet?
It is a servlet that lets you create and use XSQL pages as clients. These pages are written in
XML with embedded SQL queries and other data manipulation language (DML) statements. In
addition, you can use action handlers to provide more functionality than SQL, such as writing
the XML data to a file.
An action handler is an application that allows you to call a Java class from within an XSQL
page. There are predefined action handlers that can talk directly to the database or to Business
Components for Java, and you can create your own.
An XSQL Servlet application has these logical layers:
● Client - XSQL pages take care of querying and getting data by using XML with
embedded SQL. To present the data, you need to convert the XML data to another form,
such as HTML, wireless markup language (WML), and so on. You can write XSL
stylesheets to convert XML to any of these languages.
● XSQL Servlet in a Web Server - The servlet uses the XML SQL Utility to talk to a
database.
● Business Logic Tier - You can optionally use a Business Components for Java tier to
access and modify data.
● Database - You can use any database supporting JDBC 2.0 drivers.
How Can You Use XSQL Servlet?
7-3
XSQL servlets offer a simple and productive way to get XML in and out of the database. Using
simple scripts developers can:
● Generate simple or complex XML documents

● Apply XSL Stylesheets to generate any text format
● Parse XML documents and store the data in the database
● Create complete dynamic web applications without programming a single line of code
For example, a file such as emp.xsql:
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="emp.xsl"?>
<FAQ xmlns:xsql="urn:oracle-xsql" connection = "scott">
<xsql:query doc-element="EMPLOYEES" row-element="EMP">
select e.ename, e.sal, d.dname as department
from dept d, emp e
where d.deptno = e.deptno
</xsql:query>
</FAQ>
Generates the following SQL:
<EMPLOYEES>
<EMP>
<ENAME>Scott</ENAME>
<SAL>1000</SAL>
<DEPARTMENT>Boston</DEPARTMENT>
</EMP>
<EMP>
...
</EMP>
</EMPLOYEES>
With JDeveloper, you can easily develop and execute XSQL files. The built-in Web Server and
your default Web Browser will be used to display the resulting pages.
For more information on XSQL Servlet, see your Oracle9i documentation.
7-4
Related topics
Creating an XSQL File

Adding XSQL Tags
Creating XSQL Servlet Clients for Business Components
Creating XSQL Servlet Clients that Access the Database
Running XSQL Servlet Clients
Reference: XSQL Tags
7-5
With JDeveloper, you can easily develop and execute XSQL files. The built-in Web Server and
your default Web Browser will be used to display the resulting pages.
To create an XSQL file:
1. With the project selected in the Navigator, create an XSQL Servlet file by choosing File |
New.
2. Select the Web Objects folder in the Categories pane, then select XSQL from the Items
list and click OK.
This will add a skeleton XSQL file named untitled#.xsql to your project, which opens in the
default editor. You can type code in this editor, add tags by selecting them from the Component
Palette, and modify the file with your own stylesheet information.
Related topics
Adding XSQL Tags

Formatting XML Data with a Stylesheet
7-6
Adding XSQL Tags
All XSQL tags can be inserted by selecting them from the Component Palette, as described
below. You can also insert XSQL tags by typing them in the file. Code Insight is available for
XSQL tags.
To add XSQL tags to a file:
1. In the Navigator, select the XSQL file to which you want to add tags, right-click and
choose XML Editor to open the source file.
2. Place your cursor in the blank line after the <page xmlns:xsql="urn:oracle-xsql"> tag.
3. Choose View | Component Palette to open the Component Palette if it is not displayed.
4. Select XSQL Tags from the drop-down list in the Component Palette.
5. Select the appropriate tag from the Component Palette.
If the tag has no attributes, it appears in the XSQL page immediately. If the tag has one
or more attributes, a dialog displays.
6. In the dialog that displays, enter the required and any optional attributes. Press F1 in the
dialog to get help on an XSQL tag and its attributes.
7. After entering attributes, click Next to display the next dialog or click Finish.
The button you see and the number of dialogs depend on which tag you select. Notice
that the tag and attributes you entered appear in the XSQL page.
8. Add another line in the source file and select another tag from the Component Palette if
necessary.
9. When you have finished adding tags, choose File | Save All to save all your work thus
far.
After adding tags, you can view the raw XML data or format the XML data with a stylesheet.
Related topics
7-7
Viewing Output from Running XSQL Files as Raw XML Data
Creating an XSL Stylesheet for XSQL Files
7-8
Creating XSQL Servlet Clients that Access the
Database
You can create XML based clients for XSQL servlets using XSQL tags. XSQL servlets allow
you to easily get data in and out of the database in XML format. The following procedure shows
how to use the XSQL Query tag to display data.
To create an XSQL Servlet client that directly accesses the database:
1. Create a new project in the workspace that contains the Business Components project
by selecting the workspace in the Navigator and choosing File | New.
2. In the New dialog, click the Projects folder in the Categories pane, then select Empty
Project from the Items list, and click OK.
3. In the New Project dialog, enter a directory name and a file name and click OK to create
the project.
4. Select the new project in the Navigator and choose File | New.
list and click OK.
This adds a skeleton XSQL file named untitled#.xsql to your project.
6. In the Navigator, right-click the new XSQL file, and choose XML Editor to open the
source file.
10. Select the Query tag from the Component Palette.
The Query tag executes a SQL statement and includes its result set in XML format.
11. In the dialog that displays, you can enter values and change default values for the
attributes. Press F1 or click Help in the dialog to get help on the tag and its attributes.
12. After entering attributes, click Next.
13. In the Connection Selection dialog, select your connection if it is not selected, then click
Next.
14. In the Query dialog, type the SQL statement that you want to execute, then click Next.
7-9
For example, you might type select * from customer to display all the records in the
customer database, based on the attributes you entered.
15. Click Finish.
Notice that the Query tag and attributes you entered appear in the XSQL page.
16. Choose File | Save All to save your work thus far.
17. Right-click the XSQL file in the Navigator, and choose Run to view the raw XML data in
your web browser.
You can format the XML data with a stylesheet. The XML data also can be passed on to
another application through a messaging service.
Related topics

7-10
Creating XSQL Servlet Clients for Business
Components
You can create XML based clients for business components using XSQL servlet. XSQL servlet
allows you to easily get data in and out of the database in XML format. The following procedure
shows how to bind an XSQL client to a business components project you have already created,
using the ViewObject - Show tag to display the view object's data in XML format. You could
also use the ViewObject - Update tag to process inserts, updates, and deletes to a view object.
Note: To use XSQL pages with the Business Components XSQL action handlers, the XSQL
Runtime and the JBO HTML libraries need to be in your project's classpath, in addition to any JBO
libraries that are needed based on your intended connection mode. JDeveloper includes them in the
classpath automatically.
To create an XSQL Servlet client for Business Components:
1. Create a new project in the workspace that contains the Business Components project
by selecting the workspace in the Navigator and choosing File | New.
2. In the New dialog, click the Projects folder in the Categories pane, then select Empty
Project from the Items list, and click OK.
3. In the New Project dialog enter a directory name and a file name and click OK to create
the project.
4. Select the new project in the Navigator and choose File | New.
list and click OK.
This adds a skeleton XSQL file named untitled#.xsql to your project.
6. In the Navigator, right-click the new XSQL file, and choose XML Editor to open the
source file.
10. Select the ViewObject - Show tag from the Component Palette.
The ViewObject - Show tag shows the view object's data in XML format. The ViewObject
- Update processes inserts, updates, and deletes to a view object based on an optionally
7-11
transformed XML document.
11. In the dialog that displays, you can change the default values for the attributes. Press F1
or click Help in the dialog to get help on the tag and its attributes.
12. After entering attributes, click Next.
13. In the View Object Selection dialog, select the appropriate view object.
14. Click Finish.
Notice that the tag and attributes you entered appear in the XSQL page.
16. Right-click the XSQL file in the Navigator, and choose Run to view the raw XML data in
your web browser.
You can format the XML data with a stylesheet. The XML data also can be passed on to
another application through a messaging service.
Related topics
Creating a New Business Components Project

7-12
After you have added elements to your XSQL file, you should test your XML syntax and then
run it.
To run an XSQL servlet file:
1. In the Navigator, right-click the XSQL file and select Check XML Syntax.
JDeveloper will scan the XSQL file looking for XML syntax errors and display the results
in the Message window.
2. If there are no XML syntax errors, right-click the XSQL file and select Run.
JDeveloper compiles the servlet. It then starts its built-in OC4J webserver, launches your
default web browser, and displays the output of the servlet in the browser.
Related topics

7-13
Viewing Output from Running XSQL Files as Raw
XML Data
After creating an XSQL file and adding tags, you can view the raw XML data or format the XML
data with a stylesheet.
To view an XSQL file as raw XML data:
1. Select the XSQL file in the Navigator, right-click and choose Run to open the source file
in your web browser.
JDeveloper starts its built-in OC4J webserver, launches your default web browser, and
displays the raw XML data that is produced after the XSQL servlet processes the XSQL
page.
Related topics

Adding XSQL Tags
7-14
After creating an XSQL file and adding tags, you can format the XML data with a XSL
stylesheet or view the raw XML data. You can use a stylesheet you previously created or
create a new one in JDeveloper and apply it. By applying a stylesheet, you can convert the
XML data into HTML or another markup language, such as wireless markup language (WML).
To format the XML data with a stylesheet:
1. In the Navigator, select the XSQL file to which you want to add a stylesheet, right-click
and choose XML Editor to open the source file.
2. Locate the xml-stylesheet line and comment, which looks like this:

3. Uncomment the <?xml-stylesheet ?> line by moving it below the --> closing comment
bracket.
4. In this line, replace YourStyleSheet.xsl with the name of your stylesheet; for example,
your stylesheet could be named stylesheet.xsl, wmlstylesheet.xsl, or any other filename
with an .xsl extension.
Now you must add the .xsl file that you just entered to your project, if you used one you
created outside of this project.
5. In the Navigator, select the project and choose Project | Add to Project (project name).
In the Add to Project dialog, navigate to the directory and select the stylesheet file.
6. Click OK.
7. Choose File | Save All to save all your changes.
The file you added displays in the Navigator and opens in the XML Editor. You can close
the open files.
8. Select the XSQL file in the Navigator, right-click and choose Run to open the file in your
web browser.
7-15
You can see the formatted XML data in the browser.
Related topics

7-16
Within JDeveloper, you can create an XSL stylesheet that you want to apply to your XSQL files
in order to format the data for HTML, WML or another output. When you create an XSL
stylesheet, it is added to the selected XSQL project.
To create an XSL stylesheet:
1. With the XSQL project selected in the Navigator, create an XSL stylesheet file by
choosing File | New.
2. Select the Web Objects folder in the Categories pane, then select XSL from the Items list
and click OK.
This will add a skeleton XSL file named untitled#.xsl to your project, which opens in the default
editor. You can create your own custom stylesheet. An example of an XSL stylesheet that
transforms XML data into wireless markup language (WML) is provide below. When you are
finished, you can add the stylesheet name to your XSQL file to format the raw XML data.
XSL Stylesheet Example
This stylesheet demonstrates the conversion of XML to WML. It uses the default DeptView in a
BC4J application.
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">


<xsl:output type="wml" media-type="text/x-wap.wml"
doctype-public="-//WAPFORUM//DTD WML 1.1//EN"
doctype-system="http://www.wapforum.org/DTD/wml_1.1.xml" indent="yes" />
<xsl:template match="*|/"><xsl:apply-templates/></xsl:template>
<xsl:template match="text()|@*"><xsl:value-of select="."/></xsl:template>
<xsl:template match="/">
<wml>
<card id="C1">
<p mode="nowrap">
7-17
<big>DEPTLIST</big>
</p>
<xsl:for-each select="page/DeptView/DeptViewRow">
<p>
<strong><xsl:value-of select="Deptno"/> </strong>
<xsl:value-of select="Dname"/>
<xsl:value-of select="Loc"/>
</p>
</xsl:for-each>
</card>
</wml>
</xsl:template>
</xsl:stylesheet>
To see the result of using this stylesheet, you can create a new BC4J project based on the
DEPT table, create an XSQL page in which you reference this stylesheet, and use the (BC4J)
ViewObject Action Handler.
Related topics

Creating an Action Handler for XSQL
7-18
Modifying the XSQL Configuration File
The XSQL configuration file, XSQLConfig.xml, is on the classpath, so your XSQL pages always
have access to it. The connection information is added to the XSQLConfig.xml when a new
connection is created in the IDE. The XSQLConfig.xml is located in the system directory and
gets copied to the WEB-INF directory when a project containing an XSQL file is compiled. You
can add the file to your project if you need to modify it, for example, to register custom action
handlers.
To modify the XSQL configuration file for your project:
1. With the project selected in the Navigator, choose Project | Add to Project (project
name).
2. Navigate to the system directory in your JDeveloper installation directory, select
XSQLConfig.xml and click OK.
The file is added to the project.
3. Make any changes or additions in the source editor.

4. Choose File | Save to save your revised file.
Related topics
Creating an Action Handler for XSQL

7-19
Creating a Custom Action Handler for XSQL
An action handler in an XSQL page is a java class that gets invoked to perform a specific task.
There are pre-built action handlers for various tasks such as setting cookies, applying
stylesheets, performing queries against databases, etc. However, if you choose to perform
some operation which is not provided by the built in action handlers, then you can write what is
called a custom action handler. A custom action handler is a Java class that can be invoked
from an XSQL page just as easily as a predefined action handler.
The procedure for creating an action handler is to:
● Add the XSQL configuration file to your project.

● In the XSQL configuration file, register the new action handler by specifying the element
name and handlerclass.
● In the XSQL file, add the new element and its attributes.
● In the XSQL file, add connection information to the <page> tag.
● Add a Java file to the project.
● In the Java file, create a class that extends the XSQLActionHandlerImpl class.
The XSQL Action Handlers for BC4J are packaged as part of the "JBO HTML" library in the
IDE, which includes the relevant: <JdevHome>\BC4J\lib\bc4jhtml.jar archive in the build.
Related topics

7-20
Using XML Metadata Properties in XSQL Files
The following custom properties effect XML generation when using the writeXML method of a
view object or row.
Property Name Value Valid For

a legal element view objects and view
XML_ELEMENT
name attributes
a legal element
XML_ROW_ELEMENT view objects
name
any value (not
XML_CDATA view attributes
empty)
any value (not view objects and view
XML_EXPLICIT_NULL
empty) attributes
XML_ELEMENT
If the XML_ELEMENT custom property is present for a view object, its value is used as the
XML element name for the view object in XML, when it is generated using the writeXML
method and "consumed" by the readXML method.
If the XML_ELEMENT custom property is present for a view attribute, its value is used as the
XML element name for the attribute in XML, when it is generated using the writeXML method
and "consumed" by the readXML method.
For example, for a view object named DeptView with an attribute named Sal, setting:
● XML_ELEMENT="Departments" in the view object properties

● XML_ELEMENT="Salary" in the view attribute properties for Sal
would produce XML like:
<Departments>
<DeptViewRow>
<Empno>1010</Empno>
<Ename>Steve</Ename>
<Salary>1234</Salary>
</DeptViewRow>
</Departments>
7-21
instead of the default:
<DeptView>
<DeptViewRow>
<Empno>1010</Empno>
<Sal>1234</Sal>
</DeptViewRow>
</DeptView>
XML_ROW_ELEMENT
If the XML_ROW_ELEMENT custom property is present for a view object, its value is used as
the XML element name for each row of query results produced by the view object in XML, when
it is generated using the writeXML method and "consumed" by the readXML method.

● XML_ROW_ELEMENT="Department" in the view object properties
<Departments>
<Department>
<Empno>1010</Empno>
</Department>
</Departments>
<DeptView>
<DeptViewRow>
<Empno>1010</Empno>
<Sal>1234</Sal>
7-22
</DeptViewRow>
</DeptView>
XML_CDATA
If the XML_CDATA custom property is set to a not empty value for a view attribute, then its
value will be output as a CDATA section instead of as plain text.
XML_EXPLICIT_NULL
If the XML_EXPLICIT_NULL custom property is set to a not empty value for a view object, then
any attribute with a null value will generate an XML element that looks like:
<AttributeName null="true"/>
instead of omitting the <AttributeName> element from the XML result, which is the default.
If the XML_EXPLICIT_NULL custom property is set to a not empty value for a view attribute,
then in the case that the indicated attribute has a null value, the system will generate an XML
element that looks like:
Related topics

Adding XSQL Tags
7-23
XSQL Tag Reference
Please select an XSQL tag to see a complete description, syntax and examples.
xsql:delete-request—Deletes the rows represented in the XML document that has been posted
in the request.
xsql:dml—Executes a SQL DML statement or PL/SQL anonymous block.
xsql:include-owa—Executes a PL/SQL stored procedure that uses the OWA packages to

generate XML content, and includes the resulting XML.
xsql:include-param—Includes XML representing the name and value of a specified parameter.
xsql:include-request-params—Includes an XML fragment representing the names and values of

all HTTP parameters, cookies, and session variables.
xsql:include-xml—Include external XML content by specifying an absolute, relative , or

parameterized URL.
xsql:include-xsql—Includes the XML output of another XSQL page.
xsql:insert-param—Inserts the value of a parameter into a database table or view.
xsql:insert-request—Inserts the (optionally transformed) XML document that has been posted
in the request into a database table or view.
xsql:query—Executes an arbitrary SQL statement and includes its result set in canonical XML
format.
xsql:ref-cursor-function—Executes an arbitrary stored function returning a REF CURSOR and

includes the result set in canonical XML format.
xsql:set-cookie—Sets the value of an HTTP Cookie, and optionally specifies the maximum age
and domain of the cookie.
xsql:set-page-param—Sets the value of a page-level parameter.
xsql:set-session-param—Sets the value of a session-level parameter.

7-24
xsql:set-stylesheet-param—Sets the value of a top-level XSLT stylesheet parameter.
xsql:update-request—Updates the rows represented in the (optionally transformed) XML

document that has been posted in the request.
xsql:action handler="oracle.jbo.xsql.ViewObject"—Renders canonical XML data from a

business components view object and optionally any number of levels of related, view-linked
view objects.
xsql:action handler="oracle.jbo.xsql.UpdateViewObject"—Processes inserts, updates, and

deletes to rows in a view object and and any number of levels of related, view-linked view
objects, based on an optionally transformed XML document.
Related topics

Adding XSQL Tags
7-25
Developing Java GUI Clients
● Developing Java GUI Clients
● About JDeveloper's User Interface Design Tools

● About the Look and Feel of a Swing Application
● About JDeveloper UI Components
❍ About JavaBeans in JDeveloper
❍ About AWT JavaBeans

❍ About Swing JavaBeans Components
❍ About Sizing Properties
● Working with Layout Managers

❍ About Layout Managers
❍ About Layouts Provided with JDeveloper

■ About BorderLayout
■ About BoxLayout2
■ About CardLayout
■ About FlowLayout
■ About GridBagLayout
■ About GridLayout
■ About OverlayLayout2
■ About PaneLayout
■ About VerticalFlowLayout
■ About XYLayout
❍ About Layout Properties

❍ About Layout Constraints
❍ Determining the Size and Location of Your UI Window at Runtime
❍ Choosing Layout Manager Properties
❍ Prototyping your UI with Layout Properties
❍ Laying Out Your UI
8-1
❍ Selecting a Final Layout Manager
❍ Working with Nested Containers and Layouts
❍ Adding Custom Layout Managers
● Working with Containers and Components

❍ About Containers
❍ About Component Properties in the Inspector

❍ Creating Containers
■ Creating a Frame with the Frame Wizard
■ Creating a Panel
■ Creating a Dialog Box
■ Creating a Tabbed Pane
❍ Working with Components in a Container

■ Adding Components to Your UI
■ Changing the Layout for a Container

■ Modifying Component Layout Constraints
■ Selecting Components in Your User Interface
■ Sizing and Moving Components
■ Grouping Components
■ Cutting, Copying, Pasting and Deleting Components
❍ Working with Menus

■ About Menu Terminology
■ About Menu Components

■ About the Menu Editor
■ Customizing Menus with the Menu Editor
■ Adding Menu Items
■ Disabling Menu Items

■ Specifying Accelerators
■ Inserting a Separator Bar
■ Creating Checkable Menu Items
8-2
■ Adding a Menu Component to a Frame
■ Inserting and Deleting Menus and Menu Items
■ Moving Menu Items
■ Creating Submenus
■ Adding a Popup Menu
● Working with Events

❍ About Events
❍ Attaching Event Handling Code to Menu Events

❍ Attaching Event Handling Code to a Component Event
● Working with Applets

❍ Creating an Applet
❍ Creating an Applet HTML File

❍ Deploying Applets
● Working with JClient Applications

❍ About JClient UI Design in JDeveloper
■ About the JClient Architecture
■ About the JClient Design Time Wizards

■ About the Client Project Configuration File
■ About JClient Application Code
■ About the Frame or Applet Class in JClient
■ About the Layout Panel in JClient

■ About Data Panels in JClient
■ About Control Binding in JClient
■ About JClient Models for Swing Controls

■ About Using JClient Data Forms
■ About Master-Detail Forms in JClient
■ About the JClient Graph Panel
■ About the JClient Login Dialog
■ About Multimedia in JClient Applications
8-3
■ About Find Mode for JUNavigationBar Controls
■ About JClient Composite Components
■ About Panel Binding in JClient
■ About Navigating the UI Using JClient Controls
■ About JClient Validation Events
■ About JClient Compatibility with DAC
■ About Java Web Start and JClient Applications
❍ Creating Simple JClient Forms

■ Defining Business Component Runtime Properties in the bc4j.xcfg File for
JClient Applications
■ Creating a Client Data Model Definition
■ Creating Single Table JClient Forms
■ Creating Master-Detail JClient Forms
❍ Modifying JClient Forms

■ Changing Client Data Model References
■ Creating a New JClient Data Panel

■ Creating a JClient Graph Panel
■ Adding Controls to a JClient Data Panel
■ Setting a JClient Control Binding
■ Binding a Panel to a JClient Application
❍ Working with JClient Models

■ Setting an Action Control Binding
■ Setting an Attribute Control Binding

■ Setting an Attribute List Control Binding
■ Setting a Boolean Control Binding
■ Setting an Enumeration Control Binding
■ Setting an LOV Control Binding
■ Setting a Navigation Control Binding
■ Setting a Node Control Binding
■ Setting a View Control Binding
8-4
❍ Working with JClient Controls
■ Using the JUImage Control
■ Using the JULabel Control

■ Using the JUNavigationBar Control
■ Using the JUStatusBar Control
■ Using the OrdMediaControl
❍ Working with Java Web Start and JClient Applications

■ Setting Up JClient Runtime Information
■ Creating a Web Start JNLP Definition for JClient Applications
8-5
Developing Java GUI Clients
Using JDeveloper's UI Editor, you can quickly and easily assemble the elements of a user
interface (UI) for a Java application or applet using Swing components. You construct the UI
with JavaBeans selected from the component palette, such as buttons, text areas, lists, dialogs,
and menus. Then, you set the values of the component properties and attach event-handler
code to the component events.
This section discusses the following elements of creating a user interface in JDeveloper:

Working with Layout Managers Introduces layout managers and explains their purpose in UI
design. It also explains how you use layout managers in the UI
Editor. Each layout is explained separately.
Working with Containers and Components Explains how to create and work with containers in UI design.
Topics address support in JDeveloper for heavyweight
containers (Frames, Panels, and Dialog Boxes) and Swing
containers (Tabbed Pane, Menu Bar, and Popup Menus).
Working with Events Explains what events are and how to use them in your UI.
Working with Applets Explains how to use the Applet Dialog to generate applet, and
HTML files.
Working with JClient Applications Explains how to work with the JClient framework, which
JDeveloper provides for building Swing-based applications and
applets as Java clients for business components. Describes
the JClient tools that help you to quickly assemble Java clients
with direct binding to the Business Components for Java
(BC4J) framework.
Working with Multimedia Content Explains how to work with image, document, audio, and video
content in Java clients that rely on the Business Components
for Java (BC4J) framework to access the database. Describes
the oracle.ord.im and oracle.ord.html APIs for utilizing
Business Component domains for interMedia.
Working with Java Web Start and Java Clients Explains how to use the Java Web Start Launcher Wizard to
generate the files needed to use Java Web Start to deploy and
run client-side Java applications from web servers.
8-6
Related topics
About JDeveloper's User Interface Design Tools

About JDeveloper UI Components
About the Look and Feel of a Swing Application
8-7
About JDeveloper's User Interface Design Tools
With JDeveloper tools, you can visually design and program Java classes to produce new
compound or complex components.
JDeveloper UI design tools include the following:
● A UI Editor in which panels and other UI components are placed and edited. You access
the UI Editor by right clicking the file in the Navigator and choosing UI Editor.
● A Component Palette containing visual and nonvisual components. You display the
Component Palette for a particular file that you open in the UI Editor. To display the
Component Palette for an open file, choose View | Component Palette.
● A Structure window that displays a hierarchical view of all the components in your source
file, and their relationships. You access the Structure window below the Navigator
window or if docked, by choosing Window | Structure.
● The Property Inspector, used to inspect and set component properties and to attach
methods to component events. Changes made in the Inspector are reflected visually in
the UI Editor and source code. You display the Property Inspector for a particular file that
you open in the UI Editor. To display the Property Inspector for an open file, choose View
| Property Inspector.
Requirements for Visually Designing a Class in JDeveloper
If you want to use the UI design tools on a file, it must meet the following requirements:
● It must be a Java file.
● It must be free from syntax errors.
● It must contain a public class (the file name must be the same as the name of the public
class).
● It must follow JDeveloper coding conventions:
❍ All UI controls are declared as class members or as local variables within jbInit().
8-8
❍ All UI property settings done in jbInit(). This is necessary in order for the
JDeveloper UI Editor and Property Inspector to reflect the settings.
❍ All property settings set as expressions involve only member UI controls or static
values.
● It must have a default constructor.
Any file that meets the above requirements can be visually designed using the UI Editor and
the Property Inspector. You can also visually design a non-UI class.
Note: These requirements are satisfied when you create your files with any of the JDeveloper
dialogs.
When you first add a component to your design, the JDeveloper UI Editor ensures that your
class has a default constructor, a private jbInit() method, and that this jbInit() method is called
correctly from the default constructor. If JDeveloper does not find this code, it will add it. It will
also add any imports needed by the component.
When you open the file in the UI Editor, JDeveloper updates the Structure window tree. For
example, if your class has a frame and a menu, there will be subtrees for UI and Menu. If you
drop any other JavaBeans components into the Structure window, an 'Others' folder appears so
you can select and edit these components in the Property Inspector.
8-9
About the Look and Feel of a Swing Application
JDeveloper includes the Swing GUI components. The Swing classes allow you to specify a look
and feel for a user interface. You can take advantage of this new Java pluggable look-and-feel
to create applications that have the look and feel of a user's native desktop for Windows or
Solaris machines. You can also ensure a uniform look and feel in your applications across
platforms with the Java Metal look and feel.
There are four look and feel choices in JDeveloper:
● Oracle
● Metal
● CDE/Motif
● Windows
There are also several considerations when setting the look and feel using the UI Manager:
● The line of code for the look and feel statement is inside a try/catch block. This
placement is necessary for it to compile.
● This code needs to be run before any components are instantiated. That is why it is
placed in the <Application>.java static main() method.
● The class UIManager lives in the com.sun.java.swing package.
The Metal look and feel is default for Swing components. If you want to use the Metal look and
feel, you do not have to change your code.
To change to the Oracle look and feel:
1. Open the Application file in the Code Editor.

2. In the Main method, add the following code:
try {
UIManager.setLookAndFeel(new
oracle.bali.ewt.olaf.OracleLookAndFeel());
}
catch (Exception e) {
}
8-10
It is necessary to have the Oracle look and feel (OLAF) share.jar and jewt4.jar files from
the jlib directory in the classpath.
To change to the Windows look and feel:

try {
com.sun.java.swing.plaf.windows.WindowsLookAndFeel());
}
}
To change to the Motif look and feel:

try {
com.sun.java.swing.plaf.motif.MotifLookAndFeel());
}
}
By default, the Metal look and feel is used, but if you need to, you can specify it.
To change to the Metal look and feel:

try {
javax.swing.plaf.metal.MetalLookAndFeel());
}
8-11
}
8-12
About JDeveloper UI Components
This section gives on overview of adding and wiring components in your project:

About JavaBeans in JDeveloper Provides an overview of JavaBeans architecture, as well as the types of
JavaBeans components that are provided in JDeveloper.
About AWT JavaBeans Provides an overview of AWT JavaBeans.
About Swing JavaBeans Provides an overview of Swing components.
About Sizing Properties Describes how layout managers use component sizing properties.
See also
For more information on Swing Components, go to this java.sun.com web page:
http://java.sun.com/products/jfc/tsc/articles/component_gallery/index.html
For more information on Swing Containers, go to this java.sun.com web page:
http://java.sun.com/products/jfc/tsc/articles/containers/index.html
8-13
About JavaBeans in JDeveloper
JavaBeans are the Java building blocks used in JDeveloper's UI Editor to build a program.
Each JavaBean represents a program element, such as a user interface object, a data-aware
control, or a system facility. You build your program by choosing and connecting these
elements.
JDeveloper comes with a set of ready-to-use JavaBeans on the Component Palette. You can
also supplement these components by creating new JavaBeans yourself or by installing third-
party ones.
JavaBeans are objects in the true object-oriented programming (OOP) sense. Because they
are true objects, JDeveloper components exhibit the following:
● Encapsulation of some set of data and data-access functions.
● Inheritance of data and behavior from a superclass.
● Polymorphism, allowing them to operate interchangeably with other objects derived from
a common superclass.
Each component encapsulates some element of a program, such as a window or dialog box, a
field in a database, or a system timer. Visual components must ultimately extend either
java.lang.Object or extend some other class that derives from it such as javax.swing.Panel.
Non-visual JavaBeans components do not have this requirement.
To be recognized and used in JDeveloper, components must conform to the JavaBeans

specification. For further details about the exact technical requirements for JavaBeans
components, visit the JavaSoft Web site at http://java.sun.com/products/javabeans/docs/.
To be useful in a program, a JavaBean must provide the means by which it can be manipulated
or interact with other components. JavaBeans meet this requirement by defining properties,
methods, and events.
All components have properties, methods, and events built into them. Some of the properties,
methods, and events that components provide are actually inherited from ancestor classes,
which means they share these elements with other components. For example, all UI
components inherit a property called background that represents the background color of the
component. Each component can also introduce its own unique properties, methods, and
8-14
events. For example, the Swing Checkbox component has a property called selected that
indicates whether or not this component initially appears checked.
Related topics
AWT Components
Swing Components
8-15
About AWT JavaBeans
AWT JavaBeans components use the standard controls of the underlying platform to display
the user interface. This architecture makes AWT components simple and straightforward to
implement, but limits control over the final display of the UI and reduces flexibility. They also
require more system resources to run, which is why they are sometimes referred to as
heavyweight components. Swing components, which are implemented in Java to be self-
rendering and therefore make less use of system resources, which is why they are referred to
as lightweight components. Swing components can be more complex to implement, but offer
greater flexibility and consistency between host platforms.
Component Description
Button Simple push button.
Checkbox True/false, on/off boolean control. As a standalone component, the checkbox appears as a
square with an X to indicate when its value is set to true. When set as a member of a
checkbox group, the checkbox becomes a circle (Radio Button): a dot in the circle indicates
that its value is set to true. Add a checkbox component to a CheckboxGroup by setting its
CheckboxGroup property to the name of the CheckboxGroup to which it belongs.
CheckboxGroup Non-visual component used to integrate the behavior of a set of check box components.
Only one item in a checkbox group can be set to true at one time. Checkbox components are
added to the CheckboxGroup by setting the CheckboxGroup property to the name of the
corresponding CheckboxGroup. The default value for a CheckboxGroup can be set by
setting its SelectedCheckbox property to the name of the checkbox component.
Tip: Depending on the order in which you add the Checkbox components and
CheckboxGroup, the CheckboxGroup may be instantiated before the Checkboxes. To
ensure that the correct default is set, you can move the SelectedCheckbox and current
initialization statements to the bottom of the JbInit method so that all of its constituents are
instantiated before the default is set.
Choice Displays a popup menu. The label of the Choice control is the currently selected item. This is
similar to a combobox.
Label Displays a non-editable text label in the application, though its value may change
programmatically.
List Displays a scrolling list of data items. The user may be able to select one or more items
depending on the property settings of the List.
8-16
MenuBar Displays a menubar. Any container can add a MenuBar control as a child, however only
Frame has the setMenubar() method which will parent the MenuBar at a specific location and
will not interfere with the locations of any other children. Menubars are not available in
Applets. For more information about creating menus, see Working with Menus.
PopupMenu Displays a popup menu with a list of commands. Popup menus can be attached to panels,
and are available for use in Applets. For more information about creating menus, see
Working with Menus.
Panel A container which is used to display a group of controls. Each panel can have its own layout
to give you control over the positioning of components in relation to one another.
Scrollbar A slider control that allows the user to set an integer value. The scrollbar can be set to
display horizontally or vertically.
ScrollPane A type of panel that has horizontal and vertical scrollbars available to enable you to display a
child component that is larger than the ScrollPane itself.
TextArea A text component that displays a single string of text in multiple rows, each ending with a
newline character. Text can be scrolled up and down, left and right.
TextField An editable text component that displays a single string of text in a single row.
8-17
About Swing JavaBeans Components
Swing components are lightweight components that are self-rendering and do not use
Windowing resources as do AWT components. In many cases, these components have
corresponding AWT components, but the Swing version is enhanced to allow greater flexibility
and consistency between platforms.
Note: Swing components rely on underlying functionality in Swing containers. If you intend to use
Swing JavaBeans, you must create your program using a JFrame, JPanel or other container that
implements the basic Swing functionality.
Component Description
JButton A simple push button. A JButton can have an embedded icon.

JCheckBox A square box used to display boolean (true/false) values. When its value is set to true, the
box displays a checkmark by default. You have the option of setting your own checkmark
graphic.
JComboBox Similar to the Choice control in AWT, displays a list of values that the user can select at
runtime. JComboBox has the property editable which enables the user to type a new value at
runtime.
JEditorPane A specialized JTextComponent that displays text formatted with HTML 3.2 or RTF. It is
intended to allow you to create help pages for your application or applet.
JLabel A text component that enables you to display a text string and optional icon. Additional
properties enable you to set the position of the text relative to the icon.
JList Displays a list of objects.
Tip: The JList, unlike the AWT List component, doesn't have a scrolling facility built into the
component. To make a scrollable list, you need to drop the list component into a JScrollPane
container.
JPasswordField A JTextField that by default displays asterisks (*) in place of the characters entered by the
user.
JProgressBar Displays a progress bar that graphically depicts the percentage of completion for a process.
JRadioButton This component is specifically designed to behave as a Radio Button. When grouped with
other JRadioButtons in a ButtonGroup, only one of the buttons in the group can be selected
at one time. The ButtonGroup is a non-visual component.
JScrollBar A graphic control the user can use to set an integer value. This component can be displayed
with either a horizontal or a vertical orientation.
8-18
JSeparator A component that draws a straight line. It is intended to be used as a component in a JMenu,
but since it is an actual component, you can use it to draw a line in your UI that separates
one set of controls from another. The JSeparator can be displayed in vertical or horizontal
orientation.
JSlider Similar to a JScrollBar, this control allows the user to set an integer value using a graphic
control. JSlider allows you to set major and minor tick marks, and to display a border around
the control.
JTable Displays information in a two-dimensional grid, similar to a spreadsheet application.
Tip: The JTable, unlike the AWT List component, doesn't have a scrolling facility built into it.
To make a scrollable table, you need to drop the list component into a JScrollPane container.
JTextArea An editable text area that displays a single string in multiple rows, each of which ends in a
newline character.
Tip: In order to make a JTextArea scrollable, it needs to be displayed in a JScrollPane

container.
JTextField An editable text area that displays a single string in a single row.
JTextPane A full-featured text editor control that enables word wrap, image display, and style definition.
Tip: In order to make a JTextPane scrollable, it needs to be dropped in a JScrollPane

container.
JTree Displays hierarchical information, such as file directories, in a tree format.
Tip: The JTree, unlike the AWT List component, doesn't have a scrolling facility built into it.
To make a scrollable tree, you need to drop the list component into a JScrollPane container.
JToggleButton Toggle buttons are similar to JCheckBox controls. When they are pushed (set to true) they
remain true until they are set to false by pressing them again. JToggleButtons can be placed
in a ButtonGroup so that only one in the group can be true at one time. Toggle buttons are
useful in toolbars to display a tool in an active state. The buttons in the Component Palette
are examples of toggle buttons.
Related topics
About Containers
About Component Properties in the Inspector
Working with Components in a Container
Working with Applets
See also
8-19
For more information on Swing components, go to this java.sun.com web page:
8-20
About Sizing Properties
Layout managers use various pieces of information to determine how to position and size
components in their container. Components provide a set of methods that allow layout
managers to intelligently lay out components. All of these methods allow a component to
communicate its desired sizing to the layout manager.
These methods are property getters and represent the following.
getPreferredSize()
The size a component would choose to be, that is, the ideal size for the component to look
best. Depending on the rules of the particular layout manager, the preferredSize may or may
not be considered in laying out the container.
getMinimumSize()
How small the component can be and still be usable. The minimumSize of a component may
be limited, for example, by the size of a label. For most controls, minimumSize is the same as
preferredSize. Layout managers generally respect minimumSize more than they do
preferredSize.
getMaximumSize( )
The largest, useful size for this component. This is used so that the layout manager won't waste
space on a component that can't use it effectively. For example, BorderLayout could limit the
center component's size to its maximum size, and then either give the space to the edge
components, or limit the size of the outer window when resized.
getAlignmentX()
How the component would like to be aligned along the x axis, relative to other components.
getAlignmentY()
How the component would like to be aligned along the y axis, relative to other components.
To understand how each layout manager uses these pieces of information, study the individual
layouts listed in Layouts Provided with JDeveloper.
8-21
8-22
Working with Layout Managers
This section explains how to use JDeveloper's layout managers to control how components are
located and sized in the container each time it is displayed. A layout manager automatically
arranges the components in a container according to a particular set of rules specific to that
layout manager.

Determining the Size and Location of Your UI Describes ways you can use JDeveloper to control the
Window position of windows in your applicaiton. It also describes
ways that particular layout managers influence window
size and location.
Choosing Layout Manager Properties Provides links to descriptions of the various layout
managers and their properties.
Prototyping Your UI with Layout Properties Provides some tips on how to use JDeveloper to
effectively develop prototypes.
Laying Out Your UI Discusses JDeveloper's UI design tools for arranging

the UI.
Selecting a Final Layout Manager Discusses the importance of choosing a final layout
manager.
Working with Nested Containers and Layouts Gives an example of nest containers and describes
tools that help you to manage working with nested
containers.
Adding Custom Layout Managers Describes how to make your layout manager display in
JDeveloper.
Related Topics
About Layout Managers

About Layouts Provided with JDeveloper
8-23
About Layout Properties
About Layout Constraints
8-24
About Layout Managers
A Java programs can be deployed on more than one platform. If you were to use standard UI
design techniques of specifying absolute positions and sizes for your UI components, your UI
might not look good on all platforms. What looks fine on your development system might be
unusable on another platform. To solve this problem, Java provides a system of portable layout
managers. Layout managers allow you to specify rules and constraints for the layout of your UI
in a way that will be portable.
Layout managers give you the following advantages:
● Correctly positioned components that are independent of fonts, screen resolutions, and
platform differences.
● Intelligent component placement for containers that are dynamically resized at runtime.
● Ease of translation with different sized strings. If a string increases in size, the
components stay properly aligned.
A Java UI container uses a special object called a layout manager to control how components
are located and sized in the container each time it is displayed. A layout manager automatically
arranges the components in a container according to a particular set of rules specific to that
layout manager.
The layout manager sets the sizes and locations of the components based on various factors
such as
● the layout manager's layout rules
● the layout manager's property settings, if any;
● the layout constraints associated with each component
● certain properties common to all components, such as preferredSize, minimumSize,

maximumSize, alignmentX, and alignmentY
● the size of the container
8-25
In Java, certain types of containers use specific layout managers by default.
● All panels (including applets) use FlowLayout.
● All windows (including frames and dialog boxes) use BorderLayout.
When you create a container in a Java program, you can accept the default layout manager for
that container type, or you can override the default by specifying a different type of layout
manager.
Normally, when coding your UI manually, you override the default layout manager before
adding components to the container. When using the UI Editor, you can change the layout
whenever you like. JDeveloper will adjust the code as needed.
JDeveloper's UI Editor uses a default layout manager for each container, usually null layout. If
you want to use a different layout manager than the default, you can do so by explicitly adding
a layout manager to the source code for the container, or by selecting a layout from the
container's layout property list in the Inspector.
Important: If you want to change the properties for a layout manager using JDeveloper's UI
Editor, you must explicitly specify a layout for a container so its properties will be accessible in
the Property Inspector.
Choose a layout manager based on the overall design you want for the container. Some
layouts can be difficult to work with in the UI Editor because they immediately take over
placement and resizing of a component as soon as you add it to the container. To alleviate this
problem during initial layout prototyping, JDeveloper provides a default layout called Null, which
leaves the components exactly where you place them and at the size you specify. Starting with
an Null makes prototyping easier in your container. Later, after adding components to the
container, you can switch to an appropriate portable layout for your design.
In some designs, you might use nested panels to group components in the main Frame, using
various different layouts for the Frame and each of its panels.
Note:If you really want to design a panel without a layout manager, you can set the layout manager
in the source code to null. However, you should not leave it this way for deployment.
Experiment with different layouts to see their effect on the container's components. If you find
the layout manager you've chosen doesn't give you the results you want, try a different one, or
try nesting multiple panels with different layouts to get the desired effect. See Using nested
8-26
panels and layouts.
For a more detailed discussion of each layout, see the individual topics for each layout in
Layouts Provided with JDeveloper. You can also study the Java Language Tutorial at
http://www.javasoft.com/nav/read/Tutorial/.
8-27
About Layouts Provided by JDeveloper
JDeveloper provides the following standard layout managers from the Java AWT:
BorderLayout, FlowLayout, GridLayout, CardLayout, and GridBagLayout. For Swing,
BoxLayout2 and OverLayout2, have been included.
JDeveloper also provides three custom layouts:
● XYLayout that keeps components you put in a container at their original size and location
(x,y coordinates).
● PaneLayout, used by the SplitPanel control.
● VerticalFlowLayout, which is very similar to FlowLayout except that it arranges the

components vertically instead of horizontally.
You can create custom layouts of your own, or experiment with other layouts like the ones in
the sun.awt classes, or third-party layout managers, many of which are public domain on the
Web. If you want to use a custom layout in the UI Editor, you may have to provide a Java
helper class file to help the UI Editor use the layout.
JDeveloper's layout managers are explained in detail in the following sections.
● BorderLayout
● BoxLayout2
● CardLayout
● FlowLayout
● GridBagLayout
● GridLayout
● OverlayLayout2
● PaneLayout
● VerticalFlowLayout
● XYLayout
Most of your UI designs will use a combination of layouts by nesting different layout panels
8-28
within each other.
Related Topics
Working with Nested Containers and Layouts
8-29
About BorderLayout
BorderLayout arranges a container's components in areas named North, South, East, West,
and Center.
● The components in North and South are given their preferred height and are stretched
across the full width of the container.
● The components in East and West are given their preferred width and are stretched
vertically to fill the space between the north and south areas.
● A component in the Center expands to fill all remaining space.
BorderLayout is good for forcing components to one or more edges of a container, and for
filling up the center of the container with a component. It is also the layout you want to use to
cause a single component to completely fill its container.
You will probably find BorderLayout to be the most useful layout manager for the larger
containers in your UI. By nesting a panel inside each area of the BorderLayout, then populating
each of those panels with other panels of various layouts, you can achieve quite complicated UI
designs.
Components are positioned in one of five areas within a BorderLayout, based on the
constraints property. You can set the constraints property for the component in the Inspector to
one of the following values: North, South, East, West, or Center.
For example, to put a toolbar across the top of a BorderLayout container, you could create a
FlowLayout panel of buttons and place it in the North area of the container. You do this by
selecting the panel and choosing North for its constraints property in the Inspector.
8-30
To set the constraints property:
1. Select the component you want to position, either in the UI Editor or the Structure
window.
2. Select the constraints property in the Inspector, and click its value field.
3. Click the down arrow on the constraints property dropdown list and select the area you
want the component to occupy.
4. Press Enter or click anywhere else in the Property Inspector to commit the change to
code.
If you use JDeveloper's UI Editor to change the layout of an existing container to BorderLayout,
the components near the edges automatically move to fill the closest edge. A component near
the center may be set to Center. If a component moves to an unintended location, you can
correct the constraints property in the Inspector, or drag the component to a new position in the
UI Editor.
Each of the five areas can contain any number of components (or panel of components),
however, unless the topmost component is not opaque, any lower components in the same
area will be covered by the topmost one.
The following are some general guidelines for working with multiple components and
BorderLayout:
● Make sure the container has no more than five components.

● Use XYLayout first to move the components to their approximate intended positions, with
only one component near each edge.
● Group multiple components in an area into a panel before converting.
Note:BorderLayout ignores the order in which you add components to the container.
By default, a BorderLayout puts no gap between the components it manages. However, you
can use the Inspector to specify the horizontal or vertical gap in pixels for a BorderLayout
associated with a container.
To modify the gap surrounding BorderLayout components, select the BorderLayout object in
the Structure window (displayed immediately below the container it controls), then modify the
pixel value in the Property Inspector for the hgap and vgap properties.
8-31
Related topics
Working with Nested Panels and Layouts.
8-32
About BoxLayout2
BoxLayout2 allows you to arranges a container's components either vertically or horizontally.
By nesting components in containers, you can achieve complex layouts. The following graphic
shows three panels (P1, P2, P3) arranged vertically. Each panel contains two buttons arranged
vertically.
When you use BoxLayout2 for a component, you specify whether its major axis is the Y axis
(top placement) or X axis (left to right placement). Components are arranged from left to right
(or top to bottom), in the same order as they were added to the container.
BoxLayout2 attempts to arrange components at their preferred widths (for left to right layout) or
heights (for top to bottom layout). The components will not wrap if the container is resized.
If all the components are not the same height in a horizontal layout, BoxLayout2 attempts to
make all the components as high as the highest component. If that's not possible for a
particular component, then BoxLayout2 aligns that component vertically, according to the
component's Y alignment.
If the components are not all the same width in a vertical alignment, BoxLayout2 attempts to
make all components in the column as wide as the widest component; if that fails, it aligns them
horizontally according to their X alignments.
8-33
About CardLayout
CardLayout places components (usually panels) on top of each other in a stack like a deck of
cards. You see only one at a time, and you can flip through the panels by using another control
to select which panel comes to the top.
CardLayout is a good layout to use when you have an area that can contain different
components at different times. This gives you a way to manage two or more panels that need
to share the same display space.
An example of using CardLayout can be seen by looking at the wizards in JDeveloper. The
Cancel, Next, and Back buttons control which panel is displayed next.
To create a CardLayout container:
1. Create a new Application.

2. Right-click the frame file in the Navigator and choose UI Editor.
3. Add a panel to your UI in the UI Editor and set its layout property to CardLayout.
4. Drop a new panel into the CardLayout panel. This new panel will completely fill up the
CardLayout panel.
Note:The first component you add to a CardLayout panel will always fill the panel.
5. Set the layout property for this new panel to XYLayout and add the desired components.
6. Click a panel on the Component Palette, then click on the CardLayout panel in the
component tree in the Structure window to add it to the stack in CardLayout panel.
7. Set this second panel to XYlayout and add components to it.
8. Repeat steps 6 and 7 for each new panel you want to add to the stack.
Specifying the Gap Surrounding a CardLayout Container
Using the Structure window, you can specify the amount of horizontal and vertical gap
surrounding a stack of components in a CardLayout.
To specify the horizontal and vertical gap in a CardLayout:
1. Select the cardLayout object in the Structure window, displayed immediately below the
container it controls.
8-34
2. Click the hgap (horizontal gap) or vgap (vertical gap) property in the Inspector.
3. Enter the number of pixels you want for the gap.
4. Press Enter or click anywhere else in the Inspector to register the changes.
8-35
About FlowLayout
FlowLayout arranges components in rows from left to right, and then top to bottom using each
component's preferredSize. FlowLayout lines up as many components as it can in a row, then
moves to a new row. Typically, FlowLayout is used to arrange buttons on a panel.
Note: If you want a panel that arranges the components vertically, rather than horizontally, see
VerticalFlowLayout.
You can choose how to arrange the components in the rows of a FlowLayout container by
specifying an alignment justification of left, right, or center. You can also specify the amount of
gap (horizontal and vertical spacing) between components and rows. Use the Inspector to
change both the alignment and gap properties when you're in the UI Editor.
Alignment
● LEFT- groups the components at the left edge of the container.
● CENTER - centers the components in the container.
● RIGHT groups the components at the right edge of the container.
The default alignment in a FlowLayout is CENTER.
8-36
To change the alignment, select the FlowLayout object in the Structure window, then
specify a value in the Property Inspector for the alignment property as follows:
0=LEFT
1=CENTER
2=RIGHT
Gap
The default gap between components in a FlowLayout is 5 pixels.
To change the horizontal or vertical gap, select the FlowLayout object in the Structure window,
then modify the pixel value of the hgap (horizontal gap) or vgap (vertical gap) property in the
Inspector.
Order of Components
To change the order of the components in a FlowLayout container, drag the component to the
new location, or right-click a component and choose Move to First or Move to Last.
8-37
About GridBagLayout
GridBagLayout is an extremely flexible and powerful layout that provides more control than
GridLayout in laying out components in a grid. GridBagLayout positions components
horizontally and vertically on a dynamic rectangular grid. The components do not have to be
the same size, and they can fill up more than one cell.
GridBagLayout determines the placement of its components based on each component's

constraints and minimum size, plus the container's preferred size.
In the following discussion,
● A component's cell refers to the entire set of grid cells the component occupies.
● A component's display area refers to all the space of the cell that it occupies which is not
taken up by the component's external padding (insets).
While GridBagLayout can accommodate a complex grid, it will behave more successfully (and
more predictably) if you organize your components into smaller panels, nested inside the
GridBagLayout container. These nested panels can use other layouts, and can contain
additional panels of components if necessary. This method has two advantages:
● It gives you more precise control over the placement and size of individual components
because you can use more appropriate layouts for specific areas, such as button bars.
● It uses fewer cells, simplifying the GridBagLayout and making it much easier to control.
8-38
On the other hand, GridBagLayout requires more containers, and therefore your program uses
more memory, than if you used other layout managers.
About GridBagConstraints
GridBagLayout uses a GridBagConstraints object to specify the layout information for each
component in a GridBagLayout container. Since there is a one-to-one relationship between
each component and GridBagConstraints object, you need to customize the
GridBagConstraints object for each of the container's components.
GridBagLayout components have the following constraints:
● anchor
● fill
● gridx, gridy
● gridwidth, gridheight
● insets
● ipadx, ipady
● weightx, weighty
GridBagConstraints give you control over,
● The position of each component, absolute or relative.

● The size of each component, absolute or relative.
● The number of cells each component spans.
● How each cell's unused display area gets filled.
● The amount of internal and external padding for each component.
● How much weight is assigned to each component to control which components utilize
extra available space. This controls the component's behavior when resizing the
container.
For a detailed explanation of each of the constraints, including tips for using them and setting
them in the UI Editor, see the individual constraint topics below.
Setting GridBagConstraints Manually in the Source Code

8-39
When you use the UI Editor to design a GridBagLayout container, JDeveloper always creates a
new GridBagConstraints2 object for each component you add to the container.
GridBagConstraints is derived from GridBagConstraints, and has a constructor that takes all
eleven properties of GridBagConstraints so the code generated by the UI Editor can be simpler.
For example,
bevelPanel1.add(textFieldControl3, new GridBagConstraints2(0, 5, 6, 2, 1.0, 0.0,

GridBagConstraints.WEST, GridBagConstraints.HORIZONTAL, new Insets(0, 24, 0, 0), 150,
0));
bevelPanel1.add(checkboxControl1, new GridBagConstraints2(7, 5, 4, 1, 0.0, 0.0,
GridBagConstraints.CENTER, GridBagConstraints.NONE, new Insets(8, 29, 0, 24), 18, -11));
You can modify the parameters of the GridBagConstraints2 constructor directly in the source
code, or you can use the Constraints property editor to change the values.
When you create a GridBagLayout container by coding it manually, you only need to create one
GridBagConstraints object for each GridBagLayout container. GridBagLayout uses the
GridBagConstraints default values for the component you add to the container, or it reuses the
most recently modified value. If you want the component you're adding to the container to have
a different value for a particular constraint, then you only need to specify the new constraint
value for that component. This new value will stay in effect for subsequent components unless,
or until, you change it again.
Note:While this method of coding GridBagLayout is the leanest (recycling constraint values from
previously added components), it doesn't allow you to edit that container visually in the UI Editor.
Modifying Existing GridBagLayout Code to Work in the UI Editor
If you have a GridBagLayout container that was previously coded manually by using one
GridBagConstraints object for the container, you will not be able to edit that container in the UI
Editor without making the following modifications to the code:
● You must create a GridBagConstraints2 object for each component added to the
container.
● The GridBagConstraints2 object must have a large constructor with parameters for each
of the eleven constraint values, as shown above.
Designing GridBagLayout Visually in the UI Editor
8-40
GridBagLayout is a complex but useful layout manager. JDeveloper has additional features in
the UI Editor that make GridBagLayout much easier to design and control, such as a
Constraints property editor, a grid, and a pop-up menu on selected components.
There are two approaches you can take to designing GridBagLayout in the UI Editor. You can
design it from scratch by adding components to a GridBagLayout panel, or you can prototype
the panel in the UI Editor using another layout first, such as XYLayout, then convert it to
GridBagLayout when you have all the components arranged and sized the way you want them.
This method can speed up your design work substantially.
Whichever method you use, it is recommended that you take advantage of using nested panels
to group the components, building them from the inside out. Use these panels to define the
major areas of the GridBagLayout container to simplify your GridBagLayout design, which gives
you fewer cells in the grid and fewer components that need GridBagConstraints.
Converting to GridBagLayout
When you prototype your layout in another layout first, the conversion to GridBagLayout will be
much cleaner and easier if you are careful about the alignment of the panels and components
as you initially place them, especially left and top alignment. Keep in mind that you are actually
designing a grid, so try to place the components inside an imaginary grid, and use nested
panels to keep the number of rows and columns as small as possible. Using XYLayout for
prototyping gives you the advantage of component alignment functions on the components'
popup menu (accessed by right-clicking a component in the UI Editor).
As the UI Editor converts the design to GridBagLayout, it assigns constraint values for the
components based on where the components were before you changed the container to
GridBagLayout. Often, only minor adjustments are necessary, if any.
Converting to GridBagLayout assigns weight constraints to certain types of components (those

which you would normally expect to increase in size as the container is enlarged at runtime,
such as text areas, fields, group boxes, or lists). If you need to make adjustments to your
design after converting to GridBagLayout, you'll find the task much easier if you remove all the
weight constraints from any components first (set them all to zero).
If even one component has a weight constraint value greater than zero, it is hard to predict the
sizing behavior in the UI Editor due to the complex interactions between all the components in
the container.
You can easily spot a GridBagLayout whose components have weights because the
components will not be clustered together in the center of the container. Instead, the
components fill the container to its edges.
8-41
Tip: When you remove all the weights from the components in a GridBagLayout, one of two things
will happen:
● If the container is large enough for the grid, the components will all cluster together in the
center of the container, with any extra space around the edges of the grid.
● If the container is too small for the components, the grid will expand beyond the edges of
the container and the components that are off the edges of the container will be invisible.
Enlarge the size of the container until all the components fit. If the GridBagLayout
container you are designing is a single panel in the center of the main UI frame, enlarge
the size of the frame. You can resize this container to the final size after you have
finished setting all the components' constraints.
For more information on how to use weights and how they cause components to interact with
each other, see the following topic on weight constraints.
Adding Components to a GridBagLayout Container
If you want to create your GridBagLayout by starting out with a new GridBagLayout container
and adding all the components to it from scratch, there are certain behaviors you should
expect.
● Since the default weight constraint for all components is zero, when you add the first
component to the container, it will locate to the center of the container at its
minimumSize. You will now have a grid with one row and one column.
● The next component you add will be placed in an adjacent cell, depending on where you
click. If you click under the first component, it will go on the next row in that column. If
you click to the right of the component, it will go on the same row in the next column. All
subsequent components are added the same way, increasing the number of cells by one
as you add each one.
● Once you have several components, or cells containing components, you can use the
mouse to drag the components to new cell locations, or you can change the gridx and
gridy constraints in the Constraints property editor.
● No matter how many components you add, as long as the grid stays smaller than the
container, they will all cluster together in the middle of the container. If you need a bigger
container, simply enlarge it in the UI Editor.
● If after several rows, your design has been fitting nicely into a certain number of columns,
then you suddenly have a row that requires an odd number of components, consider
dropping a panel into that row that takes up the entire row, and use a different layout
inside that panel to achieve the look you want.
8-42
Setting GridBagConstraints in the Constraints Property Editor
By using the GridBagLayout Constraints property editor, some of the GridBagConstraints can
be specified in the UI Editor without having to edit the source code.
One big advantage to using the Constraints property editor for setting constraints is the ability
to change constraints for multiple components at the same time. For example, if you want all
the buttons in your GridBagLayout container to use the same internal padding, you can hold
down the Shift key while you select each one, then open the Constraints property editor and
edit the constraint.
To use the Constraints property editor:
1. Select the component(s) within the GridBagLayout container you want to modify, either in
the Structure window or in the UI Editor.
2. Select the constraints property in the Property Inspector and click its value field.
8-43
3. Set the desired constraints in the property editor, then press OK.
Displaying the Grid
The UI Editor displays an optional grid that lets you see exactly what is happening with each
cell and component in the layout.
● To display this grid, right-click on a component in the GridBagLayout container and

select Show Grid.
● To hide the grid temporarily when Show Grid is selected, click on a component that is not
in the GridBagLayout container (including the GridBagLayout container itself) and the
grid will disappear. The grid is only visible when a component inside a GridBagLayout
container is selected.
● To hide the grid permanently, right-click a component and select Show Grid again.
Using the Mouse to Change Constraints
The UI Editor allows you to use the mouse for setting some of the constraints by dragging the
whole component or by grabbing various sizing nibs on the component. Directions for setting
constraints visually are included in the individual following constraint topics.
Using the GridBagLayout Popup Menu
Right-clicking a GridBagLayout component displays a popup menu that gives you easy access
to some of the properties of the Constraints property editor, and lets you quickly set or remove
certain constraints.
Action
Menu Command
Show Grid Displays the GridBagLayout grid in the UI Editor.
Remove Padding Sets any size padding values (ipadx and ipady) for the selected component to zero.
Constraints... Displays the Constraints popup editor for the selected GridBagLayout component.
Fill Horizontal Sets (ors) the fill constraint value for the component to HORIZONTAL. The component
expands to fill the cell horizontally. If the fill was VERTICAL, it sets the constraint to BOTH.
Fill Vertical Sets (ors) the fill constraint value for the component to VERTICAL. The component expands
to fill the cell vertically. If the fill was HORIZONTAL, it sets the constraint to BOTH.
8-44
Remove Fill Changes the fill constraint value for the component to NONE.
Weight Horizontal Sets the weightx constraint value for the component to 1.0.
Weight Vertical Sets the weighty constraint value for the component to 1.0
Remove Weights Sets both weighty and weighty constraint values for the component to 0.0.
GridBagConstraints
The following section lists each of the GridBagConstraints separately. It defines each one,
explaining its valid and default values, and tells you how to set that constraint visually in the UI
Editor.
anchor
Description:
When the component is smaller than its display area, use the anchor constraint to tell the
layout manager where to place the component within the area.
The anchor constraint only affects the component within its own display area, depending
on the fill constraint for the component. For example, if the fill constraint value for a
component is GridBagConstraints.BOTH (fill the display area both horizontally and
vertically), the anchor constraint has no effect because the component takes up the
entire available area. For the anchor constraint to have an effect, set the fill constraint
value to GridBagConstraints.NONE, GridBagConstraints.HORIZONTAL, or
GridBagConstraints.VERTICAL
Valid values:
GridBagConstraints.CENTER
GridBagConstraints.NORTH
GridBagConstraints.NORTHEAST
GridBagConstraints.EAST
GridBagConstraints.SOUTHEAST
GridBagConstraints.SOUTH
GridBagConstraints.SOUTHWEST
GridBagConstraints.WEST
GridBagConstraints.NORTHWEST
Default value:
GridBagConstraints.CENTER
8-45
Setting the anchor constraint in the UI Editor:
You can use the mouse to set the anchor for a component that is smaller than its cell.
Simply click on the component and drag it, dragging the component toward the desired
location at the edge of its display area, much like you would dock a movable toolbar. For
example, to anchor a button to the upper left corner of the cell, click the mouse in the
middle of the button, and drag it until the upper left corner of the button touches the
upper left corner of the cell. This sets the anchor constraint value to NorthWest.
You can also specify the anchor constraint in the Constraints property editor:
1. Select the component in the UI Editor.

2. In the Property Inspector click the constraints property to display the Constraints
editor.
3. Select the desired anchor constraint value in the Anchor area, then press OK.
fill
Description:
When the component's display area is larger than the component's requested size, use
the fill constraint to tell the layout manager which parts of the display area should be
given to the component. As with the anchor constraint, the fill constraint only affects the
component within its own display area. Fill tells the layout manager to expand the
component to fill the whole area it has been given.
Valid values:
GridBagConstraints.NONE
(Don't change the size of the component.)
GridBagConstraints.BOTH
(Resize the component both horizontally and vertically to fill the area completely.)
8-46
GridBagConstraints.HORIZONTAL
(Only resize the component to fill the area horizontally.)
GridBagConstraints.VERTICAL
(Only resize the component to fill the area vertically.)
Default value:
GridBagConstraints.NONE
Specifying the fill constraint in the UI Editor:
The fastest way to specify the fill constraint for a component is to use the component's
popup menu in the UI Editor.
1. Right-click the component in the UI Editor to display the popup menu.

2. Do one of the following:
■ Select Fill Horizontal to set the value to HORIZONTAL
■ Select Fill Vertical to set the value to VERTICAL.

■ Select both Fill Horizontal and Fill Vertical to set the value to BOTH.
■ Select Remove Fill to set the value to NONE.
You can also specify the fill constraint in the Constraints editor.
editor.
2. Select the desired fill constraint value in the Fill area, then press OK.
gridwidth, gridheight
8-47
Description:
Use these constraints to specify the number of cells in a row (gridwidth) or column
(gridheight) the component uses. This constraint value is stated in cell numbers, not in
pixels.
Valid values:
gridwidth=nn, gridheight=nn
(Where nn is an integer representing the number of cell columns or rows.)
GridBagConstraints.RELATIVE (-1)
Specifies that this component is the next to last one in the row (gridwidth) or column
(gridheight.) A component with a GridBagConstraints.RELATIVE takes all the remaining
cells except the last one. For example, in a row of six columns, if the component starts in
the third column, a gridwidth of RELATIVE will make it take up columns three, four, and
five.
GridBagConstraints.REMAINDER (0)
Specifies that this component is the last one in the row (gridwidth) or column (gridheight).
Default value:
gridwidth=1, gridheight=1
Specifying gridwidth and gridheight constraints in the UI Editor:
You can specify gridwidth and gridheight constraint values in the Constraints property
editor.
8-48
editor.
2. In the Grid Position area, enter a value for gridwidth in the Width field, or a value
for gridheight in the Height field. Specify the number of cells the component will
occupy in the row or column.
■ If you want the value to be RELATIVE, enter a -1.
■ If you want the value to be REMAINDER, enter a 0.
You can use the mouse to change the gridwidth or gridheight by sizing the component
into adjacent empty cells.
gridx, gridy
Description:
Use these constraints to specify the grid cell location for the upper left corner of the
component. For example, gridx=0 is the first column on the left, and gridy=0 is the first
row at the top. Therefore, a component with the constraints gridx=0 and gridy=0 is
placed in the first cell of the grid (top left).
GridBagConstraints.RELATIVE specifies that the component be placed relative to the

previous component as follows:
❍ When used with gridx, it specifies that this component be placed immediately to
the right of the last component added.
❍ When used with gridy, it specifies that this component be placed immediately
below the last component added.
Valid values:
gridx=nn, gridy=nn
GridBagConstraints.RELATIVE (-1)
Default value:
8-49
gridx=0, gridy=0
Specifying the grid cell location in the UI Editor
You can use the mouse to specify which cell the upper left corner of the component will
occupy. Click near the upper left corner of the component and drag it into a new cell.
When moving components that take up more than one cell, be sure to click in the upper
left cell when you grab the component. Sometimes, due to existing values of other
constraints for the component, moving the component to a new cell with the mouse may
cause changes in other constraint values, for example, the number of cells that the
component occupies might change. To more precisely specify the gridx and gridy
constraint values without accidently changing other constraints, use the Constraints
property editor.
editor.
2. In the Grid Position area, enter the column number for gridx value in the X field, or
the row number for gridy value in the Y field. If you want the value to be
RELATIVE, enter a -1.
Important: When you use the mouse to move a component to an occupied cell, the UI
Editor ensures that two components never overlap by inserting a new row and column of
cells so the components will not be on top of each other. When you relocate the
component using the Constraints property editor, the UI Editor does not check to make
sure the components don't overlap.
insets
Description:
Use insets to specify the minimum amount of external space (padding) in pixels between
the component and the edges of its display area. The inset says that there must always
be the specified gap between the edge of the component and the corresponding edge of
the cell. Therefore, insets work like brakes on the component to keep it away from the
edges of the cell. For example, if you increase the width of a component with left and
right insets to be wider than its cell, the cell will expand to accommodate the component
8-50
plus its insets. fill and padding constraints never steal any space from insets.
Valid values:
insets = new Insets(n,n,n,n)
Top, left, bottom, right (where each parameter represents the number of pixels between
the display area and one edge of the cell.)
Default values:
insets = new Insets(0,0,0,0)
Setting inset values in the UI Editor:
The UI Editor displays blue sizing nibs on a selected GridBagLayout component to

indicate the location and size of its insets. Grab a blue nib (sizing handle) with the mouse
and drag it to increase or decrease the size of the inset.
❍ When an inset value is zero, you will only see one blue nib on that side of the cell.
When an inset value is greater than zero, the UI Editor displays a pair of blue nibs
for that inset: one on the edge of the cell and one on the edge of the display area.
The size of the inset is the distance (number of pixels) between the two nibs. Grab
either nib to change the size of the inset.
8-51
For more precise control over the inset values, use the Constraints property editor to
specify the exact number of pixels.
editor.
2. In the External Insets area, specify the number of pixels for each inset: top, left,
bottom, or right.
Note that while negative inset values are legal, they can cause components to overlap
adjacent components, and are not recommended.
ipadx, ipady
Description:
These constraints specify the internal padding for a component. Use ipadx and ipady to
specify the amount of space (in pixels) to add to the minimum size of the component for
internal padding. For example, the width of the component will be at least its minimum
width plus ipadx in pixels. The code only adds it once, splitting it evenly between both
sides of the component. Similarly, the height of the component will be at least the
minimum height plus ipady pixels.
❍ ipadx specifies the number of pixels to add to the minimum width of the
component.
8-52
❍ ipady specifies the number of pixels to add to the minimum height of the
component.
Example:
When added to a component that has a preferred size of 30 pixels wide and 20 pixels
high:
❍ If ipadx= 4, the component will be 34 pixels wide.

❍ If ipadx= 2, the component will be 22 pixels high.
Valid values:
ipadx=nn, ipadx=nn
Default value:
ipadx=0, ipady=0
Setting the size of internal padding constraints in the UI Editor:
You can specify the size of a component's internal padding by clicking on any of the
black sizing nibs at the edges of the component, and dragging with the mouse.
❍ If you drag the sizing nib beyond the edge of the cell into an empty adjacent cell,
the component will occupy both cells (the gridwidth or gridheight values will
increase by one cell).
Before:
8-53
After:
For more precise control over the padding values, use the Constraints property editor to
specify the exact number of pixels to use for the value.
editor.
2. Enter the number of pixels for the Width and Height values in the Size Padding
area, then press OK.
To quickly remove the padding (set it to zero), right-click the component in the UI Editor
and choose Remove Padding. You can also select multiple components and use the
same procedure to remove the padding from all of them at once.
8-54
Negative values are valid. They will make the component smaller than its preferred size.
Note: Padding, much like XYLayout, may not be accurate on different computer systems
or in different languages.
weightx, weighty
Description:
Use the weight constraints to specify how to distribute a GridBagLayout container's extra
space horizontally (weightx) and vertically (weighty) when the container is resized.
Weights determine what share of the extra space gets allocated to each cell and
component when the container is enlarged beyond its default size.
Weight values are of type double and are specified numerically in the range 0.0 to 1.0
inclusive. Zero means the component should not receive any of the extra space, and 1.0
means the component gets a full share of the space.
❍ The weight of a row is calculated to be the maximum weightx of all the

components in the row.
❍ The weight of a column is calculated to be the maximum weighty of all the
components in the column.
Valid values:
weightx=n.n, weighty=n.n
Default value:
weightx=0.0, weighty=0.0
To set weightx and weighty constraints in the UI Editor:
To specify the weight constraints for a component in the UI Editor, right-click the
component and choose Weight Horizontal (weightx), or Weight Vertical (weighty). This
sets the value to 1.0. To remove the weights (set them to zero), right-click the component
and choose Remove Weights. You can do this for multiple components: hold down the
8-55
Shift key when selecting the components, then right-click and choose the appropriate
menu item.
If you want to set the weight constraints to something other than 0.0 or 1.0, you can set
the values in the Constraints editor.
editor.
2. Enter a value between 0.0 and 1.0 for the X (weightx) or Y (weighty) value in the
Weight area, then press OK.
Important: Because weight constraints can make the sizing behavior in the UI Editor
difficult to predict, setting these constraints should be the last step in designing a
GridBagLayout.
Examples of how Weight Constraints Affect Components' behavior
❍ If all the components have weight constraints of zero in a single direction, the
components will clump together in the center of the container for that dimension
and won't expand beyond their preferred size. GridBagLayout puts any extra
space between its grid of cells and the edges of the container.
❍ If you have three components with weightx constraints of 0.0, 0.3, and 0.2
respectively, when the container is enlarged, none of the extra space will go to the
first component, 3/5 of it will go the second component, and 2/5 of it will go to the
third.
8-56
❍ You need to set both the weight and fill constraints for a component if you want it
to grow. For example, if a component has a weightx constraint, but no horizontal
fill constraint, then the extra space goes to the padding between the left and right
edges of the component and the edges of the cell. It enlarges the width of the cell
without changing the size of the component. If a component has both weight and
fill constraints, then the extra space is added to the cell, plus the component
expands to fill the new cell dimension in the direction of the fill constraint
(horizontal in this case).
The three pictures below demonstrate this.
In the first example, all the components in the GridBagLayout panel have a weight
constraint value of zero. Because of this constraint, the components are clustered
in the center of the GridBagLayout panel, with all the extra space in the panel
distributed between the outside edges of the grid and the panel. The size of the
grid is determined by the preferred size of the components, plus any insets and
padding (ipadx or ipady).
8-57
Next, a horizontal weight constraint of 1.0 is specified for the ListControl. Notice
that as soon as one component is assigned any weight, the UI design is no longer
centered in the panel. Since a horizontal weight constraint was used, the
GridBagLayout manager takes the extra space in the panel that was previously on
each side of the grid, and puts it into the cell containing the ListControl. Also notice
that the ListControl did not change size.
Tip: If there is more space than you like inside the cells after adding weight to the
components, decrease the size of the UI frame until the amount of extra space is what
you want. To decrease the size of the frame, select the frame in the UI Editor or the
Structure window, this(BorderLayout), then click its black sizing nibs and drag the
frame to the desired size.
Finally, if a horizontal fill is then added to the ListControl, the component expands
to fill the new horizontal dimension of the cell.
8-58
❍ If one component in a column has a weightx value, GridBagLayout gives the
whole column that weight. Conversely, if one component in a row has a weighty
value, the whole row is assigned that weight.
For additional information on GridBagLayout and GridBagConstraints, see GridBagLayout and

GridBagConstraints in the J2SE (Java 2, Standard Edition) documentation.
8-59
About GridLayout
GridLayout places components in a grid of cells that are in rows and columns. GridLayout
expands each component to fill the available space within its cell. Each cell is exactly the same
size and the grid is uniform. When you resize a GridLayout container, GridLayout changes the
cell size so the cells are as large as possible, given the space available to the container.
Use GridLayout if you are designing a container where you want the components to be of equal
size, for example, a number pad or a toolbar.
You can specify the number of columns and rows in the grid, but only one of the rows or
columns can be zero. You must have a value in at least one so the GridLayout manager can
calculate the other.
For example, if you specify four columns and zero rows for a grid that has 15 components,
GridLayout creates four columns of four rows, with the last row containing three components.
Or, if you specify three rows and zero columns, GridLayout creates three rows with five full
columns.
In addition to number of rows and columns, you can specify the number of pixels between the
cells by modifying the horizontal gap (hgap) and vertical gap (vgap) properties. The default
horizontal and vertical gap is zero.
To change the property values for a GridLayout container, select the GridLayout object in the
Structure window, then edit the values for the rows, cols, hgap, or vgap properties in the
Property Inspector.
8-60
8-61
About OverlayLayout2
OverlayLayout2 arranges components over the top of each other. The requested size of the
container will be the largest requested size of the children, taking alignment needs into
consideration. The alignment is based upon what is needed to properly fit the children in the
allocation area. The children will be placed such that their alignment points are all on top of
each other. Unlike BorderLayout's centering, OverlayLayout2 does not expand the component
to fill the available space, but instead leaves it at is preferred size.
8-62
About PaneLayout
PaneLayout allows you to specify the size of a component in relation to its sibling components.
PaneLayout applied to a panel or frame lets you control the percentage of the container the
components will have relative to each other, but does not create moveable splitter bars
between the panes.
In a PaneLayout, the placement and size of each component is specified relative to the
components that have already been added to the container. Each component specifies a
PaneConstraints object that tells the layout manager from which component to take space, and
how much of its existing space to take. Each component's PaneConstraints object is applied to
the container as it existed at the time the component was added to the container. The order in
which you add the components to the container is very important.
PaneConstraint Variables
The constraint for a PaneConstraints component that is being added to a container consists of
four variables:
String name
The name for this component (must be unique for all components in the container - as in
CardLayout).
8-63
String splitComponentName
The name of the component from which space will be taken to make room for this
component.
String position
The edge of the splitComponentName to which this component will be anchored.
Valid values are:
Select this To do this

PaneConstraints.TOP This component will be above splitComponentName.
PaneConstraints.BOTTOM This component will be below splitComponentName.
PaneConstraints.RIGHT This component will be to the right of splitComponentName.
PaneConstraints.LEFT This component will be to the left of splitComponentName.
PaneConstraints.ROOT This component is the first component added.
float proportion
The proportion of splitComponentName that will be allocated to this component. A

number between 0 and 1.
How Components are Added to PaneLayout
● The first component will always take all the area of the container. The only important
variable in its PaneConstraint is its name. Other components will use this value,
specifying it as their splitComponentName.
8-64
● The second component must specify its splitComponentName as the name of the first
component.
● The splitComponentName of subsequent components may be the name of any

component that has already been added to the container.
Creating a PaneLayout Container in the UI Editor
1. Add a container to your UI in the UI Editor. This can be any kind of a frame or panel.
2. Change the container's layout property to PaneLayout. This allows you to access the
PaneLayout properties in the Inspector.
3. From the Component Palette, select the first component and drop it into the PaneLayout
container. This component will completely fill the container until you add another
component.
8-65
4. Select the second component and drag it to the desired size in the desired position.
Important: If the first component you added to a PaneLayout container was itself a container,
the UI Editor assumes you are trying to add the second component to the outer container
instead of to the PaneLayout container. Use the component tree to specify to the containers
8-66
that you want the component to be placed in.
5. To add a third component to the PaneLayout, draw it similarly to define its position
relative to the other components.
For example, to split the right half of the container, begin drawing the third component
starting from the middle of the right edge of the panel to the bottom right corner of the
first component.
6. Use the same method to add subsequent components.
8-67
About VerticalFlowLayout
VerticalFlowLayout arranges components in columns from top to bottom, then left to right using
each component's preferredSize. VerticalFlowLayout lines up as many components as it can in
a column, then moves to a new column. Typically, VerticalFlowLayout is used to arrange
buttons on a panel.
You can choose how to arrange the components in the columns of a VerticalFlowLayout
container by specifying an alignment justification of top, middle, or bottom. You can also specify
the amount of gap (horizontal and vertical spacing) between components and columns. It also
has properties that let you specify the components should fill the width of the column, or the last
component should fill the remaining height of the container. Use the Inspector to change these
properties when you're in the UI Editor.
Alignment
● TOP - groups the components at the top of the container.
● MIDDLE - centers the components vertically in the container.
● BOTTOM - groups the components so the last component is at the bottom of the
container.
The default alignment in a VerticalFlowLayout is MIDDLE.
To change the alignment, select the verticalFlowLayout object in the Structure window, then
specify a value in the Inspector for the alignment property as follows:
0=TOP
1=MIDDLE
8-68
2=BOTTOM
Gap
The default gap between components in a VerticalFlowLayout is 5 pixels.
To change the horizontal or vertical gap, select the VerticalFlowLayout object in the Structure
window, then modify the pixel value of the hgap (horizontal gap) or vgap (vertical gap) property
in the Inspector.
Order of Components
To change the order of the components in a VerticalFlowLayout container, drag the component
to the new location.
Horizontal Fill
horizontalFill lets you specify a fill to edge flag which causes all the components to expand to
the container's width.
Warning: Your program can become unstable if the main panel has less space than it needs. This
property also prohibits multi-column output.
The default value for horizontalFill is True.
8-69
Vertical fill
verticalFill lets you specify a vertical fill flag that causes the last component to fill the remaining
height of the container.
The default value for verticalFill is False.
8-70
About XYLayout
XYLayout is a JDeveloper custom layout manager. XYLayout puts components in a container
at specific (x,y) coordinates relative to the upper left corner of the container. Regardless of the
type of display, the container will always retain the relative (x,y) positions of components.
However, when you resize a container with an XYLayout, the components do not reposition or
resize.
You'll discover that XYLayout is very convenient to use in prototyping a user interface. When
you design more complicated user interfaces with multiple nested panels, XYLayout can be
used for the initial layout of the panels and components, after which you can choose from one
of the standard layouts for the final design.
Note: XYLayout uses absolute x,y values when positioning objects on the screen, and does not
adjust to different screen resolutions. To ensure your layout adjusts to other resolutions, don't leave
any containers in XYLayout in your final design.
You can use the UI design tools to specify the container's size and its components' x,y
coordinates.
● To specify the size of a container using XYLayout, select the XYLayout object in the
Structure window and enter the pixel dimension for the height and width properties in the
Property Inspector. This setting specifies the size of the XYLayout container.
● To change the (x,y) values for a container using XYLayout, do one of the following:
❍ In the UI Editor, drag the component to a new size. JDeveloper automatically
8-71
updates the constraint values in the Property Inspector.
❍ Select the component in the Structure window, then click the constraints property
edit field and enter coordinates for that component.
Alignment Options for XYLayout
The following table explains the alignment options available from the popup menu:
Select this To do this

Move to first Moves the selected component to the top of the Z-order.
Move to last Moves the selected component to the bottom of the Z-order.
Align Left Lines up the left edges of the selected components with the left edge of the first
selected component.
Align Center Horizontally lines up the centers of the selected components with the center of the
first selected component.
Align Right Lines up the right edges of the selected components with the right edge of the first
selected component.
Align Top Lines up the top edges of the selected components with the top edge of the first
selected component.
Align Middle Vertically lines up the centers of the selected components with the middle of the first
selected component.
Align Bottom Lines up the bottom edges of the selected components with the bottom edge of the
first selected component.
Even Space Horizontal Evenly spaces the selected components horizontally between the first and last
selected components.
Even Space Vertical Evenly spaces the selected components vertically between the first and last selected
components.
Same Size Horizontal Makes all the selected components the same width as the first selected component.
8-72
Same Size Vertical Makes all the selected components the same height as the first selected component.
Related Topics
Layouts Provided with JDeveloper

Selecting a Final Layout Manager
Choosing Layout Manager Properties
8-73
Each container normally has some kind of layout manager attached to its layout property. The
layout manager has properties that can affect the sizing and location of all components that are
added to the container. You can view and edit these properties in the Inspector when the layout
manager is selected in the Structure window. The layout manager displays as an item in the
Structure window just below the container to which it is attached.
8-74
For each component you add to a container, JDeveloper may instantiate a constraints object,
or produce a constraint value, which provides additional information about how the layout
manager should size and locate this specific component. The type of constraint object or value
created depends upon the type of layout manager being used. The Inspector displays the
constraints of each component as if they were properties of the component itself, and allows
you to edit them.
Related Topics

Prototyping Your UI with Layout Properties
Laying Out Your UI
8-75
Determining the Size and Location of your UI
Window at Runtime
If your UI class is a Frame or Dialog, you can control its size and location at runtime. The size
and location are determined by what the code does when the UI window is created and what
the user does to resize or reposition it.
When the UI window is created, and various components are added to it, each component that
is added affects the preferredSize of the overall window, typically making the preferredSize of
the window container larger as additional components are added. This effect on preferredSize
depends on the layout manager of the outer container, as well as any nested container layouts.
For more details about the way that preferredLayoutSize is calculated for various layouts, see
the sections in this document on each type of layout.
The size of the UI window, as set by your program (before any additional resizing that may be
done by the user), is determined by which of the following container methods is called last in
the code:
● pack()
● setSize()
The location of your UI at runtime will be at 0,0 unless you override this by setting the location
property of the container (for example by calling setLocation() before making it visible).
Sizing a Window Automatically with pack()
The pack() method computes a window's preferredSize, based upon the components it
contains, and sizes itself accordingly. pack() creates the smallest possible window, while still
respecting the preferredSize of the components that are placed within it.
Note: The Application.java file created by the New Application dialog calls pack(), packing the frame
to its preferredSize before making it visible.
How the preferredSize is Calculated for a Container
preferredSize is calculated differently for containers with different layouts.
Portable Layouts
8-76
Portable layouts, such as FlowLayout and BorderLayout, calculate their preferredSize based on
a combination of the layout rules and the preferredSize of each component that was added to
the container. If any of the components are containers (such as a Panel), then the
preferredSize of that Panel is calculated according to its layout and components. The layout
calculation is recursed into as many layers of nested containers as necessary. For more
information about preferredSize calculation for particular layouts, see the individual layout
descriptions.
XYLayout
For XYLayout containers, the preferredSize of the container is defined by the values specified
in the width and height properties of the XYLayout. For example, if you have the following lines
of code in your container initialization,
xYLayoutN.setWidth(400);
xYLayoutN.setHeight(300);
and if xYLayoutN is the layout manager for the container, then its preferredSize is 400 x 300
pixels.
If one of the nested panels in your UI uses XYLayout, that panel's preferredSize will be
determined by the layout's setWidth() and setHeight() calls. This value will be used for the panel
in computing the preferredSize of the next (outer) container.
Explicitly Setting the Size of a Window Using setSize()
If you call setSize() on the container (rather than pack() or subsequent to calling pack()), the
size of the container will be set to a specific size, in pixels. setSize() overrides the effect of
pack() and preferredSize for the container.
Important: Because different screens have different pixel sizes, if you use setSize() you must call
validate() in order for child containers to be properly laid out. Note that pack() automatically calls
validate().
Making the Size of your UI Portable to Various Platforms
To make your UI portable, either use pack() or calculate an appropriate size to use with
setSize( ) based on the pixel sizes of the various screens your application will be deployed on.
For example, you might want the UI to appear at 75% of the width and height of the screen. For
the UI to appear at this sizing, you can add the following lines of code to your application class
instead of calling pack():
8-77
Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();
frame.setSize(screenSize.width * 3 / 4, screenSize.height * 3 / 4);
Note: To ensure portability, change all XYLayout containers to a portable layout after prototyping.
Positioning a Window on the Screen
If you don't explicitly position your UI, it will appear in the upper left corner of the screen.
To center the UI on the screen, obtain the width and height of the screen, subtract the width
and height of your UI, divide the difference by two (in order to create equal margins on opposite
sides of the UI), and use these figures for the location of the upper left corner of your UI.
The following code is generated when you select the Center Frame on Screen option in the
New Application dialog, and performs this calculation for you:
//Center the window

Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();
Dimension frameSize = frame.getSize();
if (frameSize.height > screenSize.height)
frameSize.height = screenSize.height;
if (frameSize.width > screenSize.width)
frameSize.width = screenSize.width;
frame.setLocation((screenSize.width- frameSize.width) / 2, (screenSize.height - frameSize.height) /2);
Placing the Sizing and Positioning Method Calls in your Code
The calls to pack(), validate(), setSize(), or setLocation() can be made from inside the UI
container class for example, this.pack(). These calls can also be made from the class that
creates the container, for example, frame.pack(), after invoking the constructor, before
setVisible(). The latter is what the New Application dialog-generated code does; the calls to
pack()or validate(), and setLocation() are placed in the Application class, after the frame is
constructed (after the call to jbInit()).
If you are constructing the UI from various places within your application, and you want it to
come up in the same size and place, place your calls in the constructor of your UI container
class (after the call to jbInit(). If your application instantiates the UI from only one place, such as
in the New Application dialog generated application, put the sizing and positioning code in the
place where the UI is created, in this case the Application class.
8-78
8-79
Choosing Layout Manager Properties
You can change the layout properties for these layout managers in the Property Inspector:
● Border Layout Properties

● GridBag Layout
● Card Layout
● Flow Layout
● Grid Layout
● Overlay Layout2
● Pane Layout
● XYLayout
● Box Layout
● Vertical Flow Layout
8-80
Prototyping Your UI with Layout Properties
Before you start creating your UI, it is useful to sketch your UI design on paper to get an idea of
the general strategy you'll use for placing various panels and components, and for assigning
layouts. You can also prototype your UI directly in the UI Editor. JDeveloper makes this easy by
providing a layout called null which leaves the components where you place them at the size
you create them.
Use null Layout for Prototyping
To make this approach simpler, JDeveloper provides the null layout. When you start a project
using the New Application dialog, JDeveloper generates a UI container class (usually one that
extends Frame or JFrame) that uses null. You can open the frame in the UI Editor and do your
design work directly on the frame.
When you initially add a new panel of any type to the UI Editor, you'll notice that the layout
property in the Inspector says <default layout>, which means that the UI Editor will
automatically use the default layout for that container. However, you may want to change the
layout property to the layout manager you want to use so it is visible in the Structure window
and that component constraints can be modified in the Property Inspector. You cannot edit
layout properties for <default layout>.
Design the Big Regions First
Design the big regions of your UI first, then, using null, work down into finer details within those
regions. Once the design is right, work systematically from the inner regions outward,
converting the panels to more portable layouts such as FlowLayout, BorderLayout, or
GridLayout, making minor adjustments if necessary.
In most cases, you will place a container in your design first, then add components to it. You
can also draw a new container around existing components. However, these components will
not automatically nest into the new panel. After drawing the container, you must move each
component in the container. You may even need to move a component out of the container,
then back in. Check the Structure window to make sure each component nests properly. Each
component inside a container should be indented in the Tree under its container.
Save Before Experimenting
When designing in JDeveloper, expect to work by trial and error, especially when changing the
layouts. Be sure to save your work before experimenting with a layout change.
8-81
You may discover that a particular layout you planned to use doesn't work as you expected.
You may need to reexamine your design process and use a different configuration of
containers, components, and layouts. For this reason, you may want to copy the container file
(for example Frame1.java) to a different name and safe location at critical points so that, when
you need to back up in your work, you don't need to start over completely.
Use JavaBeans
In order to speed up your UI design work in the future, create JavaBean components such as
toolbars, status bars, checkbox groups, or dialog boxes that you can add to the Component
Palette and reuse with no (or only minor) modifications.
Related Topics

Developing a Bean
8-82
Laying Out Your User Interface
This section explains the fundamental tasks you perform as you work with components and
JDeveloper's UI design tools to create a user interface. If you're comfortable using controls in a
graphical user interface environment, much of the material discussed here, such as selecting,
sizing, and deleting components might be familiar to you.
Before you begin actually creating your UI, you may want to Prototype your UI.
Basic Design Tasks
Designing a user interface in JDeveloper requires these tasks:
● Creating containers such as frames, panels, or dialogs. These containers hold specific
types of components.
● Adding and arranging components in the containers. You can add components to a
container and then arrange them using layout managers.
● Setting component properties. You can set properties for each component using the
Property Inspector.
● Attaching event-handling code to a component event. Events are the actions a
component takes when they are triggered by a user or another component.
● Setting container layouts and component constraints. A layout constraint tells the layout
manager how to size and position a component.
Starting Your UI Project
These instructions assume that you have already created a project that includes a designable
container class. If not, you will need to:
1. Create or open a JDeveloper Project.

2. Create an applet or an application.
Opening the UI Editor
Right-click the Java file in the Navigator that you want to modify and choose UI Editor.
The source code is accessible in the Code Editor (right click the file in the Navigator and
8-83
choose Code Editor to view the source code) so you can view and edit your source code in
parallel with designing your UI. Any changes made in the UI Editor or Property Inspector are
immediately reflected in the source code, and vice-versa.
8-84
Selecting a Final Layout Manager
If you've used the null or XYLayout Manager to design your Java program, you'll need to
change the layout manager to one of the standard layout mangers that is supported across
different platforms.
To change the layout manager, see Changing the Layout for a Container.
8-85
Working with Nested Containers and Layouts
Most UI designs in Java use more than one type of layout to get the desired component
positions by nesting multiple panels with different layouts in the main container. You can also
nest panels within other panels to gain more control over the placement of components. By
creating a composite design, and by using the appropriate layout manager for each panel, you
can group and arrange components in a way that is both functional and portable.
For example, the following sketch demonstrates the use of nested panels with different layouts.
The solid gray objects are the buttons and other visible components in the UI which are nested
in various levels of panels.
To create nested panels:
1. Add a panel to the UI design of your application.
2. In the Property Inspector, change the Layout property to null.
When you add a panel to the UI design, it uses FlowLayout. Change the layout to null
8-86
initially because it is the easiest layout to work with during the design process. After you
have all the panels and other components in place in your UI, you will set it to its final
layout.
To locate a specific panel in the UI Editor, you can select the panel in the Structure
window.
3. Place panels within panels to logically group components.
4. Add components to the panels.
❍ Make sure components are fully nested inside their panels. Examine the Structure
window to make sure each component is indented under the correct panel in the
tree outline.
❍ The components will probably be irregular sizes and shapes. Don't worry about
getting it perfect at this point, because when you change the panel layouts, the
layout manager will realign the components.
5. Set the layout property for each panel to the appropriate layout.
❍ Be aware that when you change a layout manager for one panel, the effects may
change again when you change the layout manager for the panel that holds it.
❍ Select the layout object in the Structure window to change its settings.
8-87
Adding Custom Layout Managers
JDeveloper supports the integration of other layout managers with its UI Editor. To get a custom
layout manager to appear in the Inspector's layout property list, make sure that the layout manager
is on the IDEClasspath as defined in JDeveloper\bin\jdeveloper.ini, and add the following line to
JDeveloper\bin\addins.properties:
jdeveloper.uiassistant.<full class name>=oracle.jdeveloper.uidesigner.BasicLayoutAssistant
where <full class name> is the complete classname, including package name, for example:
com.company.layout.MyLayout
If the custom Layout Manager uses a constraint class, additional integration can be performed by
supplying a class implementing java.beans.PropertyEditor for editing the constraint. This property
editor also needs to be in the IDEClasspath and is specified in JDeveloper\bin\addins.properties
as:
jdeveloper.propertyeditor.<full class name for type>=<full class name for editor>
Then, you need to extend BasicLayoutAssistant and override two methods:
public java.beans.PropertyEditor getPropertyEditor() {

//return an instance of the constraints property editor
return new com.mycompany.MyLayoutConstrainteditor();
}
public String getContstraintsType () {

// return the fully qualified constraint class name as a string, for example.
return "com.mycompany.myLayoutConstraintEditor";
}
BasicLayoutAssistant is a minimal implementation of the interface

oracle.jdevimpl.uieditor.LayoutAssistant.
Each LayoutAssistant must be associated with a class that implements this interface for the
LayoutManager to be recognized in JDeveloper (the association is made in the
JDeveloper\bin\addins.propertiess file as described above). There are many other methods in the
interface, but it is beyond the scope of this document to describe how to use the other methods.
8-88
Related Topics
Defining Property Accessors

Creating a Property Editor
8-89
Working with Containers and Components
This section explains how to use JDeveloper to create and arrange these containers:
● JFrame
● JPanel
● JDialogBox
● JTabbedPane
● JMenuBar
● JPopupMenu

Creating Containers Explains how to use JDeveloper to add a frame, panel, dialog box,
or tabbed pane to your project.
Working with Components in a Container Explains how to arrange components inside a container that you
created.
Working with Menus Explains how to use the UI Editor to create menus for your UI.
Related topics
About Containers
About Component Properties in the Inspector
See also
For more information on Swing Containers, go to this java.sun.com web page:
8-90
8-91
About Containers
Containers hold and manage other components. There are two general classes of containers:
● Heavyweight Swing containers, which were written before Swing was introduced, and
include JFrame, JPanel, JDialog, and JApplet.
● Lightweight Swing containers, which don't contain operating system-specific code, and
include, for example, JTabbedPane, JSplitPane, and JScrollPane.
All your UI design work in JDeveloper takes place in containers. Containers are also
components; you interact with them by getting and setting their properties, calling their
methods, and responding to their events as with any other component.
A non-container subclass "composite" can also hold UI components. For example, you can
design the application.java file created by the New Application dialog and drop panels and
dialog boxes into it through the Structure window.
If a container has only non-UI components, it need not be a subclass of Container, and
therefore is not visible at runtime. One example is a DataModule whose purpose is to
instantiate and interconnect a set of data components and make them available to visible UI
components in multiple UI containers.
Windows
A Window is a stand-alone top-level container component with no borders, title bar, or menu
bar. Although a Window could be used to implement a popup window, you normally use a
subclass of Window in your UI such as one of those listed below.
Window Description
Frame A top-level window with a border and a title. A Frame has standard window controls such as a
control menu, buttons to minimize and maximize the window, and controls for resizing the
window. It can also contain a menu bar.
Dialog Box A popup window, similar to a Frame, but it needs a parent. Dialog boxes are used for getting
input from the user or to present warning messages. It can also contain a menu bar. Dialog
boxes are usually intended to be transient, or temporary, and can be one of the following types:
Modal: Prevents user input to any other windows in the application until that dialog box is
dismissed.
Modeless: Lets the user enter information in both the dialog box and the application.
8-92
Panels
A Panel is a simple UI container, without border or caption, used to group other components,
like buttons, checkboxes, and text fields. Panels are embedded within some other UI, such as
in a frame or dialog. They can also be nested within other panels.
Panel Description
Applet A subclass of Panel used to build a program intended to be embedded in an HTML page and run in
an Internet browser or applet viewer. Since Applet is a subclass of Panel, it can contain components,
but does not have a border or caption.
Lightweight Swing Containers
The lightweight Swing containers available from JDeveloper's Component Palette pages
include JMenuBar, JPopupMenu, JSplitPane, JScrollPane, JTabbedPane, JToolbar,
JTextPane, and JEditorPane (these last two appear on the Swing page of the Component
Palette). All are a subclass of JComponent. You can add other containers and components to
these containers, combining components and their containers in various ways to get the
interface you want.
Lightweight Container Description

Menu Bar In JDeveloper you use the Menu Editor to add menus to the menu bar to construct a
menu. When the user selects a JMenu object, its associated JPopupMenu is
displayed, allowing the user to select one of the JMenuItems on it.
Popup Menu A small window which pops up and displays a series of choices, which you create in
JDeveloper using the Menu Editor. A JPopupMenu is used for the menu that
appears when the user selects an item on the menu bar. It is also used for "pull-
right" menu that appears when the selects a menu item that activates it. Finally, a
JPopupMenu can also be used anywhere else you want a menu to appear -- for
example, when the user right-clicks in a specified area.
Split Pane Manages two panes that are separated horizontally or vertically by a divider that can
be repositioned by the user. You can choose which pane to add a component to.
You can specify the components with the properties leftComponent and
rightComponent, or topComponent and bottomComponent. In these properties,
"Left" is equivalent to "Top" and "Right" is equivalent to "Bottom" -- so if you change
the arrangement, your existing code still works. Subsequent adds to the same pane
replace its contents with the new object.
8-93
Scroll Pane Consists of JScrollBars, a JViewport. The JViewPort provides a window, or
"viewport" onto a data source -- for example, a text file. That data source is the
"scrollable client" (or data model) displayed by the JViewport view. The scrollable
client can be any component, but when you drop the component from the
Component Palette, rather than "adding" it to the JScrollPane container, JDeveloper
specifies it as part of the constructor.
Along with its scroll bars and viewport, a JScrollPane can have a column header
and a row header. Each of these is a JViewport object that you specify with
rowHeader and columnHeader properties. The column header viewport
automatically scrolls left and right, tracking the left-right scrolling of the main
viewport. (It never scrolls vertically, however.) The row header acts in a similar
fashion.
To add a border around the main viewport, you can use the viewportBorder
property.
Tabbed Pane Manages multiple panels that completely overlap each other. The user can select a
panel to view by clicking on a "tab" attached to the panel (like the tab on a file
folder). You add tabs in JDeveloper by dropping a JPanel onto the tabbed pane
from the Component Palette. The tabPlacement property lets you position tabs on
the top, bottom, left side, or right side of the container.
Toolbar Provides a component which is useful for displaying commonly used Actions or
controls. It can be dragged out into a separate window by the user (unless the
floatable property is set to false). In order for drag-out to work correctly, it is
recommended that you add JToolBar instances to one of the four 'sides' of a
container whose layout manager is a BorderLayout, and do not add children to any
of the other four 'sides'.
Related topics
Creating Containers
Working with Menus

Prototyping the UI Using Layout Properties
8-94
See also
For more information on Swing containers, go to this java.sun.com web page:
For more information on Swing components, go to this java.sun.com web page:
8-95
About Component Properties in the Property
Inspector
About Properties
A property is a named attribute of a class that can affect its appearance or its behavior. A
property can be:
● Readable: These properties have a "get" method, which enables you to read the
property's value. If it is a Boolean property, it can also use "is" to read the value.
● Writable: These properties have a "set" method, which enables the property's value to be
changed.
● Both readable and writable: These properties have both "get" and "set" methods.
Setting property values
Properties are attributes that define how a component appears and responds at runtime. In
JDeveloper, you set a component's initial properties during design time, and your code can
change those properties at runtime.
The Properties page in the Inspector displays the properties of the selected component(s) and
is where you set the property values at design-time for any component in your design. By
setting properties at design time, you are defining the initial state of a component when the UI
is instantiated at runtime.
Note:To modify the initial property values at runtime, you can put code in the body of the methods or
event handlers which you can create on the Events page of the Property Inspector.
To set a component's properties at design time:
1. Select a component in the UI Editor or in the Structure window.

2. Click the Properties tab of the Property Inspector to give it focus.
3. Scroll until the property you want is visible, then select it with the mouse or the arrow
keys.
4. Enter the value in the right column one of the following ways:
❍ When there is only a text field, you simply type the string value for that property,
for example a text value or a number value, then press Enter.

❍ When the value field is displayed with a down arrow, click the down arrow and
8-96
choose a value from the list, then press Enter.
❍ When the value field has an ellipsis button , click it to display a property editor
for that property, for example, a color or font selector. Set the values in the
property editor, then press OK.
Setting shared properties for multiple components
When more than one component is selected, by default the Property Inspector displays only the
properties they have in common that you can edit. You can control whether or not to show
properties that are not common between all selected objects by pressing the Union button from
the Property Inspector toolbar or by choosing Union from the Inspector popup menu.
When the value for the shared property differs among the selected components, the property
value that is displayed always belongs to the anchor selection. The anchor selection is the one
that appears with hollow selection handles in the UI Editor. You may alter the anchor selection
by holding down the Shift key and clicking one of the other currently selected objects. Altering
the anchor selection changes which objects' properties are shown in the Inspector, as well as
altering which object the Property Inspector popup menu operations apply to (for example, the
alignment popup item).
When you change any of the shared properties in the Property Inspector, the property value
changes to the new value in all the selected components.
To set properties for multiple components:
1. Do one of the following to select the group of components to be changed:
❍ Hold down the Ctrl key and select each of the components.
❍ Hold down the left mouse button and draw a "lasso" around the group of
components you want to change.
2. Select and edit the desired property in the Property Inspector.
Note: The Ctrl key causes the selection state of the selected object to be toggled (from either not
selected to selected, else from selected to not selected). Using the Shift key to make selections also
changes the object's anchor usage:
● If the object is not yet selected, it will become selected and become the anchor
8-97
● If the object is already selected, it will just become the anchor.
Using either the Ctrl or Shift key, if a control goes from being not selected to selected, it will become
the new anchor until the user changes the anchor using the Shift select action.
8-98
Creating Containers
JDeveloper provides tools to help you generate these containers:
● Create a frame
● Create a panel
● Create a dialog box
● Create a tabbed pane
Related topics
About Containers

Prototyping the UI Using Layout Properties
8-99
Creating a Frame
A frame is a top-level window with a border and a title. It has standard window controls such as
a control menu, buttons to minimize and maximize the window, and controls for resizing the
window.
The New Frame dialog adds a new class to the active project. It adds necessary import
statements, creates a default constructor, and it creates a jbInit() method in which JDeveloper
sets properties and other initialization code used by the UI Editor.
To add a frame:
1. Open or create a project.

2. Choose File | New.
3. Click the Objects folder.
4. Double-click the Application icon.
The New Frame dialog appears.
5. In the New Frame dialog, enter the name of the package and class.
6. Choose which frame type to extend.
7. Type the frame title.
8. If there are any options (such as Menu Bar) select any you feel are appropriate.
9. Click OK to create the frame and its source code.
The frame is displayed as a .java source file in the Navigator.
To view the a frame in JDeveloper:
● Right click the file in the Navigator and choosing UI Editor to use the interactive UI
design tools, such as the Component Palette and the Property Inspector.
● Right click the file in the Navigator and choosing Code Editor to begin customizing the
source code directly.
Related topics
8-100
About Containers
8-101
Creating a Panel
A panel is a UI container that groups components such as buttons, checkboxes, and text fields.
A panel has a border and may have a title if the border selected is a TitledBorder. Typically, a
panel is embedded within a dialog box or frame.
The New Panel dialog adds a new class to the opened project that extends a panel you select.
It creates a default constructor, and a jbInit() method in which JDeveloper puts property setters
and other initialization code used by the UI Editor.
To create a panel:

4. Double-click the Panel icon.
The New Panel dialog appears.
5. In the New Panel dialog, enter a name of the panel's class and package.
6. Choose the base class from which the panel is derived.
You can choose from any of the base classes installed with JDeveloper. If you prefer,
you can search for another class that isn't from an installed package using the browse
button. By default, the selection is limited to the panel container provided with the core
J2SE (Java 2, Standard Edition) and Swing classes.
7. Click OK to create the panel and its source code.
The panel is displayed as a .java source file in the Navigator.
To view the a panel in JDeveloper:
8-102
Related topics
About Containers
8-103
Creating a Dialog Box
A dialog box is a popup window with a border and a title. Dialog boxes are typically used to
collect user input.
The New Dialog dialog creates a new class that extends Dialog or JDialog and adds it to the
current project. It adds the necessary import statements, and it also does the following:
● Creates a jbInit() method in which JDeveloper puts property setters and other
initialization code used by the UI Editor. The jbInit() method will be invoked when using
any of the constructors.
After adding the dialog box, you can design the dialog directly using the UI Editor. This is how
you add buttons and other controls to your new dialog box.
To create a dialog box:

4. Double-click the Dialog icon.
The New Dialog dialog appears.
5. In the New Dialog dialog, enter the name of the dialog box's package and class. The file
name is automatically filled in for you; it is assigned the same name as the class and is
saved to the package directory.
6. Choose whether to extend java.awt.Dialog or javax.swing.JDialog.
7. Click OK to create the dialog box and its source code.
The dialog box is displayed as a .java source file in the Navigation window.
To view the a dialog box in JDeveloper:
8-104
Using a Dialog Box that is Not a Bean
Once the dialog box has been created and its UI designed, you will want to test or use your
dialog box from some UI in your program. Here is a way to do this:
1. Instantiate your dialog class from someplace in your code where you have access to a
Frame which can serve as the parent Frame parameter in the dialog constructor. A
typical example of this would be a Frame whose UI you are designing, which contains a
Button or a MenuItem which is intended to bring up the dialog box. In applets, you can
get the Frame by calling getParent() on the applet.
For a modeless dialog box (which we are calling dialog1 in this example), you can use
the form of the constructor that takes a single parameter (the parent Frame) as follows:
Dialog1 dialog1=new Dialog1(this);
For a modal dialog box, you will need to use a form of the constructor that has the
boolean modal parameter set to true, such as in the following example:
Dialog1 dialog1=new Dialog1(this, true);
You can either place this line as an instance variable at the top of the class (in which
case the dialog box will be instantiated during the construction of your Frame and be
reusable), or you can place this line of code in the actionPerformed event handler for the
button that invokes the dialog box (in which case a new instance of the dialog box will be
instantiated each time the button is pressed.) Either way, this line instantiates the dialog
box, but does not make it visible yet.
(In the case where the dialog is a bean, you must set its frame property to the parent
frame before calling show(), rather than supplying the frame to the constructor.)
2. Before making the instantiated dialog box visible, you should set up any default values
that the dialog box fields should display. If you are planning to make your dialog into a
Bean, you need to make these dialog box fields accessible as properties. You do this by
defining getter and setter methods in your dialog class.
3. Next, you have to cause the dialog box to become visible during the actionPerformed
event by entering a line of code inside the event handler that looks like this:
8-105
dialog1.show();
4. When the user presses the OK button (or the Apply button on a modeless dialog box),
the code that is using the dialog box will need to call the dialog's property getters to read
the user-entered information out of the dialog, then do something with that information.
❍ For a modal dialog box, you can do this right after the show() method call,
because show() doesn't return until the modal dialog box is dismissed. You can
use a result property to determine whether the OK or Cancel button was pressed.
❍ For a modeless dialog box, show() returns immediately. Because of this, the dialog
class itself will need to expose events for each of the button presses. When using
the dialog box, you will need to register listeners to the dialog's events, and place
code in the event handling methods to use property getters to get the information
out of the dialog box.
Related topics
About Containers
8-106
Creating a Tabbed Pane
A tabbed pane is a UI container that groups components such as buttons, checkboxes, and text
fields on multiple panels. Each panel has a title and a tab that the end user clicks to view the
panel contents.
To create a tabbed pane:
1. Create a frame or other container.

2. In the Swing Containers page of the Component Palette, click the JTabbedPane
component.
3. Click inside the container in the UI Editor to drop the tabbed pane with its default size.
4. Resize the tabbed pane as desired.
5. To add the first tab to the tabbed pane, click the JPanel component in the Swing
Containers page of the Component Palette, then click on the JTabbedPane inside the UI
Editor.
6. To add additional tabs to the tabbed pane, after you click the JPanel component in the
Component Palette, you must click specifically on the tab itself of a previously added tab
panel.
7. To add a layout panel (one that has no tabs) to any of the tabbed pane tabs, click the
JPanel component in the Swing Containers page of the Component Palette, then click
the content area of the JTabbedPane inside the UI Editor (in this case, do not click the
tab itself).
To work with a tab that is not currently the top most tab in the UI Editor, you must choose
the desired panel in the Structure Window. To view the panels you have added to the
tabbed pane, expand the UI folder, expand the dataPanel node, and finally expand the
JTabbedPane node to see the list of JPanels.
Related topics
About Containers
8-107
You can perform the following tasks on the container you created:
● Add a component
● Change the layout for a container
● Modify the layout constraints
● Select components in your project
● Size and move components
● Group components
● Cut, copy, paste, and delete components
Related topics
About Swing JavaBeans Components

Creating Containers
Prototyping the UI with Layout Properties

See also
For more information on Swing Components, go to this java.sun.com web page:
8-108
Adding Components to Your User Interface
When you visually add a component in the UI Editor, JDeveloper generates an instance
variable for the component and adds it to the source code. When you delete a component, the
UI Editor deletes the associated lines from the code.
To add a component to your UI:
1. Create a container component.

2. Click a component in the Component Palette.
3. Do one of the following:
❍ Click in the UI Editor to drop the component at its default size.
❍ Drag the mouse in the UI Editor to form a bounding box from the initial mouse click
to a final point which represents the desired dimensions of the object to be
created.
Dragging to a specific size is only appropriate when layouts for a container that
consider individual component dimensions. Ultimately, the layout manager for
each container in your UI will determine its components' size and position.
❍ Drop the component onto the desired container in the Structure window. Be aware
that this method gives you no control over where the component appears in the
container.
To add multiple instances of a component:
1. Press the Shift key while clicking the component in the Component Palette. You may
release the Shift key and the palette will still remain in multiple creation mode.
Click the arrow tool in the Component Palette to turn off multiple object creation.
8-109
Changing the Layout for a Container
JDeveloper provides a layout property in the Inspector, in which you can choose a new layout
for any container in the UI Editor.
To select a new layout:
1. Select the container in the Structure window.
2. Click the Properties tab in the Inspector, select the layout property, and click its value
field.
3. Click the down arrow in the layout property's value field and choose a layout from the
dropdown list.
JDeveloper does the following:
● Substitutes the new layout manager in the Structure window.
● Changes the source code to add the new layout manager and updates the container's
call to setLayout.
● Changes the layout of components in the UI Editor.
● Updates the layout constraints for the container's components in the Inspector and in the
source code.
8-110
Modifying Component Layout Constraints
When you drop a component into a container, JDeveloper creates an appropriate constraint
object or value for that container's layout manager. JDeveloper automatically inserts this
constraint value or object into the constraint property of that component in the Property
Inspector. It also adds it to the source code as a parameter of the add() method call in the
jbInit() method.
To edit a component's layout constraints:
1. Select the component in the UI Editor or the Structure window.

2. Select the constraints property in the Property Inspector and click its value field.
When working with a null layout manager, there is no constraints property on the
children, set the contraints on the bounds property instead.
3. Use the Property Editor to modify the constraints.
8-111
Selecting Components in Your User Interface
Before attempting to select an existing component in your UI, be sure the selection arrow in the
Component Palette is depressed. Otherwise, you may accidentally place a component on your
UI.
To select a single component, do one of the following:
● Click the component in the UI Editor.
● With focus on the UI Editor, tab to the component (Tab = forward; Shift+Tab =
backward).
● Select the component in the Structure window
To select multiple components, hold down the Ctrl key and do one of the following:
● Click the components in the UI Editor one at a time.
● Click and drag around the outside of the components you want to select.
Note: We recommend using the Ctrl key to perform multiple selections because the Shift key
changes which of the selected objects is the 'anchor' of the selection. The selection anchor is the
object whose property values will be displayed in the Property Inspector; it is also the object to which
popup menu actions apply (i.e. alignment).
As you drag, you surround the components with a rectangle, or "lasso." When this rectangle
encloses all the components you want to select, release the mouse button. If necessary, you
can then use Ctrl+click to individually add or remove components from the selected group.
● Hold down the Ctrl key and select the components in the Structure window.
8-112
Sizing and Moving Components
For many layouts, the layout manager determines the size of the components by constraints,
making sizing in the UI Editor have no effect. However, when working with null, XYLayout, or
GridBagLayout, you can size components when you first place them in your UI, or you can
resize and move components later.
Note: GridBagLayout currently ignores size on creation, but you can then resize components after
creation.
To size a component as you add it:
1. Select the component in the Component Palette.

2. Place the cursor where you want the component to appear in the UI.
3. Drag the mouse pointer before releasing the mouse button.
As you drag, an outline appears to indicate the size and position of the control.
4. Release the mouse button when the outline is the size you want.
To resize or move a selected component:
1. Click the component in the UI Editor or in the Structure window to select it.
When you select a component, sizing handles or nibs, appear on the perimeter of the
component. For some containers, a move handle appears in the middle of the
component.
2. Click the appropriate outer handle and drag to resize.

3. Click anywhere in the component and drag it any direction to move it. If the component is
a container that is covered with other components, use the center move handle to drag it.
Related Topics
Determining the Size and Location of Your UI Window at Runtime
8-113
Grouping Components
JDeveloper provides a number of container components for grouping components together so
they behave as a single component at design time.
For instance, you might group a row of buttons in a Panel to create a toolbar. Or you could use
a container component to create a customized backdrop, status bar, or checkbox group.
When you place components within containers, you create a relationship between the container
and the components it contains. Design time operations you perform on the containers, such as
moving, copying, or deleting, also affect any components grouped within them.
To group components by placing them into a container:
1. Add a container to the UI.
If you are working in a layout that considers size such as the GridBagLayout, null layout
or XYLayout, you can drag to size it.
2. Add each component to the container, making sure the mouse pointer falls within the
container's boundaries. (The status bar at the bottom of JDeveloper displays which
container your mouse is over.) You can add a new component from the Component
Palette, or drag an existing component into the new container.
As you add components, they appear inside the selected container in the UI Editor, and
under that container in the Structure window.
Tip: If you want the components to stay where you put them, change the container's layout to
null before adding any components. Otherwise, the size and position of the components will
change according to the layout manager used by the container. You can change to a final
layout after you finish adding the components.
Related Topics
About Containers
8-114
Cutting, Copying, Pasting and Deleting
Components
JDeveloper supports Cut, Copy, Paste and Delete functionality in the UI Editor. You can
perform these operations between files of the same project or different projects.
Note: When you cut, copy, paste from one file to a file in another project, you may be required to
update your project properties on the target project to include additional libraries. If the the target
project does not define the right libraries for the pasted object, the paste will fail since the UI Editor
will not recognize the class of the incoming objects.
Copying Components
To copy one or more components:
1. Select the components you want to copy.

2. Choose Edit | Copy.
The components are copied to a local clipboard in JDeveloper.
Visual components copied in the UI Editor are not copied to the system clipboard, and cannot
be transferred into other applications. Use a screen capture utility to create an image of a
control, or copy the source text to use the Java code in another Java development
environment.
When you copy a component that has defined event methods, the event listener is copied with
the component, but not the event handler. This is because in most cases it's the format of the
control, and not the behavior, that you want to copy. If your goal is to copy the control and its
behavior to a different Java class file, you need to separately copy the handler: open the file in
the Code Editor, locate the handler code, select it, and choose Edit | Copy.
Tip: If you find yourself copying components from one project to another primarily for their design
settings, consider using Serialized JavaBeans components, which enable you to create new
components with predefined properties.
Cutting Components
Before you cut your component be sure to paste the previously cut object since cutting the
event code will overwrite the contents of the clipboard.
8-115
To cut a component from your user interface:
1. Select the components you want to cut.

2. Choose Edit | Cut.
The component is removed from the UI Editor and placed into a local clipboard only accessible
by JDeveloper (not to the system clipboard). If you quit JDeveloper without pasting the control
into a container, the cut version of the control will be lost.
The cut command is the first step in a cut and paste action. If you just want to remove a
component, see Deleting a component, below. Deleting a component removes it without
changing the contents of your clipboard. If you get in the habit of using the cut command to
remove items permanently, there is a chance that one day you will inadvertently replace
something in the clipboard that you would rather have kept.
When you cut a component that has defined event methods, the event listener is cut with the
component. The event handler is not removed from the source code, nor is it placed on the
clipboard. The reasons for this are twofold:
● In most cases, it isn't the behavior of the control, but the format that you want to retain.
● More than one component may use the same event handler, so removing it from the
code may impact other parts of your program.
To cut an event handler in the Code Editor, locate the handler code, select it, and choose Edit |
Cut.
Pasting Components
The components you copy or cut from a JDeveloper Design window can be pasted into any
other designable class file.
To paste a component:
1. Open the file to which you want to paste the component in the UI Editor.
2. Select the container to which you want to paste the component.
3. Choose Edit | Paste.
8-116
The JavaBeans components you paste will add any existing event listener code from the
original component to your source code. The event handler code does not get copied or cut
with the component: if you want to use the same event handler, you need to copy and paste the
handler separately using the Code Editor.
Deleting Components from your UI
Delete a component when you want to remove it from your Java program without affecting the
contents of the clipboard.
To delete a component:
1. Select the component in the UI Editor or the Structure window.

2. Press the Delete key.
When you delete a JavaBeans component from the UI Editor, the event listener methods, if
any, are deleted from the source code, but the event handler methods are not. If you want to
remove the event handler methods, you need to delete them in the Code Editor.
8-117
Working with Menus
This section explains how to use the Menu Editor to visually design:
● Main menus on a menu bar

● Popup menus for local context menus

Customizing Menus with the Menu Editor Explains how to use the Menu Editor to add and delete items,
enter separator bars and accelerators, and disable (dim) a
menu item or make it checkable.
Adding a Menu Component to a Frame Explains how to attach menus to your frame.
Inserting and Deleting Menus and Menu Items Describes how to add and remove menu items.
Moving Menu Items Describes how to reorder menu items on the menu bar or
move menu items to a different menu.
Creating Submenus Explains how to create submenus (nested menus).
Adding a PopupMenu Explains how to add a PopupMenu to your user interface.
Related topics
About Menu Terminology

About Menu Components
About the Menu Editor
See also
For more information on popup menus and menu bars, go to this java.sun.com web page:
8-118
8-119
About Menu Terminology
The basic parts of a menu are referred to using the following terms:
● A menu bar is displayed at the top of a frame. It is composed of one or more top-level
menus, such as File, Edit, or Help. A JMenuBar may have any component as a child,
such as a JComboBox or JToggleButton, for example.
● A menu is a child of menu bar and contains a collection of menu items, submenus, and
separators.
● A submenu is a menu whose parent is another menu instead of the menu bar.
● A menu item is an individual element on a menu which can invoke a command. Menu
items can have attributes such as being disabled (gray) when not allowed, or checkable
so their selection state can be toggled.
● An accelerator, also known as an keyboard shortcut, allows an alternative way to invoke

a menu item. When a menu item has an accelerator, it is displayed at the right of the
menu item.
● The separator bar helps to visually group related items. It does not invoke a command.
8-120
About Menu Component
There are four types of menu component on the Component Palette: a MenuBar, JMenuBar,
PopupMenu, and JPopupMenu.
● A MenuBar or a JMenuBar is attached to the main UI Frame, and appears at the top of
the frame.
● A PopupMenu or a JPopupMenu appears when the user right-clicks in your UI. At

runtime, popup menus do not appear on the menu bar, instead they are displayed where
the user invokes them.
All of these controls can be edited in the Property Inspector.
The first MenuBar or JMenuBar control dropped onto the UI container is considered the current
menubar for your UI. However, you can create more than one menubar for an application; they
are displayed in the Inspector in the frame's MenuBar property. Select a menu from the
MenuBar property drop-down list to make it active.
Note: Menu components are only editable at design time in the Menu Editor, not the UI Editor. The
menu bar and its top-level menus display in the UI Editor, but they are not selectable and cannot be
edited from there. However, you can always see and select them in the Structure window. To see
how the menu looks in your UI, run your application.
8-121
About the Menu Editor
You access the Menu Editor by opening the Java file in the UI Editor, which makes the
Structure window visible. Then, in the Structure window, when you click on a menu, menu item,
or menu root node, the Menu Editor appears.
Interaction with the Code Editor and the Property Inspector
JDeveloper synchronizes your changes as you work. As you edit menu items in the Menu
Editor, all changes are reflected in the source code by the Code Editor and the Property
Inspector. When you make changes to the menus in the source code or the Property Inspector,
those changes are reflected in the Menu Editor.
For example, when you add a Menu to a MenuBar component, this Menu appears in the
Structure window as a child of the MenuBar. Also, when you change properties for Menu or
MenuItem (like text or enabled), those changes are reflected in the code, Menu Editor, and
Property Inspector.
Since JDeveloper also maintains synchronization with the Code Editor, there is no need to save
your menu design manually. JDeveloper generates the code which you can view and edit in the
Code Editor as you use the Menu Editor. The generated code is saved when you save your
Java source file. The next time you open the Java file and select a MenuBar component in the
Structure window, the Menu Editor will open and reload everything for that component.
Once you add a menu component to the UI design, you can use the Menu Editor to design the
menu structure. To activate the menus in the user interface, you must use the Property
Inspector to attach the menu items to events, or enter the code manually in the Code Editor.
8-122
Customizing Menus with the Menu Editor
Use the Menu Editor to complete these tasks:
● Add menu items

● Disable menu items
● Specify accelerators
● Insert separator bars
● Create checkable menu items
8-123
Adding Menu Items
When you first open the Menu Editor, it displays the menu bar or popup menu that you opened
with any defined menu items. There is also a blank menu to the right of the last menu in the
menubar and a placeholder at the end of each menu, indicated by a dotted rectangle.
To add menu items to an existing menu:
1. In the Menu Editor, select the position on the menu bar where you want to add a new
menu, or on the menu select where you want to add a new menu item, seperator or
submenu.
2. Enter the text for the new menu component's label.
As you start to type, the highlighted dotted rectangle changes to a normal text edit field
containing a cursor. The text field will scroll as you type to accommodate labels longer
than the edit field.
3. When you're finished typing, press Enter.
The width of the list expands if necessary to display all the labels in the list, and a
placeholder for the next menu item is automatically selected.
4. Enter a label for each new item you want to create in the list, or press Esc to return to the
menu bar.
Use the arrow keys to move from the menu bar into a menu, and to move between items
in the list; press Enter to complete an action.
8-124
Disabling Menu Items
You can prevent users from accessing certain menu commands based on current program
conditions without removing the command from the menu. For example, if no text is currently
selected in a document, the Cut, Copy, and Delete items on the Edit menu are disabled and are
displayed dimmed.
Use the Enabled property to disable a menu item. As with most properties, you can specify an
initial value for Enabled using the Inspector. The default enabled state of a menu item is True;
this may change when an event occurs.
To disable a menu item:
1. Select the menu item in the Menu Editor or in the Structure window.
2. In the Property Inspector, set the Enabled property for the menu item to false.
(In contrast to the Visible property, the Enabled property leaves the item visible. A value
of false dims the menu item.)
8-125
Specifying Accelerators
Accelerators enable the user to perform an action without accessing the menu directly by typing
in an accelerator key combination. For example, a commonly used accelerator for File | Save is
Ctrl+S.
To specify an accelerator for a menu item:
1. Select the menu item in the Menu Editor or in the Structure window.
2. In the Inspector, select the accelerator property and use the accelerator dialog to supply
the key combination.
8-126
Inserting a Separator Bar
A separator bar inserts a line between menu items and between sibling menu components,
including menu items and submenus. You can use separator bars to indicate groupings within
the menus.
To insert a separator bar on a menu:
1. Select the menu item before which you want a separator, or choose the blank item at the
end of a menu.
2. Right-click and choose Insert Separator from the popup menu.
The separator bar is inserted above the selected menu item.
3. Alternatively, you can type a hyphen (-) for the menu item label.
Using the right-click menu to insert the separator will result in the line addSeparator() to
be generated, whereas using the hyphen for the label will use the more memory
intensive creation of an additional class member whose label is a hyphen.
8-127
Creating Checkable Menu Items
To make a menu item checkable, you need to change the menu item from a regular MenuItem
component to a CheckboxMenuItem. A CheckboxMenuItem has a State property (boolean) that
allows an event-handler to determine how the associated event, or behavior, should be
executed.
● The State property for a checked menu item is set to true.
● The State property for an unchecked menu item is set to false.
To change a regular menu item to a CheckboxMenuItem:
1. Select the menu item.

2. Right-click and choose Make Checkable from the popup menu.
8-128
Adding a Menu Component to a Frame
Since a non-popup menu can only be attached to container, such as a JFrame or a JDialog,
you must first open or a container file. You can open one in one of the following ways:
● Open an existing Frame or Dialog file.

● Use the New object window to create a new frame or dialog.
To add a menu component to the UI:
1. Right-click the UI frame file in the Navigator and choose UI Editor.

2. Select your main UI frame in the UI Editor or in the Structure window.
3. Click a menu component on the Component Palette and drop it anywhere in the UI
Editor. You can choose either a menu bar or a popup menu.
❍ A menu bar is attached to the main UI frame or dialog, and is displayed at the top
of the application.
❍ A popup menu is displayed when the user right-clicks in your UI. Popup menus do
not have menu bars.
Alternatively, you can open a file that already contains a menu component.
At this point, nothing is visible on the UI. The added menu component is displayed in the
Structure window and opens in the Menu Editor.
8-129
Inserting and Deleting Menus and Menu Items
To insert a new, blank menu or menu item, place the cursor on an existing menu item and right-
click and choose Insert (Menu or Menu Item).
Menus are inserted to the left of the selected item on the menu bar, and menu items are
inserted above the selected item in the menu.
To delete a menu item, select the menu item and press the Delete key.
Note: A default placeholder (which you cannot delete) appears after the last menu on the menu
bar and below the last item on a menu. This placeholder does not appear in your menu at
runtime.
8-130
Moving Menu Items
In the Menu Editor, you can move menus and menu items by dragging and dropping them.
When you move a menu item with submenu items, the submenu items move as well.
You can move menu items and submenu items:
● Within a menu
● To other menus
You move entire menus along the menu bar.
To move a menu item:
1. Click and drag the menu item or submenu item to the new location.
If you are dragging the menu item to another menu, drag it along the menu bar until the
cursor points to the new menu.This action causes the menu to open, enabling you to
drag the item to its new location.
2. Drop the menu item or submenu item at the new location.
To move a menu:
1. Click and drag the menu to the new location by dragging across the menu bar until the
cursor points to the location where you want the menu to appear.
2. Drop the menu at the new location.
8-131
Creating Submenus
Submenus can appear on menus to provide additional, related commands. Such nested lists
are displayed with the menu text followed by an arrow. JDeveloper supports as many levels of
submenus as you want to build into your menu.
Organizing your menu structure with submenus can save vertical screen space. However, for
optimal design purposes you probably want to use no more than two or three menu levels in
your UI design.
When you move a menu off the menu bar into another menu, it becomes a submenu. Similarly,
if you move a menu into an existing submenu, it forms another submenu under the submenu.
To create a submenu:
1. Right-click the menu item and choose Create Submenu.

2. Enter a name for the nested menu item, or drag an existing menu item into this
placeholder.
3. Press Enter, or Down arrow, to create the next placeholder.
4. Repeat steps 2 and 3 for each item you want to create in the submenu.
Alternatively, you can create a submenu by selecting the menu item and pressing Ctrl
and the right arrow key.
5. Press Esc to return to the previous menu level.
To move existing menus to submenus:
You can also create a submenu by inserting a menu from the menu bar between menu items in
another menu. When you move a menu into an existing menu structure, all its associated items
move with it, creating a fully intact, submenu. This behavior pertains to moving submenus as
well; moving a submenu into another submenu creates one more level of nesting.
8-132
Adding a Popup Menu
To add a Popup menu:
1. Open your UI class in the UI Editor.

2. Drop a popup menu from the AWT or Swing Containers Component Palette into the
Structure window.
3. Select the popup menu in the Structure window to open the Menu Editor.
4. Add one or more menu items to the popup menu.
5. Expand the UI folder in the Structure window and select the panel or other component
whose event you want the popup menu attached to so you can see that component in
the Property Inspector. For the following example, panel1 was selected.
6. In the Property Inspector, click the Events tab and click the desired event value field.
7. Type the stub name of the event into the event value field and press Enter to create an
event-handling method stub in the source code with the supplied name. For the following
example, the MouseClicked event was selected and the name panel1_mouseClicked
entered.
8. Edit your event-handler stub to resemble the following:
void panel1_mouseClicked(java.awt.event.MouseEvent e) {
panel1.add(popupMenu1);
if (e.isPopupTrigger()) {
// Make the PopupMenu visible relative to the current mouse position in the container.
popupMenu1.show(panel1, e.getX(), e.getY());
}
}
9. Add event handlers to the popup menu's menu items as needed for your application.
8-133
Working with Events
This section explains how to use JDeveloper's UI design tools to attach event handler code to
component and menu events. This section covers the following topics:

Attaching Event Handling Code to Menu Events Explains how to use JDeveloper to add a frame, panel
or dialog box to your project.
Attaching Event Handling Code to a Component Explains how to arrange components inside a container
Event that you created.
Related Topics
About Events
8-134
About Events
In building your Java program, you can think of your code as being divided into two categories:
initialization code and event-handling code.
● Initialization code is executed when the UI components are created. You can think of this
primarily as "start up" code for the components. This initialization code includes anything
in the jbInit() method that all JDeveloper-designed GUI classes have. JDeveloper
generates this code based on your UI design. For example, JDeveloper generates a
button1.setLabel("OK") method call because you set the label property of a button, using
the Inspector, to "OK".
● Event-handling code is the code that is executed when the user performs an action, such
as pressing a button or using a menu item. JDeveloper creates the stub (empty) event-
handling method for you when you enter an event name in the Inspector for that
component and press Enter. In that stub, you write code to handle the actual action
caused by the event.
Your entire program consists of the initialization code, which says how things should look when
they first appear, and the event-handling code, which says what should happen in response to
user input.
There are some JDeveloper components, such as dialogs, which normally appear only when
event-handling code is executed. For example, a dialog isn't part of the UI surface you are
designing in the UI Editor; instead it is a separate piece of UI which appears transiently as a
result of a user selecting a menu item or pressing a button. Therefore, some of the code
associated with using the dialog, such as a call to its show() method, might be placed into an
event-handling method.
Related Topics
Attaching Event Handling Code to Menu Events

Attaching Event Handling Code to a Component Event
8-135
Attaching Event Handling Code to Menu Events
In Swing, a menu item has actionPerformed events and CheckboxMenuItems have
itemStateChanged events. Code that you add to the actionPerformed event for a menu item is
executed whenever the user chooses that menu item or uses its accelerator keys.
To add code to a menu item's event:
1. Open the UI Editor for your UI frame.

2. Add a menubar to your UI frame and insert menus and menu items into the menubar.
Alternatively, you can open a file that already contains a menu.
3. Select a menu item in the Menu Editor or the Structure window.
4. In the Property Inspector, click the Events tab and click the desired event value field.
event-handling method stub in the source code with the supplied name.
When you enter a name in the event value field, JDeveloper open the Code Editor and
displays the source code in the Structure window. The cursor is positioned in the body of
the newly created event-handling method, ready for you to enter code.
6. Inside the open and close braces, enter the code you want to have executed when the
user clicks this Menu command.
8-136
Attaching Event-Handling Code to a Component
Event
Using the Events page of the Inspector, you can attach handlers to component events and
delete existing event handlers.
To attach event-handling code to a component event:
1. Select the component in the UI Editor or in the Structure window.
2. In the Property Inspector, select the Events tab to display the Events for that component
and click the desired event value field.
event-handling method stub in the source code with the supplied name.
JDeveloper creates an event handler with the new name and switches to that event
handler in the source code. JDeveloper also inserts some additional code into your class,
called an Adapter, to make the connection from the event to your event handling method.
4. Inside the stub of the event handler write the code that specifies the response to that
component event.
Note:To find out what methods and events a component supports, right-click that component
in the Code Editor and choose Browse Symbol at Cursor to open the class in the Code
Editor. You can also right-click the component and choose Browse Javadoc to view the
documentation for that class.
To quickly create an event handler for a component's default event:
1. Select a component on the Component Palette and add it to your UI.
2. Double-click the component in the UI Editor. An event stub is created and focus switches
to that event handler in the source code.
3. Add the necessary code to the event handler to complete it.
Note:The default event is defined by beanInfo, or as actionPerformed if none was specified.
8-137
8-138
This section explains how to use JDeveloper's UI design tools to create an applet class and
HTML file. It also describes how to generate the JNLP file when you want to use Java Web
Start to deploy and run your Java applet. This section covers the following topics:

Creating an Applet Explains how to use JDeveloper to add an applet class to your project.
Creating an Applet HTML File Explains how to use JDeveloper to add the applet HTML file to your project
Deploying Applets Provides links in the JDeveloper documentation to working with J2EE web
modules and deploying them to the Oracle9iAS application server.
Related topics

Debugging an Applet
Running an Applet
8-139
Creating an Applet
In JDeveloper, you can easily create a skeleton Java applet and then edit it with the Code
Editor.
To create a Java applet:
1. In the Navigator, select the project you want to use for your applet.
2. From the File menu, select New.
3. Click the Web Objects folder.
4. Double-click Applet icon in the Items list.
This will open the New Applet dialog that will create the applet for you based on
information you specify, including the name, package and class it extends. Click the Help
button to obtain context-sensitive help in the dialog.
When you are finished, you will have a skeleton .java file containing the applet class, based on
the details you entered. You can edit this file in the Code Editor. Using JDeveloper you will also
be able to embed your applet within an HTML page, which you can create with the Applet
HTML File wizard. You can also run the applet standalone in order to test it from JDeveloper.
Related topics
Creating an Applet HTML File

Debugging an Applet
Running an Applet
Deploying an Applet as a WAR File
8-140
In JDeveloper, you can easily create a Java applet HTML file that acts as a container for your
applet.
To create a Java applet HTML file:
1. In the Navigator, select the project that contains your applet.

2. From the File menu, select New.
3. Click the Web Objects folder.
4. Double-click Applet HTML File icon in the Items list.
This will open the Applet HTML File Wizard which will create the file for you based on
information you specify, including the file location, code attributes, positioning attributes,
and applet parameters. You can also create an optional deployment profile. Click the
Help button to obtain context-sensitive help in the wizard panels.
When you are finished, you will have an .html file that acts as the container for your applet.
When this file is opened in a browser, it causes the applet to be downloaded and executed on
the computer where it was viewed. You can edit this file in the Code Editor. When you create a
deployment profile, the profile contains the information necessary to deploy the applet, which is
described by the new HTML file, as a Web Application. Using JDeveloper you will be to run and
debug your applet, enabling you to test it before deployment.
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
8-141
Deploying Applets
Deploying your applet, or any other J2EE web modules in Oracle9iAS with JDeveloper is a
completely automated process:

● Deploying an Applet as a WAR File
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
8-142
Working with JClient Applications
This section describes JClient, the Business Component for Java (BC4J) common client
framework, which JDeveloper provides for building Swing-based applications and applets as
Java clients for business components.
Note: JClient is the next generation of Java client for BC4J support in Oracle9i JDeveloper and is
the technology that will be of interest to all developers who worked with Data-Aware Controls (DAC)
in previous releases. For information about DAC migration, see About JClient Compatibility with
DAC.

Creating Simple JClient Forms Describes how to use the JClient wizards to generate a
complete data forms application.
Modifying JClient Forms Describes ways to modify the generated data form
application using JClient wizards, the UI editor, and the
code editor.
Working with JClient Models Provides procedures for using the Model Property
Editors that you use to create JClient control bindings
based on Swing's Model-View-Controller architecture.
Working with JClient Controls Describes the use of the controls that appear on the
JClient component palette. These controls, provided by
JClient, let you implement particular data form behavior
not supported by the standard Swing controls.
Working with Java Web Start and JClient Applications Describes how to use the JClient Java Web Start
Wizard to generate the files needed to use Java Web
Start to deploy and run client-side JClient-specific
applications from web servers.
Related topics
About JClient UI Design in JDeveloper
8-143
See also
For more information on Java Web Start, go to this java.sun.com web page:
http://java.sun.com/products/javawebstart/
For more information on MVC, go to this java.sun.com web page:
http://java.sun.com/products/jfc/tsc/articles/getting_started/getting_started2.html
8-144
JClient is the Business Component for Java (BC4J) common client framework. JDeveloper
provides JClient for building Swing-based applications and applets as Java clients for business
components. The JClient framework consists of models which handle the communication
between the client and the business components. Swing application developers will benefit
from these features:
● Quick creation wizards produce databound forms

● Binding to BC4J datasources supported for any model-based controls, including:
❍ Standard Swing controls
❍ JDeveloper-provided JClient controls
❍ Third party model-based addin controls
● Easy reuse of JClient frames and panels supported by XML data definition
● Remote methods from BC4J available to Java client due to direct BC4J binding
The JClient framework permits developers to build databound Java clients. Instead of relying
on JDBC programming, JClient cleanly separates database access code from UI code.
Additionally, database access is improved with JClient because its direct binding to BC4J
allows it to take advantage of the numerous performance features implemented in BC4J. And
because JClient relies on the model-view-controller architecture, designing Java clients is no
different than working with Swing controls.
Here is a typical development scenario:
1. In JDeveloper create a BC4J project. Add entity objects, view objects, and application
modules. Build this BC4J project.
2. Create a new empty project. Add a new JClient Frame to the project. The JClient Form
Wizard in the JClient Object folder that you display in the New Gallery will guide you
through the process.
3. While creating the frame, define a client data model that will identify the BC4J application
module to use (from the BC4J project). The wizard adds this data model definition to the
client project configuration (.cpx) file.
4. After completing the wizards, the Navigator displays the generated frame and panel
classes in your project. You can further customize them by editing the code in the code
editor or by using the UI Editor.
5. If you use the UI Editor, you can add additional controls to the JClient layout panels from
8-145
the Component Palette. You can use the Property Inspector to set the binding for the
control. Binding determines how the control will interact with BC4J datasources and is
set through the component's model or document property.
6. When all edits are complete, build the JClient project.
7. Run or debug the application using JDeveloper.
8. After you have debugged your JClient project, you can test deployment using
JDeveloper's embedded OC4J server and Sun's Java Web Start application-deployment
technology. Java Web Start lets users download applications and applets using a web
browser, but runs the application entirely on the client without the need for a web
browser.
9. Deploy the production JClient application and BC4J business components to the
production web server using the generated Web Application Archive (WAR) files.
10. With Java Web Start installed on the client machines, users can easily download and
launch the application. Java Web Start handles updates that you make to the application
on the web server each time the user launches the application.
Related topics
About the JClient Architecture

About the JClient Design Time Wizards
About the Client Project Configuration File
About JClient Application Code
About JClient Models for Swing Controls
About Using JClient Data Forms
About Master-Detail Forms in JClient
About the JClient Graph Panel
About the JClient Login Dialog
About Multimedia in JClient Applications
About Find Mode for JUNavigationBar Controls
About JClient Composite Controls
About Panel Binding in JClient
About Navigating the UI Using JClient Controls
About Java Web Start and JClient Applications
Creating Simple JClient Forms

Modifying JClient Forms
8-146
Working with JClient Models
Working with JClient Controls
Working with Java Web Start and JClient Applications
See also
For more information on MVC go to this java.sun.com web page:
8-147
About the JClient Architecture
JClient is a framework, consisting of a set of Java classes that enable you to quickly and
efficiently build databound Java UI applications for business components. The JClient
framework consists of helper classes which handle the communication between the client and
the business components.
Tip: Developers that want to create databound Java clients work in combination with JClient, Swing,
and Business Components for Java (BC4J). This document topic is designed to help users
understand which of the JDeveloper design time tools and APIs are needed to implement the JClient
databound UI.
The Role of the Swing MVC in JClient Applications
JClient architecture is based on a Model-View-Controller (MVC). With MVC there are three
communication objects logically separated for each component:
● The Model represents the data or state of the component and is its underlying logical
representation.
● The View is the component's visual representation, which describes how it looks, for
example: whether it is a button or some other control, and whether it uses text or icons,
what border and color it uses and so forth.
● The Controller specifies the interaction with the client (how to interpret user input). The
controller notifies registered listeners when the user types text, clicks a button, tabs to
the next field and so forth.
For example, a JCheckBox is a Swing component which has a defined Model, View, and
Controller. When the user interacts with the controller by clicking the checkbox, the controller
notifies the model that it should change its state (from false to true or the reverse). The view,
which is listening for changes in the state of the model, can then update itself (for example, by
making the checkbox appear selected). An important point about this architecture is that the
model is not aware of the view or views displaying it, nor of the controller(s) being used to
update it.
The Swing API lets you set the model for for every component using the component's model or,
in some cases, document property. In Swing, the model for any subclass of JTextComponent is
named document which is accessed using the setDocument() and getDocument() methods.
The standard Swing JLabel component does not represent data and therefore does not follow
the MVC architecture. However, JClient provides a JULabel component to overcome this
limitation when you want to assign labels using business component data.
8-148
The Role of BC4J in JClient Applications
It is not the intention of this document topic to explain the Business Components for Java
framework. However, there is a minimum of information that you must understand to bind
Swing controls to business components through JClient. For complete details about BC4J,
please refer to the documentation topics in that area.
The data that your UI displays through JClient originates as a rowset generated by a business
components view object. Your workspace must therefore contain a business components
project, which defines a container (known as an package) that holds:
● The view definitions, which is a named object defining a database query.

● The view link definitions, which define master-detail relationships between two view
definitions.
Furthermore, the business components project must specify named instances of each for use
by the client application. To specify these named instance, you use the Application Module
Editor to modify the business components data model. The data model in the business
components project defines what named instances you will be allowed to access from the
client.
The following images, taken from the Application Module Editor, show a list of available view
object definitions in the package and the view object instances the data model of the
application module defines:
Specifically, the image above shows three view definitions and two view link definitions. For
example, the view link OrdersViewDefinition via OrdersCustomerIdFkLink defines
CustomersViewDefinition as a possible source view and OrdersViewDefinition as a possible
target view.
8-149
The image above shows the application module data model which contains five usages of the
three view definitions. For example, OrderItemsViewUsage is an instance of
OrdersItemViewDefinition and OrderItemsDetailViewUsage is another instance of
OrderItemsViewDefinition. The difference between these two view usages is the scope of the
rowset: The rowset of the detail view usage is driven by the current row of the
OrdersMasterViewUsage; whereas, the OrderItemsViewUsage is unconstrained because there
is no view link to a master view object.
It is the combination of view instances and view link instances shown in the Application Module
Editor that defines the data model against which the models of the JClient UI will work. For
instance, if, in your application, you want to get to the BC4J view object to dynamically alter the
view object, you would use the BC4J API rather than the Swing or JClient API.
The Role of the JClient Architecture
Using the JClient API, your application communicates with the business components by:
● Establishing a connection to the business components application module, which may be

running in the same VM or on another VM, deployed for instance on a middle-tier
application server.
● Registering a specific binding class with each Swing component that needs to access
data from a business components view object instance.
To understand how the JClient layer accomplishes this, let's look at typical JClient code. The
following code is the same code that you would see if you use the JClient Form Wizard to
generate complete application code.
In a generated frame, for example, the code to connect to the business components looks like
this:
JUApplication app =
JUMetaObjectManager.createApplicationObject("Project1.Mypackage1Module", null, new
8-150
JUEnvInfoProvider());
The above code looks up the named application module definition Mypackage1Module in the
project file Project1.cpx and establishes a connection to the business components application
module.
In the generated panel for which you layout your UI with Swing controls, this JClient constructor
creates a container object for the iterators used to access the rows of the view object:
private JUPanelBinding panelBinding = new JUPanelBinding("Project12.Mypackage9Module",

this);
You can create the Panel Binding object at the level of a frame or panel depending on what
level you want to manage databound controls.
Then the setApplication() method defines which connection to the business components is
used by the Panel Binding:
panelBinding.setApplication(app);
Then the executeIfNeeded() method provides the query execution policy:
panelBinding.executeIfNeeded();
Finally, the createAttributeBinding() method creates the binding and registers that binding as
listeners to a specific Swing component and possibly the model (in the case of JClient-specific
components):
mCustomerId.setDocument(JUTextFieldBinding.createAttributeBinding(panelBinding,
mCustomerId, "CustomersView", null, "CustomersViewIter", "CustomerId"));
The method returns the current model for this component. In this sense, JClient does not
provide models, it merely uses the model property to register the control using a binding helper
class.
There are two exceptions where JClient does provide its own models:
● The JTable control should use the JUTableModel

● The JTree control should use the JClient-created DefaultTreeModel
8-151
Users who decide to provide there own models for either JTable or JTree should look at the
JUTableBinding and JUTreeBinding source code and decide how to overwrite these bindings.
For all other components, it is important if a developer wants to provide their own models, the
program has to execute the setDocument(myModel) or setModel(myModel) method before the
BC4J binding is done; otherwise, the BC4J binding will not register listeners to the active
model.
Here are some examples of how you use the APIs of Swing, BC4J, and JClient:
If you need to get to the BC4J ViewObject to call the methods you added, or dynamically alter
the ViewObject, then you get to the ViewObject instance using the binding.
ViewObject vo = panelBinding.findIterBinding("DeptViewUsageIter").getViewObject();
If you decide to hard code clientside validation using Swing, this added functionality can be
used together with the JClient binding:
mDeptno.getDocument().addDocumentListener(myDocumentListener);
If you want to change the behavior of a component itself, then you can subclass a Swing
component. This component can still use the JClient binding:
JTextField mDeptno = new JTextField()

{
public boolean isFocusTraversable() {return false;}
};
Related topics

See also
For more information about business components:

8-152
Working with View Objects, View Links, Application Modules, and Clients
8-153
Functionally, JClient is divided into design time and runtime. Because the design time is fully
integrated with the JDeveloper IDE through a set of wizards, JDeveloper helps you to generate
a JClient application quickly. The wizards generate code with hooks into the JClient runtime.
You can use JClient wizards without a full command of the JClient runtime APIs. The wizards
help you to build Java clients that display data forms using standard JFC/Swing components
which are bound to Business Components for Java (BC4J) datasources. The control bindings
you add to standard Swing controls using the JClient design time allows your data forms
application to get and set values on the BC4J datasources.
The JClient wizards together with the JDeveloper IDE help you to quickly build, run, and test a
JClient application or applet. You can later modify data forms by adding more sophisticated
controls and Java code to enhance your application.
Related topics

8-154
For a given client, JClient maintains an XML configuration file with information required by the
client. This information includes details on which business components application module to
use, such as how to connect to the application module. At runtime, the client configuration file
provides the information needed by the BC4J ApplicationModule pool manager to create a new
application module session.
You create the client project configuration file at design time when you create a JClient data
model definition using the JClient Data Model Wizard. To use the JClient Data Model Wizard,
you must have an existing Business Components project in the same workspace as your
JClient project. You use the wizard to select the application module that contains the desired
view objects and connection configuration. Both of these items must be created in the Business
Components project before you can generate a JClient configuration file. When you complete
the JClient Data Model Wizard the first time, the wizard adds the configuration file to your
JClient project. The name of the file is derived from your project name with the extension .cpx.
You can rerun the wizard to add additional data model definitions to the .cpx file or to edit an
existing data model definition.
You can see the view objects contained by the application modules referenced by each data
model definition you create in JDeveloper's Structure window. If the application module was
defined in the Business Components project as a nested application module (one contained by
another application module), then only the view objects that were added to the nested
application module will be displayed. The data model definition of a nested application module
refers to the container application module for its list of view objects. In the Structure window,
you can right-click an application module node and open the JClient Data Model Wizard to edit
that data model definition or view the entire list of available view objects for that definition.
When you create or update a data model definition, JDeveloper updates several application
libraries. One of the libraries contains class files common to the JClient and business
components projects (it will have a name like
Workspace1_jws_Project1_jpr_ClassesMypackage1ModuleLocal), which are required by
JDeveloper to compile and run your JClient application. JDeveloper updates this library based
on the most recently saved data model definition. Consequently, you may need to reedit a data
model definition to update the library with the desired classes. Also, when you move a JClient
project and a business components project to a new installation, you must move all 'named
user library' definitions. All the user libraries appear in the libraries.xml file in the system folder,
and it is necessary to copy this file to the new JDeveloper installation.
The client configuration file is accessible to all of the classes that are part of the JClient project.
This allows you to create BC4J client applications or applets by selecting the application
module once, then reuse the definition throughout the entire project.
8-155
This is a sample from a typical JClient .cpx file:
<JboProject
Name="Project2"
Package="" >
<Session
Name="ClientDataModel1"
Package="package1"
Configuration="Package1ModuleLocal">
</Session>
</JboProject>
Within the “Session” element of the configuration file, “Name” identifies the name of the JClient
data model, “Package” identifies the BC4J package where the BC4J configuration definitions
will be found, and “Configuration” selects the configuration to run. Depending on how the
Business Components will be deployed, certain libraries will be required on the client. The
"Configuration" entry in the JClient data model is responsible for including the appropriate
libraries.
Related topics
Changing Client Data Model References

8-156
In a JClient application, data binding between the Swing controls and Business Components
datasources relies on the creation a set of JClient objects that closely resemble the UI
containers used to assemble the JClient forms. You can see these containers and their JClient-
specific code when you use the JClient Form Wizard to generate a complete application. For
example, assuming a master-detail type form, based on a Dept and Emp view object, the
wizard would generate the following classes:
● FrameDeptViewEmpView1 extends JFrame

● LYPanelDeptViewEmpView1 extends JPanel
● PanelDeptView extends JPanel
● PanelEmpView1 extends JPanel
Where JFrame and JPanel are Swing classes. When you run the application, starting with the
JFrame, the following JClient code is executed:
1. The main() bootstraps the application by creating an application object (JUApplication)

that allows an application module session object to be created.
2. The frame is initialized (FrameDeptViewEmpView1 in the above example) through a
constructor that takes an application object.
3. The frame or applet class creates the layout panel is initialized through a call to a
constructor that takes a JUApplication object.
4. Initialization of the layout panel (LYPanelDeptViewEmpView1 in the above example)
results in a panel binding object (JUPanelBinding) for a specific client data model. The
creation of the panel binding is an important part of the JClient functionality.
5. In the layout panel's jbInit() method, the data browsing (children) panels are created. For
this, JClient passes the layout panel's panel binding into the children data panels
(PanelDeptView and PanelEmpView1 in the above example). Thus, children panels
share the panel binding with the layout panel.
6. A control to attribute data binding occurs using the control's specified JClient model.
7. The control binding handles events to populate and update data for the UI control.
During design-time, each data browsing panel you add to the JClient application gets it context
for marshaling interactions between the UI controls and the Business Component datasource's
rowset iterator from the panel binding created in the frame or layout panel. Once you have a
8-157
frame or layout panel that creates this panel binding, JClient permits you to assemble the
application by adding new data browsing panels.
Then you can use the UI Editor in JDeveloper to add controls one by one to the data panel.
You set the data binding by specifying a JClient control model on the control's document or
model property. At runtime, each control in the data panel becomes data bound through a
getPanelBinding() call as an argument to its setModel() or setDocument() method.
8-158
About the Frame or Applet Class in JClient
Application Bootstrap
When you run the JClient application by selecting the Frame or Applet class in the Navigator
and select Run, one of the first things that happens in the JClient bootstrap code is the creation
of the JUApplication object. The following code line makes this happen:
JUApplication app =
JUMetaObjectManager.createApplicationObject("MyJClientProject.ClientDataModel1", null,
new JUEnvInfoProvider());
The first parameter to createApplicationObject(), "MyJClientProject.ClientDataModel1",

identifies the data model from which the JUApplication instance is to be created. A
JUMetaObjectManager object takes this name and uses the first part (MyJClientProject) to form
the client project file name (MyJClientProject.cpx). The .cpx file is read and parsed. The
Session information is extracted and cached in JUMetaObjectManager.
Then, the Session definition, specifically the Package and Configuration values, is extracted.
The information is passed to the ApplicationModule pool manager, which creates an application
module instance. (Refer to the Business Components for Java documentation for information
about the ApplicationModule pool.)
The JUApplication instance is created from this application module instance.
Frame Initialization
After the JUApplication is instantiated, initialization of the frame proceeds. An instance of the
frame is created by invoking the constructor that takes the JUApplication. That constructor
creates the status bar for the frame and saves the JUApplication reference in a field (app).
Then, it calls jbInit() and initialization of the main layout panel proceeds.
Applet Initialization
After an instance of the applet is created, initialization of the applet proceeds. The
JUApplication is created and the reference is saved in a field (app). Then jbInit() is called and
initialization of the main layout panel and the status bar proceeds.
8-159
About the Layout Panel in JClient
The main panel within a JClient frame is called the layout panel (field "layoutPanel"). This panel
is a UI container for one or more data browsing panels. If the frame is to show master-detail
data, the layout panel will contain two data browsing panels, one for the master and one for the
detail.
The layout panel is created through a call to the contructor that takes the JUApplication. An
important part of layout panel initialization is the creation of the panel binding. Panel binding
acts as the container of all "iterator bindings" used by the panel (or its children). An iterator
binding is the object that marshals interactions between UI controls and BC4J datasource
rowset iterator.
The panel binding is registered with the application (JUApplication) object through the following
line of code:
panelBinding.setApplication(app);
In the layout panel's jbInit() method, the creation of the data browing (children) panels
proceeds. For this, JClient passes the layout panel's panel binding into the children panels.
Thus, children panels end up sharing the panel binding with the layout panel.
8-160
About Data Panels in JClient
A data browsing panel contains controls through which the user can view and edit data. Thus, it
has a set of controls declared and instantiated as fields. The data browsing panel receives its
panel binding from the layout panel (in its constructor). After that, jbInit() is called.
In the jbInit() method, binding of the control to attributes occurs. Examine the following code:
textFieldDeptName.setDocument(JUTextFieldBinding.createAttributeBinding(getPanelBinding(),
textFieldDeptName, "DeptView", null, "DeptViewIter", "DName"));
The above code line sets the Swing Document object for a text field named textFieldDeptName.
In short, textFieldDeptName is to show and edit the DName attribute of the view object named
DeptView.
The Document object is created by a static createAttributeBinding() method on

JUTextFieldBinding. JClient provides model objects for Swing controls (where the model for text
field is called Document) that are responsible for marshalling interaction between the Swing
controls and BC4J rowset iterator. We refer to these JClient implementation of Swing models as
control bindings.
The first parameter to createAttributeBinding() is the panel binding. The second parameter is
the text field control itself. The third parameter DeptView identifies the view object. In order to
locate the view object, we need the application module in addition to the view object name. The
application module is provided by the panel binding (the first parameter) since the panel binding
is registered with the JUApplication object. While this happens, the panel binding receives the
application module reference from the JUApplication object. This application module is used as
the context in which the named view object is found.
The fourth parameter is an optional name of the rowset iterator within the view object. This
enables the user to work with a secondary rowset iterator if desired. To use a secondary rowset
iterator, the user must change code manually and enter the name of the rowset iterator. "null"
means that this control will bind to the default rowset iterator of the view object.
The panel binding keeps a list of iterator bindings. Each iterator binding specifies the view
object instance and (optionally) the rowset iterator. An iterator binding (within the panel binding)
is identified by its name. The fifth parameter (DeptViewIter) specifies the iterator binding name.
Thus, when createAttributeBinding() is called, JClient tries to look for an iterator binding by the
specified name (DeptViewIter). If one is found, JClient uses that iterator binding. If one is not
found, JClient uses the view object name and rowset iterator name to create a new iterator
8-161
binding, assign its name, and register it with the panel binding.
The last parameter (DName) is the name of the view object attribute to which the text field is
bound.
8-162
About Control Binding in JClient
Populating Controls with Data
After data browsing panels are initialized, the layout panel calls executeIfNeeded() on the panel
binding to execute the query on the BC4J datasource.
This method checks to see if the query had been executed on the view object and if not calls
executeQuery() on it. This brings data from the database into the cache and causes BC4J's
RowSetListener events to fire. The first among these would be the
RowSetListener.rangeRefreshed event. This event is captured by the iterator binding (because
it implements RowSetListener and has registered itself as a listener). It retrieves the rows of the
range and calls updateValuesFromRows() on the control binding. The control binding takes the
data out from the rows and assigns them to the controls using Swing API. This updates the
panel UI with the data.
Updating Data through Controls
The user's interaction with a JClient-bound control may result in updating of data through BC4J
APIs. Let's take textFieldDname (TextField) for an example. If the user edits its content and
leaves the control (generating focusLost event), JClient is notified of the event. It retrieve the
updated data from the control and calls setAttribute() on the row.
8-163
JClient provides model objects for Swing controls that are responsible for marshalling
interaction between the Swing controls and the business component datasource's rowset
iterator. The JClient implementation of Swing models are known as control bindings.
The UI components in the JClient application bind directly to view objects in the BC4J tier. For
example, a JClient databound panel, might have a text field (JTextField) for the First name and
Last name that allows the user to view and modify business component attribute values.
The type of control binding used for a given Swing control depends on the actions performed by
the control. In some case, controls work with multiple control bindings that define different
interactions. JClient defines these models for the various controls:
● JClient Action model:

❍ JButton
● JClient Attribute model:

❍ JEditorPane
❍ JPasswordField
❍ JProgressBar
❍ JScrollBar
❍ JSlider
❍ JTextArea
❍ JTextField
❍ JTextPane
❍ JUImage
❍ JULabel
● JClient Attribute List model:

❍ JTable
● JClient Boolean model:

❍ JCheckBox
❍ JRadioButton
❍ JToggleButton
8-164
● JClient Enumeration model:
❍ JComboBox
❍ JList
● JClient LOV (List of Values) model:

❍ JButton
❍ JComboBox
❍ JList
● JClient Tree Node model:

❍ JTree
● JClient Navigate model:

❍ JComboBox
❍ JList
❍ JUNavigationBar
● JClient View Object model:

❍ JProgressBar
❍ JScrollBar
❍ JSlider
❍ JUNavigationBar
❍ JUStatusBar
Related topics
Adding Controls to a JClient Data Panel

Setting a JClient Control Binding
See also
8-165
8-166
Using a Data Form
When a data form has been deployed to a client machine, users can use it to display and
manipulate data in the form. This figure shows an example of a JClient data form displayed in a
frame window.
At the top of the form is a menu bar. Below the menu bar is a navigation bar that controls the
navigation of data in the master table. A navigation bar at the bottom of the form allows users to
navigate and interact with the detail table.
In this example, the master table is the Department table. Several data bound text field controls
represent columns in the Department table and display DEPTNO, DNAME, and MGRNO. The
form uses a data bound grid control to display data from the detail Employee table.
When data is entered in the Department Id field, the data form uses the master-detail
association between the Department and Employee tables to locate data that is displayed in
the grid control. The columns from the detail table displayed in the grid control are EMPNO,
FIRSTNAME, LASTNAME, and EMAIL. Finally, the form contains a status bar that provides
status about the data displayed on the form.
Navigating a Rowset in a Data Form

8-167
The following table highlights the actions you can take using the navigation bar to interact with
a data form.
To perform this action: Click:
Navigate through data in a form (first, previous, next, last).
Insert data in a row below the selected row.
Delete a selected row.
Save changes to the database.
Undo changes made in a form.
Toggles the behavior of the panel to support find mode or not. In find mode, you use the
panel to enter parameters to modify the query.
Executes the query associated with the panel. When the panel is set to use Find mode,
this executes a query by example.
8-168
A master-detail relationship is an association between two or more datasources defined in a
Business Components data model. You can generate JClient forms which rely on those master-
detail relationships. The values in the master form determine which detail records will be
displayed.
Within a Business Components data model you can define the following types of master-detail
relationships:
● Master form to detail form

● Master form to multiple detail forms
● Cascading master-detail relationships (master-detail-detail forms)
8-169
The JClient oracle.jbo.uicli.jui package includes the following classes which are related to the
databound Graph:
● JUGraphBinding
● JUSingeTableGraphBinding
● JUMasterDetailGraphBinding
Note: JClient applications use the Oracle Business Intelligence (BI) Beans Graph bean to draw
graphs with Business Components view objects as their datasource. Although you do not need to
install the BI Beans JDeveloper addin component to use JClient graphs, you may want to install the
addin to view the available documentation. All the features of the BI Bean Graph bean are available
when you use the JClient Graph Wizard to generate a databound graph.
In JClient you add the BI Graph bean to your application through the JClient Graph Wizard. In
order to use the JClient Graph Wizard, your workspace must contain a business components
project with a data model specifically designed for use by the Graph bean. To understand the
selections you make in the wizard, you must understand how the Graph bean obtains sufficient
data from your business components datasources to:
● Plot each graph marker (as determined by up to three data points)

● Label each graph group; for example, the months of the year
● Draw either a single series or a multi-series type graph
● Label each graph
Purpose of the JClient Graph Wizard
The JClient Graph Wizard generates a panel with a Graph bean of the type you select. The
JClient panel binding and the control binding are determined in the wizard by the client data
model and view object attributes you select.
The JClient Graph Wizard helps you choose view objects and attributes for a particular graph
type, but you must be familiar with the data model in order to make the specific choices. In
general, when you make a graph type selection, the wizard displays one attribute choicebox for
each data point value needed to draw the markers for your graph choice. If you select a group
type graph, the wizard also prompts you to choose a view object accessor that links the master
view object with the correct detail view object.
8-170
For instance, if you want to plot a Hi-Lo Stock graph type for multiple stocks, in the wizard you
must choose:
● The master view object that contains one row for stock type
● The detail view object that contains the rows corresponding to the data of each stock
● The attribute from the master view object that specifies the label for each stock graph
● One attribute from the detail view object for each marker data value (in this case, Hi,
Low, and Close)
Whereas, if you decide to plot a single stock as a simple bar graph that shows monthly high
values, in the wizard you must choose:
● A unconstrained view object (one that does not belong to a master-detail relationship)
● One attribute that provides the label for each month
● One attribute for the marker data value (in this case, Hi value only)
The following section describes the business components data model requirements in detail.
Business Components Data Model for Graphs
It is helpful to understand how the JUGraphBinding interprets the data from the business
components view objects. In general, the requirements of the data model for your business
components project depend on:
● Whether the graph type you select requires one, two, or three data point values to
determine each graph marker
● Whether you want to plot a series (single table) or a group type (master-detail) graph
For example, let's assume a simple graph, such as a Bar graph with the following data is
desired:
ENAME SAL Comm

KING 1000 200
CLARK 2000 100
MILLER 1500 50
8-171
Each row in this table will correspond to a Series in the graph and each column corresponds to
a Group.
Some types of graphs, like the Bar graph, require one value per marker. This is in contrast to
other graph types, like the Stock HLC graph, which require three values per marker (high, low
and close). When your graph requires multiple data values, it is convenient to store them in
separate rows in your database table:
Date High Low Close

10 Jan 00 11 10 11
11 Jan 00 11 7 9
12 Jan 00 9 10 9.5
The JClient control binding JUSingleTableGraphBinding supports the type of graph whose data
is stored in a single table. When your graph requires multiple values, then the data for the chart
should be modeled as a master/detail relationship. Each detail provides one series of data,
corresponding to the master value. In the Stock graph example above, the data model could
look like this:
Master table
stock_ticker_table
-------------------------
ticker symbol
Oracle Corporation ORCL
XYZ Corporation XYZ
Detail table
stock_price_table
-----------------------------------
ticker Date High Low Close
ORCL 10 Jan 00 31 30 31
ORCL 11 Jan 00 31 27 29
ORCL 12 Jan 00 29 28 28
XYZ 10 Jan 00 10 9 9
XYZ 11 Jan 00 10 9 9
XYZ 12 Jan 00 10 8 9
In summary, the case of the single-table graph, the data model is simple and need only contain:
8-172
● A standalone view object, where each row plots one graph marker
● One attribute that supplies the label for the groups the graph displays
● One attribute per graph data point, with as many attributes as required to plot each graph
marker
In the case of the more complex group type graph, the data model is based on a master-detail
relationship and must contain:
● A master view object, where each row specifies one series but contains no data
● One master view object attribute that supplies the label for each series
● One detail view object for each series, where each row plots one graph marker for that
particular series
● One detail view object attribute that supplies the label for the groups displayed by the
graph
● One detail view object attribute per graph data point, with as many attributes as required
to draw each graph marker
Related topics
Creating a JClient Graph Panel

Binding a Panel to a JClient Application
8-173
You can add a customizable login dialog to your JClient project that will require a user name
and password to run your application. You add the login dialog class to your JClient project
when you generate a frame to run your JClient application. Two wizards in JClient let you
generate a JFrame with the appropriate JClient bootstrap code:
● JClient Form Wizard - click Use the generated login dialog in the File Names page.
● JClient Empty Frame Wizard - click Use the generated login dialog in the Frame Name
page.
When you run either of these JClient wizards with the generate login dialog option selected,
JDeveloper will:
● Modify the application object constructor in the application bootstrap code to create an
instance of JCLoginDialog:
JUApplication app =
JUMetaObjectManager.createApplicationObject("Project2.Mypackage1Module", null,
new JCLoginDialog());
● Add the JCLoginDialog.java file to your JClient project, which implements the
EnvInfoProvider interface to provide the runtime login dialog. Note, the wizard will not
overwrite an existing JCLoginDialog.java file of the same name.
Because the generated login dialog (JCLoginDialog.java) implements the methods of the
interface, it gives you the starting code that you can modify. Using the JCLoginDialog.java file,
you can customize any aspect of the login dialog:
● Its visual appearance by adding images and changing the layout

● Configuration parameters to connect to the business components application module
● Connection parameters to connect to the database
● Specify the number of times to retry connecting after failing to connect
How Does JClient Behave if You Don't Generate a Login Dialog?
When you run one of the JClient wizards to generate a JClient frame, but do not generate a
8-174
login dialog in your JClient project, you can still run your application one of two ways:
● You can automatically connect to the database without a login dialog

● You can use the JDeveloper-provided default login dialog
As long as you are developing and testing the JClient application in JDeveloper, you probably
want to automate the connection. You can accomplish this by selecting the Deploy Password
checkbox when you use the Connection Wizard to create a new connection. The password and
user name will appear in the business components configuration in the bc4j.xcfg file and the
business components application module will be able to access the connection strings directly
to make the database connection. If you do not select the Deploy Password checkbox in the
Connection Wizard, then the password will be removed from the business components
configuration (in the bc4j.xcfg file).
When you run your application in JDeveloper without deploying the password, JDeveloper uses
a default login dialog (JUEnvInfoProvider) to take the password string. Unlike the generated
login dialog, the default login dialog provided by JDeveloper is not accessible and is not
customizable. The application object constructor in the application bootstrap code creates an
instance of JUEnvInfoProvider:
JUApplication app = JUMetaObjectManager.createApplicationObject(

"Project3.MypackageModule", null, new JUEnvInfoProvider());
About Customizing the JCLoginDialog Code
You generate the JCLoginDialog.java file in your JClient project when you want to modify the
starter code that implements the required methods of the EnvInfoProvider interface. The
interface is used in the business components connection strategy to provide the hooks to
change login parameters at runtime.
The EnvInfoProvider interface expects the following methods to be implemented:
public void modifyInitialContext(Object initialContext)
This method is called before the application creates or finds an application module pool
connection. It passes in a hashtable with all configuration parameters, defining the connection
to the business components. Use this method to modify any of the application module pool
connection parameters at runtime.
public Object getInfo(String info, Object connEnvironment)
8-175
This method is called before connecting to the database. It allows you to update (and return)
the hashtable with all the connection parameters.
Public int getNumOfRetries()
This method determines how many times the business components will attempt to connect
after failing. Each time it will obtain connection information from the EnvInfoProvider.
To provide your own connection strategy, replace the following code:
JUApplication app =
JUMetaObjectManager.createApplicationObject("Project3.MypackageModule", null, new
with
Hashtable mEnv = new Hashtable(2);

mEnv.put(
PropertyMetadata.ENV_AMPOOL_CONNECTION_STRATEGY_CLASS_NAME.pName
"mypackageName.myConnectionStrategy");
JUApplication app = JUMetaObjectManager.createApplicationObject(

"Project3.MypackageModule",
mEnv);
See the business components documentation for more information about connection strategies.
8-176
A parameterized query is a query that contains a placeholder that must be supplied at runtime.
For example, in the following PL/SQL statement, min_salary is a placeholder for a parameter
value that will be supplied at runtime.
SELECT ename, job, mgr FROM emp WHERE sal < :min_salary
In JClient, you can support parameterized queries by using the JUNavigationBar control with
the Find mode enabled. Find mode (enabled by default) lets users use the panel to enter
search criteria. The state of the Find-mode button is controlled by the hasFindButton property
on the JUNavigationBar (true by default).
Users can use the Find mode to refine the search criteria. The panel in Find mode displays
fields for each attribute in the bound view object whose queryable property is set to true. The
view object defines the initial query executed by the business components.
After the results of the initial query are returned and displayed in the data form:
1. The user places the panel in Find mode.
For instance, a user may click the Find button, which is provided by default with a
JUNavigationBar (that is bound to a BC4J view object).
2. The user enters find criteria to restrict the results of the data already returned to the form
3. The Find mode performs an anchored, wild card search.
It uses the first character of the search column as an anchor, where all the strings that
begin with the entered string are matched.
4. Another control the you bind to the same view object in JClient, such as the JTable
control, displays the results of the parameterized query.
The panel used in Find mode, by itself, does not display the results of a parameterized
query. Rather, it is used in association with another databound control.
8-177
In addition to the standard Swing controls that you can use to design JClient applications,
JClient provides its own set of controls. These additional controls are available on the JClient
controls page of the Component Palette:
● JUImage
● JULabel
● JUNavigationBar
● JUStatusBar
● OrdMediaControl
Like the standard Swing controls that they supplement, these controls also rely on the MVC or
Model-View-Controller architecture. The JClient controls are unique because the controllers
they implement to manage end user interactions do not exist among the Swing controls.
Together with the JClient-specific models, the JClient controls allow you to design Java
applications with more diverse databound functionality.
You can set the JClient attribute model on the JUImage, JULabel, and OrdMediaControl
controls to display BC4J attributes. The JUNavigationBar and JUStatusBar controls manage
interactions with BC4J view objects and therefore work with the JClient view model.
Related topics
About the JClient Models for Swing Controls

8-178
About Panel Binding in JClient
You can use JDeveloper's UI Editor to design panels using Swing controls. Later, when you
want your panel to access Business Components for Java (BC4J) datasources, you can add
the panel to a JClient application, where it serves as a data panel. In order to function as a
JClient data panel, the JClient application needs to be able to initialize your panel with the
JUApplication object that your main frame creates. To accomplish this, you must provide your
panel with a JClient panel binding. There are two ways to obtain a panel binding that is specific
to the JUApplication object:
● Generate a frame and layout panel using the JClient Form Wizard
● Modify a standard frame by adding the JClient-specific code
Using the standard frame (that you generate using the New Frame dialog), it is possible to
consolidate your panel with the frame. However, a standard frame must include JClient code to
perform the application bootstrapping (creation of the JUApplication object) and it must contain
code to create the panel binding object. If you use the wizard to generate your frame, it will
already contain all this code. However, in the case of the wizard, it also produces a layout
panel, where the panel binding object is created. When you create simple forms, you may not
require a layout panel, but the layout panel is recommended for anything but the most simple
forms. For a complete discussion of the wizard-generated code, see About JClient Application
Code.
Related topics
About the JClient Application Code

8-179
About Navigation Bar Usage
When you create a default master-detail form using JClient, it will create and place a navigation bar on
both the master and the detail panel, which permits users to scroll through the data in each panel
independently. As an alternative, you can create a single navigation bar which responds to the panel
which has current focus.
In JClient UI you you need to move the code for the navigation bar from the individual panels to the
layout panel where the navigation event will affect all the child panels. For example, you can move the
code from the department and employees data panel to the layout panel.
The code which needs to be removed will be similar to the following:
// The declaration of the navigation bar

private JUNavigationBar navBar = new JUNavigationBar();
// The code which binds the navigation bar to the individual panel.
navBar.setModel(JUNavigationBar.getModelInstance(getPanelBinding(), "DepartmentsView", null,
"DepartmentsViewIter"));
//Add the navigation bar to the panel

add(navBar, BorderLayout.NORTH);
Once you have removed this code you now need to add the control binding to the layout panel which
contains both the master and the detail panels.
//The declaration of the navigation bar

private JUNavigationBar navBar = new JUNavigationBar();
//Bind the model for the navigation bar to the panel

navBar.setModel(JUNavigationBar.getModelInstance(getPanelBinding(),navBar));
//Add the navigation bar to the panel

add(navBar, BorderLayout.SOUTH);
add(masterScroller, BorderLayout.NORTH);
add(detailViewPanel, BorderLayout.CENTER);
About Tree Navigation Usage
When you add a tree control to your panel you create node-populating rules using the property editor
for the JClient node model. The property editor does not allow you to handle node selection. If you
want to handle the node-selection event in order to populate controls in a panel, you can use
8-180
JUTreeDefaultMouseListener to synchronize master and detail panels on the selected node. Here is a
sample to show how to add the listener to the tree control:
myTreeControl.addMouseListener(new JUTreeDefaultMouseListener
( panelBindingVar, new String [][] {
{ "NodeType1" , "DepartmentViewIter" }, "NodeType2" , "EmployeeViewIter" } }
)
);
The listener takes an iterator for each node's bound view object (in this example, DepartmentViewIter
for the DepartmentView view object and EmployeeViewIter for the EmployeeView view object).
Controls that share the same iterator binding as the node, will automatically be populated when the
user selects the node. For example, you might create a tree control in a master panel and the listener
will set the iterator binding, which the detail panel will obtain and use to display attribute values in its
data-bound controls.
Related topics
Setting a Node Control Binding
8-181
About JClient Validation Events
JDeveloper lets you perform validation through:
● Rules as part of your business components

● On UI activity
Through the JClient UI you set rules on the UI which prevent users from entering erroneous
data. For example, you may want to prevent alpha characters from being input to a field which
requires a telephone number. Similarly you may want to validate the data entered and inform
the user. This topic describes how perform client-side validation on the JClient UI.
Validating Every Keystroke
This example can be extended to cover various flavors of validation but basically allows
validation at each key press. To do this you define your validation code as a PlainDocument
event and then use the setDocument() method to register the code with the specific
control. Then the call to setDocument() on the control you bound to the BC4J attribute item
works with the document which contains the validation code.
//Add this code to create a document with the validation code and set it for the control
mDeptno.setDocument(new javax.swing.text.PlainDocument()
{
public void insertString(int offs, String str, javax.swing.text.AttributeSet a) throws
javax.swing.text.BadLocationException
{
StringBuffer buf = new StringBuffer(str);
int size = buf.length();
char c;
for (int i = 0; i < size; i++)
{
c = buf.charAt(i);
if (!Character.isDigit(c))
{
Toolkit.getDefaultToolkit().beep();
buf.deleteCharAt(i);
}
}
8-182
super.insertString(offs, buf.toString(), a);
}
});
/*Here is the code that is generated for you which will set the control binding for the
document. This will work with the document you defined above. */
mDepartmentId.setDocument(JUTextFieldBinding.createAttributeBinding(getPanelBinding(),
mDepartmentId, "DepartmentsView", null, "DepartmentsViewIter", "DepartmentId"));
Validating at the JClient Panel
The panelBinding object, which is responsible for managing the link between the UI and the
business components, can trigger an event on an action. This type of validation allows you to
handle validation when the user inputs data into a field and then navigates to a different field.
You may want to perform validation at the panel which should notify the user, without breaking
a business rule as defined in the business components.
For example, consider a salary which has a range of 100 up to 1000 defined in the business
components. If the salary field is set to anything less that 500, you want to alert the user and
highlight the field. In this case, you want to validate when the value is being set. The
panelBinding object will trigger an event when beforeSetAttribute() is called.
To set validation on the JClient panel:
1. Open the desired panel in the UI Editor.

2. In the Structure window, select Other then Panel Binding object.
3. In the Property Inspector for the Panel Binding, define an event name for
beforeSetAttribute.
4. Add the following code to the generated event handler:
if (e.getAttributeName().equals("Salary"))
{
Object val = e.getNewValue();
if (val != null)
{
Integer n = new Integer(val.toString());
if (n.intValue() < 500)
{
8-183
mSalary.setBackground(Color.red);
throw new oracle.jbo.JboException("That's a bit low!");
}
}
}
8-184
About JClient Compatibility with DAC
This topic provides a brief overview of the migrating a Java client application built using the
Data-Aware Components (DAC) technology from releases prior to Oracle9i JDeveloper, to the
present JClient technology for Java clients.
Benefits of Migration
In JDeveloper 2, Oracle introduced a series of Swing-based controls which could be bound to

data sources. These specialized controls were known as Data-Aware Controls. DAC was
designed to utilize InfoBus which was a standard being developed by Sun. InfoBus did not
become a popular standard and customers indicated that the benefits of InfoBus are
outweighed by the complexity of the controls.
Because of these issues, Oracle9i JDeveloper provides an improved way of creating Java UIs -
JClient. JClient is the next generation of Java client for BC4J support in Oracle9i JDeveloper,
which works by using a set of customized models based on the JFC/Swing default models.
Oracle9i JDeveloper still offers support and bug fixing for the DAC controls and frames; so you
are able to open a JDeveloper 3.2 DAC project and use the Oracle9i JDeveloper IDE to edit,
compile, debug, and test your applications. However, using the UI Designer for DAC
applications or applets will not be supported in Oracle9i JDeveloper.
If you wish to upgrade your DAC application to JClient you can run the migration tool described
in the migration guide available on the Oracle Technology Network (OTN):
http://otn.oracle.com/products/jdev/howtos/JClient/jclient_migration.html
For more information read the Java Client Statement of Direction at this page on OTN:
http://otn.oracle.com/products/jdev/htdocs/JavaClientSOD.html
As an alternative to running the migration tool, you can gradually migrate your DAC application
by combining DAC and JClient components. The steps to gradually migrate your DAC
application are addressed in this TechNote, Using a JClient Connection in DAC Applications,
also on OTN.
What Does the Migration Tool Do
The first step is to understand what the migration tool will do. Starting with a DAC project, the
8-185
migration tool will convert your DAC project to a JClient project. The following steps outline the
migration process.
1. Get the SessionInfo, AttributeInfo and RowSet info from DAC code and generate the new
JClient data model.
2. Get information on all the DAC controls, and generate the new JClient or Swing controls
based on the JClient data model.
3. Take all other code from the DAC project and copy it into the new code.
The migration tool will replace any instance of the DAC control with the corresponding JClient
control. For example, for a text field and a navigation bar, the migration tool will replace the
following DAC object with the indicated JClient object.
8-186
Java Web Start is a new application deployment technology created by Sun Microsystems, Inc.
JDeveloper supports the creation of the XML-based JNLP (Java Network Launching Protocol)
definition upon which the Java Web Start technology is based. With Java Web Start and the
JClient Java Web Start Wizard in JDeveloper, you can set up JClient applications and applets
to be maintained on the web server, but downloaded and run on client machines.
Note: You must download and install the Java Web Start software from the
http://java.sun.com/products/javawebstart/ web site to launch JClient applications with Java Web
Start in JDeveloper. Users of your JClient application will also be required to install the software on
their machines.
Purpose of the Java Web Start Technology
Although Java Web Start relies on a web server to distribute the client-side application and
users use their web browser (or Java Web Start) to initiate the downloading of the application
onto their machines, the Java Web Start approach differs from the applet approach to
deploying web-centric Java applications.
Here is a description of the technologies involved:
● Web Server stores the JNLP files, JAR files for client, middle tier, and runtime libraries.
● Application Server, optional, needed only if the middle tier runs remotely with respect to
client. For example, in the case of EJB session bean.
● Java Web Start downloads JNLP, then the dependent resources and then launches the
application or applet. Java Web Start can also run independently without the browser,
using a command like:
javaws http://localhost/myapp/test.jnlp
● Web Browser, optional, but convenient to launch Java Web Start and initiate the
download. Used when an HTML file contains a link to the JNLP file. The user follows the
link, which behind the scenes causes Java Web Start to run.
If your JClient application needs to interact tightly with a web browser, then applets are
appropriate. Though it is possible to handle JClient applets exactly the same way in Java Web
Start, with one exception: Java Web Start applets (and applications) are not tied to the web
browser. Once the application is running, the web browser can be closed, and the application
8-187
continues to function.
With the Java Web Start software install once on the user's machine, individual users can run
JClient applications and applets simply by clicking on a web page link. If the application is not
present on their computer, Java Web Start automatically downloads all necessary files from the
web server where the application libraries reside. It then caches the files on the client computer
so the application is always ready to be relaunched anytime either from an icon on your
desktop or from the browser link. The most current version of the application is always
presented to the user since Java Web Start performs updates as needed.
Files Generated by the JClient Java Web Start Wizard
Users can use Java Web Start to run JClient applications and applets on client machines, while
you maintain the application on the web server. To support downloading of files from the web
server, the JClient Java Web Start Wizard generates:
● Deployment profiles to deploy the business components and JClient class files and
libraries to the web server.
● The Java Network Launching Protocol (JNLP) definition required by Java Web Start to
download and launch the application.
Note: Your application can dynamically create the JNLP definition if you use a web browser
to launch a generated JSP file. Choose JNLP generated dynamically - JSP in the JClient
Java Web Start Wizard.
When you run the wizard, these files will be added to your JClient project:
● bc4jlibs.ear profile, which you use this profile when you are ready to deploy to the OC4J
web server to set up the context roots for the various runtime libraries required by the
JClient application.
● client profile, you use the profile to create a simple Java Archive (client.jar) file that
contains the JClient application source files.
● mymt profile, you use this profile to create a Zip archive (mymt.zip) file that contains the
business components source files.
● client_war profile, which you use to deploy to the OC4J web server the contents of the
public.html directory in your JDeveloper mywork folder: it therefore contains the client.jar,
mymt.zip, and JNLP files.
Additionally, one of these two sets of JNLP definitions is generated depending on the selection
8-188
you make in the JClient Java Web Start Wizard:
● xxx.jsp, (not generated if you select Static JNLP in the JClient Java Web Start Wizard)
lets you dynamically generate the JNLP file that describes the client and business
components archive files and whether the JClient is an applet or an application.
● xxxmt.jsp, (not generated if you select Static JNLP in the JClient Java Web Start Wizard)
an extension to the first .jsp file. Dynamically generates the JNLP file that describes the
business components runtime libraries required for a specific deployment scenario.
OR
● xxx.jnlp, (not generated if you selected JNLP generated dynamically - JSP in the JClient
Java Web Start Wizard) a static JNLP file that describes the client and business
components archive files and whether the JClient is an applet or an application.
● xxxmt.jnlp, (not generated if you selected JNLP generated dynamically - JSP in the
JClient Java Web Start Wizard) an extension to the first .jnlp file. A static JNLP file that
describes the business components runtime libraries required for a specific deployment
scenario.
Running with Java Web Start Using JDeveloper's Embedded Web Server
JDeveloper provides an embedded-OC4J web server. You can use it to simulate the process of
deploying the Web Application Archive and downloading for use with Java Web Start.
JDeveloper follows the J2EE deployment profile conventions for archiving components that run
on the client machine (simple archive) and components that are deployed to the web server
(Web Application Archive).
Note: When you want to run your JClient application using Java Web Start within JDeveloper, use
the default local deployment runtime configuration. The local deployment runtime configuration
eliminates potential security conflicts that can occur in the remote deployment runtime configuration.
Later, when you want to deploy the Business Components to a remote OC4J or VisiBroker web
server, granting security permissions in the JNLP file and signing your JAR files may be necessary.
Instructions to sign JAR files is available among the JDeveloper TechNotes on the Oracle
Technology Network (OTN): http://technet.oracle.com/docs/products/jdev/technotes/listing.htm.
When you run the JClient Java Web Start Wizard, you will generate these deployment profiles
to complete the JDeveloper setup:
● Use the client profile to create a simple Java Archive (client.jar) file that contains the
JClient application source files to be downloaded and run on the client machine
● Use the mymt profile to create a Zip archive (mymt.zip) file that contains the business
8-189
components source files to be downloaded and run on the client machine
Note: You will not be required to deploy the generated client_war to use the JDeveloper-embedded
web server. JDeveloper provides a default web.xml definition to locate the contents of the
public.html directory in your JDeveloper mywork folder.
Once you have setup the web server, you can launch the Java Web Start software in
JDeveloper using the generated .html file. Java Web Start relies on your web browser to
download the components identified by the .jnlp file. Another definition in the .jnlp file
determines whether the JClient is to run as an application or a secure applet. Once you have
launched Java Web Start and the downloading is complete, you can close your web browser
and continue to run the application or applet.
Deploying to an OC4J Web Server
One of the files that appears in your JClient project when you run the JClient Java Web Start
Wizard is bc4jlibs.ear. You use this profile to setup the context roots for various runtime
libraries required by the JClient application on the OC4J web server. These libraries are
required to run the application and they have to be accessible through HTTP. (One context
root, for example, is BC4J and this enables bc4jmt.jar to be downloaded as
http://mymachine:8888/BC4J/lib/bc4jmt.jar).
Deploying a JClient application is a two step process.
1. Setup the runtime libraries so that Java Web Start can download through HTTP.
2. Deploy the application-specific classes.
In your JClient project in JDeveloper, you deploy bc4jlibs.ear for the first step. While deploying
the generated client_war file takes care of the second step.
Related topics

Running JClient Applications with Web Start in JDeveloper
Deploying a JClient Web Application Archive for Java Web Start
About the Embedded OC4J Configuration Files in JDeveloper About OC4J Deployment
8-190
Application Directory Structure
See also
For more information on Java Web Start go to this java.sun.com web page:
8-191
You can use the JClient wizards to quickly build data forms bound to business component
datasources. These topics describe the process:
● Defining Business Component Runtime Properties for JClient Applications

● Creating a Client Data Model Definition
● Creating Single Table JClient Forms
● Creating Master-Detail JClient Forms
Related topics
8-192
Defining Business Component Runtime Properties
in the bc4j.xcfg File for JClient Applications
When you run databound JClient data forms to access business components, your business
components project must contain a runtime configuration (bc4j.xcfg) file that specifies the
application module connection for your business component deployment scenario.
You will choose the runtime configuration definition you create for your JClient project:
● In the JClient Data Form Wizard when you select an application module
Later, you can edit the runtime configuration for your JClient project:
● To update the connection information when you change or create a new business
components deployment scenario
Note: If you do not create an application module runtime configuration, the bc4j.xcfg file in your
business components project defines a default configuration that lets you run JClient data forms
within JDeveloper. The default configuration local is also known as local mode deployment because
it assumes the the business components and the JClient application run in the same VM.
To create a configuration:
2. Click New.
3. Choose the middle-tier server type and a previously defined connection, as described in
the F1 Help for the Application Module tab.
To edit a configurations file:
2. To edit a configuration in the Configurations Editor dialog, select the configuration to edit
8-193
from the list and click Edit.
3. Choose the middle-tier server type and a previously defined connection, as described in
the F1 Help for the Application Module tab.
4. Compile the business components project.
Related topics
8-194
JClient applications require a client data model definition to connect to business component
datasources. You use the JClient Data Model Wizard to add one or more client data model
definitions to the client project configuration (.cpx) file.
Note: JDeveloper updates several application libraries based on the most recently saved data
model definition. If you create or edit a data model definition, but want to run your project with a
different data model definition, then you must open the desired data model definition in the JClient
Data Definition Wizard as described below and save it; this action will result in the generation of the
appropriate classes.
To create a business components project:
1. Create a project for your business components.
In order to define a client data model, you must first create a project with a business
components application module.
To create a client data model definition on a new JClient project:
1. Create a project for your JClient application.
2. Choose File | New to locate the JClient Data Model Wizard in the New Gallery.
Note: You can also launch the JClient Data Model Wizard within the JClient form, frame, and
panel wizards when you want to use those wizards and define the data model at the same
time.
3. Choose JClient Data Model from the JClient Object category and click OK.
4. In the Name page, enter a name to identify the data model and click Next to view the
Application Module page.
5. In the Application Module page, select the application module and configuration that you
want to use for your client data model definition and click Next.
8-195
Click the wizard Help button for additional help.
6. Click Finish.
To add a client data model definition to an existing JClient project:
1. In the Navigator, expand the JClient project for which you want to add a data model
definition.
2. Click the client project configuration (.cpx) file and choose New ClientDataModel to
launch the JClient Data Model Wizard.
3. In the Name page, enter a name to identify the data model and click Next to view the
Application Module page.
4. In the Application Module page, select a different application module or configuration that
you want to use for your client data model definition and click Next.
5. Click Finish.
6. Edit references to the data model in the JClient application code.
To edit a client data model definition in an existing JClient project:
1. In the Navigator, expand the JClient project for which you want to edit a data model
definition.
2. Click the client project configuration (.cpx) file and view the file in the Structure window.
3. Right-click the desired data model definition node in the Structure window and choose
Modify Client Application Model.
4. In JClient Data Definition Wizard, modify the data model and click Finish to save the
changes.
8-196
Related topics

8-197
Creating Single Table JClient Forms
You can use the JClient Form Wizard to quickly create a single table form derived from the data
model of an existing business components project.
In order to use business components with your data forms, you must first create a project
with a business components application module.
To create a JClient project with single table data forms:
2. Choose File | New to locate the JClient Form Wizard in the New Gallery.
3. Choose JClient Form Wizard from the JClient Object category and click OK.
4. In the Form Type page, the data form type Frame appears preselected for use in an
application. If you want to create an applet, choose data form type Applet.
5. Also in the Form Type page, select Single Table and click Next and make selections to
define the form appearance.
6. In the Data Model page, select an existing client data model or click New to create a data
model definition you wish to develop against and click Next.
In the following pages, make selections appropriate to specify the data your form is to
display. Click the wizard Help button for additional help.
7. Click Finish.
8-198
Related topics
8-199
Creating Master-Detail JClient Forms
You can use the JClient Form Wizard to quickly create master-detail forms derived from the
data model of an existing business components project.
with a business components application module that defines master-detail relationships.
To create a JClient project with master-detail data forms:
2. Choose File | New to locate the JClient Form Wizard in the New Gallery.
3. Choose JClient Form Wizard from the JClient Object category and click OK.
4. In the Form Type page, the data form type Frame appears preselected for use in an
application. If you want to create an applet, choose data form type Applet.
5. Also in the Form Type page, select Master-Detail and click Next and make selections to
define the form appearance.
6. In the Data Model page, select an existing client data model or click New to create a data
model application module you wish to develop against and click Next.
In the following pages, make selections appropriate to specify the data your forms are to
7. Click Finish.
8-200
Related topics

8-201
After you generate data forms using the JClient Forms Wizard, you may want to customize the
generated application files. JDeveloper helps you customization the application, through a
combination of other JClient wizards, code editor, UI editor, Component Palette, and Property
Inspector. These topics describe modifying a JClient application:
● Changing Client Data Model References

● Creating a New JClient Data Panel
● Creating a JClient Graph Panel
● Adding Controls to a JClient Data Panel
● Setting a JClient Control Binding
● Binding a Panel to a JClient Application
Related topics

Working with Containers and Components
8-202
You can edit your application code to change the data model definition it will use to connect to your business component
datasource. You might want to do this because you had been using a local configuration to test your application in
JDeveloper and you now want to change to a data model definition that uses a remote deployment configuration.
To reference the new client data model definition in the JClient application code:
1. Add a new client data model definition to the .cpx file in your JClient project and remember the name you chose
(for example, remotedatamodel).
2. Open the main frame or applet class in the code editor and edit the bootstrap code to use the new data model
name:
// bootstrap for application

JUMetaObjectManager.setBaseErrorHandler(new JUErrorHandlerDialog());
JUApplication app =
JUMetaObjectManager.createApplicationObject("MyJClientProj.LocalClientDataModel",
null, new JUEnvInfoProvider());
// bootstrap for applet

java.util.Properties props = new java.util.Properties();
props.put(JboContext.USE_APPLET, this);
JUApplication app =
JUMetaObjectManager.createApplicationObject("MyJClientProj.LocalClientDataModel", props, new
3. Open the layout panel in the code editor and edit the panel binding code:
// BC4J binding variable

private JUPanelBinding panelBinding = new
JUPanelBinding("MyJClientProj.LocalClientDataModel",
this);
Related topics
About the Client Project Configuration

About the Frame and Applet Class in JClient
About the Layout Panel in JClient
8-203
Creating a New JClient Data Panel
You can use the JClient Panel Wizard or the JClient Empty Panel Wizard to quickly create a
single table form. While the JClient Panel Wizard generates a complete data form that you can
add to your application, the JClient Empty Panel Wizard contains no control bindings. Both
wizards generate the code needed to initialize a JClient panel binding.
After you add the new panel class to your JClient project, you can modify the application code
to display the panel from an existing panel.
To create a Business Components project:
with a Business Components application module.
To add single table data form using the JClient Panel Wizard:
1. In the Navigator, click on the JClient project to which you want to add the data form.
2. Choose File | New to locate the JClient Panel Wizard in the New Gallery.
3. Choose JClient Panel Wizard from the JClient Object category and click OK.
4. In the Template Selection page, choose the layout of the form.
5. In the Data Model page, select the same client data model used by your application's
other data forms and click Next.
In the following pages, make selections appropriate to specify the data your form is to
6. Click Finish.
8-204
To add a data panel using the JClient Empty Panel Wizard:
1. In the Navigator, click on the JClient project to which you want to add the empty data
panel.
2. Choose File | New to locate the JClient Empty Panel Wizard in the New Gallery.
3. Choose JClient Empty Panel Wizard from the JClient Object category and click OK.
4. In the Data Model page, select an the same client data model used by your application's
finished data forms and click Next.
5. Supply a class name for the new empty panel and click Finish.
6. You can open the new panel class in the UI Editor and add the desired controls.
To link the completed data form with your application:
After you have created a new JClient data panel, you can reuse the panel in your application
by:
● Adding it to an existing layout panel (for instance, the one created by your main frame)
● Creating a new frame using the JClient Empty Frame Wizard and adding it there
8-205
You can use the JClient Graph Wizard to quickly create graphs that work with BC4J
datasources. While the wizard generate the code needed to initialize a JClient panel binding,
you will need to modify the application code to display the panel from a new or existing frame in
your JClient application.
Important: The JClient Graph Wizard requires a particular data model for the BC4J datasources to
obtain the graph data. For details about the business components data model, see About the JClient
Graph Panel.
To create a Business Components project:
with a Business Component application module.
To add graph using the JClient Graph Wizard:
1. In the Navigator, click on the JClient project to which you want to add the graph panel.
2. Choose File | New to locate the JClient Graph Wizard in the New Gallery.
3. Choose JClient Graph Wizard from the JClient Object category and click OK.
4. In the Graph Type page, choose the type of graph to create and click Next.
5. In the Data Model page, select the same client data model used by your application's
other data forms and click Next.
In the following pages, make selections appropriate to specify the data your graph is to
6. Click Finish.
8-206
To link the completed graph panel with your application:
After you have created a new JClient graph panel, you can reuse the panel in your application
by:
● Adding it to an existing layout panel (for instance, the one created by your main frame)
● Creating a new frame using the JClient Form Wizard and add it to the generated layout
panel
Related topics

8-207
You can customize a generated data panel by adding more complex Swing controls from the
Component Palette.
To add a control to a JClient data panel:
1. In the Navigator, expand the JClient project and right-click the data panel you want to
customize.
2. Choose UI Editor to view the data panel.
3. If the Component Palette is not visible, choose View | Component Palette to display the
list of Swing controls.
4. From the Component Palette dropdown menu choose the control category that has the
control you want to add.
5. Click the control and click on the data panel in the UI editor to add the control.
6. If you add a control from the Swing, Swing Container, or JClient Control categories, you
can proceed to define a control binding for a BC4J datasource.
Related topics
8-208
When you add Swing, Swing Container, or JClient controls to your data panel, set the control's
model property to define a control binding that permits the control to work with a BC4J
datasource.
To define a BC4J control binding:
1. Open the data panel in the UI editor and add a Swing, Swing Container, or JClient
control from the Component Palette.
2. If the Property Inspector is not visible, choose View | Property Inspector control
properties.
3. In the UI editor, click the control for which you want to define a control binding.
4. Locate the model or document property in the Property Inspector and click on the field to
display the list of available models.
Note: The list contains both standard Swing models and JClient models that let you
define a BC4J control binding for the Swing component.
5. If you have already created a BC4J control binding, the model field displays your named
control binding. You can open the property editor with your previously saved control
binding settings by clicking the ... (ellipses) button next to the named binding.
6. If you want to create a new BC4J control binding, you can open the property editor
directly by selecting the desired JClient model from the list. The model property editor
opens with no previously saved information.
Note: If you open the model property editor and you do not want to overwrite your
previously saved control binding, select Cancel to close the property editor.
7. Click the Help button to get reference information about the editor or see Working with
JClient Models for detailed procedures for each model type.
8-209
Related topics

8-210
You can use JDeveloper's UI Editor to design panels using Swing and JClient-specific controls.
Later, when you want your panel to access Business Components for Java (BC4J)
datasources, you add the panel to a JClient frame by reusing a JClient panel binding that your
JClient application creates. There are two ways to reuse an existing panel binding:
● Generate a frame and layout panel using the JClient Form Wizard
● Modify a standard frame by adding the JClient-specific code
This procedure does not discuss the JClient-specific code, though you can get this information
from topics in the related topics list below.
To binding a panel to your JClient application:
Construct the frame with the new panel using the constructor that passes in the Panel Binding
object. To create a new instance of the screen and make it visible you need to add the following
code to the event handler for the action that opens the frame:
FrameMyNewView frame = new FrameMyNewView(getPanelBinding());

frame.setVisible(true);
The getPanelBinding() method allows you to share the Panel Binding from application, allowing
the Iterator Bindings to be shared across forms/panels. The new frame will automatically be
sync'ed with the Navigation Bar and Status Bar in the first detail of the master-detail frames.
To define an action to open the frame:
When you perform an action at the user interface such as clicking on a button, an event is
issued. Events are objects that describe what happened and are only reported to registered
listeners. JDeveloper generates all of this code for you. You must supply the code to initiate the
desired action when the button is clicked.
1. Select the button in the UI editor.

2. Click the Events tab of the Property Inspector.
3. Type the name of the function you want executed whenever the button is clicked in the
space next to actionPerformed and press the Enter key. You will be automatically be
taken to a stub of your function in the code editor.
4. Create an object of the form you want to display and set its visible property to true:
8-211
FrameMyNewView frame = new FrameMyNewView(getPanelBinding());
frame.setVisible(true);
Related topics
About the JClient Application Code

About Panel Binding in JClient Application
8-212
In order to create databound controls, you must set the model property on a Swing, Swing
Container, or JClient control to use one of the JClient-specific models in place of a standard
JFC model. In some cases, you may choose from a list of several JClient models to support
different behaviors on the control. This section describes how to set these JClient control
bindings:
● JClient Action control binding:

❍ JButton
● JClient Attribute control binding:

❍ JEditorPane
❍ JPasswordField
❍ JProgressBar
❍ JScrollBar
❍ JSlider
❍ JTextArea
❍ JTextField
❍ JTextPane
❍ JUImage
❍ JULabel
● JClient Attribute List control binding:

❍ JTable
● JClient Boolean control binding:

❍ JCheckBox
❍ JRadioButton
❍ JToggleButton
● JClient Enumeration control binding:

❍ JComboBox
❍ JList
● JClient LOV (List of Values) control binding:

❍ JButton
8-213
❍ JComboBox
❍ JList
● JClient Tree Node control binding:

❍ JTree
● JClient Navigate control binding:

❍ JComboBox
❍ JList
❍ JUNavigationBar
● JClient View Object control binding:

❍ JProgressBar
❍ JScrollBar
❍ JSlider
❍ JUNavigationBar
❍ JUStatusBar
Related topics

8-214
Setting an Action Control Binding
You can set a control binding using the JClient action model on any of these Swing controls:
● JButton
An action control binding lets users initiate a specific action on the rows of a view object. You
use the model Property Editor to choose the action and view object. The list of available view
objects is determined by the client data model. Possible actions you can specify on a view
object include:
● Move to the first, next, previous, or last row in the view object's range.
● Delete the current row.
● Reset data from the view object cache on all rows.
● Execute the view object query to get the latest data from the database.
When users initiate the action on the control, the bound view object is immediately updated.
The UI reflects the change through any control bindings that use the same view object as the
action binding.
To set an action control binding:
1. Open the data panel in the UI editor and add one of the desired Swing control to the
panel.
2. Display the model property editor for the control and select JClient Action Binding from
the list.
3. In the View Object list, select the view object on which you want to perform the action.
Hint: Add controls to your data form to display the results of the action on the view object.
Those controls need only set a control binding on the same view object as the action binding
to reflect the action in the UI.
4. In the Action dropdown menu, select the action to perform on the selected view object.
5. Click OK to save the property settings.

8-215
6. JDeveloper adds code to the class file to bind a JButton control to the view object and
specify an action:
myJButton.setModel(JUButtonBinding.createActionBinding(getPanelBinding(),
myJButton, "MyViewObject", null, "MyVOIter", JUActionBinding.ACTION_NEXT));
Related topics
8-216
Setting an Attribute Control Binding
You can set a control binding using the JClient attribute model on any of these Swing and JClient (JU)
controls:
● JEditorPane (document property)

● JPasswordField (document property)
● JProgressBar
● JScrollBar
● JSlider
● JTextArea (document property)
● JTextField (document property)
● JTextPane (document property)
● JUImage
● JULabel
Note: Some Swing controls use the document property to set a control binding as indicated in the above
list.
The behavior of the attribute control binding depends on the type of control used. Users may view
and, in some cases, edit the value of a single attribute defined by a view object. You use the model
Property Editor to select the view object and attribute. If the control is an editable field, you should
make the attribute updateable by setting a control hint in the Business Components project for that
attribute.
To set an attribute control binding:
1. Open the data panel in the UI editor and add the desired Swing or JClient control to the panel.
2. Display the model or document property editor for the control and select JClient Attribute
Binding from the list.
3. In the View Object list, select the view object that contains the attributes the form displays.
4. In the Attribute list, select a single attribute to display as the value of the control.
5. In the case of a JProgressBar, JScrollBar, or JSlider control, you can specify a Minimum and a
Maximum value. These correspond to the start and end values supported by the control.
8-217
6. In the case of the JSlider and JScrollBar control, you can specify the Extent or interval between
tick marks. Each tick mark corresponds to a possible value that the user could apply to the
bound attribute.
Note: In the case of the slider and scrollbar, attribute values are calculated by adding the slider's
Minimum value to the product of the Extend value and index of the selected tick mark. For example,
if the Minimum value is 20, the Extent value is 10, and the user has selected the 3rd tick mark in the
slider, then the attribute value would be 20 + (10 x 3) = 50.
8. JDeveloper adds code to the class file to bind the selected control to the view object attribute. In
the case of a control that uses the Document property (like a JTextField), the code looks like
this:
myJTextField.setDocument(JUTextFieldBinding.createAttributeBinding(getPanelBinding(),
myJTextField, "MyViewObject", null, "MyVOIter", "MyAttribute"));
And the code for a control that uses the model property (like a JProgressBar) looks like this:
myJProgressBar.setModel(JUProgressBarAttrBinding.createAttributeBinding(getPanelBinding(),
myJProgressBar, "MyViewObject", null, "MyVOIter", "MyAttribute", 0, 100));
The last two arguments (0 and 100) are the minimum and maximum values for the
JProgressBar.
Related topics
8-218
Setting an Attribute List Control Binding
You can set a control binding using the JClient attribute list model on this Swing control:
● JTable
An attribute list control binding lets users view a table consisting of attribute names (column
headers) and values from a view object. You use the model Property Editor to select the view
object and attributes to display. You can make attribute values updateable by setting a control
hint in the Business Components project on that attribute. In that case, users will be able to edit
the updateable attribute's values directly in the table. Another control hint lets you change the
label displayed by the column header for each attribute.
To set a table control binding:
1. Open the data panel in the UI editor and add the JTable control to the panel.
2. Display the model property editor for the control and select JClient Attribute List Binding
from the list.
3. In model Property Editor, select the view object that contains the attributes you want to
display in the table.
4. In the Available Attributes list, select the attribute to display and add it to the Selected
Attributes list. You may add as many attributes as desired to the Selected Attributes list.
6. JDeveloper adds code to the class file to bind the JULabel to the view object attributes
list:
myJTable.setModel(JUTableBinding.createAttributeListBinding(getPanelBinding(),
myJTable, "MyViewObject", null, "MyVOIter", new String[] {"MyAttribute1",
"MyAttribute2"}));
8-219
Setting a Boolean Control Binding
You can set a control binding using the JClient boolean model on these Swing controls:
● JCheckBox
● JRadioButton
● JToggleButton
An boolean control binding lets users select the control and update an attribute in a view object
based on the control's selection state. You use the model Property Editor to select the view
object and attribute on which you want the control to operate, then specify a true or false value
corresponding to the selection state (true for selected and false for unselected). You must know
what values the bound attribute takes in order to supply meaningful values.
To set an enumeration control binding:
1. Open the data panel in the UI editor and add the desired Swing control to the panel.
2. Display the model property editor for the control and select JClient Boolean Binding
from the list.
3. In the View Object list, select the view object which contains the attribute you want to
update.
4. In the Attribute list, select the attribute to display with the values list.
5. In the True Value field, enter the value the model will use to update the attribute when
the user makes the control appear selected.
6. In the False Value field, enter the value the model will use to update the attribute when
the user makes the control appear unselected.
8. JDeveloper adds code to the class file to bind a JToggleButton control to the view object
attribute and specify a true and false value:
8-220
myJToggleButton.setModel(JUButtonBinding.createBooleanBinding(getPanelBinding(),
myJToggleButton, "MyViewObject", null, "MyVOIter", "MyAttribute", new String[]
{"myTrueValue", "myFalseValue"}, true));
Related topics
8-221
Creating an Enumeration Control Binding
You can set a control binding using the JClient enumeration model on these Swing controls:
● JComboBox
● JList
An enumeration control binding lets users select a value from a display list to update an
attribute in a view object. You use the model Property Editor to select the view object and
attribute on which you want the control to operate, then specify a set of values from which the
user may select. You must know what values the bound attribute takes in order to supply
meaningful choices.
2. Display the model property editor for the control and select JClient Enumeration Binding
from the list.
update.
4. In the Attribute list, select the attribute to display with the values list.
5. Above the Values list, click the insert button to add a value to the list. Type the value into
the empty field. Values you supply must be valid for the attribute.
Related topics
8-222
Setting an LOV Control Binding
You can set a control binding using the JClient LOV (list of values) model on these Swing
controls:
● JButton
● JComboBox
● JList
An LOV control binding lets users choose a value from a list that displays the view object rows
of one or more attributes. When the user makes the selection, the LOV updates one or more
attributes of another view object based on their selection. You use the model Property Editor to
define the source and target view objects, the binding between their attributes, and the
attributes to display in the LOV.
To set a LOV control binding:
1. Open the data panel in the UI editor and add the desired control to the panel.
Hint: Drop the desired JComboBox, JButton, or JList control on the open panel in a position
near the form field that you want to receive the LOV selection.
2. Display the model property editor for the control and select JClient LOV Binding from the
list.
To define the LOV to display:
1. In the model property editor, click the Define the LOV tab and select the view objects you
want your LOV to use:
The LOV view object defines the view object that you want to use to display your list of
values for selection. This should be a view object that is not constrained by a master
view object in the business component data model.
The Target view object is the view object that contains the attribute you want to receive
the selected value in the JClient panel. This should be the same view object that your
panel displays.
8-223
2. Click the Select the LOV Attributes You Want to Display tab and select the attributes
that you want the LOV window to display. You may add as many attributes as desired to
the Selected Attributes list, although you are not required to include the LOV binding
attribute (the attribute that you want to display the selected value).
3. Click the Define the LOV tab again and click Add.
The bottom half of the LOV model editor displays a table with a list of possible LOV
binding attributes between the view object used to display the list of values and the view
object to receive the attribute selection.
4. Choose the attribute from the LOV attributes dropdown that you want to use to supply
the value to the field displayed in the data form.
5. Choose the attribute from the Target attributes dropdown that you want to receive the
value from the LOV.
6. Click Add again to bind multiple attributes through the same LOV.
8. JDeveloper adds code to the class file to bind a JButton control to the target and source
view objects:
myJButton.setModel(JULovButtonBinding.createLovBinding(getPanelBinding(),
myJButton, "MyTargetViewObject", null, "MyTargetVOIter", new String[]
{"MyTargetUpdateAttribute"}, "MySourceViewObject", new String[]
{"MySourceUpdateAttribute"}, new String[] {"MySourceDisplayAttribute1",
"MySourceDisplayAttribute2"}));
Related topics
8-224
Creating a Navigation Control Binding
You can set a control binding using the JClient navigation model on these Swing controls:
● JComboBox
● JList
● JUNavigationBar
A navigation control binding lets users select a navigate through the rows of a view object. You
use the model Property Editor to select the view object. In the case of the JComboBox and
JList controls, you also select the attributes you want to display for navigation.
2. Display the model property editor for the control and select JClient Navigate Binding
from the list.
update.
4. In the case of the JComboBox or JList controls, select the attribute to display from the
Available Attributes list.
Related topics
8-225
Setting a Node Control Binding
You can set a control binding using the JClient node model on this Swing control:
● JTree
A node control binding lets users view a hierarchical list of attributes derived from view object relationships as
specified in the business components data model. You use the model Property Editor to define a set of rules that
determine how the node control binding should traverse the relationships of the view objects you select. In order
for the node control binding to construct a tree with multiple branches, the business components data model
should meet these requirements:
● A starting or root view object that you will use as the control binding target.
● One or more viewlink accessors from that root view object and other view objects. The node model editor
will display an allowable set of viewlink accessors for that node to drill down in to the next level.
Once you create control binding for the tree, you can use the tree control to let users navigate through the rows
of the bound view object. Currently, there is no navigation model for the tree control, instead you need to add a
JUTreeDefaultMouseListener on the control.
To set a node control binding:
1. Open the data panel in the UI editor and add a JScrollPane container to the panel.
2. Add a JTree control to the scrollable pane.
3. Display the model property editor for the JTree control and select JClient Node type from the list.
To define the root node of the tree:
1. In the model property editor, click the Edit rule tab to define the parent node rule to display from the
master view object. For example, a customer's master view object that has an orders detail view object.
2. In the View type definition list, select the view object that you want to use to populate the tree root node.
This is the master view object that defines the root node. For example, a customer's master view object
that has an orders detail view object.
3. In the Attribute definition list, select a single attribute to display as the parent nodes for the tree. For
example, the last name of each customer. Currently, JTree control is limited to displaying a single attribute
for each branch.
4. In the Accessor definition list, select the view link accessor that specifies the link between the master
view object and the first branch in the tree. For example, an accessor for the customers and orders view
8-226
objects, might appear as OrdersView in the list.
Warning: If your data model does not contain view link accessors for the view objects you select, the Accessor
definition list will appear empty. You must define a view link accessor in your Business Components data
model for all nodes of the tree except the leaf (terminal) nodes.
5. Click the Add new rule button to complete the rule definition for the root node.
6. Click the Show rules tab to view the root node rule. For example, in the customers and orders example, it
might appear as:
Viewobject rule: myPackage.CustomersView, CustLastName, OrderView
This rule says: display the CustLastName attribute as the nodes for the root branch of the tree and use
the OrdersView view link accessor to drilldown and display customer orders as the second branch in the
tree. You must now add a rule to define the attributes to display from the orders view object.
To define the branches of the tree:
1. Click the Edit rule tab to define the child-branch attributes rule to display from the first detail view object.
2. In the View type definition list, select the view object you want to use to populate the tree's branch nodes.
This is the detail view object that defines the nodes for the tree. For example, an orders detail view object
from which you will display order id information in the tree.
3. In the Attribute definition list, select a single attribute to display as the branch nodes in the tree. For
example, the last name of each customer.
4. In the Accessor definition list, select the view link accessor that specifies the link between the first branch
view object and the next branch in the tree. For example, an accessor for the orders and orderitems view
objects, might appear as OrderItemsView in the list.
Note: If the branch view object you select has no further accessor defined for it in the Business Components
data model, the word <none> will appear in the list. This means no accessor is required because the selected
view object's attribute will appear as leaf nodes in the tree.
5. Click the Add new rule button to complete the rule definition for the child branch node.
6. Click the Show rules tab to view the root node rule. For example, in the customers and orders example, it
might appear as:
Viewobject rule: myPackage.OrdersView, OrderId, <none>
This rule says: display the OrderId attribute as the nodes for the second branch of the tree. The word
none means there is no accessor because this branch consists of leaf nodes.
8-227
7. You may repeat these steps in the Edit rule tab to define new branches in the tree as long as your data
model supports accessors to traverse the branches.
The model editor performs error checking for the rules you defined. It displays the following error
messages:
❍ "Invalid definition, either no root or no rules defined." Either you did not define a rule or you did not
define a rule for the root node.
❍ "Defined root not found in this Application Module." The view object usage name defining the root
node cannot be found in the application module defined in the form binding.
❍ "No rule found for accessor... ." There is no rule definition for every accessor in the rules table.
Error checking does not verify that the number of polymorphic rules for a particular accessor; only
that each accessor in the rules table has a rule definition.
9. JDeveloper adds code to the class file to bind a JTree control to view objects and their attributes:
myJTree.setModel(JUTreeBinding.createTreeNodeTypeBinding(getPanelBinding(),
myJTree, "MyRootNodeViewObject", null, "MyRootNodeVOTreeIter",
new JUCtrlHierTypeBinding[] {new JUTreeAccessorTypeBinding("NodeType1",
"mypackage.MyRootViewObject", "MyRootNodeAttribute",
"MyLeafNodeViewObject"), new JUTreeAccessorTypeBinding("NodeType2",
"mypackage.MyLeafNodeViewObject", "MyLeafNodeAttribute",
null)}));
To add images to display in the Node property editor:
The Node model editor lets you choose icons to display for each node in a branch and the open and close icon
for each branch. In order to add the icons to the Node model editor, you must add initialized images to your
variable declarations. For example:
ImageIcon deptImage = new ImageIcon();

ImageIcon deptOpenImage = new ImageIcon();
ImageIcon deptClosedImage = new ImageIcon();
ImageIcon empImage = new ImageIcon();
ImageIcon empOpenImage = new ImageIcon();
ImageIcon empClosedImage = new ImageIcon();
The images must be initialized, if you have uninitialized images, edit the parameter list and then open the Node
model editor,
you will loose your edits. When an image is uninitialized, Swing runtime will throw a NullPointerException when
attempting to
draw the node to display a node that should display the null image.
8-228
Related topics

8-229
Setting a View Control Binding
You can set a control binding using the JClient view model on any of these Swing and JClient
(JU) controls:
● JProgressBar
● JScrollBar
● JSlider
● JUNavigationBar
● JUStatusBar
In the case of the JProgressBar, JScrollBar, and JSlider, the view control binding lets users
view the relative position of the current row in the bound view object. The control thumb or
indicator will be proportional to the number of rows displayed out of the full range fo the view
object. You use the model Property Editor to select the view object on which you want the
control to operate.
You use a view control binding on a JUNavigation control to manage the position of the current
row on the view object. When the user clicks on the navigation bar buttons, the row position
changes and any indicator control bound to the same view object will be updated. The
JUStatusBar control displays information about the current row.
To set an attribute control binding:
1. Open the data panel in the UI editor and add the desired Swing or JClient control to the
panel.
2. Display the model or document property editor for the control and select JClient View
Binding from the list.
3. In the View Object list, select the view object that contains the attributes the form
displays.
4. In the case of the JProgressBar, JScrollBar, and JSlider, you can determine the view
object row count to use. Normally, leave Use Estimated Row Count selected. You can
select it if you want to count any rows from the database which have not yet been
cached by the view object.
8-230
Note: This option appears selected by default because when unselected (thereby forcing the
actual row count) it may trigger an additional query.
6. JDeveloper adds code to the class file to bind a JSlider control to the view object, with
estimated row count set to true:
myJSlider.setModel(JUSliderBinding.createViewBinding(getPanelBinding(), myJSlider,
"MyViewObject", null, "MyVOIter", true, true))
Related topics
8-231
In addition to standard Swing controls that work with JClient models, there is a set of JClient-
specific controls. These additional controls support databound behavior not provided by
standard Swing controls. This section describes how to work with the JClient-specific controls,
which appear on the JClient controls Component Palette:
● JUImage control for use with RAW, LONGRAW, BLOB and interMedia IMAGE datatypes
● JULabel control
● JUNavigationBar control
● JUStatusBar control
● OrdMediaControl for use with interMedia datatypes
Related topics

8-232
Using the JUImage Control
The JUImage control can be bound to a BC4J attribute through the JClient attribute model
object which accesses images stored in the database through a particular business component
view object. Datatypes that the JUImage control supports includes images stored as:
● LONG RAW datatype

● RAW datatype
● BLOB datatype
● interMedia IMAGE type
To bind to a view object containing an image:
1. From the JClient control tab on the Component Palette, click the JUImage control.
2. Click the UI Editor to add the JUImage control to the form.
3. In the Property Inspector for the image, select the model property and select the JClient
attribute model.
4. Select the name of the attribute object containing the image you want to use.
5. JDeveloper adds code to the class file to bind the JUImage to the view object attribute:
myJuImage.setModel(JUDefaultControlBinding.createAttributeBinding(getPanelBinding(),
myJuImage, "MyViewObject", null, "MyViewObjectIter", "MyVOAttribute"));
You can also choose to provide a scrolling region for the image.
To add a scrolling region to your image:
● In the Property Inspector, set the autoscrolls property to True.
Within a data form, users can delete and update the image file stored in the database, but they
cannot edit the image itself.
8-233
To use the JUImage control:
The Image control consists of a panel with a display area and two buttons:
● Change button to invoke an Open dialog box in which users can select the image file to
load.
● Clear button to delete the image.
Related topics
8-234
Using the JULabel Control
The JULabel control can be bound to a BC4J attribute through the JClient attribute model
object which accesses the data stored in the database through a particular business
component view object.
To bind to a view object attribute containing the desired label:
1. From the JClient control tab on the Component Palette, click the JULabel control.
2. Click the UI Editor to add the JULabel control to the form.
attribute model.
4. Select the name of the attribute object containing the label you want to use.
5. JDeveloper adds code to the class file to bind the JULabel to the view object attribute:
myJuLabel.setModel(JULabelBinding.createAttributeBinding(getPanelBinding(),
myJuLabel, "MyViewObject", null, "MyViewObjectIter", "MyVOAttribute"));
Note, the text property will be overwritten when you run the data form.
Related topics
8-235
Using the JUNavigationBar Control
The JUNavigationBar control can be bound to:
● A BC4J view object through the JClient view model object

● A JUPanel that has a panel binding passed to it through its constructor
The effect of these bindings determines the scope of the navigation bar actions. If you bind to a
view object, the JUNavigationBar lets you navigate on those controls that share the same panel
and that are bound to the same view object through its attributes. Whereas, you can control the
navigation of controls in child panels, by adding the JUNavigationBar control to the containing
panel and setting the panel binding.
To bind to a view object:
1. In the JClient project, open the UI Editor on the data panel that contains the controls you
want to navigate on.
2. From the JClient control tab on the Component Palette, click the JUNavigationBar
control.
3. Click the UI Editor to add the JUNavigationBar control to the form.
4. In the Property Inspector for the image, select the model property and select JClient
view binding.
5. Select the name of the view object you want to use.
6. JDeveloper adds code to the class file to bind the JUNavigationBar to the view object:
myNavBar.setModel(JUNavigationBar.createViewBinding(getPanelBinding(),
"MyViewObject", null, "MyViewObjectIter"));
To bind to a JUPanel:
1. In the JClient project, open the UI Editor on the layout panel that contains the panels you
8-236
2. From the JClient control tab on the Component Palette, click the JUNavigationBar
control.
3. Click the UI Editor to add the JUNavigationBar control to the form.
panel binding.
5. JDeveloper adds code to the class file to bind the JUNavigationBar to the panel binding
passed into the current panel:
myNavBar.setModel(JUNavigationBar.createPanelBinding(getPanelBinding(),
myNavBar));
Related topics
8-237
Using the JUStatusBar Control
The JUStatusBar control can be bound to:
● A BC4J view object through the JClient view model object

● A JUPanel that has a panel binding passed to it through its constructor
The effect of these bindings determines the scope of the status bar. If you bind to a view object,
the JUStatusBar lets you display the navigation status of those controls that share the same
panel and that are bound to the same view object through its attributes. Whereas, you can
display the navigation status of controls in child panels, by adding the JUStatusBar control to
the containing panel and setting the panel binding.
To bind to a view object:
1. In the JClient project, open the UI Editor on the data panel that contains the controls you
2. From the JClient control tab on the Component Palette, click the JUStatusBar control.
3. Click the UI Editor to add the JUStatusBar control to the form.
view binding.
5. Select the name of the view object you want to use.
6. JDeveloper adds code to the class file to bind the JUStatusBar to the view object:
myStatusBar.setModel(JUStatusBar.createViewBinding(getPanelBinding(),
"MyViewObject", null, "MyViewObjectIter"));
To bind to a JUPanel:
1. In the JClient project, open the UI Editor on the layout panel that contains the panels you
8-238
2. From the JClient control tab on the Component Palette, click the JUStatusBar control.
3. Click the UI Editor to add the JUStatusBar control to the form.
panel binding.
5. JDeveloper adds code to the class file to bind the JUStatusBar to the panel binding
passed into the current panel:
myStatusBar.setModel(JUStatusBar.createPanelBinding(getPanelBinding(),
myStatusBar));
Related topics
8-239
Using the OrdMediaControl
The OrdMediaControl control can be bound to a BC4J attribute through the JClient attribute
model object which accesses multimedia data stored in the database through a particular
business component view object.
To bind to a view object containing an image, audio, or video data:
1. From the JClient control tab on the Component Palette, click the OrdMediaControl
control.
2. Click the UI Editor to add the OrdMediaControl control to the form.
attribute model.
4. Select the name of the attribute object containing the multimedia data you want to use.
Within a data form, users can load multimedia content into interMedia objects, clear the
multimedia content in the interMedia objects, render the multimedia content in the interMedia
objects, save the multimedia content in the interMedia objects into a file. User may not edit the
data itself.
Using the OrdMediaControl Control
The OrdMediaControl control consists of a panel with a display area and three buttons:
● Change button to invoke an Open dialog box in which users can select the multimedia
file to load.
● Clear button to delete the content from the database.
● Launch button to open the window used to render the multimedia data.
● Save button to save the contents to a file.
For image media, the OrdMediaControl control displays the graphics. For audio and video
media, OrdMediaControl renders the content and provides a set of buttons to PLAY, PAUSE,
MUTE, VOLUME UP, VOLUME DOWN, and POSITION.
8-240
The accelerator keys for the rendering control actions are:
● Ctrl-S: Start/Play
● Ctrl-P: Pause
● Ctrl-T: Stop
● Ctrl-U: Volume Up
● Ctrl-D: Volume Down
● Ctrl-M: Mute/Unmute
● Ctrl-R: Rewind
● Ctrl-F: Fast Forward
Customizing the OrdMediaControl in the Property Inspector
To remove the buttons panel on the OrdMediaControl:
● In the Property Inspector, set the showButtons property to False.
To disable the Launch button on the OrdMediaControl:
● In the Property Inspector, set the enableLaunchButton property to False.
To disable the Save button on the OrdMediaControl:
● In the Property Inspector, set the enableSaveButton property to False.
To disable the content modification buttons (Change and Clear buttons) on the
OrdMediaControl:
● In the Property Inspector, set the enableUpdateButtons property to False.
Related topics
8-241
8-242
Working with Java Web Start and JClient
Applications
Java Web Start is Sun Microsystem's new application deployment software that lets you
maintain JClient applications on the web server, while users download and run on their client
machines. Before you deploy your JClient application or applet to the web server, you can
simulate the user's experience of running the application with Java Web Start within the
JDeveloper IDE. Then you can use JDeveloper's simple J2EE web deployment process to
move the entire production application to the web server.
● Setting up JClient runtime information

● Creating a JNLP definition to launch JClient applications
● Deploying a JClient Web Application Archive for Java Web Start
● Running JClient applications with Java Web Start in JDeveloper
Related topics
See also
For more information on Java Web Start go to this java.sun.com web page:
8-243
Setting Up JClient Runtime Information
Before you use can run your JClient application, you must setup runtime configuration
information for your application. Your application needs these files to determine a runtime
configuration:
● A business components configuration (bc4j.xcfg) file in your business components

project that specifies the application module connection and deployment scenario for the
business components
● A client data model defintion (client.cpx) file in your JClient project that specifies the
application module and business components runtime configuration your data forms will
use
There are two ways to use the runtime information:
● When you want to test your JClient application in JDeveloper

● When you want to deploy your JClient application for production
You will want to create a separate business components configuration and client data model
definition for each case.
To setup runtime configuration information for JClient applications:
1. Create the business components runtime configuration (in the bc4j.xcfg file) that
specifies the application module connection and deployment scenario for the Business
Components.
2. Create a JClient data model definition that specifies the application module and business
component runtime configuration your data forms will use.
Note: When you want to run your JClient application using Java Web Start within JDeveloper,
use the default local mode deployment for the Business Components runtime configuration.
In the case of Java Web Start, local mode deployment eliminates potential security conflicts
that can occur in the remote deployment scenario. Later, when you want to deploy the
Business Components to a remote OC4J or VisiBroker web server, signing your JAR files
may be necessary.
3. Run the desired JClient wizard to generate data forms or data panels. In the Data Model
page of the wizard, select the previously created client data model definition.
8-244
Note: You can also click New to create a data model based on another business components
configuration.
4. Optionally, run the JClient Java Web Start Wizard when you want to run your JClient
application using Sun Microsystems' Java Web Start application-deployment technology.
In the Data Model page of the wizard, select the previously created client data model
definition.
8-245
Creating a Web Start JNLP Definition for JClient
Applications
You use the JClient Java Web Start Wizard to create the XML-based JNLP (Java Network
Launching Protocol) definition that the Java Web Start software uses to download and run Java
applications and applets on client machines.
Along with several deployment profile files, the wizard adds two JNLP files to your JClient
project. Java Web Start will use these generated JNLP files to determine what application
source to download from the web server:
● One to specify source files for the JClient and business components application, where
the name depends on the business components runtime configuration (for example,
local.jnlp) you choose
● One to specify business components runtime libraries, where the name is based on the
first JNLP file (for example, localmt.jnlp, where mt stands for "middle-tier," a synonym for
business components)
Important: Before you use the JClient Java Web Start Wizard, you must setup runtime configuration
information for your application. During development, use the default local mode deployment
configuration to avoid potential security conflicts that occur in the remote deployment scenario.
To create the JNLP definition for your application or applet:
1. In the Navigator, click on the JClient project to which you want to generate a JNLP
definition.
2. Choose File | New to locate the JClient Java Web Start Wizard in the New Gallery.
3. Choose JClient Java Web Start Wizard from the JClient Objects category and click OK.
4. In the Data Model page, choose the client data model definition that corresponds to the
desired business components deployment scenario.
Note: The client data model definition you choose determines which business component
runtime libraries will appear in the generated JNLP file.
5. In the Properties page, you determine how Java Web Start will launch your JClient
application or applet. These choices will be added to the generated JNLP file:
❍ Select Generate Application Description when you want to run your JClient
application using a runnable frame that appears in your project. If you created a
8-246
JClient applet class in your project, choose Generate Applet Description.
❍ In the Main Class dropdown, choose the application or applet class from your
JClient project that you want Java Web Start to run.
❍ It is recommended that you choose JNLP generated dynamically - JSP in order to
dynamically generate the JNLP definition from a generated JSP page that the user
conveniently runs from their web browser. If you choose Static JNLP, the wizard
will add a JNLP file to your project.
6. Complete the wizard and click Finish.
Related topics

8-247
Testing and Optimizing Your Code
● Testing and Optimizing Your Code
● Compiling Your Code

❍ Compiling with the Oracle Java Compiler
■ About the Oracle Java Compiler
■ About Compiling from the Command Line or Shell

■ About OJC Response Files
■ Invoking the Oracle Java Compiler
■ Compiling with the Oracle Java Compiler (OJC)
❍ Configuring Your Project for Compiling

❍ About Dependency Checking
❍ Compiling with JDeveloper
❍ Compiling with Build
❍ Compiling with Make
❍ Specifying a Native Encoding for Compiling
❍ About the Setvars Command (Windows)
● Running in JDeveloper
❍ About the Run Manager
❍ Changing the Java Virtual Machine

❍ Configuring Your Project for Running
❍ Running Java Programs
■ Running an Applet
■ Running an Application
■ Running a JSP
■ Running an EJB
■ Running a Servlet
■ Running JClient Applications with Web Start
■ Running Applications and Applets with Web Start
9-1
❍ Running a Project from the Command Line Environment
■ Running a Project from the Command Line
■ Setting the Classpath for Your Programs

■ About the Setvars Command (Windows)
● Debugging in JDeveloper
❍ About the Debugger
❍ About Debugger Icons

❍ Configuring Your Project for Debugging
❍ Debugging a Project in JDeveloper
❍ Using the Code Editor When Debugging
❍ About the Debugger Windows
■ About the Breakpoints Window
■ About the Classes Window

■ About the Data Window
■ About the Heap Window
■ About the Inspector Window
■ About the Monitors Window
■ About the Smart Data Window
■ About the Stack Window
■ About the Threads Window
■ About the Watches Window
■ Setting Preferences for the Debugger Windows
❍ Debugging Java Programs

■ Debugging an Applet
■ Debugging a JSP
■ Debugging a Servlet
■ Debugging an EJB
■ Moving Through Code While Debugging
■ Stepping Into a Method
■ Stepping Over a Method
9-2
■ Locating the Execution Point for a Thread
■ Running to the Cursor Location
■ Pausing and Resuming the Debugger
■ Terminating a Debugging Session
■ Managing Breakpoints
■ About Breakpoints
■ Editing a Breakpoint
■ About Valid and Invalid Breakpoints
■ Setting Source Breakpoints
■ About Deadlock Breakpoints
■ Controlling Breakpoint Execution
■ Disabling and Deleting Breakpoints
■ Setting Exception Breakpoints
■ Making a Breakpoint Conditional
■ Examining Breakpoints with the Breakpoints Window
■ Managing Breakpoint Groups
■ Managing Breakpoint Groups
■ About Grouped Breakpoints
■ Examining Program State in Debugger Windows

■ Controlling Which Classes are Traced Into
■ Inspecting and Modifying Data Elements

■ Setting Expression Watches
■ Modifying Expressions in the Inspector Window
■ Using Acceptable Legal Java Expressions in JDeveloper
■ Show and Hide Fields in the Filtered Classes List
❍ Remote Debugging
■ About Remote Debugging
■ Remote Debugging in OC4J

■ Remote Debugging in Oracle9iAS 1.0.2.1.x or Apache JServ
9-3
■ Guidelines for Remote Debugging Servlets on Other Servers
■ Creating a Remote Debugging Project with the Wizard
■ Starting a Java Process in Debug Mode
■ Using a Project Configured for Remote Debugging
● Using the Embedded OC4J Server

❍ Configuring Your Project to Use the Embedded OC4J Server
❍ Setting Preferences for the Embedded OC4J Server

❍ Starting the Embedded OC4J Process
❍ Terminating the Embedded OC4J Process
❍ About the Embedded OC4J Configuration Files
● Writing More Efficient Java Programs with CodeCoach
● CodeCoach Concepts
❍ About CodeCoach
❍ About Customizing CodeCoach Advice

❍ About Pragmas
❍ About CodeCoach Memory Improvement Advice
● Preparing Your Project to be CodeCoached

● Ways to Start CodeCoach
● Customizing CodeCoach Advice for a Project from the IDE
❍ Enabling and Disabling Advice Types in CodeCoach
❍ Setting the Advice Level for CodeCoach

❍ Including and Excluding Packages and Classes in CodeCoach
● Customizing CodeCoach Advice for Files, Classes, or Methods

● Using CodeCoach from the Command Line
● CodeCoach Reference
❍ CodeCoach Keywords
9-4
❍ CodeCoach Class Advice
❍ CodeCoach Method Advice
❍ CodeCoach Field Advice
❍ CodeCoach Local Variable Advice
❍ CodeCoach Memory Improvement Advice
❍ CodeCoach Miscellaneous Advice
● Profiling a Project
● Profiler Concepts
❍ About the Profiler
❍ About the Profiler Class Set

❍ About Remote Profiling
❍ About Execution Profiling
❍ About Memory Profiling
❍ About Event Profiling
● Setting Global Profiler Options

● Defining the Profiler Class Set
● Starting and Stopping the Profiler
● Arranging Data Views in the Profiler
● Controlling a Profiling Session with Profiler API Commands
● Profiling Remotely
● Execution Profiling
❍ Setting Options for the Execution Profiler
❍ Starting and Stopping an Execution Profiling Session

❍ Analyzing Execution Profiling Results
❍ Saving the Results of an Execution Profiling Session
● Memory Profiling
❍ Setting Options for the Memory Profiler
9-5
❍ Starting and Stopping a Memory Profiling Session
❍ Finding Where Methods Are Called from in the Memory Profiler
❍ Analyzing Memory Profiler Results
❍ Saving the Results of a Memory Profiling Session
● Event Profiling
❍ Setting Options for the Event Profiler
❍ Starting and Stopping an Event Profiling Session

❍ Saving the Results of an Event Profiling Session
● Profiler Reference
❍ Class ProfilerAPI
9-6
Testing and Optimizing Your Code
The Testing and Optimizing Your Code book provides information on using the JDeveloper
compiler, runner, debugger and embedded OC4J server, CodeCoach and Profiler. This book
includes the following sections:
Topic
Topic Title
Description
Describes
compiling your
code with the
Oracle Java
Compiling Your Code Compiler and
compiling with
the build and
make
commands.
Describes how
to run your
applications
Running in JDeveloper using the Run
Manager and
from the
command line.
Describes how
to debug your
applications
using the
Debugging in JDeveloper JDeveloper
debugger. You
can debug
locally or
remotely.
9-7
Describes
using the
embedded
OC4J server to
run, debug,
Using the Embedded OC4J Server
profile, and
CodeCoach
your J2EE
EJBs, servlets,
and JSPs.
CodeCoach
can help you
with the more
routine aspects
of developing
higher quality,
better
performing
code. By
assisting you
with these
Writing More Efficient Java Programs Using CodeCoach tasks, whether
you are new to
Java or an
experienced
programmer,
CodeCoach
can help you to
develop
efficient Java
programs more
quickly and
easily.
Profiling Your Project The

JDeveloper
Profiler takes
advantage of
the features in
the Oracle
Java Virtual
Machine
(OJVM) to find
programming
inefficiencies,
performance
problems, and
memory leaks
in your
9-8
application
code. You can
use the
JDeveloper
Profiler with
the debugger
and
CodeCoach for
powerful and
efficient
troubleshooting
in your
application
code.
9-9
Compiling Your Code
Learn more about compiling your code in JDeveloper:
● Compiling with the Oracle Java Compiler (OJC)

● Configuring Your Project for Compiling
● About Dependency Checking
● Compiling with JDeveloper
● Compiling with Build
● Compiling with Make
● Specifying a Native Encoding for Compiling
● About the Setvars Command (Windows)
9-10
Compiling with the Oracle Java Compiler (OJC)
Oracle Java Compiler (ojc) compiles Java source code (*.java files) into Java bytecode
(*.class files). Learn more about OJC:
● About the Oracle Java Compiler

● About Compiling from the Command Line or Shell
● About OJC Response Files
● Invoking the Oracle Java Compiler
9-11
About the Oracle Java Compiler
Oracle Java Compiler (ojc) compiles Java source code (*.java files) into Java bytecode
(*.class files). It is used by the JDeveloper IDE or you can use it directly from the command
line. The resulting bytecode are the machine code for a Java Virtual Machine (JVM). Compiling
a Java source file produces a separate class file for each class or interface declaration. When
you run the resulting Java program on a particular platform, its JVM runs the bytecode
contained in the class files.
The ojc compiles the specified Java file and any imported files that do not have a
corresponding Class file. Unless dependency checking is specified (with the -make option),
ojc compiles all of the target Java files. For more information on dependency checking, see
Dependency Checking.
To see the syntax and list of options, enter:
ojc -?
or
ojc -help
You may need to set the environment variables for the command line so the required classes
are found. The setvars command will provide this for you.
Related topics
About the Setvars Command (Windows)

About Dependency Checking
About Compiling from the Command line or Shell
Oracle Java Compiler and Response Files
Invoking the Oracle Java Compiler
9-12
About Compiling from the Command Line or Shell
You can compile from the operating system Command Shell (Windows) or a shell (Solaris)
using the Oracle Java Compiler or ojc. To see its syntax and a list of options, enter the
following command:
ojc -?
By default, ojc compiles the specified source Java files, whether or not their class files are
outdated. It also compiles any directly imported Java file that does not have a corresponding
class file. Imported Java files that already have class files will not be recompiled, even if their
class files are outdated; after using ojc, some imported classes might still have outdated class
files.
ojc performs dependency checking and will use or generate a specified dependency file if you
use the -make command line option. By default, it only compiles files that are specified on the
command line and any referenced files that don't have a class file.
In Windows, you might need to run setvars.bat to set the environment variables for the
command line so that the required classes are found.
Switching between the command line and JDeveloper
If you edit a file outside of JDeveloper, be sure to include that file in the project if you want it to
be compiled when you are using JDeveloper.
Related topics

About the Setvars Command
Compiling with the Oracle Java Compiler
9-13
The Oracle Java Compiler (OJC) supports response files. A response file is a set of command
line options that OJC reads instead of entering them at the command line. This technique is
useful when editing and using very long command lines.
To have OJC read a response file:
● Enter ojc @args.txt at the command line.
Inside args.txt, you can separate the command-line arguments however you want, putting them
on separate lines if you like. There's no limit on the size of the response file.
You can also have comments in a response file by placing a semicolon (;) at the beginning of a
line.
However, you cannot use double quotes in a response file; the following becomes two different
arguments to ojc:
"file name.java"
where the first is "file" and the second is "name.java"
Related topics

About Compiling From the Command Line or Shell
9-14
To invoke the Oracle Java Compiler from the command line:
● Enter ojc [options] {file.java}
Command Line Options
-classpath path
The path used to find classes. It overrides the default CLASSPATH or the CLASSPATH
environment variable. Directories are separated by semicolons. For example:
ojc -classpath c:\mydir;c:\jdeveloper\myclasses foo.java
If you are using the Java 2 platform (here for the default target JDK 1.3), then the
SYSTEMCLASSPATH is prepended to the CLASSPATH. For the above example it would
look like this is:
%JAVAHOME%\jre\lib\rt.jar;
%JAVAHOME%\jre\lib\i18n.jar;
%JAVAHOME%\jre\lib\sunrsasign.jar;
%JAVAHOME%\jre\lib\jsse.jar;
%JAVAHOME%\jre\lib\jce.jar;
%JAVAHOME%\jre\lib\charsets.jar;
%JAVAHOME%\jre\lib\classes;
c:\mydir;
c:\jdeveloper\myclasses
If JAVAHOME is not defined, then the JDK 1.3 under the JDeveloper root directory is
used.
If the target JDK is 1.1 (by using the -target 1.1), the SYSTEMCLASSPATH is appended to
9-15
the CLASSPATH. For the above example it would then look like this is:
c:\mydir;
c:\jdeveloper\myclasses
%JAVAHOME%\lib\classes.zip;
%JAVAHOME%\classes
To change the SYSTEMCLASSPATH use option -sysclasspath or option -bootclasspath.
-sourcepath pathlist
A semicolon separated list of paths used to locate required Java files.
-sysclasspath pathlist
A semicolon separated list of paths used to the system class files.
-bootclasspath pathlist
Equivalent to -sysclasspath.
-d outdir
The root directory of the class (Destination) file hierarchy.
For example:
ojc -d C:\JDeveloper\myclasses JavaBean.java
causes the class files for the classes defined in the JavaBean.java source file to be
saved in the directory C:\JDeveloper\myclasses\MyPackage directory, assuming
9-16
that JavaBean.java contains the following package statement: MyPackage
Java files are read from the SOURCEPATH and Class files are written to the CLASSPATH
directory. The destination directory can be part of the CLASSPATH. The default
destination matches the package structure in the source files and starts from the root
directory of the source.
-deprecation
Display deprecation warning messages.
-encoding name
You can specify a native-encoding name (or codepage name) to control how the
compiler interprets characters beyond the ASCII character set. The default is to use the
default native-encoding converter for the platform. For more information, see Specifying
a Native Encoding.
For example, the command:
ojc -encoding SJIS JavaBean.java
compiles JavaBean.java and any directly imported Java files that do not have class
files. Characters in all source files are interpreted as the Shift-JIS character set for
Japanese.
-exclude classname(s)
This option allows you to specify class names to exclude from your build. The compiler
will ignore all calls to public static void methods of the specified class(es). This is
useful mainly for diagnostics where your non-production application build may contain
code that will need to be compiled in the official production build. More than one class
may be excluded by separating them with semicolons or specifying -exclude more than
once. For example: -exclude p1;p2;p3 -exclude p4 will exclude four classes, p1,
p2, p3, and p4.
9-17
Note: This option is also supported in the JDeveloper IDE (Project | Project Settings -
Compiler).
An example of the -exclude option:
// beginning of excludeTest.java
public class excludeTest
{
public static void main(String argv[])
{
diag.Trace("Application is about to start");
System.out.println("Test successful");
diag.Trace("Application is about to end");
}
}
class diag
{
static void Trace(String msg)
{
System.out.println(msg);
}
}
// end of excludeTest.java
When compiling the above application without the exclude option, the output will be as
follows:
Application is about to start

Test successful
Application is about to end
When compiling with the following exclude option:
9-18
ojc -exclude diag excludeTest.java
the output becomes:
Test successful
and successfully ignores all calls to diag.Trace
-extdirs pathlist
A semicolon separated list of paths to be added to the classpath. Any .jar files in each
path will be added.
-g
Generates debugging information in the class file. This is a necessary parameter to use
CodeCoach on your project. It is also required to access local variables and other
information while debugging the class.
-g:none
Forces the compiler NOT to generate debugging information in the class file.
-g:source,lines,vars,codecoach
Generates selective debugging information in the class file.
-help
-?
Displays the options for the ojc compiler.
9-19
-make depfilename
Uses the named dependency file for dependency checking. If the specified file is not
found, it will be created.
-noquiet
Displays file names as they are compiled.
-nowarn:#<id>
Compiles without displaying warnings. You can specify any number of warnings to
suppress. When specified with an argument, all warnings except the ones specified are
suppressed. Some examples include:
-nowarn:#486
Suppresses Unused Import Statement
-nowarn:#487
Suppresses Partially used Import Statement
You can also use -nowarn in combination with -warn:
-nowarn -warn:#487
to output warnings only for warning #487.
-nowrite
Compiles the program without outputting class files.
-obfuscate
Obfuscation makes your programs less vulnerable to reverse engineering. After
9-20
decompiling your obfuscated code, the generated source code contains altered symbol
names for private symbols.
-p packagename
Compiles the specified package name(s).
-rebuild
Rebuilds specified files regardless of dependencies. Rebuild is assumed unless the -

make option is used.
-recurse [level]
Instructs the compiler to recursively descend into directories when expanding file name
specifications containing wildcards.
ojc -recurse foo\*java
might be the equivalent of entering:
ojc foo\bar\*java foo\lish\*java foo\lish\lee\*java
The option [level] takes an optional integer argument specifying the maximum recursive
level.
ojc -recurse 1 foo\*java
9-21
might be the equivalent of entering:
ojc foo\bar\*java foo\lish\*java
Note that foo\lish\lee\*java would not be within the scope of the [level] variable.
-s sourcefile
Compiles the specified source file name(s).
-source {1.3|1.4}
By default, the source compatibility level is J2SE 1.3. To enable J2SE assertions in the
source code, enter -source 1.4.
-strictfp
Forces the compiler not to use extended precisions for intermediate floating point
calculations.
-target [1.1|1.2|1.3|1.4]
If the target is set to 1.1, ojc compiles for JSDK 1.1. If the target is set to 1.2, ojc
compiles for Java 2 (JSDK 1.2). If the target is set to 1.3, ojc compiles for Java 2 v1.3
(J2SE 1.3). If the target is set to 1.4, ojc compiles for Java 2 v1.4 (J2SE 1.4)
The default target is Java 2 (J2SE 1.3).
-updateimports
Updates the imported classes (if source is found on source path), but not if the classes
are from a zip or jar file. This is the default setting.
9-22
-updateimports:class
Same as -updateimports.
-updateimports:jar
Same as -updateimports except it will also update the classes if they are from a zip
or jar file.
-updateimports:none
Does not update the imported classes.
-verbose
This option gives more information about compiling, such as which class files are loaded
from where in the CLASSPATH. You get information about:
● Which source files are being compiled

● Which classes are being loaded
● Which classes are generated
-verbosepath
This option displays SOURCE PATH and CLASSPATH values used by the compiler.
-warn:#<id>
This option allows you to specify warnings. You can have any number of warnings in
combination with any suppressed warnings. When used with no arguments, all warnings
are displayed. Two useful ones include:
9-23
-warn:#486
Displays Unused Import Statement
-warn:#487
Displays Partially used Import Statement
Related topics

9-24
Configuring Project Settings for Compiling
For each project, you can configure the following:
● General compiler options

● SQLJ options
● IDL options
To set compiler options in JDeveloper:
1. Right-click a project in the Navigator and choose Project Settings from the context
menu. The Project Settings panel appears.
2. In the left frame, click the Compiler node below the Development node to display its
related options.
3. Click the plus sign beside the Compiler node to display the settings for the SQLJ and IDL
options.
4. Click Help for additional information for any field on any page.
Note: If you want to have all your project files automatically saved before compiling, set this in
the Tools | Preferences - Environment panel.
Related topics
Specifying a Native Encoding

Configuring Your Project for Running
Running in JDeveloper
9-25
JDeveloper provides fast yet complete compiling by analyzing dependencies. Dependency
checking results in fewer unnecessary compiles of interdependent source files, and thus
accelerates the edit and compile cycle.
When you compile using the IDE, dependency checking is used whenever you compile with
Make by choosing Project | Make <name of project>. Make uses a dependency file that is
automatically created within JDeveloper.
If you use the Oracle Java Compiler (ojc) from the command line, you create or use a
dependency file by specifying the following parameter:
ojc -make <makedepfile>
Related topics
Compiling With Make

9-26
JDeveloper uses a powerful, full-featured compiler, ojc (Oracle Java Compiler), to build your
projects or parts of your projects. It fully supports the Java language, including inner classes
and JAR files.
You can invoke the compiler from within the JDeveloper in the following ways:
● Choosing Project | Make [project name]

● Choosing Project | Build [projectname]
● Directly from the command line by entering ojc [ options ] file...
In addition, you can also build or make selected items, with the Build <selected item> or Make
<selected item> when you select an item in the Navigator if the Navigator is active, or for the
current node in the Code Editor, if it's active. These menu commands have the same effect as
choosing Build or Make from the context menu in the Navigator for a selected item.
For Java source files, the compiler reads Java source files, determines which additional files
need to be compiled, and produces the Java program in the form of .class files. These
.class files contain the bytecode that are the machine code for a Java Virtual Machine (JVM).
Compiling produces a separate .class file for each class declaration and interface declaration
in the source file. When you run the resulting Java program on a particular platform such as
Windows NT or Solaris, the Java Virtual Machine for that platform executes the bytecode
contained in the class files.
Files such as XML, XSQL, XSL and UIX don't have Make in their respective context menus.
Instead, you can check syntax with Check Syntax.
The following parts of a workspace can be compiled:
● The entire workspace

● A project
● Java files
● Java packages
● JSP files
● BC4J projects
● Enterprise JavaBeans projects
9-27
Related topics

Compiling With Make
Compiling With Build
9-28
Compiling with Build
Choosing the Project | Build menu option compiles the selected node and its imported files,
regardless if the node or any of the imported files have changed. The node can be the
workspace, project, package, or Java file.
Anytime you want to ensure that your entire project is up-to-date, execute Build as this
compiles every file in the project including all the imported files in the project. Choosing to
execute Make is faster than Build, once you have done your initial compilation.
Invoking Build
Choosing Project | Build Project compiles all source files within the selected node, regardless if
their class files are outdated. The imported files that are compiled include all recursively
imported files (that is, imported files of imported files) except for files that are not in the current
project.
To build a node:
● Right-click a node in the Navigator and choose Build from the context menu. You can
also select the node in the Navigator, then choose Project | Build <node_name> in the
main menu.
To build a project:
1. In the Navigator, select the project or a node in the project.

2. Select Project | Build <project_name.jpr> from the main menu or click the Build icon
on the toolbar.
To build the entire workspace:
● Right-click the workspace in the Navigator, then choose Build from the context menu.
You can also select Project | Build <workspace_name.jws>.
Related topics
9-29
Compiling With JDeveloper
Compiling With Make
9-30
Compiling with Make
Choosing Project | Make compiles the selected node, if it has changed, and any imported files,
if they have changed. The node can be the workspace, project, package, or a Java file.
Packages lower in the project tree hierarchy are built before packages higher in the hierarchy.
During routine iterations of the edit or recompile cycle, Make is recommended since it only
compiles the files that have been changed. Make is faster than Build, once you have done your
initial compilation.
Invoking Make
Choosing Project | Make <node_name> compiles any Java file within the selected node that
has outdated or nonexistent class files. Make also compiles any files imported by the node that
have outdated or nonexistent class files. An "outdated" class file is one that has a "modified
date" older than the current version of its Java source file.
The imported files that are checked and compiled include all recursively imported files (that is,
imported files of imported files) except for files that are not in packages in the current project.
To make a node:
● Right-click the node in the Navigator, then choose Make. You can also click the node in
the Navigator, then choose Project | Make <node_name> from the main menu.
To make a project:
1. In the Navigator, select the project, or a node in the project.

2. Select Project | Make <project_name.jpr> or click the Make icon on the toolbar.
To make the entire workspace:
● Select the workspace in the Navigator, then right-click and choose Make from the context
menu. You can also select Project | Make <workspace_name.jws>.
Related topics
9-31
Compiling With JDeveloper
9-32
Specifying a Native Encoding for Compiling
You can specify an encoding scheme to control how the compiler interprets multibyte
characters. If no setting is specified, the default native-encoding converter for the platform is
used.
To set the encoding option, do one of the following:
● Within JDeveloper:
❍ In the Project | Project Settings panel, click the Compiler node.

❍ Select an encoding name from the Character Encoding dropdown list.
● On the command line, use the ojc command with the -encoding option followed by
the encoding name.
Encoding Schemes
Text characters are represented using different encoding schemes. In the Windows
environment, these are known as code pages whereas Java refers to them as native
encodings. When moving data from one encoding scheme to another, conversion needs to be
done. Since each scheme can have a different set of extended characters, conversion may be
required to prevent loss of data.
Most text editors, including the Code Editor, use the native encoding of the platform on which
they run. For example, Japanese Windows uses the Shift-JIS format. If the source code has
been encoded with Shift-JIS and you are compiling it in a US Windows environment, you must
specify the Shift-JIS encoding for the compiler to read the source correctly.
JDeveloper supports the character encoding schemes included with your currently installed
J2SE.
Native encodings that are supported
Refer to the JavaSoft table, Java™2 SDK Supported Encodings at the following location:
http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html
9-33
One encoding name has special meaning:
Default
Equivalent to not specifying an encoding option. This settings uses the default encoding
of the user's environment.
Related topics
Compiling With Make

9-34
Setting system environment variables for command line compiling can be a difficult process,
due to the number of libraries that may be included in your project and the need to adjust the
variables to include the source files for each of the archive files you deploy. The setvars.bat
file lets you set the PATH and CLASSPATH information for standard libraries relative to your
installed JDeveloper root directory.
Note: Do not use setvars.bat to set up your environment for testing applets or applications.
To test applets and applications, deploy them first, or create a batch file that will set the
necessary environment variables for your applet or application.
The setvars.bat file
The setvars.bat file is located in the jdev\bin directory of your JDeveloper installation. If you
enter setvars, with no options, from the command line, it will list the available options.
Usage:
SETVARS -go
SETVARS [-jdkver=1.x] [-userhome=dir] [-private=yes|no]

[-tools=tool_list] [-terse]
SETVARS -show [all]
Setvars options:
-go
Use all the default settings. (Single-user 1.3 J2SE).
-jdkver=1.3
Use this option to select your Java platform. By default, JDeveloper uses
the JDK 1.3.
-userhome=dir
In multiuser settings, use this directory for the current user.
9-35
Note: If the userhome feature is used, then it should match the value you
pass into the JDeveloper IDE with the -userhome:USERHOME flag.
-private=yes|no
Defines the location of the Oracle Lite installation directory. This is only
required for the Oracle Lite database and by default is undefined.
-tools=tool_list
A semicolon separated list of tools that you want to use. The defaults are
tools=jdk;bc4j;9iclient;sqlj;bc4j_local. Select the tools from
the following list:
Tool Description
jdk Sun JDK core classes (always present)
9iclient Oracle9i java tools
sqlj SQLJ translator and tools
bc4j Business components core classes (always present if you select

any other bc4j)
bc4j_local Local mode
bc4j_vb VisiBroker ORB mode
bc4j_9i Oracle9i mode
9-36
bc4j_ejb9i Oracle9i with EJB support mode
bc4j_oas Oracle Application Server mode
bc4j_web Web Client mode
-terse
Do not list PATH and CLASSPATH after execution.
-show [all]
Use this option show your current settings.
Note: The values for any of the switches can be set in an environment variable called
SETVARS_SWITCHES. This is useful if you use the same collection of switches all the time.
Examples for using setvars
Example 1
If you used the default installation path, you would use setvars.bat as follows:
1. Change directories to C:\<ORACLE_HOME>\jdev\bin.

2. Enter the command:
setvars -go
setvars.bat sets the variables, appending the JDeveloper values to your existing
CLASSPATH system environment variable.
Example 2
9-37
setvars D:\\<ORACLE_HOME>\jdev -jdkver=1.3 -userhome=D:\user\Brian
Selects the J2SE and sets your working directory to D:\user\Brian.
To see the results of the above examples, enter setvars -show
Related Topics
Setting the CLASSPATH for Your Programs
9-38
Learn more about running in JDeveloper:
● About the Run Manager

● Changing the Java Virtual Machine
● Configuring Your Project for Running
● Running Java Programs
● Running a Project from the Command Line Environment
9-39
About the Run Manager
The Run Manager keeps track of processes that are run, debugged, profiled, or CodeCoached.
When two or more such processes are active at the same time, the Run Manager window is
automatically displayed. When a process has completed, it is automatically removed from the
Run Manager.
To open or hide the Run Manager:
● Choose or unchoose View | Run Manager from the main menu. When the Run Manager
is started, the Run Manager tab next to the System Navigator becomes active.
To terminate a process with the Run Manager:
● Right-click a process in the Run Manager and choose Terminate from the context menu.
Related topics

Running a JSP
Running a Servlet
Running an Applet
9-40
Running an Application
Running an EJB
9-41
Changing the Java Virtual Machine
You may need to change the Java Virtual Machine (JVM) for which you are developing
because of operating system considerations or features that are only available with Oracle Java
Virtual Machine (OJVM). For example, only OJVM supports CodeCoach, Profiling, and some
debugging operations. Also, debugging with OJVM is significantly faster than debugging with
other virtual machines such as HotSpot and Classic.
The advanced features in OJVM can help you reduce development time and effort. You may
want to change the JVM on your development
platform to test your program against the "Classic" or "HotSpot" virtual machines for better
cross-platform compatibility.
To change the Java Virtual Machine:
1. RIght-click a project in the Navigator and choose Project Settings... from the context
menu.
2. Below Configurations, click Runner to display the Runner panel.
3. In the Virtual Machine list box, select an available option. The selected JVM is used
when running and debugging the project.
4. Click Help for additional information.
Related topics
Running a Project Using JDeveloper
9-42
JDeveloper allows you to control how your program is run, including the default run target,
JVM, Console I/O settings, and proxy information.
To configure your project's runner options:
1. Right-click a project in the Navigator and choose Project Settings... from the context
menu.
2. Below Configurations, click Runner to display the Runner panel.
3. Enter or browse to the Default Run Target.
Note: If there is no default run target specified and you attempt to run an object, you'll be
prompted to choose a run target. If the specified object is not runnable at all, then an
error is displayed in the Log window.
4. If you want to run the current node in the active view, select Attempt to Run Active File
Before Default.
For example, the Runner will run the selected node in the Navigator, if the Navigator is
active. Likewise, the Runner will run the current file in the Code Editor, if the Code Editor
is active. If that file is not runnable, then Runner attempts to run the project's specified
default run target. Otherwise, the default is to run the project's specified default run
target.
5. Complete the remaining settings as required.

a. Choose which Virtual Machine (JVM) to use when running the project.
b. Enter any additional Java Options you want included in the command line when
the Java process is launched.
c. Enter any Program Arguments that you want passed to your application's main
method.
d. Specify the Run Directory from which to launch the process when running the
project.
6. If you want to configure additional runner settings, click the Options node below the
Runner node.
a. Select the Make Before Running check box to compile the entire workspace
including all projects within it before the application is run in JDeveloper.
b. Select Allow Program Input to be able to enter console style input to your
program.
c. Select Use Proxy to launch your program with the -Dhttp.proxyHost and -
9-43
Dhttp.proxyPort Java options.
7. Click Help for additional information.
Related topics
About Changing Java Virtual Machines
9-44
Running Java Programs
Learn more about running Java programs in JDeveloper:
● Running an Applet
● Running an Application
● Running a JSP
● Running an EJB
● Running a Servlet
● Running JClient Applications with Web Start
● Running Applications and Applets with Web Start
9-45
Running an Applet
JDeveloper uses the AppletViewer to run applets. After creating your applet and ensuring that
the classpath is set up properly in the HTML file, you can run it by executing the Run command
in one of the following ways:
1. In the Navigator, select the HTML file that contains the <APPLET> tag.
2. Run an applet in any of these ways:
❍ Choose Run | Run from the main menu.
❍ Right-click the HTML file and choose Run from the context menu.
❍ Select the HTML file and click on the toolbar.
The applet is launched in the Applet Viewer.
Using an HTML file to store arguments
An applet runs in an HTML page, from which it obtains its display size and other parameters.
To run an applet in JDeveloper, you need to provide an HTML file containing the appropriate
<APPLET> tag. In the Naviagor, select the HTML file from the project tree and choose Run
<filename.html> from the context menu.
Parameter names are case-sensitive, although parameter tags are not:
<APPLET CODE="foo.class" WIDTH=200 HEIGHT=20>
</APPLET>
You can also pass parameters to the applet by including a <PARAM> tag between the
<APPLET> and </APPLET> tags as shown below:
<PARAM NAME=foo VALUE=true>
Example HTML fragment used to pass parameters
...
<H1>Test File</H1>
<HR>
<APPLET CODE="Test3.class" WIDTH=500 HEIGHT=120>
<PARAM NAME=level VALUE="8">
9-46
<PARAM NAME=angle VALUE="45">
<PARAM NAME=delay VALUE="1000">
<PARAM NAME=axiom VALUE="F">
<PARAM NAME=incremental VALUE="true">
<PARAM NAME=border VALUE="2">
</APPLET>
<HR>
<A HREF="Test3.java">The source</A>.
...
Related topics
Creating an Applet
Debugging an Applet
Configuring Your Project to Use the Embedded OC4J Server
9-47
After building your application, you can run it by executing the Run command in one of the
following ways:
1. In the Navigator, select the application file or project you want to run.
2. Run an application in any of these ways:
❍ Choose Run | Run <source_file>.java from the main menu or choose Run |
Run <project>.
❍ Right-click the Java file or project containing your application and choose Run
❍ Right-click the Java file or project containing your application and click on the
toolbar.
The main method of your Java application is started.
Related topics
Running a Project From the Command Line
Running an Applet
Running an EJB
Running a JSP
Running a Servlet
9-48
Running a JSP
The embedded OC4J server is responsible for running JSPs in JDeveloper. After building your JSP, you
can run it by executing the Run command in one of the following ways:
1. In the Navigator, select the JSP file you want to run.

2. Run a JSP in any of these ways:
❍ Choose Run | Run <source_file>.jsp from the main menu.
❍ Right-click the JSP file and choose Run from the context menu.
❍ Select the JSP file and click on the toolbar.
The JSP is launched.
JDeveloper performs the following functions when a JSP is run:
● Translates the JSP into a servlet and compiles it.

● Starts the embedded OC4J server process.
● Runs the resulting classes directly from the output project directory.
● Edits the embedded OC4J web.xml file to include the servlet name and class information.
● Invokes the JSP in your default Web browser. For example, your browser is launched as follows:
http://<your_machine_IP_address>:<http_port>/<context_root>/<path_to_JSP>
Example
http://127.0.0.1:8988/Project1-context-root/untitled1.jsp
Dynamically Modifying JavaServer Pages Files While Running in

JDeveloper
When running your JSP in the embedded OC4J server, you can modify and view changes that you make
to your JSP files without having to restart OC4J. To view changes in your browser, you can either reload
the page from the browser or you can run the page again in JDeveloper. Because the embedded OC4J
server is able to change only the file, running from JDeveloper is much faster than reloading the page
from the browser.
Running JSPs with BC4J application modules
If you are running JSPs with BC4J application modules in both the embedded OC4J server and in a
remote OC4J instance and have two JSPs contained in two different projects that depend on the same
middle tier project, you must declare that BC4J is running inside of an OC4J instance with the following
property:
9-49
jbo.server.in_oc4j=true
Related Topics
About the Embedded OC4J Server

Running an Applet
Running an EJB
9-50
Running an EJB
After building your EJB, you can run it by executing the Run command in one of the following
ways:
1. In the Navigator, select the EJB class or the Java file containing your EJB that you want
to run.
2. Run an EJB in any of these ways:
❍ Choose Run | Run MySessionEJB from the main menu.
❍ Right-click MySessionEJB and choose Run MySessionEJB from the context
menu.
3. You will need a client such as a servlet, JSP, BC4J tester, or regular Java application to
access the EJB.
JDeveloper performs the following functions when a EJB is run:
● Compiles the EJB source code. The entire EJB module is debug when you choose to
debug the EJB, not just the EJB node you selected to debug.
For more information about EJBs, see the "Oracle9iAS Containers for J2EE Enterprise
JavaBeans Developer's Guide and Reference" Part Number A95881-01, which is provided with
your Oracle9iAS documentation library. This guide tells you what you need to know to develop
EJBs in the OC4J environment.
Related topics

Running an Applet
Running a Servlet
Running a JSP
About Embedded OC4J Configuration Files
9-51
Running a Servlet
A servlet is a Java program that runs in a J2EE application server. Think of a servlet as the server-side counterpart to a Java applet.
The Embedded OC4J Server is responsible for running servlets in JDeveloper. After building your servlet, you can run it by
executing the Run command in one of the following ways:
1. In the Navigator, select the Java file containing your servlet that you want to run.
2. Run a servlet in any of these ways:
❍ Choose Run | Run <servletname>.java from the main menu.
❍ Right-click the Java file containing your servlet and choose Run <servletname>.java from the context menu.
❍ Select the Java file containing your servlet and click on the toolbar.
JDeveloper performs the following functions when a servlet is run:
● Compiles the servlet source code.

● Edits the embedded OC4J web.xml file to include the servlet name and class information.
● Invokes the servlet in your default Web browser. For example, your browser is launched as follows:
http://<your_machine_IP_address>:<http_port>/<context_root>/servlet/<servlet_full_class_name>
Example
http://127.0.0.1:8988/Project1-context-root/servlet/package1.Servlet1
For more information about servlets, see the "Oracle9iAS Containers for J2EE Servlet Developer's Guide" Part Number A95878-01,
which is provided with your Oracle9iAS documentation library. This guide tells you what you need to know to develop servlets and
Web-tier applications in the OC4J environment.
To get complete documentation on the servlet APIs, visit the Sun Microsystems Web site at:
http://java.sun.com/j2ee/docs.html
Related topics
Running an Applet
Running a JSP
Running an EJB
About Embedded OC4J Configuration Files
9-52
Running JClient Applications with Web Start in
JDeveloper
Before you deploy your JClient application or applet to a production web server, you can use
the JDeveloper-embedded OC4J web server to simulate the user's experience of running the
application with the Java Web Start software from Sun Microsystems.
Note: You cannot debug a JClient application in JDeveloper while running with Java Web Start.
You will use the deployment profiles generated by the JClient Java Web Start Wizard to setup
the JDeveloper-embedded web server with you application libraries and jar files. Java Web
Start relies on the JNLP file the wizard generates to identify which files to download and how to
launch the application.
To set up the JDeveloper-embedded OC4J Web Server:
1. Configure your project to use the embedded OC4J server.

2. Optionally, set preferences for the embedded OC4J server.
3. Set up runtime configuration information for the business components deployment
scenario you choose.
Note: Choose the default local runtime configuration when you just want to test the business
components using local-mode deployment. This option uses the same VM to run the business
components and JClient libraries. It also eliminates potential security conflicts that can occur
in the remote deployment runtime configuration. Later, when you want to deploy the Business
Components to a remote OC4J or VisiBroker web server, signing your JAR files may be
necessary.
4. Run the JClient Java Web Start Wizard to generate the deployment profiles and JNLP
files. It is recommended that you choose JNLP generated dynamically - JSP in the Java
Web Start Wizard in order to dyanmically generate the JNLP definition from a generated
JSP page.
5. Select and right-click the <client> profile in the JClient project and choose Deploy to
create a Java Archive in your public.html directory.
6. Select and right-click the <mymt> profile in the JClient project and choose Deploy to
create a simple ZIP archive in your public.html directory.
Note: The business component middle-tier libraries will be deployed to the web server for you
by JDeveloper.
9-53
To run the JClient application within JDeveloper using Java Web Start:
1. Install the Java Web Start software on your machine. The software is available for
download from Sun Microsystem at http://java.sun.com/products/javawebstart/.
2. Right-click the .html file that the JClient Java Web Start Wizard added to your JClient
project and choose Run to launch your web browser with this page.
3. Click the Launch JClient Project link to run your application using the Java Web Start
software.
4. You can close your browser once Java Web Start completes the download and launches
the application. Java Web Start lets you run both applications and secure applets.
Note: The next time you run the application, Java Web Start will download only those class
files or libraries that have changed from the previous download.
Related topics


About the Embedded OC4J Configuration Files in JDeveloper
9-54
Running Applications and Applets with Web Start in
JDeveloper
Before you deploy your application or applet to a production web server, you can use the
embedded OC4J server to simulate the user's experience of running the application with the
Java Web Start software from Sun Microsystems. Use the default local mode configuration for
the Business Components runtime deployment. In the case of Java Web Start, the local mode
configuration eliminates potential security conflicts that can occur in the remote deployment
runtime configuration. Later, when you want to deploy the Business Components to a remote
OC4J or VisiBroker web server, signing your JAR files may be necessary.
Note: You cannot debug an application in JDeveloper while running with Java Web Start.
You will need to create a deployment profile to set up the embedded OC4J server with your
application libraries and JAR files. Java Web Start relies on the JNLP file that the wizard
generates to identify which files to download and how to launch the application.
To set up the JDeveloper-embedded OC4J Web Server:
1. Configure your project to use the embedded OC4J server.

2. Optionally, set preferences for the embedded OC4J server.
3. Create a simple archive (JAR) file for the application components.
4. Run the Java Web Start Wizard to generate the JNLP and HTML files.
5. Create the deployment profile.
To run the application or applet using Java Web Start:
2. Right-click the .html file that the Java Web Start Wizard added to your project and
choose Run to launch your web browser with this page.
3. Click the Launch Project link to run your application using the Java Web Start software.
Note: The next time you run the application, Java Web Start will download only those source
9-55
Related topics
About Java Web Start

Creating a Web Start JNLP Definition for Applications and Applets
Deploying a Java Client Web Application Archive for Java Web Start

9-56
Running a Project from the Command Line
Environment
Learn more about running a project from the command line environment:
● Running a Project from the Command Line

● Setting the Classpath for Your Programs
● About the Setvars Command (Windows)
9-57
Running a Project from the Command Line
The following conditions must exist to run a project from the operating system command line:
● The project is a standalone executable.

● You must select the class file containing the application main() method.
To launch an application:
java -cp c:\<jdev_home>\jdev\mywork\Workspace1\Project1\classes
package1.Application1
To launch the executable JAR file from the command line:
java -jar myapp.jar
where myapp is replaced with your JAR file name.
Related topics
Compiling With Make

9-58
Setting the Classpath for Your Programs
When you run a Java program, you must provide the Java Virtual Machine (JVM) with a list of
the paths to the class files and libraries that comprise your application. The form of the
classpath changes depending on the method you use to run the Java program.
Your Java classes can be stored in Java ARchive (*.jar) files, or as separate class
(*.class) files in their package directory. There are differences in the ways Java handles JAR
files and package directories.
● When you refer to Jar files in your CLASSPATH, you use the fully qualified path to the Jar
file.
● When you refer to package directories in your CLASSPATH, you use the path to the
parent directory of the package.
● You can refer to both JARs and package directories in a CLASSPATH statement. When
you refer to more than one CLASSPATH in the same statement, each CLASSPATH is
separated with a semicolon(;).
Once you have defined the classpath, you pass the value to the JVM in different ways,
depending on how you run your Java program.
● Set the CLASSPATH environment variable to run a standalone application using

java.exe.
● Set the classpath as a parameter to run a standalone application using the Java Runtime
Engine (jre.exe).
● Embed the classpath in the <APPLET> tag of an .html file to run an applet in an Internet
browser.
According to Java Sun, you have the option of using either the -classpath option when
calling an SDK tool (the preferred method) or by setting the CLASSPATH environment variable.
For more information, see the following URL:
http://java.sun.com/products/jdk/1.3/docs/tooldocs/win32/classpath.html.
Setting the CLASSPATH Environment Variable (for java.exe)
The java.exe is included as part of the Java2 Standard Edition (J2SE). It is intended to be
9-59
used as a development tool, and is not licensed for distribution with your Java programs. It is
used to test your Java applications from the command prompt.
In order to run a Java application from the command prompt, the system environment variable
CLASSPATH must be defined to include all of the classes necessary to run your program. This
includes both the library classes that come with JDeveloper and your own class files.
The JDeveloper Library CLASSPATH
JDeveloper ships hundreds of library classes to help you generate your Java programs. The
classes come from Sun Miscrosystems J2SE, third-party developers, and Oracle Corporation.
Each of the libraries are kept separate for easy upgrade. As a result, many archive files need to
be included in your classpath to ensure that any program you create in JDeveloper can be run
from the command prompt.
While every project you create will not use all of these libraries, it doesn't hurt to list paths to the
ones you don't use. If you don't use the classes, the paths are ignored at runtime.
The command to set the CLASSPATH variable takes this format:
set CLASSPATH=path1;path2;path3;...path_n
Note: Never use quotation in the classpath even when there is a space character in one of the
paths.
Setting the CLASSPATH to Include Your Projects
If you have used the default directory for your output path, you can test your Java application
using java.exe by appending the following directory to your classpath:
C:\<JDEV_HOME>\jdev\mywork
Having set this variable, you can use java.exe to run your application from the output
directory mywork.
If you have deployed your Java program to any other directory, you need to add the path to the
parent directory of the application package.
The CLASSPATH variable is a long string that can be difficult to type accurately. To save time
and reduce errors, you can set the CLASSPATH as a system environment variable.
9-60
Setting the CLASSPATH Parameter (for jre.exe)
The Java Runtime Engine (jre.exe) doesn't use the CLASSPATH environment variable. The
CLASSPATH must be included as a parameter to the jre.exe command. The format for the
command is:
jre -cp "classpath" package.Application
Where classpath is the complete CLASSPATH to your Java program and the dependency
classes it uses. The quotation marks are optional if there are no spaces in any of the
CLASSPATH directory names.
Embedding the CLASSPATH Parameters in the <APPLET> Tag
When running applets, the browser uses a CLASSPATH you supply in the ARCHIVE and
CODEBASE parameters to the <APPLET> tag in the host *.html file.
The CODEBASE parameter sets the root directory where the Internet browser will look for your
class files. If the classes are stored in the same directory as the HTML page calling the applet,
you can omit the CODEBASE parameter entirely. Otherwise, use either an absolute or relative
path from the HTML file to the location of the CODEBASE directory. Use forward slashes (/), not
backslashes(\) to indicate directories.
The ARCHIVE parameter lists the locations and names of the *Jar files that contain your
program and its supporting library files, similar to the CLASSPATH used with applications. There
are three important differences:
● The names of the Java Archive files are separated by commas (,), not semicolons(;).
● If the Java Archive files are in subdirectories of the CODEBASE, use forward slashes (/),
not backslashes(\), to indicate directories.
● Due to the limitations enforced by the Java security model for applets, classes
referenced by your ARCHIVE parameter can only be located in subdirectories of the
CODEBASE directory. This means that if you attempt to set the location of an archive file
using a parent directory (../) you will receive a security violation error.
Related topics
9-61
Deploying an Executable JAR
9-62
Debugging in JDeveloper
Learn more about debugging in JDeveloper:
● About the Debugger

● About Debugger Icons
● Configuring Your Project for Debugging
● Debugging a Project in JDeveloper
● Using the Code Editor When Debugging
● About the Debugger Windows
● Debugging Java Programs
● Remote Debugging
9-63
About the Debugger
The debugger enables you to control the execution of a program by:
● Running to a breakpoint
● Stepping (Into, Over, Out)
● Running to the cursor location
● Setting the next statement
● Pausing the program
When the program is paused, you can use the following debugger windows to examine the
program you are debugging:
● Threads window
● Stack window
● Data window
● Smart Data window
● Watches window
● Classes window
● Heap window
● Monitors window
● Inspector window
While some debugger features are available from the Debug main menu, you can also right-
click in a debugger window and choose options from the context menu.
Related topics

Configuring Your Project for Debugging
About the Debugger Windows
About Debugger Icons
Debugging a Project in JDeveloper
9-64
Using the Code Editor When Debugging
Setting Preferences for the Debugger Windows
9-65
The following is a list of the various debugger and runner icons. Some of these icons are
available on the JDeveloper main toolbar which you can click to perform a particular task and
some of these icons may also appear in the debugger windows which you can display by
choosing View | Debug Windows - <name of window>.
Array
Represents an array class in the Classes Window or an array in the Data window.
Breakpoints menu
Represents the View | Debug Windows - Breakpoints menu option or the tab icon for the
Breakpoints window.
Class
Represents the View | Debug Windows - Classes menu option, the tab icon for the
Classes window, and a class in the Classes window (grayed if the class is tracing
disabled).
Class Without Line Number Tables

Appears in the Classes Window. Represents a class which does not have line number
tables (obfuscated class).
Current Execution Point
Represents the current execution point shown in the Code Editor margin which you can
display by choosing the Debug | Show Execution Point menu option.
Current Thread
Represents the current thread in the Threads window.
Data
Represents the View | Debug Windows - Data menu option and the View | Debug
Windows - Smart Data menu option and the tab icon for the Data window and Smart
Data window.
Debug (Shift + F9)
Represents the Debug | Debug menu option, the Debug toolbar button which you can
click, a debugging process contained in the processes folder in the Run Manager
navigator, a log page for a debugging process, the debug layout, and the Remote
Debugging and Profiling Project Wizard.
Debug Listener Node
9-66
Represents a debug listener node in the Run Manager navigator.
Disabled Breakpoint
Represents a disabled breakpoint in the Code Editor margin and a disabled breakpoint in
the Breakpoints window.
Garbage Collector
Represents the Debug | Garbage Collection menu option and the Garbage Collection
toolbar button which you can click.
Heap Folder
Represents a folder in the Heap window.
Heap
Represents the View | Debug Windows - Heap menu option and the tab icon for the
Heap window.
Interface
Identifies an interface in the Classes Window.
Method
Represents the View | Debug Windows - Stack menu option, the tab icon for the Stack
window, and a method in the Stack window.
Monitors
Represents the View | Debug Windows - Monitors menu option and the tab icon for the
Monitors window.
Object
Represents an object in the Data Window.
Package
Represents a package in the Classes Window (grayed if the package is tracing
disabled).
Pause
Represents the Debug | Pause menu option and the Pause toolbar button which you can
click.
Primitive
Represents the View | Debug Windows - Data menu option, the tab icon for the Data
Window, and a primitive item in the Data Window.
Resume (F9)
9-67
Represents the Debug | Resume menu option and the Resume toolbar button which you
can click.
Run
Represents a running process in the Run Manager navigator, in a log page for a running
process, and in the toolbar to run the selected node.
Run to Cursor (F4)
Represents the Debug | Run to Cursor menu option. Lets you run to a specified location
and execute the code until it reaches that location.
Stack
Represents the View | Debug Windows - Stack menu option and the tab icon for the
Stack window.
Set Next Statement
Represents the Debug | Set Next Statement menu option.
Step to End of Method
Represents the Debug | Step to End of Method menu option and the Step to End of
Method toolbar button which you can click.
Static Folder
Represents the static folder in the Data Window.
Step Into (F7)
Represents the Debug | Step Into menu option and the Step Into toolbar button which
you can click.
Step Out
Represents the Debug | Step Out menu option and the Step Out toolbar button which
you can click.
Step Over (F8)
Represents the Debug | Step Over menu option and the Step Over toolbar button which
you can click.
Terminate
Represents the Terminate toolbar button which you can click to stop debugging your
application.
Thread
Represents the View | Debug Windows - Threads menu option, the tab icon for the
9-68
Threads window, and a thread in the Threads window.
Thread Group
Represents a thread group in the Threads window.
Unverified Breakpoint
Represents an unverified breakpoint in the Code Editor margin, and an unverified
breakpoint in the Breakpoints window.
Verified Breakpoint
Represents a verified breakpoint in the Code Editor margin and a verified breakpoint in
the Breakpoints window.
Watch
Represents the View | Debug Windows - Watches menu option and the tab icon for the
Watches window.
Related Topics
About Debugger Windows

Examining Program State in Debugger Windows
9-69
JDeveloper allows you to control how your program is debugged, including specifying which
packages and classes tracing is enabled or disabled and configuring remote debugging
options.
To configure debugger and remote debugger options in JDeveloper:
menu.
2. The Project Settings dialog appears.
3. Click the Debugger node below the Development node to see all the options.
4. Configure the tracing options and the Scope for New Breakpoints.
5. (optional) Click the Debugger - Remote nodes to configure these options such as which
remote debugging protocol to use when debugging (OJVM, JPDA).
6. Click Help for more information.
To compile the class and start the debugger:
1. In the Project Setttings panel, click the Configurations - Development - Compiler node.
2. If not already enabled, select the Include Debug Information check box.
3. Click OK.
4. In the Navigator, select the project node then choose Debug | Debug <project
name>, or click from the toolbar.
Once the project or class compiles successfully, the debugger starts.
Note: The project compiles according to the options selected from the Project | Project
Settings... - Runner - Options panel.
Related topics

About the Breakpoints Window
Controlling Which Classes are Traced Into
9-70
About Remote Debugging
9-71
Your code must be compiled with debugging information before you can make use of some of
the debugger features such as viewing arguments and local variables in the Data window.
See About Debugger Icons to determine the purpose and functions of the various debugger
icons displayed on the toolbar or in the debugger windows. Each of these commands is also
available from the Debug main menu.
To set breakpoints and step through your code:
1. In the Code Editor, set a breakpoint on an executable statement by clicking in the margin
to the left of the statement.
A red circle appears in the left margin.
2. Select Debug | Debug [filename.java] or click on the toolbar.
The class runs, and stops at the first breakpoint.
3. From the toolbar, click Step Into to trace into a method call, or click Step Over to
step over a method call.
4. Look in the Stack window to examine the sequence of method calls that brought your
program to its current state. Double-click a method to display the associated source code
in the Code Editor.
5. In the Smart Data and Data windows, examine the arguments and variables.
6. Display the Threads window to see the status of other theads in your program.
To edit and recompile:
1. When you have found lines of code to change, you can end the debugging session by
clicking Terminate on the toolbar, or by choosing Run | Terminate.
2. Edit your code in the Code Editor.
3. Click the appropriate node, then choose Project | Make [filename.java] from the main
menu. The affected files in your project are recompiled, and you can run the debugger
again.
Related topics
9-72
9-73
When the debugger stops, (for example, at a breakpoint, completing a step command, or
paused), the source file for the current class will open in the Code Editor and will be marked
with the execution point . If JDeveloper cannot locate the source file for the class while
debugging, the Source Not Found dialog box is displayed prompting you for the source file
location.
You can choose from the following options:
● Generate a source file stub for the class.

● Don't generate a source file stub for the class.
● Let me find the file myself.
After choosing an option, the resulting source file will appear in the Code Editor. The stub
source file shows only the method signatures for the class. To avoid seeing stub source, you
can exclude the classes for which you don't have the source files available, or make their
source files available.
Related Topics

Moving Through Code While Debugging
Modifying Data Elements
9-74
You can display the following debugger windows by choosing the View | Debug Windows |
<name of window> command from the main menu.
Breakpoints Window
Displays the breakpoints for the current workspace and project.
Threads Window
Displays the threads and the thread groups.
Watches Window
Displays the values of the watch expressions.
Stack Window
Displays the call stack for the current thread.
Data Window
Displays information about variables and arguments for the current method.
Smart Data Window
Displays the data that appears to be relevant to the source code that you are stepping
through.
Classes Window
9-75
Displays information on classes including a count of the number of instances of each
class listed and the amount of memory being consumed by instances of each class.
Heap Window
Displays information about the heap in the program you are debugging. Class folders
display all instances of a class and Reference Path folders show you why an object has
not been garbage collected. The Heap window is only available when you debug with the
Oracle Java Virtual Machine.
Monitors Window
Displays information for active monitors. This window is useful for examining deadlocks
and other thread synchronization problems.
You can control what type of information is displayed in each of the debugger windows. To see
what options are available in each window such as which columns to display, right-click in a
window and choose Settings... from the context menu. Or, you can choose Tools |
Preferences... from the main menu and expand the Debugger node to display a preferences
panel for each debugger window.
For more information, select the debugger window to make it active and press F1 to display its
Help topic.
Related topics

About the Data Window
About the Smart Data Window
About the Watches Window
About the Inspector Window
About the Stack Window
About the Monitors Window
About the Threads Window
About the Classes Window
About the Heap Window
9-76
9-77
A breakpoint is a trigger in a program that, when reached, pauses program execution allowing
you to examine the values of some or all of the program variables. By setting breakpoints in
potential problem areas of your source code, you can run your program until its execution
reaches a location you want to debug. When your program execution encounters a breakpoint,
the program pauses, and the debugger displays the line containing the breakpoint in the Code
Editor. You can then use the debugger to view the state of your program. Breakpoints are
flexible in that they can be set before you begin a program run or at any time while you are
debugging.
Breakpoints set on comment lines, blank lines, declarations, and other non-executable lines of
code are invalid and will not be verified by the debugger.
The JDeveloper debugger supports a number of different types of breakpoints:
● Source breakpoints
● Exception breakpoints
● Method breakpoints
● Class breakpoints
● Deadlock breakpoints
Note: For information about the Breakpoints window including its context menu options, press
F1 in the Breakpoints window.
To open the Breakpoints window which displays a list of set breakpoints:
● Choose View | Debug Windows | Breakpoints from the main menu.

The Breakpoints window appears.
To change which columns are displayed in the Breakpoints window:
● Right-click in the Breakpoints window and choose Settings... from the context menu.
Related Topics
9-78
Setting Source Breakpoints
Setting Exception Breakpoints
Making a Breakpoint Conditional
About Deadlocks
Managing Breakpoint Groups
9-79
The Classes window displays which classes have been loaded and may also include useful
information such as the number of instances of a class, and how much memory those
instances are using if you are using Oracle Java Virtual Machine (OJVM). In conjunction with
the Classes window and the Heap window, the debugger now includes a Garbage Collection
tool when you want to force a run of the Java Garbage Collector. When you run the Garbage
Collector, the impact is shown immediately in the Classes window. You can only force a run of
the Garbage Collector when you are using a virtual machine that allows the debugger to do so.
Note: For more information about this window including its context menu options, press F1 in
the Classes window.
To open the Classes window:
1. Set a breakpoint in the Code Editor and start a debugging session.

2. When the debugger hits a breakpoint, select View | Debug Windows | Classes.
The Classes window displays all the classes that are loaded at the current execution
point, how many instances of that class are being used, and how much memory that
number of instances requires.
To toggle information that is displayed in the Classes window:
● Right-click an item in the Classes window and choose Settings... from the context menu.
To change the ascending or descending view order:
● Click the sort arrows at the top of each column to change the sort order. You can sort by:
❍ Class
❍ Count
❍ Memory
Note: You can sort only if the Show Package Structure check box is not selected in the the
Tools | Preferences - Debugger - Classes panel.
If the Show Package Structure check box is selected, the classes are displayed in a tree
structure, where each branch represents a package. Also, the icon and entry next to each class
9-80
or package indicates whether the class is included or excluded from tracing. A special icon for a
class without line number tables is used for classes to indicate that tracing is not possible
because the class has been stripped or obfuscated.
In the Classes window, choose Settings... from the context menu to select which columns to
view:
● Count
● Memory
● File
Related topics

Controlling which Classes are Traced into
9-81
You use the Data window to display information about variables in your program. The Data
window displays the arguments, local variables, and static fields for the current context, which
is controlled by the selection in the Stack window. If you move to a new context, the Data
window is updated to show the data for the new context. If the current class was compiled
without debug information, you will not be able to see the local variables. However, if you are
debugging with the Oracle Java Virtual Machine (OJVM), the debugger analyzes the local
variable memory locations in the stack frame to show you as much information as possible.
the Data window.
To open the Data window:
1. Open a source file in the Code Editor and set at least one breakpoint.
2. Click Debug.
3. When the debugger pauses at a breakpoint, select View | Debug Windows | Data from
the main menu.
The Data window appears.
To change which columns are displayed in the Data window:
● Right-click in the Data window and choose Settings... from the context menu.
For large arrays, you can adjust the range of arrays that get displayed in the Data window:
1. In the Data window, expand the array so that the child nodes are displayed for the
elements of the array.
2. Select an array , right-click, and choose Adjust Range... from the context menu.
Note: This feature does not let you modify the array itself. The Adjust Range dialog only lets
you control which array elements are displayed when you expand the selected array node in
the Data window.
9-82
Related topics

9-83
The Heap window displays information about the heap in the program you are debugging and
helps you to detect memory leaks in your program. You can view all instances of a class as
well as why an object has not been garbage collected. For more information about this window
including its context menu options, press F1 in the Heap window.
Note: Only the Oracle Java Virtual Machine (OJVM) provides heap information. Heap
information is not provided by Sun Microsystem's Java Platform Debugger Architecture (JPDA),
the debugging protocol used with the Classic and HotSpot Java Virtual Machines. If you are
using either the Classic or the HotSpot virtual machine (the VM is specified in the Project |
Project Settings... - Runner Panel), the Heap window will not be able to provide any information
about the heap in the program you are debugging.
There are two types of folders displayed in the Heap window:
Class Folder
Displays the name of the class and how many instances of the class exists in memory,
and when expanded lists the specific instances and their addresses in the heap.
Reference Path Folder

Contains all the "root" references which point, either directly or indirectly, to a specific
object. Root references are static fields, stack variables, pinned objects. The garbage
collector will not not discard an object if there are any root references. Expanding a root
reference will show you the reference path from the root reference to the specified
object.
To open and use the Heap window:
1. In the Code Editor, set at least one breakpoint and click Debug.
2. When the debugger hits the breakpoint, select View | Debug Windows | Heap from the
main menu.
The Heap window appears.
3. Right-click in the Heap window and choose Add Class Folder... from the context menu.
Alternatively, drag a class node from the Classes window into the Heap window. Or, right
click on a class node in the Classes window and choose Show In Heap from the context
menu.
Information about the classes appears in the Heap window.
9-84
Related Topics

9-85
The Inspector window allows you to single out a selected variable, field or object, and display
the same information that is available in the Watch or Data windows. For more information
about this window including its context menu options, press F1 in the Inspector window.
The Inspector window is slightly different from the other windows in that it floats by default, and
you can have multiple instances of Inspector windows. Each Inspector window contains one
data item.
To open the Inspector Window:
1. Set at least one breakpoint in the Code Editor.

2. Click Debug from the toolbar.
3. When the debugger reaches a breakpoint, select a variable in the Code Editor, right-
click, and choose Inspect...
The Inspect dialog appears and contains the variable you selected. If you want to inspect
something else, enter a new expression or variable in the text field, or select a previous
one from the dropdown list.
4. Click OK to open the Inspector window.
The Inspector window will appear floating in the center of your screen. You can dock the
Inspector window. An inspector evaluates an expression according to the current context of the
Stack window. If you move to a new context, the expression is re-evaluated for the new
context. If the execution point moves to a new location where any of the variables in the
expression are undefined, the entire expression becomes undefined. If the execution point
returns to a location where the expression can be evaluated, the inspector again displays the
value of that expression.
Related Topics

9-86
Using Acceptable Legal Java Expressions in the Debugger
9-87
Java supports multithreading at the language level through the use of synchronization.
Synchronization is the coordinating of activities and data access among multiple threads. The
mechanism that Java uses to support synchronization is the monitor. The Monitors window
displays status and control information for active monitors.
The Monitors window is useful in detecting deadlocks in your programs. The Monitors sub-
section is actually a data panel, so objects and arrays can be expanded, similar to the Data and
Watches windows. The Owning Thread, Waiting Threads, and Blocked Threads sub-sections
are actually thread panels, so they show much of the same information as the Threads window.
the Monitors window.
To open the Monitors window:
1. In the Code Editor, set at least one breakpoint.

3. When the debugger stops at the breakpoint, select View | Debug Windows | Monitors.
Related topics
About Deadlocks
9-88
Unlike the Data window which displays all arguments, local variables, and static fields for the
current method, the Smart Data window displays only the data that appears to be relevant to
the source code that you are stepping through. Specifically, the debugger analyzes the source
code near the execution point and finds the variables, fields, and expressions, that are used
in the lines of code that you are stepping through.
By default, the debugger analyzes only one line of code for each location and analyzes up to
two locations. You can adjust these settings in the Tools | Preferences - Debugger - Smart
Data panel which you can also access by right-clicking in the Smart Data window and choosing
Settings... from the context menu.
the Smart Data window.
To open the Smart Window:
1. Set a breakpoint in the Code Editor and start a debugging session.

3. When the debugger hits a breakpoint, select View | Debug Windows | Smart Data.
Related topics

9-89
The Stack window displays the call stack for the current thread. When you highlight a line in the
Stack window, the Data window, Watches window, and all Inspector windows are updated to
show data for the highlighted method.
the Stack window.
To open the Stack window:
1. Open the source file in the Code Editor and set at least one breakpoint.
3. From the main menu, select View | Debug Windows | Stack.
The Stack window appears.
Related topics

Locating the Execution Point for a Thread
9-90
The Threads window displays the names and status of all the threads and thread groups in
your program. For more information about this window including its context menu options,
press F1 in the Threads window.
To open the Threads window:
1. Open the source file in the Code Editor and set at least one breakpoint.
3. When the debugger stops at a breakpoint, choose View | Debug Windows | Threads
from the main menu. The step commands including Step Over, Step Into, and Set Next
Statement apply to the current thread. To select a different thread, right-click a thread
and choose Select Thread from the context menu.
When you highlight a thread in the Threads window, the Stack window is automatically
updated to show the stack for the highlighted thread.
Related topics

9-91
A watch enables you to monitor the changing values of variables or expressions as your
program runs. After you enter a watch expression, the Watch window displays the current value
of the expression. As your program runs, the value of the watch changes as your program
updates the values of the variables in the watch expression.
A watch evaluates an expression according to the current context which is controlled by the
selection in the Stack window. If you move to a new context, the expression is re-evaluated for
the new context. If the execution point moves to a location where any of the variables in the
watch expression are undefined, the entire watch expression becomes undefined. If the
execution point returns to a location where the watch expression can be evaluated, the
Watches window again displays the value of the watch expression.
the Watches window.
To open the Watches window:
1. Open a source file in the Code Editor and set at least one breakpoint.
3. When the debugger pauses at a breakpoint, select View | Debug Windows | Watches
from the main menu.
The Watches window appears.
To change which columns are displayed in the Watches window:
● Right-click in the Watches window and choose Settings... from the context menu.
To add a watch:
● Right-click an item in the Data window and choose Watch from the context menu.
● Drag and drop variables, fields, and objects from the Data window to the Watches
window.
To watch a static field:
Enter the full name of the class followed by a period (dot) and the name of the field. For
9-92
example:
java.io.File.separator
To watch the current exception while stopped at an exception breakpoint, enter:
_throw.
Related topics

Setting Expression Watches
9-93
You can choose to customize various debugger window settings including the column resize
mode and other options you want to display. If the debugger has trouble connecting to the
debuggee, try increasing the connection retry setting.
To set any of the Debugger window preferences:
1. Choose Tools | Preferences - Debugger panel.

The debugging panel appears with customizable fields.
2. Make your selections from the fields and options provided.
3. To set any options for a specific debugger window, click the appropriate node below the
Debugger node. For example, if you want to change the columns displayed in the Smart
Data window, click Smart Data.
4. Edit any of the available options as desired.
5. Click OK when you are done.
6. Click Help for information on any panel.
Related topics
About Breakpoints
9-94
Debugging is the process of locating and fixing errors in your programs. The JDeveloper
integrated debugger enables you to debug Java applications, applets, servlets, JavaServer
Pages (JSPs), and Enterprise JavaBeans (EJBs). You can debug a single or several objects on
the same or different machine as JDeveloper supports distributed debugging.
Learn more about debugging Java programs:
● Debugging an Applet
● Debugging a JSP
● Debugging a Servlet
● Debugging an EJB
● Moving Through Code While Debugging
● Managing Breakpoints
● Examining Program State in Debugger Windows
9-95
Debugging an Applet
To debug an applet:
1. In the Navigator, select the HTML file that contains the <APPLET> tag.
2. Right-click and choose Debug <name of applet> from the context menu or click in
the toolbar.
The applet starts. The debugger will stop at breakpoints you have set in your applet's
source code.
Related topics
Running an Applet
Running Applications and Applets with Web Start in JDeveloper
Creating an Applet
Debugging an Applet
9-96
Debugging a JSP
Debugging a JSP is very similar to debugging any other Java program; you should set at least one
breakpoint before you launch the debugger. Execute the Debug command in one of the following ways:
To debug a JSP:
1. In the Navigator, select the JSP file you want to run.

2. Debug a JSP in any of these ways:
❍ Choose Debug | Debug <source_file>.jsp from the main menu.
❍ Right-click the JSP file and choose Debug from the context menu.
❍ Select the JSP file and click on the toolbar.
The JSP is launched.
3. Debug your JSP as you would any other Java application.
JDeveloper performs the following functions when debugging a JSP:
● Translates the JSP into a servlet and compiles it.

● Invokes the JSP in your default Web browser. For example, your browser is launched as follows:
http://<your_machine_IP_address>:<http_port>/<context_root>/<path_to_JSP>
Example
http://127.0.0.1:8988/Project1-context-root/untitled1.jsp
Related topics
Running a JSP
9-97
Debugging a Servlet
You can debug a servlet within JDeveloper using the embedded OC4J server. The Debug command attempts to debug the selected
Java file containing your servlet.
To debug a servlet:
1. Select the servlet Java file in the Navigator and select Debug | Debug <project name> from the JDeveloper main menu, or
click Debug. Alternatively, right-click the servlet Java file and choose Debug.
2. When you debug a servlet, JDeveloper opens the default Web browser and invokes the servlet.
3. Debug your servlet by setting breakpoints as you would any other Java application.
4. When you are finished running and testing the servlet, you can terminate the server by choosing Run | Terminate - Embedded
OC4J Server from the main menu.
JDeveloper performs the following functions when a debugging a servlet:
● Compiles the servlet source code.

● Invokes the servlet in your default Web browser. For example, your browser is launched as follows:
http://<your_machine_IP_address>:<http_port>/<context_root>/servlet/<servlet_full_class_name>
Example
http://127.0.0.1:8988/Project1-context-root/servlet/package1.Servlet1
For more information about servlets, see the "Oracle9iAS Containers for J2EE Servlet Developer's Guide" Part Number A95878-01,
which is provided with your Oracle9iAS documentation library. This guide tells you what you need to know to develop servlets and
Web-tier applications in the OC4J environment.
To get complete documentation on the servlet APIs, visit the Sun Microsystems Web site at:
http://java.sun.com/j2ee/docs.html.
Related topics

Running a Servlet
Terminating the Embedded OC4J Process
Ways to Deploy J2EE Applications
9-98
Debugging an EJB
Debugging a EJB is very similar to debugging any other Java program; you should set at least
one breakpoint before you launch the Debugger.
To debug a EJB:
1. Select the EJB file and choose Debug | Debug | <project name> from the JDeveloper
main menu, or click Debug. Alternatively, right-click the EJB file and choose Debug
2. Debug your EJB as you would any other Java application.
3. You will need a client such as a servlet, JSP, BC4J tester, or regular Java application to
access the EJB. The break point won't be run until you run your client.
Note: The entire EJB module is debugged when you choose to debug the EJB, not just the
EJB node you selected to debug.
The Debug command attempts to debug the selected EJB. JDeveloper performs the following
functions when debugging a EJB:
● Compiles the EJB.

● Starts the client to invoke the EJB.
Related Topics
Running an EJB
9-99
9-100
The JDeveloper debugger lets you control the execution of your program; you can control
whether your program executes a single line of code, an entire method, or an entire program
block. By manually controlling when the program should run and when it should pause, you can
quickly move over the sections that you know work correctly and concentrate on the sections
that are causing problems.
The debugger lets you control the execution of your program in the following ways:
● Stepping Into a Method

● Stepping Over a Method
● Locating the Execution Point for a Thread
● Running to the Cursor Location
● Pausing and Resuming the Debugger
● Terminating a Debugging Session
The Step Into and Step Over commands offer the simplest way of moving through your
program code. While the two commands are very similar, they each offer a different way to
control code execution.
The smallest increment by which you step through a program is a single line of code. Multiple
program statements on one line of text are treated as a single line of code; you cannot
individually debug multiple statements contained on a single line of text. The easiest approach
is to put each statement on its own line. This also makes your code more readable and easier
to maintain.
As you debug, you can step into some methods and step over others. If you are confident that
a method is working properly, you can step over calls to that method, knowing that the method
call will not cause an error. If you aren't sure that a method is well behaved, step into the
method and check whether it is working properly.
Related topics

9-101
Stepping Into a Method
The Step Into command executes a single program statement at a time. If the execution point
is located on a call to a method, the Step Into command steps into that method and places the
execution point on the method's first statement.
If the execution point is located on the last statement of a method, choosing Step Into causes
the debugger to return from the method, placing the execution point on the line of code that
follows the call to the method you are returning from.
The term single stepping refers to using Step Into to run successively though the statements in
your program code.
You can step into a method in any of the following ways:
● Select Debug | Step Into

● Press F7.
● Click from the toolbar.
Related topics
Stepping Over a Method

Running and Pausing the Debugger
9-102
The Step Over command, like Step Into, enables you to execute program statements one at a
time. However, if you issue the Step Over command when the execution point is located on a
method call, the debugger runs that method without stopping (instead of stepping into it), then
positions the execution point on the statement that follows the method call.
If the execution point is located on the last statement of a method, choosing Step Over causes
the debugger to return from the method, placing the execution point on the line of code that
follows the call to the method you are returning from.
You can step over a method in any of the following ways:
● Select Debug | Step Over

● Press F8.
● Click on the toolbar.
Related topics

Running and Pausing the Debugger
9-103
When you're debugging, the line of code that is the current execution point for the current
thread is highlighted and appears in the left margin of the Code Editor. The execution point
marks the next line of source code to be executed by the debugger.
To find the current execution point:
● Choose Debug | Show Execution Point from the main menu.

● Right-click a thread in the Threads window, and choose Go To Thread.
The debugger displays the block of code containing the execution point in the Code
Editor.
Related topics

9-104
Running to the Cursor Location
When stepping through your application code in the debugger, you may want to run to a
particular location without having to single step or set a breakpoint.
To run to a specific program location:
1. In the Code Editor, position your text cursor on the line of code where you want the
debugger to stop.
2. Run to the cursor location in any of the following ways:
❍ In the Code Editor, right-click and choose Run to Cursor.

❍ Choose the Debug | Run to Cursor option from the main menu.
❍ Press F4.
Any of the following conditions may result:
● When you run to the cursor, your program executes without stopping, until the execution
reaches the location marked by the text cursor in the Code Editor.
● If your program never actually executes the line of code where the text cursor is, the Run
to Cursor command will cause your program to run until it encounters a breakpoint or
when your program finishes.
Related topics
Pausing and Resuming the Debugger
9-105
You can pause your program when the program is running in the debugger. You can then use
the debugger to examine the state of your program with respect to this program location. When
you have finished examining that part of the program, you can then continue running the
program.
When you are using the debugger, your program can be in one of two possible states: running,
or paused by the debugger. When your program is waiting for user input, it is still considered to
be "running". When your program is in the "running" mode, Pause is available. When your
program is paused by the debugger, the debugger buttons made available include Resume,
Step Over, Step Into.
You can pause the debugger in the following ways:
● Select Debug | Pause.

● Click from the debugger toolbar.
Your program may be paused at a location for which there is no source available. In this case,
the Source Not Found dialog box is displayed prompting you for the source file location or
whether to generate stub files.
Also, your program may be paused at a location where tracing is disabled because the class is
on the tracing exclude list. For example, your program may be paused in the
java.lang.Object.wait method.
To resume the debugger when it is paused, choose Debug | Resume.
Related topics
Running a Program in the Debugger

9-106
Terminating a Debugging Session
Sometimes while debugging, you will find it necessary to restart the program from the
beginning. For example, you might need to restart the program if you step past the location of a
bug.
To terminate the current debugging session:
● Choose the Run | Terminate - <program name> menu option.

● Click Terminate in the debugger toolbar.
Terminating a debugging session closes all debugger windows. However, this action does not
delete any breakpoints or watches that you have set, which makes it easy to resume a
debugging session.
Related topics

9-107
Managing Breakpoints
Learn more about managing breakpoints:
● About Breakpoints
● Editing a Breakpoint
● About Valid and Invalid Breakpoints
● Setting Source Breakpoints
● About Deadlock Breakpoints
● Controlling Breakpoint Execution
● Disabling and Deleting Breakpoints
● Setting Exception Breakpoints
● Making a Breakpoint Conditional
● Examining Breakpoints with the Breakpoints Window
9-108
Editing a Breakpoint
To view and modify the options of a breakpoint:
1. If the Breakpoints window is not open, select View | Debug Windows | Breakpoints from
the main menu.
2. In the Breakpoints window, select a breakpoint.
3. Right-click and choose Edit Breakpoint....
The Edit Breakpoint dialog box appears with a Definition tab, a Conditions tab, and an
Actions tab.
4. Make any necessary changes to the breakpoint options.
5. Click OK to accept the changes.
From the Edit Breakpoint dialog, you can:
● Change the definition - source location or exception type of a breakpoint

● Set a condition
● Set the threads to which the breakpoint will apply
● Set a pass count for the breakpoint
● Put the breakpoint in a breakpoint group
● Choose what actions the debugger will take when the breakpoint occurs
Related topics

Examining Breakpoints with the Breakpoints Window
Disabling and Deleting Breakpoints
About Valid and Invalid Breakpoints
9-109
About Verified and Unverified Breakpoints
While debugging, you can place a breakpoint to the left of any line of code in the Code Editor.
However, for a breakpoint to be valid, it must be set on an executable line of code. Before a
method is first executed, the debugger verifies all valid breakpoints in the method. Breakpoints
set on comment lines, blank lines, declarations, and other non-executable lines of code are
invalid and will not be verified by the debugger.
When a breakpoint has been verified as valid, the icon displayed in the Code Editor margin and
in the Breakpoints window change to .
Note: For more information about other icons in the Code Editor, debugger windows, or Debug
menu, see About Debugger Icons.
Related topics

9-110
A source breakpoint is a breakpoint set in the source code and is the default type of breakpoint.
You can set a source breakpoint in any of the following ways:
● In the Code Editor, click in the left margin next to a line of executable code.
● In the Code Editor, click in a line of code then right-click and choose Toggle Breakpoint
(F5).
● Choose View | Debug Windows | Breakpoints to display the Breakpoints window.
Right-click anywhere in this window and choose New Breakpoint... from the context
menu. In the New Breakpoint window, select Source for the breakpoint type, then
complete the package, source file name, and line number information. The source
filename should not include any directory information, but must include the extension of
the file.
For example: Application1.java or MyWebApp.jsp
Setting breakpoints after starting a program
You'll probably want to set a least one breakpoint before you start debugging, but it is not
necessary. While your program is running in the debugger, you can set a breakpoint. The
program pauses when it reaches the breakpoint.
Related topics

Editing Breakpoints
9-111
About Deadlocks
A deadlock occurs when one or more threads in your program are blocked from gaining access
to a resource or waiting on a condition that cannot be satisfied. A common deadlock in Java is
a monitor block cycle deadlock.
A monitor block cycle deadlock occurs when two or more threads are unable to proceed
because each is waiting to enter synchronized code that one of the others has already entered.
Below is an example of a typical Java synchronization deadlock:
Thread 1 is executing the following code:
synchronized (a)
{
...
synchronized (b)
{
...
}
...
}
At the same time, thread 2 is executing the following code:
synchronized (b)
{
...
synchronized (a)
{
...
}
...
}
A deadlock will occur if thread 1 enters the synchronized (a) as thread 2 enters the
synchronized (b). Thread 1 will be blocked from entering synchronized (b) until thread
2 finishes the synchronized (b) and thread 2 will be blocked from entering synchronized
(a) until thread 1 finishes the synchronized (a). A deadlock is also called a "deadly
embrace." This example is for two threads but the same situation could occur for 3, 4, 5, and so
on threads.
9-112
Another kind of deadlock is where one thread calls the wait method on a particular object and
no other threads call the notify method on that object. The most common cause of this kind
of deadlock is timing. The notifying thread may have called notify before the waiting thread
called wait. The important thing to know about calling wait is that even if notify was
already called many times before, the wait method waits until notify is called again. Also,
notify doesn't return any kind of error if there was no thread waiting. The deadlock breakpoint
cannot detect this type of deadlock.
If you think your program is hanging, Pause your program in the debugger, and open the
Monitors window. Perhaps you can see that one thread is waiting, investigate the code. If you
can see that another thread probably called notify before the first thread called wait, there
is a deadlock. This kind of deadlock is very hard to detect. You must know your code well in
order to figure out which other thread should have called notify.
About the Deadlock Breakpoint
The JDeveloper debugger sets a persistent deadlock breakpoint when it starts running. It can
detect a deadlock as in the above scenario. The Monitors window can be useful when working
with deadlocks.
The deadlock breakpoint has the following characteristics:
● It is a persistent breakpoint that is created automatically when you use JDeveloper.

● It cannot be deleted, but it can be disabled.
● It pauses the debugger if a monitor block cycle deadlock is detected. A monitor block
cycle deadlock occurs when two or more threads are unable to proceed because each is
waiting to enter synchronized code that one of the others has already entered.
Related topics

9-113
Controlling Breakpoint Behavior
You can control how the debugger behaves when a breakpoint occurs in the following way:
1. In the Breakpoints window, right-click and choose either New Breakpoint or Edit
Breakpoint.
2. Click the Actions tab in the New/Edit Breakpoints dialog box. The Actions tab allows
you to change these behaviors:
❍ Halt execution (default)
❍ Beep
❍ Log breakpoint occurrence (enter a tag or an expression)
❍ Enable a group of breakpoints
❍ Disable a group of breakpoints
Click Help for additional information.
Related topics
About Grouped Breakpoints

9-114
When you disable a breakpoint, all the breakpoint settings remain defined, but the breakpoint is
not triggered when your program is run; your program will not stop on a disabled breakpoint.
Disabling a breakpoint is useful if you have defined a breakpoint that you don't need to use
now, but might need to use at a later time.
Disabling Breakpoints
Use any of the following methods to disable a breakpoint:
● In the Code Editor, right-click the line of code with the breakpoint and choose Disable
Breakpoint from the Code Editor context menu.
● To disable a breakpoint, open the Breakpoints window and select the breakpoint you
want to disable. You can now right-click, and choose Disable.
● To disable a group of breakpoints in the Breakpoints window, right-click a breakpoint
group and choose Disable Group in the context menu.
● To disable all current breakpoints, in the Breakpoints window, right-click and choose
Disable All.
● To enable a breakpoint that is disabled, right-click the disabled breakpoint in the
Breakpoints window, and choose Enable.
● To enable all breakpoints that have been set, right-click in the Breakpoints window, and
choose Enable All.
● To enable a group of breakpoints, right-click a breakpoint group in the Breakpoints
window, and choose Enable Group.
Deleting breakpoints
When you no longer need to examine the code at a breakpoint location, you can delete the
breakpoint. You can delete breakpoints using either the Code Editor or the Breakpoints
window:
Use any of the following methods to delete breakpoints:
● In the left margin of Code Editor, click the breakpoint you want to delete.
● In the Code Editor, right-click in the line of code, and choose Toggle Breakpoint from the
context menu or press F5 .
9-115
● From the Breakpoints window, highlight the breakpoint you want to remove, then choose
Remove from the context menu. Alternatively, you can press Delete on your keyboard.
● To delete all currently set breakpoints, select Remove All from the context menu.
Caution: You cannot undelete a breakpoint.
Related topics

9-116
Breakpoints are typically attached to a particular line of code; they pause the debugger when a
particular line of code is about to be executed. Also, you can set a breakpoint to be activated
when a certain type of exception is thrown. Exception breakpoints are not associated with a
particular line of code.
To set an exception breakpoint:
1. In the Breakpoints window, right-click and choose New Breakpoint...

2. The New Breakpoint dialog appears.
3. In the Definition tab, select the Exception Breakpoint from the dropdown list.
4. In the Exception Breakpoint Details area, enter the fully qualified name for the
exception.
5. By default, the debugger automatically creates a persistent exception breakpoint for
uncaught throws for java.lang.Throwable. This breakpoint will occur whenever an
uncaught exception is thrown. You cannot delete a persistent breakpoint. If desired,
select or clear the Break for caught or Break for uncaught exceptions check boxes
(both are selected by default).
6. Click OK.
The debugger will now pause if an exception of the specified type is thrown.
By default, JDeveloper always sets a persistent breakpoint to to pause the debugger when any
uncaught exception is thrown in your program.
Related topics

About Verified and Unverified Breakpoints
9-117
9-118
When you make a breakpoint conditional, the debugger pauses when a certain condition is
met. When a breakpoint is first set, the debugger pauses the program execution each time the
breakpoint is encountered. However, using the Edit Breakpoints dialog, you can customize
breakpoints so that they are activated only in certain conditions.
The Conditions tab in the Breakpoint dialog is where you enter an expression that is evaluated
each time the debugger encounters the breakpoint while executing the program. If the
expression evaluates to true, then the breakpoint pauses the program. If the condition
evaluates to false, then the debugger does not stop at that breakpoint location.
For example, suppose you want a breakpoint to pause on a line of code only when the variable
mediumCount is greater than 10.
To set a breakpoint condition:
1. Set a breakpoint on a line of code by clicking to the left of the line in the Code Editor.
2. Open the Breakpoints window by choosing View | Debug Windows | Breakpoints.
3. In the Breakpoints window, right-click the breakpoint you just set and choose Edit
Breakpoint....
4. In the Edit Breakpoints... dialog, click Conditions.
5. Enter an expression in the Condition field, for example:
mediumCount > 10
6. Click OK.
You can enter any valid Java language expression in the Edit Breakpoint Condition dialog, but
all symbols in the expression must be accessible from the breakpoint's location, and the
expression cannot contain any method calls. For an exception breakpoint, you may want to use
the exception object in your condition by using _throw.
Using Pass Count Breakpoints
The Pass Count field specifies the number of times that a breakpoint must be passed for the
breakpoint to be activated. Pass counts are useful when you think that a loop is failing on the
9-119
nth iteration. The debugger pauses the program the nth time that the breakpoint is
encountered during the program run. The default value is 1.
If the Pass Count column is shown in the Breakpoints window, you can see the pass count
value decrement each time the breakpoint line of code is encountered during the program
execution. If the pass count equals 1 when the breakpoint line is encountered, the breakpoint is
activated, and the program pauses at that line.
When pass counts are used together with breakpoint conditions, the breakpoint pauses the
program execution the nth time that the condition is true; the condition must be true for the
pass count to be decremented.
Related topics
9-120
Examining Breakpoints with the Breakpoints
Window
To see the list of breakpoints, choose View | Debug Windows - Breakpoints from the main
menu. Breakpoints that have been verified as valid by the debugger are indicated by . You
can use the Breakpoints window to quickly find the breakpoint location in your source code.
To use the Breakpoints window to locate a breakpoint in the Code Editor:
1. In the Breakpoints window, select a breakpoint.

2. Right-click and choose Go to Source for Breakpoint from the context menu.
Related topics

9-121
You can enable or disable several breakpoints with a single action, by creating a breakpoint
group and putting breakpoints into it. Once you've created a breakpoint group, you can enable,
disable, or remove them like any single breakpoint.
You can also drag and drop a breakpoint into or out of a group in the Breakpoints window.
To create a breakpoint group:
1. In the Breakpoints window, right-click a breakpoint and choose Edit Breakpoint... from
the context menu.
The Edit Breakpoint dialog appears.
2. In the Breakpoint Group Name field, enter a group name for this breakpoint.
3. Click OK.
A new group is created in the Breakpoints window, and is indicated by a folder icon. The
breakpoint you just edited is automatically put in the new group.
Moving a breakpoint into a breakpoint group:
Follow these steps or drag-and-drop the breakpoint into the breakpoint group.
1. In the Breakpoints window, right-click a breakpoint and choose Edit Breakpoint... from
the context menu.
The Edit Breakpoint dialog box appears.
2. From the Breakpoint Group Name field, select a breakpoint group from the dropdown
list.
3. Click OK.
The breakpoint is added into the specified group.
Enabling, disabling, or removing a breakpoint group:
● In the Breakpoints window, right-click a breakpoints group, and choose Enable Group,
Disable Group, or Remove Group from the context menu.
9-122
Related topics
About Breakpoints
9-123
Grouped breakpoints let you enable a set of breakpoints. When the debugger reaches a certain
point in your code, you can instruct the debugger to enable a breakpoint or a group of
breakpoints that was previously disabled.
For example, if you know that your application is encountering a NullPointerException

and although your code is catching the NullPointerException, it is not always behaving
correctly. First, you try setting an exception breakpoint, indicating that you want to stop the
debugger when a NullPointerException is thrown, regardless of whether the exception
will be caught or not caught. You start debugging and soon realize that
NullPointerExceptions occur more frequently than you had thought which causes the
debugger to stop repeatedly for NullPointerExceptions including those that are of no
concern to you. This situation can be resolved by creating a breakpoint group, adding this
breakpoint to the group, and disabling the breakpoint group so that the debugger does not stop
at this breakpoint when debugging.
Next, you can create a source breakpoint in some code that you know is executed just before
the problematic NullPointerException is thrown. You can set the actions for this source
breakpoint so that when the source breakpoint occurs, it will automatically enable the
breakpoint group which contains the exception breakpoint.
To make a breakpoint enable a breakpoint group:
1. In the Breakpoints window, choose New Breakpoint...

2. In the New Breakpoint dialog box, choose the Breakpoint Type from the list. For the
above example, you would choose Exception.
3. Specify the breakpoint details. For the above example, you would enter
java.lang.NullPointerException.
4. In the Breakpoint Group Name field, enter a name. For example, enter NPE.
5. Click OK.
6. In the Breakpoints window, you should see the newly created Breakpoint Group and your
NullPointerException breakpoint is in the group.
7. With the Breakpoint Group selected, right-click and choose Disable Group from the
context menu.
8. Next, set a source breakpoint at a line of code that you know will execute just prior to the
NullPointerException that you are trying to examine.
9. In the Breakpoints window, right-click the source breakpoint and choose Edit
9-124
Breakpoint...
10. In the Actions page, select the Enable a Group of Breakpoints check box and choose
NPE from the dropdown list.
11. Click OK.
Now when you debug, the debugger will not stop at NullPointerExceptions that are
thrown before your source breakpoint occurs, because the NullPointerException
breakpoint is disabled. When your source breakpoint occurs, the NullPointerException
breakpoint will become enabled and the debugger will pause your program the next time a
NullPointerException is thrown.
Related topics

9-125
Learn more about examing program state in the debugger windows:
● Controlling Which Classes are Traced Into

● Inspecting and Modifying Data Elements
● Setting Expression Watches
● Modifying Expressions in the Inspector Window
● Using Acceptable Legal Java Expressions in JDeveloper
● Show and Hide Fields in the Filtered Classes List
9-126
Normally, you should set the tracing include and exclude lists in the project settings before you
start debugging. However, if you need to change the tracing include and exclude lists, you can
do so from the Classes window. Right-click in the Classes window and choose Tracing from the
context menu. The Tracing dialog box appears in which you can adjust the tracing include and
exclude lists
When you specify a package to be included or excluded from tracing, all descending classes
within that package are included or excluded as well unless you've specified them individually.
To closely examine part of your program, you can enable tracing on only the files you want to
step through in the debugger. For example, you usually don't want to step through classes that
are in the J2SE library because you're not going to troubleshoot on them; you usually only want
to trace into your own classes.
Stepping Behavior as Guided by Tracing Lists
If you exclude a class or package, and you instruct the debugger to step into that class, the
debugger runs straight through that code without pausing. The debugger pauses at the next
line of code in a class which has not been excluded. The tracing include and exclude lists are
used for all step commands including Step Into, Step Over, Step Out, and so on. Using these
lists do not prevent you from setting a breakpoint in a class which has been excluded. If the
debugger stops at such a breakpoint, the step commands will be disabled.
To enable tracing for a class, you can adjust the tracing include or exclude list by adding or
removing a class or package:
menu.
The Project Settings panel appears.
2. Expand the Debugger node and click Tracing.
3. In the Tracing Class and Package Exclude List parameter, enter the name of the
packages or classes you want to include or exclude in the appropriate field, separated by
a semicolon (;) or click Edit.
The Tracing Class and Package Exclude List dialog appears.
4. Click Add or Remove.
❍ If you click Add, the Class and Package Browser dialog appears.
❍ If you click Remove, the class or package is removed from the appropriate tracing
9-127
List.
5. Navigate to the class or package you want to add and click OK.
The class or package is added to the appropriate tracing List.
By leaving the include lists blank, you are actually specifying that you would like to enable
tracing in all packages except for those specifically listed in the exclude list. For example:
include:
exclude:java;javax
Press F1 in the Classes window for more information.
Related topics

9-128
You can change the values of data items using the Data, Smart Data, Inspector, or Watches
windows during the course of your debugging sessions. You can modify program data values
during a debugging session as a way to test hypothetical bug fixes during a program run. If you
find that a modification fixes a program error, you can exit the debugging session, fix your
program code accordingly, and recompile the program to make the fix permanent.
When you modify the value of a variable through the debugger, the modification is effective for
that specific program run only; the changes you make through the Data or Watches windows
do not affect your program source code or the compiled program. To make your change
permanent, you must modify your program source code in the Code Editor, then recompile your
program.
The new value needs to be type-compatible with the variable you want to assign it to. A good
rule of thumb is that if the assignment would cause a compile-time or run-time error, it's not a
legal modification value.
To modify the value of a variable in the Data window:
1. Open the Data window while the debugger is stopped at a breakpoint.

2. Right-click an item in the Data window and choose Modify Value from the context menu.
3. The Modify Value dialog appears with the selected item's name and its current value.
4. Enter a new value for the item.
❍ If you are modifying a primitive value, you can enter a new value.
❍ If you are modifying a reference pointer (other than a String), you can enter the
memory address of an existing object or array.
❍ If you are modifying a String, you can enter either a new String value or the
memory address of an existing String.

6. Click OK to change the value for the item and to close the dialog.
The new value appears in the Data, Smart Data, Inspector, or Watches windows.
Related topics

9-129
9-130
A watch enables you to monitor the changing values of variables or expressions as your
program runs. After you enter a watch expression, the Watch window displays the current value
of the expression. As your program runs, the value of the watch changes as your program
updates the values of the variables in the watch expression.
A watch evaluates an expression according to the current context which is controlled by the
selection in the Stack window. If you move to a new context, the expression is re-evaluated for
the new context. If the execution point moves to a location where any of the variables in the
watch expression are undefined, the entire watch expression becomes undefined. If the
execution point returns to a location where the watch expression can be evaluated, the
Watches window again displays the value of the watch expression.
To open the Watches window:
● Choose View | Debug Windows | Watches from the main menu.
To add a watch from the Code Editor:
1. Select the expression you want to watch with your cursor.

2. Right-click and choose Watch... from the context menu to add the expression to the
Watches window. A dialog box appears with the expression.
3. Edit the expression, if necessary.
4. Click OK.
Or, add a watch in the following ways:
● Select a data item in the Data window. Then right-click, and choose Watch.
● Right-click in the Watches window and choose Add Watch...
● Use the mouse to drag a data item from the Data window and drop it on the Watches
window.
To edit a watch:
1. Select the expression in the Watches window, then right-click and choose Edit Watch.
The Edit Watch Expression dialog appears.
9-131
2. Enter a new expression or modify the existing one and click OK.
To delete a watch:
● Select the expression in the Watches window, press the Delete key or right-click and
choose Remove Watch from the context menu. You can also delete all the watches by
choosing Remove All Watches from the context menu.
Caution: You cannot restore a deleted watch.
Related topics

9-132
Modifying Expressions in the Inspector Window
To modify an expression in the Inspector window:
1. In the Inspector window, right-click and choose Edit Expression... from the context
menu.
The Edit Expression dialog appears.
2. Enter a new expression.
4. Click OK.
Related topics

9-133
Using Acceptable Legal Java Expressions in the
Debugger
Java expressions are used in the Watches window, Inspector windows, Breakpoint Conditions,
and Breakpoint Log Expressions. The following are examples of acceptable legal Java
expressions you can use in the debugger:
Simple variable name:

rect
Field access:
rect.width
Array element:
myArray[3]
Array length:
myArray.length
Comparison operation:
rect.height == 100
myArray.length > 7
Arithmetic operation:
rect.width * rect.height
x + y + z
Logical operation:
frame1.enabled && frame1.visible
textField1.hasFocus || textField2.hasFocus
Instance of operator:
<my_value> instanceof java.lang.String
Shift operator:
x << 2
y >> 1
Binary operator:
keyEvent.modifiers & java.awt.event.InputEvent.CTRL_MASK
Question-colon operation:
9-134
y>5 ? y*7 : y*4
Static field name:
java.awt.Color.pink
Fully-qualified class name:
java.awt.Color
Related Topics

9-135
Show and Hide Fields in the Filtered Classes List
While debugging, you can use filters to reduce the number of fields that are displayed when
you expand an object in a data-related debugger window. You can perform this task in the
Smart Data window, the Data window, the Inspector window, the Watches window, the Heap
window, and the left-hand side of the Monitors window. Displaying fewer fields narrows your
focus when debugging and may make it easier to locate and isolate potential problems in your
program.
To show or hide fields in the filtered classes list:
1. Right-click in a data-related debugger window and choose Edit Filters...

Choosing Edit Filter for <type of object> lets you you go directly to the Edit Filters dialog
box for this specific class from which you can specify filters to control which fields are
displayed and which fields are not displayed when you expand an object.
2. In the Edit Filters dialog, you can easily traverse the superclass hierarchy for any class,
defining or updating the filters for each superclass.
Click Add to add a class to the Filtered Classes list. The Class Browser dialog is
displayed, from which you can choose any class which is accessible in you project.
Click Remove to remove the selected class from the Filtered Classes list.
3. Click the arrows to shuttle filters from the Fields to Show list to the Fields to Hide list.
5. Click Help for more information about this dialog.
Related Topics

9-136
Remote Debugging
Learn more about remote debugging:
● About Remote Debugging

● Remote Debugging in OC4J
● Remote Debugging in Oracle9iAS 1.0.2.1.x or Apache JServ
● Guidelines for Remote Debugging Servlets on Other Servers
● Creating a Remote Debugging Project with the Wizard
● Starting a Java Process in Debug Mode
● Using a Project Configured for Remote Debugging
9-137
The main difference between remote debugging and local debugging is how you start the
debugging session. For local debugging, JDeveloper automatically launches the program you
want to debug (called a debuggee process) and then attaches the debugger to that program.
For remote debugging, you must manually launch the program you want to debug. Also, if you
are debugging a JSP or a servlet, you must manually start a browser to invoke your JSP or
servlet.
Once the debuggee is launched and the JDeveloper debugger is attached to it, remote
debugging is very similar to local debugging. Remember that you can use remote debugging
when the debuggee process is running on the same machine as JDeveloper or when the
debuggee process is running on a different machine.
Similar to local debugging, you must choose which protocol to use before you start your remote
debugging session. The remote debugging protocols are configured from the Project | Project
Settings - Debugger - Remote panel and include:
Attach to OJVM
OJVM is the default debugging protocol and is the fastest debugger available in
JDeveloper. OJVM is available on Windows platforms only.
Attach to JPDA
For more information about the Sun Java Platform Debugger Architecture (JPDA)
Connection and Invocation, see
http://java.sun.com/j2se/1.3/docs/guide/jpda/conninv.html.
Listen for JPDA
If you are using the Sun Microsystem's Java Platform Debugger Architecture (JPDA) and
you would like the debugger to listen so that a debuggee can attach to the debugger.
This protocol will be used to support remote debugging with the Oracle9i Database
Release 2 when it becomes available.
Instructions for remote debugging servlets, JSPs, and EJBs are available for the following
application servers:
● Remote Debugging on Oracle9iAS Containers for J2EE (OC4J)

● Remote Debugging on Oracle9iAS 1.0.2.x or Apache JServ
● Guidelines for Remote Debugging Servlets on Other Servers
9-138
Related topics

9-139
Remote Debugging in OC4J
This topic provides the information on how to set up the Oracle9iAS Container for J2EE (OC4J) as a
remote debuggee (listener) so you can perform remote debugging.
Note: If you want to perform remote debugging using the embedded OC4J server running in
JDeveloper, you can skip step 2 below as your environment is already set up for you.
However, you must perform all these steps in any of these scenarios:
● You are running a standalone OC4J instance which can be on the same or separate machine
as JDeveloper.
● You are remote debugging on a machine running Oracle9iAS Release 2.0 (out-of-the-box).
After completing steps 1 to 5 below you should be able to remote debug JSPs, servlets, and
Enterprise JavaBeans (EJBs) in OC4J with JDeveloper.
To set up OC4J for remote debugging JSPs, servlets, and EJBs:
1. Create a remote debugging project with the wizard.

2. Copy the required JDeveloper runtime JAR files to the OC4J home directory.
3. Edit the OC4J servlet file to bind all Web sites.
4. Start OC4J in debug mode from the command line.
5. After setting up the debuggee and instantiating the remote debuggee process, you can connect
the debugger to the debuggee. The Attach to OJVM or Attach to JPDA dialog box is displayed
which lets you establish a connection between the debugger (attacher) and a debuggee
(listener).
6. Once the debugger is connected to the debuggee, the debuggee is not automatically stopped or
paused. You must do this yourself. For example, with remote debugging, JDeveloper does not
automatically open a browser with your JSP or servlet. When you open a browser with your JSP
or servlet, the debugger will stop at breakpoints which are in your JSP or servlet code. If you are
debugging an EJB, you must run an EJB client so that the debugger will stop at breakpoints in
your EJB code.
Copy the JDeveloper runtime JAR files to the OC4J home directory
Note: Some of these files may already be installed in the appropriate location with your OC4J 2.0
installation, in which case you do not need to copy them over to the OC4J home.
9-140
1. In the <JDEV_HOME>/lib directory, copy xmlparserv2.jar to <OC4J_HOME>/lib.
2. In the <JDEV_HOME>/jdev/lib directory, copy ojc.jar and jdev-rt.jar to
<OC4J_HOME>/lib.
3. In the <JDEV_HOME>/jsp/lib directory, copy ojsp.jar and ojsputil.jar to
<OC4J_HOME>/lib.
Note: JARs placed in this directory are automatically added to the OC4J classpath.
See also: "OracleJSP Support for JavaServer Pages Developer's Guide and Reference" (Part
Number A90208-01) which is provided with the Oracle9iAS documentation library.
Edit the OC4J-specific file for configuring servlets that are bound to all
Web sites
1. In the <OC4J_HOME>\config directory, open the global-web-application.xml in a text

editor.
2. Edit the following section:
<orion-web-app
jsp-cache-directory="./persistence"
servlet-webdir="/servlet"
development="false"
>
change development="false" to development="true" to enable servlet debugging.
3. Add a servlet tag to set debug options for OJSP by adding the following lines to the global-
web-application.xml file with a text editor:
<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
<init-param>
<param-name>debug_mode</param-name>
</init-param>
<init-param>
<param-name>developer_mode</param-name>
9-141
</init-param>
<init-param>
<param-name>encode_to_java</param-name>
</init-param>
<init-param>
<param-name>emit_debuginfo</param-name>
</init-param>
<init-param>
<param-name>jspcompiler</param-name>
<param-value>oracle.jdevimpl.jsp.JspOjcCompiler</param-value>
</init-param>
</servlet>
Start OC4J in debug mode from a command line
1. Change to the <OC4J_HOME> directory.

2. Issue the appropriate command based on the environment for OC4J:
OC4J on Windows NT with OJVM:

java -ojvm -XXdebug,port5000,detached,quiet -jar oc4j.jar
The -XXdebug parameter options are the following:

detached
Starts the Java program immediately and allow a debugger to connect any time.
Without this option, the Java program stays halted until a debugger is connected.
port <#>
Debugger must connect at the specified port. Without this option, the default port is
4000.
quiet
Don't print connection messages. Without this option, connection messages are
sent to Standard Error.
OC4J with Classic VM on Windows NT and UNIX:

java -classic -Xdebug -Xnoagent -Djava.compiler=NONE -
Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5000 -jar
oc4j.jar
9-142
OC4J with HotSpot VM on Windows NT and UNIX:
java -server -Xdebug -
Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5000 -jar
oc4j.jar
Note: Open a browser with your JSP or servlet or run your EJB client so that the debugger will stop at
breakpoints in your code.
Related topics

9-143
Remote Debugging on Oracle9iAS 1.0.2.x or Apache JServ
This topic provides the information on how to set up the remote debuggee to perform remote debugging against an
Oracle9iAS 1.0.2.x or Apache with JServ instance. After completing these steps you should be able to remote debug JSPs,
servlets, and EJBs from the remote debuggee.
To set up Oracle9iAS or Apache JServ for remote debugging:
1. In your ApacheJServ installation directory, open the jserv.conf file which should be located in the following
location.
$ORACLE_HOME/Apache/Jserv/etc/
2. For JSPs, locate the section for ApJServAction and add the following line:
ApJServAction .jsp /servlets/oracle.jsp.JspServlet
3. In your ApacheJServ installation directory, open the jserv.properties file which should be located in the following
location:
$ORACLE_HOME/Apache/Jserv/etc/
4. Specify the Java executable as follows:
wrapper.bin=<ORACLE_HOME>\jdk1.3\bin\java
On Solaris or Linux, set the JVM as follows:
$JDK_HOME/bin/java
5. Refer to the appropriate JVM section to continue the remote debugging setup:
❍ Oracle Java Virtual Machine (OJVM)
❍ Classic JVM
❍ HotSpot JVM
6. Set up the classpath for Oracle9iAS or Apache JServ.
Oracle Java Virtual Machine (OJVM)
The OJVM is available on Window platforms only. Set the parameters passed to the JVM for debugging using the
wrapper.bin.parameters as follows:
wrapper.bin.parameters=-ojvm
where java -ojvm sets Java
Example
-XXdebug,detached,quiet,port5000
-XXdebug
Set to make available for debugging.
detached
Starts the Java program immediately and allow a debugger to connect any time. Without this option, the Java program
stays halted until a debugger is connected.
port<#>
9-144
Debugger must connect at the specified port. Without this option, the default port is 4000.
quiet
Don't print connection messages. Without this option, connection messages are sent to Standard Error.
JPDA (Sun Classic VM)
(For use on Windows NT, J2SE 1.3 or JDK 1.22 or JDK 1.2.2_007 Reference on Solaris Only.) Set the parameters passed
to the JVM for debugging using the wrapper.bin.parameters as follows:
wrapper.bin.parameters=-classic
wrapper.bin.parameters=-Xdebug
wrapper.bin.parameters=-Xnoagent
wrapper.bin.parameters=-Djava.compiler=NONE
wrapper.bin.parameters=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=4000
The -Xdebug parameter options are the following:
- Xdebug
Enables debugging.
Xnoagent
Disables the default sun.tools.debug debug agent.
Djava.compiler=NONE
disables the Just In Time (JIT) compiler.
Xrunjdwp
Loads the JPDA reference implementation of JDWP.
This library resides in the target virtual machine and uses JVMDI and JNI to interact with it. It uses a transport and the
JDWP protocol to communicate with a separate debugger application.
transport=dt_socket
This sub-option specifies sockets as the transport mechanism when communicating with the debugger.
server=y
This sub-option specifies that the debuggee will listen for a debugger to attach.
suspend=n
This sub-option specifies that the target VM is not to be suspended, but will allow a debugger to attach at any time.
address=4000
This sub-option specifies the socket port number which will be used when communicating with the debugger. You can
specify a different port number, but it must match the port which you will enter later in the debugger.
9-145
If you are using JDK 1.2.2 for Classic debugging the JPDA, the path needs to be included in wrapper.path as follows:
wrapper.path=<ORACLE_HOME>/jpda-1.0/bin/
This is not required for OJVM debugging or J2SE 1.3. If you are using JDK 1.2.2 on Solaris, you must use 1.2.2_007
reference version; the production version will not perform remote debugging.
HotSpot VM
Set the parameters passed to the JVM for debugging using the wrapper.bin.parameters:
On Windows NT
wrapper.bin.parameters=-hotspot
On Solaris or Linux
wrapper.bin.parameters=-server
where
- Xdebug
Enables debugging.
Xrunjdwp
This library resides in the target virtual machine and uses JVMDI and JNI to interact with it. It uses a transport and the
JDWP protocol to communicate with a separate debugger application.
transport=dt_socket
This sub-option specifies sockets as the transport mechanism when communicating with the debugger.
server=y
This sub-option specifies that the debuggee will listen for a debugger to attach.
suspend=n
This sub-option specifies that the target VM is not to be suspended, but will allow a debugger to attach at any
time.
address=4000
This sub-option specifies the socket port number which will be used when communicating with the debugger.
You can specify a different port number, but it must match the port which you will enter later in the debugger.
Setting Up the Classpath for Oracle9iAS 1.0.2.x or Apache JServ

9-146
1. In the jserv.properties file, add or verify that the following lines exists:
wrapper.classpath=d:\apache\JServ\ApacheJServ.jar
wrapper.classpath=<ORACLE_HOME>\lib\servlet.jar
# Needed for JSP
wrapper.classpath=<ORACLE_HOME>\lib\ojsp.jar
wrapper.classpath=<ORACLE_HOME>\lib\ojc.jar
wrapper.classpath=<ORACLE_HOME>\lib\xmlparserv2.jar
# optional, for JML tags, SQL tags, and database-access JavaBeans
wrapper.classpath=<ORACLE_HOME>\lib\ojsputil.jar
# Needed if JDBC connection being used in JSP or Servlet
wrapper.classpath=<ORACLE_HOME>\lib\classes12.zip
# Needed if SQLJ being used JSP or Servlet
wrapper.classpath=<ORACLE_HOME>\lib\translator.zip
wrapper.classpath=<ORACLE_HOME>\lib\runtime.zip
2. Download Java Servlet APIs if you are using JDK 1.2.2. For more information, see:
http://www.javasoft.com/products/servlet/download.html#specs
# Needed for servlets.
# Note: jsdk.jar must preceed servlet.jar
# jsdk provides servlet 2.0 APIs required by Apache/JServ
# servlet. jar provides servlet 2.2 APIs
wrapper.classpath=<jsdk home>\jsdk2.0\lib\jsdk.jar
3. Edit the Apache JServ configuration file, zone.properties, which is located in:
$ORACLE_HOME/Apache/Jserv/servlets/
4. If the servlet is in a JAR, add it to repositories as follows:
repositories=<Apache_Home>\JServ\servlets
repositories=<Apache_Home>\JServ\servlets\shopcart.jar
5. If you have classes, copy them to the following location:
<APACHE_Home>\JServ\servlets
6. Locate the Servlet Init parameters section (near the bottom of the file) and add these lines:
servlet.oracle.jsp.JspServlet.initArgs=emit_debuginfo=true
servlet.oracle.jsp.JspServlet.initArgs=jspcompiler=oracle.jdeveloper.jsp.JspOjcCompiler
servlet.oracle.jsp.JspServlet.initArgs=classpath=<JDeveloper
Home>\jdk1.3\jre\lib\rt.jar
Next, you can create a Remote Debugging Project with the wizard.
Related topics
9-147
Guidelines for Remote Debugging Servlets on Other
Servers
If you are using a servlet container other than Oracle9iAS Containers for J2EE (OC4J), you'll
need to manage the server's configuration by yourself. Refer to the appropriate JVM section
below for guidelines to help you remote debug servlets on other servers.
Oracle JVM (OJVM)
1. Add a debug command line argument similar to the following:
-XXdebug,detached,quiet,port4000
detached
Starts the Java program immediately and allow a debugger to connect any time.
port <#>
Debugger must connect at the specified port. Without this option, the default port
is 4000.
quiet
Don't print connection messages. Without this option, connection messages are
sent to Standard Error.
JPDA (Sun Classic VM)
1. Add appropriate command line arguments, including the JPDA options for Classic and
HotSpot virtual machines:
where
- Xdebug
Enables debugging.
Xnoagent
Disables the default sun.tools.debug debug agent.
9-148
Djava.compiler=NONE
Disables the Just In Time (JIT) compiler.
Xrunjdwp
This library resides in the target virtual machine and uses JVMDI and JNI to
interact with it. It uses a transport and the JDWP protocol to communicate with a
separate debugger application.
transport=dt_socket
This sub-option specifies sockets as the transport mechanism when
communicating with the debugger.
server=y
This sub-option specifies that the debuggee will listen for a debugger to
attach.
suspend=n
This sub-option specifies that the target VM is not to be suspended, but will
allow a debugger to attach at any time.
address=4000
This sub-option specifies the socket port number which will be used when
communicating with the debugger. You can specify a different port number,
but it must match the port which you will enter later in the debugger.
You can use any other parameters your JVM requires. For additional options as
described by Sun, see Connection and Invocation Details.
Next, you can create a Remote Debugging Project with the wizard.
Related topics

9-149
Remote Debugging in Oracle9iAS or Apache JServ
9-150
Creating a Remote Debugging Project with the
Wizard
JDeveloper provides the Remote Debugging and Profiling Wizard which guides you in the
creation of a remote debugging project. You are prompted for the following information:
● Project directory
● Java source directories
● Sun J2SE Version and Libraries
● Debugging protocol
To create a Remote Debugging Project with the wizard:

2. In the Projects category, select the Project Configured for Remote Debugging and
Profiling item.
3. Click OK to launch it.
4. Read the Welcome page for a brief description about the purpose of this wizard.
5. Click Next.
6. You are prompted to enter the project directory name and project file name. The fields
are already populated according to the current workspace and project information. You
can change or browse to another location to create your remote debugging project as
desired. The project settings are updated accordingly for you.
7. Click Next.
8. Enter the location for the Java source root directory that the debugger will use to locate
your source files. For example, you can enter the following:
D:\<ORACLE_HOME>\jdev\mywork\Workspace1\Project1\src
Note: You do not need to add any source files to the project, but you will need access to
the source files for the code you will be debugging. You may need to copy your source
files to the machine where you are running JDeveloper.
9. Click Next.
10. Select the following as required: J2SE version and any libraries that contain source code
that you want to be able to see in the debugger.
Note: Oracle9i JDeveloper is not supported on JDK 1.1.x.
9-151
11. Click Next.
12. Select the remote debugging protocol used to attach to the debuggee. If you will be using
the Oracle Java Virtual Machine when you start the remote debuggee process, choose
OJVM. If you are using another Java virtual machine like HotSpot or Classic, choose
JPDA.
13. Click Next.
14. Click Finish.
Note: At any time, you can click Help for additional information.
Related topics

9-152
Starting a Java Process in Debug Mode
After you've created a Remote Debugging Project with the wizard, you can start your remote
debugging session by issuing the appropriate command based on the debugging protocol and
the environment:
Attach to OJVM Protocol
Enter the appropriate command based on the debugging protocol you chose when configuring
your remote debugging project:
On Windows NT to OJVM:
java -ojvm -XXdebug,port5000 <java_main_class>
detached
Starts the Java program immediately and allows a debugger to connect any time.
port <#>
Debugger must connect at the specified port. Without this option, the default port is 4000.
quiet
Does not print connection messages. Without this option, connection messages are sent
to Standard Error.
Attach to JPDA Protocol
With Classic VM on Windows NT and UNIX:

Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5000
<java_main_class>
With HotSpot VM on Windows NT and UNIX:

java -hotspot -Xdebug -
Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5000
9-153
<java_main_class>
For more information about the Sun JPDA Connection and Invocation, see
Related topics
Remote Debugging on Oracle9iAS Containers for J2EE (OC4J)
Remote Debugging on Oracle9iAS 1.0.2.x or Apache JServ
Guidelines for Remote Debugging Servlets on Other Servers

Creating a Remote Debugging Project with the Wizard
9-154
Using a Project Configured for Remote Debugging
Any project can be configured to perform remote debugging. Once you've created a remote
debugging project, you may choose to modify the project properties in the following way:
1. In the Navigator, select the project.

2. Choose Project | Project Settings....
3. Modify settings as necessary. Click Help for more information.
4. Click OK.
To start remote debugging:

The appropriate Attach to dialog appears.
2. In the Host list box, enter or select the name or IP address of the machine where the
remote debuggee has been started.
3. In the Port list box, enter or select the port number for the remote debuggee.
4. Click OK.
In the Log window, once the debugger has connected, a successful connection message
appears.
5. If you are remote debugging a JSP or servlet, you will want to access your JSP or servlet
by launching your browser.
6. Continue with your debugging session as usual.
7. To detach the debugger from the remote debugging process without terminating the
debuggee process, choose the Debug | Detach menu option. This option is appropriate
for remote debugging an application server.
8. To terminate the remote debugging process, choose the Run | Terminate menu
option.
Related Topics

9-155
JDeveloper has integrated the Oracle9iAS Containers for J2EE (OC4J) into the product which
lets you run, debug, profile, and CodeCoach your server-side Java applications locally. This
means you don't need a remote OC4J connection to perform these tasks and are not
concerned with dependency checking. Using the embedded OC4J server in JDeveloper,
developers can deploy their J2EE applications for development or testing purposes.
Optionally, developers can deploy to a standalone OC4J instance that is not embedded or
within an Oracle9i Application Server (Oracle9iAS). JDeveloper uses the Oracle9iAS
Containers for J2EE administration console command-line tool, admin.jar, to deploy to the
embedded OC4J or standalone OC4J.
Note: If you want to deploy to an Oracle9i Application Server using the Oracle Enterprise
Manager, see About Deploying on Oracle9i Application Server for information.
This section contains the following topics:
● Configuring Your Project to Use the Embedded OC4J Server

● Setting Preferences for the Embedded OC4J Server
● Starting the Embedded OC4J Process
● Terminating the Embedded OC4J Process
● About the Embedded OC4J Configuration Files in JDeveloper
9-156
Configuring Your Project to Use the Embedded
OC4J Server
When you are using the embedded OC4J server to run, debug, profile, and CodeCoach your
J2EE applications or modules, you need to configure the various J2EE settings to properly set
all web site bindings (controlled in the web.xml file) in your project. Specifically, you need to
define the default J2EE application name, Web application name, and Web context root.
To configure the J2EE settings to use the embedded OC4J server:
1. Right-click a project in the Navigator and choose Project Settings... from the context
menu.
2. Below the Common node, click the J2EE node to display its configuration panel.
3. Enter the appropriate information as required for the J2EE Application Name, J2EE Web
Application Name, J2EE Web Context Root.
5. Click OK.
All Web applications deployed to the connection will be bound to the specified web site. You
define the OC4J connection and the target web site with the Connection Wizard in JDeveloper.
When creating and deploying a web module deployment profile, you can use these project
default names or specify another J2EE application name or J2EE web context root.
Related topics
Starting the Embedded OC4J Process

About the Embedded OC4J Configuration Files
9-157
Setting Preferences for the Embedded OC4J Server
The embedded Oracle9iAS Containers for J2EE (OC4J) lets you run, debug, profile, and
CodeCoach your server-side Java applications locally which means you don't need a remote
OC4J connection to perform these tasks and are not concerned with dependency checking.
OC4J is automatically installed as part of JDeveloper in the following location:
<ORACLE_HOME>\j2ee\home
If you want to override the JDeveloper OC4J installation and specify another location:
1. Choose Tools | Preferences ....

2. Click the Deployment node to display its configuration panel.
3. In the OC4J Installation to Use for Running and Debugging text field, you can edit the
directory location of the default embedded OC4J to another directory location where
OC4J is installed.
Note: If no directory is specified, JDeveloper would try the default location for the
embedded OC4J Server.
4. Configure the port information as appropriate. You can assign ports for HTTP, RMI, and
JMS.
5. Click Help for more information about this panel.
Related topics

9-158
The embedded OC4J server is automatically started when you select to run, debug, profile, or
CodeCoach an EJB, servlet, or JSP. You can perform any of these tasks by selecting an object
(for example, a JSP or a Java servlet) in the System Navigator, and choosing the appropriate
option in the Run or Debug menus.
Once the server has started, you will see a node in the Run Manager for the embedded OC4J
server.
Only a single instance of the embedded OC4J server can be run at any given time. Thus, if you
attempt to start another instance of the server, JDeveloper will shut down the previous instance
and restart the embedded OC4J server in order to run, debug, profile, or CodeCoach the node
in the Navigator that you have currently selected.
Related topics

9-159
JDeveloper provides an embedded Oracle9iAS Container for J2EE (OC4J) Server which is
automatically started for you when you run, debug, profile, or CodeCoach on an EJB, servlet, or
JSP. This feature saves you from having to make a connection to an OC4J instance as the
embedded OC4J server is run directly on your local machine.
Once the embedded OC4J server has started, a node in the Run Manager named Embedded
OC4J Server appears. You can access the Run Manager by choosing View | Run Manager
from the main menu.
To shutdown the running embedded OC4J Server:
● Choose Run | Terminate - Embedded OC4J Server from the main menu.
● Right-click Embedded OC4J Server in the Run Manager and choose Terminate from the
context menu.
● Choose File | Exit to exit JDeveloper. You are prompted to terminate the embedded
OC4J server process.
JDeveloper will attempt to gracefully shut down OC4J.
If OC4J is not responding to the initial shutdown
Make sure to allow OC4J adequate time to shut down and check the Log window for status
information about the shutdown. Reasons that OC4J does not shut down after the initial
request may include:
● Server configuration was changed while server was still running

● Administrative shutdown command was sent to a port that was not the RMI port of the
server, so the server never received the shutdown request.
● The RMI port of the server is unavailable, which may happen if the server was launched
when there was a port conflict trying to bind the RMI port, so the server never received
the shutdown request.
● A Web browser using "keep alive" tokens is maintaining a connection to OC4J. If this is
the case, close the browser window that is using those "keep alive" tokens.
● A client to an EJB is still connected or the connection is hung.
● A database connection used by an EJB, servlet, JSP, or XSQL page is still open and for
some reason cannot be closed.
9-160
In these situations, you may need to shut down the OC4J server forcefully by doing the
following:
● Choose Run | Terminate - Embedded OC4J Server again from the main menu. When the
embedded server is next started up, you will see a message in the log window indicating
that OC4J is attempting to recover from abrupt termination or a crash. This is the normal
OC4J startup process after it has been forcefully terminated.
Related topics
Terminating a Debugging Session

9-161
About the Embedded OC4J Configuration Files in
JDeveloper
The embedded Oracle9iAS Containers for J2EE (OC4J) lets you run, debug, profile, and
CodeCoach your Java applications locally which means you don't need a remote OC4J
connection to perform these tasks. The embedded OC4J is automatically installed as part of
JDeveloper in the following location:
<ORACLE_HOME>\jdev\system\oc4j-config
Important: Do not manually edit any of the files in this directory as this may affect the running,
debugging, profiling, and CodeCoaching of your J2EE application files. JDeveloper updates
these files as appropriate based on your J2EE application development.
Related topics

9-162
Writing More Efficient Java Programs Using
CodeCoach
The CodeCoach tool was developed to help you with the more routine aspects of developing
higher quality, better performing code. By assisting you with these tasks, whether you are new
to Java or an experienced programmer, CodeCoach can help you to develop efficient Java
programs more quickly and easily.
Working with CodeCoach is an iterative process, driven by where you are in the development
process, which tasks you wish to attend to, and the sort of advice returned by CodeCoach in
any given run.
Typically, to work with CodeCoach:
1. Decide which classes to CodeCoach and which to exclude.

2. Decide which type of CodeCoach tests to run on your program.
3. Direct CodeCoach to the program you wish to evaluate and start the tool, either from
within the IDE or from the command line.
4. Review the advice returned. If you are running CodeCoach from the IDE, this advice
appears in the Log window under a CodeCoach tab. If you are working from the
command line, this advice is returned as standard output, which you can redirect should
you choose.
5. Fine-tune CodeCoach advice at the project level, either from the command line or
through the IDE.
Note that once you have become accustomed to CodeCoach, you may well make these
decisions before running it on a program.
6. Optionally, fine-tune CodeCoach advice at the file, class, or method level by inserting
pragmas directly into source code.
As with project-level adjustments, once you have become accustomed to CodeCoach,

you may well make these decisions before running it.
7. Rerun CodeCoach on your program.

8. If you are running CodeCoach from the IDE, for specific messages in the advice list, use
the context menu in the Log window to apply simple fixes directly to your code, hide
9-163
messages of a certain type, and so on. This functionality is available only in the IDE.
Related topics
About CodeCoach
About Customizing CodeCoach Advice
About Pragmas

Configuring Your Project for Deployment
9-164
CodeCoach Concepts
You may find the following conceptual topics useful while working in CodeCoach:
● About CodeCoach
● About Customizing CodeCoach Advice
● About Pragmas
● About CodeCoach Memory Improvement Advice
Related topics
Writing More Efficient Java Programs Using CodeCoach

Preparing Your Project to Be CodeCoached
Ways to Start CodeCoach
9-165
About CodeCoach
CodeCoach helps you create more efficient Java programs by helping you write higher quality,
better performing code. When you use CodeCoach, JDeveloper looks for changes you can
make to increase the robustness of the code and optimize its use of system resources.
Running CodeCoach
You must use CodeCoach in the JDeveloper environment, with the Oracle Java VM. You can
run any files through CodeCoach that can be run in Java, under two conditions: the files must
be executed locally, and they must have been compiled with the Oracle Java Compiler (ojc)
including debug information.
If you have a JSP web application project, for instance, you can run CodeCoach on this project,
but you will receive CodeCoach advice only on those Java source code files that are both
included in the project and used by JSPs (in other words, custom beans).
When a class is run through CodeCoach, but debug information has not been included in the class,
CodeCoach will issue the following warning:
Class classname must be compiled with debug info to

enable CodeCoach
To get rid of this message, you must exclude the class from CodeCoach or compile with debug
information enabled, which you can do either by choosing that option in the Project Settings
dialog (from the Compiler node, select Include debug information) or by using the -g switch of
ojc on the command line. You should exclude all third-party classes.
Advice Types
CodeCoach offers advice for a number of different areas: classes, methods, fields, local
variables, memory usage, and miscellaneous. Within each of these areas, it organizes the
changes it suggests into finer-grained categories, called "advice types," which you can enable
or disable as you wish. You can also define the depth to which CodeCoach evaluates your
code, and determine which classes or packages you wish to include or exclude. You can select
advice types, CodeCoach depth, and packages or classes to be evaluated either directly from
the IDE or from the command line. In addition, you can further fine-tune the way CodeCoach
tests your code by inserting pragmas directly in the source itself.
9-166
Ensuring Accurate Advice
To ensure that CodeCoach receives the most accurate data possible (so that it can, in turn,
offer advice that is as accurate as possible), it is crucial during a CodeCoach run session that
you fully exercise your code: be sure to use all the menus and buttons in the UI and to include
corner cases. If you do not run all the features of your application to ensure the fullest code
coverage, the advice CodeCoach returns may compromise the performance of the application.
Why is full code coverage so essential? The CodeCoach system in the VM is able to consider
only those classes that have actually been loaded. And since Java is a late-loading language,
classes are loaded only if they are actually used, not when they are referenced. If a class is
simply referenced, and never used, CodeCoach has no way of knowing that it exists. If the
advice returned is to be valid, your program must load all the classes it is designed to use.
For example, consider the following code:
class Greeting {
String title;
String name;
public Greeting() {
}
public Greeting(String title, String name) {

this.title = title;
this.name = name;
}
public String toString() {

return "Hello " + title + " " + name;
}
}
class DearGreeting extends Greeting {
public DearGreeting(String name) {

this.title = "Dear";
this.name = name;
}
public class Class1 extends Object {
static Object getGreeting(String name, boolean isfemale) {
9-167
if (name.equals("Joe")) {
return new DearGreeting(name);
}
if (isfemale) {
return new Greeting("Mrs", name);
}
else {
return new Greeting("Mr", name);
}
}
public Class1() {
}
public static void main(String[] args) {

System.out.println(getGreeting("Kiks", false));
}
}
If you were to CodeCoach this simple program, CodeCoach would provide the following advice:
(CFIN) Class Greeting should be final

(CFIN) Class Class1 should be final
(FPRI) Field java.lang.String name should be private
(FPRI) Field java.lang.String title should be private
Were you to follow this advice, you would break the compilation. Greeting ought not to be
made final, as DearGreeting extends it. And neither the name nor the title of
java.lang.String should be made private, as DearGreeting needs access to this field.
Why, then, does CodeCoach return such seemingly bad advice? Because the method
getGreeting is called only once, with "Kiks" for its argument, while instances of
DearGreeting are returned only if the name is "Joe". The line return new
DearGreeting(name); is thus never executed in this run, and since Java waits until a class
is actually used to load it, the class DearGreeting is not loaded in this run. If the class
DearGreeting didn't exist (and, as far as CodeCoach knows, it doesn't), the advice returned
would be correct.
If, on the other hand, the method getGreeting were to be called anywhere with "Joe" as an
argument or if any other part of the program were to use an instance of the DearGreeting
class, the CodeCoach system would produce the following advice:
9-168
(CFIN) Class DearGreeting should be final
(CFIN) Class Class1 should be final
This is a very simple example, of course, and in real-world programs the relationships are likely
to be much more complicated. All the more reason to keep in mind this dependency on loaded
classes. In the ideal world, your program loads all the classes in the CodeCoach run that it is
designed to use. The closer you approach this ideal, the more accurate will be the advice.
As the ideal is not always possible, be aware that following CodeCoach advice without first
evaluating it can break the compilation of your program. If this happens, just undo the "fix" and
use a pragma to ignore the misleading advice.
Using the Advice Returned
The more complete the code is, the more accurate CodeCoach's advice will be. On the other
hand, if you wait until the program is complete, or nearly so, before ever running CodeCoach,
you can be overwhelmed by the number of messages it returns.
The best method is to use CodeCoach all along, as you develop your program, so that you can
take its suggestions into account while you work and so that you can determine which advice
types, for your purposes, you'll want enabled and disabled. The earlier in the process you use
CodeCoach, however, the more you'll want to keep in mind your own overall design, which
CodeCoach has no access to. If CodeCoach suggested, for example, that you declare a
method static, but you know that you will eventually be overloading that method in a subclass,
you would disregard this particular advice. You could even disable it, if you wished, using
pragmas or the context menu in the Log window. CodeCoach can only take into account what it
sees, so you must provide the necessary correctives.
Used wisely, CodeCoach can be a useful assistant, and a time saver. But before following any
of its advice, you will want to consider the larger picture so as to avoid unintentional
consequences.
Related topics

Customizing CodeCoach Advice for a Project from the IDE
9-169
Customizing CodeCoach Advice for Files, Classes, or Methods
Using CodeCoach from the Command Line
CodeCoach Keywords
About Pragmas
9-170
You can control the type of advice that CodeCoach provides, and to what depth:
● At the project level, either from the command line or through the IDE
● At the level of files, classes, or methods by using pragmas
You can fine-tune this advice repeatedly, between subsequent CodeCoach runs, and it is often
a good idea to do so.
During a CodeCoach run session, be sure to exercise your code in a way that is typical of its
intended use. If you do not run all the features of your application to ensure full code coverage, the
advice returned may compromise the performance of the application.
Adjusting Advice at the Project Level
Specifically, at the project level, you have three options available to you:
● To enable or disable advice types

● To set the level of advice you'll receive
● To include or exclude specific files or packages
You can set all three of these attributes whether you are using CodeCoach in the IDE or
running it from the command line. Note that you should exclude all third-party classes and run
CodeCoach with debug information enabled.
Adjusting Advice at File, Class, or Method Level
You can also enable or disable advice types individually at the file, class, or method level by
inserting pragmas directly into the source code. The other two options—setting the level of
advice you'll receive and including or excluding packages—are, by definition, project-wide
attributes and so cannot be set at a finer level of granularity.
Adjusting Advice from the Log Window
If you run CodeCoach from within the IDE, you can elect to do the following with individual
advice lines returned:
9-171
● Find the source of the problem in the code.
● Apply the suggested fixes directly to the source (only available for certain messages).
● Disable this message for future runs by inserting a pragma for the item.
● Temporarily hide messages of a given type.
● Restore all previously hidden messages.
You access these choices from the context menu of the log window, where all CodeCoach
warnings and advice appear. Filtering the advice after the run session saves you time by
eliminating the need for you to change project properties settings and rerun code.
Related topics

CodeCoach Keywords
About CodeCoach
About Pragmas
9-172
About Pragmas
You can customize the advice that CodeCoach provides for individual files, classes, or methods
by inserting pragmas directly in your source code. The settings you place directly into source
code override any you might have set in the IDE.
Pragmas are specially formatted comments that only the Oracle Java Compiler understands.
When your code is running normally, or in another VM, the pragmas are ignored. However,
when you run the code through CodeCoach's VM, these pragmas give you greater control, with
greater precision, over the advice that CodeCoach returns for specific sections of your code.
Pragmas can be used anywhere within your source files. You can turn specific advice types or
sets of advice types off and on for entire classes, for specific methods, or for individual lines of
code within a source file. Pragmas are active either until they are reset by another pragma or
until the end of the file.
Pragmas provide you with direct control over individual files, classes, and methods. To fine-
tune CodeCoach across a project, you can work either from the Project Settings dialog or from
the command line.
Related topics

CodeCoach Keywords
About CodeCoach
9-173
About CodeCoach Memory Improvement Advice
CodeCoach delivers memory advice for all the utility classes that provide constructors which
allow you to specify the initial size of the object. Two features of such utility classes are
important for memory allocation:
● Constructors, which determine the initial size and, sometimes, the expansion policy
● An internal mechanism that allows objects to expand automatically if they run out of
capacity
These features are both very useful, but if the initial size is not properly set, your code can end
up with wasted memory. CodeCoach advises you on the two most common problems related to
memory usage: oversizing and undersizing.
Oversizing
If only a small percentage of the space reserved for memory is used, the remaining space is
uselessly allocated. For example, if you use the default constructor for a HashTable, you obtain
one with 101 entries, while if by design you store only five items in this HashTable, a significant
amount of space is wasted. Creating this HashTable with an initial size of 10 would be a wiser
move, offering ample performance for the design, yet significantly reducing memory footprint
and ensuring that what is set aside is used.
Undersizing
If the original size of the object is too small, on the other hand, it will be automatically expanded
as needed. For all these classes, expansion is an expensive operation, both in terms of
memory and execution time. Consider this situation. If you use the default constructor for a
Vector, you obtain a default size of 10. What happens if you then add a hundred objects to this
Vector? The system performs the following series of expansions:
Add element 11 => Vector is expanded size doubled 10 –> 20

Each expansion involves allocating a new array and copying the old array into the newly
allocated one. Both operations are expensive.
9-174
Additionally, the four required expansions leave four garbage arrays (sizes 10, 20, 40, 80),
which will need to be collected. And, after all that, the final size attained by such stepwise
expansion is not always well suited for the content. In this example, you are using 160% of the
optimum size, which means that you have gone from an undersized allocation to an oversized
one.
How Does CodeCoach Help?
Every memory advice provides the following statistics about the objects allocated at the
position in question:
● Size (the size allocated to store information)

● Content (the actual number of objects used)
● Expansions (the number of expensive resizing operations performed)
● Number (the number of instances allocated)
For size, content, and expansions, CodeCoach gives you the minimum, average, and
maximum values. These values are generally very easy to interpret.
For example, in the HashTable example above you would find something like the following:
Size 101/101/101
Content 5/5/5
Exp 0/0.00/0
While, in the Vector example you would have something like this:
Size 160/160/160
Content 100/100/100
Exp 4/4.00/4
These two examples are fairly straightforward. There will be other situations for which the
values given may be trickier to interpret. Let's say, for example, that you allocate 1000 Vectors
and that you fill 999 of them with a hundred values, but that you don't use the last one at all.
The statistics returned would be something like this:
Size 10/159/160
Content 0/99/100
Exp 0/3.99/4
9-175
If you decided to go with the average content (99), in this case the results would not be good.
You would end up with 999 Vectors expanded once (to add the one hundredth element), for an
overall size of 198, and you would lose 99 positions on the empty one.
When you obtain nontrivial stats from CodeCoach, the best way to begin assessing the
situation is to return to first principles: what the application is actually doing with the objects.
You might, for example, find a way to "predict" a good initial size according to some heuristics
of your program and then use this calculated size when you create the object.
Some basic guidelines are:
● If the content is min/avg/max, the initial size must be at least the minimum, but not
exceed the maximum. If the average size is close to that of the maximum, then the
maximum is a good choice.
● If the average expansion is 1 or more, you should use a bigger size.
These basic guidelines hold for Vectors, StringBuffer, and so on. For HashTables you might
want to increase the number to limit the number of hash collisions.
With the memory improvement advice it returns, CodeCoach allows you to weed out and
handle the easy cases first, while highlighting the more complicated ones which will require
your closer attention. For these complicated cases, nothing replaces the knowledge of the
developer in selecting the best value for the situation.
Related topics
CodeCoach Memory Improvement Advice
About CodeCoach
9-176
Before you run your project through CodeCoach, you must make sure that debug information
has been included for all classes you wish to be CodeCoached. If you do not want to
CodeCoach a class, be sure to put it on the exclude list.
You should plan to CodeCoach only those classes for which you have source code that you
intend to change, in other words, your own source files. Place all other classes on the exclude
list.
When CodeCode encounters a class on the include list that does not have debug information
included, it issues this warning:

enable CodeCoach
To get rid of this message, make sure that the class in question is either on the exclude list or
that it is compiled with debug information included.
To exclude a class from CodeCoach when working from within the IDE:
1. From the main menu, choose Project | Project Settings .

2. Select the CodeCoach node and enter the class to be excluded.
3. Click OK.
To exclude a class from CodeCoach when working from the command line:
● Insert the following parameter when running the project with java.exe or javaw.exe:
-Xcc:excl:[class or package list]
To include debug information for a class when compiling from within the IDE:
1. From the main menu, choose Project | Settings.

2. Select the Compiler node and check the box labeled Include Debug Information.
3. Click OK.
9-177
To include debug information for a class when compiling from the command line:
● Insert the -g switch when compiling the application with ojc.
Related topics

About CodeCoach
9-178
Starting CodeCoach is very much like starting a debugging session. Before you begin, you
must decide which classes to CodeCoach and which to exclude. All classes included in a
CodeCoach run must be run with debug information included.
You can start CodeCoach either:
● In the IDE, by selecting the appropriate node in the Navigator and choosing Run |
CodeCoach <appname>.
or
● From the command line
When you start CodeCoach from within the IDE, your program will run as normal. When you
exit the program, the log window will display a list of changes for you to consider, each of which
is categorized by advice type. To view the section of your code that CodeCoach recommends
you review, double-click the advice line. For more information on the advice itself, click the line
to highlight it and press the F1 key.
Note that the advice CodeCoach returns will only make sense if the code coverage of the
program run is as complete as possible: be sure to use all menus and buttons in the UI and to
include corner cases.
Related topics

About CodeCoach
9-179
Customizing CodeCoach Advice for a Project from
the IDE
You can fine-tune the advice that CodeCoach provides either before or after you run
CodeCoach.
Before a CodeCoach Run
Before running CodeCoach, you can fine-tune advice at the project level by choosing to:
● Enable or disable advice types

● Set the level of advice you'll receive
● Include or exclude specific files or packages
You can also enable or disable advice types individually at the file, class, or method level by
inserting pragmas directly into the source code.
In subsequent runs, you can continue to fine-tune this information, both for the entire project
and at the level of files, classes, or methods.
After a CodeCoach Run
After a CodeCoach run, you can elect to apply simple fixes or to filter advice by accessing the
context menu for the individual advice lines in the log window.
Related topics

About CodeCoach
About Pragmas
9-180
Enabling and Disabling Advice Types in CodeCoach
Enabling and disabling advice types is one of the ways which you can customize CodeCoach to
do the work you want it to before you run it on a project.
To enable or disable advice types for an entire project from the IDE:
1. Select the appropriate project (the one that you want to customize CodeCoach options
for) node in the Navigator.
2. From the Project menu, choose Project Settings.
3. In the Project Settings dialog that appears, select the CodeCoach node.
4. Select which advice types to generate by clicking the checkboxes for individual types or
groups of types in the CodeCoach advice list tree.
For more information on individual selections, click Help.
5. Click OK.
You can also enable or disable advice types for a project directly from the command line. To
disable advice types individually for files, classes, or methods, you can insert pragmas directly
into the source code.
Related topics

Setting the Advice Level for CodeCoach
Including and Excluding Packages and Classes in CodeCoach
About CodeCoach
About Pragmas
9-181
Setting the advice level is one of the ways which you can customize CodeCoach to do the work
you want it to before you run it on a project.
To set the advice level for an entire project from the IDE:
4. Use the sliding bar to set the advice level that you wish.
Setting the advice level to 10 gives you one hundred percent of all the advice for a given
category. Setting it to 1 returns you advice for only the most significant problems. For
more information on advice levels, click Help.
5. Click OK.
You can also set the advice level for a project directly from the command line. Setting the
advice level is, by definition, a project-wide attribute and so it cannot be set at the file, class, or
method level.
Related topics

Including and Excluding Packages and Classes in CodeCoach
About CodeCoach
9-182
Including and Excluding Packages and Classes in
CodeCoach
Including and excluding packages and classes is one of the ways which you can customize
CodeCoach to do the work you want it to before you run it on a project. When packages are
excluded, CodeCoach does not return advice on the code within them.
To include or exclude packages and classes for an entire project from the IDE:
4. Enter any packages or classes to include or exclude in the appropriate fields, or click
Edit (for classes to include) and Edit (for classes to exclude) and select the appropriate
class(es) and package(s) from the Class and Package Browser.
For additional information, click Help.
5. Click OK.
You can also include or exclude packages and classes for a project directly from the command
line. Including or excluding packages and classes is, by definition, a project-wide attribute and
so it cannot be set using pragmas.
Related topics

About CodeCoach
9-183
Customizing CodeCoach Advice for Files, Classes,
or Methods
You can fine-tune the advice that CodeCoach provides either before or after you run
CodeCoach.
Before you run CodeCoach on a project, you can customize the categories of advice that
CodeCoach provides for individual files, classes, or methods by inserting pragmas (specially
formatted comments that only the Oracle Java Compiler detects) directly in your source code.
The settings you place directly into source code override any you might have set in the IDE.
The general form of a pragma is:
//@codecoach:[enable, disable, default] [keyword list]
The keyword list is a list of advice keywords, separated by commas. Each advice type has a
keyword associated with it. Do not include any spaces in the list.
Pragmas are only in effect through the end of the source file. If you want to disable advice for
multiple files, it is probably easier to do so through the IDE.
Disabling Advice
To disable advice using a pragma, use code patterned on the following:
//@codecoach:disable NVCT,LALL
public void methodname () {
// method body
}
//@codecoach:enable NVCT,LALL
This bit of code disables Vector instance usage advice and all local variable advice in the
method methodname until the enable line is reached. Pragma-disabled advice remains
disabled until you enable it once again or until the end of the file.
To disable advice for a particular line only, use the following line:
//@codecoach:disable nextline
9-184
It is important, however, that the intended disabled advice appear on the very next line. If a
blank line intervenes, the disabling will not take effect.
Enabling Advice
To enable advice using a pragma, use code patterned on the following:
//@codecoach:enable MALL
// method body
}
//@codecoach:default MALL
This bit of code enables all method advice in the method methodname, and then later returns it
to its default behavior as defined in the project properties or at the command line.
Receiving Default Advice
To receive default advice using a pragma, use the following code:
//@codecoach:default ALL
// method body
}
CodeCoach will now assume the default behavior defined in the project properties or at the
command line.
Related topics

CodeCoach Keywords
9-185
About CodeCoach
About Pragmas
9-186
You can use CodeCoach directly in the IDE or from the command line. From either location,
you can customize CodeCoach advice before running it on a project.
Because CodeCoach runs only within the JDeveloper environment, when working with
CodeCoach from the command line, be sure to use the Oracle Java Virtual Machine (OJVM)
and the Oracle Java Compiler (ojc).
To run CodeCoach from the command line:
1. Decide which classes to CodeCoach and which to exclude.

2. Compile the project with ojc, using the -g switch to compile all included classes with
debug information.
3. For either java.exe or javaw.exe, begin with the parameter -Xcodecoach.
4. To receive information on the advice types added with JDeveloper 3.2 (INST and CSTA),
add the parameter -Xcc:new.
5. List out the appropriate parameters from those shown below to customize the advice
type, the advice level, and to include or exclude packages and classes as needed.
To avoid receiving advice for classes whose source code you will not be altering, be sure
to exclude all third-party classes.
Enabling and Disabling Advice Types
By default, CodeCoach will check for all forms of advice.
To control which types of advice CodeCoach checks for, use the following parameter:
-Xcc:[enable|disable]:[keyword list]
Each advice has a keyword associated with it, and you can combine keywords (separating
them with a comma) to enable or disable several different types of advice.
Note that the order in which you disable and enable advice affects the outcome. To enable only
method advice, for example, you would first disable all advice types and then reenable the
advice for methods:
9-187
-Xcc:disable:ALL -Xcc:enable:MALL
To enable advice for final and private methods alone, you would disable all advice types,
enable method advice, and then disable advice for static methods (the one type of method
advice that you don't want):
-Xcc:disable:ALL -Xcc:enable:MALL -Xcc:disable:MSTA
To control advice more finely in the source file, consider using pragmas.
Setting the Advice Level
By default, CodeCoach will check at the highest level, returning one hundred percent of
potential advice as enabled on the included packages and classes.
-Xcc:level:[0-9]
where 0 indicates the minimum and 9 the maximum depth of advice.
Including or Excluding Packages and Classes
By default, every class that the runnable program loads is included. Nothing is excluded. But
you can alter these values.
If you wish to CodeCoach only a selected subgrouping of your full project class and package
list, use the following parameter:
-Xcc:incl:[class or package list]
Note that as soon as you indicate even one value to be included, the default no longer holds.
Nothing will be CodeCoached but what appears in this include list—so long as it does not
appear in the exclude list. Use the exclude list to exclude subelements of classes or packages
listed in the include list.
To exclude a class or package, use the following parameter:
-Xcc:excl:[class or package list]
To list more than one class or package in either list, separate the names with a semicolon. For
9-188
example,
-Xcc:excl:java;sun.util;oracle.jdeveloper.Class
would exclude java.*, sun.util.*, and oracle.jdeveloper.Class.
Be sure to exclude all third-party classes.
Related topics

CodeCoach Keywords
About CodeCoach
About Pragmas
9-189
CodeCoach Reference
You may find the following reference topics useful while working in CodeCoach:
● CodeCoach Keywords
● CodeCoach Class Advice
● CodeCoach Method Advice
● CodeCoach Field Advice
● CodeCoach Local Variable Advice
● CodeCoach Memory Improvement Advice
● CodeCoach Miscellaneous Advice
Related topics

9-190
CodeCoach Keywords
In CodeCoach, each advice type has a keyword associated with it. You use these keywords to
control the type of advice CodeCoach returns on a segment of code, either in pragmas or from
the command line.
Advice type Keyword

All advice ALL
All class advice CALL

Possible final class
CFIN
Possible static class

CSTA
All method advice MALL

Possible final method
MFIN
Possible private method

MPRI
Possible static method

MSTA
All field advice FALL

Possible final field
FFIN
Possible local field

FLOC
Possible private field

FPRI
Possible static field

FSTA
Possible unused field

FUNU
All local variable advice LALL
9-191
Possible final local variable
LFIN
Possible unused local variable

LUNU
All memory improvement advice NALL

ArrayList instance usage
NALS
BitSet instance usage

NBST
HashMap instance usage

NHMP
Hashtable instance usage

NHTB
StringBuffer instance usage

NSBU
Vector instance usage

NVCT
WeakHashMap instance usage

NWHT
All miscellaneous advice OALL

Dead code caused by constant propagation
CDEA
Immutable object allocation with constant parameters

ACST
Inefficient instanceof
INST
Related topics

9-192
About CodeCoach
CodeCoach Class Advice

CodeCoach Method Advice
CodeCoach Field Advice
CodeCoach Local Variable Advice
CodeCoach Miscellaneous Advice
9-193
CodeCoach will advise you when you can safely change a class modifier.
There are two types of class advice that CodeCoach will provide.
Possible final class

A class which is never extended can be declared final.
In a final class, all the methods can be considered final. Final methods can be inlined
and, more importantly, final methods can be called directly without using the method
table.
In addition, declaring the class final helps the JVM to execute instanceof /checkcast
operations, which are, in general, very expensive.
If CodeCoach detects a class which could be declared final, no final methods advice
(MFIN) is given for the methods of this class.
If you expect to extend the class in the future, you should not follow this suggestion.
The keyword for possible final class advice is CFIN.
Possible static class

If all the symbols of the outer class accessed by an inner class are static, the inner class
should be static as well.
If the inner class accesses even one nonstatic field, method, or object of the outer class,
then it cannot be static.
The keyword for possible static class advice is CSTA.
When a class is run through CodeCoach, but debug information has not been included in the class,
CodeCoach will issue the following warning:

enable CodeCoach
9-194
information enabled, which you can do either by choosing that option in the Project Settings
dialog (from the Compiler node, select Include Debug Information) or by using the -g switch of
ojc on the command line. You should exclude all third-party classes.
Related topics

CodeCoach Project Settings
9-195
CodeCoach will advise you when you can safely change a method modifier. CodeCoach may
advise one of these changes or a combination of these changes, depending on the method.
Method access modifiers can affect efficiency. The stricter the access, the more efficient the
method can be.
There are three types of method advice that CodeCoach will provide.
Possible final method

A method can be declared final if is never overloaded in its subclasses. Final methods
can be inlined, and more importantly, final methods can be called directly without using
the method table.
If CodeCoach detects that the complete class can be set to final, you will not get any
possible final method advice.
The keyword for possible final method advice is MFIN.
Possible private method

Any method used only in its own class can become private. Setting a method to private
will not necessarily make your code more efficient, but it will make it more maintainable.
The keyword for possible private method advice is MPRI.
Possible static method
A method can be declared static if it fulfills the following criteria:
❍ It doesn't use this (in other words, it doesn't access nonstatic fields or methods).
❍ It doesn't overload any method in its superclasses or implement a method of an
interface.
❍ It is never overloaded in its subclasses.
This change spares one parameter on each method call, which is faster and potentially
less expensive in stack memory. Making a method static can allow a compiler to produce
better code because it doesn't have to maintain space or a register to hold an unused
9-196
object reference.
The keyword for possible static method advice is MSTA.
Related topics

9-197
By choosing the right access modifier, you can make fields more efficient. In addition, making a
field local can help your code perform better. Removing unused fields will also help
performance. CodeCoach can advise you on each of these improvements.
There are four types of field advice that CodeCoach will provide.
Possible static final field

A field which is always initialized with the same constant, and never changed, can
become static final. Setting a field to static final can reduce object size, which is very
likely to save memory. If you are planning on extending your code to change the value of
the field or to initialize the field to a different value, you should not set it to static final.
The keywords for possible static final field advice are FSTA and FFIN.
Possible local field

If a field is used by multiple methods, but is always initialized before being used, it should
be replaced by a local variable in the corresponding methods. This saves space and
enhances performance because access to local variables is faster than to fields.
For example, in the following code
class foo {
private int i;
void method1() {
for (i = 0;i < 10;i++) {
// do some stuff
}
}
void method2() {
i = bar();
switch (i) {
case 1 :
........
}
}
}
the field i should be declared as a local field in method1 and in method2 because, in
9-198
each case, the variable is initialized before being used by the method.
Be careful when you are setting fields to local variables. CodeCoach will also, incorrectly,
suggest making a change in the following code:
class foo extends Thread {

private boolean active;
void dostuff() {
active = true;
while (active) {
// do something
}
}
void stopit() {
active = false;
}
}
The method dostuff is designed so that it will be exited only when the field active is
set to false. The method stopit is designed to be used by another thread to set the
field active to false, thereby halting the execution of the method dostuff. If active
is changed to a local variable, it will not function in the intended manner.
The keyword for possible local field advice is FLOC.
Possible private field

Any field used only in its own class can become private. Setting a field to private will not
necessarily make your code more efficient, but it will make it more maintainable. If you
are planning on extending your code to use this field outside of its own class, you should
not set it to private.
The keyword for possible private field advice is FPRI.
Possible unused field

The compiler will usually detect when a field is unused. CodeCoach checks for unused
fields that the compiler misses. If you are considering using the field in the future, you
should not remove it.
The keyword for possible unused field is FUNU.
9-199
Related topics

9-200
Adding modifiers to local variables can save memory in your program.
There are two types of variable advice that CodeCoach will provide.
Possible final local variable

Any local variable which is initialized once with a constant can be declared final. As a
result, the compiler generates better code by using constant bytecode. This also allows
the JVM to do better constant propagation.
In the following example, the variables FIRST_ELEMENT and LAST_ELEMENT are

effectively constants. When the modifier "final" is added, the compiler can generate much
more efficient code.
class foo {
private int FIRST_ELEMENT = 0; //should be modified to final
private int LAST_ELEMENT = 10; //should be modified to final
void method1() {
for (int i = FIRST_ELEMENT;i < LAST_ELEMENT;i++) {
// do something
}
}
void method2() {
int i=bar();
switch(i) {
case FIRST_ELEMENT: // do this
case LAST_ELEMENT: // do that
}
}
}
If you are planning on extending your code to change the value of the variable, you
should not set the variable to final.
The keyword for possible final local variable advice is LFIN.
Possible unused local variable

The compiler will usually detect when a local variable is unused. CodeCoach checks for
9-201
unused local variables that the compiler misses. This includes cases where a value is
assigned to the variable, but the variable is never used.
If you are considering using the variable in the future, you should not remove it.
The keyword for possible unused local variable advice is LUNU.
Related topics

9-202
The size you allot to an object is very important: oversizing can lead to wasted memory, and
undersizing to degraded performance. CodeCoach not only tells you the minimum and the
maximum of memory allocated for an object, but it also gives you the average size of memory
used, the number of times that the object has been resized, and the number of instances.
Resizing is a very expensive operation and should be avoided as much as possible, but there
will be times when you decide to accept the cost of resizing for the benefit of using far less
memory. For example, if the initial size of an object buffering data is too small, there will be an
unnecessary amount of resizing, which will have a high impact on performance.
More so than any of the other advice categories, memory allocation involves judgment. You
should always look at the numbers returned and decide what your best strategy should be for
finding a balance between a larger number of resizes or a larger amount of potentially unused
memory to be set aside. This is why CodeCoach does not try to return a recommended size,
but rather gives you the pertinent data for making an informed decision.
ArrayList instance usage

An ArrayList object behaves in the same manner as a Vector object, and the same
advice applies. The constructor for setting an initial ArrayList size is
ArrayList al = new ArrayList(256);
This code instantiates an ArrayList object al for 256 characters. The default is 10.
The keyword for ArrayList instance usage advice is NALS.
BitSet instance usage

A BitSet object behaves in the same manner as a Vector object, except that these
objects are allocated in groups of 64 rather than 101. Otherwise, the same advice
applies. The constructor for setting an initial BitSet size is
BitSet bset = new BitSet(128);
This code instantiates a BitSet object bset for 128 characters. The default is 64.
The keyword for ArrayList instance usage advice is NBST.
9-203
HashMap instance usage
A HashMap object behaves in the same manner as a Hashtable object, and the same
advice applies. The constructor for setting an initial HashMap size is
HashMap hm = new HashMap(64);
This code instantiates a HashMap object hm for 64 characters. The default is 101.
The keyword for HashMap instance usage advice is NHMP.
Hashtable instance usage

A Hashtable object, much like a StringBuffer object, can be resized. However, resizing a
Hashtable is much more expensive because each time it is resized the entire table must
be rehashed. In addition, the default size for a Hashtable is 101, which is larger than is
often needed.
For every line containing a Hashtable allocation, CodeCoach performs a survey of what
appends to these Hashtables.
If CodeCoach detects that the Hashtable is not full enough, it will advise you to reduce
the size at allocation.
The constructor for setting an initial Hashtable size is
Hashtable ht = new HashTable(64);
This code instantiates a Hashtable object ht for 64 characters. The default is 101.
The keyword for Hashtable instance usage advice is NHTB.
StringBuffer instance usage

When a StringBuffer is created via new StringBuffer(); its initial memory allocation
is 16 characters. If you then add characters past the initial 16-character size, the
StringBuffer is allocated more memory.
The way memory is allocated to expand a StringBuffer can be costly. If a StringBuffer

needs to be expanded beyond its current size, the size is doubled and then the old
StringBuffer is copied into the newly allocated space. So, using the above example, the
9-204
memory allocation looks like this:
Command Memory needed Memory allocated

new StringBuffer() 0 characters 16 characters
append("0123456789") 10 characters 16 characters
which isn't so bad. But, if you put that into a loop that appends the string upon itself
several times
class foo {
void dostringop() {
int i;
StringBuffer sb;
sb = new StringBuffer();
for (i=0; i<100; i++) {
sb.append("01234567890");
}
}
}
and you keep track of needed memory and allocated memory, which now becomes this:
Command Memory needed Memory allocated

new StringBuffer() 0 characters 16 characters
... ... ...
you will see that it can become a real problem. In this case, nearly 1K of memory is
wasted. In addition, resizing the StringBuffer seven times can be a performance problem.
9-205
To avoid such problems, StringBuffer has a constructor that allows you to manually
allocate the amount of space to give the buffer:
StringBuffer sb = new StringBuffer(1100);
This code instantiates a StringBuffer object sb for 1100 characters. The default is 16.
Keeping track of how big StringBuffers are can be difficult, and allocating too much
space is just as much of a problem as not allocating enough space. CodeCoach can
make allocating StringBuffers easier. For every line containing a StringBuffer allocation,
CodeCoach performs a survey of what appends to these StringBuffers.
Because internally the Java compiler uses StringBuffer as a mechanism for

concatenating String objects, CodeCoach may also give you advice concerning such
concatenation. In such a case, you may want to change your String to a StringBuffer
instead. This allows you to have better control over the operation.
The keyword for StringBuffer instance usage advice is NSBU.
Vector instance usage

Like a StringBuffer object, a Vector object may be automatically expanded. CodeCoach
uses the same methodology to check for efficient use of Vector as it does for
StringBuffer. The constructor for setting an initial Vector size is
Vector v = new Vector(512);
This code instantiates a Vector object v for 512 characters. The default is 10.
The keyword for Vector instance usage advice is NVCT.
WeakHashMap instance usage

A WeakHashMap object behaves in the same manner as a Hashtable object, and the
same advice applies. The constructor for setting an initial WeakHashMap size is
WeakHashMap whm = new WeakHashMap(64);
This code instantiates a WeakHashMap object whm for 64 characters. The default is 101.
9-206
The keyword for WeakHashMap instance usage advice is NWHT.
Related topics

About CodeCoach Memory Improvement Advice
9-207
There are three types of miscellaneous advice that CodeCoach will provide.
Dead code caused by constant propagation

CodeCoach can go a little further than the compiler to detect dead code.
CodeCoach can detect blocks of dead code in conditionals and exception blocks, as in
the following:
int i,j;
i = 1;
j = 2;
if ( i + j == 5) {
// Because 1 + 2 can never equal 5,
// anything in this block would be dead code.
}
CodeCoach will also catch dead code in exception blocks like the following:
try {
i = j + 3;
}
// This is dead code because no
// instruction in the try can cause
// an exception
}
And, in the following snippet, CodeCoach would also detect partial dead code:
int i,j,k;
i=2;
j=3;
k=(i==3)?i-j:i+j;
In this case, CodeCoach would detect that i cannot ever equal three, and so i-j will be
dead code.
9-208
Be cautious when deleting detected dead code. If you remove code from an exception
block based on CodeCoach advice and then change your code you may get some
unintended results.
The keyword for detecting dead code is CDEA.
Immutable object allocation with constant parameters

Some Java classes, including java.lang.String and java.awt.Color, are
immutables. Once an instance of an immutable class has been allocated, its value can
never be modified.
If such an immutable object is used repeatedly, CodeCoach will recommend creating a

static final instance of this object in the class static initializer. Doing this will spare
memory and gain performance for the program.
For example, the following code
class foo {
void paint() {
int i;
for (i=0; i<100; i++) {
bar(i, new Color(1,2,3));
}
}
}
will create one hundred instances of java.awt.Color each time the method paint is
called. Each of these instances will be kept if the bar function stores this value in a
visible reference.
A better version of the same class would be:
class foo {
private static final Color MyColor = new Color(1,2,3);
void paint() {
int i;
for (i=0; i<100; i++) {
bar(i, MyColor);
}
}
9-209
}
In this case only one java.awt.Color instance would be created.
Be careful using this advice if the object will be used for any synchronization process. In
that case, creating a static final field would make synchronization global to the process
instead of local to the object instance.
The keyword for detecting repeated instances of immutable objects is ACST.
Inefficient instanceof success rate of 100%

Inefficient instanceof success rate of 0%
The instanceof operation enables you to determine when one object is a subclass of
another.
When an instanceof statement is either always true or always false, the operation is
both unnecessary and expensive:
private static final void test_INST() {

BufferedReader r1;
try {
r1 = new BufferedReader(new FileReader("C:\\boot.ini"));
Object obj = r1;
if (obj instanceof Reader) { //success rate 100%

System.out.println("It's a Reader!");
}
if (obj instanceof Writer) { //success rate 0%
System.out.println("It's a Writer!");
}
} catch (IOException e) {
System.out.println("Ooops!");
}
}
In this example, it's clearly visible that obj is always a reader. In real-world applications,
the situation is usually not so obvious.
9-210
Another common situation is this:
1 : void foo(Vector v)
2 : {
3 : int i;
4 :
5 : for (i = 0; i < v.size(); i++)
6 : {
7 : Object o = v.elementAt(i);
8 : if (o instanceof MyClass)
9 : {
10 : MyClass m = (MyClass) o;
11 : m.bar();
12 : }
13 : else
14 : {
15 : abortProgram();
16 : }
17 : }
18 : }
In this case, the Vector provided to the foo method is designed to contain only instances
of MyClass. If it contains something else, it must be a bug and it's fatal. This version of
foo is very conservative and tests for all the cases. But an expensive operation is
performed twice: at line 8 (instanceof) and at line 10 (checkcast performed internally
by the VM). A more efficient version of the same method could be:
1 : void foo(Vector v)
2 : {
3 : int i;
4 : try
5 : {
6 : for (i = 0; i < v.size(); i++)
7 : {
8 : MyClass m = (MyClass) v.elementAt(i);
9 : m.bar();
10 : }
11 : {
12 : Catch (ClassCastException e)
14 : {
15 : abortProgram();
16 : }
18 : }
9-211
In this case only one expensive test is performed at line 8, and if something goes wrong,
the program is aborted as well. You could even catch it higher in the calling hierarchy.
The same thing would be true if the instanceof operations always fails: it would
probably mean that it's an error in the program logic.
The keyword for detecting such instanceof operations is INST.
Related topics

9-212
Profiling a Project
The Profiler gathers statistics on your program that enables you to more easily diagnose
performance issues. With it you can examine and analyze your data.
When using the Profiler, you will want to know how to:
● Set global profiler options

● Define the profiler class set
● Start and stop the Profiler
● Arrange data views in the Profiler
● Control a profiling session with Profiler API commands
● Profile a program remotely
● Execution profile a program
● Memory profile a program
● Event profile a program
Related topics
About the Profiler

About Remote Profiling

Configuring Your Project for Deployment
9-213
Profiler Concepts
You may find the following conceptual topics useful while working with the Profiler:
● About the Profiler

● About the Profiler Class Set
● About Remote Profiling
● About Execution Profiling
● About Memory Profiling
● About Event Profiling
Related topics
Profiling a Project
Starting and Stopping the Profiler
9-214
About the Profiler
The Profiler takes advantage of the features in the Oracle Java Virtual Machine (OJVM)
enabling you to find programming inefficiencies, performance problems, and memory leaks in
your application code. You can use the Profiler with the Debugger and CodeCoach for powerful
and efficient troubleshooting in your application code.
There are three types of profiling you can use to improve the performance of your application:
● Event profiling
● Execution profiling
● Memory profiling
You can also profile a program remotely.
To profile a program, you first define its parameters in the Project Settings dialog. On the
Profiler page, you define the parameters common to the three types of profiling. On the Events
page, you define the settings for event profiling. On the Execution page, you define the settings
for execution profiling. On the Memory page, you define the settings for memory profiling.
Once you have configured the profiling settings, you begin a profiling session by selecting the
file or project in the Navigator and choosing the appropriate profiler from the Run menu. The
Profiler then opens in a window, with the information displayed as indicated by the settings you
have given it. To alter those settings directly from the Profiler itself, right-click in the Profiler
window and choose Settings. Changes in which columns appear are dynamic. If you specify a
change in which columns appear, when you return to the Profiler, its display reflects that
change. If you make other changes, they will not take effect until you begin a new profiling
session.
All of the Profiler windows are dockable and you can sort the data by any column, in either
ascending or descending order, and move columns to reflect any order.
Related topics

Defining the Profiler Class Set
Setting Profiler Options
9-215
Controlling a Profiling Session with Profiler API Commands
9-216
About the Profiler Class Set
It is the profiler class set that defines which classes will be considered when you profile a
program.
You define the profiler class set by listing which classes will be included and which will be
excluded in a profiling session. It is this set of classes—all those both included and not
excluded—that determines what the Profiler considers to be your program. Only those classes
contained in the profiler class set will be evaluated when you run the Profiler on a project.
The profiler class set is defined on the Profiler page of the Project Settings dialog.
Defining Profiler Class Sets
Separate individual entries in either list with semicolons. Entries can be packages or classes. If
a package is included, all of its subpackages and their classes are included. You can include
an entire package and then exclude specific members of that class, but you cannot do the
reverse. If a package is excluded, there is no way to include portions of it. Do not exclude a
package unless you intend not to use any of its classes or subpackages.
So, in other words, if you include java, you have included java and java.util and
java.io and java.lang and java.lang.ref, and so on. You can now exclude individual
subpackages if you wish. Conversely, if you exclude java, then you have excluded
java.util, java.io, java.lang, java.lang.ref and all the rest. There is no way to
individually include any of these subpackages.
An empty value in the include list is the same as including all classes. An empty value in the
exclude list is the same as excluding no classes. When both are empty, everything is included
and nothing is excluded.
Examples
As an example, take a program that uses myPackage, which contains your main program
code, and myPackage.fileUtils, which contains your own file utilities, and java, which
contains the Java J2SE
If you wanted to specify all your code, you could enter:
Include = "myPackage"
Exclude = ""
9-217
or
Include = ""
Exclude = "java"
If you wanted to specify all your code except the file utilities, you would enter:
Include = "myPackage"
Exclude = "myPackage.fileUtils"
And if you wanted to include everything, including java, you would enter:
Include = ""
Exclude = ""
Some Common Mistakes
Once you have specified an include list (such that only what you have defined here is now
being included), it is not necessary to exclude something that is not in some way contained
within the elements of that list.
For example, if you have included myPackage it is not necessary to exclude java. As java is
not contained within myPackage, it is already automatically excluded by never having been
included.
While if your include list is fully contained in the exclude list, the net result is an empty profiler
class set.
For example, if you include myPackage.fileUtils and then exclude myPackage, you have
completely excluded what you had intended to include. As myPackage.fileUtils is
completely contained within myPackage, it has been excluded. And as it constitutes the only
included element, the end result it that nothing is included and there is no profiler class set.
Profiling and the Profiler Class Set
The purpose of the profiler class set is to tell the Profiler what to look at. How you define the set
directly affects the results you are returned.
To take an example, suppose you use the default profiler class set, which doesn't contain either
9-218
the J2SE or the java package. What happens as a result when you profile your program?
If you begin an execution profiling session, even if the sample was taken while your method
happened to be calling some number of J2SE methods, the Profiler will register a hit towards
your method and not towards the J2SE method. The reason this is so significant is that you can
modify your code, but generally not that of the library you are using. On the other hand, if you
find your method is slow, but you cannot locate why, you might try including the libraries that
this methods calls in order to figure our which calls are expensive and which are not.
Let's say, on the other hand, that you wish to begin a memory profiling session, and that you
have also created a Finalizer object. The VM will automatically call the register method from
the java.lang.ref.Finalizer class, but the allocation of this Finalizer object will be
attributed to your method. In this case, not including the J2SE in the profiler class set might be
just the strategy you want. If the J2SE had been part of the set, all allocation of Finalizer
objects would have been reported in the Finalizer.register() method, rendering
potentially less useful results.
Related topics
About Event Profiling

About Execution Profiling
About Memory Profiling
9-219
You can run a profiling session remotely. When you start a remote profiling session, the Profiler
connects and profiles remote applications as if they were local. Since you still run the Profiler
locally, you can profile applications on other computers provided that they have a reachable IP
address or DNS name.
Remote profiling can be preferable to local profiling. When you remote profile, the profiler and
profilee are running on two different computers and so they are not competing for the same
resources.
Note that the remote JVM must be an ojvm.
Related topics
Profiling Remotely
9-220
You use the Execution Profiler to create a statistical analysis of the performance of your
application. The Execution Profiler can be used to test functions of your application, such as
startup and initialization, repainting, and compiling, for example.
The Execution Profiler samples data on a running application at regular intervals based on the
Sample Interval setting. When the Execution Profiler takes a sample, data is recorded about
the most active thread in the last interval The samples are computed and displayed in the Call
Sample table when you pause the Execution Profiler, or when the application terminates. All
samples that have accumulated from the start of the program (or the last clear) are displayed
when you pause the Execution Profiler or when the program terminates. Knowing which
methods appear frequently at the top of the call stack can help you identify problem areas in
your application.
You set the sample interval in the Project Settings dialog. The shorter the interval, the more
samples are taken. In the upper right corner of the Execution Profiler window, you will see the
total number of samples taken. When you allow the Execution Profiler to accumulate more
samples, the more accurate the statistical analyses are.
When comparing results between two different execution profiling sessions, you might take into
account the difference in the number of samples taken as the number of samples affects the
percentages that are displayed.
You can also save the results of your execution profiling session into an HTML file for
comparison with a subsequent session. The generated HTML file contains a table which is
sorted the same way as the current sort order in the Execution Profiler.
Related topics
Execution Profiling
9-221
The Memory Profiler provides a visual and statistical analysis of how your program utilizes
memory in the Java heap. You use the Memory Profiler to track down and isolate memory
leaks in your program.
The Memory Profiler obtains information on memory utilization at specified intervals for your
application. After pausing the Memory Profiler, or after the application terminates, you'll see
profiler information displayed about the last interval, such as memory used and discharged in
the Java heap. You can scroll through the available samples using the slider controls in the
user interface. After locating the suspicious memory leaks with the Memory Profiler, you can
jump to the source code and fix and test your changes. After sorting and viewing information in
the Profiler, you can save memory profiling data to an HTML file.
When using the Memory Profiler, you might want to start with automatic sampling first, to get a
global view of the heap usage by your program. You'll select a combination of sampling interval
and slider depth that depends upon your program type. A long interval and large slider depth
are adapted to long running applications such as servers. Small intervals are better suited for
fast and intensive applications. Remember that a set defined by a smaller sampling rate, a
larger slider depth, and wider instances puts high memory demands on the profiler UI.
Once you have a better idea of what you want to observe, use the include/exclude instances to
refine your search. With a narrower search, you can request more samples or a higher
sampling rate without encountering difficulties with memory.
After you have monitored your program's memory usage with automatic sampling, such that
you have detected with functionality performs poorly on the heap, you can switch to manual
sampling rate (0 for update interval) in order to get an accurate count of what's happening when
this functionality is executed.
Related topics
Memory Profiling
9-222
The Event Profiler gathers and displays event timing, for specified events, in relation to all
events in your program. The Event Profiler automatically adds all events it finds in your
program to the Event list. You can also add other events as you create them, as well as group
events together.
The Event Profiler allows you to find uncover problematic issues such as:
● This operation is slow because it produces a lot of temporary objects on the heap, which,
in turn, require multiple garbage collection operations.
● Displaying this screen is slow because several database operations must be performed
before it can be displayed
Configure the type of events to be displayed in the Project Settings dialog and create events of
your own using the Profiler API. Using API class provides greater control and analysis of events
in your applications.
Related topics
Event Profiling
9-223
Setting Global Profiler Options
The settings on the Profiler node itself are generic to all types of profiling. Settings that are
made on a specific page affect only that type of profiling.
To access and set Profiler options:
1. In the Navigator, select the project to be profiled.

3. In the Project Settings dialog that appears, select the Profiler node.
4. Define the profiler class set by specifying packages and classes to be included and
excluded.
For more information on any control in this dialog, click Help.
5. Select the options to use profiler APIs or to remote profile, if desired.

6. Click OK.
Related topics
9-224
The profiler class set is the set of classes that the Profiler will look at during a given profiling
session. For the Profiler, the class set is your program.
By default, all packages and classes in your project are included and nothing is excluded. To
create a viable profiler class set, you must define, depending upon what you are examining,
what ought to be included and what ought to be excluded.
The profiler class set is defined by the combination of what appears in both the include and the
exclude lists.
To include classes in a profiling session:
1. In the Navigator, select the project to be sampled.

2. From the main menu, choose Project | Settings and click the Profiler node.
3. In the Included Classes text field, add the names of the classes or packages to be
included, separating each with a semicolon.
By default this field is empty, which includes everything in the project. As soon as you
add one specific item to this list, the packages or classes included are limited to that one
item.
4. Select OK.
The next time the Profiler samples data from your application, these classes will be
included in the data sample.
To exclude classes in a profiling session:
1. In the Navigator, select the project to be sampled.

2. From the main menu, choose Project | Settings and click the Profiler node.
3. In the Excluded Classes text field, add the names of the classes or packages to be
excluded, separating each with a semicolon.
By default this field is empty, which excludes nothing. As soon as you add one specific
item to this list, you begin to define items to be excluded.
9-225
4. Select OK.
The next time the Profiler samples data from your application, these classes will be
excluded from the data sample.
Related topics
About the Profiler Class Set
9-226
You can start an event, sample, or memory profiling session for a project or any of its runnable
files, as well as have multiple sessions running, depending on the availability of system
resources.
You can also select the Profile icon in the toolbar; however, there is only one icon in the
toolbar. Once you select a specific profiler type from the Run menu, the icon will change to
reflect the most recently used profiler.
To start the Profiler and begin a profiling session:
● In the Navigator, select the project or file to be profiled.

● From the main menu, choose Run | <profiler type> <project name>.
The Profiler window appears. The default profiling mode is execution profiling.
After the Profiler starts, a Profiler tab with the project name or filename appears in the Log
window and the process is added to the Run Manager.
Profiler tab
To pause the Profiler:
● While your application is running in the Profiler, click Pause .
With the program paused, you can examine the in-progress results of the current
profiling session.
To resume the Profiler:
9-227
● Click Resume .
Resume a paused program to access your application.
To clear results for the Event or Execution Profiler:
● Click Clear .
Clear results when you wish to view data in one window of time, between a paused and
resumed program, rather than all the data in a given profiling session.
To stop and close the Profiler:
● Click the close box (marked with an x) in the Profiler.
Closing the Profiler removes the process from the Run Manager, but does not dismiss
the profiling information in the Log window.
Related topics
About the Profiler

Setting Profiler Options
9-228
Arranging Data Views in the Profiler
You can easily customize the views of data in the Profiler, as well as scroll through the data
samples. When you save your profiling results to an HTML file, the column order and sorting is
saved as well.
To arrange the columns in the Profiler:
● Click on a column header and drag it left or right to the desired position.
To sort the data in a column:
1. Click on a column header so that the green arrow is visible.

2. Click the green arrow to change the order of the data in the column as ascending or
descending .
Related topics
Starting and Stopping a Profiler Session
9-229
Controlling a Profiling Session with Profiler API
Commands
You can place the Profiler API calls in your source code to control starting, pausing, or stopping
your profiling session. These API calls do not affect compilation.
To use Profiler API commands in your source code:
1. From the main menu, choose Project | Project Settings and click the Profiler node.
2. Choose Use API and click OK to dismiss the Project Settings dialog.
3. Place the appropriate API calls in your source code, depending on which type of profiling
you wish.
Related topics
Class ProfilerAPI
9-230
Remote Profiling
You can remote profiler any program. You may find remote profiling preferable to local profiling.
To set up a remote profiling session:

3. On the Profiler page, select the Remote Profiling checkbox.
The first time that you run the Profiler subsequent to this, the Connect to Profilee dialog
appears.
To connect remotely:
1. In the Navigator, select a runnable node.

2. From the main menu, choose Run | <profiler type> <project name>.
If this is the first time you have connected since specifying remote profiling, or if you have
not before saved or have unsaved parameters, the Connect to Profilee dialog appears.
3. In the Connect to Profilee dialog, enter the machine and its port. If you will be remote
profiling from this same location, select Save parameters.
When you save parameters, this dialog no longer appears. Subsequent remote profiling
sessions connect to this same machine and port.
To change your remote profiling location:

3. On the Profiler page, click Unsave Parameters.
The next time you open a remote profiling session, the Connect to Profilee dialog will
again appear. As long as the Remote Profiling checkbox is selected, every profiling
session will be a remote one.
9-231
Related topics
About the Profiler

9-232
Execution Profiling
Execution profiler enables you to identify the most expensive methods and threads in your
program.
When event profiling, you'll want to know how to:
● Set options for the Execution Profiler

● Start and stop an execution profiling session
● Analyze execution profiling results
● Save the results of an execution profiling session
Related topics
About the Profiler

9-233
Setting Options for the Execution Profiler
You can specify for how long the Execution Profiler to take a sample. Larger sample intervals
provide you with more accurate statistical information about your application.
To set Event Profiler options:

2. In the Project Settings dialog that appears, select the Profiler and then the Execution
node.
3. In the Sample Interval field, enter the sample interval rate.
4. Select which columns to be displayed.
Column display is dynamic. You can change which columns to display while a profiling
session is paused.
5. Click OK.
6. Start or resume the execution profiling session.
Related topics
Execution Profiling
9-234
Starting and Stopping an Execution Profiling
Session
To start the Execution Profiler:
1. In the Navigator, select a runnable node.

2. From the main menu, choose Run | Execution Profile <project or filename>.
The Execution Profiler opens and executes your runnable file.
3. To view sample data while the runnable file is executing, click Pause. If the runnable file
has finished executing, data will appear in the columns.
4. To resume execution profiling, click Resume.
To end an execution profiling session:
● Click the close box (marked with an x) to dismiss the Execution Profiler.
Related topics
Analyzing Execution Profiling Results

9-235
Analyzing Execution Profiling Results
You can let the Profiler run for the lifecycle of the application, and display results when the
application has terminated, or you can Pause , Resume , or Clear the sample data as
the application runs. When you Pause the Profiler, control is given to the Profiler window. To
return to your application, you must first Resume the Profiler, then you can access your
application to continue running it.
When you press Clear, the next set of data that is displayed is for the interval between that
Clear action, and the next Pause. This interval enables you, for example, to get a data sample
only on the interval of code that is used during specific events in your program's user interface,
such as a button being pressed, and the result that is issued.
You can sort by any column in the results table by selecting the column heading in the table. A
green arrow appears in the column heading to indicate if the column is sorted in ascending
or descending order. You can select a method in the main table to see the calls and called from
details on the left side of the window. You can also double-click a method in the main table to
navigate to the source for that method in the Code Editor.
Related topics

Saving the Results of an Execution Profiling Session
9-236
Saving the Results of an Execution Profiling
Session
When you are no longer using the Profiler, you can save the results of your profiling session to
an HTML file. If you've rearranged the way information is displayed in any column, that order is
preserved in the HTML file.
To save the results of a profiling session to a formatted HTML file:
● Right-click a method in the Call Sample table and choose Save to HTML.
Related topics
Execution Profiling
9-237
Memory Profiling
Memory profiling helps you to find out how your program is using the Java heap.
When memory profiling, you'll want to know how to:
● Set options for the Memory Profiler

● Start and stop a memory profiling session
● Locate where methods are called from
● Analyze memory profiling results
● Save the results of a memory profiling session
Related topics
About the Profiler

9-238
Setting Options for the Memory Profiler
To set Memory Profiler options:

2. In the Project Settings dialog that appears, select the Profiler and then the Memory
node.
3. Fill in the update interval, the slider depth, and the included and excluded instances as
desired.
session is paused.
5. Click OK.
6. Start or resume the memory profiling session.
Related topics
Memory Profiling
9-239
Starting and Stopping a Memory Profiling Session
When you start a memory profiling session, and as a new sample is taken at regular intervals, the
details table is updated with the latest results as the program runs, providing you with dynamic data.
When you pause the Memory Profiler, or when the application terminates, the last interval is displayed.
To start the Memory Profiler:
● From the main menu, choose Run | Memory Profile <project name>.
A window appears for the Memory Profiler output.
A snap of the Memory Profiler window
To terminate a memory profiling session:
● From the main menu, choose Run | Terminate.
or
● Close the Profiler window.

9-240
At the top of the window is a slider: the dots indicate each sample taken. You can set the interval for
execution profiling in the Project Settings dialog.
You can Pause and Resume the execution profiling as you need to. When the Memory Profiler is
paused, you can use the slider to navigate to previous samples by selecting one of the red dots or one
of the arrow buttons on either side of the slider.
The slider depth is also configurable in the Project Settings dialog if you want to be able to see more or
fewer samples. By default, the slider only shows 10 samples. Once 11 samples have been taken, the
first sample will no longer be visible in the slider, and you won't be able to navigate back to that first
sample.
Related topics
Analyzing Memory Profiling Results

9-241
Finding Where Methods Are Called from in the Memory
Profiler
You can locate where a method is called from in the Memory Profiler while the Memory Profiler is
running or paused.
To locate where a method is called from in the Memory Profiler:
1. In the Navigator, select the runnable file to run in the Memory Profiler.
2. From the main menu, choose Run | Memory Profile <project filename>.
The Memory Profiler window appears and runs your application.
A snap of the Memory Profiler window
3. Double-click a method in the Class column, or select a class, right-click it, and choose Get
Allocation Details.
A new window appears for each method you click in the Class column.
9-242
4. Within each entry in the Location column, you can double-click to open the Code Editor to view
the source code. If source is not available, the Memory Profiler will ask you if you want to
generate a stub for it.
5. Click the close box (marked with an x) to dismiss each location window when you're done with it.
Related topics
Analyzing Memory Profiler Results

Saving the Results of a Memory Profiling Session
9-243
Analyzing Memory Profiler Results
You can use the Memory Profiler to locate and isolate memory leaks in your runnable files and
projects. The screenshot below contains a memory profiling session that illustrates a memory
leak.
A memory profiling session illustrating a memory leak
The detail columns provide you with specific information about memory usage for your
application.
The values for these columns change as you scroll through the previous samples.
Localizing a Memory Leak
As you scroll backwards through some of the previous samples using the slider, you can locate
memory leaks by looking at the number in the Diff Sz column. If this number is always very large
for an object, it means that the program is allocating a lot of memory for a particular method or
set of methods, but not freeing up as much, and the difference between allocations and freed
9-244
remains high. This difference indicates a memory leak.
When you resume the Memory Profiler by clicking Resume at the top of the window, and let it
run for a few more samples, the details table updates for each interval as well as the master
table. Also, the specific source lines of code in the details table do not change, which means the
memory leak is localized.
Optionally, you can save your profiling session information into an HTML file.
Related topics

9-245
You can save the results of a memory profiling session as an HTML file at any time. You can
save the current interval, or all of them. The sort order in the Memory Profiler is preserved in
the HTML file, with links for navigation.
To save the results of an interval to an HTML file:
1. Right-click in the main window of the Memory Profiler and choose Save to HTML.
The Save dialog appears.
2. Enter a name for the file and click Save.
To save the results of all intervals to an HTML file:
1. Right-click any of the instances in the main window of the Memory Profiler and choose
Save All to HTML.
The Save dialog appears.
2. Enter a name for the file and click Save.
Related topics
Memory Profiling
9-246
Event Profiling
Event profiling enables you to figure out how your program spends its execution time, by
evaluating the interaction between the different modules of your application and the Java
Virtual Machine.
When event profiling, you'll want to know how to:
● Set options for the Event Profiler

● Start and stop an event profiling session
● Save the results of an event profiling session
Related topics
About the Profiler

9-247
Setting Options for the Event Profiler
To set Event Profiler options:

2. In the Project Settings dialog that appears, select the Profiler and then the Events node.
3. On the Events page, define and select the events to profile as desired. Assign numeric
IDs as needed.
session is paused.
5. Click OK.
6. Start or resume the event profiling session.
Related topics
Event Profiling
9-248
Starting and Stopping an Event Profiling Session
To start an event profiling session:
1. In the Navigator, select a project node.

2. From the main menu, choose Run | Event Profile < project name>.
The Event Profiler appears and runs your application.
To pause the Event Profiler:
● Click Pause to interrupt the Event Profiler and display the current event profile
information.
If you paused the Event Profiler, you can Resume it to continue the event profiling session,
or Clear the current profiling information.
To end an event profiling session:
● Click the close box (marked with an x) in the Event Profiler window. If you have multiple
profiling sessions running, right-click the window in the Run Manager and choose
Terminate.
Related topics
9-249
Saving the Results of an Event Profiling Session
When you are no longer using the Profiler, you can save the results of your profiling session to
an HTML file. If you've rearranged the way information is displayed in any column, that order is
preserved in the HTML file.
To save the results of a profiling session to a formatted HTML file:
● Right-click an event in the main window of the Memory Profiler and choose Save to
HTML.
Related topics
Event Profiling
9-250
Profiler Reference
You may find the following reference topic useful while working in the Profiler:
● Class ProfilerAPI
Related topics
Profiling a Project
9-251
oracle.jdeveloper.profiler
Class ProfilerAPI
java.lang.Object
|
+--oracle.jdeveloper.profiler.ProfilerAPI
public class ProfilerAPI

extends java.lang.Object
Utility class to provide code-level support for profiling features.
This class contains a set of static methods allowing code instrumentation for profiling.
Instrumented code will run on any VM or in any mode with OJVM, but the instrumentation will
be effective only if you run your program with OJVM in profiling mode. In any other cases the
implementation is designed to be "transparent" and, as long as the instrumentation is done
properly, to add no execution penalty.
This class currently supports two of JDeveloper's profiling modes: execution profiling and event
profiling.
Sample Use for the Execution Profiler
In execution profiling mode you can instrument your code to start or stop the Profiler, in order to
profile a specific area of your program. See startSampling() stopSampling().
Typical sampling code implementation:

public void foo()
{
ProfilerAPI.startSampling(); // Starts the sampler
// execute some code
ProfilerAPI.stopSampling(); // Stops the sampler
}
Nested calls of start/stop sampling are allowed.
9-252
Sample Use for the Event Profiler
Useful event profiling requires code instrumentation, even if the VM and some libraries
generate events. The ProfilerAPI class allows you to do so.
Events have the following attributes:
ID
Integer value describing the event type. The user is responsible for providing a unique ID
system wide. It's strongly recommended to use static final int CSTXXX to define
the events ID. OJVM might generate an events ID from 0-99, but the event ID unicity is
not enforced by the API.
Comment
Extra information associated with every event. Unless the event is trivial, it's in your best
interest to provide meaningful information through this comment.
Start and End time
Provided automatically using a high-performance time counter.
Code position
Provided automatically by the VM.
Recommended event instrumentation:

class foo
{
private static final int EVENT_ID = 500;
private static final boolean EVENT_ON =
ProfilerAPI.isActive && ProfilerAPI.isEventActive(EVENT_ID);
// some code
String getInfo(String request)
{
int eventHandler = -1; // default value
if (EVENT_ON)
{
eventHandler = ProfilerAPI.startEvent(EVENT_ID, "Getting info
for " + request + "\n");
}
try
{
// some code
9-253
if (simpleRequest)
{
if (EVENT_ON)
{ // might be useful for the user
ProfilerAPI.addComment(eventHandler, " Simple request\n");
}
// actual code of the simple request
}
else
{
if (EVENT_ON)
{ // might be useful for the user
ProfilerAPI.addComment(eventHandler, " Complex request\n");
}
// actual code of the complex request
}
}
catch (Throwable e)
{
if (EVENT_ON)
{
ProfilerAPI.addComment(eventHandler, " Interrupted with
exception " + e);
}
throw(e);
}
finally
{
if (EVENT_ON)
{
ProfilerAPI.endEvent(eventHandler, " Result = " + res);
}
}
return res;
}
// other methods
}
This implementation looks complex, but it attempts to deal with all cases. Unless you are event
profiling, it has almost no performance penalty. If you know that your code will not throw any
exceptions, all try / catch / finally structure is useless. Using a static boolean evaluated
only once minimizes the performance penalty when you not profiling. It would work properly
without this "trick," as the ProfilerAPI functions would just return instantly, but all the method
9-254
arguments would have been evaluated already.
Field Summary
static boolean isActive
Method Summary
static void addComment(int handle, boolean o)
Add comment to the event.
static void addComment(int handle, char o)
static void addComment(int handle, char[] o)
static void addComment(int handle, char[] o, int offset, int count)
static void addComment(int handle, double o)
static void addComment(int handle, float o)
static void addComment(int handle, int o)
static void addComment(int handle, long o)
static void addComment(int handle, java.lang.Object o)
static void addComment(int handle, java.lang.String o)
Add String comment to the event.
static void addStackToComment(int handle)
Add the current stack to the comment.
static void clearEventHistory()
Clear all event except the non finished ones.
static void dumpEventHistory()
Print the current stored events on stderr.
9-255
static void endEvent(int handle)
End an event.
static void endEvent(int handle, java.lang.String comment)
End an event.
static boolean isEventActive(int event)
Check if this particular Event ID is active during this run.
static void pulseEvent(int event, java.lang.String comment)
Create a pulse event.
static int startEvent(int event)
Returns a handle which must be used for any further references to this event.
static int startEvent(int event, java.lang.String comment)
static void startSampling()
Start sampling. This call must be paired with stopSampling().
static void stopSampling()
Stop sampling. This call must be paired with startSampling().
Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Field Detail
isActive
public static boolean isActive
Method Detail
startSampling
public static void startSampling()
Start sampling. This call must be paired with stopSampling().
9-256
Sampling is on until the outermost call to stopSampling is executed.
See Also:
stopSampling()
stopSampling
public static void stopSampling()
Stop sampling. This call must be paired with startSampling().

See Also:
startSampling()
startEvent
public static int startEvent(int event,

java.lang.String comment)
This call must be paired with a call to endEvent.
Multiple events with the same ID can be started and ended independently.
Start time and code position are evaluated during this call.
The comment String argument is stored within the VM. Any further comments will be
appended.
If the event profiler is not activated or this event is not active, the returned value is -1. All
further calls to any event function will then return immediately. That's why it's a good idea
to initialize the handle to -1.
9-257
Parameters:
event - Event ID.
comment - Comment.
Returns:
Event handle.
See Also:
endEvent(int), endEvent(int, String)
startEvent
public static int startEvent(int event)
This call must be paired with a call to endEvent.
This call is equivalent to startEvent(event, null);

Parameters:
event - Event ID.
Returns:
Event handle.
See Also:
startEvent(int, String), endEvent(int), endEvent(int, String)
endEvent
public static void endEvent(int handle,

9-258
End an event.
This call must be paired with a call to startEvent. The Handler must have been
provided by a startEvent function or be -1. Any other value will be ignored and a
warning message will be printed on stderr.
End time is evaluated during this call.
The comment String argument is appended to the current comment.
Once an event id has ended, no further calls should be made using this particular
handle. endEvent must be the last call to generate this event.
Parameters:
handle - Event Handle.
comment - Comment.
See Also:
endEvent(int), startEvent(int, String), startEvent(int)
endEvent
public static void endEvent(int handle)
End an event.
This call must be paired with a call to startEvent. The Handler must have been
provided by a startEvent function or be -1. Any other value will be ignored and a
warning message will be printed on stderr.
9-259
Equivalent to endEvent(handle, null); End time is evaluated during this call.
Once an event id ended, no further calls should be made using this particular handle.
endEvent must be the last call to generate this event.
Parameters:
comment - Comment.
See Also:
endEvent(int, String), startEvent(int, String), startEvent(int)
pulseEvent
public static void pulseEvent(int event,

Create a pulse event.
Position, Start, and End time are evaluated during this call.
This function allows you to create an event with no significant duration.

Parameters:
event - Event ID.
comment - Comment.
isEventActive
public static boolean isEventActive(int event)
Check to see whether this particular event ID is active during this run.
9-260
This function should be used to avoid extra overhead if any event is not needed in this
particular run.
Parameters:
event - Event ID.
Returns:
Event handle.
addComment
public static void addComment(int handle,

java.lang.String o)
Add String comment to the event.
The Handler must have been provided by a startEvent function or be -1. Any other
value will be ignored and a warning message will be printed on stderr.
The comment is appended at the end of the current comment.

Parameters:
Comment - Comment.
See Also:
startEvent(int, String), startEvent(int)
addStackToComment
public static void addStackToComment(int handle)
Add the current stack to the comment.
9-261
The current stack is appended at the end of the current comment.

Parameters:
Comment - Comment.
See Also:
clearEventHistory
public static void clearEventHistory()
Clear all finished events.
dumpEventHistory
public static void dumpEventHistory()
Print the current stored events on stderr.
addComment

java.lang.Object o)
9-262
Equivalent to addComment(handle, String.valueOf(o))

Parameters:
o - Comment.
See Also:
addComment

int o)

Parameters:
o - Comment.
See Also:
9-263
addComment

char o)

Parameters:
o - Comment.
See Also:
addComment

Boolean o)
9-264
Parameters:
o - Comment.
See Also:
addComment

float o)

Parameters:
o - Comment.
See Also:
addComment

double o)
9-265

Parameters:
o - Comment.
See Also:
addComment

long o)

Parameters:
o - Comment.
See Also:
9-266
addComment

char[] o)

Parameters:
o - Comment.
See Also:
addComment

char[] o,
int offset,
int count)
9-267

Parameters:
o - Comment.
See Also:
9-268
● Developing JavaBeans
● JavaBeans Concepts
❍ About JavaBeans
❍ About JavaBeans Properties

❍ About JavaBeans Methods
❍ About JavaBeans Events
❍ About JavaBeans Event Sets
❍ About Event Handling
❍ About Property-Accessor Methods
❍ About BeanInfo Classes
❍ About Tuning Properties, Methods, and Events for a JavaBean
❍ About Introspecting a JavaBean
❍ About Property Editors
❍ About Customizers
❍ About Serializing a JavaBean
● Creating a JavaBean
● Creating and Modifying Fields Using the Class Editor
● Creating and Modifying Methods Using the Class Editor
● Creating and Modifying Events Using the Class Editor
● Creating and Modifying Property-Accessor Methods Using the Class Editor
● Selecting an Event-Handling Adaptor
● Ways to Create a BeanInfo Class
❍ Creating a BeanInfo Class Using the Class Editor
❍ Creating a BeanInfo Class Using the New BeanInfo Dialog
● Ways to Customize a JavaBean Using a BeanInfo Class

❍ Tuning Properties and Methods for a JavaBean
❍ Tuning Events for a JavaBean
10-1
❍ Specifying a Default Property or Event for a JavaBean
❍ Introspecting a JavaBean
● Ways to Create a Property Editor

❍ Creating a Property Editor That Displays a List of Source Code Values
❍ Creating a Property Editor That Displays a List of Tags

❍ Creating a Custom Property Editor
● Creating a Customizer
● Registering a Property Editor with the BeanInfo Class
● Registering a Customizer with the BeanInfo Class
● Creating Instances of a Serialized JavaBean
❍ Serializing a JavaBean in the UI Editor
❍ Generating the Beans.instantiate() Method

❍ Ways to Instantiate the Serialized JavaBean
■ Instantiating a Serialized JavaBean Using the Class Name
■ Instantiating a Serialized JavaBean Using a Custom Filename
● Ways to Create a Pluggable Java Component

❍ Creating a PJC from an Existing Oracle Forms Control
❍ Creating a PJC from Scratch
10-2
A JavaBean, or simply a bean, is a reusable software component used as a building block to
create Java applets and applications.
For details about the JavaBeans component model and the URL to download the specification
from Sun Microsystems, see About JavaBeans. For detailed information, and working code, on
developing JavaBeans in JDeveloper, see the section titled "Advanced JavaBeans and
JDeveloper" on the Oracle OTN site at http://otn.oracle.com/products/jdev.
The topics in this book outline the general process you'll follow when Developing JavaBeans.

Creating a JavaBean Using the New Bean dialog to create a new empty bean, or to
extend an existing class to conform to the requirements of the
JavaBeans component model.
Creating and Modifying Fields Using the Using the Class Editor to define fields for the bean.
Class Editor
Creating and Modifying Methods Using the Using the Class Editor to define methods for the bean.
Class Editor
Creating and Modifying Events Using the Using the Class Editor to define events (source), which the bean
Class Editor will fire to all registered listeners (targets).
Creating and Modifying Property-Accessor Using the Class Editor to define accessor methods for the bean.
Methods Using the Class Editor
Ways to Create a BeanInfo Class Optional. Creating a BeanInfo class to provide JDeveloper with
explicit information about your JavaBean.
Ways to Customize a JavaBean Using a Customizing your bean by creating and refining the
BeanInfo Class metadata—including icons, exposed properties, and exposed
events—associated with it.
Ways to Create a Property Editor Optional. Creating a property editor to enable users to modify the
properties of your bean at design time. The property editor works
with JDeveloper's Property Inspector, allowing users to modify
properties individually.
Creating a Customizer Optional. Creating a customizer to enable users to modify the
properties of your bean at design time. The customizer allows
users to change multiple settings from a single interface.
Registering a Property Editor with the Required for property editors. JDeveloper will not recognize the
BeanInfo Class property editors you have created unless you first register them
with the BeanInfo class.
10-3
Registering a Customizer with the BeanInfo Required for customizers. JDeveloper will not recognize the
Class customizers you have created unless you first register them with
the BeanInfo class.
Related topics
About JavaBeans
About JavaBeans Properties
About JavaBeans Methods
About JavaBeans Events
About JavaBeans Event Sets
About Event Handling
About BeanInfo Classes

About Tuning Properties, Methods, and Events for a JavaBean
About Introspecting a JavaBean
About Property Editors
About Customizers
10-4
JavaBeans Concepts
You may find the following conceptual topics useful while working with JavaBeans in
JDeveloper:
● About JavaBeans Properties

● About JavaBeans Methods
● About JavaBeans Events
● About JavaBeans Event Sets
● About Event Handling
● About Property-Accessor Methods
● About BeanInfo Classes
● About Tuning Properties, Methods, and Events for a JavaBean
● About Introspecting a JavaBean
● About Property Editors
● About Customizers
Related topics
10-5
About JavaBeans
The JavaBeans architecture is a modern component architecture, designed for building
independent software components from which developers assemble larger application
components. With JavaBeans components, developers have complete freedom to assemble
components either by using traditional programming strategies or by using JDeveloper's
graphical tools.
For more information on JavaBeans, you can visit Sun's JavaBean specification at
http://www.javasoft.com/beans/docs/spec.html.
JDeveloper facilitates bean development by providing:
● A New Bean dialog to make creating beans easy

● A Class Editor that makes creating and modifying bean fields, methods, and events
easier
● Wizards to create property editors and customizers
Through the process of serialization (also known as component persistence), JDeveloper lets
users reuse instances of any JavaBean created during an editing session. For JavaBeans,
serialization provides a simple way to preserve the state of a bean from one session to another.
That is, the user of a bean who changes the values of several properties has only to serialize
that bean to ensure that the property changes are maintained. The next time she uses the
bean, she deserializes it to restore the bean to exactly the state she left it in.
For detailed information, and working code, on developing JavaBeans in JDeveloper, see the
section titled "Advanced JavaBeans and JDeveloper" on the Oracle OTN site at
http://otn.oracle.com/products/jdev.
Related topics
10-6
Properties allow the component user to change the state of a component. They enable the
value of a variable in the componet to be set or read, while keeping the internal implementation
hidden. By creating a property, the component writer can allow access to the state of the
component without exposing the underlying data structure.
Using properties in components has a number of advantages:
● Properties are available at design time
Properties take advantage of the full power of JDeveloper's UI Editor. The component
user can change the state of a component (by setting a property value) and immediately
see the effects of that change on the program. By default, all of a component's public
properties are available to other components, but you can control design-time access to
component properties by using the optional BeanInfo class to specify which properties
should be exposed.
● Properties hide specific implementation
You can include complex functionality in a property's accessor methods. Component

users need never know about the details: they only make the setProperty() or
getProperty() method call. A property that looks like a simple number can actually be
a lengthy calculation or a lookup in a database. Your component users don't have to deal
with that complexity.
● Properties allow a simple assignment to cause appropriate side-effects
You can have the accessor method notify other objects or call other methods whenever a
property is set or read. The accessor method can encapsulate all kinds of complex
behavior for a component; all the component user needs to know is how to make a
method call.
It is recommended that properties have appropriately named accessor methods defined in the
component. The component need not have a class data member (or field) associated with it, as
sometimes there isn't a one-to-one relation between a component class data member and a
given component property. For example, the following code fragment defines a component
property called shadowColor:
10-7
public class MyComponent extends Panel {
private int redValue;
private int greenValue;
private int blueValue;
public int getShadowColor() {

return redValue | greenValue | blueValue;
}
public void setShadowColor(int color) {

redValue = color & 0xff0000; // class data members
greenValue = color & 0x00FF00;
blueValue = color & 0x0000FF;
}
}
Although MyComponent has no actual class data member named shadowColor, the property
is correctly defined because of the two accessor methods, getShadowColor() and
setShadowColor(). These methods write and read three variables and calculate a value for
the property. Although it is common for a component property to set a variable with the same
name as the property itself, it is not required. To be valid, the component property must merely
have correctly declared property accessor methods.
Related topics
Tuning Properties and Methods for a JavaBean
About JavaBeans
10-8
JavaBeans methods encapsulate the behavior of the component. They are standard Java
methods which can be called from other components. Component methods are available at
runtime only.
There are few restrictions on what component methods can do, but you should make every
effort to ensure that your methods are as intuitive as possible:
● Name your methods so that the purpose of the method is obvious. Remember, too, that
methods are actions.
If you find yourself creating many methods that have no verbs in their names, consider
creating properties instead.
● Choose the shortest descriptive name.
However, avoid abbreviating method names.
● Avoid preconditions on method use.
If you must have preconditions on a method call, build in tests to validate that conditions
are met and provide exception handling for situations where a method call is
inappropriate.
Related topics
Creating and Modifying Methods Using the Class Editor
About JavaBeans
10-9
Events allow components to receive input and feedback from the user at runtime. When an
application runs, actions initiated by the user (mouse clicks, key presses, windows opening and
closing, to name a few) can potentially change how the application behaves. An event is the
link between these occurrences and the user's code that tells the application how to respond.
The JavaBeans component model defines how to:
● Create methods and interfaces so that JDeveloper can recognize component events
● Display those events within the JDeveloper's environment
● Allow the component user to select which events the component will respond to
Components are affected by events in two ways:
● Components can generate or fire events.
A component that generates events is a source component. When a user clicks a button,
for example, the button must generate an event that notifies all other interested
components that it was clicked.
● Components can listen for and respond to events.
Again, suppose a user clicks a button. A component that can respond to such an event
waits (or listens) for the event that the button generates, and then responds to it by
performing some operation.
The component user writes the method that tells the application what to do when an event
occurs. The component writer writes the code that determines which event(s) each bean can
generate, and (occasionally) which bean can listen or respond to events.
Event source components have registration methods, which are similar in naming patterns to
the accessor methods of properties. If a component's code complies with JavaBean rules,
JDeveloper recognizes the component's events and displays them on the Events page of the
Class Editor.
Standard Java events are grouped on listener interfaces (and, in some cases, on source
interfaces). These are the standard AWT event sets and their events:
10-10
● Action events
❍ actionPerformed
● Adjustment events
❍ adjustmentValueChanged
● Component events
❍ componentHidden
❍ componentMoved
❍ componentResized
❍ componentShown
● Container events
❍ componentAdded
❍ componentRemoved
● Focus events
❍ focusGained
❍ focusLost
● Item events
❍ itemStateChanged
● Key events
❍ keyPressed
❍ keyReleased
❍ keyTyped
● Mouse events
❍ mouseClicked
❍ mouseEntered
❍ mouseExited
❍ mousePressed
❍ mouseReleased
● Mouse motion events

❍ mouseDragged
❍ mouseMoved
10-11
● Text events
❍ textValueChanged
● Window events
❍ windowClosed
❍ windowClosing
❍ windowDeiconified
❍ windowIconified
❍ windowOpened
Related topics
Creating and Modifying Events Using the Class Editor
Tuning Events for a JavaBean
About JavaBeans
10-12
An event set defines a type of event, what it communicates, and what is required to generate
and to listen to the event. An event set consists of:
● The event-listener interface
The interface defines one or more methods that must be implemented by a class that
wishes to receive an event of this type. The methods typically take one or more
parameters: the event object.
● An event object
An event object is actually passed from the source to the listener. It contains all the
necessary parameters that a listener may be interested in, including the origin of the
event source. All events derive from java.util.EventObject.
● The event-registration methods (add<Event>Listener and

remove<Event>Listener methods) permit the component to manage all the
components that register interest in this particular event.
These methods take a single parameter: the object that is interested in listening for the
event. By definition the object must implement the <Event>Listener interface.
The java.awt package provides several predefined event sets, such as focus events, mouse
events, mouse move events, key events, and so on. These event sets include both the
<Event>Listener interfaces and the event objects.
For example, consider the key events. The key events set includes the KeyListener interface
(which defines the keyPressed(), keyReleased(), and keyTyped() methods), and the
KeyEvent class. Any component that generates key events must define the
addKeyListener() and removeKeyListener() registration methods.
In the key events example, note the naming pattern convention: the event name Key appears in
the listener interface, its methods (optional), the event object, and the registration methods.
Use this same naming pattern for all the event sets you create.
Usually the predefined event sets such as the key events set are sufficient for your
10-13
programming needs. However, you can create your own event sets if you choose.
If you want a component to generate events, you must define the event set, the event object,
and the event-registration methods so that other components that register interest in the event
can be notified of the event firing.
About Event-listener Interfaces
Standard JavaBeans events are grouped into a series of Java interfaces: you can identify them
by the word Listener as part of the source filename (for example, KeyListener.java). All of
them extend java.util.EventListener. Java defines the event listeners as interfaces so
that you can implement your responses to these events. Here is some of the code from the
KeyListener.java source file:
public interface KeyListener extends EventListener

{
void keyTyped(KeyEvent e); // a key is pressed and released
void keyPressed(KeyEvent e); // a key is pressed
void keyReleased(KeyEvent e); // a key is released
// end of code example
The KeyListener interface defines all of the types of keyboard events for which Java
components can listen. Each specific type of key event has a separate method within the
interface. For example, there is a keyPressed() method for a key press event, and a
keyReleased() method for a key-release event.
Related topics
About JavaBeans
10-14
There are usually at least three pieces of code involved in an event transaction. This discussion
refers to them as A (the event source), B (the event listener), and C (the container or other
code where everything is bound together):
● A is the event-source component.
The source component generates the event. It must provide the event-registration
methods (add<Event>Listener and remove<Event>Listener methods) that other
components can use to be notified of this event.
● B is the event-listening component.
This is the component that implements the event-listener interface and is registered
using the add-listener call on A. Theoretically, this could be any component that
implements the event-listener interface, but usually it is a private, anonymous class that
is written specifically to handle certain events in a particular program.
● C is the code that ties all this together.
Within the code, A and B are instantiated, and the add<Event>Listener method is
called.
Specifically, in JDeveloper:
● A can be any component that generates events. For example, many of the components
on JDeveloper's Component Palette generate events.
● B is an action adapter class, implementing the event listener.
The JDeveloper UI Editor generates the action adapter class automatically and places it
in the same .java file in which C is defined. JDeveloper generates the action adapter to
receive and route the event. It delegates the event handling to a target event-handling
method implemented in C. It is in the event-handling method that the user writes code to
respond to the event. The user doesn't generally do anything with the action adapter.
● C is the class under design in JDeveloper, usually a java.awt.Container

descendant.
10-15
JDeveloper does not make container C directly implement the event-listener interface,
and register itself (instead of the action adapter) as the event listener. Instead,
JDeveloper relies on the action-adapter approach to avoid confusion when more than
one component could generate a particular event. Otherwise, the event handler would
need to determine which component generated the event before it could handle the
event properly. Using the action-adapter approach, each adapter, and therefore, each
event-handling method, represents a single source-listener pair.
How Component End Users View Events
When using the UI Editor, the end user sees an event primarily as the event-handling method
that must be implemented in the class that contains the component. For example, suppose the
end user places a button named button1 into a container called Frame1, and wants something
to happen when button1 is pressed. This sequence of actions needs to occur:
1. The end user selects button1 in the Frame1 editor.

2. The user goes to the Event page of the Property Inspector, and clicks to the right of
actionPerformed. (actionPerformed is the event generated when a button is
pressed).
3. This action creates a default action-listener name, which you may edit. Double-click the
name to direct JDeveloper to create the appropriate method and take you to the method
body.
4. JDeveloper switches to the Frame1 source view and inserts an event-handling method
into Frame1 that is called when that event occurs. The method is called
button1_actionPerformed() by default, and the body of the method is initially
empty.
5. Finally, the end user adds code into the method to respond to the button press.
Behind the scenes, JDeveloper also generates additional code in the Frame1.java file to
handle the other aspects of event listening:
1. It generates an anonymous inner class for the action adapter that implements the
ActionListener interface.
2. Instantiates the class in Frame1.
3. Registers itself as a listener for the button1 event by calling
button1.addActionListener().
10-16
All of this code is visible in the source, but the developer's primary task is to fill in the event-
handling method that the action adapter calls when the event occurs.
The particular type of inner-class event adapters that JDeveloper generates by default are
known as anonymous adapters. This style of adapter avoids the creation of a separate (named)
adapter class. The resulting code is compact and elegant.
You can control how JDeveloper generates the adapter class by selecting the desired option from
the Code Style page of the Project Properties dialog. See Using Standard Adapter Classes for
details.
For example, here is code that is generated for an action-performed event using an anonymous
adapter:
button1.addActionListener(new java.awt.event.ActionAdapter() {
public void actionPerformed(ActionEvent e) {
button1_actionPerformed(e);
}
});
void button1_actionPerformed(ActionEvent e) {
// your code to respond to event goes here
}
The end user sees all of the potential events from button1 listed on the Events page of the
Property Inspector. As the component writer, you are responsible for creating the component
class in such a way that all the events it generates will appear in the Property Inspector. All the
end user must do to use your bean is write the code that fills in the event-handling method.
An advanced user could hook up events in other ways. For example, if component src is an
event source and component lstnr is an event listener, and class init is where src and lstnr
are instantiated, the user could put code that calls src.addListener(b) into the init class.
The default mechanism in JDeveloper:
1. Creates an anonymous inner class for the adapter to serve as listener component.
2. Makes the container class the site where the objects are instantiated and the event-
listener registration and event handling are performed
In this simplified model, the components that the user selects from the Component Palette do
not need to be event listeners, only event sources.
10-17
Using Standard Adapter Classes
JDeveloper can also generate standard class event adapters, instead of inner classes.
The standard event adapters have only public- and package-level access, unlike anonymous
adapters that have access to all variables in scope where it is declared.
For example, here is code that is generated for an action-performed event using a standard
class:
// Registers the adapter as a listener to button1.

button1.addActionListener(new Frame1_button1_actionAdapter(this));
...
// Adapter class definition.

class Frame1_button1_actionAdapter extends java.awt.event.ActionAdapter {
Frame 1 adaptee;
Frame1_button1_actionAdapter(Frame1 adaptee) {
this.adaptee = adaptee;
}
public void actionPerformed(ActionEvent e) {
adaptee.button1_actionPerformed(e);
}
}
void button1_actionPerformed(ActionEvent e) {
// code to respond to event goes here
}
Compare this code with the previous code sample shown above. JDeveloper generated that
code using an anonymous inner class. Both ways of using adapters provide the code to handle
action-performed events, but the anonymous adapter approach is more compact.
To make standard adapters the default for your projects:

2. Select the Code Style node.
3. On the Code Style page, select Standard adapter as an event-handling option.
4. Choose OK.
10-18
Now JDeveloper will generate standard adapters (as opposed to anonymous, inner classes) for
its events.
How Component Writers View Events
When you develop a bean, you must think of all the events that the bean should be able to
generate.
To make a component capable of firing events:
1. Determine what kind of event needs to be fired, and either:
Select an appropriate existing event set from the AWT or JFC.
or
Create a new event set.
2. Create event registration methods for the component.

3. Create an event notification/propagation mechanism for the event:
fire<yourEventName>Event()
4. Call the event is fired and call the event notification mechanism from the key points in
your bean where such an event should be sent.
Related topics
About JavaBeans
10-19
About Property-Accessor Methods
To the outside world, bean properties are defined entirely by the presence or absence of
accessor methods. The JavaBeans architecture relies on these public methods when explicit
BeanInfo is not specified. The "getter" and "setter" methods you specify for your bean provide
the necessary description of the bean's properties and methods. For example, your bean's
BeanInfo (when available) relies on the bean's accessors to update the Property Inspector,
which you can use to view and edit property values. Whether the property is editable or not
depends on your choice of accessor methods.
You can have these combinations of get and set accessor methods:
● To make a read-only property, create a getter only.

● To make a write-only property, create a setter only.
● To make a read-write property, create both a getter and setter.
Your property must have both a get and a set accessor method in order for the Property
Inspector in JDeveloper to display it. A read-only or a write-only property will not appear in the
Property Inspector.
You can create get and set methods manually or you can use the Fields or Methods page of the
Class Editor. Either way, the read-write properties will appear in the Property Inspector at design
time.
Related topics
Creating and Modifying Property-Accessor Methods Using the Class Editor
About JavaBeans
10-20
When you create a bean and install it on the Component Palette, in most cases you will want its
properties and events to appear in JDeveloper's Inspector. If you followed the JavaBeans
design and naming conventions while creating your bean, all the properties and events you
defined, plus all those inherited from superclasses, appear automatically.
But what if you didn't use the JavaBeans design and naming conventions, or if you have
existing classes that don't use them? And what if you don't want to give the user of your bean
access to every property at design time?
To handle these situations, you can create a BeanInfo class that will provide explicit information
about a bean to JDeveloper, rather than having JDeveloper derive the information through
automatic introspection. You create this class by extending the SimpleBeanInfo class.
Related topics
Ways to Create a BeanInfo Class
Ways to Customize a JavaBean Using a BeanInfo Class
Registering a Property Editor with the BeanInfo Class
Registering a Customizer with the BeanInfo Class
About JavaBeans
10-21
About Tuning Properties, Methods, and Events for a
JavaBean
You may find some properties and methods that you don't want your bean's user to access at
design time. Introspection, for example, would expose properties like background, foreground,
font, and name that you may wish to remain unexposed. You may also find this to be the case
for some events, although this is less likely. Use a class that implements BeanInfo to provide
an explicit description of these features of your bean:
● A set of properties
● A set of methods that other objects can invoke on it
● A set of events it generates
There are two ways to specify which of these features should not appear in JDeveloper's
Property Inspector or, conversely, which should be available at design time to other visual
tools. Which technique you choose depends on whether the property, method, or event follows
the JavaBeans design and naming conventions or not.
Related topics
About JavaBeans
10-22
You use the BeanInfo editors for your BeanInfo class to expose or hide specific properties,
methods, and event sets of the associated bean. You can also choose to defer to the default
behavior when you want to rely instead on Java's runtime automated bean introspection. In this
case, introspection will examine the bean itself to expose these properties, methods, and event
sets for use by the IDE at design time:
● All properties (including read-only, write-only, and read-write)

● All public methods
● All event sets with a matching add-event and remove-event listener method pair
The BeanInfo editors support this choice through the Defer to Introspection checkbox. Selecting
and deselecting this option causes the appropriate changes to your BeanInfo class's code. This
feature is particularly useful when you want to toggle off a portion of the BeanInfo description
without losing the existing property, method, or event set settings in the editors.
Deferring to introspection of your bean can cause side effects for its descendants. In this case,
descendants will inherit the introspected properties and methods rather than those defined by the
BeanInfo class.
Related topics
Introspecting a JavaBean
About JavaBeans
10-23
A property editor is an editor for changing property values at design time. You can see several
different types of property editors in JDeveloper's Inspector. Within the Inspector, for some
properties all you need do to change the value is type in that new value. This is the simplest
form of property editor. For other properties within the Inspector, you use a choice menu in the
form of a dropdown list to display all the possible values, and then select the value you want
from that list. Some properties have still more complex editors: the property editors for colors
and fonts, for example, are actually dialog boxes you can use to set their values.
Property editors work well for simple- to medium-sized beans. If your bean is more complex,
you should consider using a customizer instead.
Related topics
Ways to Create a Property Editor
About JavaBeans
About Customizers
10-24
About Customizers
The property editors that you develop for your component can edit a single property at a time.
Customizers go a step further. A customizer can be simple or complex. That is, it can either:
● Edit the entire component at once. Usually a simple customizer presents a dialog box or
panel that lets the user set many properties in the same step.
or
● Provide an interactive interface to the component user, guiding the user through the
steps to customize the component.
For a complex customizer, you might create a wizard that questions the user about how the
component should be customized. Based on the user's responses, the customizer edits all
affected properties of the component. Whenever a customizer generates an event informing
JDeveloper that something happened, JDeveloper generates the appropriate code.
Related topics
Creating a Customizer
About JavaBeans
10-25
About Serializing a JavaBean
Serializing an object is the process of turning its state into a sequence of bytes that is neither a
.java nor a .class file. The sequence of bytes can be saved as a file on a disk or sent over
a network. When a request is made to restore an object, either from a file or on the other end of
a network connection, the sequence of bytes is deserialized into its original structure.
For JavaBeans, serialization provides a simple way to preserve the state of a bean from one
session to another. This is also called component persistence. That is, suppose the user of a
bean changes the values of several properties during one session. If bean is serialized to a file
and then deserialized the next time it is used, the bean is restored to exactly the state the user
left it in.
For example, you might want to create a java.awt.Button on a Frame and set the
background of that button to blue. To reuse the blue button, you would serialize the blue button
instance to java.awt.Button.ser so that it appears in your classpath. After that, all buttons
you create would appear blue since JDeveloper will find the .ser version on your classpath
first.
Related topics
Creating Instances of a Serialized JavaBean
About JavaBeans
10-26
Creating a JavaBean
The first step in developing a bean for reuse is to create the JavaBean class. Using the New
Bean dialog, you can either create a new empty bean or extend an existing class to conform to
the requirements of the JavaBeans component model.
To create a JavaBean:
1. In the Navigator, select the project to which the bean will be added.
2. From the menu, choose File | New.
3. In the New Gallery, select the Beans category.
4. Double-click the Bean icon to open the New Bean dialog.
5. To create a new JavaBean class, accept the defaults.
6. To extend an existing class, use the Browse button to navigate to the appropriate
package and superclass.
7. Click OK.
Related topics
Creating and Modifying Fields Using the Class Editor
About JavaBeans
10-27
Creating and Modifying Fields Using the Class
Editor
When creating a bean for reuse, you will want to define its fields. The easiest way is to do so
from within the Class Editor.
To create or modify JavaBean fields using the Class Editor:
1. In the Navigator, select the bean, right-click, and choose Class Editor.
2. In the Class Editor, select the Fields tab.
3. To create a new field, click Add.
4. To modify an existing field, select it and either double-click the row or click Edit to open
the Edit Fields dialog.
5. In the Edit Fields dialog, enter the settings for your field.
For more information on individual settings, click Help.
6. Click OK.
Related topics
Creating a JavaBean
About JavaBeans
10-28
Creating and Modifying Methods Using the Class
Editor
When creating a bean for reuse, you will want to define its methods. The easiest way is to do
so from within the Class Editor.
To create or modify JavaBean methods using the Class Editor:
2. In the Class Editor, select the Methods tab.
3. To create a new method, click Add.
4. To modify an existing method, select it and either double-click the row or click Edit to
open the Edit Methods dialog.
5. In the Edit Methods dialog, enter the information for your methods, including the method
name, its type, and any parameters or throws that the method will use.
For additional information on individual selections, click Help.
6. Click OK.
Related topics
Creating a JavaBean
About JavaBeans
10-29
Creating and Modifying Events Using the Class
Editor
When creating a bean for reuse, you will need to define its events. The easiest way is to do so
from within the Class Editor.
When defining events, you create a new event set and its associated listener interface. The
bean will then be able to fire these events (source) to all registered listeners (targets).
To create or modify JavaBean events using the Class Editor:
2. In the Class Editor, select the Events tab.
3. Select which types of events to fire or listen for.
You can also create custom events or import events sets using the Class Editor.
Related topics
Creating a JavaBean
About JavaBeans
10-30
Creating and Modifying Property-Accessor Methods
Using the Class Editor
When creating a bean for reuse, you will want to define its accessor methods. The easiest way
is to do so from within the Class Editor.
To create or modify JavaBean accessor methods using the Class Editor:
2. In the Class Editor, select the Fields tab.
3. To create a new accessor method, click Add.
4. To modify an existing accessor method, select the field and either double-click the row or
click Edit to open the Edit Fields dialog.
5. In the Edit Fields dialog, select Regenerate Accessors to either add new accessor
methods or overwrite your class's existing getter and setter methods for reading and
writing field values.
For more details on this and subsequent selections, click Help.
6. Deselect get() or set() only when you want to remove a getter or setter previously
generated in the Settings dialog for the field.
If you deselect either get() or set(), the editor will remove the getter or setter implementation
from your class without adding a replacement accessor for the deselect option. Deselect
these options only when you want to delete a particular accessor method from your class
definition.
7. Select get() or set() to add a new getter or setter to your class (where none already
exists) or to overwrite an existing getter or setter (where one does exist).
Note that when the original accessor method does not follow the JavaBeans convention,
it cannot be overwritten.
8. Click OK.
10-31
Related topics
Creating a JavaBean
About JavaBeans
10-32
Selecting an Event-Handling Adaptor
When creating a bean for reuse, you will want to define its events. Once you have defined its
events, you will want to select an event-handling adaptor.
To make standard adapters the default for your projects:

2. Select the Code Style node.
3. On the Code Style page, select Standard Adapter as an event-handling option.
4. Click OK.
Now JDeveloper will generate standard adapters (as opposed to anonymous, inner classes) it
generates for events.
Related topics
Creating a JavaBean
10-33
By creating a class that extends BeanInfo, you provide explicit information about your
JavaBeans component to JDeveloper. Creating a BeanInfo class is optional.
You can create your BeanInfo class in one of two ways:
● Creating a BeanInfo class using the Class Editor

● Creating a BeanInfo class using the New BeanInfo dialog
Related topics
Creating a JavaBean
10-34
Creating a BeanInfo Class Using the Class Editor
Use the Class Editor when you want to create a BeanInfo class that implements the standard
BeanInfo interface. If you want to create a custom BeanInfo interface, or if the bean for which
you want BeanInfo is not a part of your project (and so not available to be opened in the Class
Editor), see Creating a BeanInfo Class Using the New BeanInfo Dialog.
To create a BeanInfo Class Using the Class Editor:
1. In the Navigator, select the bean, right-click and choose Class Editor.
2. In the Class Editor, select the General tab to display the General page.
3. Click Generate BeanInfo.
Related topics

Creating a BeanInfo Class Using the New BeanInfo Dialog
10-35
Creating a BeanInfo Class Using the New BeanInfo
Dialog
Use the New BeanInfo dialog when you want to create a BeanInfo class that implements a
custom BeanInfo interface, or when the bean is not a part of your project and so not available
to opened in the Class Editor. If you want to create a standard BeanInfo class, see Creating a
BeanInfo Class Using the Class Editor. You may want to do this, for instance, when your
company supplies its own standard interface for this purpose.
To create a BeanInfo class using the BeanInfo dialog:
1. Choose File | New and select the Beans tab in the New Gallery.
2. Double-click the BeanInfo icon.
3. In the New BeanInfo dialog, choose the bean for which you want to create a BeanInfo.
The dialog generates the BeanInfo class name from the bean itself.
4. Accept the name of the package, or specify a different package to which the BeanInfo
should be added.
5. Click Browse to choose a base class, other than SimpleBeanInfo, for the BeanInfo
that you want to implement.
6. Click OK to add the new BeanInfo class to your project.
Related topics

Creating a BeanInfo Class Using the Class Editor
10-36
Ways to Customize a JavaBean Using a BeanInfo
Class
After you have created a BeanInfo class, you can use it to customize a JavaBean in any of the
following ways:
● Tuning properties and methods for a JavaBean

● Tuning events for a JavaBean
● Specifying a default property or event for a JavaBean
● Introspecting a JavaBean
Related topics
Creating a JavaBean
About JavaBeans
10-37
For every BeanInfo class you create, you can decide which properties and methods will display
for the JavaBean in JDeveloper's Inspector, and which will not.
When you expose one or more properties, methods, or events from your BeanInfo, you force the
IDE to rely on your BeanInfo for information describing the properties, methods, or events. This
means that as soon as you select any property, method, or event, all other properties, methods, and
events that you do not select will not be exposed for the class.
To tune properties or methods for a class that is a standard JavaBean:
1. Create a BeanInfo class for your bean.

2. Open the BeanInfo class file for your bean in the Class Editor.
3. Select the Properties or Methods tab to view the list of declared properties or methods.
4. To make your property visible through BeanInfo, select the Properties tab and select the
get() and set() checkboxes for that property.
The combination of these checkboxes you select for a property should reflect the
property's read-write access. For example, select only set in the case of a write-only
property. You need only select get in the case of read-only property.
You must select both get and set to expose a property through your BeanInfo class so
that it appears in the Property Inspector. The Inspector displays only the read-write
properties.
5. To hide your property so it is not visible through BeanInfo, deselect both the get() and
set() checkboxes for that property.
If you do not select any property checkboxes, the editor removes the property-descriptor
method from the BeanInfo class definition. In this case, the IDE will rely on Java
introspection and you will expose all properties.
6. To explicitly expose a method that your bean defines, select the Methods page and click
Expose for the desired method. If you do not want to make the method available,
deselect the method's Expose checkbox.
If you do not select any method checkboxes, the editor removes the method-descriptor
method from the BeanInfo class definition. In this case, the IDE will rely on Java
10-38
introspection and you will expose all methods.
For properties and methods you expose, JDeveloper implements the

getProperDescriptors() and getMethodDescriptors() methods, including code to
instantiate an array of descriptor objects containing information on each property and method
you want to be available at design time. Those properties and methods you did not select in the
editors are omitted from the code and will not appear in the Property Inspector of your IDE.
If you wish to expose a property or method via BeanInfo, but would still prefer that it not be
shown in a Property Inspector, you may be able to use the setHidden() method to hide the
property or method. In order for this technique to work, your IDE must recognize the hidden
setting. Not all IDEs, including JDeveloper, obey the hidden setting. Thus, properties and
methods flagged as hidden may still be displayed to the user.
To tune properties or methods for a class that does not follow the JavaBean naming patterns:
For properties or methods that do not follow the JavaBeans naming conventions, you must
hand-modify the code for each of getPropertyDescriptors() and
getMethodDescriptors() as needed.
Related topics

Specifying a Defualt Property or Event for a JavaBean
About JavaBeans
About Tuning Properties, Methods, and Events
10-39
For every BeanInfo class you create, you can decide which events will display for a JavaBean
in JDeveloper's Inspector, and which will not.
When you expose one or more properties, methods, or events, you force the IDE to rely on the
generated BeanInfo. This means that as soon as you select any property, method, or event, all other
properties, methods, and events that you do not select will not be exposed from the class.
To tune events for a JavaBean:

2. Open the BeanInfo class file for your bean in the Class Editor.
3. Select the Events tab to view the list of event sets.
4. Select the event sets that you want your bean to be able to fire.
5. Click OK.
For event sets that you want your BeanInfo to fire, JDeveloper implements the
getEventSetDescriptors() method, including code to instantiate an array of
EventSetDescriptor objects containing information on each event set you want to be
available at design time. Those event sets you do not expose are omitted and will not appear in
the Property Inspector of your IDE.
Related topics

Specifying a Default Property or Event for a JavaBean
About JavaBeans
10-40
10-41
Specifying a Default Property or Event for a
JavaBean
Using a BeanInfo class, you can specify a default property or default event for your JavaBean
component. If you don't specify a default property or event, the tool will default to an arbitrary
property or event in its Property Inspector. If you modify BeanInfo to specify a property or event
as the default, however, the tool may highlight the property or event when an instance of your
bean is first loaded.
To specify the defaults when the user is most likely to want to edit that value, add these lines of
code to the BeanInfo class for your bean:
public int getDefaultPropertyIndex() {

return <value>;
}
public int getDefaultEventIndex() {

return <value>;
}
Specify the position of the defaults in the sets described in the result of the
getPropertyDescriptors() and getEventDescriptors() methods.
To indicate that no property or event is to be the default, specify a value of -1. Not all tools respond
to these settings.
Related topics

About JavaBeans
10-42
Introspecting a JavaBean
If you create a BeanInfo class, JDeveloper lets you use it to define your bean's external
interface for properties and methods. You can also choose to expose the properties, methods,
or events using Java's automated introspection.
Deferring to introspection of your bean can cause side effects for its descendants. In this case,
descendants will inherit the introspected properties and methods rather than those defined by the
BeanInfo class.
To introspect a JavaBean:

2. Open the BeanInfo class for your bean in the Class Editor.
3. Select the Properties tab to view the list of properties your BeanInfo exposes through get
and set methods.
For more information on this or subsequent steps, click Help.
4. Optionally, to use the default behavior for all properties, click Defer to Introspection.
5. Select the Methods tab to view the list of methods your BeanInfo exposes.
6. Optionally, to use the default behavior for all methods, click Defer to Introspection.
7. Select the Events tab to view the list of methods your BeanInfo exposes.
8. Optionally, to use the default behavior for all events, click Defer to Introspection.
9. Display the BeanInfo class in the Code Editor to view the changes to the property- and
method-descriptor methods.
JDeveloper modifies the return value of the descriptor for the part of the bean you choose to
introspect. Instead of instantiating an array of Descriptor objects containing information on each
property, method, or event set, the getPropertyDescriptor(),
getMethodDescriptor(), getEventSetDescriptor() methods simply return null. The
IDE checks the return value—if null is returned in the BeanInfo descriptor methods, it signals
the IDE to use introspection.
Related topics
10-43
10-44
JDeveloper provides a text field property editor automatically. In addition, you can create three
types of property editors:
● A property editor that displays a list of source code values

● A property editor that displays a list of tags
● A custom property editor
Related topics
Creating a JavaBean
About JavaBeans
10-45
Creating a Property Editor That Displays a List of
Source Code Values
Other than a property editor that simply uses a text input field, the simplest kind of property
editor allows the user to choose from a dropdown list of strings, each of which is an actual
value that can appear in the source code.
To create a property editor that selects from possible source code values:
2. Double-click the Property Editor icon to open the Property Editor dialog.
3. In the Editor name field, enter the class name for the editor.
4. From the Editor type dropdown list, select String List.
5. Click Add.
6. Replace the default value with the value for your String.
This value should be a possible string value for the property. It will also appear in the
dropdown list.
7. Repeat steps 5 and 6 for each possible value for the property.
8. Click OK to create the property editor.
Related topics

Creating a Property Editor that Displays a List of Tags
Creating a Custom Property Editor

10-46
Creating a Property Editor That Displays a List of
Tags
You may want to create a property editor that allows users to select from a dropdown list but
not want that dropdown list to contain the actual possible values of the property. The property
may not be a string at all, or you may wish to define more intuitive strings for the dropdown list.
To create a property editor that selects from strings you define:
4. If the property is a String, select String Tag List. If it is an int, select Integer Tag List.
5. Click Add.
6. In the Resource string field, enter a string that will be displayed in the dropdown list.
7. If the property is a String, in the Java initialization string field, enter the quoted value
corresponding to the resource string.
8. If the property is an int:
a. In the Integer value field, enter the value corresponding to the resource string.
2. In the Java initialization string field, enter Integer(i).intValue(), where i is
the value corresponding to the resource string.
9. Repeat steps 5 through 8 for each possible value for the property.
Related topics

Creating a Property Editor that Displays a List of Source Code Values

10-47
You should create a custom property editor when a text field or dropdown list won't suffice, or
when you need a more complicated dropdown list, such as one that displays colors.
To create a custom property editor:
4. From the Editor type dropdown list, select Custom Editor Component.
5. In the Custom editor name field, enter a name for the component that will implement the
custom editor.
6. If you want the editor to be able to refresh itself, select Support paintValue().
You should support paintValue() if the editor will display a graphical representation of
the property's value (such as a color) or if you want changes to the value to be reflected
in other values displayed in the editor. You should not support paintValue() if you
need to support the display and editing of the property's value as text.
8. Modify the component's source code to implement your property editor.
9. If you selected Support paintValue(), make sure you complete the paintValue()
method stub to paint the representation of the property value in the editor.
Related topics

Creating a Property Editor that Displays a List of Source Code Values
Creating a Property Editor that Displays a List of Tags

10-48
For complex beans, you should consider creating a customizer, rather than a property editor.
To create a customizer:
2. Double-click the Customizer icon. This starts the New Customizer dialog.
3. Enter the name of the customizer in the Name field.
4. If you want to add the customizer to a package other than the default package of your
project, enter the package name in the Package field or click Browse.
5. If you want to have the customizer extend a class other than the default, enter the class
name in the Extends field or click Browse.
6. Click OK to add the new customizer class to your project.
Related topics
Creating a JavaBean
About JavaBeans
About Customizers
10-49
Registering a Property Editor with the BeanInfo
Class
If you decide to create property editors, you must list them within the BeanInfo class in order for
the IDE to recognize them. This process is known as registering.
To register a property editor with the BeanInfo class:
1. In the Navigator, select the BeanInfo class for your bean, right-click, and choose Class
Editor.
2. Select the Properties tab.
3. Select the property you want to specify the editor for and either double-click the row or
click Edit to open the Edit Properties dialog.
4. In the Edit Properties dialog, select the property editor from the list in the Hints pane.
5. Click OK to save your changes to the BeanInfo class.
Related topics
Creating a JavaBean
About JavaBeans
10-50
If you decide to create a customizer, you must list it within the BeanInfo class in order for the
IDE to recognize it. This process is known as registering.
To register a customizer with the BeanInfo class:
1. In the Navigator, select the BeanInfo class for your bean, right-click and choose Class
Editor.
2. Select the General tab.
3. Select the customizer from the Customizer Class list box.
4. If your customizer makes changes to the bean other than public property modifications
(bean.set<propname>), add this statement to the bean's BeanInfo class:
beanDescriptor.setValue("hidden-state", Boolean.True)
Related topics
Creating a JavaBean
About JavaBeans
About Customizers
10-51
When you want to preserve the state of a bean that you are editing for reuse between sessions,
you create a serialized instance of it.
To create instances of a serialized JavaBean:
1. Serialize the bean in the UI Editor to create a .ser file.

2. Generate the beans.instantiate() method for beans that you drop in the UI Editor.
3. Instantiate the serialized JavaBean using either:
❍ A .ser filename that is the same as the bean class name
or
❍ A custom .ser filename
Related topics
Creating a JavaBean
About JavaBeans
10-52
Serializing a JavaBean in the UI Editor
When creating instances of a serialized JavaBean, you must first serialize the bean to create a
.ser file.
JDeveloper lets you serialize a bean through the UI Editor. You can perform this procedure
while you are modifying a bean instance in JDeveloper to preserve its settings for use in other
applications. Serializing saves you from having to subclass the bean and initialize all the
property settings in its constructor or from requiring the applications to all make the same
property sets.
To serialize a bean instance:
1. Select the component you want to serialize in the UI Editor.

2. Right-click the component to display its context menu and choose Serialize.
3. In the serialization dialog, specify the name of the serialized component and the directory
to which you want the component saved.
The dialog suggests a filename, which is the name of the component with a .ser
extension. If you accept this default, all components of that name will be instantiated with
your serialized information. Specify a directory that is on your classpath.
4. Click OK to serialize the bean.
The component is serialized to a file with the name you specified and the .ser file extension.
The next time you instantiate that bean using beans.instantiate(), JDeveloper will read
the .ser file into memory.
Related topics

Generating the beans.instantiate() Method
Ways to Instantiate the Serialized JavaBean
About JavaBeans
10-53
When creating instances of a serialized JavaBean, after creating the .ser file you must
generate the beans.instantiate method. Using beans.instantiate() is preferable to
using the new keyword because beans.instantiate():
● Automatically loads any serialized version of the JavaBean (the name of the bean with a
.ser file extension)
● Performs additional housekeeping tasks that applets need
To customize JDeveloper so that the code it generates uses beans.instantiate():

2. Select the Code Style tab.
3. On the Code Style page, select Use Beans.instantiate.
4. Click OK.
Now whenever the bean is dropped on the UI Editor, JDeveloper generates code that uses the
beans.instantiate() method to instantiate your bean, instead of new.
beans.instantiate() can throw an exception, so that it gets generated within the jbInit()
method where exceptions are expected and handled. beans are still declared where they were
before, but their initializers appear inside jbInit().
Related topics

About JavaBeans
10-54
When creating instances of a serialized JavaBean, after you have created a .ser file and
customized JDeveloper to generate the beans.instantiate() method, you must instantiate
the serialized bean. You can drop a bean into the UI Editor and JDeveloper will instantiate that
bean using beans.instantiate().
In order for JDeveloper to read the .ser file into memory, you must either:
● Instantiate the bean using the <component>.class.getName() argument
or
● Instantiate the bean by substituting the package name and serial filename for the
<component>.class.getName() argument
This method enables you to instantiate both:
● Standard JavaBeans
● JavaBeans with your serialized format in the same project
Related topics

About JavaBeans
About Serializing JavaBeans
10-55
Instantiating a Serialized JavaBean Using the Class
Name
If you create a .ser file with the same name as the original component, you can instantiate the
bean using the <component>.class.getName() argument.
JDeveloper may not display the serialized instances in the UI Editor if you have already loaded the
object's original class. However, running and debugging your code will still work as expected.
For example, this is how the code appears using beans.instantiate() to instantiate a
serialized button bean whose class name and .ser filename are the same:
public class ButtonBoxFrame extends JFrame {

XYLayout xYLayout1;
Button button1;
Button button2;
Button button3;
public ButtonBoxFrame() {
try {
jbInit();
}
}
}
private void jbInit() throws Exception {

xYLayout1 = (XYLayout)
beans.instantiate(getClass().getClassLoader(),
XYLayout.class.getName());
button1 = (Button)beans.instantiate(getClass().getClassLoader(),
Button.class.getName());
button2 = (ButtonControl)
button3 = (ButtonControl)
...
}
10-56
Here is how the code could have appeared using the new keyword to instantiate an object:
public class ButtonBoxFrame extends JFrame {

XYLayout xYLayout1 = new XYLayout();
Button button1 = new Button;
public ButtonBoxFrame() {
try {
jbInit();
}
}
}
private void jbInit() throws Exception{
...
}
Related topics

Instantiating a Serialized JavaBean Using a Custom Filename
About JavaBeans
10-57
Instantiating a Serialized JavaBean Using a Custom
Filename
If you create a .ser file with a name other than that of the original component, you can
instantiate the bean by substituting the package name and serial filename for the
<component>.class.getName() argument.
JDeveloper may not display the serialized instances in the UI Editor if you have already loaded the
object's original class. However, running and debugging your code will still work as expected.
For example, if you serialized a button and named the .ser file MyDifferentName.ser in a
package named mypackage, you would instantiate the JavaBean using the command:
button1 = (Button) beans.instantiate(getClass().getClassLoader(),

"mypackage.MyDifferentName.ser");
Related topics

Instantiating a Serialized JavaBean Using the Class Name
About JavaBeans
10-58
Ways to Create a Pluggable Java Component
JDeveloper allows you to extend your current set of Oracle Forms controls with Pluggable Java
Components (PJCs).
You can do this in either of these ways:
● By subclassing an existing Oracle Forms control

● By creating a completely new control, based on the Java Swing classes, to be added to
the Oracle Forms palette
When you use JDeveloper to create a PJC from your custom control, JDeveloper preserves the
original business logic associated with the control.
Related topics
Creating a New PJC from Scratch

Creating a PJC from an Existing Oracle Forms Control
10-59
Creating a PJC from an Existing Oracle Forms
Control
You can create a PJC for your Oracle Forms application by extending an existing Oracle Forms
control. The easiest way to extend this class is with the PJC builder.
To create a PJC component from an existing control using the PJC builder:
1. In the Navigator, select a project.

3. In the New Gallery, select Beans in the Categories column and Oracle Forms Pluggable
Java Component in the Items column.
4. In the New Oracle Forms Pluggable Java Component dialog, name your PJC class.
5. Accept the name of the package or click Browse to specify a different package to which
the PJC should be added.
6. Select a default Oracle Forms control from the dropdown list or click Browse to specify a
nondefault control.
7. Click OK to add the new PJC class to your project.
Next, use the PJC Class Editor to add set and get handlers in the generated code to make the
properties accessible.
Related topics

Creating a New PJC from Scratch
10-60
Creating a PJC from Scratch
You can create a PJC from scratch for your Oracle Forms application by extending the
BeanWrapper class. The easiest way to extend this class is with the PJC builder.
To create a wrapped PJC component using the PJC builder:
1. In the Navigator, select a project.

3. In the New Gallery, select Beans in the Categories column and Oracle Forms Pluggable
Java Component in the Items column.
4. In the New Oracle Forms Pluggable Java Component dialog, name your PJC class.
5. Accept the name of the package or click Browse to specify a different package to which
the PJC should be added.
6. Accept the default BeanWrapper or click Browse to choose a base class for the PJC that
you want to create.
Extending BeanWrapper enables you to expose a Swing class to Oracle Forms.
7. If you accepted the default BeanWrapper, you must now select the Swing control to be
wrapped. Choose the control from the dropdown list or click Browse to select another.
8. Click OK to add the new PJC class to your project.
Next, use the Class Editor to add set and get handlers for making the properties accessible in
the generated code.
Related topics

Creating a PJC from an Existing Oracle Forms Control
10-61
Developing Business Components
● Developing Business Components
❍ What's New in Business Components for Java
■ About Synchronizing the Database and Business Logic Tier
■ Synchronizing the Database and Business Logic Tier with the

Synchronization Tool
■ Using an Entity Attribute as a Database Sequence
■ Implementing Cascade Delete Behavior
■ Specifying Entity Attribute Settings
■ Specifying View Attribute Settings
■ Adding and Editing a Validation Rule
■ Tuning Entity Object Performance with the JDBC Update Batching
API
■ Tuning View Object Performance by Adjusting the Row Fetch Size,
Providing Query Hints, and Specifying Page Iteration Mode
■ About Polymorphic Row Sets
■ Selecting Entity Objects to Implement Polymorphic Row Sets
■ Selecting View Objects to Implement Polymorphic Row Sets
■ Creating a View Object Based on a Static Set of Values
■ Implementing Row Set Filters
■ Finding an Application Module Instance in Code
■ About Application Module Pooling
■ Pooling Application Modules
■ Enabling and Disabling Failover for Application Module
Instances
■ Enabling and Disabling Connection Pooling when Using
Application Module Pooling
■ Setting the Maximum Cookie Age for Application Module
Pooling
■ Setting the Pool Recycle Threshold
■ Setting the Initial Pool Size
■ Setting the Maximum Pool Size
11-1
■ Setting the Pool High Water Mark for Application Module
Instances
■ Managing Non-Transactional State for Application Module
Pooling
■ Implementing Pooling in Application Module Code
■ Implementing a Custom Application Module Pool
■ About Connection Pooling

■ Pooling Connections
■ Enabling and Disabling Connection Pooling
■ Setting the Initial Number of Pool Connections

■ Setting the Maximum Number of Pool Connections
■ Setting the Pool High Water Mark for Connections
■ Setting the Connection Pool Wait Timeout
■ Using a Custom Connection Pool Manager
■ About Pooling Classes

■ Implementing XML Messaging
■ About Intersection Tables
■ Creating a Many-to-Many Association
■ Ways to Create a Many-to-Many View Link
■ Creating a Many-to-Many View Link Based on an Association
■ Creating a Pure SQL Many-to-Many View Link
■ About Business Components Service Beans

■ About Container-Managed and Bean-Managed Transactions
■ Using Client-Demarcated Transactions
■ Using LOBs as Java Streams
■ Customizing Error Messages
■ Using Bundled Exceptions
■ Creating Default Business Components
■ Business Component Data Types
■ Understanding the n-Tiered Business Components Architecture
11-2
■ About Client Interfaces
■ About the Factory Pattern
■ About Business Components and Wire Protocols
■ How Does the Business Logic Tier Cache Data?

■ Understanding Business Components for Java from a Forms
Developer's Perspective
■ Understanding Deployment Configurations
■ About Debugging Multi-Tier Programs
■ What Is an Entity Object?
■ What Is an Association?
■ What Is an Entity Attribute?
■ About Validation Logic
■ Entity Object Row States
■ About Using Stored Procedures
■ What Is a View Object?
■ What Is a View Link?
■ What Is an Application Module?
■ How Clients and the Business Logic Tier Interact
■ About Custom Client Methods

■ Ways To Create a Client for Business Components

■ Creating a Hand-Coded Client for Business Components
■ Ways to Create and Find View Objects in Code

■ Finding a View Object in the Data Model
■ Finding a View Object Not in the Data Model

■ Creating a View Object from a Query Statement
■ Creating a View Object from Query Clauses
■ Calling Methods from Clients
11-3
■ Ways to Represent Oracle Object Types in Entity Objects
■ Representing an Oracle Object Type with a User-defined
Domain
■ Representing a VARRAY that Contains Oracle Object Types
■ Replacing an Oracle Object Type Column with a REF to a
Table of that Type
■ Running Business Components Samples
❍ Introducing Business Components for Java

■ What Are Business Components?
■ What Is the Business Components Framework?
■ Understanding the n-Tiered Business Components Architecture


■ About Business Components and Wire Protocols
■ How Does the Business Logic Tier Cache Data?

■ Understanding Business Components for Java from a Forms Developer's
Perspective
■ About Testing Business Components within JDeveloper
■ Understanding Deployment Configurations
■ About Debugging Multi-Tier Programs
■ About the Development Process
■ Stage 1: Use Cases
■ Stage 2: UML or Class Diagrams

■ Stage 3: Database Tables and Business Components
Implementation
■ Stage 4: Clients and Deployment
■ About Structuring the Development Team
■ Customizing the Business Components Framework
11-4
■ Converting a Legacy Application into a Business Components Application
❍ Working with Business Component Projects, Packages, and System Options

■ What Is a Business Component Project?
■ What Business Component Packages Are Imported?

■ About Structuring Business Component Projects and Packages
■ About Importing Business Components
■ Setting Default Business Component Preferences and Project Settings
■ Setting Default Schema Options
■ Setting Default Framework Base Classes

■ Setting Business Component Root and Working Directories
■ Ways to Create a Business Component Project

■ Creating a New Business Component Project
■ Specifying the Directory and Filename for a Business
Components Project
■ Specifying the Paths for a Business Components Project
■ Specifying the Connection to the Database
■ Specifying the Name of a Package in a Business Component
Project
■ Editing Default Business Component Object Names
■ Understanding the Default Business Components
■ Turning an Existing Project into a Business Component Project
■ Setting Business Component Project Options

■ Specifying the Connection to the Database
■ Specifying Code Generation, Lazy Loading, and Custom Message

Bundle Options
■ Enabling and Disabling Java File Generation
■ Improving JDeveloper Performance by Not Loading All

Packages
■ Specifying a Custom Message Bundle
■ Substituting Business Components
11-5
■ Creating and Registering Validation Rule Classes
■ Creating a New Validation Rule Class
■ Registering an Existing Validation Rule Class

■ Selecting a Superclass
■ Setting Business Component Root and Working Directories
■ Creating a Business Component Package

■ Specifying the Name of a Package in a Business Component Project

■ Editing Default Business Component Object Names
■ Understanding Default Business Components
■ Ways to Import Existing Business Components

■ About Extending Imported Business Components
■ Importing Business Components
❍ Working with Entity Objects, Associations, and Database Tables

■ Understanding Entity Objects and Associations
■ What Is an Entity Object?
■ What Is an Association?
■ About Generating Entity Objects, Associations, and Database Tables
■ About Reverse Generation
■ About Forward Generation
■ About Synchronizing the Database and Business Logic Tier

■ What Is an Entity Attribute?
■ Types of Business Logic
■ About Validation Logic
■ What Is a Domain?
■ About Inheriting and Overriding Domain Attribute

Settings
■ Files that Define a Domain
■ About the Predefined Validation Rule Classes
11-6
■ About CompareValidator
■ About ListValidator
■ About RangeValidator
■ About MethodValidator
■ How Entity Objects Are Validated When an Attribute Is

Set
■ About Transactions
■ About Commit Cycle Processing
■ About Rollback Cycle Processing

■ About Application Modules and Transactions
■ About Transactions and Locks
■ How Entity Objects Interact with View Objects

■ Entity Object States and Events
■ Entity Object Row States
■ Entity Object Exceptions
■ About the EntityDefImpl Class
■ About the EntityImpl Class
■ About Business Component Properties
■ About Using Stored Procedures
■ About Intersection Tables
■ Creating and Modifying Entity Objects and Associations

■ Preparing for Reverse Generation
■ Using a Domain as a Data Type for an Attribute
■ Ways to Represent Oracle Object Types in Entity Objects

■ Representing an Oracle Object Type with a User-defined
Domain
■ Representing a VARRAY that Contains Oracle Object
Types
■ Replacing an Oracle Object Type Column with a REF to
a Table of that Type
■ Coordinating Entity Objects and Database Triggers

11-7
■ Preparing for Forward Generation
■ Ways to Create Entity Objects and Associations
■ Creating Default Entity Objects and Associations from a
Database
■ Creating an Entity Object
■ Specifying the Name, Package, and Table of an Entity
Object
■ Selecting a Package
■ Specifying an Existing Entity Object to Extend
■ Creating, Removing, and Ordering Entity Attributes

■ Defining a New Entity Attribute
■ Adding an Entity Attribute from a Table

■ Generating Java Source Files and Methods for Entity
Objects
■ Setting Framework Base Classes
■ Creating a Default View Object and Finishing the Entity

Object Wizard
■ The Files that Define an Entity Object
■ Creating an Entity Object for a Table with No Primary
Key
■ Creating an Association or Composition

■ Specifying the Name and Package of an Association
■ Specifying an Existing Association to Extend
■ Specifying the Entity Objects for an Association

■ Selecting the Attributes for an Association
■ Specifying Behavioral Aspects of an Association
■ Specifying the Cardinality of an Association
■ Exposing Association Accessors

■ Specifying Whether to Generate Database
11-8
Constraints Based on an Association
■ Creating a Composition
■ Specifying the Intersection Entity Object for a Many-to-

Many Association
■ Generating One-to-Many Portions of a Many-to-Many
Association
■ The File that Defines an Association
■ Creating a Many-to-Many Association
■ Creating an Association from a Database Constraint
■ Ways to Edit Entity Objects and Associations

■ Editing an Entity Object
■ Specifying the Name, Package, and Table of an Entity
Object
■ Specifying an Existing Entity Object to Extend
■ Creating, Removing, and Ordering Entity Attributes

■ Creating a New Entity Attribute
■ Creating an Entity Attribute from a Table

■ Synchronizing the Database and Business Logic
Tier with the Synchronization Tool

■ Tuning Entity Object Performance with the JDBC Update
Batching API
■ Generating Java Source Files and Methods for Entity
Objects
■ Adding, Editing, Removing, and Reordering Entity

Validation Rules
■ Publishing Entity Object Events
11-9
■ Creating and Editing an Event
■ Subscribing to Entity Object Events

■ Adding and Editing a Method that Executes in
Response to an Entity Event
■ Defining Business Component Properties and Values
■ Editing an Association or Composition

■ Specifying the Entity Objects for an Association
■ Selecting the Attributes for an Association

■ Specifying Behavioral Aspects of an Association
■ Specifying the Cardinality of an Association
■ Exposing Association Accessors

■ Specifying Whether to Generate Database
■ Creating a Composition
■ Specifying the Intersection Entity Object for a Many-to-

Many Association
■ Generating One-to-Many Portions of a Many-to-Many
Association
■ The File that Defines an Association
■ Creating a Many-to-Many Relationship
■ Creating an Association from a Database Constraint
■ Ways to Edit Entity Attributes

■ Editing Entity Attribute Settings
■ Adding, Editing, and Removing Entity Validation Rules

■ Reordering Validation Rules

■ Defining User Interface Control Hints
■ Forward Generating Database Tables and Constraints

■ Defining Tables through Entity Objects
11-10
■ Ways to Define Constraints
■ Specifying Whether to Generate a Referential Integrity
Constraint Based on an Association

■ Defining a Database Constraint by Creating an Entity
Constraint
■ Specifying an Entity Constraint Name and Table
■ Selecting the Attributes Involved in an Entity

Constraint
■ Specifying the Properties of an Entity Constraint
■ Code that Defines an Entity Constraint
■ Creating Database Tables and Constraints from Business

Components
■ Ways to Add Validation Logic

■ Using a Domain as a Data Type for an Attribute
■ Creating a Domain
■ Specifying a Domain Name, Package, and
Optionally an Oracle Object Type

■ Ways to Specify Domain Attributes and Settings

■ Specifying Domain Attribute Settings
■ Specifying Domain Attributes and Settings

for Oracle Object Types
■ Files that Define a Domain

■ Ways to Represent Oracle Object Types in Entity
Objects
■ Representing an Oracle Object Type with a
User-defined Domain
■ Representing a VARRAY that Contains
Oracle Object Types
■ Replacing an Oracle Object Type Column
with a REF to a Table of that Type
■ Editing a Domain
■ Ways to Specify Domain Attributes and Settings
11-11
■ Specifying Domain Attribute Settings
■ Specifying Domain Attributes and Settings
for Oracle Object Types
■ Defining Business Component Properties and

Values
■ Applying a Domain to an Entity Attribute
■ Writing Validation Code in setAttribute Methods

■ Writing Validation Code in the validateEntity Method
■ Adding, Editing, Removing, and Reordering Entity Validation
Rules
■ Creating and Registering Validation Rule Classes

■ Creating a New Validation Rule Class
■ Implementing a Validation Class

■ Registering an Existing Validation Rule Class
■ Working with Custom Properties

■ Overriding Property Values
■ Getting and Setting Properties at Runtime

■ Using Properties to Dynamically Create a UI
■ Ways to Handle Errors in Business Component Applications

■ Handling Errors Using Error Codes
■ Handling Errors through Predefined Business Component

Exception Classes
■ Returning a Localized Error Message
■ Marshaling Exceptions Across a Network
■ Creating Custom Business Component Exception Classes

■ Trapping Business Component Exceptions on a Client
11-12
■ Using the API to Customize Entity Objects and Associations
■ Generating Java Source Files and Methods for Entity Objects

■ Applying Unposted Changes to Entity Object Rows Queried
from the Database
■ Implementing Transaction Locking in Code
■ Calling Stored Procedures
❍ Working with View Objects, View Links, Application Modules, and Clients
■ Understanding View Objects, View Links, Application Modules, and Clients
■ What Is a View Object?
■ When to Associate View Objects with Entity Objects
■ What Is a View Link?

■ What Is an Application Module?
■ When to Put Code in an Application Module or a View Object
■ About Master-Detail Views
■ About Application Module Pooling
■ About Connection Pooling
■ About Pooling Classes
■ What is a View Attribute?
■ What Is a Domain?
■ About Transactions
■ About Commit Cycle Processing
■ About Rollback Cycle Processing

■ About Application Modules and Transactions
■ About Transactions and Locks
■ About Container-Mananged and Bean-Managed Transactions
■ How Entity Objects Interact with View Objects

■ About Exposing View Links to Entity Objects
11-13
■ About the Business Components Fault-in Mechanism
■ How Clients and the Business Logic Tier Interact

■ About Custom Client Methods

■ About Managing Rows in Memory at Runtime

■ About Testing Business Components within JDeveloper
■ View Object States and Events
■ View Object Exception Classes
■ About Business Component Properties
■ Creating and Modifying View Objects, View Links, Application Modules, and
Clients
■ Ways to Create View Objects, View Links, and Application Modules
■ Ways to Create Default View Objects, View Links, and
Application Modules
■ Creating a View Object
■ Specifying the Name and Package of a View Object
■ Extending an Existing View Object
■ Selecting Entity Objects to be Used by a View Object

■ Selecting Entity Objects to Implement
Polymorphic Row Sets
■ Creating, Removing, and Ordering View Attributes

■ Defining a New View Attribute

■ Customizing the SQL Statement of a View Object
■ Ordering View Attributes
■ Mapping View Attributes to SQL Columns

■ Generating Java Source Files and Methods for View
Objects
11-14
■ The Files that Define a View Object
■ Adding Custom Code to a View Object XML File
■ Creating a View Link

■ Specifying the Name and Package of a View Link
■ Extending an Existing View Link
■ Specifying the View Objects to Link and Generating

Accessors
■ Specifying the Attributes in a View Link
■ Customizing the SQL of a View Link
■ Specifying the Cardinality and Directionality of a View
Link
■ Specifying the Cardinality and Directionality of a View
Link
■ Specifying the Cardinality of a View Link
■ Exposing View Link Accessors
■ The File that Defines a View Link

■ Ways to Create a Many-to-Many View Link
■ Creating a Many-to-Many View Link Based on an
Association
■ Creating a Pure SQL Many-to-Many View Link
■ Creating an Application Module

■ Specifying the Name and Package of an Application
Module
■ Extending an Existing Application Module
■ Specifying the View Objects and View Links in an

Application Module's Data Model
■ Selecting View Objects to Implement Polymorphic
Row Sets
■ Nesting Application Modules

■ Generating a Java Source File for an Application Module
11-15
■ The Files that Define an Application Module
■ Ways to Edit View Objects, View Links, and Application Modules

■ Editing a View Object
■ Selecting Entity Objects to be Used by a View Object
■ Selecting Entity Objects to Implement
Polymorphic Row Sets
■ Creating, Removing, and Ordering View Attributes

■ Defining a New View Attribute

■ Customizing the SQL Statement of a View Object
■ Ordering View Attributes
■ Mapping View Attributes to SQL Columns

■ Tuning View Object Performance by Adjusting the Row
Fetch Size, Providing Query Hints, and Specifying Page
Iteration Mode
■ Generating Java Source Files and Methods for View
Objects
■ Exporting View Object Methods

■ Exporting View Object Row Accessor Methods
■ Editing a View Link

■ Specifying the View Objects to Link and Generating
Accessors
■ Specifying the Attributes in a View Link
■ Customizing the SQL of a View Link
■ Editing an Application Module

■ Specifying the View Objects and View Links in an
Application Module's Data Model

■ Selecting View Objects to Implement Polymorphic
Row Sets
■ Nesting Application Modules

11-16
■ Generating a Java Source File for an Application Module
■ Creating a Remote Application Module

■ Exporting Methods to Clients
■ Ways to Edit View Attributes

■ Editing View Attribute Settings
■ Editing Entity Attribute Settings

■ Testing Business Components

■ Using the Tester Menus and Buttons
■ Executing a View Object or Link Query in the Tester

■ Reexecuting a Query in the Tester
■ Viewing and Changing Called Methods and Values in the
Tester
■ Examining Attribute Characteristics in the Tester
■ Examining XML Output in the Tester
■ Testing Query Results
■ Creating an Application Module in the Tester
■ Creating View Objects in the Tester
■ Creating View Links in the Tester
■ Querying Data with View Criteria in the Tester
■ Examining Diagnostic Information from the Tester
■ Enabling Debug Tracing in the Tester
■ Managing Rows in Memory at Runtime

■ Exposing View Links to Entity Objects
■ Pooling Application Modules
■ Enabling and Disabling Failover for Application Module
Instances
■ Enabling and Disabling Connection Pooling when Using
Application Module Pooling
11-17
■ Setting the Maximum Cookie Age for Application Module
Pooling
■ Setting the Pool Recycle Threshold
■ Setting the Initial Pool Size
■ Setting the Maximum Pool Size
■ Setting the Pool High Water Mark for Application Module
Instances
■ Managing Non-Transactional State for Application Module
Pooling
■ Pooling Connections
■ Enabling and Disabling Connection Pooling
■ Setting the Initial Number of Pool Connections

■ Setting the Maximum Number of Pool Connections
■ Setting the Pool High Water Mark for Connections
■ Setting the Connection Pool Wait Timeout
■ Using a Custom Connection Pool Manager
■ Ways To Create a Client for Business Components

■ Creating a Hand-Coded Client for Business Components


■ Calling Methods from Clients
■ Creating Methods for Clients to Use

■ Ways to Create and Export Business Logic Tier Methods to
Clients
■ Creating Exportable Application Module Methods
11-18
■ Creating Exportable View Object Methods
■ Creating Exportable View Row Methods
■ Creating Delegators for Entity Object Methods
■ Ways to Call Exported Methods on Clients

■ Calling Exported Application Module Methods
■ Calling Exported View Object Methods

■ Calling Exported View Row Methods
■ Working with Custom Properties

■ Using Properties to Dynamically Create a UI
■ Ways to Handle Errors in Business Component Applications

■ Handling Errors Using Error Codes
■ Handling Errors through Predefined Business Component

Exception Classes
■ Returning a Localized Error Message
■ Marshaling Exceptions Across a Network
■ Creating Custom Business Component Exception Classes

■ Trapping Business Component Exceptions on a Client
■ Using the API to Customize and Use View Objects, View Links, and
Application Modules
■ Ways to Work With Transactions

■ Opening a JDBC Connection for a Transaction
■ Closing a JDBC Connection from a Transaction

■ Manually Posting Changes in a Transaction
■ Committing a Transaction
■ Rolling Back a Transaction
■ Implementing Transaction Locking in Code
■ Using Client-Demarcated Transactions
11-19

■ Creating a View Object Based on a Static Set of Values

■ Ways to Find Nested Application Module Instances in Code
■ Finding a Nested Application Module in the Data Model
■ Finding a Nested Application Module not in the Data

Model
■ Removing a View Object or Nested Application Module from an

Application Module in Code
■ Traversing View Links in Code
■ Executing a View Object Query in Code
■ Ways to Navigate Rows in Queries
■ Finding the First Row in a Query
■ Finding the Last Row in a Query

■ Stepping Through a Query
■ Stepping Backwards Through a Query
■ Finding a Row in a Query by Primary Key
■ Setting View Object Attribute Values in Code

■ Using a View Object to Insert and Delete Rows in Code
■ Creating and Changing View Object Queries in Code
■ Using a Range of View Object Rows in Code
■ Using Multiple View Object Row Iterators in Code
■ Ways to Create View Link Instances in Code
■ Creating a View Link from a View Link Definition
■ Creating a View Link from an Entity Association

■ Creating a View Link by Associating View Object
11-20
Attributes
■ Using Transaction Utility Methods for Testing and Debugging
❍ Customizing Existing Business Component Applications

■ Ways to Customize Existing Business Component Applications
■ Substituting Business Components

■ Substituting Extended Entity Objects
■ Substituting Extended View Objects

■ Substituting Extended Associations
■ Substituting Extended View Links
■ Substituting Extended Application Modules
■ Extending Business Components

■ Extending an Existing Entity Object
■ Extending an Existing Association

■ Extending an Existing View Object
■ Extending an Existing View Link
■ Extending an Existing Application Module
❍ About Developing Business Components for Foreign Datasources

■ Limitations of Developing for Foreign Datasources
■ SQL Server Walkthrough

■ DB2 Walkthrough
■ Ways to Develop Business Components for Foreign Datasources
■ Developing an Application for a Foreign Database
■ Developing an Application for an OLite Database

■ Developing an Application for a Custom Database
■ Modifying a Legacy Application for Foreign Datasources
■ Developing an Application for Switchable Databases
■ Switching Datasources
■ Using a Foreign Datasource by Matching Schemas

■ Matching Schemas with OLite
11-21
■ Matching Schemas with a Standars-based Database
■ About Type Maps

■ Creating a Custom Type Map
■ Specifying a Custom TypeMap for Generic JDBC

■ Sample TypeMap Class
■ Java Type Map Entries
❍ Using XML with Business Components

■ Implementing XML Messaging
■ About Business Components, XML, and Packages

■ Using the XML Parser
■ Using Special Characters in XML
■ Retrieving Metadata from a Custom Lookup Implementation
■ Using XML Metadata Properties that Affect XML Generation
❍ About Oracle Object Types and Business Components

■ Ways to Represent Oracle Object Types
■ Representing Column Objects as Business Components
■ Representing Object Tables as Business Components

■ Representing a VARRAY that Contains Oracle Object Types
■ Representing Nested Tables that Contain Oracle Object Types
■ Using Oracle Objects with Business Components

■ Forward-generating Oracle Objects in the Database
■ Creating a Domain for an Oracle Object Type
■ Replacing an Oracle Object Type Column with a REF to a Table of that
Type
❍ Business Components Reference

■ Business Component Reserved Words

■ Controlling JDBC Behavior
11-22
■ Controlling Diagnostic Messages
■ JBO Error Messages
❍ Glossary
■ Alias attribute setting
■ application module
■ application module class
■ Application Module Wizard and Editor
■ association
■ Association Wizard and Editor
■ attribute
■ Attribute Editor
■ attribute settings
■ business component
■ business components project
■ Business Components for Java
■ Business Components Project Wizard and Editor
■ business logic
■ business logic tier
■ cache
■ cardinality setting
■ Change Indicator attribute setting
■ client
■ composition
■ connection
■ connection pooling
■ CORBA
■ Create Database Objects Tool
■ Default Value attribute setting

■ Discriminator attribute setting
■ domain
11-23
■ Domain Wizard and Editor
■ EJB
■ entity
■ Entity Constraint Wizard
■ entity definition class
■ entity object
■ entity object class
■ Entity Object Wizard and Editor
■ Expression attribute setting
■ fault-in mechanism
■ forward generation
■ forward only mode
■ framework
■ HTML
■ IIOP
■ iterator
■ JDBC
■ JSP
■ Key Attribute attribute setting
■ Mandatory attribute setting

■ metadata
■ Name attribute setting
■ ODBC
■ optimistic locking
■ Package Wizard and Editor

■ packages
■ Persistent attribute setting
■ pessimistic locking
11-24
■ Primary Key attribute setting
■ Project Wizard
■ property
■ Queriable attribute setting
■ Refresh After attribute setting

■ reverse generation
■ rollback
■ row object
■ Selected in Query attribute setting

■ server
■ SID
■ snapshot
■ stored procedure
■ synonym
■ Tester
■ thin client
■ transactions
■ Type attribute setting
■ type map
■ UML
■ Unique attribute setting
■ Updateable attribute setting
■ validation logic
■ validation rule
■ view
■ view link
■ View Link Wizard and Editor
■ view object
■ view object class
11-25
■ View Object Wizard and Editor
■ view row class
■ wizards
■ XML
11-26
Developing Business Components
Business Components for Java is a 100%-Java, XML-powered framework that enables
productive development, portable deployment, and flexible customization of multi-tier, database-
savvy applications from reusable business components.
Developing Business Components contains topics that describe using the Business
Components for Java framework and JDeveloper's integrated design-time wizards, component
editors, and Java coding environment to build applications by defining the characteristics of
objects: their attributes, relationships, and business rules.
JDeveloper generates executable Java code and XML to implement the behavior you design.
You can edit the code to enhance or change their behavior. You can then test application
services from reusable business components. These application services can then be deployed
on enterprise-scale server platforms supporting Java technology.
To get a hands-on overview of Business Components for Java, see the tutorials, available from
the Help contents. There are also samples in the BC4J directory of your installation.
11-27
What's New in Business Components for Java
This release of Business Components for Java includes new features and samples. See the
topics in the What's New book of the Developing Business Components online help for topics
describing new features.
In addition, many conceptual topics have been rewritten to provide more guidance on how to
use business components in your applications. Some of these topics are listed under the
What's New book.
You can find new business components samples in $ORACLE_HOME\BC4J\samples.
11-28
About Synchronizing the Database and Business
Logic Tier
Business Components for Java assists you in keeping the business logic tier and database in
sync, even after you change database tables and constraints. The Synchronize tool, new in the
release of Business Components for Java, identifies the differences between the database and
the business logic tier representation of it.
The tool can identify these types of differences and optionally update the business logic tier:
Database Business logic tier Action that the

table Synchronize tool can
take
new column no corresponding attribute in an entity Add the missing
in table/type object or in a domain representing an attribute.
Oracle Object Type
deleted a corresponding persistent attribute in For an entity object,
column in an entity object, or in a domain make the attribute
table/type transient. For a
domain, delete the
attribute.
changed a persistent attribute doesn't have the Change the attribute
type, corresponding attribute settings settings.
precision, or
scale
key no corresponding key constraint Add the missing key
constraint constraint to metadata.
added The key constraint is
(primary key, used for forward
foreign key, generation. You can
uniqueness, see key constraints in
cascade the business logic tier
delete, by selecting an entity
deferrable, object in the Navigator,
initially and looking in the
deferrable) Structure pane.
key key constraint present Remove key
constraint constraint.
removed
Note: Changing a column name is considered to be two changes: deleted a column and added
a column.
11-29
The tool can identify these types of differences between a database table and the business
logic tier, so you can manually make business logic tier changes, if needed:
Database table Business logic tier

table removed entity objects refer to the table
database changes SQL queries in view objects or view links no longer valid
that affect SQL (all queries are checked everytime you run the
queries Synchronize tool)
You can output a Synchronize tool report to a file. After you make changes, you can output to a
file again and compare the file differences so you can keep a record of changes made by you
or the tool.
Remember that some items that the Synchronize tool identifies might be appropriate in your
program. For example:
● Entity objects don't have to contain all the columns in a table if you aren't using them.
● Entity and domain attributes can have attribute settings that don't match the table,
specifically, column length and precision.
● You aren't required to have associations representing foreign key constraints in a
database.
Related Topics
Synchronizing the Database and Business Logic Tier with the Synchronization Tool
About the Development Process
About Generating Entity Objects, Associations, and Database Tables
About Synchronizing the Database and Business Logic Tier
What Is an Entity Object?
What Is an Entity Attribute?
What Is an Association?
Business Component Data Types
Creating an Association from a Database Constraint
11-30
Synchronizing the Database and Business Logic
Tier with the Synchronization Tool
Business Components for Java assists you in keeping the business logic tier and database in
sync, even after you change database tables and constraints. The Synchronize tool identifies
the differences between the database and the business logic tier representation of it. Note that
not all of these differences need to be corrected.
To access the Synchronize tool, in the Navigator, right-click a business components package
and choose Synchronize with Database. You can also access it from the Attributes page of the
Entity Object Editor and the Settings page of the Domain Editor (when you are defining a
domain for an Oracle Object Type).
Field and button descriptions
Field Description
Actions to synchronize A list of the actions that can be take to synchronize the
objects business logic tier with the database.
Click to take all actions in the list.
Synchronize All
Synchronize Click to synchronize the selected items in the list.

Click to save the action list in a text file. This feature help
Write to File
you keep track of changes you make over time.
To synchronize all items in the list:
● Click Synchronize All.
To synchronize selected items in the list:
1. Click Synchronize.
2. Individually specify whether you want to take an action.
To write the action list to a text file:
1. Click Write to File.

2. In the Open dialog, specify the text file and click Open.
11-31
To close the Synchronize tool:
● Click OK.
Related topics
11-32
Using an Entity Attribute as a Database Sequence
You can auto-create a primary key (as a sequence, GUID, and so on) whose value is generated
by the database when a new row is inserted into a table.
If you want to use to use an entity attribute as a database sequence, you could use the
DBSequence domain (new in this release), add code to the EntityImpl create method, or
select the Refresh After Insert attribute setting.
● To use the DBSequence domain, use the Entity Object Wizard or Editor to select it as the
entity Attribute Type.
● The code you add in the create method would need to return the value immediately
when a new row is created.
● For the Refresh After Insert attribute setting, the value is returned after the row is saved
to the database, assuming the column was filled in by a database trigger on insert.
You may want to make these types of attributes read-only so that an end user cannot change it,
or at least make them Updateable While New. Usually the attribute is a primary key.
Using the DBSequence domain
The domain oracle.jbo.domain.DBSequence can be used as as an attribute type for

columns that have an insert trigger that fills in a sequence value for the column. At design time,
you can choose DBSequence for an entity attribute.
At runtime, when a new instance of the DBSequence domain is created, it gets a temporary VM-
unique value (a temporary unique value in the Java VM where this application is running). After
the row containing this domain is posted, the value is replaced by the sequence value filled in
by the database trigger.
To use the domain, the attribute must use the following attribute settings:
● Primary Key — Selected, and the attribute must be mapped to a column in a table.
● Default Value — Zero (0), which is the starting seed value for the DBSequence temporary
values, or it tells the domain instance to recalculate it's value to be a unique value in the
Java virtual machine when this domain is set into a row as an attribute value.
● Updateable — While New
11-33
● Column Type — NUMBER
Note that the implementation assumes the presence of an insert trigger to fill in the column
value. If there isn't one, a temporary value will be stored, which might conflict with existing data
in the database.
Related topics
Creating an Entity Object
Editing an Entity Object
11-34
Implementing Cascade Delete Behavior
While creating an association with the Association Wizard or editing an association with the
Association Editor, in the Association Properties page, you specify whether to implement
cascade delete behavior or not.
When you have a composition, it most likely maps to an ON DELETE CASCADE constraint on
the foreign key in the database table definition. However, at runtime, when the remove method
is called on an entity object, the framework does not automatically delete all the "cached
composed children." By default, the remove method throws an exception if the user (or the
application) hasn't already removed the children before attempting to remove the parent.
To implement cascade delete behavior in the business logic tier, select the Implement Cascade
Delete checkbox — new in this release. When a master entity object is deleted, the details are
deleted first (if the detail rows are in memory at runtime). If the detail rows are not in the cache,
at least one detail row is retrieved from the datasource and the remove method is invoked on
it, so that all view object instances that are listening to the detail entity object type are notified of
the removal. A flag is added in the XML file for the composition to indicate that it implements
cascade delete. You must also have ON CASCADE DELETE at the database level so the
equivalent detail rows are removed.
Alternatively, you can implement runtime cascade delete behavior programmatically. (In this
case, deselect the Implement Cascade Delete checkbox.) If you'd like the application to
perform in-memory cascade delete when the remove method is called, you can override the
code on the EntityImpl subclass that is the parent end of the composition as follows:
● Override the remove method on the parent entity object.

● Implement the remove method to recursively remove all the instances present on
compositions. The default implementation only removes the current instance.Field
description
Field Description
Implement Cascade Delete Select this option to implement cascade delete behavior. To select the
checkbox, you must first select Composite Association so the association
is a composition, in which the source object "owns" the destination object.
To implement cascade delete behavior:
11-35
1. Select Composite Association.
2. Select Implement Cascade Delete.
Related Topics
Specifying Behavioral Aspects of an Association
About Validation Logic
11-36
Specifying Entity Attribute Settings
While creating an entity object with the Entity Object Wizard or editing an entity object with the
Entity Object Editor, you specify the following information in the Attribute Settings page. The
settings can affect forward generation or the settings can be derived from an existing table
(reverse generation). The Discriminator attribute setting is new in this release.
Field descriptions
Field Description
A list of attributes you defined in the Attributes page.
From the drop-down list, choose the attribute you want to
Select Attribute edit. Its settings appear below it, where you can modify
them.
You can modify the following settings. How you fill in the fields depends on the type of entity
attribute, and whether you're performing reverse or forward generation.
Attribute Setting Forward Generation Reverse Generation Persistent Transient

Attribute Attribute
Attribute Name N/A Default based on column Required Required

name; you can change it to
any Java identifier name.
Attribute Type N/A Default based on column data Required Required
type; you can choose another
type in the list.
Default Value N/A N/A Optional Optional
Persistent Only persistent attributes All attributes derived from the Selected Deselected
are added to the table. table are persistent; if you
change it, this column does
not get populated through the
business components
framework.
Discriminator N/A N/A Selectable Selectable
11-37
Primary Key Becomes the table's From the table; it must match Selectable Selectable,
primary key, or part of it if the table. but you
you specify multiple should
primary keys for a table (a leave it
composite key) deselected
in most
cases
Mandatory Becomes a mandatory From the table; this value Selectable Selectable
column in the table (a NOT must match the table, or you
NULL constraint is might get problematic runtime
generated for that column behavior or an exception.
in the table).
Updateable N/A N/A Selectable Selectable
Refresh After N/A N/A except when the Selectable N/A
java.sql.type for this attribute
is CHAR, then all Refresh
After checkboxes are
selected.
Database Column Becomes the table's From the table; it must match Required; it N/A
Name column name the table. must match
the table.
Column Type Becomes the table's From the table; it must match Required; it N/A
column data type the table. must match
the table.
Queriable N/A N/A Selectable N/A
Unique If selected, the column has From the table; it must match Selectable N/A
a unique constraint. the table.
Change Indicator N/A N/A Selectable N/A
In general, if you are performing reverse generation, you don't want to change the primary key,
mandatory, database column name, column type, and unique settings that were received from
the table. For forward generation, the primary key, mandatory, persistent, database column
name, column type, and unique settings are used to generate tables.
For your entity object to be able to uniquely identify a row of data, one of its attributes must be
defined as a primary key. If your table doesn't have a primary key, you can use the ROWID.
To define attribute settings:
1. Choose an attribute in the Select Attribute list.
2. Specify attribute settings, as described in the previous table.
11-38
3. Repeat these steps for each attribute you want to define.
To save changes or continue with the wizard:
● After you are finished, click OK or Finish to save your changes.

● In the editor, click Apply to save the changes in this page without exiting the editor.
● To go to the next page of the wizard, click Next.
Related topics
Creating a Domain
Editing a Domain
Ways to Represent Oracle Object Types in Entity Objects
About Inheriting and Overriding Domain Attribute Settings
11-39
Specifying View Attribute Settings
While creating a view object with the View Object Wizard or editing a view object in the View
Object Editor, use the Attribute Settings page to edit the attribute settings of the view attributes
you defined in the Attributes page. The Selected in Query, Key Attribute, and Discriminator
attribute settings are new in this release.
Field descriptions
Field Description
A list of attributes you defined in the Attributes page.
Select Attribute edit. Its settings appear below it, where you can modify
them.
You can modify the following settings. How you fill in the fields depends on the type of view
attribute.
Attribute Setting Persistent Attribute Entity-Derived Transient SQL-Derived

Attribute Attribute Attribute
Attribute Name Default based on Default based on Required Required

entity attribute name entity attribute
name
Attribute Type Not modifiable; uses Not modifiable; Required Required
entity attribute setting uses entity attribute
setting
Selected in Query When selected, this When selected, this When selected, Selected
attribute appears in attribute appears in this attribute
the view object's SQL the view object's appears in the
Select statement. SQL Select view object's SQL
statement. Select statement.
Key Attribute When selected, this When selected, this When selected, When selected, this
attribute is a key attribute is a key this attribute is a attribute is a key
attribute. attribute. key attribute. attribute.
Discriminator Selectable Selectable Selectable Selectable
Updateable Based on entity Based on entity Selectable Selectable
attribute setting; can attribute setting;
make setting more can make setting
restrictive. more restrictive.
11-40
Alias Default based on Optional Optional Optional, can use to
entity attribute name; prevent name
optional, but can use conflicts
to prevent name
conflicts
Expression N/A Optional N/A (NULL) Required (not NULL)
Queriable Selectable N/A N/A Selectable
To modify view attribute settings:
1. Choose an attribute in the Select Attribute field.

2. Edit attribute settings, as needed.
3. Repeat for each attribute you want to edit.
● After you are finished with the wizard or editor, click Finish or OK to save your changes.
Related topics
What Is a View Object?
What Is a View Attribute?
Working with Domains
Testing Business Components
How Does the Business Logic Tier Cache Data?
About Using Stored Procedures
11-41
Adding and Editing a Validation Rule
While editing an entity object with the Entity Object Editor or editing entity attributes in the
Attribute Editor, from the Validation page, you can use the Add Validation Rule dialog to add
and edit validation rules. The rules could be predefined in JDeveloper or be your own custom
rules. New in the previous release was the UniqueKeyValidator validation rule.
To add a validation rule:
1. Choose a rule from the Rules list.
2. Specify the information needed by that rule.
3. Click OK.
The rule appears in the Validation page of the editor.
To edit a validation rule:
1. Choose a rule from the Rules list.
2. Specify the information needed by that rule.
3. Click OK.
To use CompareValidator, ListValidator, RangeValidator, or UniqueKeyValidator:
If you choose CompareValidator, ListValidator, or RangeValidator, you must also choose an

operator and the type of comparison you want to make.
Validation Rule Description Attribute Operator Values
11-42
CompareValidator Performs a logical The name of the Equals In the Compare
comparison between the attribute to which NotEquals With field, choose
attribute and a value. The you are applying LessThan one of:
comparison can be to a the validation rule. GreaterThan
literal value, a SQL query, LessOrEqualTo Literal Value
or the results of a view GreaterOrEqualTo Type a value in the
object query. Enter Literal Value
field. Each entry
must be on a new
line, separated by
Return.
Query Result
Type a SQL query
in the Enter SQL
Statement field.
This statement will
be executed at the
time of validation;
the first column
from the select list
will define the list
of values.
View Object
Attribute
Select a view
object in your
project from the
Select Attribute
tree. At runtime,
this view object will
be executed at the
time of validation
and the first row
returned from the
view object will be
used to get the
attribute value for
comparison.
11-43
ListValidator Compares an attribute The name of the In In the List field,
against a list of values. The attribute to which Not In choose one of:
attribute value can be you are applying
compared against a list of the validation rule. Literal Values
fixed literal values, a list of Query Result
values returned from a SQL View Object
query, or a list of values Attribute
returned for an attribute of
a view object.
Each value must
be entered on it's
own line - do not
use commas or
spaces to separate
values. Lines with
no string in them
will be ignored.
JDeveloper does
not evaluate the
contents of the list
for validity, type, or
duplicate values.
RangeValidator Tests for attribute values The name of the Between Define the range
within specified minimum attribute to which Not Between by typing minimum
and maximum values. Note you are applying and maximum
that this validator performs the validation rule. values. Note that
an inclusive range this validator
comparison. performs an
inclusive range
comparison.
UniqueKeyValidator Ensures that the primary NA NA NA
key for an entity object is
always unique. Whenever
any of the primary key
attribute values change,
this validation rule
validates, both in the entity
cache and the database,
that the new key does not
belong to any other entity
object instance of this entity
object class. (It is the
business logic tier
equivalent of a unique
constraint in the database.)
If the key is found in one of
the entity objects, a
TooManyObjectsException
is thrown. To handle the
exception, you need to
11-44
write code in the Java file
where you are setting the
attribute. Instead of using
UniqueKeyValidator, you
can write code that uses
the EntityDefImpl
addUniquePKValidation
method; see the Javadoc
for more information.
The Attribute field is available only when you are adding a validation rule: it is not available
when you are editing an existing rule. By default, if the rule is being applied on an attribute level
(in the Rules page), then that attribute will be selected in this list box. However, this does not
have to be the same attribute that you chose on the Validation page; any other attribute can be
selected for validation. For example, for a rule "validate DeptNo whenever an EmpNo has
changed", the rule is being applied to EmpNo; however, in this drop-down list box, DeptNo
should be selected.
To use MethodValidator:
The MethodValidator invokes a custom, or "user-defined," method.
1. In the Add Validation Rule dialog, choose MethodValidator from the Rules list.
A list of the methods you have defined for the project appears.
2. Select a method name.
3. Click OK.
If there are custom methods defined in the Java class for this entity object, for the selected
validation level, those methods will be displayed in the method list. Candidate methods should
be public, return boolean and start with the keyword validate. Also, for an attribute, the
method should have one argument of the type of the attribute.
For example, for an entity-level validation, the candidate methods could be:
public boolean validateDepartment()

public boolean validateDepartmentsForProperLocations()
11-45
For an attribute DeptNo of type Number, candidate methods could be:
public boolean validateDeptNo(Number value)

public boolean validateDepartmentNumberForTwoDigits()
These custom methods should be added to the Java file before the Entity Object Wizard is
started or they won't appear in the Select a method list.
To use a custom validator:
Typically, you follow these steps.
1. In the Add Validation Rule dialog, choose the custom validator from the Rules list.
The editable field contains a table of properties and their corresponding values.
2. Type the values that you want to validate the attribute against.
3. Click OK.
A custom validator typically consists of a list of properties and values against which an attribute
is compared. The contents of the Validation page changes depending on your choice of rule.
These rules are JavaBeans and, thus, could have their own customizers, per the JavaBeans
specifications. These customizers will be displayed in this page allowing you to edit the
properties of the bean. If there are no customizers defined for a bean, this page will display a
Property-Value editor where Properties are listed on the left column and their current values
listed on the right column. The values can be modified using this page. (For an example of a
customizer, see oracle.jbo.server.rules.CompareValidatorCustomizer.java
which is a custom editor for oracle.jbo.server.rules.JboCompareValidator.java.)
Related topics
About the Predefined Validation Rule Classes
11-46
Tuning Entity Object Performance with the JDBC
Update Batching API
While editing an entity object with the Entity Object Editor, in the Tuning page you can specify
when you want to use the Update Batching API to update entity objects at runtime. No coding is
required. This feature of the Entity Object Editor is new in this release.
Using this API usually improves performance, except where there is only one modified row.
Field descriptions
Field Description
Select to use the JDBC Update Batching API. No coding
Use Update Batching
is required.
The Update Batching API is used when the number of
modified rows is more than the threshold value (an
Threshold integer 0 or more).
To use the Update Batching API:
1. Select Use Update Batching.
2. Specify a Threshold value.
To save changes:
● After you are finished with the editor, click OK to save your changes.
● Click Apply to save the changes in this page without exiting the editor.
Related Topics
11-47
Tuning View Object Performance by Adjusting the
Row Fetch Size, Providing Query Hints, and
Specifying Page Iteration Mode
While you are editing a view object in the View Object Editor, you can specify fetch size
parameters in the Tuning page to tune the performance of your program. The fetch size
controls how many rows the business logic tier fetches from the database. The fetch size
parameters are stored in the view object XML file.
You can override the XML parameters in client code, or in view object code in the business
logic tier. The following oracle.jbo.server.ViewObjectImpl interface methods deal with
the fetch strategy (including the fetch size):
● setFetchMode
● getFetchMode
● getFetchSize
● setFetchSize
● setMaxFetchSize
● getMaxFetchSize
You can use them on the business logic tier only. In addition, you can use the MaxFetchSize
methods (in the ViewObject interface) from both the business logic tier and client code. See
the Javadoc for more information.
For an example, see the Batch Client sample in the

ORACLE_HOME\BC4J\samples\OnlineOrdersForClients directory.
New in this release, you can also specify SQL query hints to optimize your SQL query, and
specify how your client pages through data.
Field descriptions
Field Description
11-48
Fetch Mode Select As Needed to get data from the database as it is used (the default). Select
All at Once to get all data at once. The fetch mode controls how rows are
retrieved out of the JDBC result set. After a SQL query executes, the business
logic tier retrieves row data from the result set.
If you specify As Needed, the result set is left open and rows are retrieved as the
user navigates through the row set. If the user reaches the end of the row set, the
result set is closed. This option is useful, for example, if the number of rows is
large and the application is likely to use only a small portion of these rows.
If you specify All at Once, all rows are retrieved out of the result set, even if the
user has not navigated through the row set. After all rows are retrieved, the result
set is closed. This option is useful, for example, if the number of rows is small.
When you specify All at Once, you incur the data fetching "penalty" all at once.
When you specify As Needed, your incur the penalty incrementally.
You may want to use All at Once if the number of rows in the row set is relatively
small and the number of row sets open on the view object is large. This can avoid
using up the JDBC result sets. If As Needed is specified and too many row sets
are open (and left open because they are not navigated to the end), the user may
run out of result sets and get a DMLException.(You can set the jbo.max.cursors
runtime parameter to a higher number, if needed.) On the other hand, if the result
set contains many rows, All at Once may not be preferred because it incurs the
cost of retrieving all rows up front.
Fetch Size Specify the number of rows to fetch at a time (through JDBC) when the fetch
mode is As Needed. (This value is ignored when the fetch mode is All at Once.)
You can specify a number greater than zero; the default is 1.
Maximum Fetch Size Specify the maximum number of rows to fetch. For example, if the query result set
contains 2000 rows, and you specified 1000 rows as the maximum fetch size, the
business logic tier will only fetch 1000 rows total, and close the result set. You can
specify a number -1 or greater. The default is -1 meaning fetch all rows. Zero (0)
means fetch no rows in the result set.
Query Hint (Optional) Type a hint for the SQL Query Optimizer. Query Optimizer Hints are an
Oracle SQL Language feature; see the SQL Tuning Manual for more information.
Hints are stored in the view object XML file through a QueryHint property. The
hints are overridable through methods on the ViewObject interface:
setQueryOptimizerHint and getQueryOptimizerHint. See the Javadoc
At runtime, if the query is normal (not expert) mode, and the QueryHint property is
not NULL or empty, the SELECT statement is augmented as follows:
SELECT /*+ value-of-optimizer-hint */ ...
11-49
where the value of the optimizer hint is included immediately following the
SELECT keyword, separated on either side by a space, and surrounded by a
leading /*+ and a trailing */.
For expert mode queries, it is the same, except that the hint is part of the wrapping
SELECT * FROM () wrapper:
SELECT /*+ value-of-optimizer-hint */ * FROM (...)
Other SQLBuilder implementations (not supplied by Oracle) can ignore this

property.
Page-by-Page Iteration When a user scrolls through data in a page-by-page fashion on a client (such as
Mode from a series of web pages), the default behavior is to completely fill the last page
with data. As a result, rows viewed on the previous page can appear on the last
page. If you want to keep this default behavior, select Keep Last Page Full. If you
want to avoid repeated data, select Allow Partial Last Page.
To save changes:
Related topics
Controlling JDBC Behavior
11-50
About Polymorphic Row Sets
In this release of Business Components for Java, you can now map different types of entity
objects or view objects to the same row set, and clients can process the row set without having
to know about the different types of objects. Previously, each result set had to map to the same
type of entity object or view object.
The polymorphism can exist on the entity object level, the view object level, or both. The
following new features were added to support polymorphism:
● a new Discriminator attribute setting, used in conjunction with the Default Value attribute
setting
● the new Subtypes dialog in the View Object Wizard and Editor and the new Subtypes
dialog in the Application Module Wizard and Editor
In addition, the business components Extends feature (different from extending classes in the
Java sense) plays an integral role.
Polymorphism on the entity object level
Let's say you have a table with rows that you'd like to map to different entity objects. For
example, you have a table of Platinum, Gold, and Silver customers and you want to process
their rows differently. Business Components for Java now allows you to accomplish this by
taking the following actions:
1. Define a base entity object for the rows, and then extend it to create different versions of
this entity object. In this example, you might have a base Customers entity object and
child PlatinumCustomers, GoldCustomers, and SilverCustomers entity objects.
2. In the base entity object, create an entity attribute that you want to use to discriminate
between the different types of rows; for this attribute, select the Discriminator attribute
setting. In each child of the base entity object, add a unique default value to this attribute.
In this example, the you might have three child entity objects with these default values:
Platinum, Gold, and Silver.
3. In the child entity objects, remove or add attributes specific to processing that type of
entity object. You can also add methods with different functionality depending on the
entity object. You could add skeleton methods to the base class, and customize the
methods in the child classes.
4. In the Entity Objects page of the View Object Wizard or Editor, select the base entity
11-51
object. After, in the Subtypes dialog, select the child entity objects. That makes them
available to the view object that uses the entity objects.
Note that the framework doesn't force you to use a discriminator column in the table, although
usually this is the case. The discriminator attribute can be derived from a calculated value, for
example.
The base entity object could be a row type (that is, associated with a type of row in your
datasource), or only the child entity objects could be used for row types and the base would
simply be the "template."
Polymorphism on the view object level
You can implement polymorphism on the view object level, regardless of whether you
implement it on the entity object level or not. Similarly to the entity object level, you accomplish
polymorphism by taking the following actions:
1. Define a base view object for the rows, and then extend it to create different versions of
this view object. For example, you might have a base Dept view object and child
LargeDept and SmallDept view objects.
2. In the base view object, create a view attribute that you want to use to discriminate
between the different types of rows; for this attribute, select the Discriminator attribute
setting. In each child of the base view object, add a unique default value to this attribute.
In this example, you might have two child view objects with these default values: S or L.
3. In the Data Model page of the Application Module Wizard or Editor, select the base view
object. After, in the Subtypes dialog, select the child view objects. That makes them
available to the application module who uses the view objects.
When rows are retrieved from the database, the ViewObjectImpl

createRowFromResultSet method is called. This method retrieves discriminator attributes
for the view object to determine the target view object definition. Next, using the definition, it
creates the appropriate row. This method is overridable.
Coding for polymorphic row sets
When you work with polymorphic row sets, your code has to deal with more attribute lists. For
legacy applications, when you implement polymorphic row sets, you will probably need to
rework the code to handle the change.
11-52
Related topics
11-53
Selecting Entity Objects to Implement Polymorphic
Row Sets
Object Editor, use the Subtypes dialog to select entity objects you want to use for the business
components polymorphism feature, new in this release.
In the Entity Objects page, you must first add the base entity object to the Selected list. Next,
you click Subtypes to access the Subtypes dialog. Here you can shuttle to the Selected list
those entity objects that extend the base entity object (using the business components Extends
feature); you use these entity objects to implement polymorphism through a Discriminator
attribute/column.
Field descriptions
Field Description
A list of entity objects defined in the current workspace,
grouped by package. Expand or collapse the tree to see
Available just the entity objects you need. To add an entity object
to the Selected list, select it in the Available list and click
the right arrow (>).
(Optional) A list of entity objects that extend the base
entity object through the business components Extends
Selected feature (not Java extends). To remove an entity object
from the list, select it and click the left arrow (<).
To select a polymorphic entity object:
1. Select an entity object in the Available list and click the right arrow (>).
The entity object appears in the Selected list.
2. Repeat for any other entity objects you need.
3. Click OK when you are finished.
Related topics
11-54
Extending Business Components
11-55
Selecting View Objects to Implement Polymorphic
Row Sets
While creating an application module with the Application Module Wizard or editing an
application module with the Application Module Editor, use the Subtypes dialog to select view
objects you want to use for the business components polymorphism feature, new in this
release.
In the Data Model page, you must first add the base view object to the Data Model list. Next,
you click Subtypes to access the Subtypes dialog. Here you can shuttle to the Selected list
those view objects that extend the base view object (using the business components Extends
feature); you use these view objects to implement polymorphism through a Discriminator
attribute/column.
Field descriptions
Field Description
A list of view objects defined in the current workspace,
Available just the view objects you need. To add an view object to
the Selected list, select it in the Available list and click
the right arrow (>).
(Optional) A list of view objects that extend the base view
object through the business components Extends feature
Selected (not Java extends). To remove an view object from the
list, select it and click the left arrow (<).
To select a polymorphic view object:
1. Select an view object in the Available list and click the right arrow (>).
The view object appears in the Selected list.
2. Repeat for any other view objects you need.
3. Click OK when you are finished.
Related topics
11-56
What is an Application Module?
11-57
Creating a View Object Based on a Static Set of Values
View objects are usually based on one or more underlying entity objects; however, you can create a
view object based on other data sources as well, which is a new feature in this release. In this case, the
view object "query" is not a SQL statement, so you must override the code in the view object's
implementation class to gather and work with the data. View objects of this sort can be from any source
of data including:
● A static set of values

● A text file
● A legacy database for which no JDBC driver exists
This topic walks you through creating a view object based on a static set of values. It uses a business
components project based on the HR schema. Also see
ORACLE_HOME/BC4J/samples/ProgrammaticVO for a sample.
To create the business components project:
1. If you want to create a new workspace, choose File | New | Workspace.

2. Choose File | New | Project.
3. In the Project Wizard, choose A Java Project Containing Business Components and click
Next.
4. Work through the wizard, changing the information there or accepting the defaults and click
Finish.
5. When the Business Component Project Wizard opens, review the information on the Welcome
page and click Next.
6. In step 1 of the wizard, specify a database connection that contains the HR schema (enter HR for
both the username and password). Click Next.
7. In step 2 of the wizard, enter a package name or accept the default and click Next.
8. In step 3 of the wizard, shuttle the LOCATIONS table to the Selected list and click Finish.
You now have a default view of the Locations table, which you can scroll through based on the
LocationId attribute. Now, suppose you want to be able to look at the records by country name. You are
faced with two problems:
● The Locations table contains only abbreviations. To solve this, you will create a new view object,
CountryCodesView, that contains two attributes, CountryName and Abbreviation. This view
object will get its information from a static list of values, listing the abbreviation and the name of
the country.
11-58
● You need a restricted view of the Locations table based on the country name. To implement this,
you will create a view link that gives a restricted view of LocationsView based on the
CountryCodesView.
Create a new view object
Now you will create a new view object with two attributes, CountryName and Abbreviation. These
attributes are transient, meaning that they are not mapped to a database table. Therefor, you will not
base the view object on an entity object, or create a query statement in the wizard.
To create a view object with two transient attributes:
1. In the Navigation Pane, right click on your package node and choose New | View Object.
2. When the View Object Wizard opens, review the information on the Welcome page and click
Next.
3. In the Name, page, enter CountryCodesView for the view object's name and click Next.
4. In the Entity Object page, select Next. You will not be basing this view object on an entity object.
5. In the Attributes page, click New to create a new attribute.
a. In the Define New View Attribute dialog, enter CountryName in the Name field. Click OK.
2. Click New again, this time making an attribute called Abbreviation.
6. You do not need to change any of the default values for the rest of this wizard. You may work
through the wizard or click Finish now.
Modify the view object's code
You now have a view object with two transient (unmapped) attributes. To populate the view object's
"query" with a list of countries and abbreviations, you need to edit the code in the view object's
implementation class to do the following:
● Declare and initialize a vector

● Populate the "query" with the contents of the vector
● Determine if there are any rows left in the result set
● Return the next row in the result set
To edit the implementation class:
1. In the Navigation Pane, expand the node for CountryCodesView.
11-59
2. Double click CountryCodesViewImpl.java to open it in the Source Editor.
Declare and initialize a vector in the constructor
Your view object now contains two transient attributes. The first step is to add code to the constructor
method to declare and initialize a vector containing country names and abbreviations. The completed
code looks like the following:
public class CountryCodesViewImpl extends oracle.jbo.server.ViewObjectImpl {
static final String [] countryStr = {

"AR,Argentina",
"AU,Australia",
"BE,Belgium",
"BR,Brazil",
"CA,Canada",
"CH,Switzerland",
"CN,China",
"DE,Germany",
"DK,Denmark",
"EG,Egypt",
"FR,France",
"HK,HongKong",
"IL,Israel",
"IN,India",
"IT,Italy",
"JP,Japan",
"KW,Kuwait",
"MX,Mexico",
"NG,Nigeria",
"NL,Netherlands",
"SG,Singapore",
"UK,United Kingdom",
"US,United States of America",
"ZM,Zambia",
"ZW,Zimbabwe" };
static Vector countries = new Vector(countryStr.length);
/**
* This is the default constructor (do not remove)
*/
public CountryCodesViewImpl() {
if (countries.isEmpty()) {
for (int i=0; i<countryStr.length; i++) {
countries.add(i, countryStr[i]);
}
}
}
11-60
Populate the query collection with the contents of the vector
The next step is to populate the query collection with the results of the view object's query, by overriding
executeQueryForCollection(). In this case the "query result" is the contents of the static vector.
The completed code follows:
protected void executeQueryForCollection(

Object qc, Object[] params, int noUserParams) {
super.executeQueryForCollection(qc, params, noUserParams);
// associate relevant data with this query collection: our
// countries Vector, its size, and an index we'll use when
// populating the rowset
setUserDataForCollection(qc,
new Object[] {countries, new Integer(countries.size()), new Integer(0)});
}
Determine if there are any rows left in the result set
The next step is to determine if there are any more rows in the result set. To do this, override
hasNextForCollection(). This method compares the size of the result set with the index of the
next row to determine whether there are any more rows in the result set. The completed code follows:
protected boolean hasNextForCollection(Object qc) {

Object[] userData = (Object[])getUserDataForCollection(qc);
// userData[0] is the result set

// userData[1] is the number of rows in the result set
// userData[2] is the index of the next row
if (userData == null || userData[0] == null) {
return false;
}
// has the index moved beyond the end of the list of countries?
int index = ((Integer)userData[2]).intValue();
if (index >= ((Integer)userData[1]).intValue()) {
setFetchCompleteForCollection(qc, true);
return false;
}
return true;
}
Return the next row in the result set
The final step is to return the next row in a result set. To do this, override
createRowFromResultSet(). This method returns the next row in the result set. The completed
code follows:
11-61
protected ViewRowImpl createRowFromResultSet(Object qc, ResultSet resultSet) {
Object[] userData = (Object[])getUserDataForCollection(qc);
if (userData == null || userData[0] == null) {

return null;
}
// are there any more rows to fetch?

int index = ((Integer)userData[2]).intValue();
if (index >= ((Integer)userData[1]).intValue()) {
setFetchCompleteForCollection(qc, true);
return null;
}
// Create and populate a new row

ViewRowImpl vRow = createNewRowForCollection(qc);
Vector data = (Vector)userData[0];
StringTokenizer st =
new StringTokenizer((String)data.get(index), ",");
populateAttributeForRow(vRow, 0, st.nextToken());
populateAttributeForRow(vRow, 1, st.nextToken());
userData[2] = new Integer(++index);
return vRow;
}
Test the view object
Your new view object is now complete, containing the country names and abbreviations listed in the
implementation class. At this point you might want to test the view object to see that it is working.
To test the view object:
1. In the Navigation Pane, right click the application model's node and choose Test.
2. When the Business Component Browser dialog appears, click Connect.
3. Double-click CountryCodesView.
4. Use the Business Component Browser controls to scroll through the records, and you will see the
country names and abbreviations listed.
Notice that the country names and abbreviations are read only. You cannot change the values here, as
you would if the view object was based on an entity object; you must change the values in the
implementation class.
Link the view object to another view object
11-62
Now that your view object has been completed, you may want to do something more useful with it. For
example, you could link it to LocationsView, which would allow you to scroll through the records country
by country. To do that, you'll need to create a new view link, and edit the application module's data
model.
To create a view link from CountryCodesView to LocationsView:
1. In the Navigation Pane, right click the package node and choose New | View Link.
2. When the View Link Wizard opens, review the information on the Welcome page and click Next
to continue.
3. On the Name page, enter the name CountriesToLocationsLink. Click Next.
4. On the View Objects page, select CountryCodesView as the source and LocationsView as the
destination. Click Next.
5. On the Source Attributes page, select Abbreviation as the source attribute. Click Next.
6. On the Destination Attributes page, select CountryId as the destination attribute. Click Next.
7. Click Finish.
To edit the application module:
1. In the Navigation Pane, right click the application model's node and choose Edit.
2. On the Data Model page, select CountryCodesView and shuttle it to the Data Model pane.
3. In the Data Model pane on the right, click CountryCodesView to select it.
4. Now shuttle LocationsView via CountriesToLocationsLink to the Data Model pane. It will
appear underneath CountryCodesView. LocationsView is now a restricted view in the data
model.
5. Click Finish.
To test your application module:
1. In the Navigation Pane, right click the application model's node and choose Test.
2. When the Business Component Browser dialog appears, click Connect.
3. Double-click CountriesToLocationsLink. You can now browse through the location information
by country.
Conclusion
View objects do not have to be based on a database query. By overriding methods in the
implementation class, you can use whatever data source you want. You can use this view object as you
11-63
would any other view object: you can scroll through records, link it to another view object, and bind a
user interface component to it.
11-64
Implementing Row Set Filters
In the previous release, the ability to create user-defined coordinated row set filters was added.
By default, view links coordinate master/detail rowsets using the equality criteria between
attributes in a source (master) row and a corresponding set of attributes in a destination (detail)
row. If the detail rowset is set to be used in "Association Consistent" mode, then even pending
changes to entity objects in the cache are automatically kept in their appropriate detail rowset.
Using a user-defined view link "Association SQL" clause, available from the View Link Wizard
and Editor, you can define view link relationships that go beyond basic equality with a complex
SQL-based detail query criteria. In addition, these more complicated view links can now keep
their in-memory rowset contents consistent. To do so, view objec's can associate custom row
filters to enable this behavior to work for arbitrarily complex view links.
Code Tasks to Implement Row Filtering
If you are working programmatically with view objects that are view-linked using a custom SQL
Where clause, you can now achieve the same kind of master/detail rowset consistency as is
provided by default for basic equality-based view links. To achieve this, you must:
● Write a class that implements the oracle.jbo.server.RowFilter interface
A row filter is an object that conceptually "owns" a group of related rows based on some
customized grouping criteria. The default implementation defines a filter that "owns" a
group of related rows that match a particular set of key attribute values (e.g. all
employees whose department number = 10).
● Override three methods in the ViewObject implementation class that represents the
detail query in the master/detail view link.
RowFilter buildRowFilter(Object[] paramValues)
This method returns an instance of your custom implementation of a RowFilter instead of

using the default implementation, oracle.jbo.server.RowFilterKey.
RowFilter[] getQualifyingRowFilters(Object[] rowParamValues)
This method returns an array of zero or more matching RowFilters that a candidate row
belongs to.
RowFilter[] buildQualifyingRowFilters(Object[] rowParamValues)
11-65
This method is called to build new RowFilters, if any, to be associated with a candidate
row which does not qualify for any existing RowFilters.
Example of Using Custom Detail Row Set Filtering
See ORACLE_HOME\BC4J\samples\RowFilter for an example that uses the HR schema.

For information on running the sample, see Running Business Components Samples.
The sample illustrates how to use a custom row filter. It uses two view objects to present
employee information grouped into data-driven salary bands, instead of the default way of
grouping them by department number. There is an employees table in the database that this
application is connected to, and an employees entity object mapped to this table.
The query of the SalaryBands view object is
select name as band_name,

lo_value as low_value,
high_value
from salary_bands
There is an employees view object and a view link which shows, for each salary band master
row, the list of employees whose salary falls between the high and low values in the current
band. The employees view object is associated with the employees entity object. The details
view object must be mapped to an entity object for the rowset consistency feature to work.
If you look in the View Object Editor, you see that the view link has the source attributes
LowValue and HighValue. The matching destination attributes are Salary and Salary.
You have to pick the Salary attribute twice because you only need to refer to single attribute in
the destination. In the View Link Properties page, the default association accessor name was
overridden to the more meaningful name "EmployeesInBand". This accessor lets you
programmatically get an attribute by this name on each row of the SalaryBands view to get the
coordinated set of detail records.
In the View Link SQL page, the Where clause is
Employee.SALARY BETWEEN :1 and :2
The application module contains the SalaryBands view object along with its view-linked detail
11-66
employees view object. You can run the Tester to show that querying the salary bands and
employees that falls into the bands works.
In SalaryBandRowImpl.java, RowFilter is implemented so that inserts and updates of employee

rows will automatically be grouped into the right detail employees collection based on the salary
band that the employee's salary falls into.
EmployeesImpl.java overrides the methods required for row filtering. These overrides inform
the framework that you want to use a custom RowFilter implementation, and respond
appropriately to the framework's needs to identify appropriate filters that match a candiate row.
The client demonstrates the functionality:
1. Connects to the application module.

2. Finds the SalaryBands view object to work with
3. Gets the first row of the SalaryBands view (Band1, 0-999)
4. Gets the coordinated set of detail employees in the current salary band by requesting the
view link accessor attribute named "EmployeesInBand".
5. Creates a new employee row in this collection, having a salary which falls outside the 0-
999 range of the current band.
6. Navigates to the second salary band, 1000-2999.
7. Gets the coordinated set of detail employees in that salary band by again requesting the
view link accessor attribute named "EmployeesInBand" on that row
8. Calls setAssociationConsistent(true) on the detail rowset it retrieves so that its contents
will be retrieved in a cache-consistent way (including pending new/modified rows in
addition to ones that are queried).
9. Iterates the detail employees found in the current band to illustrate that the newly added
employee has been automatically "shuffled" into the proper detail rowset based on its
salary band.
Related topics
Synchronizing the Database and Business Logic Tier with the Synchronization Tool
11-67
11-68
Finding an Application Module Instance in Code
The first thing a client must do when it accesses business components is find an instance of the root
application module using the factory model. In this release of Business Components for Java, this
process has been made easier through the use of configurations.
To find an application module instance:
● Use the method

oracle.jbo.client.Configuration.createRootApplicationModule(). Pass this
method the package-qualified name of your application module and the name of the
configuration you want to use. For example, to instantiate OnlineOrders.OnlineOrdersModule
in local mode, you would use:
ApplicationModule myAM =
Configuration.createRootApplicationModule("OnlineOrders.OnlineOrdersModule",
"OnlineOrdersModuleLocal");
11-69
A client can use application module instances from a pool, called application module pooling. It
has these advantages:
● reduces the amount of time to obtain server-side resources
● reduces memory usage by allowing a small number of instances to serve a much larger
number of sessions
● addresses the requirements of web applications that must handle thousands of incoming
requests
● lets you preserve session state between requests and provides failover support
For example, in the case of a web application, you may have 1,000 users but you know that only
100 will be using a certain application module at one time. So you use an application module
pool. When a client needs an application module instance, it takes a free one from the pool and
releases it to the pool after either committing or rolling back the transaction. Because the
instance is precreated, end users are saved the time it takes to instantiate the application
module when they want to perform a task. Typically, web-based JSP clients use pools. If you
want to make sure that the application module pool has a maximum of 100 application module
instances, you can simply set a property.
In this release of Business Components for Java, both application module pooling and
connection pooling have many new features and have been implemented using a new, common
class structure.
One pool manager per Java VM
The framework provides a pool manager to manage the application module pools. There is one
pool manager for each web server's Java VM. Application module instances remain in the pool
until they are removed or the Java VM stops running. You can also specify the maximum
number of instances. The pool manager is defined in the framework class PoolMgr.
One application module pool per application module definition
Typically, there is one application module pool per application module configuration. For
11-70
example, for a web server, there is one pool for each type of application module that clients can
access.
The following illustration shows how three deployed application modules, TaskApp, StatusApp,
and MTBFApp, use application module pooling. TaskApp, StatusApp, and MTBFApp each have
their own application module pools. These pools are managed by the pool manager. Each pool
manages application module instances. The instances are connected to a database server.
New in this release, you can now share application module instances.
How application module instances are created, assigned, and

released
In general terms, the application module pooling feature is implemented as follows:
1. A client sends an HTTP request to a web server.
11-71
2. If the request requires an application module instance, the web application on the web
server first checks if a pool manager has been created. If not, it creates one.
3. The web application requests an application module pool from the pool manager. If one
has not already been created, it is created.
4. The web application checks out an application module instance from the application
module pool.
❍ If the pool contains an idle instance, the application module pool reuses the
instance.
❍ If there isn't an idle instance, the application module pool creates one and returns
the new instance.
5. The web application uses the application module instance to perform the requested
service.
6. The web application releases the application module instance back to the pool. There are
three types of release modes, described later.
After it is released to the pool, the instance can be reused by other pool sessions.
Three release modes are provided by the business components

framework
The web application framework (including Data Web Beans and JSP tags), provided with
Business Components for Java, supports three release modes for application module instances
obtained from a pool. You can decide how instances are allocated, whether their state is
preserved, and whether there is failover support.
● Stateful — In a stateful JSP application, the data tags or data web beans of a JSP
application also do not access the same application module instance each time they are
invoked. However, unlike stateless applications, Business Components for Java saves
the application module state to the database, file, or memory when the application module
is released, and allows a view object's rowset to remain the same from one invocation to
the next. Stateful mode is the preferred choice because it provides failover support from
the database and still allows application modules to be recycled. However, you may need
11-72
to use the stateless mode when you expect many users to access your JSP application
simultaneously. The stateless option may allow more users to access a JSP application
simultaneously. The passivation store can be changed through the jbo.passivationstore
property.
● Stateless — When you select the stateless option for individual JSP pages or the entire
JSP application, the data tags or data web beans do not necessarily access the same
application module instance each time a new page is invoked during a specific HTTP
session and, therefore, cannot depend on a view object's rowset remaining the same from
one invocation to the next. Each HTTP session does not get its own instance for each
application module; instead, all HTTP sessions share a limited pool of instances of each
application module.
● Reserved — When you select reserved mode for individual JSP pages or the entire JSP
application, once a data tag or data web bean has connected to an application module, all
subsequent connections to that application module from any data tag or data web bean
during the same HTTP session involve the same instance of the application module. This
holds true whether a subsequent connection is from another JSP page or from a new
invocation of the same JSP page. This mode is similar to the stateful application, but it
does not provide failover support nor does it permit application modules to be recycled.
Reserved mode is provided primarily for compatibility with application modules that use
non-standard JDBC connections. You can use reserved mode to hold pessimistic locks
between HTTP requests.
See About JSP Pages and Application Module Pooling for more information on how JSP pages
use pooling.
Note that the stateful mode of previous releases is now reserved mode. However, old code
should be backward compatible.
The state of application module instances can be preserved
When you use stateful mode, the transactional state of an application module instance is
maintained between requests. Your program can maintain a user's data without tying up an
application module instance. The state includes the currencies of view objects in the application
module, all modified attributes and new rows, and other view-object–specific states that are
required to resurrect a view object, including queries, the Where clause, Where clause
parameters, and so on. The framework will manage the state for a session, without requiring
cookies.
11-73
For stateful application module check-ins, if failover support has been specified (the default),
then the application module state is persisted to a datastore (a file, database, or memory) when
the application module is checked into the application module pool. If failover support has not
been specified, then application module state is persisted when the application module pool
detects that it must recycle that application module instance. The application module pool
recycles application module instances when an application module is requested, the application
module pool size is greater than the recycle threshold, and there are not any available
application module instances in the pool. The release of an unstateful application module does
not cause the application module state to be persisted. The cookie is used to store a unique
identifier for the application module state in the client browser. The cookie is only generated if
failover support has been specified. The cookie is generated upon stateful application module
release.
For Java servlets, you use methods in the SessionCookie interface, as demonstrated in the
sample in ORACLE_HOME\BC4J\\samples\Pooling.
When using stateful mode, your program must meet the following conditions:
● Pessimistic locking is not permitted.
● There should not be any uncommitted, posted changes. All changes are preserved,
whether they were committed or not. For example, if you called the postChanges method
to cause a database trigger to fire but you didn't commit, you could get conflicts when a
row is restored because the trigger fires more than once.
Note: When your application module state is saved, the data in the cache is saved. If there are
changes in the database, there is no guarantee that they will be reflected in your saved data
when you check the application module state back out. For example, if the application module
was not recycled, the data stays the same. However, if the application module was recycled and
then activated through failover, the activation logic reexecutes the view objects, so it may bring
in more or less rows than originally seen by the clients due to any database updates that have
occurred.
Timeouts prevent tying up application module instances
What happens if a user leaves a browser open for a long period of time, such as to get some
coffee? Does the the Pool Manager release the application module to the pool?
If the release mode is reserved, the application module is release to the pool after the
HttpSession is timed out by the web server. The application module state is not persisted if the
session is timed out. See the J2EE specification for more information about session timeout.
11-74
If the release mode is stateful, the application module is released after the page is displayed and
the state is persisted immediately, if failover support has been requested.
Application module instances can be failover protected
In case the business logic tier or database becomes inoperable, such as from a power failure,
you may want to preserve application module states in the database. To do so, you can enable
failover support, which is the default. The disadvantage is that storing data in a database makes
business logic tier operation somewhat slower.
The number of application module instances can be controlled
You can set the maximum pool size and the initial pool size. In addition, you can manage an
average number of active application module instances in the pool with the high water mark
functionality.
Related Topics
Pooling Application Modules
About Application Module Pooling Classes
11-75
You can perform the following tasks to implement application module pooling, including new
features implemented in this release:
● Enabling and Disabling Failover
● Enabling and Disabling Connection Pooling
● Setting the Maximum Cookie Age
● Setting the Pool Recycle Threshold
● Setting the Maximum Pool Size
● Setting the Initial Pool Size
● Setting the Pool High Water Mark
● Managing Non-Transactional State for Application Module Pooling
● Implementing Pooling in Application Module Code
● Implementing a Custom Application Module Pool
In addition, the application module pool supports a dumpPoolStatistics(PrintWriter)

method that you can use to retrieve statistical information about a pool.
For more information on JSP and application module pooling, see About Configuration
Properties for a JSP Project.
Related Topics
11-76
About Configuration Properties for a JSP Project
11-77
Enabling and Disabling Failover for Application
Module Instances
When you are using application module pooling, you can provide failover support. The default is
enabled.
To disable failover support:
When you start the business logic tier's Java VM, include the following directive on the
command line:
-Djbo.dofailover=false
A value of true enables failover.
Alternatively, you can enter a line in the jboserver.properties file, which is stored in
$JDEV_HOME/BC4J/lib/bc4jmt.jar. During deployment, you need to include the file.
jbo.dofailover=false
To set Java options through project properties:
1. In the the Navigator, right-click a business component project (JPR file) and choose
Project Settings.
2. In the left panel of the Project Settings dialog, select Runner in the tree under
Configurations | Development.
3. Type the parameters in the Java Options field.
4. Click OK.
The values are added to the jboserver.properties file, which is stored in

$JDEV_HOME/BC4J/lib/bc4jmt.jar.
11-78
Related Topics
11-79
Enabling and Disabling Connection Pooling when
Using Application Module Pooling
You can enable and disable connection pooling when using the application module pooling
feature. By default, it is disabled.
To enable connection pooling:
command line:
-Djbo.doconnectionpooling=true
A value of false disables failover.
Alternatively, you can enter a line in the jboserver.propertiesfile, which is stored in

jbo.doconnectionpooling=true
Project Settings.
4. Click OK.

11-80
Related Topics
11-81
Setting the Maximum Cookie Age for Application
Module Pooling
By default, the cookie age is -1 (when you shut down the browser, the cookie goes away). To
change this behavior, you can set a cookie age. This property is failover-specific. It specifies
how long the state ID is managed by the browser.
To set the cookie age:
command line:
-Djbo.maxpoolcookieage=age
The age is in seconds from 0 to 2,147,483,647. -1 means the cookie is transient.
jbo.maxpoolcookieage=age
Project Settings.
4. Click OK.

11-82
Related Topics
11-83
Setting the Pool Recycle Threshold
You can tell the pool when it should start recycling existing, inactive application module
instances. The pool recycle threshold is the number of application module instances the pool
manager will create before recycling application module instances that have an associated
session. It's default value is 10.
The tradeoff between high and low values is performance versus memory usage. A high
recycle threshold reduces checkout times, because the pool doesn't have to reactivate an
application module instance state as frequently. The cost is more application module instances
in the pool.
To set the pool recycle threshold:
command line:
-Djbo.recyclethreshold=n
n is a number from 0 to 2,147,483,647.
jbo.recyclethreshold=n
Project Settings.
4. Click OK.
11-84
Related Topics
11-85
Setting the Initial Pool Size
The initial pool size defines the initial number of application module instances in a pool. Pool
initialization is performed in a low priority thread to prevent blocking active users from
accessing the pool. The default initial pool size is zero (0).
To set the initial pool size:
command line:
-Djbo.ampool.initpoolsize=n
jbo.ampool.initpoolsize=n
Project Settings.
4. Click OK.

11-86
Related Topics
11-87
Setting the Maximum Pool Size
The maximum pool size defines the maximum number of application module instances that an
application module pool may reference. The default is 2147483647.
When the pool size has reached the maximum pool size, no new application module instances
can be created in that pool. Consequently, pool requests that are made when there are no
available pool instances are blocked for a configurable time period until an instance becomes
available. If the wait time period is exceeded, then a pool exception is thrown indicating that a
request thread timed out while waiting for an available instance.
To set the maximum pool size:
command line:
-Djbo.ampool.maxpoolsize=n
jbo.ampool.maxpoolsize=n
Project Settings.
4. Click OK.
11-88
Related Topics
11-89
Setting the Pool High Water Mark for Application
Module Instances
You can manage an average number of active application module instances in the pool with the
high water mark functionality. If the release mode is stateful (and failover is disabled), or
stateless (and resetnontransactionalstate=false), the pool will properly preserve the state of the
application module instance before release.
A single daemon thread monitors all application module pools. This thread periodically signals
each pool that they should resolve their high water marks. This allows the pool to remain large
or highly available during periods of high activity. For example, assume that 100 sessions are
hitting a pool with a high water mark value of 25 for a period of 10 minutes. When application
module instances are checked back into the pool, if the pool released the number of application
module instances greater than the high water mark, every release/use during that 10 minute
period of high activity would result in an application module instance creation and removal. With
the current high water mark implementation, however, the pool size could remain at 100 for the
10 minute period of high use.
The high water mark functionality is configurable with the following four application module pool
parameters:
● jbo.ampool.maxavailablesize (default 25) — defines the maximum number of inactive,

available instances that should be managed by the pool
● jbo.ampool.minavailablesize (default 5) — defines the minimum number of inactive,
available instances that should be managed by the pool
● jbo.ampool.maxinactiveage (default 600000ms or 10min) — defines the maximum period
of time that an application module may remain inactive before it is a candidate for
removal
● jbo.ampool.monitorsleepinterval (default 600000ms or 10min) — defines the amount of
time that the monitor thread should sleep between
high water mark triggers
Application module instances are removed from the pool as follows:
1. The pool manager compares the number of inactive, available instances in the pool
against the minimum available instance size. If the number of inactive, available
instances is greater than the minimum available instance size, then the pool will attempt
to remove any inactive, available instances. An inactive instance is defined as an
instance that has been unused for a period longer than the pool's maximum inactive age.
11-90
The pool will continue to remove inactive, available application module instances until the
minimum available instance size has been reached or there are no more inactive,
available instances.
2. The pool manager compares the number of available instances in the pool against the
maximum available instance size. If the number of available instances is greater that the
maximum available instance size, the pool attempts to remove any available instances.
The pool will continue to remove available instances until the maximum available
instance size has been reached or there are no more available instances.
To set the maximum number of application module instances:
command line:
-Djbo.ampool.maxavailablesize=n
jbo.ampool.maxavailablesize=n
To set the minimum number of application module instances:
command line:
-Djbo.ampool.minavailablesize=n
jbo.ampool.minavailablesize=n
To set the maximum time an instance can be inactive:
11-91
command line:
-Djbo.ampool.maxinactiveage=n
n is the number of milliseconds from 0 to 2,147,483,647.
jbo.ampool.maxinactiveage=n
To set the time interval between high water mark processing:
command line:
-Djbo.ampool.monitorsleepinterval=n
jbo.ampool.monitorsleepinterval=n
Project Settings.
4. Click OK.
11-92
Related Topics
11-93
Managing Non-Transactional State for Application
Module Pooling
When you are using stateless mode, you can specify that non-transactional application module
state should be preserved by the pool between requests. Examples of non-transactional state
include cached JDBC prepared statements, dynamic where clauses, view object instances, and
application module object instances. Examples of transactional state include any database
state and the state of the entity and view caches.
The default value of the property is currently true, so it does reset non-transactional state. This
is was the behavior for version 3.2. For example, this default setting prevents any confusion or
security leaks that could result from session two reusing a dynamic where clause that was
specified during session one.
If you need to preserve non-transactional state between stateless requests, such as cached
JDBC statements, set this property to false.
The tradeoff between settings is memory versus performance.
Warning: Be careful when setting this property to false. You could inadvertantly share secure
information, such as data in Where clauses, between sessions.
To enable preservation of non-transactional state:
command line:
-Djbo.ampool.resetnontransactionalstate=false
A value of true enables resetting non-transactional state.
jbo.ampool.resetnontransactionalstate=false
11-94
Project Settings.
4. Click OK.

Related Topics
11-95
Implementing Pooling in Application Module Code
One of the tasks you must perform to enable application module pooling is to set up the environment
information needed to connect to the application module. The information you supply will depend on
the platform on which the application module resides. To find out more about the code you need to
supply to set up the environment for the various platforms, see Setting up the Environment.
For a sample developed for new features in this release, see

ORACLE_HOME\BC4J\samples\Pooling. This sample uses the HR schema, which is provided
with Oracle9i. See Creating and Populating the Database Tables for information on how to install the
tables when you are using another database version.
Note that the way that the pool name is derived for an application pool that was created with the
ApplicationModuleTag has changed. The pool
name is now derived from the ApplicationModuleTag configName attribute instead of the id attribute.
This change was necessary
to support multiple applications in a request with a single pool. If an application is using the method,
oracle.jbo.common.ampool.PoolMgr.getPool(String), the application should be migrated to use the
ApplicationModuleTag's configName as the pool name instead of the ApplicationModuleTag's id.
An example implementation of a stateful application
The PoolTester class provides a sample implementation and use of application module pooling in
LOCAL mode. This example uses the default implementation of application module pooling.
1 public class PoolTester extends Object {
2 /**
3 * Constructor
4 */
5 public PoolTester() {
6 }
7 public void doTest() throws Exception

8 {
9 Hashtable env = new Hashtable(10);
10 env.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
11 env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);
12 PoolMgr.getInstance().createPool("TestAMPool", "Package1.MyAppMod",
"jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", env);
11-96
13 PoolMgr.getInstance().createPool("SecondAMPool", "Package2.MyAppMod",
14 ApplicationPool pool = PoolMgr.getInstance().getPool("TestAMPool");
15 ApplicationModule instance = pool.checkout();
16 ApplicationModule instance2 = pool.checkout();
18 ApplicationPool pool2 = PoolMgr.getInstance().getPool("SecondAMPool");
19 ApplicationModule instance22 = pool2.checkout();
21 String sessionId = pool2.checkinWithSessionState(instance22);
22 instance22 = pool2.checkout(sessionId);
23 PoolMgr.getInstance().removePool("TestAMPool");
24 }
Lines 9-11: Define the environment settings. This can be done directly (as is demonstrated here) or
from a property file. In this example, the hashtable contains the properties to set up the environment
to connect in LOCAL mode. For more information about the code you need to supply to set up the
environment for LOCAL mode and the other platforms, see Setting up the Environment.
Line 12: Create the pool TestAMPool. Since PoolMgr is a singleton object, use
PoolMgr.getInstance to get it. Use createPool to create the pool. Notice that createPool
requires the name of the pool, the name of the package that contains the application module, the
connect string to the database, and env, the hashtable. The createPool method is
overloaded—an alternative version takes an additional parameter that lets you override the default
implementation of application module pooling and specify your own.
Line 13: Create a second pool, SecondAMPool that connects with the same environment variables,
11-97
but to an application module in a different package.
Line 14: PoolMgr.getInstance().getPool("TestAMPool") gets a handle to the pool to work

with it.
Lines 15-17: Checkout three instances. Note that the classes ApplicationPoolImpl and
PoolMgr contain other functions that you can use to traverse the pool content. The ampool
package also contains a PoolAdministrator Web Bean that you can use to dump the contents of
the pool.
Lines 18-20: Get a handle to the second pool, check out two instances.
Lines 21-22: Check in an application module instance in a stateful fashion, stroring the session ID in
a local String. Check out an application module with the same state that was checked in.
Line 23: Use removePool to remove the application module pool. This function calls remove() on
all of the application module instances, including ones that are currently checked out and in use, and
causes them to disconnect from the database and remove all of their view objects.
An example implementation of a stateless application
The PoolTester class provides a sample implementation and use of application module pooling in
LOCAL mode. This example uses the default implementation of application module pooling.
2 /**
3 * Constructor
4 */
6 }

8 {
9 Hashtable env = new Hashtable(10);
10 env.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
11 env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);
12 PoolMgr.getInstance().createPool("TestAMPool", "Package1.MyAppMod",
11-98
13 PoolMgr.getInstance().createPool("SecondAMPool", "Package2.MyAppMod",
14 ApplicationPool pool = PoolMgr.getInstance().getPool("TestAMPool");
15 ApplicationModule instance = pool.checkout();
18 ApplicationPool pool2 = PoolMgr.getInstance().getPool("SecondAMPool");
21 pool2.checkin(instance22);
22 PoolMgr.getInstance().removePool("TestAMPool");
23 }
from a property file. In this example, the hashtable contains the properties to set up the environment
to connect in LOCAL mode. For more information about the code you need to supply to set up the
Line 12: Create the pool TestAMPool. Since PoolMgr is a singleton object, use
PoolMgr.getInstance to get it. Use createPool to create the pool. Notice that createPool
requires the name of the pool, the name of the package that contains the application module, the
connect string to the database, and env, the hashtable. The createPool method is
overloaded—an alternative version takes an additional parameter that lets you override the default
implementation of application module pooling and specify your own.
Line 13: Create a second pool, SecondAMPool that connects with the same environment variables,
but to an application module in a different package.
Line 14: PoolMgr.getInstance().getPool("TestAMPool") gets a handle to the pool to work
11-99
with it.
Lines 15-17: Checkout three instances. Note that the classes ApplicationPoolImpl and
PoolMgr contain other functions that you can use to traverse the pool content. The ampool
package also contains a PoolAdministrator Web Bean that you can use to dump the contents of
the pool.
Lines 18-21: Get a handle to the second pool, check out two instances, then check in one.
Line 22: Use removePool to remove the application module pool. This function calls remove() on
all of the application module instances, including ones that are currently checked out and in use, and
causes them to disconnect from the database and remove all of their view objects.
Related Topics
11-100
Implementing a Custom Application Module Pool
You can create your own custom implementations of application module pooling by extending the
ApplicationPoolImpl class and overriding the methods you need. For example, you can define a
class, CustomPool, that ensures that no more than three instances are checked out of the pool at any
time. In this case, the definition of the checkout method is overridden to check that no more than
three instances are checked out. If more than three are checked out, an exception is thrown.

ORACLE_HOME\BC4J\samples\Pooling. This sample uses the HR schema, which is provided with
Oracle9i. See Creating and Populating the Database Tables for information on how to install the tables
when you are using another database version.
Note that the application pool interface has been updated to include a number of new methods which
were required to support new application pool features. The new methods may effect applications
which have developed custom application pools which DO NOT extend the default application pool
implementation, oracle.jbo.common.ampool.ApplicationPoolImpl. Those applications will receive
compilation exceptions when compiling the custom application pool class against the Oracle9i Business
Components for Java runtime. In order to workaround this issue, those applications should upgrade the
custom pool implementations to either extend the default implementation (preferred) or to implement
the new application pool methods.
1 /**
2 ** This is a simple application pool class that allows checkout
3 ** of only three instances.
4 **/
5 class CustomPool extends ApplicationPoolImpl
6 {
7 public CustomPool()
8 {
9 }
10 /**
11 * Ensures that only three instances are
12 * checked out of the pool. Otherwise, a
13 * RuntimeException is thrown.
14 *
15 * @return oracle.jbo.ApplicationModule
16 */
17 public synchronized ApplicationModule createNewInstance()
18 {
19 // if the instance count > 3 throw an exception
20 int nCount = getInstanceCount();
21 if(nCount > 3)
22 {
23 throw new RuntimeException("You have exceeded the number of
11-101
instances for this pool");
24 }
25 return super.checkout();
26 }
27 }
Line 5: Create a CustomPool class that extends ApplicationPoolImpl.
Lines 17-23: Override the checkout method to test whether more than three instances are checked
out. If more than three are checked out, throw a RuntimeException.
Using the custom application module pool Implementation
You can then use the CustomPool class in your programs.
2 /**
3 * Constructor
4 */
6 }
8 {
9 Hashtable info = new Hashtable();
10 info.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
11 info.put(JboContext.DEPLOY_PLATFORM, "LOCAL");
12 // create a pool with a custom application pool class

13 PoolMgr.getInstance().createPool("CustomTestAMPool",
"oracle.jbo.common.ampool.CustomPool" , "package2.Package2Module" ,
"jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", info);
14 pool = PoolMgr.getInstance().getPool("CustomTestAMPool");
15 try
16 {
17 instance = pool.checkout();
11-102
22 }
23 catch(Exception ex)
24 {
25 ex.printStackTrace();
26 }
27 }
from a property file. In this example, the hashtable contains the properties to set up the environment to
connect in LOCAL mode. For more information about the code you need to supply to set up the
Lines 12-14: Use the CustomPool class to create the pool CustomTestAMPool. Since PoolMgr is a
singleton object, use PoolMgr.getInstance to get it. Use createPool to create the pool. Notice
that in this case, createPool requires the name of the pool, the name of the class that overrides the
default implementation of application module pooling, the name of the package that contains the
application module, the connect string to the database, and the name of the hashtable.
Lines 15-25: Set up a try-catch loop to start checking out instances and to catch exceptions. The
pool.checkout() in line 20 should cause an exception to be thrown.
Related Topics
11-103
About Connection Pooling
Since version 3.2 of Business Components for Java, connection pooling is the default behavior.
Instead of one JDBC connection being created for each application module instance, and being
destroyed when the instance disconnects, application module instances can now reuse a pool
of connections.
In this release of Business Components for Java, both application module pooling and
connection pooling have many new features and have been implemented using a new,
common class structure.
Faster client response times
Opening a connection to a database is a time-consuming process that can sometimes take

longer than getting the data itself. The advantage of connection pooling is that clients can have
faster response times, because they are saved the time of creating the database connection.
Instead, they can reuse a connection in an application module instance that already exists.
One connection pool per connection URL
There is one connection pool for each JDBC connection URL, which includes the username
and password. Here is a sample connection URL:
jdbc:oracle:thin:scott/tiger@myhost:1521:ORCL
For example, if you have three separate databases (one each of Oracle9i, Oracle Lite, and a
foreign database), the following connection types would have separate connection pools:
● Oracle9i with username jsm and password tiger
● Oracle9i with username scott and password tiger
● Oracle Lite with username scott and password tiger
● Foreign database with username pam and password tiger
As a result, connection pooling is most useful when many people log in to the same database
using the same username and password.
11-104
How connections are created, assigned, and released
The framework provides a connection pool manager to manage the pool. When a database
connection is needed by a top-level application module instance, the following sequence of
events occurs:
1. The application module instance asks the connection pool manager for a connection, as
specified in the JDBC connection URL.
2. The connection pool manager looks for an available connection in the pool. If there isn't
one, it creates one, up to the maximum allowable connections. If it can't create a
connection, it waits for one (up to the timeout value).
3. When the application module instance disconnects, the connection goes back to the
pool.
There is one connection pool manager for each business logic tier's Java VM. Connections
remain in the pool until they are released or the Java VM stops running. The default maximum
number of connections is a very large number, so it is essentially the number of connections
supported by your database driver.
Other options
In addition to using the default behavior, you have these options:
● You can set the maximum and initial number of connections in a pool.
● You can manage an average number of active connections in the pool with the high
water mark functionality.
● You can disable connection pooling.
● You can set the wait for connection timeout.
● You can create and use a custom connection pool manager.
11-105
Related Topics
Pooling Connections
11-106
Pooling Connections
Connection pooling is the default behavior. Instead of one JDBC connection being created for
each application module instance, and being destroyed when the instance disconnects,
application module instances can now reuse a pool of connections.
Here are the tasks you can perform related to connection pooling, including new features for
this release:
● Enabling and Disabling Connection Pooling
● Setting the Initial Number of Pool Connections
● Setting the Maximum Number of Pool Connections
● Setting the Pool High Water Mark for Connections
● Setting the Connection Pool Wait Timeout
● Using a Custom Connection Pool Manager
In addition, the connection pool supports a dumpPoolStatistics(PrintWriter) method

that you can use to retrieve statistical information about a pool.
Related Topics
11-107
Enabling and Disabling Connection Pooling
In Business Components for Java, if you disable connection pooling, there will be one
connection per application module instance. The connection is destroyed when the application
module instance disconnects. This was the behavior prior to version 3.2 of Business
Components for Java.
To disable connection pooling:
command line:
-Djbo.maxpoolsize=0
$JDEV_HOME\BC4J\lib\bc4jmt.jar:
jbo.maxpoolsize=0
To enable connection pooling:
Make sure the maxpoolsize is not zero (0), but a number from 1 to 2,000,000. The default is
2,000,000, limited by the number of connections supported by your database driver. See
Setting the Maximum Number of Pool Connections.
Project Settings.
4. Click OK.

11-108
Related Topics
Pooling Connections
Using a Custom Connection Pool Manager
11-109
Setting the Initial Number of Pool Connections
In Business Components for Java, you can specify a Java VM parameter (-D) or
jboserver.properties property that sets the initial number of connections in the pool. The default
is zero (0).
To set the initial pool size:
command line:
-Djbo.initpoolsize=n
n is the number of connections in the pool, from 0 to 2,147,483,647. The number of

connections is limited by the number of connections supported by your database driver.
$JDEV_HOME/BC4J/lib/bc4jmt.jar:
jbo.initpoolsize=n
Project Settings.
4. Click OK.

11-110
Related Topics
Pooling Connections
11-111
Setting the Maximum Number of Pool Connections
jboserver.properties property that sets the maximum number of connections in the pool. The
default maximum number of connections is a very large number, so it is essentially the number
of connections supported by your database driver, up to 2147483647.
To set the maximum pool size:
command line:
-Djbo.maxpoolsize=n
n is the number of connections allowed per pool, from 1 to 2,147,483,647 (the default). The
number of connections is limited by the number of connections supported by your database
driver. If view row spillover or application module state preservation is required, the maximum
poolsize should be set to two times the expected number of active (connected) application
modules.
jbo.maxpoolsize=n
Project Settings.
4. Click OK.
11-112
Related Topics
Pooling Connections
11-113
Setting the Pool High Water Mark for Connections
You can manage an average number of active connections in the pool with the high water mark
functionality.
A single daemon thread monitors all connection pools. This thread periodically signals each
pool that they should resolve their high water marks. This allows the pool to remain large or
highly available during periods of high activity. For example, assume that 100 sessions are
hitting a pool with a high water mark value of 25 for a period of 10 minutes. When connections
are checked back into the pool, if the pool released the number of connections greater than the
high water mark, every release/use during that 10 minute period of high activity would result in
a connection creation and removal. With the current high water mark implementation, however,
the pool size could remain at 100 for the 10 minute period of high use.
The high water mark functionality is configurable with the following four connection pool
parameters:
● jbo.poolmaxavailablesize (default 25) — defines the maximum number of inactive,

available connections that should be managed by the pool
● jbo.poolminavailablesize (default 5) — defines the minimum number of inactive, available
connections that should be managed by the pool
● jbo.poolmaxinactiveage (default 600000ms or 10min) — defines the maximum period of
time that a connection may remain inactive before it is a candidate for removal
● jbo.poolmonitorsleepinterval (default 600000ms or 10min) — defines the amount of time
that the monitor thread should sleep between
high water mark triggers
Connections are removed from the pool as follows:
1. The pool manager compares the number of inactive, available connections in the pool
against the minimum available connection size. If the number of inactive, available
connections is greater than the minimum available connection size, then the pool will
attempt to remove any inactive, available connections. An inactive connection is defined
as an connection that has been unused for a period longer than the pool's maximum
inactive age. The pool will continue to remove inactive, available connections until the
minimum available connection size has been reached or there are no more inactive,
available connections.
2. The pool manager compares the number of available connections in the pool against the
maximum available connection size. If the number of available connections is greater
11-114
that the maximum available connection size, the pool attempts to remove any available
connections. The pool will continue to remove available connections until the maximum
available connection size has been reached or there are no more available connections.
To set the maximum number of connections:
command line:
-Djbo.poolmaxavailablesize=n
jbo.poolmaxavailablesize=n
To set the minimum number of connections:
command line:
-Djbo.poolminavailablesize=n
jbo.poolminavailablesize=n
To set the maximum time an connection can be inactive:
command line:
-Djbo.poolmaxinactiveage=n
11-115
jbo.poolmaxinactiveage=n
To set the time interval between high water mark processing:
command line:
-Djbo.poolmonitorsleepinterval=n
jbo.poolmonitorsleepinterval=n
Project Settings.
4. Click OK.

11-116
Related Topics
Pooling Connections
11-117
Setting the Connection Pool Wait Timeout
jboserver.properties property that sets the amount of time the connection pool manager will
wait for an available connection when one isn't immediately available. The default is 30
seconds.
To set the connection pool wait timeout:
command line:
-Djbo.poolrequesttimeout=n
n is the amount of time, in milliseconds, from 0 to 2,147,483,647.
$JDEV_HOME/BC4J/lib/bc4jmt.jar:
jbo.poolrequesttimeout=n
Project Settings.
4. Click OK.

11-118
Related Topics
Pooling Connections
11-119
In Business Components for Java, the default connection pool manager is an
oracle.jbo.server.ConnectionPoolManagerImpl object, which implements the
oracle.jbo.ConnectionPoolManager interface.
You might want to implement a custom connection pool manager if you have an existing
connection pool manager you want to use or need special functionality not provided by the
default connection pool manager.

ORACLE_HOME\BC4J\samples\Pooling. This sample uses the HR schema, which is
provided with Oracle9i. See Creating and Populating the Database Tables for information on
how to install the tables when you are using another database version.
To create and use a custom connection pool manager:
1. Implement the oracle.jbo.ConnectionPoolManager interface in your custom connection

pool manager.
See the Javadoc for more information on this interface and where to find the default
connection pool manager.
2. Specify the custom connection pool manager (a fully qualified class name) by using the
jbo.ConnectionPoolManager Java VM parameter or jboservers.properties property.
❍ When you start the business logic tier's Java VM, include a directive similar to the
following on the command line
-Djbo.ConnectionPoolManager=oracle.jbo.server.ConnectionPoolManagerImpl
This directive specifies the default connection pool manager.
❍ Alternatively, you can enter a line in the jboserver.properties file, which is stored in
\lib\jbomt.zip. You can deploy the custom jboserver.properties with customer
application. Be sure that the zip file and file path that includes the customer's
version of jboserver.properties appears on the application classpath before
jbomt.zip
11-120
jbo.ConnectionPoolManager=oracle.jbo.server.ConnectionPoolManagerImpl
Related Topics
Pooling Connections
11-121
About Pooling Classes
This topic lists the classes used to implement pooling: application module pooling and
connection pooling. New in this release, both types of pooling use the same base classes. See
the Javadoc for more information about these classes.
Base classes:
oracle.jbo.pool.ResourcePoolManager
oracle.jbo.pool.ResourcePool
oracle.jbo.pool.ResourcePoolLogger
oracle.jbo.pool.ResourcePoolMonitor
Application pooling:
oracle.jbo.common.ampool.ApplicationPool interface
oracle.jbo.common.ampool.ApplicationPoolImpl class
oracle.jbo.common.ampool.ConnectionStrategy interface
oracle.jbo.common.ampool.DefaultConnectionStrategy class
oracle.jbo.common.ampool.SessionCookie interface
oracle.jbo.common.ampool.SessionCookieImpl class
oracle.jbo.common.ampool.SessionCookieFactory interface
oracle.jbo.common.ampool.DefaultSessionCookieFactory class
oracle.jbo.common.ampool.EnvInfoProvider interface
oracle.jbo.common.ampool.SharedSessionCookieFactory class
oracle.jbo.common.ampool.SharedSessionCookieImpl class
oracle.jbo.common.ampool.ApplicationModuleRef interface
oracle.jbo.common.ampool.ApplicationPoolLogger
oracle.jbo.http.HttpSessionCookieFactory class
oracle.jbo.http.HttpSessionCookieImpl class
Connection Pooling:
oracle.jbo.server.ConnectionPoolManager class
oracle.jbo.server.ConnectionPoolManagerImpl class
oracle.jbo.server.ConnectionPool
If you are writing a custom servlet, you need to use a few classes to use application module
11-122
pooling. Application module pooling is controlled by classes in the
oracle.jbo.common.ampool package. The class JSPApplicationRegistry in the
oracle.jbo.html.jsp package, provide the functionality to instantiate an application
module, enable Data Web Beans to use the application module pool, and to create new pools.
11-123
Implementing XML Messaging
Sun Microsystems, Inc. provides a Java Message Service (JMS) API, and Oracle9i provides an
Advanced Queueing API, that you can use with Business Components for Java to implement
XML messaging.
To do so, you use business component framework methods in the ViewObjectImpl and
ViewRowImpl classes which enable the reading and writing of a canonical format of XML data:
● writeXML — Writes the current object into an XML Element, which can be added to any
XML Document, including as a payload for an XML Message. New in this release,
writeXML has new parameters to break cycles and be more selective about how to
generate the XML data, as described in the Javadoc.
● createXMLDefinition — Creates an XML DTD for a ViewObject or ViewRow.
● readXML — Reads the attribute values or rows in this object from the XML Element,
which could be derived from an XML Document or an XML Message.
The XML messaging sample shows you how to implement a working messaging system. In
addition, it provides the general steps you need to follow to implement XML messaging. See
$ORACLE_HOME\BC4J\samples.
For more information on business component methods, see the Javadoc. For more information
on JMS, see the Javasoft web site. For more information on Advanced Queueing, see your
Oracle9i documentation.
Related topics
Using XML Metadata Properties that Effect XML Generation
11-124
About Intersection Tables
Intersection tables are used to specify many-to-many relationships between database tables.
You need to create intersection tables before you can create many-to-many associations.
For example, consider the tables PRODUCT_INFORMATION (a table of products) and

WAREHOUSES (a table of warehouses). You might want to express a many-to-many
relationship between these tables: One warehouse can stock many products, and one product
can be carried by many warehouses. To do this, you need to create an intersection table. The
OrderEntry schema contains such an intersection table: INVENTORIES. The INVENTORIES
table contains two foreign keys: PRODUCT_ID, which points to PRODUCTS , and
WAREHOUSE_ID, which points to warehouses:
You can combine these two one-to-many relationships to create a single many-to-many
relationship: A single product is related to many inventories, each of which is related to a
warehouse. So, from each product, you can get many warehouses. A single warehouse is
related to many inventories, each of which is related to a product. So, from each warehouse,
you can get many products. You might want to create this information if you want to know
which warehouses stock each particular product and/or which products can be found in each
particular warehouse.
Related Topics
Creating a Many-to-Many Association
Ways to Create a Many-to-Many View Link
11-125
1. Create an entity object for your intersection table.
2. Create or edit an association.
3. Specify that you want a many-to-many relationship on the Association Properties page.
Related Topics
11-126
In a many-to-many view link, any row of the source can correspond to many rows of the
destination, and any row of the destination can correspond to many rows of the source. This
feature is new in this release.
There are two ways to create many-to-many view links.
Method Use This Option If...
Creating a Many-to-Many View Link Based on an You want your view link to be bidirectional, and the
source and destination attributes in your view objects
Association
come from underlying entities.
The source and destination attributes in your view
Creating a Pure SQL Many-to-Many View Link objects do not come from underlying entities, and you do
not need your view link to be bidirectional.
You cannot create a many-to-many, bidirectional view link with source and destination
attributes that do not come from underlying entity objects.
Related Topics
11-127
Creating a Many-to-Many View Link Based on an
Association
If the source and destination attributes you want to join in a many-to-many view link are both
based on underlying entity attributes, you may want to base your view link on a many-to-many
association between the entity objects. This allows you to make your view link bidirectional. If
your source or destination attributes are not based on underlying entity attributes, see Creating
a Pure SQL Many-to-Many View Link.
To create a many-to-many view link based on an association:
1. Identify the entity objects that underly your source and destination attributes.
2. Create a many-to-many association between these entity objects.
3. Create a view link.
4. On the Source Attributes page of the View Link Wizard, select the association you
created and shuttle it to the Selected list.
5. Do the same on the Destination Attributes page.
11-128
Creating a Pure SQL Many-to-Many View Link
If the source or destination attributes you want to join in a many-to-many view link are not
based on underlying entity attributes, you cannot base the view link on an association. In this
case, you must edit the SQL in the view link.
Note: You will not be able to make a pure sql view link bidirectional. If you need a bidirectional
view link, base your view attributes on underlying entity objects, and base the view link on an
association.
To create a pure SQL many-to-many view link:
1. Identify the tables from which you draw your source and destination attributes.
2. Create an intersection table for those tables.
3. Edit your source view object.
4. Select the Query page of the View Object Editor.
5. Select Expert Mode.
6. Edit the FROM clause of your query to include your intersection table.
7. Create a view link.
8. On the Source Attributes page, shuttle your source attributes to the Selected list.
9. On the Destination Attributes page, shuttle your destination Attributes to the Selected list.
10. On the View Link SQL page, edit the Where field so that it reads:
:1=<intersection>.<sourceAttr> AND
<intersection>.<destAttr>=<destination>.<destAttr>
for example, if you were using the Order Entry schema, your Wherefield might read:
:1=Inventories.PRODUCT_ID AND
Inventories.WAREHOUSE_ID=Warehouses.WEREHOUSE_ID
11-129
About Business Components Service Beans
In general, when you deploy your business components as Enterprise JavaBeans, you should
deploy them as Application module session beans, which allow you to take advantage of the
tier-independent business components architecture. However, the business components
framework also allows you to deploy business components as service beans, which are generic
EJBs that themselves call application modules in local mode.
Note that you do not have to use service beans to be J2EE-compliant. Application module
session beans are genuine EJB session beans that fully conform to J2EE; they simply have
helper classes in the business components libraries that handle EJB architecture for you.
How Service Beans Work
When you deploy your business components as a service bean, JDeveloper creates a simple
EJB session bean and deploys both the session bean and the application module as separate
classes. The EJB can make calls to the application module just as a client in local mode does.
Just as you can with other deployment modes, you can export methods on an application
module deployed as a service bean. These methods will be published to the EJB's remote
interface and accessible from the client using RMI. Unlike other deployment modes, however,
the business components framework base methods (the methods on the interfaces in the
oracle.jbo package) will not be automatically accessible in the client tier. You must add
these methods to the remote interface yourself if you want clients to be able to use them.
Advantages and Disadvantages of Service Beans
Service beans have the following advantages over application module session beans:
● No business components libraries are required with client code
Because service beans do not use the business components architecture to handle
remote access, clients of service beans do not need access to any business components
libraries.
● Complete control over access to data
The business components framework allows you great control over what access clients
have to data by overriding the framework methods in your business components.
11-130
However, if you need an even finer-grained level of control over client access to your
data, you can use a service bean and only expose custom methods to your clients.
Service beans have the following disadvantages:
● Not tier-independent
Normally, the business components framework handles all issues of cross-tier

communication for you. If you use service beans, you must manually code to the EJB
architecture.
● Doesn't manage remoteable rowsets
Normally, the business components framework allows clients remote access to rowsets
that are continually refreshed as your business logic changes them. Service beans do
not automatically provide client access to or synchronization of rowsets.
● No client architectures
Because service beans do not manage remotable rowsets, you cannot use them with
JClient or business components JSP clients.
When to Use Service Beans
In general, you should not use service beans in any situation where your clients need highly
interactive access to data. Service beans are best for batch processing jobs: cases where, in a
single roundtrip, your client will call a custom method which will perform extensive processing in
the business logic tier.
11-131
About Container-Managed and Bean-Managed
Transactions
In general, root-level application modules handle their own transactions. The application
module API provides all the control over transactions most applications need.
However, if you deploy an application module as an EJB session bean (including as a service
bean) to Oracle 9iAS, you can choose to have the EJB container manage your transactions.
There are two reasons to do this:
● You want different root-level application modules to share a transaction

● You want complete control over the transaction from the client
Note that you should only use container-managed transaction in these two cases; in general,
bean-managed transactions are simpler and have no disadvantages.
You can choose which transaction type to use on the Remote page of the Application Module
Wizard.
Container-Managed Transactions Let You Share Transactions

Between Root-Level Application Modules
Suppose one of your root-level application modules, ApplicationModule1, instantiates and uses
another root-level application module, ApplicationModule2. If ApplicationModule2 uses bean-
managed transactions, everything it does will be in a separate transaction from
ApplicationModule1. Uncommitted changes in ApplicationModule1 will not be visible from
ApplicationModule2, and vice versa.
If you want ApplicationModule1 and ApplicationModule2 to share a transaction,

ApplicationModule2 should use container-managed transactions. It will then inherit a
transaction from ApplicationModule1.
Container-Managed Transactions Let You Use Client-Demarcated

Transactions
If your client is running in the same Java virtual machine as your EJB server (for example, your
client is a JSP running in the same instance of Oracle 9iAS as your business components), you
11-132
can also use container-managed transactions with application modules instantiated directly by
the client. The client can then demarcate the transaction for complete control.
11-133
If your client directly invokes a business components EJB with container-managed
transactions, you must use a client-demarcated transaction to create a transaction in the client.
Note: You can only use a client-demarcated transaction If your client is running in the same
Java virtual machine as your EJB server (for example, your client is a JSP running in the same
instance of Oracle 9iAS as your business components).
Note: Before using client-demarcated transactions, make sure you have selected container-
managed transactions on the Remote page of the Application Module Wizard.
To use a client-demarcated transaction:
1. Import javax.transaction.UserTransaction into your client.

2. Instantiate your application module.
3. Use the following code to create a UserTransaction object:
Context ctx = new InitialContext();

userTrans = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
4. Call userTrans.begin() to begin the transaction.

5. When your client is finished with the transaction, call userTrans.commit() or
userTrans.rollback().
11-134
Using LOBs through Java Streams
To efficiently use LOBs in the business logic tier, it is best to implement Java input and output
streams, as illustrated in the sample in ORACLE_HOME/BC4J/samples/StreamingLobs.
This feature is new in this release.
Related topics
11-135
Customizing Error Messages
The system-generated Business Components error messages are written to help the application developer; this
information is often useless and confusing to the end user. You can customize error messages for the end user in
two ways:
● Use a try-catch block to trap the exception and display an alternate message
● Use a message bundle to override the system-generated error messages whenever a particular error number
is raised
There are situations where you might want to handle an error message using one way rather than the other. For
example, if the user enters an invalid value in a form, you might want to catch the error and display a message,
allowing the user to continue after they made a correction. Alternatively, if the user cannot do anything to recover
from the error (for example, if the database is down), it generally makes more sense to surface the exception with a
custom error message that tells the user what to do next.
These two alternatives are examined below.
Using a try-catch block to trap an exception
When using a try-catch block, you trap the exception before it is dislplayed. This allows you to throw a new
exception with your own text. Here's an example of using a try-catch block to verify that the user enters a value
between 0-10, with a custom message of "You must enter a number between 0 and 10."
public void setOrderStatus(Number value) {

try
{
setAttributeInternal(ORDERSTATUS, value);
}
catch (oracle.jbo.AttrSetValException e)
{
throw new oracle.jbo.JboException
("You must enter a number between 0 and 10.");
}
}
Using a message bundle to override system-generated messages
Another way to implement a custom error message is with a message bundle. A message bundle is an array of error
numbers and replacement text that you specify. When you add a message bundle to your project, the error
messages you specify in the bundle override the default system-generated error messages.
You make your project use a custom message bundle by adding it to the list of custom bundles in the Business
Component Project Editor. You edit the message bundle in the Code Editor.
To create a message bundle:
1. In the System Navigator, double-click your .jpx node to open the Business Components Project Editor.
11-136
2. Click the Options tab.
3. Click New to create a new message bundle.
4. In the New MessageBundle Class dialog box, enter a name or accept the default.
5. Click OK.
Notice that your new message bundle has been added to the project.
6. Click OK to close the editor.
You may have noticed that all Business Component error messages are five digits prefixed with "JBO-", for example
JBO-25222. To override the error message for this exception, your resource bundle must list "25222" and the text
you want to replace (you do not use the JBO- prefix in the message bundle).
To edit the message bundle class:
1. In the System Navigator, double-click your message bundle class to open it in the Code Editor.
2. Where you see the comment /*fill in 2-D array here*/, enter the number of the error that you want to replace,
followed by the text you want the user to see. Use the following format:
package mypackage;
import java.util.ListResourceBundle;
public class MessageBundle1 extends ListResourceBundle
{
private static final Object[][] sMessageStrings = new String[][] {
{"25002", "Could not start the application. Call x9876 for assistance."},
{"26061", "Application cannot connect to database. Call x4357 for assistance."},
{"27122", "Application error, log a support ticket or call x9876 for assistance." "}
};
/**
* Return String Identifiers and corresponding Messages in a two-dimensional array.
*/
protected Object[][] getContents()
{
return sMessageStrings;
}
}
Using parameterized error messages
Some error messages use parameters to further describe the problem area. For example, your error message may
say "View object, OrdersView, is read only," where OrdersView is a the name of the view object that was passed to
the error message.
To use parameters, you need to look at the message strings in CSMessageBundle.java, which is included in <jdev
install>/bc4j/src/bc4j-messages.zip. In the CSMessageBundle.java file, you'll see a list of error numbers and
corresponding strings. These strings denote the position of the parameter in the object array that gets passed to the
constructor.
For example, if you wanted to override JBO-25026, first EXC_READ_ROW_XML, you would do the following:
1. Open CSMessageBundle.java and search for 25026.

11-137
2. Next toJBO-25026 you'll see a unique string, EXC_READ_ROW_XML. Search for that string in the same file.
3. Where you find that string you'll see the message that goes with the exception: EXC_READ_ROW_XML is
"Row:{1} with XML tag:{0} failed."},
4. Now you know that when you override JBO-25026 you must pass information about the XML tag first and
then the row that failed.
Related Topics
Business Component Error Messages

Ways to Handle Errors in Business Components
11-138
Using Bundled Exceptions
New in this release, you can bundle exceptions until validation is called by using this method on
the Transaction interface:
setBundledExceptionMode(true);
When your application is setting attributes, all exceptions are cached and thrown when the
entity or view row is validated, or when an exception is explicitly thrown while validating. All
attributes are not set if an exception is thrown, and all attributes that threw exceptions retain
their old values.
You can also register exceptions instead of throwing them. These exceptions are thrown at the
end of validation or when an exception is thrown explicitly:
void registerRowException(JboException e)
void clearRowExceptions()
When validating a row, you can check if an attribute is valid by using:
boolean hasAttributeException(String name)

boolean hasAttributeException(int index)
You have access to the cached exceptions through:
boolean hasDeferredExceptions()
ArrayList getAllExceptions()
void clearallExceptions()
JboException has a method that converts entity object exceptions to a view object exception:
public void doEntityToVOMapping(ApplicationModule rootAm, ViewObject[]

vos)
The object name and attribute name retrieved from the exception returns a view object usage
name and a view attribute name, respectively. Attribute validation exceptions thrown from
ViewRows must set the exception NeedsEntityToVOMapping flag to false.
There are four kinds of validation exceptions and they all extend from ValidationException:
11-139
● AttrValException - for attribute validation
● AttrSetValException - for attribute value set exceptions
● DataCreationException - for data creation/formatting errors
● RowValException - for row validation exceptions
These exceptions can be thrown from entity object rows or view object rows.
To instantiate attribute validation exceptions, you must pass
● object type (TYP_ENTITY_OBJECT or TYP_VIEW_OBJECT)

● full entity object definition name for entity object rows, or view usage name for view rows
● attribute name
● attribute value
To instantiate a row validation exception, you must pass the full entity object definition name for
entity object rows, or view usage name for view rows.
See the Javadoc for more information on the methods discussed in this topic.
11-140
Creating Default Business Components
While you are creating a business component project with the Business Components Project
Wizard, creating a package with the Business Components Package Wizard, or editing a
package with the Business Components Package Editor, use the Business Components page
to create default business components from the specified database objects. This page lets you
create a large number of business components quickly and easily, using the most common
values for each of the options available in the other business component wizards. You can edit
any default business components you create and add new business components later. New in
this release, before you generate default business components, you can specify the naming
convention you want to use.
Each table you selected in the wizard produced one entity object of the same name. If you
selected the option, each entity object has a corresponding view object of the same name, but
with the suffix "View." Where there was a foreign key to another table, an association and
optionally a view link were created. The default names are based on the database constraint
names, with the suffix "Assoc" or "Link."
If you selected the option, the default application module contains each view object and view
link. This is similar to how a Java Frame can contain instances of components, such as buttons
and text fields. The default name of the application module is the same as the package, but
with the suffix "Module."
Field descriptions
Field Description
Create Entity Objects and From the drop-down list, select the schema containing the database objects
Associations for these that you will use to create entity objects. You can select from the schema's
Database Objects Tables, Views, Synonyms, and Snapshots by selecting the appropriate
checkboxes. These items are added to the Available list.
Available The Available list contains the list of database objects that you can use to
create entity objects. To select a database object, click its name in the
Available list, and shuttle it to the Selected list.
Selected The Selected list contains the list of database objects that will be made into
entity objects. To remove an item from the list, click its name, and then click
the left arrow. To change the default entity object and view object names,
click Edit; if you change the default names, they appear in the Selected list
in the following format: (entity_object: view_object).
11-141
View Objects and View Links Select this checkbox if you want to create a view object for each entity object
in the Selected list. The view object will contain an attribute for each of the
attributes in the entity object from which it was created. Also, if there were
any associations created, the wizard will create a corresponding view link.
Application Module Select this checkbox if you want to create an application module. The
application module will contain each of the view objects and view links
created by the wizard. To change the default name, type it in the field to the
right.
● After you are finished with the wizard, click Finish to save your changes.
Related topics
Creating a New Business Component Project
Creating a Business Component Package
What Is a Business Component Project?
About Structuring Business Component Projects and Packages
Ways to Create Entity Objects and Associations
Ways to Edit Entity Objects and Associations
Ways to Create View Objects, View Links, and Application Modules
Ways to Edit View Objects, View Links, and Application Modules
11-142
The following table lists the data types supported by Oracle Business Components for Java. These types
are used to map table columns to entity attributes. In addition, you can use a custom domain as a type.
In this release of JDeveloper, support for TIMESTAMP columns with local timezones was added through a
TIMESTAMP domain. In addition, Business Components for Java automatically creates domains for nested
tables and VARRAYs when you are performing reverse generation. VARRAYs are supported for forward
generation, but nested tables are not.
Note that both nested tables and VARRAYs are mapped to oracle.jbo.domain.Array.
JDBC SQL Type

Database Column Type Java Class Name JDBC Type Int
ID
TINYINT oracle.jbo.domain.Number TINYINT TINYINT -6
SMALLINT oracle.jbo.domain.Number SMALLINT SMALLINT 5
INTEGER oracle.jbo.domain.Number INTEGER INTEGER 4
BIGINT oracle.jbo.domain.Number NUMERIC NUMERIC 2
INT oracle.jbo.domain.Number NUMERIC NUMERIC 2
REAL oracle.jbo.domain.Number REAL REAL 7
DOUBLE oracle.jbo.domain.Number DOUBLE DOUBLE 8
FLOAT oracle.jbo.domain.Number FLOAT FLOAT 6
DECIMAL oracle.jbo.domain.Number DECIMAL DECIMAL 3
NUMERIC oracle.jbo.domain.Number NUMERIC NUMBER 2
BIT oracle.jbo.domain.Number BIT BIT -7
NUMBER java.lang.Boolean BIT BIT -7
VARCHAR2 java.lang.String VARCHAR VARCHAR 12
NVARCHAR2 java.lang.String VARCHAR VARCHAR 12
CHAR java.lang.String CHAR CHAR 1
VARCHAR java.lang.String VARCHAR VARCHAR 12
LONG java.lang.String LONGVARCHAR LONGVARCHAR -1
RAW oracle.jbo.domain.Raw BINARY BINARY -2
RAW oracle.jbo.domain.Raw VARBINARY VARBINARY -3
RAW oracle.jbo.domain.Raw LONGVARBINARY LONGVARBINARY -4
LONG RAW oracle.jbo.domain.Raw LONGVARBINARY LONGVARBINARY -4
CLOB oracle.jbo.domain.ClobDomain CLOB CLOB 2005
BLOB oracle.jbo.domain.BlobDomain BLOB BLOB 2004
BFILE oracle.jbo.domain.BFileDomain BFILE BFILE -13
TIMESTAMP oracle.jbo.domain.Date TIMESTAMP TIMESTAMP 93
TIME oracle.jbo.domain.Date TIMESTAMP TIME 92
TIME oracle.jbo.domain.Date TIMESTAMP TIMESTAMP 93
11-143
DATE oracle.jbo.domain.Date DATE DATE 91
DATE oracle.jbo.domain.Date TIMESTAMP TIMESTAMP 93
DATETIME oracle.jbo.domain.Date TIMESTAMP * see note below 93
ROWID oracle.jbo.domain.RowID VARCHAR VARCHAR 12
VARCHAR2 oracle.jbo.domain.Char VARCHAR VARCHAR 12
NVARCHAR2 oracle.jbo.domain.Char VARCHAR VARCHAR 12
CHAR oracle.jbo.domain.Char CHAR CHAR 1
VARCHAR oracle.jbo.domain.Char VARCHAR VARCHAR 12
LONG oracle.jbo.domain.Char LONGVARCHAR LONGVARCHAR -1
NUMBER java.lang.Integer NUMERIC NUMBER 2
NUMBER java.math.BigDecimal NUMERIC NUMBER 2
TIMESTAMP java.sql.Timestamp TIMESTAMP TIMESTAMP 93
DATE java.sql.Date DATE DATE 91
STRUCT java.lang.Object STRUCT STRUCT 2002
ORDSYS.ORDIMAGE oracle.ord.im.OrdImageDomain STRUCT STRUCT 2002
ORDSYS.ORDAUDIO oracle.ord.im.OrdAudioDomain STRUCT STRUCT 2002
ORDSYS.ORDVIDEO oracle.ord.im.OrdVideoDomain STRUCT STRUCT 2002
ORDSYS.ORDVIR oracle.ord.im.OrdVirDomain STRUCT STRUCT 2002
ORDSYS.ORDDOC oracle.ord.im.OrdDocDomain STRUCT STRUCT 2002
ORDSYS.ORDIMAGESIGNATURE oracle.ord.im.OrdImageSignatureDomain STRUCT STRUCT 2002
ARRAY oracle.jbo.domain.Array ARRAY ARRAY 2003
REF oracle.sql.REF REF REF 2006
STRUCT java.lang.Object OTHER OTHER 1111
*Note: All JDBC SQL Type IDs are of OracleType.<JDBC type> except DATETIME which is of the type
java.sql.Types.TIMESTAMP.
11-144
Understanding the n-Tiered Business Components
Architecture
When you develop a business components project, you should think of it as having three
separate logical tiers: client code, the business logic, and the database. However, these three
logical tiers can be deployed in multiple physical configurations. Client code can appear
anywhere you can write Java code (for example, a GUI application, a JSP, or an Enterprise
JavaBean). In addition, the business logic you create using Business Components for Java is
tier-independent: You can deploy your application modules to multiple platforms without
changes in your business components or client code.
Common Deployment Configurations
You can deploy business components and client code anywhere you can deploy Java.
However, there are four especially common deployment configurations:
Client Code Business Components

Java client on client machine On client machine
As an EJB session bean or CORBA server
Java client on client machine
object
Servlet/JSP in the web module of a
In the web module
server (accessed through a browser)
Servlet/JSP in the web module of a As an EJB session bean or CORBA server
server (accessed through a browser) object
When business components are deployed as an EJB session bean or CORBA server object,
the configuration is called remote deployment. Tier-independence means you can switch
between deploying business components remotely and deploying them in the web module or
on the client machine without any changes to your code.
This is a marked improvement over other programming styles. Without the business
components framework, you would have to plan your entire application around your
deployment configuration--an application designed around EJBs would look entirely different
from a client/server application with no separate physical business logic tier. With the business
components framework, you can program and invoke a business components EJB and a
locally deployed business components archive in exactly the same way.
Choosing a Deployment Configuration
11-145
When you choose the configuration of your business components application, ask yourself the
following questions:
Is it more important to me to have a thin client or a client with a complex user interface?
Using servlet or JSP client code will take most of the load off of the client machines: The web
server will do all of the processing, and the client machine will only need to render HTML. A
Java client, on the other hand, requires the client machine to run Java but allows for real-time
interactivity and a complex user interface.
Is network speed more of a concern than machine speed?
Deploying business components remotely takes much of the weight off of the machine
processing your client code. The cost of this is more trips over the network, as your client code
accesses your business components EJB. If your client code is executing on a fast, centralized
machine such as a web server, saving network trips by deploying to the web module may be
worth the increased processing demands.
Advantages of Tier-Independence
Tier-independence gives you multiple advantages:
● You can prototype your application with the convenience of local or web module
deployment and then move to a remote configuration if you want, and you won't need to
change any code.
● You can easily deploy and benchmark your application in multiple deployment
configurations to see which gives you the best performance and scalability.
● Instead of devoting extensive project resources to EJB or CORBA architecture, you can
let the business components framework deal with issues of cross-tier communication for
you.
Maintaining Tier-Independece
You can maintain independence by using client interfaces and the factory pattern.
11-146
About Client Interfaces
The business components framework is organized around interfaces in the oracle.jbo
package, such as oracle.jbo.ApplicationModule, oracle.jbo.ViewObject, and
oracle.jbo.Row. By coding your client to these interfaces, rather than the classes that
implement them, your code can stay tier-independent. If, for example, you choose to deploy
your business components as an EJB, you can use the same client code you used for testing
when your business components were deployed locally, because the interfaces are always
accessible in the client tier. The business components framework handles all issues of cross-
tier communication for you.
The interfaces in oracle.jbo are implemented by classes in the package

oracle.jbo.server. For example, oracle.jbo.ApplicationModule is implemented by
oracle.jbo.server.ApplicationModuleImpl. You should not directly call methods on
these implementation classes, because if you deploy remotely, these classes will not be
available on the client tier. Invoking the classes would prevent you from ever deploying your
application remotely. Instead, you should call methods on the interfaces.
Similarly, when you create your own application modules and view links, you should not call
methods on their implementation classes. Instead, you should export methods to create custom
interfaces that contain them. These interfaces extend oracle.jbo.ApplicationModule or
oracle.jbo.ViewObject and are also always accessible in the client tier. When you
downcast a business component, always downcast to your interface, never to your
implementation class.
For more information on what happens behind the scenes when you make a method call on
remotely deployed business components, see the topic About Business Components and Wire
Protocols. Note that you don't need to know any of that information when you write your code;
the business components framework handles wire protocols automatically.
Note: A general rule of thumb is that direct access to *Impl classes is

permissible inside another *Impl class; however, access or casting to *Impl
classes in client code accessing an application module should be avoided.
11-147
About the Factory Pattern
To maintain tier-independence, your client code should never mention a specific application
module implementation class. All your references should be to
oracle.jbo.ApplicationModule (or a custom subinterface).
Because of this, you cannot instantiate an application module using new. To do so would
require explicitly mentioning a particular implementation class, which will destroy tier-
independence and lock your application into local or web module deployment.
Instead, the business components framework uses the factory pattern to instantiate application
modules. The framework uses connection and platform information and the name of your
application module to create an instance of
oracle.jbo.common.ApplicationModuleHome, an interface present on all tiers. You can
then use this class to dynamically create the proper implementation class, which you can cast
to the interface to maintain tier independence.
For more information on using the factory pattern, see Finding an Application Module Instance
in Code.
11-148
About Business Components and Wire Protocols
The Business Components for Java framework deals with all issues of cross-tier
communication. Instead of devoting extensive project resources to EJB or CORBA architecture,
you can write your applications as if you were deploying locally or to a web module and let the
framework transparently handle remote deployment.
Although you do not need to know the details of cross-tier communication, you may find your
understanding of remote deployment aided by a brief explanation of how the framework
handles it.
Calling Framework Methods in Remote Mode
When you deploy business components remotely, the oracle.jbo.server classes (such as
ApplicationModuleImpl and ViewObjectImpl) are only present on the business logic
tier. Clients access business components methods through separate client-side classes in a
subpackage of oracle.jbo.client.remote. For example, when you deploy business
components as an application module session bean, clients use tha package
oracle.jbo.client.remote.ejb.
When a client calls a method on an interface to remotely deployed business components, it

gets executed by the implementing class in the client package. This object passes the call over
a wire protocol to a class in a subpackage of oracle.jbo.server.remote (for example,
oracle.jbo.server.remote.ejb) on the business logic tier. This class in turn passes the
call to the implementing class in oracle.jbo.server:
11-149
Note that you don't need to worry about all of this internal plumbing; your client application calls
oracle.jbo.ApplicationModule through a normal Java call.
Calling Exported Methods in Remote Mode
Just as remotely deployed framework implementation classes are not available on the client
tier, your remotely deployed custom implementation classes are not either. If you want clients
to be able to access your custom methods, you must export methods to create a tier-
independent interface. Then, when you make your application module remotable, JDeveloper
creates separate client-side classes that implement your interface.
When a client calls a custom method on an interface to remotely deployed business

components, it automatically gets passed to the implementing class in the client package. This
class passes the call over a wire protocol to the implementation class on the business logic tier.
11-150
Again, note that your client doesn't need to concern itself with the wire protocol. It simply calls
mypackage.common.MyAppModule through an ordinary Java call.
11-151
The business logic tier stores data it receives from a database and clients in two types of
caches: an entity cache and a view cache. This sophisticated, patented caching system
handles many complex design patterns and programmatic tasks for you, so you can
concentrate on implementing the business logic and client interfaces specific to your
application.
You could implement an entire business components application without ever learning how the
caching system works. However, it's useful to understand its major features so you can make
informed implementation and optimization decisions. In addition, experienced Java
programmers can customize or bypass the caching system for application-specific reasons
(although it's rarely necessary). After reading this topic, you should have an understanding of
what the caching system does for you and what aspects of the caching system you can control.
To make the principles more concrete, each major concept has an accompanying code snippet
that illustrates a common scenario that causes a change in the caches. The complete sample is
in $ORACLE_HOME\BC4J\samples\Caching and the client is TestClient.java. This
sample uses the HR schema, which is provided with Oracle9i. See Creating and Populating the
Database Tables for information on how to install the tables when you are using another
database version.
Before reading this topic, you should understand what business components and the framework
are, as described in the Introducing Business Components for Java book of the online help.
Why does the business logic tier use caches?
The business logic tier caches business component instances in memory for five main reasons:
● To improve application performance. When an application needs to work with data, it

retrieves the data from the database, accesses the data, and possibly updates the data.
When finished, the application adds changes to persistent data to the database. If the
data was not cached, the application might have to retrieve and post data many times,
resulting in performance degradation.
● To manage business component states. As the program performs operations on

business component instances, the cache manages their state. The state can indicate
that the instance is newly created, unmodified, deleted, and so on. When the program is
ready to commit to the database, the business logic tier uses the business component
states to determine what database operations to perform. You don't have to write
11-152
complex code to manage these states or to save changes to the database, because the
business components framework does it for you.
● To implement a well-defined business component lifecycle. The cache enables the

framework to implement a well-defined lifecycle model, including how business
component instances are created in memory, accessed, modified, validated, and written
back to the database. You can create your applications knowing what the lifecycle
behavior is and, if needed, customize certain points in the lifecycle to better suit your
programs.
● To coordinate the use of data and business logic by multiple views. All clients of a
business logic tier share the caches and the business logic. Changes made in one view
of data are visible to other views looking at the same data.
● To coordinate changed data and database data. Many applications need to work with
data that a user has entered but not committed to the database ("work-in-progress"
data), as well as data already in the database. For example, an application might need to
perform validations and data updates based on both types of data. The cache presents
to the application a "merged" view, where work-in-progress data is merged with database
data. As a result, the application can perform validation and other data operations before
data is written to the database. This reduces the number of times the application needs
to post, thereby increasing application performance. In addition, the application can wait
until the user finishes their edits before any database constraints and triggers are fired.
What classes make up the caches
Several framework classes in the oracle.jbo.server package affect the caches. It's useful to
have a general idea of this relationship to understand how your code uses the caches.
For each EntityDefImpl instance used in a session, the top-level application module manages an
entity cache that contains EntityImpl instances.
A view object manages a view cache. The view cache contains row sets. The row sets contain
ViewRowImpl instances.
To better understand these relationships, consider a simple example where an application

begins running, retrieves data from the database, and later updates the data in the database.
How a query first populates empty caches

11-153
Typically, when an application first starts running, a view object query populates the caches.
When the view object query executes, each row of the query's result set is cached in a view
row:
● View attributes that are based on (map to) entity attributes are placed in one or more
entity caches. For these attributes, the view cache points to the entity cache.
● View attributes that do not map to entity attributes are placed in the view cache.
The process of populating the caches follows these general steps:
1. The client creates a top-level application module.
To use the business logic tier, a client creates a top-level application module instance
(also called a root application module), which can contain view object instances, view link
instances, and nested application module instances. Each top-level application module
instance has its own caches and connection to the database (session). The instance also
provides a transaction context for the view object instances it contains, including those in
any nested application module instances. So the top-level application module instance is
a container for view object instances and nested application module instances that share
caches, a connection, and transactions.
2. The client finds or creates a view object.
If the view object was created by the application module, the client would "find" it.
Otherwise, it would create it.
3. The view object executes its query.
Each view object typically contains a SQL query. The client calls a method to execute the
query, or the client asks for one or more rows (which causes the view object to execute
its query if it hasn't already).
4. The view object retrieves the initial rows of requested data from the database.
Alternatively, the client could request all rows.
By default, the view object does not fetch all rows in the result set at once, unless
specified. For example, the first method will bring in the first row and leave the rest
out of the cache. The next method brings in the next row, and so on.
11-154
5. The view object creates a blank view row for each retrieved database row. The view
object creates an empty EntityImpl instance for each entity object related to this view
object.
6. The view object adds attribute values to the instances.
The view object populates the EntityImpl instances with mapped attributes. The view
object populates the view row with attributes that are not persisted in the database.
7. The view row adds EntityImpl instances to the entity cache.
The instances are identified by their primary key.
8. The view row is added to the row set in the view cache.
For example, in the following code snippet, the client creates an application module instance,
finds a view object, adjusts the view object query, retrieves the first row, and gets the salary of
the first row. All view attributes based on an entity attribute are added to the entity cache. All
view attributes that are not based on an entity attribute are added to the view cache. For the
Managers view object, all attributes are persistent, so the view object places all attribute values
in the entity cache.
"frags/popcache.frag"<<popcache.frag in TestClient.java>>
An application does not have to use a view cache or entity cache.
If there are no view attributes that are based on entity attributes, the entity cache is not used.
To prevent data from entering the view cache, you can use the setForwardOnly method in a
view object. This is called forward only mode. Using forward only mode can save memory
resources and time, because only one view row is in memory at a time. Forward only mode is
useful when you are fetching data and reading it once, such as formatting data for a web page,
or for batch operations that proceed linearly. Note that if the view object is based on one or
more entity objects, the data does pass to the entity cache in the normal manner, but no rows
are added to the view cache.
In addition, an entity object can populate the entity cache directly, bypassing the view cache. If
you look up an entire entity object with the findByPrimaryKey method, all of its attribute values
are added to the entity cache. (It gives priority to data in the cache, and then brings in data from
the database if it's not already there, as described later.) Using a view object to look up data is
11-155
more flexible, in that you can bring in any attributes that are relevant to the task and leave out
those that are not. The view object executes a query, and if the attribute doesn't already contain
data, it adds the data for that attribute.
How you create a new row
Inserting a new row involves these general steps:
1. A client calls the createRow method.
The view object creates a blank view row. The view row and EntityImpl are not in the
cache yet.
2. The client sets the primary key.
The new EntityImpl is added to entity cache. The new row enters the transaction list
when it goes into the entity cache.
If the ROWID is the primary key, the framework assigns a temporary value.
3. The client calls the insertRow method on the view object.
A new view row is added to view cache.
Note that you could reverse the order of steps 3 and 4. You should never omit the createRow
method or setting the primary key, because the data will enter the view cache, but not the entity
cache.
Here is a code sample showing these steps. In addition, it shows built-in validation for required
fields and posting changes.
"frags/newrow.frag"><<newrow.frag>>
You can auto-create a primary key (as a sequence, GUID, and so on) whose value is
generated by the database when a new row is posted to it. If you want to use to use an entity
attribute as a database sequence, for example, you could add code to the EntityImpl create
method, select the Refresh After Insert attribute setting, or use the DBSequence domain. The
code you add in the create method would need to return the value immediately when a new row
is inserted. For the Refresh After Insert setting, the value is returned after the row is saved to
the database; you need a database trigger that inserts the value into the column of a new row.
You may want to make these types of attributes read-only so that an end user cannot change it.
11-156
If a query returns multiple row sets because of a bind variable, multiple row sets can be
created. For example, if the query is SELECT DEPTNO, DNAME, LOC FROM DEPT WHERE
LOC=:1, and the bind values are SAN JOSE, CHICAGO, and NEW YORK, there can be three
row sets, one for each location, in the view cache.
How data merge occurs in the caches
Each view object instance has its own view cache. After a query, each returned database row
is represented by a row in the view cache. Each column is represented by a corresponding
attribute in the row. Attributes that did not receive a value remain empty in the row.
Each entity object instance has its own entity cache. After a view object query, in each returned
row, the values of view attributes that map to entity attributes are placed in the appropriate
entity cache. Remember that view objects can map to more than one entity object. So different
attributes in a row can end up in more than one entity cache. Each row in an entity cache is
uniquely identified by its primary key. (So if you specify more than one entity object for a view
object, you must always include the primary key of each entity object.) Attributes whose values
were not populated by the query remain empty in the row. Whenever a view attribute that is
mapped to an entity object is retrieved or set, it delegates to the getter or setter in the entity
object.
Each view object instance contained by a top-level application module shares entity caches
with all other view object instances in the top-level application module. (This includes any view
object instances in nested application modules.) If you have several view objects that refer to
the same entity object, you know that they also refer to the same entity cache. This means that
when shared data is modified through one view object instance, all other view object instances
are notified of this change and can show the modification in a client form, for example.
When a view object executes a query, the data needs to be merged into the entity cache. The
business logic tier uses modified data in the entity cache, if it exists. If an entity object instance
has been modified, the query returns the entity cache's data instead of new data from the
database. If the entity object instance does not exist or is unmodified, the query returns data
from the database. This ensures that unposted changes are not overwritten when the same row
is retrieved from database through other view object instances. The entity object checks its
cached data against database data at locking time.
Here's an example:
● An Employees entity object has Employee_Id, Last_Name, and Salary attributes.

● An Employees view object has Employee_Id and Last_Name attributes.
● An Employees2 view object has Employee_Id, Last_Name, and Salary attributes.
11-157
The following code snippet shows how different view objects can view the same cached data.
"frags/showuniquing.frag"><<showuniquing.frag>>
When fault-in occurs
In the entity cache, attributes may be missing, for example, if a view object does not have a
view attribute that maps to a particular entity attribute so that attribute is never populated. If
business logic tries to access an attribute value stored in a database row, and the value hasn't
been brought into the entity cache, fault-in occurs. All empty attributes in the row are populated
from the database so that business logic can complete. Here's an example:
1. An Employees view object has Employee_Id and Last_Name attributes.

2. An Employees entity object has Employee_Id, Last_Name, and Salary attributes.
3. The view object query brings Employee_Id and Last_Name attributes into the entity
cache, but the Salary attribute is unpopulated.
4. The validation method accesses Salary.
5. The business logic tier gets all row attributes from the database.
Fault-in ensures that business logic has values it needs. As an optimization technique, you can
prevent fault-in by making sure that all attributes needed by business logic are included in view
object queries. This prevents extra SQL statements from being executed and creates a clean
separation between entity objects and view objects. However, you may want to keep rarely
accessed attributes out of the view object to conserve memory.
The following entity object code snippet, from EmployeeImpl.java, shows why fault-in will occur.
The CommissionPct attribute is accessed, but it's not in the cache, so it's faulted-in.
"frags/bizlogic.frag"><<bizlogic.frag>>
The following code snippet, in TestClient.java, shows where fault-in occurs.
"frags/updateentity.frag"><<updateentity.frag>>
When all attributes are brought into the entity cache
There are four conditions under which all attributes of a row in the entity cache are brought in:
11-158
● The view object query includes all attributes.
● Fault-in occurred.
● The findByPrimaryKey method was used.
● The business logic tier has obtained a lock for the corresponding row in the database
(through pessimistic locking or the Row.lock method).
How locking occurs
There are two types of locking: pessimistic and optimistic. Or you can choose not to use locking
at all, which is typically not the best choice. You usually use optimistic locking when you are
optimistic that two users will never modify the same row at the same time, due to the nature of
your application. Pessimistic locking is the most conservative form of locking.
When an application uses locking, the business logic tier attempts to lock a row in these
circumstances:
● For pessimistic locking, there is an attempt to set data in an existing row. The client or
business logic tier successfully calls setAttribute on a mapped attribute for the first time
on the row. First, business logic validation is triggered. Then the entity object attempts to
acquire a lock on the database row.
● For optimistic locking, there is an attempt to post a row.
● There is an attempt to delete a row.
● The client or business logic tier calls the lock method. (Note that it is harmless to call the
lock method even when the row is already locked.)
When an application doesn't use locking, if the row is locked by another user, the entity object
will wait until the row is released by the other user who locked it. Then it will write the changes,
which could overwrite the previous user's changes.
Here is how the business logic tier acquires a lock:
11-159
1. The business logic tier sends a DML statement to the database to lock the row.
It uses this general syntax:
select ... from ... where PK = value for update nowait
2. If the lock succeeds, it retrieves the latest data from the database (with same statement).
3. The business logic tier resolves the database data with the data in the cache, as
described in the next section.
When the transaction associated with a top-level application module uses pessimistic locking
(the default), and the row is an existing row in the database, the business logic tier attempts to
lock a database row the first time one of its attributes is successfully modified, including passing
any validation. (If the entity object is part of a composition, the framework first tries to lock the
row for the top-level entity object in the composition.) If it can lock the row, the business logic
tier can modify the row. If the business logic tier cannot lock the row, it throws an exception and
the value returns to what it was before the modification.
When the transaction of a top-level application module uses optimistic locking, at post time, the
business logic tier attempts to lock each row corresponding to any deleted or modified entity
object instances. (If the entity object is part of a composition, the framework first tries to lock the
row associated with the top-level entity object.) If any of the attempts to lock are unsuccessful,
an exception is thrown.
For session-oriented programs, pessimistic locking is best, because the application discovers
errors immediately and there is less chance of the transaction aborting when it tries to commit.
For non–session-oriented programs, optimistic locking can be best, for example, you don't want
to lock a record if a user leaves a web page open on their screen for a few days.
Locking is defined in the oracle.jbo.Transaction interface. You set the locking mode with the
setLockingMode method, and
get the current locking mode with the getLockingMode method. After an entity object instance is
successfully modified in the entity cache (after it acquires a lock), all view object instances who
have queried data for the row are notified so clients can refresh their displayed data.
After locking a row, the entity object verifies that the data retrieved from the database during
the lock acquisition matches the unmodified data in the entity cache. If not, an
oracle.jbo.RowInconsistException is thrown. This ensures that if another program in another
database session has modified that row, then the application does not unknowingly overwrite
that modification.
How database data is brought into an existing cache
11-160
There are different data resolution processes for locking, fault-in, and updates.
For locking, here is how the business logic tier resolves the data:
● If you did not use a change indicator attribute, for each mapped attribute, the business
logic tier compares the originally retrieved values and the new database values by calling
the equals method.
● If the entity includes an attribute that has been marked as a change indicator
(recommended), the change indicator is compared only.
If there are no differences, the data from the database is placed in the cache. If there are
differences, a RowInconsistException is thrown. You can catch the exception and resolve the
differences in your code.
For example, let's say there is $100 in a joint checking account and the two owners go to an
ATM:
1. Person1 checks the balance and sees $100, populating the entity cache.
2. Person1 requests a $20 withdrawal.
3. Person2 checks the balance, and sees $100, populating a different entity cache.
4. Person1's transaction gets a lock, calls setAttribute to set the balance to $80, and
commits the transaction.
5. Person2 elects to withdraw $50.
A RowInconsistException is thrown, because the values in the entity cache have
changed.
For fault-in, if the business logic tier has modified an attribute in the cache, the modified value
is kept. If the business logic tier has not modified the value, the value retrieved from the
database is used.
For updates, the business logic tier locks before the update and compares values, so it knows
immediately if data has changed.
The commit and rollback cycle
Associated with the top-level application module is a transaction object. This object manages
the interaction between the entity cache and database. To do this, the transaction object keeps
a transaction list, which is a list of entity object instances that have been changed during this
11-161
transaction.
In general, the commit and rollback cycle follows these steps:
1. When the client calls Transaction postChanges or commit, the transaction object iterates
through the transaction list and calls the doDML method on each entity object, to perform
delete, data update, and insert operations in the database.
Note that commit calls postChanges.
In general, the transaction object processes entity objects in the transaction list in the
chronological order of when the entity object was first modified in this transaction.
However, there is no guaranteed order that changes are processed. For a composition,
however, the transaction object processes the parent entity object first, followed by
children entity objects.
2. After the posts are complete, the transaction list cleared.
3. The data is committed or rolled back in the database.
4. The locks are released.
The order that you insert rows in a database matters for associations. For example, suppose
you have an association between Employees and Departments, with a key of Department_Id
that associates the two entity objects. First, you create an employee with a Department_Id of a
department not yet created. Next you create a department for that new Department_Id. If you
post these changes, the transaction object will create the new employee first (with the new
Department_Id), followed by the department. If the database had a foreign key referential
integrity constraint on the Employees table, you will get a database error. This is because the
transaction object tried to create a row in the Employees table where the associated
department had not yet been created. This situation is a post order problem: associated rows
were not created in the proper order.
One way to avoid post order problems is to use a composition. In a composition, the
transaction object ensures that the parent entity object is written to database first, followed by
children. In the Employees/Departments example, if you marked the association as a
composition, Departments being the parent and Employees the child, then the new department
is created first, so you would not get a referential integrity error.
Only valid rows are posted. The entity object makes sure each row is valid before posting.
11-162
A previous code snippet, in How you create a new row, shows validation and posting.
The following code snippet illustrates rolling back a transaction (since you don't want a sample
to modify the database).
"frags/dorollback.frag"><<dorollback.frag>>
See Entity Object Row States for state diagrams.
How rows are deleted
Here are the general steps for row removal:
1. The client removes a row by either calling the ViewRow remove method or
RowSetIterator removeCurrentRow method.
Note that the second approach causes the remove method to be called on the current
row of the row set iterator.
2. For both pessimistic and optimistic locking, the business logic tier locks the entity rows
that comprise the view row. Next, it calls the EntityImpl remove method.
This call marks the entity row as deleted and sends out an event that marks all view rows
that use the entity row as "dead." The dead view rows are removed from the view cache.
3. When the user calls the postChanges (or commit) method, for each entity row marked as
deleted, the corresponding database row is deleted.
4. When the transaction is committed, the entity row is marked as dead and is removed
from the cache.
The following code snippet removes a row. After it's removed, it's an error to operate on its
attributes.
"frags/removerow.frag"><<removerow.frag>>
When rows are removed from a cache
When a view object or application module is destroyed, the associated view caches are also
destroyed. You can also explicitly clear view caches by calling certain methods, including
11-163
clearVOCaches on the application module, clearEntityCache on the transaction, and
clearCache on the view object.
When no view caches point to an instance in the entity cache, and the entity instance hasn't
been modified, the instance becomes a candidate for clearing. When the rows are cleared
depends on the Java VM you are using. The Java VM usually removes them when it needs
more memory.
Refreshing the caches
Business Components for Java provides methods that can clear the cache. These methods are
mainly used for these two purposes:
● to release memory occupied by the row (view rows or entity rows)

● to clear the cache of data and get the latest data from the database
You can use the following methods to clear the caches:
● ViewObjectImpl clearCache method

● ApplicationModuleImpl clearVOCaches method
● Transaction clearEntityCache method
● Transaction isClearCacheOnCommit and setClearCacheOnCommit methods (These
methods clear the entity cache; the default is not to clear the entity cache on commit.)
● Transaction isClearCacheOnRollback and setClearCacheOnRollback (These methods
clear the entity cache; the default is to clear the entity cache on rollback.)
These last two groups of methods set (or inquire about) the flag that controls whether the entity
cache is automatically cleared after commit or rollback. For example, if
setClearCacheOnCommit(true) is called on a transaction, whenever the transaction is
committed, all entity caches are cleared. Subsequent access to entity objects will refresh data
from the database.
Note that by default, isClearCacheOnCommit is false and isClearCacheOnRollback is true. So,

by default, the entity caches are cleared after rollback. But after commit, the entity caches are
retained (not cleared).
Multiple view object instances and update, delete, and insert

behavior
11-164
In the same application module instance, if you have two instances of the view object
EmpView, named EmpView1 and EmpView2, which both use the Emp entity object, you will
see the following behavior:
● update — If you modify view attributes mapped to entity attributes, both view object
instances always show the same data, including any pending, uncommitted changes,
even after you requery the database. For view attributes not mapped to entity attributes,
changes made in one view object instance are not visible to another view object
instance.
● delete — If you delete one row in EmpView1, you no longer see it in EmpView2, even if
you requery the database before committing the change.
● insert — If you insert a row into EmpView1, EmpView2 doesn't show the new row. If you
requery the database using EmpView1, EmpView1 will no longer show the new row. If
you post the change to the database, the row does appear to both view object instances.
The only exception applies to detail row sets in a master-detail relationship. If you call
setAssociatonConsistent(true) on a detail row set, it will see new rows that qualify. For
example, let's say there is a master-detail relationship between Dept and EmpView2,
and the current row is Dept with a Deptno of 20. If you insert a new row on EmpView1
with Deptno 20, EmpView2 will see that new row, if you had previously called
EmpView2.setAssociationConsistent(true).
There are two reasons for this insert behavior:
● To prevent inconsistent result sets. If EmpView2 had a Where clause of "Deptno = 10"
and the new row had "Deptno = 20," the business logic tier doesn't know whether the
new row should be part of the result set, because it doesn't have a query evaluator (it
relies on the database to resolve the query). For a master-detail relationship, however,
there are related attributes, so they can be used to determine whether to add the row to
a result set.
● To prevent inefficient verifications. If a view object refers to multiple entity objects,

verification cycles can be lengthy. Let's say EmpView2 used two entity objects, Emp and
Dependent, but EmpView1 just used Emp. When you insert a new row into EmpView1,
should EmpView2 see this new row? If so, what should be the Dependent portion?
Conversely, if you add a new row to EmpView2, should that row show up in EmpView1?
What if the new row in EmpView2 really does not represent a new Emp, but a new
Dependent? It can take many verification cycles to figure that out. This problem applies
even in the master-detail case, so AssociationConsistent is false by default.
11-165
How to see data changed through other connections
If you traverse the same association or view link more than once to get data, the data you're
trying to get is already cached. If data was changed through another connection since you
queried the data, you will not see the new data in the database. So if you use the validateEntity
method to perform validation on the data you obtained, it could inadvertently perform validation
using stale data.
If it's important to your application to always see fresh data when you perform validation, you
can use a programmatic technique to get the most up-to-date data. If the accessor returns
RowIterator, you can cast to RowSet and call the executeQuery method to force a requery from
the database before you get attribute values used for validation. You can use this technique in
the following circumstances:
● an association accessor is getting data from the many side of a one-to-many relationship
● a view link accessor is getting data from either a one or many side of a relationship
(remember that view link accessors can be exposed to entity objects)
Here's an example:
public void validateEntity() {

String list = "";
RowIterator ri = getEmp();
boolean found = false;
((RowSet) ri).executeQuery();
while (ri.hasNext()) {
String ename = (String)ri.next().getAttribute("Ename");
if (ename.equalsIgnoreCase("STEVE")) {
found = true;
}
else {
list += " "+ename;
}
}
if (found) {
System.out.println("Found STEVE among employees in this department");
throw new JboException("Cannot have employee named STEVE");
}
else {
System.out.println("Found ("+list+") but no STEVE");
}
}
11-166
Related Topics
What Is an Application Module?
11-167
Understanding Business Components for Java from
a Forms Developer's Perspective
This topic is specifically for developers who are familiar with creating client-server applications
using a rapid application development (RAD) tool such as Oracle Forms. In typical two- and
three-tier client-server applications, most of the development work is focused on the client
forms. Therefore this type of application will be referred to as forms-based for the remainder of
this topic. Although Oracle Forms in particular will be referenced throughout, users familiar with
other RAD tools, such as Visual Basic and PowerBuilder, might find much of this information
useful.
Assumptions about your background
Before starting to learn about Business Components for Java (BC4J), it might be helpful to
review what you are assumed to know and not know.
As a forms-based application developer you probably know how to:
● Develop applications using a 4GL RAD tool such as Oracle Forms, Visual Basic, or
PowerBuilder
● Build user interfaces with controls that correspond to database tables
● Enforce business logic through:
❍ UI controls, such as option buttons and lists
❍ Code written to respond to UI events, such as a text field losing focus

❍ Code written to respond to database events, such as a row being inserted
● Program reusable code in SQL and PL/SQL

● Base blocks on database views to work with joined tables
As someone new to Business Components for Java, you might not know how to:
● Program in Java
❍ Object-oriented programming techniques
❍ Design user interfaces with Swing UI components

❍ Exploit inheritance to make the most out of the framework
❍ Implement JavaBean events
11-168
● Use object/relational mapping
● Isolate business logic for reuse in multiple forms
● Work with business components
Much of what you know will translate easily, and learning the rest only requires proper
orientation. What you know about developing in a forms-based tool will provide a good base
from which to learn Business Components for Java.
Forms and Business Components for Java are frameworks
Both Forms and Business Components for Java are application frameworks. A framework is
responsible for doing all the "application plumbing": interacting with the database, commit
processing, enforcing validation at event points, etc. The framework allows the developer to
focus on the business problem, not the background details.
The main difference between the two frameworks is that Business Components for Java
separates the UI from the data access. You will see later how this separation facilitates better
access and reuse of the components.
The Forms framework
The Forms runtime engine, or Forms Server, runs the data in a Forms definition file. Typically a
Forms definition consists of both UI objects (windows and canvases) and data blocks. A Forms
definition is made up of two parts: the metadata and the implementation code. The metadata
describes the blocks, items, windows, canvases, etc. The user-written implementation code is a
combination of triggers and PL/SQL packages, procedures, and functions. Collectively, these
parts are stored in the Forms .fmb file.
11-169
The Business Components Framework
From a high level, Business Components for Java and Forms have similar architectures. Like
Forms, metadata is set apart from implementation code. However, where the Forms definition
file could be very large and might contain many data blocks, Business Components for Java
divides the parts into smaller modular pieces called business components. Business
components are a pairing of a Java class and an XML metadata file. These finer-grained
components make for better reuse and easier customization.
Another difference in the architectures is the separation of the implementation code into two
pieces: the compiled Java code, and the client (presentation) code.
11-170
Application development in both frameworks is more closely examined later in this topic, and
that will do more to illustrate these differences. But before that you need to know what the
business components are and what they do.
What Are Business Components?
The easiest way to understand that business compoents are is to relate them to Froms
constructs you already know. Indeed, you will find that many Forms objects have analogous
counterparts in the business components architecture. The differences are a result of the way
business components separate the data from the user interface. For example,
● The functionality of data blocks is provided by the combination of view objects and entity
objects
● The master-detail functionality performed by Forms relations are provided by view links
● The functionality of a form is similar to the combination of an application module and a
Java UI
● The functionality of database foreign keys is provided by associations
Data blocks are similar to the combination of view objects and entity objects
A Forms data block has two primary responsibilities:
● Querying data
● Manipulating data in the database
11-171
A data block allows you to work with rows within a database, directly from the user interface.
Operators can use data blocks to automatically query, update, insert, and delete rows within
that table or view.
In Business Components for Java this functionality is split between two different objects, view
objects and entity objects. View objects are the objects responsible for querying data, while
entity objects are responsible for modifying data in the database. Splitting the functionality into
two objects allows querying data in many different ways while using the same validation and
data manipulation logic.
View objects query a selective view of data
Each data block in a form represents some view of the available data. The form may contain a
subset of the available values, have certain fields hidden, apply only to a specific group of
people, etc. For example, this form could be called Employees, and only show their names,
addresses, and phone numbers. You might have a similar form accessible by managers that
shows a different view of data, for example their salary would be displayed.
The way Business Components for Java represents this selective view of data is through a
view object. View objects are reusable components that contain a SQL query. This query can
be based on one or many database tables. In your business components application, each
unique view of data will be represented by a single view object. You will have as many view
objects you need to represent the data in your "forms".
When you think of view objects, think of them as being half of a data block, the part responsible
for querying data.
Entity objects represent tables
Like Forms data blocks, entity objects are usually based on database tables or views. Think of
entity objects as classes that represent your database tables.
The representation of tables in your forms-based application correspond one-to-one with entity
objects in a business components application. For example, if you have an Orders form that
modifies information in the Salesperson, Customer, and Item tables, you would have three
entity objects that represent those tables.
Entity objects are not only used for storing data, but are also used to validate data. Entity object
validation is done at a higher level than database triggers, and this is a common source of
confusion. While you can use triggers with Business Components for Java, it makes more
sense to attach the validation to the entities, as you can then apply validation to unposted data.
11-172
Forms relations are functionally similar to view links
The master-detail functionality performed by Forms relations is provided by view links. View
links define the relationship between two view objects. To define a view link you specify which
view object is the master, which is the detail, and specify which columns they are related by.
A Form is similar to an application module combined with a UI
In your forms-based applications, each form was probably created to do a particular task; a unit
of work within a single transaction. For example, you might have created an Order form who's
task it was to do everything required to place an order: first to take the information from the
order, then to make sure the information there was valid, and finally to post changes to the
database.
In Business Components for Java, every task is associated one-to-one with an application
module. In the above example, your Order form would be represented by a single application
module. Unlike a form, there is no user-interface component to an application module, it is
simply a model of the data and how they relate to each other. With a user interface "front end"
plugged into the application module, the functionality is the same as a form.
Application modules are containers for view objects and view links
A form is a container for data blocks, and as such might have displayed data from multiple
views of data. For example, an Order form could have contained data blocks based on the
Customers, Items, and Salesperson tables. Likewise, if your task requires the use of more than
one view of data, your application module will contain more than one view object. An
application module also contains view links, which describe the relationship between the view
objects.
The way that view objects and view links are related to each other is not coordinated by the
framework, as they are with data blocks and relations. Instead, the queries (view objects) and
relations (view links) are described by a data model.
Familiarity with Oracle Reports will help you with data models
If you are familiar with Oracle Reports, you know that Forms and Reports are conceptually
different in the way that they deal with the data model. In Forms, there is an implicit data model
described by the data blocks and relations. Oracle Reports separates the queries and
relationships, allowing you to define the data model explicitly; you can build a data model from
queries and draw links between the queries.
11-173
Just like Reports, the data model in Business Components for Java is explicit, but is described
by in an application module by view objects and view links. Based upon those similarities, one
way of looking at Business Components for Java is that it provides the separation of data
provided by Reports with the data manipulation provided by Forms.
Associations
When two database tables are linked by a key, the business component representation is an
association object. Associations allow you to retrieve data from related tables.
Associations are created automatically by the business components framework when database
foreign key constraints are detected in the database. You can also create associations directly
using the business component wizards. View links can be easily created using the underlying
associations. This makes it very easy to get related information and show it on the UI.
Reviewing Business Components
Before you go on, it might be helpful to recap what you have learned by reviewing the the role
of business components and how they relate to Forms constructs:
● View objects are the "query" part of a data block.

● Entity objects are the "data-manipulation" part of a data block.
● View links describe relations between view objects, and are similar to a Forms relation.
● Application modules represent a task, and are the data model part of a form.
● Associations represent database foreign keys.
Comparing Application Development
In both Forms and Business Components for Java, you start by creating a framework-level
container. In Forms this is called a Form Module, while in Business Components for Java this is
called a Project. Next, the objects that will communicate with the database are created. For
Forms this is the data block, for Business Components for Java, these are the business
components. Up to this point, application development is quite similar.
The first difference you will notice about Business Components for Java is that the data
elements are not tied to the UI in the same way that they are in Forms. In Business
Components for Java, your UI components can take information from any number of underlying
database tables. While you can start laying out UI elements immediately in Forms, in Business
Components for Java you create your UI separately.
11-174
Another difference that you'll notice, and one that is related to separating the business logic
from the UI, is in the way business rules are enforced.
Enforcing Business Rules
Suppose you want to create an application that allows employees to view and change their
data. Among the business rules you needed to implement could be the following:
● Enforce that an employee's manager must also come from the Employees table
● Make sure the number of vacation days they enter is less than or equal to the number of
vacation days they have saved up
● Ensure that a password is alphanumeric and longer than 4 characters
Enforcing Business Logic in Forms
In a forms-based application, the client forms enforce the business rules through UI controls
such as lists and option buttons. Validation is enforced through UI events, such as a text field
losing focus, or a database event such as a new row being inserted.
The three conditions that need to be validated might be done in the following manner:
● To enforce that an employee's manager must also come from the Employees table, you
might use a list control.
● To check that entered vacation days are less or equal to the number of days they have
saved up, you could run code on a lost_focus event.
● To validate that the password is formatted correctly, you'd use a trigger on the database
Enforcing Business Logic in Business Components for Java
To enforce the same three business rules in Business Components for Java, you would not
code the validation in the client or on the database. Instead, validation code goes on the
business logic tier (business logic tier).
● To enforce that an employee's manager must be in the employee table, you would use a
list validator bean attached to the entity object. (This is done through the Entity Object
Wizard by pointing and clicking at a validator bean.)
● To check that entered vacation days are less or equal to the number of days they have
saved up, you would edit the Java code on the entity object.
11-175
● To validate that a password is formatted correctly you would create a new dataype that
was both alphanumeric and longer than 4 characters, and assign this as a datatype for
the entity object. Custom datatypes are created using a business component domain.
Reusing Business Logic
Now suppose you had to create another similar form, this one to be accessed by managers and
additionally showing salary information. In a typical RAD environment, this means creating a
new UI, attaching validation code to the various fields, etc.
In Business Components for Java, you can reuse all the validation without re-coding any of it.
Since all the validation is attached to the entity objects, every time you use the entities the
validation comes with it. This is a drastic improvement in reusability. Also, if the business rules
change, for example, the passwords are now required to be 8 characters, you can edit the
entity objects to reflect that change and all views of data are simultaneously updated. The
reuse of business rules is one key advantage of Business Components for Java. Another is the
flexibility of the framework.
Customizing the Framework
One frustration for Forms developers is that it is very hard to change the way the Forms
framework operates. If you want navigation or validation to work in a special way, you have to
short-circuit the framework by writing triggers. Indeed, developers can spend a great deal of
time writing triggers to deconstruct the default way the framework operates so that they can
customize behavior for their application.
Business Components for Java allows you to extend new business components from base
business component classes, or even substitute new business components for the existing
ones. This means that an enterprise application can be modified after it has been delivered,
without ever changing the original source code.
Working on Multiple Forms
In Forms, when you are working with a master-detail form and you want to make changes to
another form, you must first commit the changes to the form you are working on. This is a
limitation for the user, as they might be forced to commit changes before they are through with
the form. The user interface can be misleading in this way, because it allows you to look at the
forms as if they are independent. For working on forms that are dependent on each other, this
model is very hard to work with.
11-176
Also, if the information in another form was necessary to complete the task in the form the user
was working on, the user would need to do a query over the other forms to find that information.
After seeing multiple query results from the search, they would go to a detail screen that show
more info, and gather their information there.
In Business Components for Java the user can work on multiple forms at the same time. A
change in one record propogates to multiple forms. The user can query back and forth between
objects and make whatever modifications they desire. If the task on one form is related to other
forms, the interaction between forms is seamless. Finally, the user can commit the changes
when they are through with their work, not when the framework forces them to.
Although Business Components for Java allows users to work on multiple forms at the same
time, this feature exposes a limitation, which is the inability for the framework to clear a block
(or record) at the form level.
In Forms, CLEAR_BLOCK (or CLEAR_RECORD) allows you to clear all the changes made in
a single block and start over again. You can't do this in Business Components for Java
because the view object you are trying to clear may have made changes to other view objects
11-177
and these changes are not kept track of by the individual view objects. This management of
data is done at the application module level, which is why you can work on multiple forms at the
same time. If you want the ability to clear data at the form level, it must be managed in the UI,
not in the framework.
Summary
Forms and Business Components for Java are both application frameworks, and from a high
level, they share similar architectures and concepts. However, Business Components for Java
is a finer-grained solution that separates the metadata from the UI. The benefits of this are
many, including easily reusable business logic, a customizable framework, a client-independent
business logic tier, and caching of data at the application level.
Related Topics

Understanding the N-tiered Architecture
11-178
Understanding Deployment Configurations
The following table lists the deployment configurations available in JDeveloper. There are three
possible physical tiers: the client process, the application server process, and the database
process. The database process is always present to manage the application data.
Type of Business
Process Running Process Running Number of
Type of Client Components
Client Business Components Physical Tiers
Deployment
Java Application or
Client Process Local Mode Client Process 2
Applet
Java Application or VisiBroker CORBA Application Server

Client Process 3
Applet Server Object Process
EJB in Application
Java Application or
Client Process Server CORBA Server Process 3
Applet
(OC4J/WebLogic)
JSP, XSQL page, or Application Server Application Server
Web Module (WAR) 2
Servlet Process Process
JSP, XSQL page, or Application Server VisiBroker CORBA Different CORBA
3
Servlet Process Server Object Server Process
EJB in Application
JSP, XSQL page, or Application Server Same or Different
Server 2 or 3
Servlet Process Application Server
(OC4J/WebLogic)
Java Stored
Database Process Local Mode Database Process 1
Procedure
Related Topics

List of J2EE Deployment-Related References
Understanding the n-Tiered Business Components Architecture

11-179
BC4J Setup and Deployment Prerequisites for OC4J Deployment
11-180
About Debugging Multi-Tier Programs
Debugging a business components project is no different from debugging any other project in
JDeveloper. You can debug a multi-tier program from within the JDeveloper design
environment as you would any Java applet or application. You may need to configure the
debugging environment to specify the source root directory in the
To debug a business components program file:
1. In the Navigator, select a multi-tier program project file (.java) and choose Debug
<name of file> from the context menu. Alternatively, you can choose the Debug |
Debug <name of file> main menu option.
2. Debug your multi-tier program by setting breakpoints as you would any other Java
application.
Note: To view the results of your debugging session, choose View | Debug Windows <name of
window>.
Related Topics
About Debugger and Runner Toolbar Icons
Setting JDeveloper Options for Debugging
Connecting to the Remote OJVM
11-181
Entity objects are classes that encapsulate the business model, including rules, data,
relationships, and persistence behavior, for items that are used in your business application.
For example, entity objects can represent
● the logical structure of the business, such as product lines, departments, sales, and
regions
● business documents, such as invoices, change orders, and service requests
● physical items, such as warehouses, employees, and equipment
From an object-oriented perspective, an entity object represents an object in the real-world

problem domain. From a relational database perspective, an entity object provides a Java
representation of data from a database table (or view, synonym, or snapshot). Advanced
programmers can map entity objects to other types of data sources, such as spreadsheets, flat
files, and XML files.
Depending on how you want to work, you can automatically create entity objects from existing
database tables (reverse generation) or define entity objects and use them to automatically
create database tables (forward generation).
Entity objects encapsulate business logic
The best place to write your business logic is in entity objects, because they consistently
enforce business logic for all views of data, accessed through any type of client interface.
Business logic includes the following items:
● business rules and policy — When adding or modifying data, you can ensure that the
data complies with your organizations' procedures before adding it to the database. For
example, you could increase the salary when an employee is promoted, give an
employee three weeks of vacation after they have been at a company three years, or
change the status of an order to shipped after all items in an order have been mailed to a
customer.
● validation logic — When adding new data, you can ensure that the data is valid before
storing it in the database. For example, you could ensure that a job code is a valid job
11-182
code.
● deletion logic — You can make sure that data is deleted only when appropriate and that
any dependencies are handled. For example, you could prevent an on-leave employee
from being removed.
● calculations — You can efficiently perform data calculations in the business logic tier. For
example, you could calculate an employee's monthly pay based on an hourly rate.
● default value logic — When creating new data, you can add appropriate default values.
For example, you could provide a default benefit plan based on an employee's job code.
● security — You can make sure that data is read and modified only by users with that
authority. For example, you could ensure that only the direct manager can change an
employee's salary.
Business logic in an entity object provides immediate feedback to the user if changes are
inappropriate. This way, the in-memory business model always remains consistent.
Entity objects map to database tables
When you use a Business Components for Java wizard to create entity objects from existing
tables (reverse generation), it creates one entity object for each database table. It creates an
entity attribute for each column in the database table; each attribute can have the same name
as the column or a different name that is more meaningful to your business application. The
attribute definitions of an entity object reflect and enforce the properties of the respective
database columns, including data types, column constraints, and precision and scale
specifications.
An entity object can have an attribute for each column or you can use a subset, for example, if
you don't need to work with that column or if a table contains information for more than one
entity.
You can also use Business Components for Java wizards to define entity objects, and their
attributes, without starting from an existing database table (forward generation). When you use
a wizard to generate database tables from entity objects, it creates a table for each entity
object, a table column for each entity attribute, and column constraints based on the entity
attribute settings. In addition, you can use the Entity Constraint Wizard to define table
constraints.
11-183
Multiple entity objects can map to the same table
Usually, one entity object maps to one database table. However, a table could store multiple
categories of information, so you might need to map multiple entity objects to it.
You can apply different entity objects to different rows. For example, an Items table might store
inventory items, requisition items, order items, and so on, in different rows of the table. For
each type of row, you would define one type of entity object. In this case, you could have an
Item entity object, and InventoryItem, RequisitionItem, and OrderItem entity objects that extend
it. In addition, for each entity object, you would define one or more attributes to be a
discriminator so the framework can automatically determine which rows map to which entity
objects, and manage entity object storage. You would omit columns that do not apply to the
entity object you are defining; however, each entity object must always include the primary key.
You should never map multiple entity objects to the same row.
Tools help you create entity objects
You can create and edit entity objects by using the Entity Object Wizard and Editor. For reverse
generation, you can also use the Business Components Project Wizard or Package Wizard or
Editor to create default entity objects. Default entity objects contain attributes for each column
in the table; you can customize default entity objects in the Entity Object Editor.
You can also create entity objects from a UML class diagram in JDeveloper. For more
information, see Modeling Business Components.
Each entity object instance represents a row
During runtime, each entity object instance represents a row in the database table and stores
its data. There is only one instance per row, and all instances of the same entity object class
within the same transaction are cached together. Multiple view object queries returning the
same row refer to the same entity object instance, so updates are visible to all view objects;
one entity object can be used by multiple view objects. Each entity object instance is uniquely
identified by its primary key attribute or attributes. For more detail, see How Does the Business
Logic Tier Cache Data?
View rows can make entity object methods available to clients
For security reasons, entity objects are not exposed to clients. Instead, clients access an entity
11-184
object’s data through one or more view objects. In the view row class, you can make entity
object methods available to a client by writing a view row method that calls the method you
want to expose. For example, you could use this feature to implement security: you could
create different view objects so different clients have varying levels of access to entity object
methods.
Associations represent relationships between entity objects
Relationships between entity objects are expressed through associations. They match
attributes, typically key fields, from source and destination entity objects. Accessor methods
that return rows and row sets through the association are available on the entity object class.
UML class diagrams model entity objects
To decide which entity objects your application needs, you can model them on a UML class
diagram in JDeveloper. For more information, see Modeling Business Components.
Related topics
The Files that Define an Entity Object
11-185
An association is a business component that defines a relationship between two entity objects
based on related attributes. The relationship can be one-to-one, one-to-many, or many-to-many.
The association allows entity objects to access the data of other entity objects through a
persistent reference.
Associations and foreign key relationships can be created from

each other
Business component wizards can automatically create associations based on the database
constraints already defined in the database. They can also create database constraints based
on the associations you define.
Associations are independent of database constraints
You are not required to have both an association and a database constraint defining the same
relationship. An entity object only needs an association to access the data of another entity
object, regardless of whether the corresponding constraint exists in the database through a
foreign-key relationship or object REF.
For example, you might want to have an association but not a database constraint if you want
to be able to insert a child before the parent exists.
An example of an association
In an organization, you might have a one-to-many relationship between departments and

employees. The Department entity object could be related to an Employees entity object
through DepartmentId attributes (Department.DepartmentId =
Employees.DepartmentId). The following figure shows how the association, by default
named EmpDeptFkAssoc, would appear in the JDeveloper Structure pane:
11-186
The source end, containing the primary key, is the Departments entity object. The destination
end, containing the foreign key, is the Employees entity object.
Tools help you create associations
You can define and edit associations in the Association Wizard and Editor.
You can also generate default associations, based on foreign key constraints in existing tables
(reverse generation), by using the Entity Object Wizard and Editor, Business Components Project
Wizard, or Package Wizard.
You can optionally add foreign-key constraints to tables based on the associations you've
defined in the Association Wizard and Editor (forward generation).
If you add database constraints after generating your business components, you can
automatically create the corresponding associations in the following ways:
● Use the Synchronize tool to create associations based on new foreign key constraints.
● Click Finish in the Entity Object Editor to create the new associations (the attributes
corresponding to the foreign and primary keys must be included in the entity objects).
Accessors let you retrieve data across associations
Through optional association accessor methods in the entity objects, you can access data on
the other side of the association. Your code can traverse associations in either direction. For
example, inside the Department entity object, you could call the getEmployees method and
retrieve a row set of Employees entity objects that reflect the employees working in the current
department. Similarly, from the Employees entity object, you could call the getDepartment
method to get the department that an employee works in. The data is cached, so the first time
you call the method a database query is executed, but the next time it returns the cached data,
saving time.
An entity object can call accessors in sequence to traverse multiple associations to get the data
it needs. Remember to close the iterator that's returned from the accessor after it's used, to
avoid having too many row sets in the system.
An association can be a composition
11-187
A composition relationship means that the source entity object "owns" the destination entity
object: no destination entity object can be created without the owning entity object existing first.
The source entity object (the parent) is a container for one or more destination objects (the
children). If a destination entity object is modified, the source entity object is "marked" as
needing validation.
A child entity object can't be created without its parent. When a child entity object is created,
the framework assigns foreign key values to match the parent primary key values.
For inserts, updates, and deletes, the child entity object is considered to be part of the parent
entity object. A parent entity object containing valid child entity objects can't be deleted until all
of the contained child entity objects are deleted. When attempting to change a child entity
object, the business logic tier attempts to lock the parent entity object; the topmost parent entity
object must be successfully locked or the change will not be allowed. For example, if you have
an order with line items, and a user starts to modify a line item, the entire order is locked so no
one else can modify the order or its items.
When you have a composition, in the validateEntity method of the parent class, you can add
code that enforces a business rule involving multiple children. When data is changed in a child,
the parent is marked for revalidation so that all rules about children can be enforced. For
example, you could add code in the validateEntity method of an Order entity object so the total
of an order's items can't be above the customer's credit limit.
Deciding whether an association should be a composition
To determine whether two entity objects have an ownership relationship, there are two
questions you can ask.
Can a destination entity object exist independently of a source entity object?
● If Yes, the source is associated to the destination.
● If No, the source is composed of the destination.
For example, can a line item exist independently of an order? The answer is no, so the
relationship is a composition.
When I delete the source, do I also delete the associated destinations?
11-188
● If Yes, the relationship is a composition.
● If No, the relationship is an association.
For example, if you delete an order, should you delete all of its line items? The answer is yes,
so the relationship is a composition between orders and line items. If you delete a department,
do you delete all of its employees? The answer is no, so the relationship is an association.
During reverse generation, if a referential integrity constraint in the database was defined with
the ON DELETE CASCADE option, Business Components for Java automatically creates a
composition.
UML diagrams model associations
To decide which associations your program needs, you can use UML object-oriented modeling
techniques. A business component association is an implementation of the UML association
concept.
Related topics
The File that Defines an Association
11-189
An attribute is a named characteristic of an entity object or view object, implemented as a
JavaBean property of the object class. An entity attribute can correspond to a database
column, or be independent of a column, and describes the values that the entity object can
hold.
Two kinds of entity attributes
There are two kinds of entity attributes:
Attribute Value is derived from and

kind stored in the database?
persistent yes
transient no
Persistent entity attributes correspond to database columns
When you first create an entity object using reverse generation, a persistent entity attribute is
created for each table column.
For forward generation, when you create database tables from entity objects, each persistent
attribute becomes a column in the table.
After, if you change a table or entity objects, you can use the Synchronize tool to make sure
that the tables and entity objects are in sync.
Entity attributes have settings
While creating or editing an entity object in the Entity Object Wizard or Editor, you specify
attribute settings. The settings can affect forward generation or the settings can be derived from
an existing table (reverse generation). The following table summarizes which settings affect
forward and reverse generation, and which settings apply to persistent and transient attributes.
For persistent attributes, the settings determine the type of column and the constraints on it.
11-190
Attribute Forward Generation of Reverse Generation from Persistent Transient
Setting Database Tables Database Tables Attribute Attribute

Attribute Type N/A Default based on column Required Required
data type; you can choose
another type in the list or
import a domain that isn't
already in the list.
Primary Key Becomes the table's primary From the table; you can Selectable Selectable,
key, or part of it if you specify change it if you don't want it but you
multiple primary keys for a table to match the table, or add a should
(a composite key) primary key if the table didn't leave it
have any. deselected
in most
cases
Mandatory Becomes a mandatory column in From the table; this value Selectable Selectable
the table (a NOT NULL must match the table, or you
constraint is generated for that might get problematic runtime
column in the table). behavior or an exception.
Persistent Only persistent attributes are All attributes derived from the Selected Deselected
added to the table. table are persistent; if you
business components
framework.
selected.
Database Column Becomes the table's column From the table; it must match Required; it N/A
Name name the table. must match
the table.
Column Type Becomes the table's column From the table; it must match Required; it N/A
data type the table. must match
the table.
11-191
Unique If selected, the column has a From the table; it must match Selectable N/A
unique constraint. the table.
In general, if you are performing reverse generation, you don't want to change the primary key,
mandatory, database column name, column type, and unique settings that were received from
the table. For forward generation, the primary key, mandatory, persistent, database column
The attribute name and type settings affect the entity object Java code. They determine the
signature of the Java attribute accessor.
All of the attribute settings are stored in the entity object XML file.
Entity attributes are based on the UML definition
In Business Components for Java, the term "attribute" is based on the UML definition of the
term, not the XML definition. In UML, an attribute is a named property of a class that describes
a range of values that instances of that class might hold.
Related Topics
Ways to Edit Entity Attributes
What is a View Attribute?
What Is a Domain?
11-192
Business Components for Java provides a framework for defining, implementing, and executing
validation logic in the business logic tier. The validation framework provides a consistent
programming model that hides internal implementation details. It frees you to focus on rules
that make sure your new and updated business data is valid.
Business logic tier validation occurs separately from database

validation
Business logic tier validation is different from a database constraint. A database constraint is a
declarative way to define a business rule for a column of a table. Database constraints are
defined with a table and are stored as part of the table's definition, centrally in the database's
data dictionary, so that all database applications adhere to the same set of rules.
You want to use business logic tier validation when you need to check data as it is cached in
the business logic tier; you can use database constraints when you want data to be validated
as it is committed to the database. In addition, you can use database constraints to be
absolutely sure that all data in the database is valid, even if someone modifies data through a
SQL statement or another program.
Business logic tier validation assumes existing data is valid
The business logic tier employs validation logic when it needs to create or change data, but it
assumes that data already in the table is valid. So a query could return a result set that
contains invalid values (for example, from legacy data entered before the validation logic was
applied), but a user cannot enter an invalid value into the table.
Ways to implement validation logic
You can define and apply validation logic in the business logic tier in the following ways, listed
in the order they are triggered (from first to last). All of these techniques are programmatic (in
Java code), except for validation rules, which are declarative (in XML code).
Using domains as a data type for entity and view attributes
A domain object is a developer-defined data type that can contain validation, which is
performed when the domain instance is constructed. You can use a domain as the data type of
an entity or view attribute, or both. By embedding your validation logic in a domain, you reuse
11-193
the same logic everytime you specify the domain as a data type of an attribute. For example, a
CreditCard domain would be very reusable — you wouldn't have to rewrite this validation code
for every attribute that needs it and you could maintain the logic in one place.
Depending on how you program your client, the domain validation can be triggered at the client
or at the business logic tier. For example, a Java client can construct the domain instance in
the client tier when a user tabs out of a field. So the user gets feedback immediately if they
enter an invalid value. Alternatively, the client could pass the value as a Java type, where the
business logic tier converts it to a domain, which validates the value later than when you
instantiate it on the client.
Once constructed, instances of domains can be freely passed around in a type-safe way as
method parameters.
Adding code to entity setAttribute methods
The business components framework can generate specific setAttribute methods for entity
objects (for example, Department.setLocation). In these methods, you can add validation that
occurs before or after the attribute is set. As a good coding practice, if you override a
setAttribute method, you want to place any validation logic that throws exceptions before you
call setAttributeInternal; otherwise, it can be hard to retrieve the attribute's previous value
before an exception was thrown.
In the setAttribute method, you would add validation logic that applies only to that attribute
value. If you will reuse the logic multiple times, consider putting the logic in a domain instead.
You can also override the setAttributeInternal method if you want to add attribute validation
logic in a single method. Remember to add validation logic, and catch any exceptions, before
calling super.setAttributeInternal; otherwise, the previous value (before the exception was
thrown) can be harder to retrieve.
Adding code to the validateEntity method
The base entity class provides a validateEntity method that your entity objects can override.
Entity validation occurs when moving from one row to another. It is useful for validating values
of two or more attributes; for deferring validation of individual fields until values for the entire
row have been entered; for validating values in separate entity objects that are associated. For
example, when you set a Salary attribute, you may need to check other field values, such as
job title, currency, and so on. Another example is a date range, where the begin date must be
less than the end date.
Applying validation rules to entity objects and entity attributes

11-194
Validation rules encapsulate reusable patterns of validation that you can use by supplying
appropriate parameter values. You can use the Entity Object Wizard and Editor and Attribute
Editor to define and apply simple rules without writing code. When you use the wizard or editor,
it generates XML, enabling you to customize rules without recompiling Java code.
You can use predefined validator types or define your own. You could implement more complex
rules in your own custom validation classes; then you can register the classes as validator
types and apply them, the same as the predefined rules.
Defining a composition
A composition provides parent and child hierarchic validation at the entity object level. The
validateEntity method of the parent validates the children by calling their validate methods. For
example, for an order system, a composition ensures that an order is not valid unless all of its
line items are valid.
When to use a domain or validation rule, or modify entity object

code
When deciding whether to use a domain or a validation rule to add validation logic, remember
that a domain can be used by multiple attributes, while a validation rule applies to one attribute
or entity object only. For example, it's appropriate to use a domain to validate a URL attribute,
because you might want to use the domain with another attribute later. But if you're checking
whether a field contains one of Platinum, Gold, or Silver, you'd use a validation rule because it
is unlikely that you will have another attribute that uses these values.
Alternatively, instead of using domains and validation rules, you could implement validation
logic by modifying the Java source file of the entity object. Like a validation rule, this logic
applies to the entity object or attribute only; however, you can add more complex logic that
might not be possible through a validation rule.
When validation logic and database constraints are triggered
Remember that the framework applies rules to contained objects before invoking rules on top-
level objects. Database constraints and validation logic are triggered as follows:
● When data is read in from the database, domain validation occurs.
● When entity attribute values are set, attribute level validation (including domain
11-195
validation) occurs.
● Entity level validation occurs when row currency changes, validation is explicitly called,
or before committing to the database.
● Database constraints are fired when data is posted to database, after validation logic in
the business logic tier has triggered. Or, you can explicitly fire database constraints
before entity level validation by using the postChanges method.
Executing a view object query
When data is requested by a view object query, no validation occurs as the data is read in,
except validation in the domain constructor (if present), which occurs as object instances are
created.
The framework assumes that committed data in the database is valid because all data placed
in the database by the business logic tier passes validation first. If you have legacy data or if
another application or SQL statement modifies the data, you could have data that doesn't pass
validation in a domain constructor. If data does not pass this domain validation, the fetch
operation fails: no data is read in, even if just one attribute fails validation.
Setting an attribute value
When you assign a value to an attribute by calling the setAttribute method (for example, a Java
or JSP client calls it), the business logic tier performs type validation. If the value's type is not
assignable, the framework attempts to convert it using the constructor of the class that is the
attribute's type, which could be a domain. If the conversion fails, the framework throws a
JboException. Note that if you call a specific getter or setter in an entity object, the Java
compiler checks the types, so a runtime check is not necessary.
Attribute-level validation occurs after type validation. This includes validation logic in a
setAttribute method, the setAttributeInternal method, and attribute-level validation rules, in this
order.
Changing row currency
If the row iterator moves to a different row, entity-level validation fires under these
circumstances for the previous row:
● Data in the row was modified.

11-196
● The row is a parent in a composition. (All children are validated, too.)
● The row was just inserted (it's new).
● The application markeds the row as invalid (using the setInvalid method).
For view row iterators other than the default ("secondary" view row iterators), you can switch off
entity validation with the setRowValidation method.
Posting and commiting changes
At commit time, the business logic tier performs entity-level validation on all entity objects that
need it. Except for composition validation, the order that invalid entity objects are validated is
nondeterministic. For every new, modified, or deleted entity object posted to the database, the
framework performs DML operations to save the data in the database; this causes the
database to fire triggers and enforce constraints. If the DML operation fails, a DMLException is
thrown. If you want to perform operations in the database against pending changes, you can
post the data but not commit it. For example, sorting in the database (through ORDER BY) can
be the fastest way to sort large amounts of data. If you want newly created rows to be sorted
with the existing rows, you would need to move the newly created rows to the database. To do
so, you can call the postChanges method on the transaction to trigger database validation
logic, but not entity validation. If you want entity validation to trigger, first call the validate
method on the entity object, view object, or the transaction.
For composition relationships, first the children entity objects are validated (only the ones that
need validation). Then the parent entity object is validated. The order that children are validated
is nondeterministic: usually, the entity objects that were modified first are validated, but this
order is not guarenteed.
See About Commit Cycle Processing for more information.
Explicitly starting validation
You can invoke entity validation explicitly by calling methods in the business components API,
such as Entity.validate, Transaction.validate, Row.validate, or
Transaction.commit.
How validation rules are usually triggered in a Java GUI client
Typically, attribute validation occurs when the value of an attribute is changed by a setAttribute
method (for example, setDname). For example, if your GUI client is coded so that setAttribute
11-197
is called when a user changes a value and tabs out of a field, then validation is triggered:
Entity object validation is invoked before moving from one row to another, if the GUI client is
programmed to change the current row of the iterator at the same time:
As explained later, this description applies when deployed in local mode or, for remote mode,
when the sync mode is immediate. This example does not apply when the application is
deployed in three-tier environments and the sync mode is lazy.
How validation rules are usually triggered in an HTML client
If you are using JSP, XSQL Servlet, or a servlet, the data that users enter in a web page is not
transferred to the business logic tier until the web page is submitted. At this point, any changed
attribute values are set with a setAttribute method, and attribute validation is triggered. If a page
is being submitted because the user selects a different row (or master row in a master-detail),
entity object validation occurs because the current row on the current row iterator changes.
How you can use sync mode to reduce network traffic
After deployment, you can set the sync mode of an application module through the
setSyncMode method on the ApplicationModuleImpl class. The sync mode determines when
the setAttribute method is called. You can set it to "lazy" to optimize your application by
reducing the number of trips over the network. The sync mode is only used when you deploy in
remote mode, not local mode.
11-198
For example, if the client is setting ten attributes of an employee, your code would call ten
setAttribute methods. If the application uses a sync mode of immediate (the default), the
application makes ten trips over the network and attribute-level validation fires immediately. If
the sync mode was lazy, the client-side attribute set requests are buffered until the next time
the client sends a message to the business logic tier, for example, when the client changes the
current row, calls the postChanges or commit methods, calls the sync method, or calls the
validate method on the row.
Note that when you are using lazy sync mode, you must handle errors differently then when
you are using immediate sync mode (for example, there are network error handling
considerations).
Deferring validation
If you specify that a transaction should defer validation, setAttribute methods do not fire
validation rules. Instead, ValidationExceptions thrown in your logic, either in setter methods or
setAttributeInternal, are cached and not thrown immediately. See Using Bundled Exceptions for
more information.
11-199
Entity Object Row States
The following figure shows the possible entity row states:
The following figure shows the possible entity row post states, and the progression between
them:
11-200
11-201
Business Components for Java lets you execute any JDBC statement from your business logic.
For example, you can call a stored procedure from an entity object. Some possible scenarios
are:
● You have legacy tables with stored procedures and want to continue to use the stored
procedures.
● You want to do an efficient "existence check" that a certain record exists in the database.
● You want to call a stored procedure to do validation.
In general, to invoke a stored procedure from within an entity object, you need to:
1. Create a JDBC CallableStatement with the PL/SQL block containing the stored
procedure invocation.
2. Bind any variables.
3. Execute the statement.
4. Optionally retrieve the values of any OUT parameters.
5. Close the statement.
To create the CallableStatement, you use code like this:
DBTransaction tr = getDBTransaction();
CallableStatement st = tr.createCallableStatement(...);
After the statement is created, you use standard JDBC APIs to perform the remaining steps.
Application developers using Oracle databases often take advantage of PL/SQL packages in
the database to centralize business logic and to control access to data from a table. The typical
scenario involves:
1. Revoking all privileges from a table so users cannot work directly with the table.
2. Creating a PL/SQL package with public procedures to provide an API to select, update,
insert, and delete a row in the table.
3. Granting EXECUTE privilege on the package.
11-202
Entity objects can be mapped in a straightforward manner to interact with a stored procedure
API like this instead of performing their default DML directly against a database table.
To call stored procedures, there are two methods in the oracle.jbo.server.EntityImpl class that
you need to override in your entity object class:
● doDML to implement create, update, and delete logic

● doSelect to implement locking and fault-in behavior (it gets all entity attributes)
Using these methods, you can integrate stored procedures into the Business Components for
Java model: they let you implement your own custom logic instead of using the default behavior
provided by the framework.
To override the default way that entity objects do their DML operations, overide the doDML
method. The doDML method will be invoked by the framework whenever an instance of your
entity object type needs to be inserted, updated, or deleted from the database. The framework
indicates which operation its expecting to be performed by passing an 'operation' flag as an
argument to the doDML method.
Your custom doDML method should check whether the operation flag equals DML_INSERT,
DML_UPDATE, or DML_DELETE and act accordingly. To invoke a stored procedure, create a
CallableStatement (as mentioned previously) and invoke the appropriate procedure. If the
procedures are returning any modified column values in PL/SQL OUT variables — for example,
the package's insert_rowprocedure might return a primary key value assigned from a sequence
— you will need to retrieve the returned parameter values from the JDBC statement, then
populate their values into the entity object's attribute values using the
populateAndNotifyChanged method.
It is easy to call stored procedures, but you need to make sure that when stored procedures
make modifications to data in the table, that these changes are reflected back to the entity
cache when needed by your program; you need to determine under what circumstances it is
important to your program to fetch back some or all of the changed values in the database.
Your entity object could use a helper view object to requery the database, or you could use
doSelect to get the changes.
Related topics
Calling Stored Procedures
11-203
A view object is a class that lets you define and work with a set of rows, often in service of a
user interface. Typically, a view object contains a SQL query that selects data from a database.
It can be associated with underlying entity objects so you can modify data in the database, or
not be associated with entity objects at all.
View objects are based on what the client needs to display
A view object uses a SQL query to specify filtered subsets of business data that can be related
to attributes from entity objects. You create views based on what the client needs to display.
The views of data can be based on but are independent of the underlying entity objects,
enabling flexible data retrieval to support the required UI. In other words, you can query a set of
data exactly as you want to show it in the display. The view object defines the attributes of the
view row class, which represents a row in the query result, and optionally refers to underlying
entity objects. View objects provide clients with row sets they can scroll through and update
without concern for or knowledge of the underlying entity objects. Clients manipulate data by
navigating through the result set, getting and setting attribute values; changes are made to the
data in the underlying database when the transaction is committed. Relationships between view
objects are expressed using view links. Each view object provides a default iterator that you
can use to navigate through its result set.
For example, the following figure shows the relationship between a view object, entity object,
and the underlying database table. A view object named EmpNames operates on the Emp entity
object to provide a view of the EMPNO and ENAME columns of the EMP table.
11-204
View objects are often used to:
● Provide an additional level of security by restricting access to a predetermined set of

rows and columns. For example, you could create a view object where columns
containing sensitive data (such as salaries) are not selected.
● Hide data complexity. For example, a view object can display columns or rows from
multiple entity objects. Such a view object hides the fact that the data is coming from
several tables.
● Customize presentation. Using a view object, you can rename columns without affecting
the entity objects on which the view object is based.
● Store complex queries. A query could perform extensive calculations on table data. By
saving this query in a view object, the calculations are performed only when the view
object's query is executed. The calculation is executed before the data is retrieved from
the database.
11-205
● Improve efficiency of the application by using fast-executing, optimized SQL, selecting
only the data you need.
Types of view objects
You can define the following general types of view objects, either at design time or dynamically
at runtime:
Does the view Does at least one You can use the view object for... And you get these benefits...
object contain view attribute map
a SQL query? to an entity
attribute?
yes yes querying, updating, inserting, and data consistency with other view
deleting data objects that map to the same
entity objects, and memory
savings
yes no querying data less overhead (and potentially
faster) than when you map to
entity objects, especially when
using forward only mode (where
there is no view caching)
no yes inserting data no initial query is executed,
which saves startup time
no no temporary collections of data can use the same consistent
interface for data and easily bind
data to a user interface
In addition, it's possible to use a datasource other than a database, for example, a flat file,
spreadsheet, or XML file. In this case, you would need to write custom code so a view object
reads data from the datasource, and entity objects write data to the datasource.
A view object can map to multiple entity objects
You can define multiple view objects per entity object, and a view object can select data from
multiple entity objects. Data is cached at the entity object level and all view object references
within the same transaction share the cache, so changes made through one view object are
immediately available to other view objects in the same transaction.
For example, the following figure shows a view object selecting from multiple entity objects.
11-206
View objects named DeptEmp and EmpNames select data from the Emp entity object.
DeptEmp also selects data from the Dept entity object.
When you define a view object, you can specify which underlying entity objects are read-only
and which support read/write operations on participating attributes in the view object's attribute
list. For example, when defining a view object based on the EMP and DEPT tables (with
associated Emp and Dept entity objects) you can specify that Emp information should be
modifiable, while Dept information is presented only as supporting information.
View objects and view links can be part of an application module's

data model
In the Application Module Wizard and Editor, you can choose the view links that you want to
use to link view objects in master-detail relationships. View links can also be specified in code
that executes at runtime. Detail view objects are automatically synchronized with their
respective master view objects.
An application module can use the same view object more than once, such as an unrestricted
view and a detail view; you can specify aliases to represent the various usages of a given view
11-207
object.
For example, the following figure shows an application module using a master-detail view
(DeptView) and a top-level view (EmpView). You could provide views of the DEPT and EMP
tables linked master-detail by a view link, and a top-level view of the EMP table. The alias for
the DeptView is MyDeptView. The view object EmpView has two aliases:
MyEmpDetailView (used in a master-detail link) and MyEmpView (used to present a top-level
view).
SQL queries can be customized
Business Components for Java automatically creates SQL queries for you in the design-time
wizards. However, you can customize SQL queries as needed. If you need complete control
over an entire query, you can define expert mode queries.
Using view objects with a user interface
The typical sequence of what happens at runtime is:
1. Client code initializes an application module. An application module contains one or more
related view objects, connects to the database, and provides a context for database
transactions.
2. A view object provides a runtime reference to a query. You can specify a query using
11-208
wizards at design time, or by hard-coding a literal SQL string. At runtime, you can create
and instantiate view objects, and you can find and reuse ones that are already
instantiated by calling methods on the application module.
3. When a view object executes its query, it operates on data from one or more tables
represented by one or more entity objects. Oracle business components implements a
pull model to refresh view objects: a view object does not execute its query until an
iterator requests data.
4. After executing a query, you can call view object methods to navigate through the result
set. If you don't want to work with the entire result set, you can set a range and work with
a specified number of rows. Each row of the result set is represented by a Row object;
each attribute of a Row object represents a column value in that row. Clients manipulate
data by getting and setting row attribute values within the transaction context provided by
the application module. Changes to data through views are automatically validated by
the encapsulated business logic in one or more entity objects on which each view object
is based. This encapsulation separates business logic from the user interface.
5. Commit the changes (if any) to the database to make the updated data available to other
application modules and other users.
Using forward only mode
You can use forward only mode in a view object to prevent data from entering the view cache.
Using forward only mode can save memory resources and time, because only one view row is
in memory at a time. Forward only mode is useful when you are fetching data and reading it
once, such as formatting data for a web page, or for batch operations that proceed linearly.
Note that if the view object is based on one or more entity objects, the data does pass to the
entity cache in the normal manner, but no rows are added to the view cache.
Dynamic view object performance can be optimized
For dynamic view objects, created using either the createViewObjectFromQueryStmt or

createViewObjectFromQueryStmtClauses
method, the first time you fetch data, the query might be executed twice. The first query collects
data type and precision information. This information is used in subsequent queries to return
data in the proper Java types and make the query more efficient (it can get data in smaller or
predefined sizes rather than the maximum size). For "expensive" queries, if executing two
queries the first time causes a performance problem, a possible workaround could be to first
11-209
create a view object with "dummy" Where clause that returns no rows, call
getAttributeCount on the view object to facilitate the metadata query and attribute
definition, and then call setQuery with the exact query required for fetching data. This way,
you can avoid executing an expensive query twice; instead, the first query becomes a trivial
query on the same dataset.
Related topics
11-210
What Is a View Link?
A view link defines a relationship between view objects. The relationship can be one-to-one,
one-to-many, many-to-one, or many-to-many. The View Link Wizard and Editor lets you specify
source and destination view objects, and links them using attributes selected from the view
objects. You need view links to traverse view objects, such as to obtain or modify data, and to
add master-detail relationships to a data model in the application module.
Examples of view links
An example of a one-to-many relationship could be a DepartmentsOverBudgetView view object

linked to a ContractorView view object in a master-detail relationship. With this view link, you
could efficiently look at information about contractors in overbudget departments.
An example of a more complex one-to-many relationship could be a CustomerView view object

linked to an OrderView view object in a master-detail relationship, and the OrderView view
object linked to an ItemView view object in a master-detail relationship. So a user could quickly
look at the items in a particular customer's order in one form.
View links can be created based on associations
View links can be created based on associations, but an association is not needed to use a
view link. A view link is similar to an association, but is more flexible. It allows more
relationships than equality between attributes and supports automatic master-detail
synchronization.
Note that if a view link is based on an existing association, and the association has been
defined as a composition, then when creating a detail view row, the master view row must exist
and have non-null key values. If the association has not been defined as a composition, no
such restriction applies.
Tools help you create view links
You can define and edit view links in the View Link Wizard and Editor.
You can also generate default view links, based on existing associations, by using the Entity
Object Wizard and Editor, Business Components Project Wizard, or Package Wizard.
11-211
View link navigation and relationships are customizable
View links are navigable in one direction (master to detail, not detail to master) or both
directions. If the default relationship based on attribute equality does not provide adequate
functionality, you are able to create complex SQL-based relationships by specifying a Where
clause in the Association SQL page of the View Link Wizard or Editor.
If a view object is specified as a detail view in a link, the view object further restricts the data to
the detail information (by adding the Where clause specified in the Association SQL page to the
SQL statement that defines the view object). In other words, a view link selects a correlated
view of underlying data based on bind values supplied by the current row of the master view.
Detail row sets are automatically coordinated with the master row
set
When two view objects, related through a master-detail view link, are in an application module,
the default (or first) iterator for the master view object automatically changes the detail rowset
when the master row changes. When the detail view object is created, the business component
framework registers it as an event listener for the master's iterator. So, when the iterator moves
to another row in the master iterator, the detail view object receives the event and automatically
refers to the appropriate detail rowset.
View links can be included in an application module's data model
A view link can be included in one or more applications modules, or not. You can reuse view
links in multiple application modules.
Accessor methods let you traverse view links
You can use the View Link Wizard and Editor to create optional accessor methods in the
source view object (the ViewRow class) and possibly the underlying source entity object (see
About Exposing View Links to Entity Objects for more information). You can use these
accessor methods to traverse the view link to programmatically access a desired result set in
the view object. The accessors let you gather data from other view objects, returning a rowset
from the other view object. They also let you get and set attributes at the destination end of the
view link. You can access them programmatically even if the view link is not part of an
application module.
View links can be dynamically created
11-212
You can create view links dynamically at runtime using the createViewLink methods of the
ApplicationModule interface.
Related topics
11-213
An application module is a class that represents a business application task. Specifically, it
encapsulates the data model associated with a task, plus the custom code to implement the
task. An example of an application task might be updating customer information, creating a new
order, or processing salary increases.
The business logic tier has one or more application modules that the other tiers — clients and
the database — interact with.
An application module represents a reusable data model
An application module represents the data model that your client uses. To create the data
model, the application module contains named instances of view objects and view links. (This
containership is similar to how a Java frame can contain instances of components, such as a
list box and a grid control.)
Together, the view objects and view links represent the various views of data required by the
application task. For example, to accomplish the Create New Order task may require,
● A view of minimal customer details (Name, Id, Phone)

● A view of available items that can be ordered (perhaps to support a browsing
page/screen)
● A view of order header information (in which a new order will be created)
● A view-linked view of order detail line items (in which new order line items will be
created)
Different forms or pages in a client can share the view object instances and refer to them by
name.
All application module operations are part of the same transaction
An application module provides a transaction context for the view object instances it contains
and use the same set of changes. The transaction keeps track of all changes that affect data in
the database. This is an important consideration when deciding what application modules your
application needs. For example, you could combine creating an order and adding a customer
into the same transaction. View objects are the vehicles upon which the entity objects are
changed.
11-214
All changes made during one transaction are committed or rolled back together.
As a general guideline, if you have one form per task, you could structure your application so
there is one application module per form.
An application module contains code to implement a task
Code specific to a given application task can be written as custom methods on your application
module class to encapsulate processing logic and to simplify the job of client pages/frames for
using the functionality.
For example, a CreateNewOrderModule application module could have a method called

"newOrderForCustomer()" which encapsulated the details of looking up a customer.
An application module represents a data model for a task that is accomplished within one
transaction.
Application module logic is specific to a task
Each component in your business logic tier can have Java code associated with it, to perform a
particular role. This architecture also makes business components easily reusable. In general,
you can determine where to place functionality based on these guidelines:
● An entity object contains business logic pertaining to a single business entity. All view
objects based on the entity object share the logic. At the entity level, calculations are
performed in Java code.
● A view object contains logic pertaining to a database query, which is defined by a SQL
SELECT statement. This can include SQL-calculated expressions, joins, unions, nested
subselects, and so on. You can also add code to the Java source, for example, you can
propagate events to the UI from the ViewObjectImpl class, or create a method that calls
an entity object method that you want to expose for this view by adding code to the
ViewRow class.
● An application module's source files can contain logic specific to the task it performs —
logic not appropriate to put in an entity object or view object, which multiple application
modules performing different tasks can use. If two applications use the same view, you
would put logic specific to one of the applications in its application module source files
instead of in the entity or view object source files.
11-215
Application modules can be hierarchical
In the same way that an application module can use view objects, an application module can
use another application module's data model and code by including nested application
modules. One application module can contain a variety of simpler application modules that
together provide compound functionality. In other words, this feature lets you create new
"compound" tasks from application module building blocks. For example, lets say you have
separate forms that are each in their own transaction. Later, you decide that you want a form
that does many of these tasks at once, in one transaction. So you nest application modules to
perform these subtasks in one form, perhaps as separate tabs or dialogs launched from the
parent form.
The top-level application module provides a transaction context for the view object instances it
contains, including those in all nested application modules. A top-level application module has
one connection to the datasource. You define it the same way you define any application
module.
Application modules should be nested when they are a reusable part of a specific application
task. You should have one form per application module, which can be embedded in other
application modules and applications. Nesting an application module implies that it needs to be
part of the top-level application module's transaction. For example, an OnlineOrders application
module could contain an AddNewCustomer application module.
An application module exports methods
An application module provides methods that implement the application module behavior and
are accessible to clients. There are predefined framework methods that clients can use to work
with the application module instance. For example, application modules let you obtain view
object instances and execute queries, manipulate the transaction, and so on.
In addition, you can add custom methods and selectively export those public methods you want
clients to use. For example, an application module that processes employee salary increases
might export methods for finding employee salary information and adding the raise.
You can deploy application modules in multiple configurations with

no code changes
You can deploy the same application module in multiple configurations, perhaps using EJB or a
web module, without changing its code. Also, the same application module can be used in a
11-216
physical one-tier, two-tier, or three-tier application (tiers on one, two, or three computers)
without code changes.
Application modules encapsulate client data
An application module lets you gather data tailored to a client interface (such as a form), so
data can be retrieved in one network roundtrip instead of multiple trips. You can also perform
calculations in the business logic tier through remotely accessible methods, reducing client
overhead. For bulk operations on application data, you can perform the operation in the
business logic tier without downloading all of the data to the client; changes to the data the
client is currently viewing are automatically synchronized.
Tools help you create application modules
To create and edit an application module at design time, use the Application Module Wizard
and Editor. You can also create a default application module by using the Business
Components Project Wizard and Package Wizard.
Clients create instances of application modules
At runtime, a client creates an instance of an application module for its use. They are not
shared between clients. The client can create an instance of an application module you created
at design time, or an instance of the base application module class, called a generic application
module. You can use a generic application module when you want a container for dynamically
created view objects, view links, and application modules. For example, if you have a complex
application with a client menu containing many tasks, you might decide to create a generic
application module that instantiates nested application modules as needed, based on the menu
choice, within the same transaction.
Application modules can be pooled
A client can use application module instances in a pool. For example, in the case of a web
application, you may have 1,000 users but you know that only 100 will be using a certain
application module at one time. So you keep 100 application module instances in a pool. When
the web client needs an application module instance, it takes a free one from the pool and
releases it to the pool when it is finished processing that request. Because the instance is
precreated, end users are saved the time it takes to instantiate the application module when
they want to perform a task. You can use this feature to improve scalability and performance.
Typically, web-based JSP clients use pools. See About Application Module Pooling for more
information.
11-217
Related topics
About Structuring Business Components Projects and Packages
11-218
How Clients and the Business Logic Tier Interact
When a client first accesses the business logic tier, it gets an instance of an application module
that contains all of the view objects and nested application modules it needs. A client gets an
application module instance by using the factory pattern.
After a client has an application module instance, it can access and manipulate data by calling
methods on application modules, view objects, and view rows.
The business components framework provides a large number of methods on the framework
interfaces ApplicationModule, ViewObject, and Row (which is implemented by view rows)
in the oracle.jbo package. For information on using these methods, see Using the API to
Customize and Use View Objects, View Links, and Application Modules.
You can also create custom methods in your application module, view object, and view row
classes. The following topics describe concepts about how clients use custom business logic
tier methods:
● About Custom Client Methods
● About Client Interfaces
Related Topic
Ways to Create a Client for Business Components
11-219
About Custom Client Methods
JDeveloper allows client-side programs to access, use, and change the business logic in the
business logic tier. JDeveloper does this by allowing you to create methods on your business
logic tier business components and export then to clients. The methods can then be called in
client programs to access business logic tier business logic. This technique of exporting
business logic tier business component methods allows code which is logically part of the
business logic tier to remain physically in the business logic tier in remote deployments. Not
only does it provide access to the business logic tier, it can potentially eliminate unnecessary
network roundtrips and data exchange between the business logic tier and the client.
What Business Components Can be Accessed?
To access business logic, you can export methods written on application modules, view
objects, and view rows. By allowing you to create and export methods on these business
components, you can choose to access the business logic at the appropriate level.
Working with application module methods allows the client program to encapsulate task-level
custom code in a place that allows data-intensive operations to be done completely in the
business logic tier without burdening the client.
Working with view object methods allows the client program to access the entire row collection
for cross-row calculations and operations.
Working with view row methods allows the client program to operate on individual rows of data.
There are three types of custom view row methods you might want to create:
● Accessor methods. The oracle.jbo.Row interface (which view rows implement)

contains the methods getAttribute() and setAttribute(), but these methods are
not typesafe. You can automatically generate custom typesafe accessors when you
generate a custom view row class.
● Delegators to entity methods. By design, clients cannot directly access entity objects. If
you want to expose an entity method to the client tier, you should create a delegator
method in a view row.
● Entity-independent calculations. This is useful if the calculation uses attributes derived
from multiple entity objects or from no entity objects.
11-220
Ways To Create a Client for Business Components
Once you create your business logic tier, you must create a client to provide the user interface
and control flow of your application. You will, most likely, create your view objects and
application modules in conjunction with your client: the design of the client will dictate what
tasks and queries you need, what your data model should look like, and what methods you
need to export.
JDeveloper provides three powerful client architectures to help you create common kinds of
client applications for business components:
● JClient, a swing-based architecture for creating Java clients with graphical user
interfaces
● Business components JSP applications, an architecture for creating thin HTML clients
● Oracle XSQL Pages, which enables an XML/XSLT-based approach to building
applications
In addition, you can create your own business components client by hand-coding Java.
11-221
Creating a Hand-Coded Client for Business
Components
JDeveloper provides several powerful client architectures to help you create common kinds of
client applications for business components. However, for special purposes (such as a batch
application), you may want to create your own client by hand. There are several steps you must
implement programmatically in any hand-coded client.
To write a hand-coded client:
1. Add the following libraries to your project:
● JBO Runtime
● JBO Oracle Domains
● Oracle JDBC
● Connection Manager
● A library containing your client-side business components
1. Import oracle.jbo.*, oracle.jbo.client.*, and oracle.jbo.domain.*.

2. If you exported any methods or created any domains, import
<yourBCpackage>.common.*.
3. Load an instance of your application module.
4. If your application module uses container-managed transactions, create and use a client-
demarcated transaction.
5. Find or dynamically create the view objects that contain the data and methods your client
needs.
6. Call methods on the view objects and application module to navigate, retrieve, and
manipulate data.
11-222
Ways to Create and Find View Objects in Code
Once you have instantiated an application module, you can complete the following tasks to find
or create view objects. Your client must have access to a view object before it can view or
update data.
Task Description Methods

Finding a
View Find an instance of a view
object that was added to
Object in ApplicationModule.findViewObject()
an application module's
the Data
data model at design time.
Model
Finding a Create an instance of a
View view object that was
Object not created at design time but
not added to the ApplicationModule.createViewObject()
in the
application module's data
Data model, and add it to the
Model data model.
Creating a
View Create a SQL-only view
Object object from a query ApplicationModule.createViewObjectFromQueryStmt()
from a statement, and add it to
Query the data model.
Statement
Creating a
Create a view object from
View SELECT, FROM, WHERE,
Object and ORDER BY clauses, ApplicationModule.createViewObjectFromQueryClauses()
from and add it to the data
Query model. The view object will
Clauses not be SQL-only.
11-223
Finding a View Object in the Data Model
If you added a view object to the data model either previously in code or in design time (using
the Data Model page of the Application Module Wizard), you can retrieve it in either the
business tier or the client by calling findViewObject() on the application module. Pass the
name of the view object usage (in the data model) to this method.
ViewObject mgrVO = am.findViewObject("Managers");
Related topics

Finding a View Object Not in the Data Model
Creating a View Object from a Query Statement
Creating a View Object from Query Clauses
11-224
If you created a view object at design time but did not add it to the data model of your
application module, you can still access it at runtime by calling createViewObject() on the
application module. The view object will be added dynamically to the application module's data
model. createViewObject() takes two String arguments. The first becomes the name of
the view usage in the data model. The second is the possibly package-qualified name of the
view object (the name that you specified in the View Object Wizard). You can call this method
from the client or the business logic tier.
String viewUsageName="EmployeesView";
String viewObjectName="demo.EmployeesView";
ViewObject empvo=am.createViewObject(viewUsageName, viewObjectName);
Related topics

11-225
You can dynamically create a view object from a SQL query statement by calling
createViewObjectFromQueryStmt() on an application module. You can call this method
from either the client or the business logic tier. This method both returns a view object and adds
it to the application module's data model. The view object will be SQL-only, and can not be
used to alter data. If you need to dynamically create a view object based on entity objects, see
Creating a View Object from Query Clauses.
createViewObjectFromQueryStatement() takes two String arguments. The first

becomes the name of the view usage in the data model. The second is the SQL query with no
semicolon.
String viewUsageName="TempVO";
String query="SELECT Employees.EMAIL FROM EMPLOYEES Employees";
ViewObject mgrvo=am.createViewObjectFromQueryStmt(viewUsageName, query);
Note: If you create a view object using this method, the query may be executed twice the first
time you fetch data. The first query collects data type and precision information, which is used
in subsequent queries to map data to the proper Java types and make the query more efficient
(by specifying precision where it is below the maximum). For expensive queries, where
executing twice causes a performance problem, you may want to create the view object with a
"dummy" where clause that returns no rows, call getAttributeCount() on the view object
to facilitate the metadata query and attribute definition, and then call setQuery() to change
the query to the one you want. This way, the initial query is a trivial, and far less expensive,
query on the same dataset.
Related topics

11-226
You can dynamically create a view object based on an existing entity object by calling
createViewObjectFromQueryClauses() on an application module. You can call this method from either the client or
the business logic tier. This method both returns a view object and adds it to the application module's data model.
The view object must be based on exactly one entity object. If you need to dynamically create a SQL-only view
object, see Creating a View Object from a Query Statement. The method takes six String arguments:
● The String that should become the name of the view usage in the data model
● The possibly package-qualified name of the entity object (the name that you specified in the Entity Object
Wizard) that the view object will use to alter data
● The SELECT clause of the SQL statement. The clause must contain the same number of columns as the
entity object has attributes. The columns in the clause are mapped to the entity attributes according to the
order in which they appear in the entity object's XML file: The first column in the clause will map to the first
entity attribute, the second column will map to the second, and so on
● The FROM clause of the SQL statement. The clause must contain the same tables, in the same order, as the
entity object
● The WHERE clause of the SQL statement
● The ORDER BY clause of the SQL statement
String viewUsageName="EmployeesView";
String entityObjectName="demo.Employees";
String selectClause="E.EMPLOYEE_ID, E.LAST_NAME, E.HIRE_DATE, E.SALARY, E.COMMISSION_PCT,
E.MANAGER_ID, E.DEPARTMENT_ID";
String fromClause="EMPLOYEES E";
String whereClause=null;
String orderByClause=null;
ViewObject mgrvo=am.createViewObjectFromQueryClauses(viewUsageName, entityObjectName,
fromClause, whereClause, orderByClause);
Note: If you create a view object using this method, the query may be executed twice the first time you fetch data.
The first query collects data type and precision information, which is used in subsequent queries to map data to the
proper Java types and make the query more efficient (by specifying precision where it is below the maximum). For
expensive queries, where executing twice causes a performance problem, you may want to create the view object
with a "dummy" where clause that returns no rows, call getAttributeCount() on the view object to facilitate the
metadata query and attribute definition, and then call setQuery() to change the query to the one you want. This
way, the initial query is a trivial, and far less expensive, query on the same dataset.
Related topics

11-227
11-228
Calling Methods from Clients
After your client has loaded an application module instance, found a view object instance, or
navigated to a view row, it can call methods on the business components it has found. There
are two types of methods a client can invoke: Framework methods (those provided by the
default framework interfaces) and custom methods (those you create).
For information on when you should put custom methods in the application module, view
object, or view row, see About Custom Client Methods.
For commonly used framework methods and how to invoke them, see Using the API to
Customize and Use View Objects, View Links, and Application Modules.
To invoke custom methods on application modules, view objects, or view rows:
1. Make sure you have exported the methods. This generates a custom interface. For
example, if you export a method on mypackage.MyAppModuleImpl, it will create an
interface called mypackage.common.MyAppModule.
2. When you call the method from the client, cast the business component to the custom
interface:
((MyViewObjectInterface) foundVO).myCustomMethod();
11-229
Ways to Represent Oracle Objects as Business
Components
The Business Components for Java framework maps database types to Java types. This
mapping is done automatically by the framework for all Oracle database datatypes following a
predefined type map. Complex objects, like Oracle Objects, are mapped to domain objects or
entity objects, depending on how the object is created and used in the database.
The following topics illustrate how Oracle Objects are represented in Business Components for
Java:
● Representing Column Objects

● Representing Object Tables
● Representing VARRAYs
● Representing Nested Tables
Related Topics
About Oracle Object Types and Business Components

Ways to Represent Oracle Objects as Business Components
Representing Column Objects
Representing Object Tables
Representing VARRAYs
Representing Nested Tables
11-230
Creating a Domain for an Oracle Object Type
There are three ways to create a domain for an Oracle Object Type:
● By default - Domains are generated automatically for any Oracle Objects that exists in
the database when you start a new project using the Business Component Project
Wizard.
● By forward generating domains - Create a domain using the Domain Wizard and forward
generate the obect in the database.
● By creating a domain for an new Oracle Object Type - If an Oracle Object Type was
created or added to the database after you started your business components project,
you can create a domain for it without starting a new project. The rest of this topic details
this scenario.
When you create a domain from an Oracle Object Type, the Domain Wizard uses the object to
create an object.java file in the package to represent the domain. The class encapsulates the
object value and represents the Java class to which the Oracle Object is mapped. Unlike
domains created from built-in SQL datatypes, the object.java file created for Oracle Objects is
a mutable Java class. The object.java file contains getters and setters for all of the individual
attributes. For example, if you define a NAME object with FirstName and LastName attributes,
the Domain Wizard will create a Name.java file that contains the methods getFirstName,
setFirstName, getLastName, and setLastName. You can then use Name as an attribute
datatype in your programs to represent objects of type NAME.
The object.java file created by JDeveloper includes getters and setters for the individual
attributes. If you want to supply validation, you must do so in the attribute getters and setters.
Later, when the object is used in your application, validation will be performed on the object's
attributes whenever one is created or encountered. This allows the object to be referenced or
reused in multiple places, and passed between tiers and applications, without the need for
reconstruction or revalidation. (Note that you cannot validate the constructor through the
validate() method; this method is not generated for domains created from Oracle Objects.)
The example below assume that you aleady have an Oracle Object Type in the database.
An Example
This example uses the customers table. The customers table contains an Oracle Object
cust_address_typ for the datatype of the customer cust_address column. The object
11-231
type is defined as follows:
CREATE TYPE cust_address_typ AS OBJECT

( street_address VARCHAR2(40)
, postal_code VARCHAR2(10)
, city VARCHAR2(30)
, state_province VARCHAR2(10)
, country_id CHAR(2)
);
/
To create a domain from the Oracle Object Type:
1. Right-click the Package and choose Create Domain to open the Domain Wizard.
2. In the Name page of the Domain Wizard, enter cust_address_domain.
3. Select the Domain for an Oracle Object Type checkbox to expose the list of object
types available in the database. Then select cust_address_typ from the Available
Types list and click Next.
4. In the Settings page, use the Attribute dropdown list to edit the properties of existing
cust_address_typ attributes. The domain attributes are automatically mapped to the
Java Business Object datatypes (street_address to a String, and so on). You can
also use the Settings page to remove attributes or create new attributes. For this
example do not make any changes.
5. Click Finish. The wizard creates a reusable domain.
The cust_address_domain.java class contains the getters and setters for each of the
domain attributes: street_address, city, state_province, and so on. Once the domain
has been created, it can be reused as the datatype of an entity attribute.
You can add your own validation to the domain by editing the attribute getter and setter
methods. Here you will validate that the country_id is US.
To edit the attribute setter method:
1. In the Navigation pane, expand cust_address_domain.

2. Double-click on cust_address_domain.java to open it in the Source Editor.
3. In the Structure Pane, double click setCountryId(Sting) to jump to that line in the
Source Editor.
11-232
4. Modify the source code so that it resembles the following:
public void setCountryId(String value) {

setAttribute(4, value);
\\ do I use an "if" statment or a try-catch block? help!
}
Once the domain is created you can assign it as an attribute of an entity object.
To create an entity object containing the Oracle Object Type:
Next, create the entity object for the table that contains the cust_address_domain object.
Question: Do we need to show how to create an entity object and assisgn the domain as an
attribute type?
Related Topics

Representing a VARRAY that Contains Oracle Object Types
Replacing an Oracle Object Type with a REF to a Table of that Type
11-233
Representing a VARRAY
The business component framework maps database types to Java types based on a
predefined type map. VARRAYs are mapped as a domain, to oracle.jbo.domain.Array.
Domains for VARRAYs are automatically created when you are performing reverse generation.
For sample code, see ORACLE_HOME\BC4J\samples\Varrays.
In the following example, a phone_list_typ is defined using the CREATE TYPE statement. A
customers table is then created with a column phone_numbers, that contains the new type,
phone_list_typ. When the customers table is reverse engineered as a business
component, a domain is created for phone_list_typ. A domain is not required for
phone_numbers.
CREATE TYPE phone_list_typ AS VARRAY(5) OF VARCHAR2(25);
CREATE TABLE customers

( customer_id NUMBER(6)
, cust_first_name VARCHAR2(20) CONSTRAINT cust_fname_nn NOT NULL
, cust_last_name VARCHAR2(20) CONSTRAINT cust_lname_nn NOT NULL
, cust_address cust_address_typ
, phone_numbers phone_list_typ
, nls_language VARCHAR2(3)
, nls_territory VARCHAR2(30)
, credit_limit NUMBER(9,2)
, cust_email VARCHAR2(30)
, account_mgr_id NUMBER(6)
, cust_geo_location MDSYS.SDO_GEOMETRY
, CONSTRAINT customer_credit_limit_max
CHECK (credit_limit <= 5000)
, CONSTRAINT customer_id_min
CHECK (customer_id > 0)
) ;
VARRAYs That Contain Oracle Object Types
If you have a VARRAY that contains Oracle Object Types, the domain for the Oracle Object
Type is created by the business components framework when you reverse engineer business
components. The VARRAY is represented by oracle.jbo.domain.Array. A separate
domain is created for the Oracle Object Type.
11-234
Related Topics

11-235
Replacing a Column Object with a REF to a Table
The following example illustrates an alternative to using an Oracle Object datatype as a column
in a table. In a table definition, you can replace a line that identifies a column as an Oracle
Object datatype with a REF to a table that is of the Oracle Object datatype. That is, assume
you have a table definition with a column that is an Oracle Object Type. Create a second table
with the same name and type as the Oracle Object. You can then redefine the column in the
original table as a REF to the second table. This powerful technique gives you certain
advantages:
● Each table can be translated to a separate entity object.
● The REF between the tables is translated to an association between the entity objects,
one of which represents the Oracle Object Type.
● You can create separate entity-level validations on the entity object representing the
table and the entity object representing the Oracle Object type.
● You can make the entity object representing the Oracle Object type read-only and allow
the entity object representing the table to be updateable. The REF (or association) will
allow you to essentially have a read-only attribute in an entity object that is otherwise
updateable.
● After you create the entity objects for the table and the Oracle Object type, use the
Association Wizard to set the Composition flag. The parent entity object will not be able
to be deleted before its children are deleted.
The following example demonstrates the SQL code needed to make use of this technique.
[Note that this example is a 1:1 example - one person pointing to one address. A more
appropriate example would be a 1:M. Line items on an Order, for example.] The example
begins with the definition of the address_objtyp as an Oracle Object type. It then creates a
table named address_objtab of type address_objtyp. The definition of the table
people_reltab2 has already been rewritten to replace the line:
address address_objtyp
with the REF statement:
11-236
address_ref REF address_objtyp
SCOPE IS address_objtab ) -- REF specified
The SQL code concludes with an example of inserting data into the tables.
CREATE TYPE address_objtyp AS OBJECT (

street VARCHAR2(200),
city VARCHAR2(200),
state CHAR(2),
zipcode VARCHAR2(20))
/
CREATE TABLE address_objtab OF address_objtyp ;

/
CREATE TABLE people_reltab2 (id NUMBER(4)

CONSTRAINT pk_people_reltab2 PRIMARY KEY,
name VARCHAR(15),
Phone Number(6),
address_ref REF address_objtyp
SCOPE IS address_objtab ) -- REF specified
/
insert into address_objtab values(address_objtyp

('St1','FosterCity', 'CA', '94491'))
insert into address_objtab values
(address_objtyp('St2','Redwood', 'CA', '94331'))
insert into people_reltab2 values( 1, 'Sanjay',911,
(SELECT REF(p) FROM address_objtab p WHERE street = 'St1'));
insert into people_reltab2 values( 2, 'KING',1241,
(SELECT REF(p) FROM address_objtab p WHERE street = 'St2'));
Note: If the attribute is of Array type, you must fill in an element type for the array for reverse
generation only.
Related Topics

Representing an Oracle Object Type with a User-defined Domain
Representing a VARRAY that Contains Oracle Object Types
11-237
11-238
Running Business Components Samples
You can find business components samples in ORACLE_HOME\BC4J\samples. Many of the
samples are new in this release. In addition, the JDeveloper version 3.2 tutorial samples have
been updated for use with this version of JDeveloper, although the tutorials have been replaced
by new tutorials.
The instructions on running the samples are grouped in these main sections:
● Running samples that use the OnlineOrders tables — The online orders tables are used
by the version 3.2 tutorial samples, which illustrate a variety of programming techniques
on both the business logic tier and the client tier.
● Running samples that use the HR tables — The new caching, pooling, programmatic
view object, row filter, and stored procedure samples use the human resources tables.
● Running the Varrays sample — The VARRAYs sample uses the order entry tables.
● Running the StreamingLobs sample — The streaming LOBs sample uses its own table.
Running samples that use the OnlineOrders tables
See OnlineOrdersForClients\sampleREADME.html for instructions on installing the

OnlineOrders tables and setting up the database connection.
Running the OnlineOrdersForClients samples
The OnlineOrdersForClients workspace contains a basic business logic tier and several clients
that use it. See OnlineOrdersForClients\sampleREADME.html for instructions on
running the samples.
Running the AdvancedOnlineOrders sample
The AdvancedOnlineOrders workspace contains an advanced business logic tier and a simple
JSP client that uses it.
First, you run the business logic tier in the Tester (which automatically builds it). Then, you'll run
its JSP client in a browser.
To run the business logic tier in the Tester:
11-239
1. Open AdvancedOnlineOrders.jws.
2. In the Navigator, expand OnlineOrders.jpr and then the OnlineOrders package.
3. Right-click OnlineOrdersModule and choose Test.
4. In the Connect dialog, make sure the Connection Name is MyJdbcConn and click
Connect.
5. Double-click items in the right pane to display them in the left pane, where you can
perform operations on the data.
6. When you are finished with the Tester, close it.
To run the JSP client:
1. In the Navigator, expand JSPClient.jpr.

2. Right-click main.html and choose Run.
The client appears in your default browser.
3. Click items in the right pane to display them in the left pane, where you can perform
operations on the data.
4. When you are finished with the client, close the browser.
Running samples that use the HR tables
The following samples use the HR schema, which is provided with Oracle9i. See Creating and
Populating the Database Tables for information on how to install the tables for use with the
samples. Next, see Creating a Connection for information on setting up a connection for the
samples; however, use a connection name of hr, and a username and password of hr. After
setting up the connection, choose File | Save All.
Running the Caching sample
This sample illustrates important concepts about how the Business Components for Java
caching system works, as described in How Does the Business Logic Tier Cache Data?
Follow these steps to run the sample:
1. Open Samples.jws, if not already open.

2. In the Navigator, right-click Caching.jpr and choose Build Project.
11-240
3. Right-click TestClient.java and choose Run.
See the Messages window for messages showing how the program runs. The indenting
indicates the tiers in the application architecture. You can examine the code to
understand how the data flows through the caches.
Running the Pooling sample
This sample illustrates pooling features. See About Application Module Pooling and About
Connection Pooling for more information.

2. In the Navigator, right-click Pooling.jpr and choose Build Project.
3. Right-click TestPoolServlet.java and choose Run.
Pooling statistics appear in your default browser. If you click Reload in your browser, the
number of checkins value increments.
Running the ProgrammaticVO sample
This sample illustrates the "programmatic view object" feature. The sample shows how you can
create a view object that uses data you defined directly in code. See Creating a View Object
Based on a Static Set of Values for more information.

2. In the Navigator, right-click ProgrammaticVO.jpr and choose Build Project.
3. Right-click ProgrammaticVOModule and choose Test.
4. In the Connect dialog, make sure the Connection Name is hr and click Connect.
5. In the Tester, double-click CountryCodesView and use the arrow buttons to scroll
through the data that was defined in the code.
6. Close the Tester when you're finished.
11-241
Running the RowFilter sample
This sample illustrates the row filter feature, sometimes called the non-equi join feature. See
Implementing Row Set Filters for more information.

2. Run SalaryBands.sql against the database.
It is in the RowFilter project. For example, if you have SQL*Plus installed, you can simply
right-click SalaryBands.sql in the Navigator and choose SQL*Plus | hr.
3. In the Navigator, right-click RowFilter.jpr and choose Build Project.
See the Messages window for messages showing how the program runs.
Running the StoredProc sample
This sample illustrates how to use stored procedures from the business logic tier. See About
Using Stored Procedures and Calling Stored Procedures for more information.

2. Run stproc.sql against the database.
It is in the StoredProc project. For example, if you have SQL*Plus installed, you can
simply right-click stproc.sql in the Navigator and choose SQL*Plus | hr.
3. In the Navigator, right-click StoredProc.jpr and choose Build Project.
4. Right-click StprocModule and choose Test.
5. In the Connect dialog, make sure the Connection Name is hr and click Connect.
6. In the Tester, try inserts, updates, and deletes.
7. Close the Tester when you're finished.
Running the Varrays sample
This sample uses the OrderEntry schema, which is provided with Oracle9i. See Creating and
11-242
Populating the Database Tables for information on how to install the tables for use with this
sample. Next, see Creating a Connection for information on setting up a connection for the
samples; however, use a connection name of oe8, and a username and password of oe8. After
setting up the connection, choose File | Save All.
The sample illustrates how to use VARRAYs in your business components code. See
Representing a VARRAY for more information on VARRAYs and business components.

2. In the Navigator, right-click Varrays.jpr and choose Build Project.
You can examine the code to understand how to use VARRAYs this way.
Running the StreamingLobs sample
To efficiently use LOBs in the business logic tier, it is best to implement Java input and output
streams, as illustrated in this sample. See Using LOBs through Java Streams for more
information.
To run the sample, you must first create a table. These steps use the same connection you
define when running the OnlineOrders samples:

2. Run create_person.sql against the database.
It is in the StreamingLobs project. For example, if you have SQL*Plus installed, you can
simply right-click create_person.sql in the Navigator and choose SQL*Plus |
MyJdbcConn.
3. In the Navigator, right-click StreamingLobs.jpr and choose Build Project.
You can examine the code to understand how to use LOBs this way.
11-243
Introducing Business Components for Java
Business Components for Java is JDeveloper's programming framework for building multi-tier database
applications from reusable business components. Such applications typically consist of:
● A client-side user interface written in Java and/or HTML
● One or more business logic tier components that provide business logic and views of business objects
● Tables on the database server that store the underlying data
This figure illustrates an example of a multi-tier configuration.
The following figure compares client/server and multi-tier applications. A typical client/server application
stores business rules, views, and custom code in client-side forms. Clients can quickly become thick with
code and hard to maintain. For example, if a rule changes (as when the minimum salary is raised),
developers must update every form that uses the rule.
11-244
In contrast, a multi-tier application built with the Business Components for Java framework deploys views,
business rules, and custom code in components that clients can share. With the Business Components for
Java framework, such components are easy to build and maintain, easy to use and reuse, and easy to
customize. Components do not need modification to be deployed to any supported platform. This approach
provides many features and benefits, including:
Feature Description
Business logic, including validation, resides and executes in the business logic tier, enabling truly
Encapsulated business logic
thin clients, easy customization, and reuse.
Views of data are SQL-based and completely separate from the underlying entities, enabling
Flexible views of data
flexible presentation schemes.
Business Components for Java supports thin clients--simple windows to business logic and views
Thin clients
of data processed by the business logic tier.
11-245
Flexible deployment Deploy locally or on standard server platforms as CORBA server objects and EJB Session Beans.
Business Components for Java's component-based framework handles many repetitive coding
Database interaction
tasks, such as master-detail coordination and locking.
Business Components for Java manages changes in its cache and handles posting of changes to
Transaction management
the database.
Business Components for Java comprise a framework for building and customizing domain-specific
components. As a developer, you derive objects from the classes and interfaces provided by the framework
and add custom code to implement features specific to your application. The following business components
are used to support this process:
Object Description
entity object An entity object encapsulates business logic for a database table, view or synonym. Clients access an
entity object's data through one or more view objects. A given entity object can be used by any number of
view objects. Relationships between entity objects are expressed using associations.
view object View objects use SQL queries to specify filtered subsets of attributes from entity objects. Clients manipulate
data by navigating through the result set, getting and setting attribute values. Relationships between view
objects are expressed using view links.
application module An application module is a logical container for instances of view objects, view links, and transactions
specified by other application modules.
Each business component you create is represented by an XML file and one or more Java files. The XML file
stores metadata (the descriptive information about features and settings of an application you declare using
wizards at design time), while the Java file stores the object's code (which implements application-specific
behavior). Each object is organized into a package using the directory-based semantics of packages in Java.
For example, the files DeptView.xml and DeptViewImpl.java are in the package d2ePackage because
they reside in the directory d2ePackage:
In the Business Components for Java framework, you select a package, and its code is correctly located for
you.
The Java and XML files that represent business components use a similar syntax to identify the package they
reside in, as shown below.
Java XML
11-246
package d2ePackage;
... <ViewObject
public class DeptViewImpl extends Name="DeptView"
oracle.jbo.server.ViewObjectImpl { ...
... ComponentClass="d2ePackage.DeptViewImpl">
}
11-247
JDeveloper provides integrated support for the Business Components for Java framework.
Using design tools such as wizards and property editors you define the characteristics of
objects: their attributes, relationships, and business rules. Then JDeveloper generates
executable Java code and XML to implement the behavior you define for the components.
In theory, you could write this code yourself. In practice, though, it's better to use the wizards to
be sure that all necessary code is generated and all dependencies are addressed. Then you
can edit the generated code to meet the specific needs of your applications. JDeveloper
enforces no particular methodology, but the development process typically involves answering
questions like these:
● What are the entities and business objects? You can use entity objects on their own
(for example, a customer), or you can combine several entity objects (for example, a
purchase order consisting of a header, line items, shipments, and distributions).
● How are the entities related? For example, you could define a one-to-many association
between departments and employees.
● What are the validation rules? For example, a business rule might specify a minimum
salary for employees with more than five years of service. You can apply rules to
attributes, entities, and business objects.
● What data will be presented and manipulated? By creating views, you define SQL
queries to select and filter data from the entities to minimize network traffic and client-
side processing requirements.
Design time
1. Real-world entities (for example, employees) are used to represent data stored in tables
in a database.
2. JDeveloper uses data and metadata from the table to create a Java class that represents
the entity. You can edit this Java code to change the default attributes and behavior.
3. JDeveloper also represents metadata in a customizable XML file.
11-248
4. JDeveloper can create default view objects to specify criteria for selecting data. You can
define your own view objects in addition to (or instead of) the defaults.
5. JDeveloper generates customizable Java classes for each view object: a class for the
view object definition and a class for the row. It also generates an XML file for each view
object.
6. You use a wizard to define an application module. An application module is a logical

container for related objects. It provides a context for defining and executing
transactions.
After the application service comprising the business components is designed, built, tested, and
debugged, you can deploy it.
Runtime
1. Client code initializes an application module, loading the entities and views it contains.
2. When a view object executes a query at run time, it manipulates data from the
corresponding entity or entities.
3. Each view object provides a default iterator that you can use to navigate through its
result set.
4. When a query fetches one or more result rows, individual rows are represented by Row
objects. Each column value in the result row is accessed through an attribute of a Row
object.
5. Controls in the client form enable users to view and edit the data. The controls display
rows provided by view objects, which are themselves bound to underlying entity objects.
So, when a user changes a value in a control, the Business Components for Java
framework sends the action to the view object, which sends it to the entity object.
Business rules (if any) attached to the entity object validate the new value before the
framework sends it to the database.
11-249
What Is the Business Components Framework?
The business components framework is class library, in oracle. jbo.*, with built-in application
functionality. Using the framework involves specializing base classes to introduce application-
specific behavior, allowing the framework to coordinate many of the basic interactions between
objects.
By using the Business Components for Java design-time wizards and editors, you can build
business logic tiers by defining the characteristics of components: their attributes, relationships,
and business rules. Business Components for Java generates Java source code and XML
metadata to implement the behavior you have specified. Because the code inherits from a
framework, the Java source files are concise and do not contain large amounts of generated
code, so it's easy to see where to add the code that models your business. You can use
JDeveloper to add the Java code to enhance or change the behavior, and easily test the
application services, independently of the deployment platform.
11-250
About Testing Business Components within
JDeveloper
The Oracle Business Components Browser (also called the Tester) lets you quickly test your
business logic tier from within JDeveloper. To access it, simply right-click an application module
and choose Test from the Workspace view of the Navigator.
The Tester is an example of a generic, thin Java client application. It uses the dynamic
capabilities of the framework's client APIs to interrogate the runtime metadata of any
application module that you want to exercise, and presents a directory of the view objects and
view links contained by the current application module. The Tester creates dynamic Swing-
based forms for each view object you want to browse, and dynamic master-detail forms for
each view link that you want to test.
The Tester visually exposes all of the runtime features of the framework including:
● view objects, which can be executed, scrolled, and have the values in any of their
columns changed,
● entity object business logic, which will be enforced when changes to related view object
columns are made so you can verify that domains are set up properly, that default value
logic functions correctly, that validation code is working, and that association lookups do
what you expect,
● multiple view objects, which include the same entity attributes stay synchronized when
changes are made through any of them,
● view linked view objects are automatically master-detail coordinated as you scroll
through master records to any level of depth,
● application modules can be tested in any supported deployment configuration from a

single application: Local, Remote CORBA/EJB in a physical business logic tier, as well
as Remote CORBA/EJB inside of Oracle8i.
When you commit, all pending changes are communicated to the database by the underlying
entity objects in the cache.
11-251
11-252
Planning a Business Components for Java program could follow these basic phases:
1. Use cases
2. UML diagrams
3. Database tables and business components implementation
4. Clients and deployment
11-253
Stage 1: Use Cases
The first step in planning the application is determining what it should do. A team of experts
interviews end users to determine what they need and learn their nomenclature. They
remember "nouns" and "verbs."
11-254
Stage 2: Class Diagrams
The next stage is to determine the objects and classes your application needs. To do so, you
can create a class diagram, perhaps using a software tool.
The Unified Modeling Language (UML) is a general, notational language for specifying and
visualizing complex software. It is ideal for large object-oriented projects. The JDeveloper class
modeler can help by allowing you to create UML class diagrams to model your business
components and to then generate business components from the model. See Modeling
Business Components for more information.
11-255
Stage 3: Database Tables and Business
Components Implementation
You can either create database tables or business components first, and then automatically
create the other based on the definitions.
Database tables
There are two ways you can create database tables:
● With reverse generation, a database administrator creates tables to meet the business
requirements. The tables are used to create the initial definitions of entity objects. Entity
objects have attributes that correspond to the columns of the tables, and associations
between entity objects are created for the database constraints.
● With forward generation, the tables are created based on the business components
definitions. The database administrator can then refine them as needed.
Business components implementation
The business components implementation is comprised of the following objects:
● Entity objects. Each entity object has attributes.
● Associations link the entity objects, in a bidirectional manner, so each entity object can
access other entity objects' information.
● View objects filter data from the entity objects.
● View links link the view objects, in a unidirectional manner, from master to detail.
● The view objects and view links will form the data model in one application module.
Business Components for Java provides a wizard for each business component, to help you
define them quickly. You can then modify the automatically generated code as needed.
11-256
Why use both entity objects and view objects?
Entity objects answer the question, "What objects are relevant to the business?" They are
nouns in the problem domain.
Application modules answer the question, "What tasks does the business perform?"
View objects answer the question, "What data is relevant to the task?"
Associations are relationships between entity objects, regardless of the tasks involved.
View links help you set up hierarchical master-detail relationships so you can build the view you
want. For example, "I need to work with XS and its related set of Y." Although they are similar
to associations, you might need additional relationships that gather the data you need for a
certain task.
11-257
Stage 4: Clients and Deployment
After creating a business logic tier, you can quickly deploy it to multiple platforms. You can
create Swing-based Java clients, HTML clients, and batch Java clients for the application.
11-258
About Structuring the Development Team
As with all large Java programs, you can break your product into "subproducts" and have
different development teams for each functional area.
In addition, for business components programs, in some circumstances it makes sense to have
separate teams that work on:
● business logic, including entity objects, associations, and database tables
● presentation, including view objects, view links, application modules, and clients
Related topics
11-259
Customizing the Business Components Framework
Typically, in an applications organization, the framework supplied by JDeveloper will be
customized by a core group. A customized framework streamlines application development by
providing base classes that the business components can inherit from. You can extend the
framework base classes for entity objects, view objects, and application modules, and then your
organization can generate business components from these customized classes. This offers
the following advantages:
● You can specify default framework base classes while you are setting default business
component preferences with the Preferences dialog. The default classes become the
defaults in wizard and editor fields, and are the base classes used when you generate
default business components.
● Business components can be made to extend from common framework base classes.
This can be utilized to provide common features and functionality to all default-generated
business components.
● Changes made to the base classes are carried through to all business components that
inherit from the base class.
Who needs framework customization?
For Business Components for Java, it's a best practice to extend the default framework base
classes. This way you can easily and globally customize the framework for your entire
company, a company division, or a specific project, either now or in the future.
For best results, framework customization preceeds application development.
If your application will span multiple versions or will have many developers working on it, a
customized framework is a good idea. The framework will speed the development of repetitive
tasks, as well as provide for easier modification in the future.
You may not need framework customization if you have access to the original source code, the
application is relatively small, doesn't require a common set of business components, or
What business components classes can be customized?
You can extend the framework base classes for the following business components:
11-260
● entity objects
❍ entity definition class — oracle.jbo.server.EntityDefImpl
❍ entity collection class — oracle.jbo.server.EntityCache

❍ entity row class — oracle.jbo.server.EntityImpl
● view objects
❍ view object class — oracle.jbo.server.ViewObjectImpl
❍ view row class — oracle.jbo.server.ViewRowImpl
● application modules
❍ application module class — oracle.jbo.server.ApplicationModuleImpl
How do I customize the framework?
In order for business components to extend a customized framework, you need to create a
library of business components to extend from.
The process of customizing components follows these general steps:
1. Create a JAR file containing the existing components and their project (.jpx) file.
Typically, this will already have been done for you by the application supplier.
2. Create a JDeveloper library for the JAR file and add it to the list of libraries for the new
project.
3. Import a package of existing components from the JAR file using the Import Package
option in JDeveloper.
4. Create a new package with a different name from the original to house the customized
components.
5. Use the wizards to create new components in your new package that extend the
appropriate components in the imported package.
6. Optionally, if you want the extended component to completely replace the original in an
existing application, substitute the extended component for the original.
How do I specify base classes?
Business components are customized through the BC4J Base Classes dialog. To open this
11-261
dialog, in the System Navigator, select a business components project, and choose Tools |
Preferences, expand the node for business components and choose BC4J Base Classes.
Specify the classes you want to use as the defaults. JDeveloper will now use these classes
when generating default business components. In addition, when you use a business
component wizard or editor to define a business component, the class will be listed as the
default class to extend.
You can also specify a base class on a per-object basis using Framework Base Classes dialog.
To open this dialog, create or edit a business component with the wizard, go to the Java page
and click Extends.
How does framework customization compare with customizing

existing business component programs?
Framework customization happens before an application is developed.
Customizing existing business component programs is a step that is done after the application
has been delivered.
Related Topics
Setting Framework Base Classes

Enabling and Disabling Java File Generation
Generating Java Source Files and Methods for Entity Objects
Creating and Registering Validation Rule Classes
Creating a Domain
Setting Default Business Component Preferences and Project Settings
Creating Default Entity Objects and Associations from a Database
Ways to Create Default View Objects, View Links, and Application Modules
11-262
Converting a Legacy Application into Business
Component Application
If you have an existing application that you want to convert to a Business Components for Java
application, you will find this topic helpful. Although there is no one recipe for converting an
existing application to use business components, there is a logical order in which things can be
done.
Your current application is assumed to be a two-tier client-server application, with a thick-client

front end accessing a database back end. Legacy client-server applications of this sort are
forms-based, meaning that the business logic resides directly in the client forms. Applications of
this sort are often created with tools like Developer 2000, PowerBuilder, or Visual Basic.
Depending on the language the application is coded in, you may have an easier or harder time
converting the application. If it was coded in Java, you will be slightly better off, as the language
would have forced the business logic to be created in classes, and not in the user interface.
Business Components for Java puts the business logic on the business logic tier. As such, the
client forms do not contain the business logic. This change of paradigm is central to the design
of business component applications. Your business components application will be structured
differently. Even though the final application will use some sort of form, it may be distributed in
a number of different ways.
Analyzing the Current Application
Before you can start building your business components application you must analyze your
current application on a form-by-form basis. Each of the client forms in your application
contains information that will help you build your business component application. To decipher
this information, you need to ask the following questions:
● What database tables does this form access?

● What constraints are the forms putting on the tables?
● What view of data is this form showing?
What database tables does this form access?
Take a look at each form and note which database tables this form modifies or uses These
tables will correspond one-to-one with entity objects in a business components application.
11-263
For example, if you have an Orders form that contains information about salesperson,
customer, and item, you can infer that there are at least three database tables that contain this
information. These database tables will be represented by entity objects.
When two database tables are linked by a key, this is represented by an association object. An
association object links entity objects. To find the associations, you must know or infer the
relationships in the underlying tables.
What constraints are the forms putting on the tables?
In a forms-based application, validation occurs on the client forms. Event handlers for the
individual UI-controls handle validation of their fields. For example, a text field control could
have an event called on_change. When the text field changes, the on_change event
executes the code related to the event. In this manner, the business logic is validated.
In a business components application, validation is done on the business logic tier. Your UI
controls will not enforce validation, so you will need to decipher the business logic for each
control on every form. You will probably find that many forms use similar validation for their
fields, for example, validating a date, which will simplify the process somewhat.
Domain objects are a special kind of business component that declare what kinds of values
something may have. For example, you could have a membership domain that allowed only the
values Platinum, Gold, and Silver. In your legacy application, this could be implemented by a
drop-down list that contains only those discreet values. In a business components application,
each of your user-designed types should be represented as a domain object.
What view of the data is this form showing?
Each form in your legacy program represents some view of the data. Ask the following
questions:
● Does this form contain a subset of the available values; are certain fields hidden? For
example, is this form showing only customers?
● Is this form something that anyone can see or does it apply to a specific group only?
● Does this form modify all data in the table, or just a subset?
● What are the data items in this form?
When you create your view object, your view object SQL query will be based on the answers to
these questions. Each form that represents a unique view of the data can be represented by a
view object. You will have as many view objects as there are views of data.
11-264
View links connect view objects in the same way that association objects connect entity
objects. To define the view links, there are additional questions to be answered:
● Is this table linked to other tables?

● If so, what is the relationship?
The answers to these questions will tell you what gets selected from each table. This will help
you when you define a view link SQL query.
What task is being accomplished?
Generally, you will have one application module per task. If a form contains one task, it will
relate one-to-one with an application module. If the form contains multiple tasks, it will contain
more than one application module.
Building the Business Components Application
If your legacy application uses a non-Oracle database, you can develop your application
against it, but there are certain limitations. Also, if your database uses any enhanced datatypes
not supported in the SQL92 standard, you will have to design a custom type map. For more
information, see the section on Developing Business Components for Foreign Datasources.
11-265
Working With Business Component Projects,
Packages, and System Options
When beginning a business components application, you should consider the organization of
your workspace, the default system and project options, and the type(s) of database you will
use.
Organizing your workspace
Before you start a business components project you should consider the organization of your
workspace. In particular, you may find that that you will need multiple projects in your
workspace, each one customized for a particular task or area. Likewise, within each project you
will want to customize the packages by grouping them functionally, how they are delivered, or
along some other logical lines. For information on structuring your projects and packages, see
the topic About Structuring Business Component Projects and Packages.
Setting default system and project options
Before you start a business components project you will find it helpful to set default options.
Setting default schema options can help limit the number of initial choices, which is particularly
useful when your schema defines a large number of database objects. Setting default
framework base classes is useful when the framework supplied by JDeveloper will be
customized by a core group. All business components may be built over this customized
framework, which will allow you to add custom functionality to all objects of a given type, by
extending the framework base classes. It may help you organize your application by setting
business component root and working directories for each project.
There are also additional options for setting business component project properties and
options.
Choosing a database development scenario
Plan your application around a database scenario. Since Business Components for Java was
designed to work with Oracle8i, this is the default database configuration. However, since the
3.2 release of JDeveloper, you can connect to a foreign datasource and specify custom type
mapping. This opens up a range of development scenarios, from creating an application that
will run against generic databases, to custom database support, to databases that can be
switched at design-time or runtime. For more information, see the topic About Developing
11-266
Business Components for Foreign Datasources.
Importing business components
You can build extended business components by adding a JAR file of business components
(.class files and .xml metadata) to your project's library list and creating your new derived
components by extending the components delivered in the JAR file. For more information, see
the topic About Importing a Business Component Package. You can also import business
components to use existing entity objects in new view objects or existing view objects in new
application modules.
Incorporating legacy code
If you have a legacy client-server application that you are converting into a Business
Components for Java application, there are some guidelines that will help you make a start. For
more information, see the topic Incorporating Legacy Code into Business Component
Programs.
11-267
A business component project differs from other JDeveloper projects by having a .jpx file. The
.jpx file is an XML file that defines the project as a business component project. A business
component project contains the following folders and files:
● Deployment folder - The Deployment folder contains deployment profiles (.prf files).
When you create a new deployment profile, it is placed here by default. The folder only
appears when you have deployment profiles and you have switched on category view.
● Packages - A business component package is a Java package.
❍ Business components - This is where your application modules, associations,

domains, entitiy objects, view links and view objects reside. The business
components are represented by a Java file and an XML file.
● JPX file - The .jpx file is an XML file that defines the project as a business component
project.
● Other files - your business component project may contain any number of files, from
custom Java or XML files, to TypeMaps, etc.
11-268
What Business Component Packages Are Imported
When you create a business components project, the following business component packages
and classes are imported.
Package Imported by
oracle.jbo.server.* All business components
oracle.jbo.RowIterator Entity objects and view objects
oracle.jbo.domain.Number Entity objects
oracle.jbo.Key Entity objects
oracle.jbo.server.util.* Entity objects
oracle.jbo.RowIterator View objects
oracle.jbo.ViewObject Application modules
oracle.jbo.domain.DomainOwnerInterface Domains
oracle.jbo.domain.DomainInterface Domains
oracle.jbo.JboException Domains
oracle.jbo.Transaction Domains
Other packages are imported depending on what you do. For example, if you create a
remoteable application module, you will import additional packages appropriate for the remote
target. For additional information, see the Javadoc.
11-269
About Structuring Business Component Projects
and Packages
Deciding on an intelligent system for organizing your projects and packages during the planning
stage can save you time during the development phase.
Structuring Projects
A business component project is a collection of files grouped together for your convenience.
You might want to have several projects in your workspace, with each project optimized for a
particular task. For example, your main project would contain all the packages in your business
components application; when you compile or deploy your entire project, you would do so from
there. For simplicity or to speed up performance, you might have a design-time project that
loads only some of the available packages. You might have yet another project that contains
only the packages needed to perform a specific task, such as debugging part of the program.
Structuring Packages
A business component package is a Java package containing classes for part or all of a
business logic tier. In addition, a business components package has an associated XML file.
Deciding what packages you want in a business logic tier is the same as when you are
developing any Java program. Different application feature teams might need to be able to
work independently on their functionality. You need to functionally decide what objects to put
together in packages according to what methods you want internal team members to use
versus what you want external teams to use. If a portion of your product gets delivered together
as a component, you probably want to put it in one package.
In a product using business components, you need to decide what business components you
want to group in the same package, so they have access to package private methods and
variables, and which business components should be in different packages. Business
components in separate packages can interact through public methods and variables; you can
also reuse the packages in other projects as needed. As a general guideline, you need to
decide what "subproduct" your product is made of. Then you can create the following packages
in your business components project(s) for each subproduct:
● business logic package, including entity objects and associations as well as view objects
used for filtering and validation
11-270
● presentation package, including the application module as well as view objects and view
links that project and filter data for the UI
● client package
● interface and domain package, which are common to both tiers and you might want to
upgrade it separately
Another consideration is the size of the package. Small packages are loaded faster than very
large packages both during development and deployment. JDeveloper has a "lazy loading"
feaure that can help speed up performance during development, by loading only the classes
needed at that time, rather than all classes in a package.
11-271
About Importing Business Components
There are a number of scenarios where you may want to import existing business components.
For example, you may want to base your business components project on an existing
application, or you may have two more more separate projects that you want to merge into one
project. Depending on your needs, there are two ways to import the existing business
components: as read-only files from a JAR or Zip file, or as mutable source files. You can
extend existing business components, create new view objects from existing entity objects, or
create new application modules from existing view objects.
About Importing JAR or Zip Files
You can build extended business components in nearly the same way that you build extended
Swing classes. You extend Swing classes by adding the Swing JAR file to your project's library
list and creating your new derived classes by extending the classes delivered in the Swing JAR
file. You build extended business components by adding the JAR file of business components
(.class files and .xml metadata) to your project's library list, and extend the components in
the same manner.
As is typical with other archives, the "runtime" JAR file does not have the source in it. The
application supplier might choose to make source available separately or not. Again, exactly
like the Swing example, the source is not required to extend the base classes.
The JAR file containing the package of original components will serve as the base for the
extended components. The developers who will be customizing the components, must define a
library for the JAR file and add it to the library list for the project. The package of original
components then must be imported into the project that will house the extended components.
Within this project, a package must be created to house the extended components.
Maintaining separate packages for the existing and extended components allows customization
to be performed without the danger of modifying the existing components. When a library is
imported into your project, all of the contents of the library are read-only. This is to protect you
from accidentally modifying the metadata of the delivered components.
About Importing XML Source Files
If you need to import mutable files, then you must import the source files directly. Files imported
this way are treated the same as any other source file in your project.
11-272
Related topics
Importing Business Component XML Files from a JAR or ZIP File
11-273
Setting Default Business Component Preferences
and Project Settings
You can customize the default preferences and project settings for JDeveloper. Following are
tasks particularly relevant to business components projects:
● Setting default schema options
● Setting default framework base classes
● Setting root and working directories
To specify business component preferences:
● Choose Tools | Preferences.
The Preferences dialog appears. The settings in the Business Components area of the
tree are used as the default for all of your business component projects.
To specify default project settings:
● Choose Project | Default Project Settings.
The Default Project Settings dialog appears. These settings are used as the default for
all of your projects.
Related Topics
11-274
Setting Default Schema Options
In the Preferences dialog, you can use the Schema Options page to set the default database
object display in the Name page of the Entity Object Wizard and in the Business Components
page of the Business Components Project and Package Wizards. You specify database objects
during reverse generation.
Limiting the initial choices is particularly useful when your schema defines a large number of
database objects, so it's easier to choose what you need. You can change the default while
using the wizard.
Field description
Field Description
Tables, Views, Synonyms, Select a checkbox to include the item in the list when users first open the
Snapshots wizard page. Deselect it to exclude these objects.
Related topics
Creating and Modifying Entity Objects and Associations
About Reverse Generation
11-275
Setting Default Framework Base Classes
Entity objects, view objects, and application modules are based on these framework classes:
● entity definition class — oracle.jbo.server.EntityDefImpl
● entity collection class — oracle.jbo.server.EntityCache
● entity object class (row) — oracle.jbo.server.EntityImpl
● view object class — oracle.jbo.server.ViewObjectImpl
● view row class — oracle.jbo.server.ViewRowImpl
● application module class — oracle.jbo.server.ApplicationModuleImpl
You can optionally extend one or more of these classes and generate business components
from your customized classes. When you add functionality to your classes, either now or in the
future, you globally affect all the business components that extend from them.
Use the Preferences dialog to specify your custom framework base classes as the default:
● They will appear as the default base classes in the Entity Object, View Object, and
Application Module Wizards and Editors and in Java code. In the wizards and editors,
you can change the default, as needed.
● They are used when you generate default business components.
To specify default framework base classes:
The Preferences dialog appears.
2. In the left pane, select Business Components | Base Classes.
3. In the right pane, specify the classes you want to use as the defaults.
11-276
The class must extend the appropriate framework base class and be located on the
classpath.
4. Click OK.
JDeveloper will now use these classes when generating default business components. In
addition, when you use a business component wizard or editor to define a business
component, the class will be listed as the default class to extend.
Related topics
About Customizing the Framework
Creating Default Entity Objects and Associations from a Database
Ways to Create Default View Objects, View Links, and Application Modules
11-277
Setting Business Component Root and Working
Directories
You can set business component root and working directories from the Project Settings dialog.
You set these directories in the same way that you would any JDeveloper project.
To set default project settings:
● Choose Project | Default Project Settings.
To set project settings:
● While a business components project is selected in the Navigator, choose Project |

Project Settings.
Related Topics
Setting Business Component Project Options
11-278
Ways to Create a Business Component Project
You can create a business component project in the following ways:
● Create a new business component project.
● Turn an existing project into a business component project.
Related topics
11-279
The Business Components Project Wizard lets you create a business component project,
including the database connection, Java package, and optionally default business components.
You can edit any default business components you create with this wizard and add new
business components later.
1. While the workspace you want to add the project to is selected in the Navigator, choose
File | New.
2. In the New Gallery, select Projects in the Categories list and then Project with Business
Components in the Items list, and click OK.
3. In the Location and Paths pages of the wizard, specify the standard project information.
Click Help for information on the fields. Click Next to go to the next page.
4. In the Finish page, click Finish.
The Business Components Project Wizard appears.
5. If the Welcome page appears, click Next.
6. In the Connection page, type the connection information for the database that the
business logic tier will use. Then click Next.
7. In the Package Name page, specify the Java package that will hold your business
components. Then click Next.
8. In the Business Components page, if you are performing reverse generation, you can
optionally specify which default business components you want to create from existing
database information. If you are performing forward generation, do not add any
information. Click Next.
9. In the Summary page, review the information. Click Back to change information. Click
Finish to create the database connection, package, and default business components, if
specified.
Note that the business component project is described by an XML file, which is shown in
the Navigator as a JPX file.
11-280
Related topics
11-281
Specifying the Directory and Filename for a
Business Components Project
While you are creating a business components project with the Business Components Project
Wizard, use the Location page to name your project and define its directory.
Field descriptions
Field Description
Type a new or existing directory name for the project or
click Browse to select one. By default, the directory is
Directory Name placed in the work directory within the user home.
Type a filename for your project, with a .jpr file

extension. By default, the generic name Project.jpr is
incremented each time you use the default name, for
File Name example, Project1.jpr. The name you supply here will
appear in the Navigator.
To continue with the wizard:
Related Topics
11-282
Specifying the Paths for a Business Components
Project
Wizard, use the Paths page to define the paths for your new project.
Field descriptions
Field Description
The default package for this project. To change the
Default Package default value, type a new package name.
The path or paths to the Java source files contained in

your project. By default, this is the src directory under
the project file's directory. To change the default, type a
Java Source Path new value or click Browse to display the Edit Project
Source Path dialog, which you can use to modify paths
in, or add paths to, your list of root directories.
The directory where compiled class files will be placed.

Output Directory To change the default, enter a new value or click Browse
to select an existing directory.
Related Topics
11-283
Specifying the Connection to the Database
Wizard or specifying project options with the Business Components Project Editor, use the
Connections page to specify the database connection for the project. You can have one
connection per project.
Field Description
Connection Name Choose the connection that you want to use. Click New to define a new connection. Click
Edit to edit an existing connection.
After you choose a connection, the page displays the User Name and Connect String,
which you can change by clicking Edit.
Choose the type of SQL your application will use. For more information, see About
SQL Flavor
Developing Business Components for Foreign Datasources.
Choose the type map you will use. If you specified a custom type map, it will appear in this
Type Map
list. For more information on type maps, see About Type Maps.
To specify a connection:
1. Choose a connection in the Connection Name field. If you need to define a new
connection, click New. If you need to edit an existing connection, choose the connection
and then click Edit.
2. If you are developing against a database other than Oracle, choose a SQL Flavor.
3. If you need to use a custom type map, between Java in the business logic tier and SQL in
the database, choose it in the Type Map field.
Related topics
11-284
11-285
Specifying the Name of a Package in a Business
Component Project
While you are creating a business component project with the Business Components Project
Wizard, creating a package with the Business Components Package Wizard, or editing a
package with the Business Components Package Editor, use the Package Name page to
specify the name and location of a package to hold business components. It is a jbo package, to
hold jbo classes, and a Java package, to hold Java classes. You can have multiple business
component packages for the same reason any Java programmer uses multiple packages: to
implement a good architecture.
Field descriptions
Field Description
Package Name Accept the default name or type a new name. You can type a single-word name (for
example, myPackage), or a dot-separated name (for example, oracle.jbo.server) and
JDeveloper will create the necessary directories for you, if they don't already exist. The root
directory is the source path from the project.
Related Topics
11-286
Editing Default Business Component Object Names
While you are creating a new business component project or package with the wizard, from the
the Business Components page, use the Edit Object Names dialog to change the name of
default entity objects and view objects.
Note: Any associations and view links created will have their names based on the default object
names, not the newly specified name.
Field descriptions
Field Description
Entity Object (Optional) Type a new default name in the field.
(Optional) Type a new default name in the field.
View Object
Related topics

11-287
Understanding the Default Business Components
After creating a business components project with the Business Components Project Wizard,
you have various project files and optionally default business components, if you chose to
generate them. These items are displayed in the Navigator.
If you chose to generate default business components, you will have business components in
your package, arranged in alphabetical order. For example:
optionally a view link were created. The names were based on the database constraint names,
with the suffix "Assoc" or "Link." Alternatively, you could have changed the default names.
and text fields. A default application module is named the same as the package, but with the
11-288
suffix "Module," unless you changed the default name.
Business components are defined in Java files and XML files, which you can see by expanding
the component's node:
Each default entity object, view object, and application module is defined in a Java file, which
you can customize. In addition, each business component is defined in an XML file, which
allows you to modify the application's behavior without recompiling Java code. If you look at
one of the Java or XML files, you will see that each entity and view object has attributes
corresponding to each column in the table.
Generating a default business components project provides a big head start in your
development effort. Afterwards, you can customize the business components and add new
business components to complete the business logic tier of your application. In addition,
Business Components for Java lets you generate default JClient and JSP clients through
JDeveloper wizards.
Related topics
11-289
11-290
Turning an Existing Project into a Business
Component Project
1. In the Navigator, select a project JPR file and do one of the following:
❍ Right-click and choose New Business Components.
❍ Choose File | New, select Business Components in the Object Gallery Categories
list and then in the Items list, and click OK.
2. Work through the Business Components Project Wizard.
Related topics
11-291
To edit an existing business components project, in the Navigator, right-click a JPX file in a
business components project and choose Edit to access the Business Components Project
Editor. Or double-click it.
The JPX file is an XML file describing the project.
You can customize your project options by:
● Specifying the connection to the database - There is one connection per project.
● Specifying whether Java code is generated - You may not need to generate Java files if
you encapsulate the business logic in the validator classes or your entity objects do not
need validation. A few benefits of generating Java code are that you have access to
strongly typed accessors instead of just having to use the generic getAttribute and
setAttribute methods that return an object, and you can write code in the setter method.
● Specifying whether all packages are loaded - You can improve performance by lazy
loading components or by not loading all the packages.
● Specifying a custom message bundle - A message bundle allows you to override the
system-generated error messages with your own text. A message bundle contains an
array of error numbers and replacement text that you specify.
● Substituting business components - This is a useful feature if you have created an

extended object and want to substitute your new extended object for all instances of the
base object.
● Creating validation rule classes - You can use validation rules to ensure that the values
returned by a query are valid or that users do not enter invalid data.
● Setting root and working directories - You can set directories at the project level, giving
you fine-grained control of where your files are located. It is best if you set these
directories before you generate files.
Related Topics
11-292
11-293
Specifying Code Generation, Lazy Loading, and
Custom Message Bundle Options
While you are editing a business components project with the Business Components Project
Editor, use the Options page to set these options:
● Code generation
● Lazy loading
● Custom message bundle
To save changes:
Related Topics
11-294
Editor, in the Options page, you can specify whether Java files are generated.
The XML files are where JDeveloper stores the metadata for the generated objects. Typically,
Java files are where the business logic is implemented. You might not have to generate Java
files if:
● You encapsulate the business logic in the validator classes.
● Your entity objects do not need validation.
Field description
Field Description
Code Generation Select Java and XML files to generate Java files or XML files only to not generate Java
files.
To save changes:
Related Topics
Specifying Code Generation, Lazy Loading, and Custom Message Bundle Options
11-295
Improving JDeveloper Performance by Not Loading
All Packages
Editor, in the Options page, you can specify whether to "lazy load" packages.
When working with very large business component projects it may be useful to load only those
packages that are of immediate use. This can be accomplished by enabling lazy loading of
business components. Lazy loading will load business components as they are required. If this
checkbox is not selected, all business components are loaded immediately upon startup.
This runtime feature is also available by modifying the server.properties file.
You can also improve performance by explicitly stating which packages are to be loaded before
starting JDeveloper.
Note: During runtime, the lazy loading flag value stored in the project JPX file is not loaded until
you connect to the datasource. So, if you launch the Tester and look at the configuration before
connecting, it will show the flag value as it is set in the server. After connection, it shows the
value as set in the JPX file.
Field description
Field Description
Lazy loading Select this option to load packages as needed. Deselect it to load all packages at startup.
enabled The default is enabled.
To save changes:
Related Topics
11-296
Specifying a Custom Message Bundle
While you are editing a business components project with the Business Components Project Editor, in the Options
page, you can specify a custom message bundle. A message bundle allows you to override the system-generated
error messages with your own text. A message bundle contains an array of error numbers and replacement text that
you specify.
● To create a new message bundle, click New.

● To use an existing message bundle, click Add.
● To remove a message bundle, select it and click Remove.
You may have noticed that all Business Component error messages are five digits prefixed with "JBO-", for example
JBO-25222. To override the error message for this exception, your resource bundle must list "25222" and the text
you want to replace (you do not use the JBO- prefix in the message bundle).
To edit the message bundle class:
1. In the Navigator, double-click your message bundle class to open it in the Code Editor.
2. Where you see the comment /*fill in 2-D array here*/, enter the number of the error that you want to replace,
followed by the text you want the user to see. Use the following format:
package mypackage;
import java.util.ListResourceBundle;
public class MessageBundle1 extends ListResourceBundle
{
private static final Object[][] sMessageStrings = new String[][] {
{"25002", "Could not start the application. Call x9876 for assistance."},
{"26061", "Application cannot connect to database. Call x4357 for assistance."},
{"27122", "Application error, log a support ticket or call x9876 for assistance." "}
};
/**
* Return String Identifiers and corresponding Messages in a two-dimensional array.
*/
protected Object[][] getContents()
{
return sMessageStrings;
}
}
Related Topics
Business Component Error Messages

Customizing Error Messages
11-297
Substituting Business Components
Editor, use the Substitutions page when you have created an extended object, for example,
DeptExtended from Dept, and you want to substitute your new extended object for all instances
of the base object; you want all instances of Dept to be replaced with DeptExtended.
Note: You must select the same type of business component in the Available and Substitute
lists. You cannot, for example, substitute a view object for an entity object.
Field Description
Available Select the business component that you want to make a substitution for (in the
above example, this would be Dept).
Substitute Select a business component that will be making the substitution (in the above
example, this would be DeptExtended).
Add Click Add to create a new substitution. If this button is not enabled, you need to
select a business component in each of the Available and Substitute lists. These
two business components need to be of the same type (for example, both entity
objects).
Update Click Update to change a substitution. If this button is not enabled, you need to
select a different business component in the Substitute list.
Remove Select a substitution from the Substitutions list and click Remove to delete it.
Substitutions A list of the substitutions that have been made. Select an item from this list to
Update or Remove it. When you select an item from this list, the business
components that comprise this substitution are highlighted in the Available and
Substitute lists.
To save changes:
Related Topics
11-298
Creating and Registering Validation Rule Classes
Editor, use the Registered Rules page to create or add validation rules to your project. This
page displays the registered validation rules already defined. These rules are stored as a list
with the project's XML-definition (.jpx file). Registered rules can be applied to an entity object
or an entity attribute as a validation rule.
Field Description
Registered Validation Rules The list of rules contained by the project.
New Click New to open the New Class dialog where you can create a new
registered validation rule for your project, and specify class and style
information for the rule. This information will be used to generate skeleton
code for the rule and will add a new Java file to the project.
Custom validation logic can then be implemented in the validateValue

method of the class. Since this new class is a JavaBean, new properties
(generated in the class) could be added to the Java class.
Note: At the time of applying the rule to a particular level, newly defined rules
have to be compiled before property values can be declared for them.
Add Click a registered rule name in the Registered Validation Rules list and click
Add to add it to the project.
Remove Click a rule name in the Registered Validation Rules list and click Remove
to delete it from the project. Note that if the rule has already been applied at
some level, that information is still valid.
To create and register a new validation rule class:
The following steps show how to create and register a validation rule based on a business
component validation class. The Business Components for Java framework provides several
validation classes, and you can implement custom validation classes.
1. In the the Navigator, right-click the JPX file, then choose Edit.
The Business Component Project Editor opens.
2. Click the Registered Rules tab, and then click New.
11-299
3. In the New Validation Rule class dialog, type the class name for the rule and the name of
the package where it should reside. Type the fully qualified class name in the Extends
field if the validator extends the functionality of an existing class.
4. Click OK to close the dialog. Click OK to exit the Business Component Project Editor.
The Business Component for Java framework generates code and registers the new validator
type. The new validator name will appear in other wizards and you can apply it to entity objects
and attributes as you would any other rule.
To add existing validation classes to your project:
1. In the Navigator, right-click the Business Components for Java project file, then choose
Edit.
The Business Component Project Editor opens.
2. Click the Registered Rules tab, and then click Add.
The Rules dialog appears. By default, the dialog displays the JboGenericValidator
class, and the Description field lists Temporary.
3. Specify a class and name.
The class must implement the JbiValidator class.
If you click Browse, the Find Superclass dialog opens. This dialog uses a tree structure
to display the classes from which you can choose. Note that one of the classes,
oracle.jbo.server.rules, contains the business component validator classes. For
more information on these classes, see Business Component Validator Classes.
Some validator types can be customized. If the Edit Validation Rules panel is available,
you can enter data in the table of Properties and Values to specify parameters for the
validator. (If the validator is a JavaBean with its own customizer, that customizer will
display.)
4. Click OK to close any open dialogs. Click OK to close the editor.
11-300
The Business Components for Java framework generates code and registers the new validator
type. The new validator name will appear in other wizards and you can apply it to entity objects
and attributes as you would any other rule.
Business Component Validator Classes
Following are the business components validator classes in oracle.jbo.server.rules.

You can use these directly, or as the basis for a custom validator type.
Class Description
JboCompareValidator Performs logical comparisons with literals.
JboSQLCompareValidator Performs logical comparisons with the result of a SQL statement.
JboQOCompareValidator Performs logical comparisons with the result of a view object's

query.
JboRangeValidator Performs range comparisons with literals.
JboListValidator Checks that a value is one of the list.
JboQOListValidator Checks that the value is one of the list returned by executing this
view object. This may be used for LOVs.
JboSQLListValidator Checks that the value is in the list returned by executing a SQL
statement.
JboMethodValidator Used to invoke user-defined methods.
Related topics
Ways to Add Validation Logic
11-301
Creating a New Validation Rule Class
Editor, from the Registered Rules page, you can use the New Validation Rule class dialog to
provide the details of your new validation rule class.
Field Description
Name Type the name of your validation rule or accept the default name.
Package Specify the name of the package that this new class belongs to.
Extends Specify the name of the Java class that this new class extends (or inherits) from. By default
the class will extend java.lang.Object.
Related topics
11-302
Registering an Existing Validation Rule Class
Editor, from the Registered Rules page, you can use the Rules dialog to specify the Java class
that will be used as a validation rule. Select an existing class (it needs to be compiled and
available in the classpath of the project) to be registered as a validation rule. Give a valid alias
by which the project should address the selected class.
Field descriptions
Field Description
Class The Java class to which the validation rule belongs. If you do not want to use the
displayed class, click Browse to select the validator class from a tree of available
packages in the classpath. Alternatively, a fully qualified class name can be entered
in to the Class field. If the name is a valid validation rule class (it implements
JbiValidator interface), then it's description is shown in the Description field.
Click OK and the rule will be registered with the project through the Project Wizard.
Name A default name is provided for the validation rule. You can accept the default or enter
a different name.
Description A text description of the validation rule.
Related topics
11-303
Selecting a Superclass
Expand the tree to select a class that extends the appropriate base class. Then click OK.
11-304
Creating and Editing a Business Component
Package
The Package Wizard and Editor let you create and edit packages. They provide some of the
same functionality as the Business Components Project Wizard.
While the business components project is open, to create a package with the Package Wizard,
do one of the following:
● While the project is selected, choose File | New, click Business Components, and
double-click Package.
● In the the Navigator, right-click the project JPX file and choose New Package.
To edit an existing package, in the Navigator, right-click the package and choose Edit. Or
simply double-click the package.
Related Topics
Ways to Create a Business Component Project
11-305
Understanding Default Business Components
After creating a business components project with the Business Components Project Wizard,
you have various project files and optionally default business components, if you chose to
generate them. These items are displayed in the Navigator.
If you chose to generate default business components, you will have business components in
your package, arranged in alphabetical order. For example:
optionally a view link were created. The names were based on the database constraint names,
with the suffix "Assoc" or "Link." Alternatively, you could have changed the default names.
and text fields. A default application module is named the same as the package, but with the
11-306
suffix "Module," unless you changed the default name.
Business components are defined in Java files and XML files, which you can see by expanding
the component's node:
Each default entity object, view object, and application module is defined in a Java file, which
you can customize. In addition, each business component is defined in an XML file, which
allows you to modify the application's behavior without recompiling Java code. If you look at
one of the Java or XML files, you will see that each entity and view object has attributes
corresponding to each column in the table.
Generating a default business components project provides a big head start in your
development effort. Afterwards, you can customize the business components and add new
business components to complete the business logic tier of your application. In addition,
Business Components for Java lets you generate default JClient and JSP clients through
JDeveloper wizards.
Related topics
11-307
11-308
Ways to Import Existing Business Components
● Importing from a JAR or Zip file - If you import from a JAR or Zip file, you will be using
read-only definitions. This is useful if you are customizing an existing application and
don't want to change the underlying components.
● Importing a package - To use mutable source files, you must import a package of
business component XML files.
11-309
About Extending Imported Business Components
Just as you can build extended Swing classes by adding the Swing JAR file to your project's
library list and creating your new derived classes by extending the classes delivered in the
Swing JAR file, you can build extended business components by adding the JAR file of
business components (.class files and .xml metadata) to your project's library list and
creating your new derived components by extending the components delivered in the JAR file.
As is typical with other archives, the "runtime" JAR file does not have the source in it. The
application supplier might choose to make source available separately or not. Again, exactly
like the Swing example, the source is available but not required to extend the base classes.
The JAR file containing the package of original components will serve as the base for the
extended components. The developers who will be customizing the components, must define a
library for the JAR file and add it to the library list for the project. The package of original
components then must be imported into the project that will house the new customization.
Within this project, a package must be created to house the customized components.
Maintaining separate packages for the existing and customized components allows
customization to be performed without the danger of modifying the existing components. When
a library is imported into your project, all of the contents of the library are read-only. So you
don't have to worry about accidentally modifying the metadata of the delivered components.
Related topics
Ways to Customize Existing Business Component Applications
11-310
Importing Business Components
There are two ways to import existing business components: as read-only files from a JAR or
ZIP file, or as mutable source files in a package. The Import Business Component XML File
dialog lets you import business components in both of these ways.
To import business components:
1. If you want to import a JAR or ZIP file and you haven't already created, use JDeveloper
to create it.
2. Make sure the package, or JAR or ZIP file, is in the classpath. If you are importing a
package, it must also be in the source path.
3. If you are importing a JAR or ZIP file, create a library for it and add the library to the
project you want to import it into.
4. In the Navigator, right-click the project JPR or JPX file and choose Import Business
Components.
The Import Business Component XML File dialog opens.
Note that if you are importing a package, you could alternatively click the plus sign (+)
icon at the top of the Navigator as another way to import the package.
5. If you are importing a package, select an XML file in the package. If you are importing a
JAR or ZIP file, double-click on the file to explore into the file and find the package you
want to import; select an XML file from inside the package.
When you select one XML file, it finds the other XML files in the package and imports
them, too.
6. Click Open to import the package or JAR or ZIP file.
The dialog closes and the package containing the existing components is added to the
project. If components are added in read-only mode, when you open any of the
components in the wizards, you will notice that many of the entries are grayed and not
editable. Although the components themselves are not editable, they can be used as the
basis for customized components.
11-311
Related topics
About Importing Business Components
Ways to Import Existing Business Components
11-312
Working with Entity Objects, Associations, and
Database Tables
With Business Components for Java, the business logic tier represents your business entities,
and represents and interacts with a database, through these main components:
● entity objects
● associations
You can use wizards to generate them, and later customize the files that the wizards generate,
if needed. You implement most business logic using these components.
In the help contents, this book is divided into two main books:
● Understanding Entity Objects and Associations describes important concepts you must
understand before programming with entity objects and associations.
● Creating and Modifying Entity Objects and Associations describes tasks, including using
the wizards and editors, and programming with the API. See the Javadoc for more
information on the classes and methods provided by the framework.
Related topics
Ways to Customize the Business Components Framework
Ways to Customize Existing Business Component Programs
Developing Business Components for Foreign Datasources
Working with View Objects, View Links, Application Modules, and Clients
11-313
Understanding Entity Objects and Associations
Before working with entity objects and associations, you need to understand important
concepts about what they do and how you can use them. The following topics describe these
concepts:
What is an Entity Attribute?
Types of Business Logic
About Transactions
How Entity Objects Interact with the Database
How Entity Objects Interact with View Objects
About Entity Object Classes and Interfaces
About Entity Object and Association XML Metadata
About Business Component Properties
About Grouping Entity Objects and Associations in Packages
11-314
About Generating Entity Objects, Associations, and
Database Tables
You can either create database tables or business components first, and then automatically
create the other based on the definitions:
● reverse generation — You create the database tables first.
● forward generation — You create the business components first. You could use the
business components wizards and editors, or the Class Modeler.
You can use the Class Modeler to create business components. See Modeling Business
Components for more information.
11-315
With reverse generation, you first define your database tables (and perhaps views, synonyms,
and snapshots), and then use them to create entity objects and associations with one or more
of the following tools:
● Entity Object Wizard or Editor
● Business Components Project Wizard
● Package Wizard or Editor
Your team usually starts with a database design or UML diagram, and the database
administrator creates a table for each entity in the diagram. The table has columns
corresponding to the attributes of the entities, and has database constraints based on the
relationships between the entities. The tables are used to create the initial definitions of entity
objects and associations using the business components wizards. After, programmers
customize these business components to implement the application's business logic.
Business components wizards translate the database data types into the corresponding
business component data types, based on a type map. The type may be a Java type or a
domain. If the type map doesn't contain a mapping for a data type in your database, you should
create a domain for it before starting reverse generation. Otherwise, the column will be omitted
from the default entity object, and you will need to add it using the Entity Object Editor later.
Note that nested tables and varrays are mapped to oracle.jbo.domain.Array.
In the Project Wizard, you can specify a different type map than the default, which could be
your own custom type map, if needed.
The wizards also translate many database constraints into the business logic tier:
● Primary key constraints cause the primary key attribute setting to be set.
● Referential integrity constraints (foreign key constraints) become associations or

compositions.
● Check constraints are not translated into the business logic tier.
11-316
Related topics
About Forward Generation
11-317
With forward generation, database tables and database constraints are automatically created
based on business component definitions. The database administrator can then refine the
generated tables and database constraints as needed.
You usually follow these steps:
1. Typically, your design starts with a UML diagram.

2. You create custom domains for attribute data types that are not available in the
predefined business component data types.
3. Next, you define an entity object for each entity by using the Entity Object Wizard and
Editor.
4. You define associations and other constraints with the Association Wizard and Editor
and Entity Constraint Wizard.
5. After, you use these business components to create your database tables, and optionally
constraints, with the Create Database Objects Tool.
The tool first creates object types for the custom domains in your entity object definitions. Next,
it creates the tables.
Related topics
11-318
Types of Business Logic
Business logic includes
● business rules and policy — When adding or modifying data, you can ensure that the
data complies with your organizations' procedures before adding it to the database. For
example, you could increase the salary when an employee is promoted, give an
employee three weeks of vacation after they have been at a company three years, or
change the status of an order to shipped after all items in an order have been mailed to a
customer.
● validation logic — When adding new data, you can ensure that the data is valid before
storing it in the database. For example, you could ensure that a job code is a valid job
code.
● deletion logic — You can make sure that data is deleted only when appropriate and that
any dependencies are handled. For example, you could prevent an on-leave employee
from being removed. Another example is marking a row as deleted but never deleting the
row physically from the database by adding logic to the entity object's remove method.
● calculations — You can efficiently perform data calculations in the business logic tier. For
example, you could calculate an employee's monthly pay based on an hourly rate.
● default value logic — When creating new data, you can add appropriate default values.
For example, you could provide a default benefit plan based on an employee's job code.
● security — You can make sure that data is read and modified only by users with that
authority. For example, you could ensure that only the direct manager can change an
employee's salary.
You should implement business logic at the entity object level.
Some examples of business logic are tracking why a customer returned a product, or bidding
rules between potential suppliers to choose the best deal.
Related topics
11-319
11-320
What Is a Domain?
An entity or view attribute can have a domain as its data type, defining the type of values an
attribute can have. A domain object is a developer-defined data type, an immutable Java class
encapsulating a scalar value or a structure, with simple validation built into its constructor. The
validation check occurs when an object of that domain type is created. Business Components
for Java provides predefined domains, and you can create your own.
Some advantages of domains are:
● You can define custom data types to represent a database type that does not map to any
business component data type or to further restrict values, such as to certain strings.
● You can define attribute settings for a domain, and then share them with all attributes
that are based on the domain.
● Simple validations are performed once, against the domain definition, when the data is
created. Then, the data object can be passed between the tiers without the need for
reconstruction or revalidation.
Use domains to define custom data types and maps
Business Components for Java uses Java data types. Relational database tables use built-in
SQL types. The data types need to be mapped to each other so data can be passed back and
forth.
Business Components for Java can make many of the mappings to SQL data types for you,
either to a standard Java data type or to a predefined domain. For a list of supported mappings,
see Business Component Data Types. During reverse generation, the wizard automatically
assigns the default business component data types, which you can change, if needed. During
forward generation, you use a wizard or editor to assign both the Java data type and the SQL
data type (an appropriate default is provided), and later automatically create the tables
containing the SQL data types.
If you have a data type that is not automatically mapped, such as some Oracle Object Types,
you need to create a domain for it before you start reverse or forward generation.
Domain classes extend or encapsulate Oracle SQL data types. Domain objects can be
converted to the standard JDBC data types.
11-321
Tools help you create and use domains
JDeveloper provides a Domain Wizard and Editor for defining domains. It helps you specify a
domain name, package, attribute settings, and properties, if used. After, you can add custom
validation and formatting code, if needed. For example, you could create a domain named
SSNumber, and write validation code for it that ensures that the resulting data type is a string of
nine characters.
After you have created a domain object, you can use the Entity Object Wizard or Editor, View
Object Wizard or Editor, or Attribute Editor to assign the domain to an attribute as its data type.
Attributes inherit domain attribute settings
In the Domain Wizard and Editor, you can specify attribute settings so that all attributes of that
domain type inherit those settings. Attributes may further restrict domain settings, but may not
make them less restrictive. For example, a domain could be marked Persistent, meaning no
transient attribute can be of that domain type.
Domains can exist in the business logic tier or client
You can use a domain class on the thin client as well as the business logic tier to hold values of
a specific type, such as a social security number. You can write code to format or validate the
input string in the domain's validate method, which is called by all constructors. Domain classes
can be associated fields in a form. The form could directly instantiate an instance of the domain
class with the field's given input string.
An example
Suppose you define a Salary domain and specify minimum and maximum values. Then, when
program code creates a Salary object, the validation check ensures that the salary amount is
within the range you specified.
public void createSalary (Number amount) {

try {
// Assume MySalaryDomain is a domain defined elsewhere.
MySalaryDomain salDom = new MySalaryDomain(amount);
// Salary amount is OK. Continue.

...
11-322
} catch (DataCreationException dce) {
// Salary amount is invalid.
...
}
}
Related topics
Creating a Domain
Editing a Domain
Files that Define a Domain
11-323
About Inheriting and Overriding Domain Attribute
Settings
In the Domain Wizard and Editor, you can specify attribute settings so that all attributes of that
domain type inherit those settings. Attributes may further restrict domain settings, but may not
make them less restrictive. For example, a domain could be marked Persistent, meaning no
transient attribute can be of that domain type.
The following table lists what settings you can override in an attribute when you choose a
domain as a data type, and the domain has specified a setting. Note that at the view level,
persistent and entity-derived attributes inherit settings from the entity level.
Attribute Setting Persistent Transient Attribute Transient Attribute SQL-Derived

Attribute (entity level) (view level) Attribute
(entity level) (view level)
Attribute Type Choose the domain. Choose the domain. Choose the domain. Choose the domain.
Default Value The default value is The default value is N/A N/A
inherited and cannot inherited and cannot
be changed. be changed.
Primary Key If selected in If selected in N/A N/A
domain, cannot be domain, cannot be
changed. changed.
Mandatory If selected in If selected in N/A N/A
domain, cannot be domain, cannot be
changed. changed.
Persistent If specified in If specified in N/A N/A
domain, must be domain, must be
selected. deselected.
Updateable If selected in If selected in If selected in If selected in domain,
domain, the domain, the domain, the the updateability can
updateability can be updateability can be updateability can be be restricted further.
restricted further. restricted further. restricted further.
Refresh After If selected in N/A N/A N/A
domain, cannot be
changed.
Column Type The domain data N/A N/A N/A
type must map to
the table data type.
11-324
Queriable If selected in N/A N/A If selected in domain,
domain, cannot be can be changed.
changed.
Unique If selected in N/A N/A N/A
domain, cannot be
changed.
11-325
A Java file and an XML file define a domain:
● The Java file implements oracle.jbo.domain.DomainInterface. You can add validation

logic to its validate method. See the Javadoc for more information.
● The XML file contains the attribute settings. It can also contain custom properties that you
added to the domain through the Domain Wizard.
A domain represents the type of values an attribute can have. Domain validations are
performed once, against the domain definition, when the data is created. The data object can
then be passed between the tiers without the need for reconstruction or revalidation. You can
also define properties and then share them with all attributes which are based on a given
domain.
Entity object and view attributes can be declared to be of a domain type. In the JDeveloper
wizards, various settings can be established on a domain so that all attributes of that domain
type inherit those settings. For example, a domain could be marked Persistent, meaning no
transient attribute within the framework can be of that domain type. These attributes may
further restrict those settings, but may not make them less restrictive.
Domains are always serializable Java objects. In the framework, it is recommended that
domains have a constructor that can accept at least one of the native Java types, like String,
byte[], Integer, and so on.
A domain can be one of two types, immutable or mutable. You select this type on the Domain
Wizard's Name page.
Immutable Domains
Immutable domains are simple Java datatypes encapsulating a scalar value, and with simple
validation built into the constructor of the domain. Domain values are validated immediately
upon construction and then serialized across tiers without further duplicate validations. For
example, a SocialSecurityNumber domain object could immediately validate that a given
string is a valid SSN on a particular client. The value is then carried over to the business logic
tier without reconstruction or revalidation by the framework. If the attribute type is String
instead, on every setter method for a SSN, the incoming string has to be validated for the
proper format and number validity.
11-326
Mutable Domains
Oracle Object Types are mutable. However, their changed status is not maintained by the
business components framework. The changed domain must be set to a Row Object using
setAttribute() or a variable method for the change to be reflected in the database.
Related topics
What Is a Domain?
Creating a Domain
Editing a Domain
11-327
About the Predefined Validation Rule Classes
The Business Components for Java framework provides the following predefined validation rule
classes that you can use when applying validation rules to entity objects and entity attributes:
● CompareValidator
● ListValidator
● RangeValidator
● MethodValidator
● UniquePKValidator
You can also create your own custom validation rule classes.
Related topics
Adding and Editing a Validation Rule
11-328
About CompareValidator
The CompareValidator performs a logical comparison between an attribute value and another
value. The supported operators are:
● EQUALS
● NOT EQUALS
● GREATER THAN
● GREATER OR EQUAL TO
● LESS THAN
● LESS OR EQUAL TO
The other value can be either a literal value, the results of a SQL query, or the results of a view
object query:
Type Description
Literal value The list is created by providing one or more literal values to compare.
The list is created by executing a SQL query using a custom view object. The values
are defined by the first column returned by the query. In both ListValidator and
CompareValidator, attributes from the entity object being validated can be used
Query result
as bind variables, for example, SELECT UNIQUE loc FROM dept WHERE loc =
%Loc%, where Loc is an attribute on the entity object being validated and thus has a
method getLoc defined on it.
The list is created by executing the query for a predefined view object. Choose the
View object attribute
view object from the tree structure.
11-329
11-330
About ListValidator
The ListValidator validation rule determines whether an attribute value is in a given list of
values. The list can be either a list of literal values, the results of a SQL query, or the results of
a view object query.
The method validateValue gets the list either by executing a SQL query or by executing a
view object query, and then searches the list for the value. If the value is found,
validateValue returns true.
The supported operators are:
● In
● Not In
The following table describes the ways that the list can be created:
Type Description
Literal value The list is created by providing one or more literal values to compare.
The list is created by executing a SQL query using a custom view object. The values
are defined by the first column returned by the query. In both ListValidator and
CompareValidator, attributes from the entity object being validated can be used
Query result
as bind variables, for example, SELECT UNIQUE loc FROM dept WHERE loc =
%Loc%, where Loc is an attribute on the entity object being validated and thus has a
method getLoc defined on it.
The list is created by executing the query for a predefined view object. Choose the
View object attribute
view object from the tree structure.
11-331
About RangeValidator
The RangeValidator tests for attribute values within specified minimum and maximum values
(inclusive). The range values are set in the constructor or by using set methods. The
validateValue method performs the actual comparisons and returns true on success.
The supported operators are:
● BETWEEN
● NOT BETWEEN
11-332
About MethodValidator
A method validator invokes a custom, or "user-defined", method.
11-333
How Entity Objects Are Validated When an Attribute
Is Set
Business component validation follows the JavaBeans PropertyChange mechanism. A
change to an attribute leads to a VetoableChange event notification followed by
PropertyChange notification. A PropertyChangeEvent object is passed along with the
event containing the entity object reference to which the attribute belongs and the new value to
be set for the attribute that is being validated. The validators implement
VetoableChangeListener events and attach themselves to the listeners list in the attribute
descriptors and hence get notified of the changes to an attribute. When a setCurrentRow
call changes the current row in a view object, the Business Components for Java framework
invokes entity object validation.
To validate an entity object, a validator object is created and attached to the entity object as a
VetoableChangeListener. When the entity object's validate method is called, the
listeners are activated, which in turn perform their validate methods and throw
VetoableChangeException in case of failures.
An entity object has one public validate method that is called both at change of row currency
and commit time. The logic of the validate method is:
1. Call validateEntity. You can override this method, but you should call
super.validate before your own code to invoke the framework's validation
mechanism. Note that Entity.validate() is not overridable (is final).
2. For a composition, validateEntity calls validateChildren on the entity object.

The entity object traverses each of its ownership associations where it is the source
entity object, and examines the entity object on the destination end. If the destination
entity object is marked invalid, the traversing entity object calls the validate method on
it.
3. Perform validations on declarative rules attached to this entity object.
4. Call setValidated(true) to reset the invalid flag and/or remove the entity object from
its owner's list of invalid entities. If the entity object is a top-level entity object, then
remove it from the transaction's list of invalid entity objects.
11-334
The following figure is a high-level illustration of the sequence of events and method calls that
executes when an attribute value is set in the business logic tier.
The next figure illustrates what happens if the entity object is part of a composition relationship.
In this case, the framework tries to lock the topmost entity object.
11-335
11-336
About Transactions
A transaction is an interface to manage database operations. All operations to modify data in a
transaction must succeed before the server will accept the changes. These operations include
methods that set attribute values, standard SQL calls (such as INSERT, UPDATE and
DELETE), or more specialized RPC-like calls such as calling Java stored procedures or
PL/SQL packages. A transaction is an atomic unit; the effects of the operations in a transaction
can be either all committed (saved to the database) or all rolled back (undone).
For example, when a client using a banking service transfers money from a savings account to
a checking account, the transaction consists of three separate operations: decrement the
savings account, increment the checking account, and record the transaction in a transaction
journal. If all three operations are performed to maintain the accounts in proper balance, the
transaction is committed and the effects of the operations applied to the database. But, if
something (such as insufficient funds, invalid account number, or a hardware failure) prevents
any of the operations from completing, the entire transaction must be rolled back so that the
balance of all accounts is correct.
Transactions also provide multi-user consistency to a shared store of data. When a client
changes data, locks ensure that other clients don't make other changes until the first client is
finished. When a transaction is committed or rolled back, the locks are released. This is a
"pessimistic" locking mode, which the Business Components for Java framework assumes by
default.
Application modules provide default transaction and concurrency support. No coding is required
unless you want to customize the default behavior.
When programming with Business Components for Java, the principles of transaction
management are the same from the business logic tier as from a client:
1. Create an application module that connects to the database and establishes a context for
the transaction.
2. Execute a query.
3. Manipulate the result set (set attributes, validate values).
4. Commit changes to the database (making the new data available to other application
modules) or roll them back, as appropriate.
11-337
The Business Component for Java framework uses a batch-oriented (as opposed to a change-
oriented) approach to synchronize changes in any cached state with the database state. This
approach provides the following benefits:
● Changes are buffered in an in-memory cache.
● Changes in the cache are synchronized with the database using a series of database
manipulation operations. This series of operations is typically referred to as posting. (In
Business Components for Java, posting is performed in the commit cycle; or by
specifically calling postChanges() on the Transaction interface.)
● Validations occur on some combination of each state change made and just prior to
posting because individual changes may have left the cache in an invalid database state.
Locking Mode
Use one of the following constants to represent the locking mode:
● ApplicationModule.LOCK_NONE
● ApplicationModule.LOCK_OPTIMISTIC
● ApplicationModule.LOCK_PESSIMISTIC (default)
11-338
About Commit Cycle Processing
A business logic tier service commits a transaction by using an application module. The
following flowchart illustrates the process for the commit cycle.
Figure 1: Flowchart for Commit Cycle Processing
11-339
1. Validate entity objects.
The Business Components for Java framework walks through the transaction's list and
validates the entity objects needing validation. The validation step is performed 10 times
(this number can be altered by calling DBTransaction.setValidationThreshold()). If the
final attempt at validation fails, the framework throws a JboException and exits.
Note: Looping gives application developers a chance to set attribute values based on
validation logic, then validate these new updates.
The framework then calls postChanges() on all TransactionPostListeners. If you have

overriden postChanges() in an entity object, the method will be called at this stage.
2. Post entity objects.
The business components framework posts changes to the database, then calls
beforeCommit() on all TransactionListeners.
The framework performs one final validation on any modified entity objects. If any
component is invalidated the framework throws an exception, restores the database to
the state it was in before the commit cycle started, and exits. New changes are not
allowed at this point in the commit cycle; any changes are made after this commit cycle
is complete, during afterCommit().
3. Commit changes.
The framework invokes database commit to commit the transaction, then calls
afterCommit() on all TransactionListeners.
If a JboException is thrown during the commit stage, the framework restores the
database to the state it was in before the commit cycle started, throws a new
JboException, and exits. However, after the commit is completed in the database, the
framework does not attempt to restore the cached state (for any exception thrown in the
afterCommit methods).
Note: During the commit cycle, the framework ensures that a listener's method (for
example, a particular TransactionListener's beforeCommit() method) is invoked only
once.
11-340
About Rollback Cycle Processing
The Business Components for Java framework processes a rollback with the following steps:
1. Calls beforeRollback() on all TransactionListeners.
2. Invokes a database rollback.
3. Calls afterRollback() on all TransactionListeners.
If exceptions are thrown from beforeRollback() methods, they're thrown to the caller. If rollback
throws an exception from the database, it's turned into a JboException and thrown. If
afterRollback() calls throw exceptions, they're caught and thrown as an AfterRollbackException
that contains the exceptions thrown in afterRollback() calls.
Note: During the rollback cycle, the framework ensures that each TransactionListener's
beforeRollback() and afterRollback() methods are invoked only once.
11-341
About Application Modules and Transactions
Client applications connect to databases and manage transactions by using the
oracle.jbo.Transaction interface. Some useful methods of the Transaction interface with
regard to application modules are:
● commit - Commit the transaction; saves all changes to the database. If the database
connection is established, the transaction is implicitly started.
● connect - Attempt to establish a connection to the given database URL.
● disconnect - Disconnect the server from the database.
● getLockingMode - Get the preferred locking mode for this transaction. Currently the
locking mode defaults to LOCK_PESSIMISTIC.
● rollback - Rollback the transaction; discard all changes.
● setLockingMode - Set the preferred locking mode for this transaction. Changing the
locking mode affects only subsequent locks that are placed.
A client can use an application module provided by a business logic tier component, or it can use
the default application module provided by the Business Components for Java framework. When
connected to a database, an application module defines a transaction boundary. When an
application module commits changes to the database, it makes the updated data available to other
application modules. The following figure shows two application modules: AppMod 1 and AppMod
2. In AppMod 1, DeptEmpView and EmpView provide access to the DEPT and EMP tables by
using entity objects. AppMod 2 also uses EmpView. However, when data is changed in one
application module, the changes are not available to the other application module until the
transaction is committed. For example, if EmpView in AppMod 1 updates EMP but does not
commit the changes, DeptEmpView can access the new data, but EmpView in AppMod 2 cannot.
11-342
If a business logic tier component does not include a custom application module, a client
application must use the generic application module provided by the Business Components for
Java framework to get the transaction for connecting to the database and starting a transaction.
The following code example shows how an application module provides a context for transactions.
The code assumes that an application module represented by the variable appMod has been
declared and initialized elsewhere, and the transaction is started using the connect() method. It
also assumes that a method named updateAttr has been implemented to update a row of a
view object vo with the value newAttrVal. If updateAttr succeeds (returns true), the code
commits the transaction; otherwise, it rolls the transaction back.
// Assume that appMod has been declared and initialized elsewhere.
try {
if (updateAttr(vo, newAttrVal)) {
// Commit changes to the database, making
// updated data available to other application modules.
appMod.getTransaction().commit();
System.out.println("\n Transaction committed. \n");
}
else {
11-343
appMod.getTransaction().rollback();
System.out.println("\n Transaction rolled back. \n");
}
}
Application modules can be nested. That is, an application module can (logically) contain one or
more other application modules as well as view objects. When application modules are nested, the
outer-most (top-level) application module provides the transaction context for the others. The
following figure shows two examples. In the first example, amTwo contains amThree, but it does
not provide its transaction context because amOne is the outer-most application module. In the
second example, the generic application module is outer-most, so it provides the transaction
context for amFour.
The top-level application module defines a transaction context for groups of related queries and
supports combining data changes from independent forms into the same transaction. By sharing
an application module, forms can participate in the same transaction, and they can pass view
objects from the shared application module.
Data changes, such as inserts and deletes, are immediately detected by other application modules
in the same transaction. Likewise, changes to attributes are detected by view objects immediately.
An entity object represents a database object. It caches data and provides mapping to an
underlying database object. The transaction manages the cache and synchronizes data with one
database. Entity objects are not directly exposed to the client tier. Instead, clients access an entity
object's data through a view object in an application module. All view objects within the transaction
share the same entity caches. view objects and entity objects communicate through events and/or
Java calls (not by using remote interface proxies).
11-344
A view object, expressed as a query on top of underlying entity objects, shapes the result set for
presentation. Because data is cached at the entity object level and all view object references
within the same transaction share the entity objects, changes made through one view object are
immediately available through other view objects in the same transaction.
The following code example shows the interaction between application modules, view objects, and
the database as values are changed, posted, and committed.
package amdemo;
import java.util.Hashtable;
import javax.naming.*;
public class TestAm {

final String amName1 = "am1.AppMod1";
final String amName2 = "am2.AppMod2";
final String voName1 = "am1.DeptView1";
final String connStr = "jdbc:oracle:thin:scott/tiger@jtora815:1521:ORCL";
// Set environment for local deployment.

Hashtable env = new Hashtable(2);
env.put(Context.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);
ApplicationModule appMod1 = null;

ApplicationModule appMod2 = null;
try {
javax.naming.Context ic = new InitialContext(env);
ApplicationModuleHome home1 =
(ApplicationModuleHome)ic.lookup(amName1);
appMod1 = home1.create();
appMod1.getTransaction().connect(connStr);
ApplicationModuleHome home2 =
(ApplicationModuleHome)ic.lookup(amName2);
appMod2 = home2.create();
appMod2.getTransaction().connect(connStr);
11-345
} catch(Exception e){
}
ViewObject vo1 = appMod1.createViewObject("vo1", voName1);

//ViewObject vo4 = appMod2.createViewObject("vo4", voName4);
Row r1 = vo1.first();
r1.setAttribute("Loc", "asdf");
System.out.println("vo1 before AppMod1 post " + r1.getAttribute("Loc"));
vo3.executeQuery();
//Row r4 = vo4.first();
//System.out.println("vo4 before AppMod1 post " + r4.getAttribute("Loc"));
appMod1.getTransaction().postChanges();
System.out.println("vo1 after AppMod1 post " + r1.getAttribute("Loc"));
r2 = vo2.first();
r3 = vo3.first();
//r4 = vo4.first();
//System.out.println("vo4 after AppMod1 post " + r4.getAttribute("Loc"));
try {
appMod1.getTransaction().commit();
System.out.println("Commit succeeded.");
} catch (oracle.jbo.JboException e) {
System.out.println("Commit failed. " + e);
}
System.out.println("vo1 after AppMod1 commit " + r1.getAttribute("Loc"));

r2 = vo2.first();
vo3.executeQuery();
r3 = vo3.first();
//r4 = vo4.first();
//System.out.println("vo4 after AppMod1 commit " + r4.getAttribute("Loc"));
11-346
// Keep the console window open so you can see what happened.
System.out.println("\n Press Enter to close this window.");
try { System.in.read(); } catch (Exception e) {}
}
}
11-347
About Transactions and Locks
A multi-user application must control concurrency, the simultaneous access of the same data
by many users. Otherwise, data could be updated or changed improperly. Concurrency control
is managed through the Transaction interface. This topic describes how transactions fulfill
the following important requirements of an information management system:
● Data must be read and modified in a consistent fashion.
● Data concurrency of a multi-user system must be maximized.
● High performance is required for maximum productivity from clients.
Transactions use locks to control concurrent access to data, achieving two important database
goals:
● Consistency ensures that the data you are viewing or changing is not changed by other
users until you are finished with the data.
● Integrity ensures that the database data and structures reflect all changes made to them
in the correct sequence.
The Business Components for Java framework supports a locking model that provides the
following features and benefits:
● A lock is placed even if inconsistency is detected.
● It can determine that inconsistency is due to DELETE or UPDATE of data.
● It supports business logic tier server comparison of original data columns.
● Data is retrieved to correct inconsistencies when they occur, with no further roundtrips
required.
Using the Business Components for Java framework, you can request locks on rows in entity
objects or view objects. Locking an entity 0bject row places a database lock on that row. When
11-348
locking a view object's row, the framework requests locks on those Entity rows that are used in
the view object's row.
Business Components for Java supports the locking styles listed in the table below. Each style
represents a trade-off between scalability, performance, and consistency of data. For example,
placing database locks early (pessimistic locking) reduces scalability but decreases the
likelihood of data inconsistencies. When you change the locking style, the change only affects
subsequent locks. Locks already in place do not change.
Locking Style Description

Pessimistic Locking Locks are automatically placed upon the underlying row immediately before the first
client change is made. This is the default style for application
modules. Represented by the constant Transaction.LOCK_PESSIMISTIC.
Optimistic Locking Locks are automatically placed upon the underlying row during the "save to
database" logic. Represented by the constant Transaction.LOCK_OPTIMISTIC.
Explicit Locking Locks are manually placed, at the correct point in time, by explicit calls from the
client. If no lock calls occur, then only the database locks, obtained when the rows
are flushed to the server, are obtained. Represented by the constant
Transaction.LOCK_NONE.
The following code example demonstrates pessimistic locking mode:
if ( myEntity.getPostState() != Entity.STATUS_NEW
&& myEntity.getDBTransaction().getLockingMode()
== Transaction.LOCK_PESSIMISTIC
&& !myEntity.isLocked() )
{
myEntity.lock();
}
return myEntity;
About Lock Failure
Locks may fail for any of the following reasons:
● The resource is held by another user.
● The resource has been deleted from the Database.
● The resource changed since the entity cache was populated.
11-349
● Some general SQL error condition (such as the database going down).
In each case, a different type of error is raised to indicate the problem. This permits higher level
callers to indicate the error in question, and potentially retry the operation.
Releasing Locks
After a lock is placed on a given object, it is added to the list of Transaction participants. After
the Transaction performs a commit or rollback operation, each Transaction participant is
notified of the outcome of the operation. Each object is given an opportunity to release any
internal state, such as lock indicator flags, that it may hold during this notification cycle.
About Low-level Locking
Independent of the locking style selected, the low-level APIs permit the explicit locking of
View/Entity Rows by calling their lock method at the appropriate time.
After the initial lock call for a given row object, subsequent calls are ignored unless the
corresponding database transaction has had the commit or rollback operation performed,
because locks are automatically released at these times.
The call to place a lock can fail for a number of reasons:
● Resource held by another user.
● Resource deleted from the database.
● Resource changed since the entity cache was populated.
● General SQL Error condition (such as the database going down).
In each case, an exception is thrown to indicate that a problem occurred. These exceptions can
also occur at other times, such as changing the value of a column, because locks can be
placed implicitly at that time.
An Entity Row provides a method for testing the locked status, as follows:
11-350
/**
* Is the Row locked?
**/
public boolean isLocked()
11-351
How Entity Objects Interact with View Objects
Entity objects are not directly exposed to the client tier. Instead, clients access data through
view objects: clients use view objects to get and set attribute values, and changes are made
to the data in the underlying database when the transaction is committed. Entity objects and
view objects communicate directly by using events and Java calls (not by using remote
interface proxies).
Related topics
11-352
Entity Object States and Events
The Business Components for Java framework follows the standard Java event delegation
model for propagating events among business logic tier objects. Publishers (also called
senders) fire events, subscribers (also called listeners) respond to them.
Java event types are classes that extend java.util.EventObject. The framework sends
an event from a publisher to a subscriber by invoking a method of the RowSetListener
interface on the subscriber and passing in an instance of the event type generated. The
subscriber registers listeners by using addEventTypeListener() on the publisher.
The publisher defines the set of events it emits by providing addEventTypeListener methods
which register specific listeners for those events.
A subscriber implements a specific EventListener interface, RowSetListener, that

extends java.util.EventListener. An EventListener interface defines one or more
methods to invoke in response to each specific event type handled by the interface.
The following Business Components for Java classes for built-in events can be found in the
oracle.jbo package. They can be published by various business components and are used
to manage three-tier communications.
11-353
Entity Object Exceptions
The Business Components for Java framework follows the Java platform model for conveying
information about run-time errors, so a method can return a result code (also called an error
code), throw an exception, or both. Following are some recommendations.
● Use exceptions for serious or unexpected error conditions, use result codes for simple
warnings. In general, exceptions are more expensive than result codes: they use more
system resources and take longer to process.
● Use an 80/20 rule. If the calling routine is likely to be aware of the condition (for example,
end-of-list) roughly 80 percent of the time, return a result code. If callers are likely to be
aware 20 percent of the time, throw an exception.
● If stack unwinding will be a serious chore, throw an exception.
The following topics describe how to write error-handling routines:
● Programming with Result Codes
● Programming with Exceptions
● Error-handling Approaches for Clients
11-354
About the EntityDefImpl Class
It is a class extending directly or indirectly from oracle.jbo.server.EntityDefImpl. It represents
the runtime metadata describing the entity object, including attributes, events, validators,
associations, and properties. When instantiated, it describes all instances of the entity object
class. A client can call methods to find information about the entity object, such as the attribute
names and types, database source, and so on. There is one entity definition class instance per
entity XML file. The entity definition class is a singleton class at runtime.
You can use the Entity Object Wizard and Editor to generate this Java class for an entity object
when you need custom create and find methods. This class is a good place to group together
methods that are used by all entity object instances. For example, you can optionally modify the
createDef method to use properties from another source (in addition to or instead of the XML)
when the entity definition is instantiated.
You might also create this class if you want to provide custom properties to the entity definition
and entity attribute definitions at runtime through the APIs.
If an entity object publishes or subscribes to an event (as specified in the Publish and
Subscribe pages of the Entity Object Wizard and Editor), most of the event code is generated in
the definition files of the entity objects that publish and subscribe.
You can specify that this class extend from a custom class (which must directly or indirectly
extend the EntityDefImpl class and be in the project classpath); for example, you might do this
if you want to reuse code that's already been written or if your organization decides to
customize the business components framework to meet specific needs.
11-355
About the EntityImpl Class
It is a class directly or indirectly extending from oracle.jbo.server.EntityImpl. When it is
instantiated, it represents one row of data. You can use the Business Components Project
Wizard, Package Wizard or Editor, or Entity Object Wizard or Editor to generate this Java class
for an entity object if you want to customize methods, such as add custom validation logic code
to the validateEntity method or attribute setter methods, or calculate attribute values in the
getter methods. You can specify that this class extend from a custom class (which must directly
or indirectly extend the EntityImpl class and be in the project classpath); for example, you might
do this if you want to reuse code that's already been written or if your organization decides to
customize the business components framework to meet specific needs. In the wizard, you can
optionally generate
● accessor methods (for example, getJob and setJob), which provide type-safe access to
the corresponding attribute fields and a place to add your own custom code for
validation.
● data manipulation methods, including lock, which you can modify to customize the entity
object's locking behavior, and doDML, which you can modify to customize its update,
insert, and delete logic. The lock method is called by the framework whenever an entity's
row in the database is locked for modifications. The doDML method is called by the
framework with appropriate DML command, to insert, update or delete the row
corresponding to the entity instance during the Transaction-Commit cycle. This method
can be overridden to modify the update behavior. For example, instead of directly
updating through a SQL statement as the framework does, update through a procedure
call to the database.
● create method, which you can modify to customize or add additional initialization features
to the entity object's create logic, for example, setting default values for attributes
● remove method, which you can modify to customize or add clean-up code to the entity
object's remove logic, for example, you might need to delete child objects in a
composition
11-356
In a business components project, properties are name/value pairs of type String that you can
use as application-specific metadata to drive runtime behavior. (Do not confuse them with
JavaBean properties: they're different.) Domains, entity objects, view objects, application modules,
and entity and view attributes can have properties. The properties are stored in the component's
XML file.
You can define any properties you need in the appropriate Properties page of a wizard or
editor, such as the Entity Object Wizard and Attribute Editor. You can also work with properties in
the Control Hints page.
For example, an attribute could have a Label property that specifies what the label should be
when the attribute is displayed in the UI. Another example is when you are laying out a
presentation space and want to use a mask (or picture string). To define properties for a string
that represents a social security number, you could create a SSN-MASK property with a value
of 000-00-0000. At runtime, your code can evaluate the property name and apply the proper
formatting when appropriate. This lets you write code whose behavior is driven by the values of
the properties. You could also store information about user types and what they are allowed to
do in the application.
Your custom attribute and domain properties can be overridden in an inheritance hierarchy,
from top to bottom:
● domain property
● entity attribute property
● view attribute property
For example, a domain attribute could have a UIHint property value of TextField. An entity
attribute of that domain type could override the UIHint property value to be TextArea. A view
attribute that inherits from that entity attribute could override the UIHint property value to be
ComboBox. If you don't override the property value, it inherits the value according to the
inheritance hierarchy.
You can get and set properties at runtime by calling these methods: getProperty, setProperty,
getProperties, getPropertiesAsStrings, and refreshProperty. You can call these methods on the
EntityDefImpl, ViewObjectImpl, ApplicationModuleDefImpl, and AttributeDefImpl classes.
11-357
Clients can query properties and make decisions based on property values, but can't set
properties.
In summary, in addition to the predefined XML properties, custom business component

properties let you store and modify any XML metadata you need for any of your application
modules, entity objects, view objects, attributes, or domains.
Related topics
Defining User Interface Control Hints
Using XML Metadata Properties that Affect XML Generation
11-358
Creating and Modifying Entity Objects and
Associations
The following topics describe how to create and modify entity objects and associations:
● Preparing for Reverse Generation
● Preparing for Forward Generation
● Ways to Create Entity Objects and Associations
● Ways to Edit Entity Objects and Associations
● Forward Generating Database Tables and Referential Integrity Constraints
● Ways to Add Validation Logic
● Working with Custom Properties
● Ways to Handle Errors
● Using the API to Customize Entity Objects and Associations
11-359
Preparing for Reverse Generation
Before performing reverse generation, you usually perform the following tasks:
1. Define your database tables (and views, synonyms, and snapshots) based on your
business requirements. If you have existing legacy tables, you may want to structure
them so there is one entity per table, if possible.
2. Decide if you will create default entity objects and associations, define them individually,
or a combination of the two. Create custom domains, if needed.
Because the database data types are in SQL and the business logic tier types are in
Java, Business Components for Java needs to translate between the two:
❍ If you let a wizard generate default entity objects, it uses the predefined data type
mappings. For Oracle Object Types and types that do not have predefined
mappings, it attempts to create a domain for the type. You can change the data
type after reverse generation, if needed.
❍ If you create an entity object by using the Entity Object Wizard, you can specify
what data types and domains to map to your database columns before reverse
generation. You can optionally create custom domains for certain column types.
Note: You can also reverse-engineer table definitions to entity objects on UML class diagrams in
JDeveloper. For more information, see Modeling Business Components.
After completing these steps, you are ready to create entity objects and associations from the
tables.
You can optionally effect the behavior of many business components by customizing
framework base classes, which you might want to start before generating business
components.
Related topics
Using a Domain as a Data Type for an Attribute
11-360
Creating a Domain
Editing a Domain
Coordinating Entity Objects and Database Triggers
11-361
Because the database data types are in SQL and the business logic tier types are in Java,
Business Components for Java needs to translate between the two.
For reverse generation:
● If you let a wizard generate default entity objects, it uses the predefined data type
mappings. For Oracle Object Types and types that do not have predefined mappings, it
attempts to create a domain for the type. You can change the data type after reverse
generation, if needed.
● If you create an entity object by using the Entity Object Wizard, you can specify which
data types and domains to map to your database columns before reverse generation.
You can optionally create custom domains for certain column types.
For forward generation, you create an entity object for each entity by using the Entity Object
Wizard and Editor, which includes specifying data types for each attribute. You need to create
custom domains for attribute data types that are not available in the predefined business
component data types. You use these entity objects to create your database tables with the
Create Database Objects Tool.
To assign a domain as the data type of an attribute:
1. If an appropriate domain does not already exist, create a domain.
2. In the Entity Object Wizard or Editor, assign the domain as a data type for an attribute.
Related topics
Creating a Domain
Editing a Domain
11-362
11-363
Coordinating Entity Objects and Database Triggers
In some cases, you may want to coordinate the business logic tier with database triggers. For
example, you can use database triggers to create default values when a row is inserted and
bring the value back to the business logic tier using the Refresh After Insert attribute setting
(however, you don't see the default until the row is committed).
11-364
Preparing for Forward Generation
Before performing forward generation, you usually perform the following tasks:
1. Determine if the predefined business component data types meet your needs.
2. Create custom domains for additional attribute data types you need.
3. Define an entity object for each entity by using the Entity Object Wizard and Editor.
Define associations and other constraints with the Association Wizard and Editor and
Entity Constraint Wizard.
Note: You can also model business components on UML class diagrams in JDeveloper. For more
information, see Modeling Business Components.
After, you use these business components to create your database tables, and optionally
constraints, with the Create Database Objects Tool.
You can optionally effect the behavior of many business components by customizing
framework base classes, which you might want to start before creating business components.
Related topics
Creating a Domain
Editing a Domain
11-365
Business Components for Java provides several tools that let you create entity objects and
associations. The entity objects can be based on existing tables (reverse generation) or be used
to create database tables (forward generation).
● Creating Default Entity Objects and Associations from a Database — You can create
default entity objects, based on existing database tables, in the Business Components
Project Wizard and Package Wizard or Editor.
● Creating an Entity Object — You can create an entity object in the Entity Object Wizard.
How you define the entity object depends on whether you are using reverse or forward
generation. You must use this wizard if you want to specify a particular entity object
name or entity object to extend.
● Creating an Association or Composition — You can create an association or composition

in the Association Wizard. You must use this wizard if you want to specify a particular
association name or association to extend.
● Creating business components from a UML model — You can model them on a UML
class diagram in JDeveloper.
After creating an entity object, you can edit it in the Entity Object Editor and customize its Java
source files. You can customize an association in the Association Editor.
Related Topics
11-366
Creating Default Entity Objects and Associations
from a Database
Business Components for Java can automatically generate entity objects and associations from
some or all of your database tables when you use these wizards:
● Package Wizard
When you let a wizard generate default entity objects, it uses the predefined data type
mappings. For Oracle Object Types and types that do not have predefined mappings, it
attempts to create a domain for the type. You can change the data type after reverse
generation, if needed.
Before generating default business components, you can specify that the wizards use
customized framework base classes, if needed.
In addition, there are a few other ways to create associations from database constraints.
Related topics

11-367
11-368
The Entity Object Wizard lets you create an entity object at design time. The entity object can be
based on an existing table (reverse generation) or be used to create a database table (forward
generation).
Alternatively, you can create default entity objects, based on existing database tables, in the
Business Components Project Wizard and Package Wizard or Editor. These entity objects are a
good start, but you'll probably want to edit them in the Entity Object Editor so they're
customized for your application.
To create an entity object with the Entity Object Wizard:
1. While the business components project is open, either:
● Choose File | New, click Business Components, and double-click Entity Object.
● In the Navigator, right-click the business components package and choose New
Entity Object.
The Entity Object Wizard appears.
3. In the Name page, specify the name and package and optionally the table of the entity
object. Then click Next.
4. In the Attributes page, specify entity attributes. Then click Next.
For reverse generation, remove attributes you want to exclude and define new attributes
that are not based on a table. For forward generation, define attributes and change the
attribute order (which is the order of the columns in the table).
5. In the Attributes Settings page, specify settings for each attribute. Then click Next.
In general, if you are performing reverse generation, you don't want to change the
primary key, mandatory, database column name, column type, and unique settings that
11-369
were received from the table. For forward generation, the primary key, mandatory,
persistent, database column name, column type, and unique settings are used to
generate tables.
6. In the Java page, specify which Java source files and methods you want to generate, if
any. Then click Next.
You want to generate source files if you need to customize Java code.
7. In the Finish page, optionally create a default view object containing the attributes you
specified in the entity object. Then click Finish to generate the entity object.
You can edit the entity object in the Entity Object Editor. If you created a default view
object, you can edit it in the View Object Editor.
Related topics
Creating an Entity Object for a Table with No Primary Key
11-370
Specifying the Name, Package, and Table of an
Entity Object
Entity Object Editor, you specify the following information in the Name page. How you use this
page depends on whether you are performing reverse or forward generation, or extending an
existing entity object.
Field descriptions
Field Description
Name Type the name of the entity object, which can be the same as a table name,
or different if, for example, the table name doesn't adequately reflect what
you're using the entity object for or you want to use a different language.
Note that you must not use the name Entity.
To use a default name based on the table, first select an object in the
Schema Object list.
Package Type the package the entity object should be placed in. Click Browse to
select an existing package.
Extends Entity (Optional) Type the name of an existing entity object you want to extend.
Click Browse to select it from a dialog. (The entity object must extend
directly or indirectly from oracle.jbo.server.EntityImpl.) This is a useful
feature if you want to provide additional functionality or extend a previously
created entity object that you don't have the source for. See Extending an
Existing Entity Object.
Database Objects For reverse generation, specify the database table (or view, synonym, or
snapshot) used to create an entity object, as well as associations, which are
based on joins already in these tables.
For forward generation, do not specify a database table.

Schema Object Choose the schema object you want to base the entity object on. (If you
haven't yet typed a name in the Name field, selecting an object adds a
default name.) Or, type the name of the object. If the schema contains a lot
of tables, it may be easier to type the name rather than find it in the list.
Database Choose a schema from the list. Its schema objects will appear in the
Schema Schema Object list.
11-371
Tables, Views, Select a checkbox to include the item in the Schema Object list. Deselect it
Synonyms, to exclude these objects.
Snapshots
To specify name, package, and table information for reverse generation:
1. Choose a schema from the Database Schema dropdown list.
2. Select the information you want to appear in the Schema Object list, any combination of
Tables, Views, Synonyms, and Snapshots.
3. In the Schema Object list, choose the object that you want to base the entity object on.
Or, type a name in the field.
4. In the Name field, optionally change the entity object name.
5. In the Package field, you can accept the default package where the object will reside, or
you can choose another package by typing the name or clicking Browse.
To specify name and package information for forward generation:
1. In the Name field, type the entity object name.
To extend an existing entity object:
1. In the Extends Entity field, click Browse to select an entity object in your project to
extend.
2. If you will forward generate a table for the extended entity object to use, do not change
anything in the Database Objects fields. If you will reverse generate the extended entity
object from a table you have extended, select the table:
a. Choose a schema from the Database Schema dropdown list.
11-372
b. Select the information you want to appear in the Schema Object list, any
combination of Tables, Views, Synonyms, and Snapshots.
c. In the Schema Object list, select the object that you want to base the entity object
on. Or, type a name in the field.
3. In the Name field, optionally change the entity object name.
Related Topics
What Is a Entity Attribute?
Extending an Existing Entity Object
11-373
Selecting a Package
In the Parent dialog, select a Java source package. Typically, this dialog is used to select a
package that will contain a newly created business component.
1. Expand the tree to display the packages in your project.
2. Select the package and click OK.
Related Topics
11-374
Specifying an Existing Entity Object to Extend
In the Parent dialog, select the entity object you want to extend.
1. Expand the tree to display the entity objects in your project.
2. Select an entity object and click OK.
Related topics
11-375
Creating, Removing, and Ordering Entity Attributes
Entity Object Editor, you can do the following in the Attributes page:
● Define a new entity attribute — For reverse generation, you can define a new transient
attribute. For forward generation, you can define both transient and persistent attributes.
● Add an entity attribute from a table — For reverse generation, you can add a new
attribute from a column in an existing table. When you first create an entity object, this
Entity Attributes list is populated with attributes from all columns in the table you
selected in the Name page.
● Remove an entity attribute — Remove attributes that you don't want to be part of this
entity object.
● Order entity attributes for forward generation — The order that the attributes appear in
the Entity Attributes list is the order that the columns are created in the table.
New in this release, from the editor, you can access the Synchronize tool, which helps you
keep the datasource and business logic tier in sync after one of them changes.
Field Description
(Optional) A list of the entity attributes in the entity object
you're defining. In the Name page, if you chose a
schema object that exists, the list is initially populated
with attributes based on columns in the datasource.
Entity Attributes
To reorder the entity attributes (which determines column
order when forward generating), select one or more
attributes, and click the up or down arrow button until the
selected items are in the position you want.
Click New to define a new transient entity attribute, or a

New
new persistent entity attribute for forward generation.
11-376
Click New from Table to add a new persistent entity
New from Table
attribute based an existing table column.
Select an attribute in the Entity Attributes list and click
Remove to remove it from the list. If an attribute has
Remove dependencies, you can't remove it; a dialog appears
which lets you view all dependencies so you can remove
them, if needed.
In the editor, click Synchronize to access the
Synchronize tool, which helps you keep the datasource
Synchronize
and business logic tier in sync after one of them
changes.
To create an entity attribute:
1. Click New.
2. In the Define New Entity Attribute dialog, specify attribute settings to define one of the
following:
❍ a new transient entity attribute
❍ a new persistent entity attribute for forward generation
3. Click OK.
The attribute appears in the Entity Attributes list.
To add an entity attribute based on a table column:
1. Click New from Table.
2. In the Create New Entity Attributes from Columns dialog, define one or more attributes.
3. Click OK.
The new attribute(s) appear in the Entity Attributes list. The attributes added to the entity
object will have attribute settings that correspond to the properties of the underlying
database column.
11-377
To remove an entity attribute:
You can remove columns if your business logic does not require all of the information from the
table.
1. Select one or more attributes. For multiple attributes, control-click or shift-click them.
2. Click Remove.
To order entity attributes:
The attribute order is the order that the columns will appear in the table during forward
generation.
1. Select one or more attributes. For multiple attributes, control-click or shift-click them.
2. Click the up or down arrow button to rearrange the order.
To access the Synchronize tool:
You can access the Synchronize tool from the Entity Object Editor, but not the wizard.
● Click Synchronize.
Related topics
11-378
Defining a New Entity Attribute
Entity Object Editor, use the Define New Entity Attribute dialog to define a new entity attribute,
either
● a new transient entity attribute
● a new persistent entity attribute for forward generation
Transient entity attributes are not persisted in the database, while persistent entity attributes
are. To add a persistent attribute from an existing table, see Adding an Entity Attribute from a
Table.
The Discriminator attribute setting is new in this release.
Field descriptions

Attribute Attribute

type in the list.
business components
framework.
11-379
in most
cases
in the table).
selected.
the table.
the table.
In general, for forward generation, the primary key, mandatory, persistent, database column
To create a entity attribute:
1. Fill in the attribute settings, as outlined in the previous table.

2. Click OK.
The attribute appears in the Entity Attributes list of the Attributes page.
Related topics
11-380
Creating a Domain
Editing a Domain
11-381
Adding an Entity Attribute Based On a Table
Column
Entity Object Editor, from the Attributes page, use the Create New Entity Attributes from
Columns dialog to define new entity attributes based on an existing table column.
Field descriptions
Field Description
A list of attributes based on columns in a table and that
are not already included in the Entity Attributes list of
the Attributes page. You can create entity attributes by
moving attributes from the Available list to the Selected
Available list: select one or more attributes, and click the right
arrow (>). Or click the double right arrow (>>) to move all
attributes.
(Optional) A list of new entity attributes you want to add

to the entity object. To remove an attribute from the list,
Selected select one or more attributes, and click the left arrow (<).
To remove all attributes, click the double left arrow (<<).
To add an entity attribute based on a table column:
The Available list displays the entity objects and attributes you selected in the Entity Objects
page.
1. Move one or more entity attributes from the Available list to the Selected list in one of
these ways:
❍ In the Available list, select an entity attribute, control-click to individually select
multiple attributes, or shift-click to select a range of attributes, and then click the
right arrow (>).
❍ In the Available list, double-click an entity attribute.
❍ To move all attributes in an entity object, select the entity object in the Available
list and click the right arrow (>).
❍ To move all attributes in a package, select the package and click the right arrow
(>). Or simply click the double right arrow (>>).
11-382
2. Click OK.
The new attribute appears in the Entity Attributes list of the Attributes page. The
attributes added to the entity object will have attribute setting that correspond to the
properties of the underlying database column.
To remove an entity attribute from the list:
Do one of the following:
● Select one or more attributes in the Selected list, and click the left arrow (<).
● Double-click an attribute in the Selected list.
● Click the double left arrow (<<) to remove all attributes.
Related topics
Creating a Domain
Editing a Domain
11-383
Generating Java Source Files and Methods for
Entity Objects
Entity Object Editor, in the Java page, you can specify that the wizard generate a Java file for
the entity definition class, the entity object class, the entity collection class, or a combination. By
default, the wizard generates the entity object class, but not the other two classes. You can edit
the classes to customize the entity object's behavior through its methods. You can also
generate these classes from a customized base class.
Field Description
Entity Definition Class These settings apply to the EntityDefImpl class.
Generate Java file When this checkbox is selected, JDeveloper generates a Java file
you can edit to customize the entity object definition's behavior.
Otherwise, JDeveloper generates an XML file only.
If an entity object publishes or subscribes to an event through the

Publish or Subscribe pages, this checkbox is automatically set, as
most of the event code is generated in the definition files.
Entity Collection Class
that you can edit to customize the entity object's behavior.
Entity Object Class These settings apply to the EntityImpl class.

that you can edit to customize the entity object's behavior.
Generate Methods By default, accessor methods are generated. The others are not.
Accessors Select this checkbox to generate accessor methods (for example,

getJob and setJob).
Data Select this checkbox to generate data manipulation methods,

Manipulation including lock, which you can modify to customize the entity
methods object's locking behavior, and doDML, which you can modify to
customize its update, insert, and delete logic.
11-384
Validate Select this checkbox to generate a validate method, where you
method can customize the entity object's validation logic.
Create Select this checkbox to generate a create method, where you

method can customize or add additional initialization features to the entity
object's create logic.
Remove Select this checkbox to generate a remove method, where you

method can customize or add clean-up code to the entity object's remove
logic.
Extends Click Extends to select entity object and definition base classes
you want to use to generate the entity object. Typically, in an
applications organization, the framework supplied by JDeveloper
will be customized by a core group and all entity objects for the
organization may be built over this customized framework.
To generate an entity definition class:
1. Select Generate Java File.
2. Optionally click Extends if you want to generate this class from a customized framework
class.
To generate an entity collection class:
class.
To generate an entity object class:
2. Select the methods you want to generate.
class.
11-385
● After you are finished, click OK or Finish to save your changes.

Related Topics
About the EntityDefImpl Class
About the EntityImpl Class
11-386
Entity objects, view objects, and application modules are based on these framework classes:
● entity definition class — oracle.jbo.server.EntityDefImpl
● entity collection class — oracle.jbo.server.EntityCache
● entity object class (row) — oracle.jbo.server.EntityImpl
● view object class — oracle.jbo.server.ViewObjectImpl
● view row class — oracle.jbo.server.ViewRowImpl
● application module class — oracle.jbo.server.ApplicationModuleImpl
You can optionally extend one or more of these classes and generate business components
from your customized classes. When you add functionality to your classes, either now or in the
future, you globally affect all the business components that extend from them.
You can specify default framework base classes while you are setting default business
component preferences with the Preferences dialog. The default classes become the defaults
in wizard and editor fields, and are the base classes used when you generate default business
components.
You can specify that a specific business component extend from a customized framework base
class while you are
● creating or editing an entity object with the Entity Object Wizard or Editor,
● creating or editing a view object with the View Object Wizard or Editor, or
● creating or editing an application module with the Application Module Wizard or Editor.
To specify framework base classes for a specific business component:
11-387
1. In the Java page, click Extends.
2. In the Framework Base Classes dialog, type the fully qualified class name or click
Browse to specify the class.
The class must extend the appropriate framework base class and be located on the
classpath.
3. When you have finished specifying all the classes, click OK.
Related topics
About Customizing the Framework
11-388
Creating a Default View Object and Finishing the
Entity Object Wizard
While creating an entity object with the Entity Object Wizard, you can generate a default view
object, based on the entity object you defined, and finish the wizard in the Finish page.
The default view object contains all the attributes of your entity object (essentially a SELECT *
FROM table_name). You can later edit this view object in the View Object Editor.
To finish the wizard:
1. Optionally select Create default View Object.
2. Click Finish.
Related topics
11-389
An entity object always has an associated XML file. It optionally has Java source files — an
entity object class, entity definition class, or both — depending on your selections:
● Enabling and Disabling Java File Generation
● Generating Java Source Files and Methods for Entity Objects
To customize entity object behavior, you can:
● customize the framework base classes and create entity objects from your customized
classes, so you can globally effect multiple entity objects
● edit the Java classes of specific entity objects
Related topics
11-390
Creating an Entity Object for a Table with No
Primary Key
When you define an entity object, it must have a primary key or use a RowID attribute (based
on the table's ROWID). To do so, you must create a new attribute while you are defining your
entity object in the Entity Object Wizard.
If you create a default entity object from a table with no primary key, a RowID attribute is
automatically created as the primary key.
To define a RowID attribute to use as a primary key:
1. In the Attributes page of the Entity Object Wizard, click New from Table.
2. In the Create New Entity Attributes for Column dialog, select ROWID in the Available list
and click > to move it to the Selected list.
3. Click OK.
The RowID attribute appears in the Entity Attributes list.
Related topics
11-391
Creating an Association or Composition
The Association Wizard lets you create an association at design time. The association can be
based on an existing table (reverse generation) or not, and optionally be used to create a
database constraint in a database table (forward generation).
Alternatively, you can create default associations, based on key constraints in existing
database tables, in the Business Components Project Wizard or Editor and Package Wizard or
Editor.
For forward generation, creating associations can optionally add relationships to the tables you
generate; for example, you might want other applications (that don't use Business Components
for Java) to have access to the same relationships. You create tables from entity objects by
using the Create Database Objects Tool.
Before you can define an association, you must define the entity objects involved in the
association.
To create an association with the Association Wizard:
● Choose File | New, select Business Components, and double-click Association.
● In the Navigator, right-click the business components package and choose New
Association.
The Association Wizard appears.
3. In the Name page, specify the name and package and optionally extend an existing
association. Then click Next.
4. In the Entity Objects page, specify the entity objects involved in an association. Then
click Next.
11-392
Typically, the source entity object is the entity object containing the primary key of a
foreign key constraint, while the destination entity object is the entity object containing
the foreign key.
5. In the Source Attributes page, specify the attributes involved in the association for the
source entity object. Then click Next.
6. In the Destination Attributes page, specify the attributes involved in the association for
the destination entity object. Then click Next.
7. In the Association Properties page, specify association options, including cardinality,

whether to generate accessors, whether it is a composition, whether it should be used to
key constraints, and whether to implement cascade delete behavior. Then click Next.
8. If you are creating a many-to-many association, the Intersection page will appear.
Specify the entity object corresponding to your intersection table. Then click Next.
9. If you are creating a many-to-many association, the Generate Related Associations page
will appear. Optionally, specify associations between your source and intersection entity
objects and between your destination and intersection entity objects. Then click Next.
10. In the Finish page, click Finish to generate the entity object.
You can edit the entity object in the Association Editor.
To quit the wizard without saving any changes, click Cancel.
Related topics
11-393
Specifying the Name and Package of an Association
While creating an association with the Association Wizard, you specify the following information
in the Name page. How you use this page depends on whether you are performing reverse or
forward generation, or extending an existing association.
Field descriptions
Field Description
Name Type an association name. You can pick something that describes the
relationship, perhaps ending with the string "Assoc" to make it easy to
identify.
Package Type the name of the package that should contain the association. Click
Browse to search for an existing package. Ideally, the association resides
in the same package as the entity objects it associates, but this is not
required.
Extends Association (Optional) Type the name of an existing association you want to extend.
Click Browse to select it from a dialog. This is a useful feature if you want to
provide additional functionality or extend a previously created association
that you don't have the source for. See Extending an Existing Association.
To specify name, package, and table information for reverse or forward generation:
1. In the Name field, optionally change the association name.
To extend an existing association:
1. In the Extends Association field, click Browse to select an association in your project to
extend.
2. In the Name field, optionally change the association name.
11-394
Related Topics
Extending an Existing Association
11-395
Specifying an Existing Association to Extend
In the Parent dialog, select the association you want to extend.
1. Expand the tree to display the associations in your project.
2. Select an association and click OK.
11-396
Specifying the Entity Objects for an Association
Association Editor, use the Entity Objects page to specify the entity objects you want to
associate. The page displays entity objects in your current project.
The relationship can be one-to-one or one-to-many; you can implement a many-to-many

relationship either by using an entity object based on an intersection table or by using two one-
to-many associations.
After the association is defined, the entity objects can use the association to transparently
traverse to the other side of the association in a predefined manner. For example, the
employees of a department might be accessed through a department by issuing the call
deptImpl.getEmps().
Field descriptions
Field Description
Select Source Entity Object Select the source entity object from this list. Typically, this is the entity
object containing the primary key of a foreign key constraint.
Select Destination Entity Object Select the destination entity object from the list. Typically, this is the entity
object containing the foreign key.
Select Intersection Entity Object For a many-to-many association, choose the entity object corresponding to
your intersection table.
To specify the entity objects in an association:
1. Select the source entity object in the Select Source Entity Object list.
2. Select the destination entity object in the Select Destination Entity Object list.
3. For a many-to-many association, in the Select Intersection Entity Object field, choose
the entity object corresponding to your intersection table.
11-397
Related Topics
11-398
Selecting the Attributes for an Association
Association Editor, use the Source and Destination Attributes pages to specify the attributes
that define the relationship between the entity objects of an association. The Role Attributes
page appears twice:
● once for the attributes of the source entity object
● once for the attributes of the destination entity object
At least one attribute must be selected for each entity object in order to create a valid
association; the resulting detail must match each pair of selected attributes. Typically these
attributes represent key fields in a database table, but an association can be defined using any
entity attributes. For example, an association created between two entity objects, Department
and Employees, might have a relationship where Dept.Deptno = Emp.DeptNo.
Field descriptions
Field Description
Entity Object The name of the source or destination entity object chosen in the Entity
Objects page.
Available Attributes A list of the entity object's available attributes. To specify the attributes that
define the association, select one or more attributes or nodes, and click the
left arrow (>) to add them to the Selected Attributes list. You must specify
the same number of attributes for each entity object, in the proper order.
Alternatively, you can specify attributes by key.
Available Keys A list of the keys associated with this entity object. To specify attributes by
key, select an available key and click the left arrow (>) to add the attributes
that define the key to the Selected Attributes list.
While you can explicitly choose the attributes used for the relationship,
there may already be keys that exist that have the set of attributes selected.
If so, you can save time by selecting an available key from this list. Another
advantage of using a key is that if you select a key on the source entity
object, the matching key (if applicable) will be included by default on the
destination side.
Selected Attributes The attributes that define the association between the entity objects. To
remove an attribute from the list, select one or more attributes, and click the
left arrow (<).
11-399
To specify the attributes for an association:
1. In the Source Attributes page, select attributes from the source entity object. Either:
❍ In the Available Attributes list, select an entity attribute, control-click to individually

select multiple attributes, or shift-click to select a range of attributes, and then click
the right arrow (>). Or double-click an attribute.
❍ Select a key in the Available Keys list and click the right arrow (>) to move its
associated attributes to the Selected Attributes list. Or double-click a key.
2. Click Next or the Destination Attributes tab.
3. In the Destination Attributes page, select the attributes from the destination entity object.
You must specify the same number of attributes for each entity object, in the proper
order. If you selected a key in the source page, the matching key (if applicable) will be
included by default on the destination page.
To remove an attribute from the Selected Attributes list:
● n the Selected Attributes list, select an entity attribute, control-click to individually select
multiple attributes, or shift-click to select a range of attributes, and then click the left
arrow (<).
● Double-click an attribute in the Selected Attributes list.
Related Topics
11-400
11-401
Association Editor, use the Association Properties page to specify the behavioral aspects of an
association:
● cardinality
● whether to expose association accessors that return data from the other side of the
association and the names of the accessors. The accessors are placed in the entity
object class.
● whether to generate key constraints during forward generation
● whether the association is a composition
● whether to implement cascade delete behavior
This page has divisions on the left and the right for the source and destination sides of the
association.
Related Topics
11-402
Specifying the Cardinality of an Association
Association Editor, in the Association Properties page, you can specify the cardinality of an
association.
Cardinality helps to define the relationship between entity objects by setting the minimum and
maximum number of members that may participate in an association:
● 0..1 indicates that a single value is allowed, but not required
● 1 indicates that exactly one value is required
● * indicates that there are many values allowed, but none required
Field descriptions
Field Description
Source Cardinality Choose a cardinality setting for the source end of the association.
Destination Cardinality Choose a cardinality setting for the destination end of the association.
To specify cardinality:
Choose a Cardinality setting for the source and destination entity objects:
● For a one-to-one relationship, both entity objects should have 1.

● For a one-to-many relationship, the master entity object can have 1 or 0..1 and the detail
*.
● For a many-to-many relationship, both entity objects should have *.
Note: If both source and destination entity objects have cardinalities of *, you will need an
intersection table.
Related Topics
11-403
Creating a Many-to-Many Relationship
11-404
Exposing Association Accessors
Association Editor, in the Association Properties page, you can generate and name association
accessors, which return data from the other side of the association. For example, inside the
Dept entity object, you could call getEmps() and get back a collection of Employee entity
objects that reflected the employees working in the current department.
The accessors are placed in the entity object class.
Field descriptions
Field Description
Source Expose Accessor Select this option to expose the accessor method in the source or
destination entity object. By default, associations are exposed in the owning
Destination Expose Accessor entity objects through association accessors, which return data from the
other side of an association.
Source Accessor Name Type the name of the accessor method or accept the default name
provided. The accessor method will be available to the entity object on the
Destination Accessor Name other side of the association. For example, in a Dept-Emp association, Dept
would have an accessor called getEmp().
To generate an association accessor:
1. For the source or destination entity object, select Expose Accessor.
2. Optionally change the name of the accessor method in the Accessor Name field.
To not generate an association accessor:
● For the source or destination entity object, deselect Expose Accessor.
Related Topics
11-405
Specifying Whether to Generate Database
Association Editor, in the Association Properties page, you specify whether to generate key
constraints during forward generation.
Field description
Field Description
Use Database Key Constraints Select this option to create entity-level key constraints when generating
tables with the Create Database Objects Tool. The appropriate database key
constraint objects will be created to correctly represent the association
settings you have selected (a foreign key referencing either a primary or
unique key). Note that deselecting this option does not remove constraints
that were already created.
To generate database key constraints for forward generation:
● Select Use Database Key Constraints.
Related Topics
Forward Generating Database Tables and Constraints
11-406
Creating a Composition
Association Editor, in the Association Properties page, you specify whether an association is a
composition or not.
Field description
Field Description
Composite Association Select this option to create a composition or deselect it to create an
association that isn't a composition. A composition is an association in
which the source object "owns" the destination object. You might think of
the source object as a container for the destination objects. For inserts,
updates, and deletes, the destination entity object is considered part of the
parent entity object.
To create a composition:
● Select Composite Association.
To create an association that isn't a composition:
● Deselect Composite Association.
Related Topics
11-407
Specifying the Intersection Entity Object for a Many-
to-Many Association
While you are creating an association with the Association Wizard or editing an association with
the Association Editor, the Intersection page appears if the association is many-to-many. In the
Intersection page, you specify the entity object that corresponds to your intersection table and
select the attributes in that table that correspond to your source and destination entity objects.
Field descriptions
Field Description
Entity Object The name of the intersection entity object.
Attributes A list of the intersection entity object's available attributes. You can select
an attribute as a foreign key to the source entity object by selecting the
attribute and then clicking the upper >. You can select an attribute as a
foreign key to the destination entity object by selecting the attribute and
then clicking the lower >. Control-click to select more than one attribute.
Source Attributes The attributes you have selected as foreign keys to the source entity object.
Remove an attribute from this list by selecting an attribute and then clicking
<.
Destination Attributes The attributes you have selected as foreign keys to the destination entity
object. Remove an attribute from this list by selecting an attribute and then
clicking <.
Related Topics
11-408
Generating One-to-Many Portions of a Many-to-
Many Association
While you are creating an association with the Association Wizard or editing an association with
the Association Editor, the Generate Related Associations page appears if the association is
many-to-many. In the Generate Related Associations page, you specify whether you want to
generate one-to-many associations from your source and destination entity objects to your
intersection entity object.
Field descriptions
Field Description
Source If you want to create a one-to-many association from your source entity
object to your intersection entity object, select the checkbox and enter the
name of the association in the field.
Destination If you want to create a one-to-many association from your source entity
object to your intersection entity object, select the checkbox and enter the
name of the association in the field.
Related Topics
11-409
The File that Defines an Association
Each association is defined in an XML file and has package scope. Association accessors are
placed in the entity object class.
Related Topics
Creating an Association or Composition
11-410
JDeveloper can automatically create associations from database constraints in these ways:
● When you create default business components.
● When you click OK in the Entity Object Editor if the database constraint is a foreign key
relationship and the primary and foreign key attributes are part of the entity object.
● When you use the Synchronize Tool.
Related Topics
11-411
Business Components for Java provides several tools that let you edit entity objects and
associations. The entity objects can be based on existing tables (reverse generation) or be
used to create database tables (forward generation).
● Editing an Entity Object — You can edit entity object in the Entity Object Editor.
● Editing an Association or Composition — You can edit associations in the Association

Editor.
● Ways to Edit Entity Attributes — You can edit entity attributes in the Entity Object Editor
and Attribute Editor.
● Editing business components on a UML class diagram — If you used JDeveloper to

create a UML class diagram, you can edit business components from the diagram.
Related topics
11-412
Editing an Entity Object
To edit an entity object with the Entity Object Editor, in the Navigator, right-click the entity object
and choose Edit object. Or simply double-click it. You can also edit Java source files in the
JDeveloper code editor.
In the Entity Object Editor, you can modify these aspects of an entity object:
● Specifying the Name, Package, and Table of an Entity Object
● Creating, Removing, and Ordering Entity Attributes
● Specifying Entity Attribute Settings
● Generating Java Source Files and Methods for Entity Objects
In addition, you can specify these items, which you could not specify while creating the entity
object with the Entity Object Wizard:
● Tuning Entity Object Performance with the JDBC Update Batching API
● Adding, Editing, Removing, and Reordering Entity Validation Rules
● Publishing Entity Object Events
● Subscribing to Entity Object Events
● Defining Business Component Properties and Values
Related Topics
11-413
Adding, Editing, Removing, and Reordering Entity
Validation Rules
Attribute Editor, you can add, edit, remove, and reorder validation rules in the Validation page:
● Add and edit a validation rule — You can apply new rules at the entity object level,
attribute level, or both.
● Remove a validation rule — You can remove rules you do not want.
● Reorder validation rules — Rules can be reordered within a level, which is useful when
you have multiple validation rules per attribute and want to control the order of rule firing.
You can specify both validation rules and validation levels. A validation level indicates whether
the rule is applied to the attribute level or the entity object level.
At runtime, attribute-level validation rules are invoked when the attribute value is modified
through a generated setter method, or by the setAttribute method called on the entity object.
The entity-level validation rules are invoked when the current row in the client's iterator changes
from this entity object to the next; or during the commit cycle if an entity object is invalid; or by
an explicit validate method call on the entity object.
Applying validation rules involves attaching code to an entity object. When you use the wizard
(as opposed to writing everything by hand), the Business Components for Java framework
generates XML, enabling you to customize rules without recompiling Java code.
Field Description
(Optional) A tree showing the entity object and the
attributes in the entity object. You can add validation
rules at the entity object and attribute levels.
Declared Validation
Rules To reorder the validation rule, select one or more of
them, and click the up or down arrow button until the
11-414
Select an entity object or attribute, and click New to
New
define a new validation rule.
Select an entity object or attribute, and click Edit to edit a
Edit
validation rule.
Select an entity object or attribute, and click Remove to
Remove
remove it from the list.
To add a validation rule:
1. In the Validation page, select an attribute or entity object in the Declared Validation
Rules list and click New.
2. In the Add Validation Rule dialog, define the rule.
3. Click OK.
To edit a validation rule:
1. In the Validation page, select the validation rule in the Declared Validation Rules list and
click Edit.
2. In the Add Validation Rule dialog, define the rule.
3. Click OK.
To remove a validation rule:
1. In the Validation page, select a rule in the Declared Validation Rules list.
2. Click Remove.
To reorder a validation rule:
This is useful when you have multiple validation rules per attribute and want to control the order
of rule firing.
1. Select a rule in the Declared Validation Rules list.

11-415
2. Click the up or down arrow button to move the selected item up or down by one position.
To save changes:
Related Topics
11-416
Publishing Entity Object Events
While editing an entity object with the Entity Object Editor, you can use the Publish page to
define, edit, or remove events to be published by the entity object. You can also specify
attributes that are delivered with the event.
Field Description
(Optional) A list of the events defined for this entity
Published Events object.
New Click New to define a new event.

Edit Select an event and click Edit to edit it.
Select an event and click Remove to remove it from the
list. Note that if you want to remove an event from your
Remove project, you must manually edit the Java source files and
XML files. You cannot completely remove an event with
the user interface.
To add an event:
1. Click New.
2. In the Create New Event dialog, define the event.
3. Click OK.
The event appears in the Published Events list of the Publish page.
4. To make this event immediately available in the following Subscribe page, click Apply
when you are finished with this page.
To edit an event:
1. Select the event in the Published Events list.
11-417
2. Click Edit.
3. In the Edit Event dialog, edit the name or the attributes delivered with the event.
4. Click OK.
To remove an event:
1. In the Subscribe page, remove all subscriptions to the event.
2. In the Publish page, select the event in the Published Events list.
3. Click Remove.
The event is removed from the list.
4. Click OK.
If you want to remove an event from your project, you must manually edit the Java source files
and XML files. You cannot completely remove an event with the user interface.
To send an event:
The editor generates a method of the same name as the event. You must add a call to this
method from whatever code fires the event.
For example, for an event named SalaryChanged, the generated method is also named
SalaryChanged(). Any call to SalaryChanged fires the event, sending the appropriate
data. To fire the SalaryChanged event whenever Sal is set, call SalaryChanged from
setSal.
public void setSal(Number value) {

setAttributeInternal(SAL, value);
SalaryChanged(); // Call this method to fire the event.
}
To save changes:
11-418
Related Topics
11-419
Creating and Editing an Event
While editing an entity object with the Entity Object Editor, from the Publish page, you can use
the Create New Event dialog to create and edit events to be published by the entity object. An
event is raised by invoking the event method in custom Java code. Enter or edit the event's
name and parameters that should be delivered. Ordering of these parameters is not necessary,
as the event delivers the parameters in a hashtable, hashed by the parameter name. The editor
generates event code in the Java files for the entity object class and the entity definition class, as
well as XML code, so the entity object can publish the event.
Field descriptions
Field Description
Name The event name.
A list of entity attributes for this entity object. To move
attributes from the Available list to the Selected list,
Available Attributes select one or more attributes or nodes, and click the left
arrow (>). Or click the double left arrow (>>) to move all
attributes.
(Optional) A list of the entity attributes used by the event.
To remove an attribute from the list, select one or more
Selected Attributes attributes, and click the left arrow (<). To remove all
attributes, click the double left arrow (<<).
To add an event:
1. Type an event name in the Name field.
2. To deliver an attribute with the event, move it from the Available Attributes list to the
Selected Attributes list.

right arrow (>).
Select an attribute and click < to remove it from the selected list or click << to remove all
selected attributes.
11-420
3. Click OK.
The event appears in the Published Events list of the Publish page.
4. To make this event immediately available in the following Subscribe page, click Apply
when you are finished with the Publish page.
To edit an event:
1. With the event name displayed in the Name field, edit the name or the attributes
delivered with the event.
2. Click OK.
The edited event appears in the Published Events list of the Publish page.
Related Topics
11-421
Subscribing to Entity Object Events
While editing an entity object with the Entity Object Editor, you can use the Subscribe page to
select the events that the entity object will listen for. When the event is triggered, the entity
object responds by calling the specified method.
You can specify how the event will be delivered: deliver the event to the instances of the entity
object as subscribed in program logic (addListener), or to those entity objects that are
associated to the publisher, by the selected association. To use associations for event delivery,
you need to first create the association and have generated accessors in the Association
Properties page of the Association Wizard or Editor. In addition, the entity objects need to be
directly associated with one association: you can't traverse multiple associations.
Field descriptions
Field Description
Published Events A tree view of events defined in the project. To subscribe to
an event, select an entity object or an event, and click the
right arrow (>) to move it to the Subscribed Events list. The
Published Events list is populated by the events defined in
the Publish page; remember that after you define an event in
that page, you need to apply changes before it will appear in
the Subscribe page. If you have added events directly in
code, the editor won't notice them.
Subscribed Events (Optional) A tree view of event publishers and their events
that are currently subscribed to by this entity object. To
remove events from the list, click an entity object or event,
and then click the left arrow (<).
Deliver Events Select an event in the Subscribed Events list and then use
the Deliver Events group to specify event delivery.
To Subscribing Entities In this area, specify how entity objects subscribe to the
event.
Registered in Select this option if you want to add your own custom logic
Program to link a subscribing entity object instance with a publisher
instance.
11-422
Associated to Select this option if you want the editor to add code so all
Publisher instances of this entity object are automatically linked to their
respective publisher entity object, as defined by the selected
association accessor (By field) .
By Select an association accessor from the list. The available
association accessors get their subscribing entity object type
from the publisher. For example, if an Emp entity object is
subscribing to LocChanged on a Dept entity object, all
associations between Dept and Emp that return Emp would
be on this list.
By Invoking Methods (Optional) A list of methods that will be called by this entity
object when the event is received. They are called in the
order they are listed, from top to bottom. To add a new
method, click New. To edit a method, select the method and
click Edit. To remove a method, select the method and click
Remove. To reorder methods, select a method and click the
up or down buttons to move them in the list. Note that you
can have the same method in the list more than once; this is
analogous to calling the method more than once.
To subscribe to an event:
You can subscribe to events defined in the Publish page of an entity object. You can specify a
method that will be executed when the event is received; if you want the editor to add the
method call for you, define the method before using the Subscribe page.
1. Move one or more events from the Published Events list to the Subscribed Events list by
selecting an entity object or event and clicking the right arrow (>).
2. While an event is selected in the Subscribed Events list, specify how the entity object
subscribes to the event.
❍ To write subscription code yourself, select Registered in Program.
❍ To have the editor add code for you, select Associated to Publisher and choose
the association accessor in the By list.
3. Optionally specify one or more methods to invoke when the event is received:
❍ To add a new method, click New.
❍ To edit a method, select the method and click Edit.

❍ To remove a method, select the method and click Remove.
❍ To reorder methods, select a method and click the up or down buttons to move
them in the list.
4. Perform steps 2 and 3 for each event you want the entity object to subscribe to.
11-423
To remove events:
● In the Subscribed Events list, click an entity object or event, and then click the left arrow
(<)
To save changes:
Example
The following steps show how to make a Dept entity object subscribe and respond to a change
in an employee's salary. This example assumes that Emp and Dept are defined in a package
named d2e, and that the Emp entity object publishes a SalaryChange event as described in
Publishing Entity Object Events. First, you define a method that executes when the event is
fired. Next, you subscribe to the event.
To implement a method to subscribe to:
Implement a method to execute when an Emp entity object instance fires the SalaryChange
event. Use the Source Editor to add a calcDeptTotal method (the method name is arbitrary)
to the Dept entity object's .java file. Import oracle.jbo.domain.Number and paste the
following code into the Dept class definition in DeptImpl.java.
public Number calcDeptTotal(Number EMPNO,

Number NewSalary,
Number DEPTNO) {
Number total = new Number(0);

RowIterator emps = this.getEmp();
EmpImpl empRow = null;
emps.reset();
while (emps.hasNext()) {
empRow = (EmpImpl)emps.next();
total = total.add(empRow.getSal());
}
11-424
System.out.println("TOTAL ->"+total);
return total;
To subscribe to the new method:
1. In the Navigator, double-click the Dept entity object.
2. In the Entity Object Editor, click the Subscribe tab.
3. Select SalaryChange in the Published Events list, and then click the right arrow to move
it to the Subscribed Events list.
4. While SalaryChange is selected in the Subscribed Events list, click New.
5. In the Define Method dialog, choose calcDeptTotal from the Method dropdown list.
The editor adds attributes Empno, Sal, and Deptno to the Available list.
6. Click the double right arrow to move Empno, Sal, and Deptno from the Available list to
the Selected list. If Empno is not first in the Selected list, select it and click the up arrow
button to move it to the top of the list.
7. Click OK to close the Define Methods dialog and the Entity Object Editor.
The business components framework generates Java and XML code for the event
subscription. At run time, when an employee's salary changes, the Dept entity object
responds by executing calcDeptTotal.
Related Topics
11-425
Adding and Editing a Method that Executes in
Response to an Entity Object Event
While editing an entity object with the Entity Object Editor, from the Subscribe page, use the
Define Method dialog to specify a method that the subscriber will execute in response to a
particular event. In the dialog, you select a method and the arguments that should be passed to
the method.
Warning: This page only validates that the count of the arguments match the required count for
the selected method. No type-checking is done for the arguments. The generated code may try
to perform a conversion, but will fail if the event parameter's type is not convertible to the type
of the argument a method expects.
Field descriptions
Field Description
Method Choose a method from the list.
Available The parameters (attributes) that are delivered with the event. Select the
attributes you want to pass to the method, and click the right arrow (>) to
move them to the Selected list. Click the double right arrow (>>) to move all
of the attributes to the Selected list.
Selected (Optional) An ordered list of parameters that will be passed as arguments to
the method. To remove an attribute from the list, select one or more
attributes, and click the left arrow (<). To remove all attributes, click the
double left arrow (<<). To reorder attributes, select an attribute and click the
up or down arrow to move it up or down in the list.
Note: The attribute list should match the the arguments for the selected
method. JDeveloper verifies only the count. Type cast errors are thrown
only at runtime.
To add method:
The Available list displays the attributes sent with the events, as defined in the Publish page of
the entity object.
1. Choose a method in the Method list.
2. Specify the attributes you want to pass to the method.
Move one or more attributes from the Available list to the Selected list in one of these
11-426
ways:
right arrow (>).
❍ To move all attributes in an entity object, select the entity object in the Available
list and click the right arrow (>).
❍ To move all attributes in a package, select the package and click the right arrow
(>). Or simply click the double right arrow (>>).
3. Using the up an down arrow buttons, order the attributes so it matches the method
signature.
Also remember that the attribute type must match the methods parameter type.
4. Click OK.
The method appears in the By Invoking Methods list of the Subscribe page.
To remove an attribute from the Selected list:
To edit a method:
● While the method name is displayed in the Method field, modify the Selected list as
needed, and then click OK.
Related Topics
11-427
Defining Business Component Properties and
Values
Use the Properties page to add a property. You can also add and edit values for existing
properties, and delete properties.
With this page, you can supply your own name/value pairs of business component metadata
which the framework can access at runtime. Properties are often user-supplied data that
provide hints, UI formatting clues, notes to users, and so on. You can set custom properties on
entity objects, view objects, domains, and application modules, as well as the individual
attributes of an entity or a view object.
You can access the page while
● editing an entity object with the Entity Object Editor

● editing an entity attribute in the Attribute Editor
● editing a view object in the View Object Editor
● editing a view attribute in the Attribute Editor
● editing an application module with the Application Module Editor
● editing a domain with the Domain Editor
Field descriptions
Field Description
Name Type an attribute property name directly in the field or choose a property
from the drop-down list. The drop-down list will contain some default
property names, as well as property names recently used.
Value Type a value for the property displayed in the Name field.
Properties A list of the properties currently applied to the object. Selecting an item will
put the selected property name and value in the appropriate fields.
To add a new property:
● Type a property name and value, and then click Add.
11-428
The name and value appear in the Properties pane. If you attempt to add a property that
has the same name as an existing property, the existing property will be replaced with
the new value.
To delete a property:
● Choose the property in the Name field or select the property in the Properties list, and
then click Remove.
To change the value of a property:
● Choose the property in the Name field or select the property in the Properties list, edit
the Value field, and click Update.
To rename a property:
● Delete the property and redefine it.
To save changes:
Related Topics
Using XML Metadata Properties that Effect XML Generation
11-429
Editing an Association or Composition
To edit an association with the Association Editor, in the Navigator, right-click the association
and choose Edit object. Or simply double-click it.
In the Association Editor, you can modify these aspects of an association:
● Specifying the Entity Objects for an Association
● Selecting the Attributes for an Association
● Specifying Behavioral Aspects of an Association
For a many-to-many association, you can also specify these items:
● Specifying the Intersection Entity Object for a Many-to-Many Association
● Generating One-to-Many Portions of a Many-to-Many Association
Related Topics
11-430
Ways to Edit Entity Attributes
You can edit entity attributes in the
● Entity Object Editor
● Entity Attribute Editor
The Entity Attribute Editor is where you can specify properties and control hints at the attribute
level.
To use the Entity Attribute Editor, in the Navigator, select an entity object. Then right-click an
attribute in the Structure pane and choose Edit attribute; or simply double-click it.
You can specify the following information in the Entity Attribute Editor:
● Editing Entity Attribute Settings
● Defining User Interface Control Hints
Related topics
11-431
Editing Entity Attribute Settings
While you are editing entity attributes in the Entity Attribute Editor or editing a view attribute
(that is based on an entity attribute) in the View Attribute Editor, use the Entity Attribute page to
define attribute settings for an entity attribute.
Field descriptions

Attribute Attribute

type in the list.
in most
cases
in the table).
business components
framework.
11-432
selected.
the table.
the table.
To save changes:
● After you are finished, click OK to save your changes.

Related topics
Creating a Domain
Editing a Domain
11-433
Reordering Validation Rules
Attribute Editor, you can reorder validation rules in the Validation page. This is useful when you
have multiple validation rules per attribute and want to control the order of rule firing.
To reorder a validation rule:
1. In the Validation page, select a rule in the Declared validation rules list.
2. Click the up or down arrow button to move the selected item up or down by one position.
11-434
Use the Control Hints page to associate a control hint with the current view object or entity
attribute. If a hint is defined at the entity attribute level, all view objects will inherit the hint
values at runtime. A view object can define or override any entity object hints. At runtime the
client application displays the attribute through the user interface (UI) and will attempt to use
the control type and other hint customization options you choose.
You can specify more than one set of control hints for the attribute by changing the control hints
locale. The client UI will attempt to use the appropriate locale at runtime. To view the control
hints that are currently set for the attribute, select the Properties tab.
You can create control hints in your business components project while:
● Editing view attributes in the View Attribute Editor

● Editing entity attributes in the Entity Attribute Editor
Locale
Choose one or more language locales that the application will apply. All the control hints
you create will apply to the selected locale. To specify control hints for another locale,
choose the desired locale; the Control Hints page will display the current settings for that
locale.
Label Text
Enter the text the control will use for its label. For example, labels are prompts or table
headers that precede the value of a field.
Tooltip Text
Enter a short description the control will use for its tooltip text. In web applications, this
hint could be used in HTML as the value of the ALT attribute.
Format Type
Choose a formatter to use when the attribute is displayed. The formatting control hints
work with the attribute’s domain type and provide formatting support. The mapping of the
domain type to it’s available formatters is kept in the <jdev
root>/system/formatinfo.xml.
Format
Choose a format to be used by the selected formatter.
Display Hint
11-435
Choose whether or not the attribute should be displayed. You can use this hint to limit
the client UI to display only the desired attributes.
Control Type
Choose the control type the client UI will use to display the attribute.
Display Width
Enter the character width to be used by the control that displays this attribute.
Display Height
Enter the number of character rows to be used by the control that displays this attribute.
Form Type
Choose whether the attribute is to be displayed in the short or long form layout. The long
form acts like a detail mode. The short form is summary a form.
Related topics

Defining Control Hints for the UI
11-436
Forward Generating Database Tables and
Constraints
For forward generation, you first define business components in the business logic tier, and then
use them to generate database tables and constraints. You follow these general steps:
1. Define entity objects.

These are the basis of your tables.
2. Define associations, entity constraints, or both.

These are the basis of your database constraints.
3. Use the Create Database Objects Tool to create database tables and constraints from
business components.
Related topics

11-437
Defining Tables through Entity Objects
For forward generation, you first define entity objects. The entity objects are later used to create
database tables.
Related topics

11-438
Ways to Define Constraints
You can define database constraints through the following business components in the
business logic tier:
● associations
● entity constraints
To generate constraints in the database, you use the Create Database Objects Tool to forward
generate them from the business components.
Related Topics
11-439
Defining a Database Constraint by Creating an
Entity Constraint
The Entity Constraint Wizard lets you define entity constraints, which are used when you
forward generate database tables and constraints with the Create Database Objects Tool.
An entity constraint is a business logic tier object that represents a key constraint in the
database. An entity constraint describes, in terms of entity objects and attributes, the database-
level relationships between tables and columns. You select the entity object's attributes and
define qualities such as primary, foreign, check, or unique. When you create a database object
based on an entity object, the definition of the entity constraint is used to detect associations
between tables, create the specified key constraints in the database, and ensure that data in
the database is valid and conforms to the key constraints.
You can also create constraints while you define associations. In the Association Properties
page of the Association Wizard and Editor, select Use Database Key Constraints to
automatically create a constraint based on the association.
To create an entity constraint with the Entity Constraint Wizard:
1. In the Navigator, right-click an entity object and choose New Entity Constraint.
3. In the Name page, enter the Java name for your key constraint in the Name field, for
example, EmployeeSalaryKey.
4. In the Constraint Name field, type the name of the constraint that the database will use.
JDeveloper will provide a default name based on your choice of a constraint name, for
example, EMPLOYEE_SALARY. Click Next.
5. In the Attributes page, select the attributes that will participate in the key constraint. Click
the right arrow (>) to move the items from the Available list to the Selected list. Click
Next.
6. In the Properties page, specify details about the key constraint. Click Next.
11-440
7. When you are finished, click Finish to complete the wizard.
Related Topics
Editing an Entity (Key) Constraint
11-441
Specifying an Entity Constraint Name and Table
While you are creating an entity constraint with the Entity Constraint Wizard, use the Name
page to enter the Java name and the database name of the key object.
Field descriptions
Field Description
Name Type the Java name of the key constraint. You can enter a new name or
accept the default name provided.
Constraint Name Type the name of the key constraint that will be used in the database. You
can type a new name or you can accept the default name provided by
JDeveloper.
Related Topics
11-442
Selecting the Attributes Involved in an Entity
Constraint
While you are creating an entity constraint with the Entity Constraint Wizard or editing an entity
constraint with the Entity Constraint Editor, use the Attributes page to select the attributes that
will be participating in the key constraint definition.
Field descriptions
Field Description
Available A list of the object's attributes that can participate in the key constraint.
Select an attribute name and click the right arrow (>) to move it to the
Selected list. You can select more than one item by control-clicking. To
move all of the available attributes to the Selected list, click the double right
arrow (>>).
Selected The attributes that will participate in the key constraint. To remove an
attribute name, click its name, and then click the left arrow (<). You can
select more than one item by control-clicking. To remove all of the available
Related Topics
11-443
Specifying the Properties of an Entity Constraint
While you are creating an entity constraint with the Entity Constraint Wizard or editing an entity
constraint with the Entity Constraint Editor, use the Properties page to enter specific details
about the key constraint.
Field descriptions
Field Description
Key Type Specify the type of key constraint you want to create.
Primary The column or set of columns included in the definition of a table’s
PRIMARY KEY constraint. The attributes, or set of attributes, you
chose in the Attributes page will be interpreted as columns
participating in the table's primary key constraint. These attributes
will be used to represent unique values in the corresponding
database table columns; a primary key's values uniquely identify the
rows in a table. The primary key integrity constraint guarantees the
following:
● No two rows of a table have duplicate values in the specified

column, or set of columns.
● The primary key columns do not contain nulls (that is, a value
must exist for the primary key columns in each row).
Only one primary key can be defined in a table.
Unique The column, or set of columns, included in the definition of a table's

primary key constraint. A primary key's values uniquely identify the
rows in a table. You can define one or more unique keys for each
table.
11-444
Check condition The check integrity constraint does not use attributes. A CHECK
integrity constraint on a column or set of columns requires that a
specified condition be true for every row of the table. If a DML
statement results in the condition of the CHECK constraint evaluating
to false, the statement is rolled back.
If you select Check, you must also enter a condition. An example of

a condition would be a PL/SQL code fragment that checks that a
column value is non-null. The condition of a CHECK constraint has
some limitations:
● It must be a Boolean expression evaluated using the values

in the row being inserted or updated.
● It cannot contain subqueries, sequences, the SQL functions

SYSDATE, UID, USER, USERENV, or the pseudocolumns
LEVEL or ROWNUM.
Foreign references The column or set of columns included in the definition of a

referential integrity constraint.
If you select Foreign, you must also enter the foreign key references.
The attributes or set of attributes you chose in the Attributes page will
be interpreted as columns participating in a referential integrity
constraint. A referential integrity constraint requires that, for each row
of a table, the value in the foreign key matches a value in the primary
key. If you select Foreign, you must also enter the primary key (or
unique key) constraint name of a primary or unique key that the
foreign key references.
In the references field, type the primary key (or unique key)
constraint name that the foreign key references.
Cascade If you select this option, when rows containing referenced key values
Delete are deleted, then all rows in child tables with dependent foreign key
values are also deleted; that is, the delete "cascades".
For example, if a row in a parent table is deleted, and this row's

primary key value is referenced by one or more foreign key values in
a child table, the rows in the child table that reference the primary
key value are also deleted from the child table.
Key Properties Specify key validation options.
11-445
Mandatory If you select Mandatory, the column or set of columns must be non-
null.
Deferrable validation Indicates that constraint checking can be deferred until the end of the
transaction.
Initially Implies that this constraint is DEFERRABLE and specifies that, by

deferred default, the constraint is checked only at the end of each transaction.
validation
Disable validation Disables the constraint, drops the index on the constraint, and
disallows any modification of the constrained columns. Any new or
modified columns can violate the constraint.
Enable validation, The constraint is checked and must be true for all new and pre-
validate existing data existing column data.
Enable validation Is the same as ENABLE. The constraint is checked and is

guaranteed to hold for all new rows. Pre-existing column data is not
checked.
Related Topics
11-446
Code that Defines an Entity Constraint
While you are creating an entity constraint with the Entity Constraint Wizard, click Finish in the
Finish page to create the entity constraint. It is stored in the entity object's XML file. It also
appears in the Structure pane, under the Keys node, when you select the entity object that
contains it.
Entity constraints are business logic tier objects that represent database-level key constraints.
These constraints enforce integrity and help define the relationship between database tables.
When an entity object is created from a database object, database keys (such as PRIMARY
KEY, FOREIGN KEY, CHECK, and UNIQUE) are detected and corresponding entity
constraints are created automatically. These appear as properties in the Entity Object Wizard's
Attribute Settings page, and as keys in the Association Wizard's Attribute pages.
To create or modify key constraints, use the Entity Constraint Wizard and Editor to select the
attributes that will participate in the key constraint definition, and then specify the type and
details of the constraint. When database tables are forward-generated from business
components, the corresponding key constraints are created in the database as well.
Related Topics
11-447
Creating Database Tables and Constraints from
Business Components
The Create Database Objects Tool lets you create database tables based on the information in
entity objects and optionally associations and entity constraints (as specified in the Entity
Constraint Wizard). This is called forward generation.
To access the tool, in the the Navigator, right-click a business components package and choose
Create Database Objects.
WARNING: Be sure to archive existing data before creating new tables so that you can restore
it if necessary. You will need to drop any existing database objects that have the same name
as those used in the new database tables and key constraints. If there is data in an identically
named existing table, it will be lost if you proceed. A message box will warn you of this
beforehand.
Field descriptions
Field Description
Business Components A list of the entity objects in the current package. Each entity object has
information about the database object it represents. This database
information is used to determine the object to create.
Click > to move the selected items into the Objects to Create list.
Objects to Create A list of the selected objects that will be created when you click OK.
Note: For foreign keys to be created, both the source and destination
entities involved in the association must be inserted into the Objects to
Create list.
Click < to remove selected entity objects from the Objects to Create list.
Related Topics
11-448
Some ways to add validation logic are described in the following topics:
● Using a Domain as a Data Type for an Attribute
● Writing Validation Code in setAttribute Methods
● Writing Validation Code in the validateEntity Method
● Creating and Registering Validation Rule Classes
Related topics
11-449
Creating a Domain
The Domain Wizard helps you create domains. Follow these steps:
1. In the Navigator, right-click a package and choose New Domain to open the Domain
Wizard.
2. If the Welcome page appears, click Next to display the Name page.
3. In the Name page, specify a name. For example, SSNumberDomain. You could use it to
ensure that a Social Security number is unique. Specify whether you are defining a
domain for an Oracle Object Type. Click Next.
4. In the Settings page, select a data type and storage properties for the domain. For an
Oracle Object Type, in the Settings page, you specify different properties. Click Next.
5. Click Finish to close the wizard.
The Business Components for Java framework generates Java and XML code to
implement the domain object. The framework generates a domainName.java file for
each domain you create. For example, when you create SSNumberDomain, JDeveloper
generates SSNumberDomain.java.
You can now use the domain as an entity and view attribute type. You can modify the domain
Java file to add additional validation logic.
Related topics
What Is a Domain?
Editing a Domain
11-450
Specifying a Domain Name, Package, and
Optionally an Oracle Object Type
While creating a domain with the Domain Wizard, use the Name page to provide a name and
location for the domain object.
Field descriptions
Field Description
Type a name for the new domain type. The name should
Name
be a valid Java identifier and not a reserved word.
The name of the package that contains the domain
object. Click Browse to select a subpackage within this
Package project.
Domain for an Oracle Select this checkbox to create a domain that is an Oracle
Object Type Object Type. This will enable the list of Available Types.
Select an Oracle Object Type from this list. To enable
Available Types
this list, select the checkbox.
Type the name of an Oracle Object Type or select one
from the Available Types list. Type a new name to make
Selected Type a new domain type. Later, to create this type in the
database, in the Navigator, right-click a package and
select Create Database Objects.
Related topics
What Is a Domain?
Editing a Domain
Defining a Database Constraint by Creating an Entity Constraint
11-451
11-452
Ways to Specify Domain Attributes and Settings
You can specify domain attributes and settings in the following ways. The process is different if
you're defining a domain for an Oracle Object Type.
● Specifying Domain Attribute Settings
● Specifying Domain Attributes and Settings for Oracle Object Types
Related topics
What Is a Domain?
Creating a Domain
Editing a Domain
11-453
Specifying Domain Attribute Settings
While creating a domain with the Domain Wizard or editing a domain with the Domain Editor,
use the Settings page to specify attribute settings.
Field descriptions
You can specify the following settings:
● Attribute Type
● Persistent
● Discriminator
● Primary Key
● Mandatory
● Updateable
● Refresh After
● Column Type
● Queriable
● Unique
Related topics
What Is a Domain?
11-454
Specifying Domain Attributes and Settings for
Oracle Object Types
While creating a domain with the Domain Wizard or editing a domain with the Domain Editor,
use the Settings page to specify domain attributes and settings for Oracle Object Types.
Field descriptions
Field Description
edit. Its settings appear below it, where you can modify
them. To add an attribute, click New; in the dialog, type a
name and click OK. To remove an attribute, choose the
Attribute attribute and then click Remove. When you are editing a
domain, you can click Synchronize to access the
Synchronize Tool.
You can modify the following settings.
● Attribute Type
● Database Column Name
● Column Type
● Queriable
Related topics
What Is a Domain?
11-455
11-456
Editing a Domain
To edit a domain, in the Navigator, right-click the domain and choose Edit domain. Or double-
click it.
The Domain Editor lets you specify the following information:
● Specifying Domain Attribute Settings
For an Oracle Object Type, it lets you specify the following information:
● Specifying Domain Attributes and Settings for Oracle Object Types
You can specify properties from the editor, not the wizard.
Related topics
What Is a Domain?
Creating a Domain
11-457
Applying a Domain to an Entity Attribute
After you have created a domain object, you can use it as a data type for an attribute. For
example, you could create a domain named SSNumberDomain, and write validation code for it
that ensures that the resulting data type is a string of nine characters. You could then edit an
entity object and use SSNumberDomain as the data type for an attribute, as shown in the
following steps.
1. In the Navigator, right-click an entity object and choose Edit to display the Entity Object
Wizard.
2. In the Attribute Settings page, select the attribute in the Select Attribute drop-down list.
3. In the Type drop-down list, choose the domain (SSNumberDomain in this example).
4. Click Finish to close the wizard.
JDeveloper generates code to apply the domain to the attribute.
The following code, which would be used in the entity object's .java file, shows how domains
enforce validation rules. This code, contrived for the sake of simplicity, takes a string as an
argument and tries to create a social security number. If the string violates the validation logic
defined in SSNumberDomain, an exception is thrown.
public void createSSNumber (String newNumber) {

try {
SSNumberDomain SSNumber = new SSNumberDomain(newNumber);
// The new number is OK. Continue.
...
// The new number is invalid. Handle the error.
...
}
}
Related topics
11-458
What Is a Domain?
Editing a Domain
11-459
Writing Validation Code in setAttribute Methods
You can specify business logic by editing specific validation methods. You start by using the
Entity Object Wizard to add methods to an entity object. To write an attribute-level rule, use the
wizard to add accessor methods to the entity object. An accessor method has the general
name of getAttribute or setAttribute, where Attribute is replaced by the name of an entity's
attribute.
The Business Component for Java framework defines the signatures for these methods and
generates skeleton code; you add the code to implement the validation logic. For example,
given an Emp entity object, the framework could generate a setSal method to validate the Sal
attribute.
To write attribute-level validation code, edit an entity object's setAttribute method (use the
Entity Object Wizard to generate a skeleton). By default, the skeleton method contains a call to
Entity.setAttributeInternal. Insert your custom validation code before this call.
For example, suppose a Customer entity object has an attribute named creditCardNumber
that represents the customer's credit card number. To validate the number, the following code
calculates the sum of the digits and compares it to a given value. If the sum is less than that
value, the method throws an exception. Otherwise, the card number is valid, and the code calls
setAttributeInternal to continue the validation process.
public class Customer extends oracle.jbo.rt.Entity {
...
public void setCreditCardNumber(String cardNo) {

int checkSum = 0;
// Minimum value chosen arbitrarily for this example.

int MIN_VAL = 100;
// Assume the following card number format:

// "1234567890123456"
for (int i = 0; i < cardNo.length(); i++) {
checkSum += Integer.parseInt(cardNo.substring(i, i + 1));
}
if (checkSum < MIN_VAL) {

throw new JboException("Invalid card number");
}
11-460
// Continue the validation process.
// Generated calls follow.
setAttributeInternal(CREDTICARDNUMBER, cardNo)
}
...
}
The following example method enforces a rule that requires a unique key value before setting a
distribution ID. If the value is not unique, the method throws an exception; otherwise, it
continues with the validation process.
public void setDistributionId(Number quantity) {

Object[] reqDistKey = new Object[1];
reqDistKey[0] = this.distId;
// If the key exists, then it's not unique.

if (getDefinitionObject()
.findInstance((ApplicationModuleImpl)getApplicationModule(),
new Key(reqDistKey)) != null ){
throw new JboException("Must be unique");
}
// Generated calls follow.
setAttributeInternal( DISTRIBUTIONID, quantity );
}
Related topics
11-461
Writing Validation Code in the validateEntity Method
You can specify business logic by editing specific validation methods. You start by using the
Entity Object Wizard to add methods to an entity object.
To write entity-level validation code, enter the protected validateEntity() method in your
entity object's class file, call super.validateEntity(), and then enter your validation code.
For example:
protected validateEntity() {
super.validateEntity()
// ### Implement custom domain validation logic here. ### }
The Business Component for Java framework defines the signatures for these methods and
generates skeleton code; you add the code to implement the validation logic. For example,
given an Emp entity object, the framework could generate a validateEntity method to
validate the Emp entity as a whole.
Use entity-level validation when an entity object's validity depends on two or more attributes,
regardless of whether the attributes are related. For example, in a personnel-management
application an Emp entity object might only be valid if the relationship between the DateHired
attribute and the YearsOfService attribute is valid. Validation rules can also consider values
from other entities: the following code example evaluates values from the Emp and Dept entity
objects which are joined in a master-detail association.
public void validateEntity() {

// Generated call here.
super.validateEntity();
// Custom validation follows.

// Rule: Employees in ACCOUNTING cannot have Salary > 1500.
if (this.getDept().getDname().equals("ACCOUNTING") &&
(this.getSal().compareTo(1500) > 0) {
throw new JboException("Salary too high for ACCOUNTING.");
}
}
The following example method checks the values of three unrelated attributes. That is, none of
the attribute values is derived from the others. However, none of these attributes can have a
null value. If any of them is null, the method throws an exception.
11-462
protected void validateEntity() throws DataAccessException {
// Generated call here.

super.validateEntity();
// Custom validation follows.

//------------------ EDITCHECKS: HeaderId
Number reqHdrId = (Number)getHeaderId("HeaderId");
if (reqHdrId == null) {
throw new JboException("HeaderId is required");
}
//------------------ EDITCHECKS: Segment1

if ((getSegment1("segment1") == null) ||
(((String)getSegment1("segment1")).trim().equals(""))) {
throw new JboException("segment1 is required");
}
//------------------ EDITCHECKS: TypeLookupCode

if ((getTypeLookupCode("typeLookupCode") == null) ||
(((String)getTypeLookupCode("typeLookupCode")).trim().equals(""))) {
throw new JboException("typeLookupCode is required");
}
}
Related topics
11-463
Implementing a Validation Class
With the Business Components for Java framework developers can create classes and use
them to create validator types. A validation class must implement the JbiValidator interface,
which provides two key methods: vetoableChange and validateValue. The business
component framework calls vetoableChange and passes in a PropertyChangeEvent
when an attribute value is set. Typically, you implement vetoableChange to call
validateValue. If validateValue returns false, vetoableChange builds an exception
with information about what failed. Your implementation of validateValue can also throw an
exception of its own (which must extend ValidationException). See About Error Handling
for information about programming with exceptions.
The business component framework provides a skeleton class to which you can add code to
implement a validation class (or you can create one yourself from scratch). To generate the
skeleton class, do the following.
1. In the Navigator, right-click a business component project file, then choose Edit to
display the Business Component Project Wizard.
2. In the Registered Rules tab, click New to display the Validation Rule Wizard. Fill in fields
and choose options as desired for your class.
3. Click OK to close the Validation Rule Wizard, then click Finish to close the Business
Component Project Wizard.
The business component framework generates a Java skeleton class with the name you
specified. Add code to this class to implement your validation class.
After you have implemented your class, you need to make a change to the JDeveloper IDE
classpath to allow the Entity Object Wizard to access it:
1. In the Navigator, right-click your class and choose Make.

2. Close JDeveloper.
3. Navigate to <JDeveloper>\bin\jdeveloper.ini and add the following entry to the
IDEClassPath, so it can find the compiled validation class:
..\myclasses
11-464
4. Save jdeveloper.ini.
The following code implements a validation class named DemoCardValidator. In

validateValue it implements business logic that is too complex to define using the business
components' built-in rules. After compiling it, you can use it to create a validator type and then
apply it to an entity object (for example, to the CreditCardNumber attribute of a Customer
entity).
package d2e;
import oracle.jbo.server.rules.JbiValidator;
import oracle.jbo.server.util.VetoableChangeListener;
import oracle.jbo.server.util.PropertyChangeEvent;
import oracle.jbo.server.ValidationException;
public class DemoCardValidator implements JbiValidator {

private String description = " Verifies a credit card number. ";
private final int mMinValue = 100; // Arbitrary value for demo.
/**
* Return true if value is valid
*/
public boolean validateValue(Object value) {

// Validates a credit card number by comparing the
// sum of the digits to mMinValue, defined above.
int checkSum = 0;
// Assume the following card number format:

// "1234567890123456"
String cardNo = value.toString();

for (int i = 0; i < cardNo.length(); i++) {
checkSum += Integer.parseInt(cardNo.substring(i, i + 1));
}
return (checkSum > mMinValue) ? true : false;
}
11-465
/**
* Invoked by framework for validation
*/
public void vetoableChange(PropertyChangeEvent pce)

throws ValidationException {
Object newValue = (pce.getNewValue());
if (!validateValue(newValue)) {
Object objs[] = new Object[2];
objs[0] = pce.getPropertyName() + this.getDescription();
objs[1] = newValue;
String errCode = "001";
ValidationException ve = new ValidationException(errCode, objs);
throw ve;
}
}
/**
* Description of what this class validates
*/
public String getDescription() {

return description;
}
/**
* Description of what this class validates
*/
public void setDescription(String str) {
description = str;
11-466
Working with Custom Properties
Use custom properties to supply your own name/value pairs of business component metadata
which the framework can access at runtime. Properties are often user-supplied data that
provide hints, UI formatting clues, notes to users, etc. You can set custom properties on entity
objects, view objects, domains, and application modules, as well as the individual attributes of
an Entity or a view object.
The fundamental benefits of using properties are the following:
● You can set a property to any string value.

● Information is bound from the Design Time to the components as you select them.
● Every component can have its own property.
● Every attribute can have its own property.
● You can set any number of properties.
● Built-in inheritance of attribute-level properties.
● Properties can be set dynamically (at runtime) using APIs.
11-467
Overriding Property Values
Inheritance of Attribute-level Properties
You can set custom properties on Entity attributes, view object
For example, assume you have a Dept entity object with an attribute Dname of type (domain)
nameLength. The purpose of the nameLength domain is to limit the length of the department
name to a string of less than 10 characters. If you want to allow departments with longer
names, you can define a custom property on the Dname attribute to override the value of 10; for
example, a string length of less than 15.
Setting Multiple Levels of Properties
Custom property values set on view attributes override custom property values set on entity
attributes and domains. Thus, you can design multiple levels of property inheritance. For
example, a view object can have an attribute Dname of type (domain) nameLength which will
inherit the restriction on the length of the department name to a string of less than 10
characters. The view object can be defined with a custom property to override the value of 10
provided by the nameLength domain; for example, a string length of less than 20. Note that
the custom property on the Dname attribute in the view object will also override the custom
property value defined on the Dname attribute for the Dept entity object.
11-468
Getting and Setting Properties at Runtime
Advanced users can use the APIs to dynamically set properties at runtime. For example, one of
the APIs you can use is the setProperty(String name, String value) method. This
method is available for all component objects. For entity attributes, you can either set properties
on entity attributes from methods on the EntityDefImpl class or by calling:
entity.def.getAttributeDefImpl(i).setProperty(name, value);
For view attributes (in local mode):
((AttributeDefImpl))vo.getAttributeDef(i)).setProperty(name, value);
11-469
Using Properties to Dynamically Create a UI
The real power of setting custom properties is when you are using them to drive runtime
behavior. A typical situation might be when you are laying out a presentation space and want to
use a mask (or picture string). For example, to define properties for a string that represents a
social security number, you could create a Property Name of SSN-MASK with a Property
Value of 000-00-0000. At runtime you could evaluate the property name and apply the proper
formatting when appropriate.
Related topics
Using XML Metadata Properties that Affect XML Generation
11-470
Ways to Handle Errors in Business Component
Applications
code), throw an exception, or both. Following are some recommendations.
The following topics describe how to write error-handling routines:
● Handling Errors Using Error Codes
● Handling Errors through Predefined Business Component Exception Classes
● Creating Custom Business Component Exception Classes
● Trapping Business Component Exceptions on a Client
● Customizing Error Messages
● Using Bundled Exceptions
11-471
Handling Errors Using Error Codes
Use result codes (also called error codes) to indicate minor errors and issue warnings. A result
code can be a simple Boolean value (typically, true indicates success, false indicates an
error), or it can be a numeric value. The following code shows a setSize method that returns
an integer as a result code.
// (Optional) Declare symbolic constants to represent code values.

public final int TOO_SMALL = -1;
public final int OK = 0;
public final int TOO_BIG = 1;
...
public int setSize(int newSize) {

if (newSize < 15) return TOO_SMALL;
if (newSize > 37) return TOO_BIG;
mSize = newSize;
return OK;
}
Code that calls setSize should test the return value to check for errors. For example,
public void grow(int amount) {

int result = setSize(amount);
String msg = "";
switch (result) {
case TOO_SMALL :
msg = "New size is too small.";
break;
case TOO_BIG:
msg = "New size is too big.";
break;
case OK :
msg = "New size is OK.";
break;
}
System.out.println(msg);
}
11-472
11-473
Handling Errors through Predefined Business
Component Exception Classes
Use exceptions to indicate serious or unexpected error conditions, conditions from which the
program cannot easily recover. This topic presents the following information:
● About Java exceptions
● About exception classes
● Returning a Localized Error Message
● Marshaling Exceptions Across a Network
About Java Exceptions
Java exceptions fall into two categories: either they extend java.lang.RuntimeException
(these are called implicit exceptions) or they do not (these are called explicit exceptions). When a
method uses an explicit exception to indicate an error, a Java program requires:
● A throws clause in the method signature that declares the type of exception the method will
throw when an error occurs.
● A throw statement in the method body that creates and throws an exception of the type
specified in the signature.
The following code shows a method getCustName that declares and throws a
ValidationException.
public String getCustName(Customer cust) throws ValidationException {

String name = cust.mName;
if (name == null) {
throw new ValidationException();
}
return name;
}
When you write code that calls a method that throws an exception, enclose the call in a
11-474
try...catch block. For example, the following code calls getCustName, a method defined to
throw a ValidationException. The try keyword indicates that you are about to call one or more
methods that throw exceptions. The catch keyword marks the beginning of a code block that
executes only when an exception is thrown.
public printName(Customer cust) {

try {
// Call the method(s) here.
getCustName(cust);
catch (ValidationException dae) {
// Handle the error here.

System.out.println(dae.getMessage());
}
}
Java programs are more lenient about implicit exceptions: they do not have to be declared or caught.
You can write a method that throws a RuntimeException (or a subclass of RuntimeException)
without declaring it in the method signature (although you can do so, if you prefer).
About Exception Classes
The Business Components for Java framework provides many exception classes (for example,
ValidationException and NameClashException). These classes extend
oracle.jbo.JboException, which extends java.lang.RuntimeException. Therefore, a
business component method can throw a Business Components for Java exception without a
throws clause in the signature.
Business Components for Java exceptions have an attribute that stores an error message, and they
support NLS translation and message formatting. JboException uses
java.util.ListResourceBundle to format its messages. A resource bundle class defines
constants and strings to use as error messages. The default format is:
{productCode}-{errorCode}: {messageBody}
For example,
ORA-10234: You cannot do that.
Business component exception messages are derived from the following generalized set of
parameters. The table lists each parameter followed by an example of the parameter.
11-475
Parameter Example
Product code "OBCJ"
Error code "03101"
ResourceBundle "oracle.jbo.CSMessageBundle"
an optional set of parameters "Vendor", "Oracle"
Any exception thrown in low-level code that is transformed
details
into a business component exception.
Messages may need to include information known only when the exception is thrown, so error
message strings can include placeholders that refer to values in an array of Objects passed to the
exception when it's thrown. When the message is formatted for display, these parameters are placed
into slots in the message (the first slot is 0) using the standard formatting capabilities provided by
java.text.MessageFormat. Following is a an entry from CSMessageBundle.java.
public static final String EXC_VAL_ATTR_SET_FAILED = "03101";

...
// Description: Generic Attribute validation failure.
// set<Attribute> method failed to set the value.
// Parameter 0: Ignored.
// Parameter 1: Entity Object/View Object name.
// Parameter 2: Attribute name.
// Parameter 3: New value
{EXC_VAL_ATTR_SET_FAILED, "Attribute set with value {3} for {2} in {1} failed."},
The JboException class provides the following methods for working with exceptions.
Method Description
JboException(String message, Create a Formattable Exception Object.
String errorCode,
Object[] params)
JboException(Class Create a Translatable Exception Object.
resBundleClass,
String errorCode,
Object[] params)
String getProductCode() Return the Product code for the Message.
String getErrorCode() Return the Error code.
String Return the Message in the specific Locale.
getLocalizedMessage(Locale loc)
11-476
Object[] getDetails() Details are usually used to accommodate
lower-level exceptions. For example, if a
SQLException is thrown in some low-level code, the Business Components for
Java
framework can catch it and represent it as
one of the business component exceptions.
The original SQLException becomes
the first entry in the detail.
String getResourceName() Return the name of the ResourceBundle used to
resolve messages.
Object[] getErrorParameters() Return the Parameters to the Error.
Using JboExceptionHandler
JboExceptionHandler is user-installable exception handler for three-tier applications. When

exceptions are brought over through the piggyback mechanism, the normal Java language throw
does not quite work, because (among other things) the piggyback may have carried back more than
one exceptions. Thus, instead of throwing the exception, a method on the JboExceptionHandler
interface is invoked with each exception unloaded from the piggyback.
JboExceptionHandler defines:
void handleException(Exception ex, boolean lastEntryInPiggyback);
Where ex is the exception unloaded from the piggyback and lastEntryInPiggyback is a flag
indicating whether the exception was the last entry on the piggyback. (Note that for two-tier execution
there is no piggyback.)
If you do not install your own handler, the default handler is used. The default handler is
implemented by the application module. (At the interface level, ApplicationModule implements
JboExceptionHandler.) For jbo.client.remote, this implementation ignores the exception if
lastEntryInPiggyback is false. If lastEntryInPiggyback is true, the exception is thrown.
To install your own handler, call the following method on the application module interface:
void setExceptionHandler(JboExceptionHandler hndlr);
and pass in your own implementation of the JboExceptionHandler interface.
11-477
11-478
Returning a Localized Error Message
To make an exception localizable into different national languages, use the NLS framework.
First, create a resource bundle for your error messages. The following code example defines a
bundle named MyMsgBundle that stores three error messages.
import oracle.jbo.common.util.CheckedListResourceBundle;
public class MyMsgBundle extends CheckedListResourceBundle
// String Constants
public static final String BAD_EMPNO = "101";
public static final String DEPT_NOT_FOUND = "102";
public static final String NOT_IN_DEPT = "103";
...
/**
* Private 2-D array of key-value pairs
*/
private static final Object[][] sMessageStrings = {
...
{ BAD_EMPNO, "Invalid employee number." },
{ DEPT_NOT_FOUND, "Department {0} does not exist." }
{ NOT_IN_DEPT, "Employee {0} not found in Department {1}." }
...
}
}
Then you can use the resource bundle class to define a value to pass to the constructor for
your exception class or JboException.
throw new JboException(MyMsgBundle.class /* Class of Bundle */,

MyMsgBundle.DEPT_NOT_FOUND /* String Constant */,
new Object[1] { localVar1 } /* Arguments to message */
);
JboException provides a getLocalizedMessage method which returns the message

formatted for the specified locale.
The NLS framework translates the message text when the client calls
getLocalizedMessage rather than at creation time because the client may need to present
the message in a number of different languages. This mechanism provides a single point for
localizing and formatting messages.
11-479
Marshaling Exceptions Across a Network
JboException can marshal itself across a network. It handles NLS issues for the business logic tier, enabling
one instance of a business logic tier component to serve (for example) French users and English users at the
same time.
If your exception contains member data that must be marshalled, extend JboException. If you need to provide
more control over the serialized stream, implement the readObject and writeObject methods. The Java
serialization mechanism uses these methods to serialize/deserialize an object. You might want implement these
methods if you want to:
● add derived information to the serialized stream which is not present in a member variable of your class
● exclude some members from being serialized
For example, suppose you have the class MyException (shown below), and you want to carry memberA and
memberB across tiers:
public class MyException extends JboException

{
int memberA;
String memberB;
...
}
Write code like the following in MyException:
private void writeObject(ObjectOutputStream out) throws IOException {

out.writeInt(memberA);
out.writeUTF(memberB);
}
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {

memberA = in.readInt();
memberB = in.readUTF();
}
11-480
Creating Custom Business Component Exception
Classes
You can use Business Component for Java exception classes in your own code to indicate
errors, and you can create custom exception classes. For example, you can extend
JboException and override the getProductCode method, making it return values
appropriate for your exception.
You can throw a JboException by using a statement like this:
throw new JboException("Don't do that.", "101", null );
The drawback to this approach is that the hard-coded error message is not easy to localize.
11-481
Trapping Business Component Exceptions on a
Client
Clients, whether running local or remote, can trap Java exceptions thrown by the business logic
tier. Business logic can catch exceptions as needed, as in the following example:
try {
...
// This might cause an error.
empRow.lock();
...
} catch ( AlreadyLockedException lfe )
{
// Handle the error here.
11-482
Using the API to Customize Entity Objects and
Associations
Here are some ways you can use the business component framework API to customize entity
objects and associations. See the Javadoc and the tutorials for more information.
● Getting and Setting Properties at Runtime
● Applying Unposted Changes to Entity Rows Queried from the Database
● Implementing Transaction Locking in Code
● Calling Stored Procedures
11-483
Applying Unposted Changes to Entity Object Rows
Queried from the Database
When you call association accessor methods in an entity object, such as getEmployees on a
DepartmentImpl class representing department 20, you get back a RowIterator over a set
of related EmployeeImpl objects for the employees in that department. This entity object
rowset of appropriate employee instances associated with department 20 is produced by
querying the database, so existing employees assigned to department 20 will always show up
in the associated entity object rowset.
During the current session, new Employee entity objects may be created and existing
Employee entity objects may be modified. By default, unless these new and modified Employee
entity objects are posted or committed, they would not appear in the entity object rowset
returned by a subsequent call to getEmployees on the same Department entity object later in
the session. If you want the business logic tier to perform the extra bookkeeping necessary to
provide a cache-consistent entity object rowset, including any appropriate new and modified
entity objects (in addition to the existing queried entity objects already reflected in the
database), you need to run in full EntityRowSet consistency mode.
There are two approaches to accomplish this:
● If you want all entity object rowsets created by association accessor methods in your
application to consistently include appropriate unposted new and modified entities, then
provide the following Java VM parameter on your runtime command line:
-Djbo.entityrowset.mode="NEW_AND_MODIFIED"
● If you only want to incur the additional overhead of presenting a cache-consistent view of
associated entity objects for a particular rowset, you can call the following on just that
rowset:
yourRowset.setAssociationConsistent(true);
Related Topics
11-484
Implementing Transaction Locking in Code
A multi-user application must control concurrency, the simultaneous access of the same data
by many users. Otherwise, data could be updated or changed improperly. Concurrency control
is managed through the Transaction interface. This topic describes how transactions fulfill
the following important requirements of an information management system:
● Data must be read and modified in a consistent fashion.
● Data concurrency of a multi-user system must be maximized.
● High performance is required for maximum productivity from clients.
Transactions use locks to control concurrent access to data, achieving two important database
goals:
● Consistency ensures that the data you are viewing or changing is not changed by other
● Integrity ensures that the database data and structures reflect all changes made to them
in the correct sequence.
The Business Components for Java framework supports a locking model that provides the
following features and benefits:
● A lock is placed even if inconsistency is detected.
● It can determine that inconsistency is due to DELETE or UPDATE of data.
● It supports business logic tier server comparison of original data columns.
● Data is retrieved to correct inconsistencies when they occur, with no further roundtrips
required.
Using the Business Components for Java framework, you can request locks on rows in entity
objects or view objects. Locking an entity object row places a database lock on that row. When
11-485
locking a view object's row, the framework requests locks on those Entity rows that are used in
the view object's row.
Business Components for Java supports the locking styles listed in the table below. Each style
represents a trade-off between scalability, performance, and consistency of data. For example,
placing database locks early (pessimistic locking) reduces scalability but decreases the
likelihood of data inconsistencies. When you change the locking style, the change only affects
subsequent locks. Locks already in place do not change.
Locking Style Comments

Pessimistic Locking Locks are automatically placed upon the underlying row immediately before the first
client change is made. This is the default style for application modules.
Represented by the constant Transaction.LOCK_PESSIMISTIC.
Optimistic Locking Locks are automatically placed upon the underlying row during the "save to
database" logic. Represented by the constant Transaction.LOCK_OPTIMISTIC.
Explicit Locking Locks are manually placed, at the correct point in time, by explicit calls from the
client. If no lock calls occur, then only the database locks, obtained when the rows
are flushed to the server, are obtained. Represented by the constant
Transaction.LOCK_NONE.
The following code example demonstrates pessimistic locking mode:
if ( myEntity.getPostState() != Entity.STATUS_NEW
&& myEntity.getDBTransaction().getLockingMode()
== Transaction.LOCK_PESSIMISTIC
&& !myEntity.isLocked()
)
{
myEntity.lock();
}
return myEntity;
About Lock Failure
Locks may fail for any of the following reasons:
● The resource is held by another user.
● The resource has been deleted from the Database.
● The resource changed since the entity cache was populated.
11-486
● Some general SQL error condition (such as the database going down).
In each case, a different type of error is raised to indicate the problem. This permits higher level
callers to indicate the error in question, and potentially retry the operation.
Releasing Locks
After a lock is placed on a given object, it is added to the list of Transaction participants. After
the Transaction performs a commit or rollback operation, each Transaction participant is
notified of the outcome of the operation. Each object is given an opportunity to release any
internal state, such as lock indicator flags, that it may hold during this notification cycle.
About Low-level Locking
Independent of the locking style selected, the low-level APIs permit the explicit locking of view
and entity rows by calling their lock method at the appropriate time.
After the initial lock call for a given row object, subsequent calls are ignored unless the
corresponding database transaction has had the commit or rollback operation performed,
because locks are automatically released at these times.
The call to place a lock can fail for a number of reasons:
● Resource held by another user.
● Resource deleted from the database.
● Resource changed since the entity cache was populated.
● General SQL Error condition (such as the database going down).
In each case, an exception is thrown to indicate that a problem occurred. These exceptions can
also occur at other times, such as changing the value of a column, because locks can be
placed implicitly at that time.
An Entity Row provides a method for testing the locked status, as follows:
11-487
/**
* Is the Row locked?
**/
public boolean isLocked()
11-488
Calling Stored Procedures
You can call stored procedures instead of using the default Business Components for Java
logic for create, update, delete, lock, and fault-in, or any combination of them.
If you have existing PL/SQL packages that encapsulate the select, insert, update, delete, and
lock behavior for a particular application database table, you can override the built-in entity
object framework methods doDML() and doSelect() to completely base all database
persistence operations for an entity object on your existing package, as shown in the following
code sample. Note that you can generate skeleton code for the doDML method in the Entity
Object Wizard or Editor.
In this topic, first the stored procedure and entity object code are listed, followed by an
explanation.
Here is the SQL stored procedure:
"frags/storedprocsql.frag"><storedprocsql.frag in stproc.sql>
Here is the entity object code:
"frags/storedproc.frag"><storedproc.frag in DepartmentsImpl.java>
The code in doSelect calls the appropriate overridden helper method depending on whether the
framework is faulting in the row based on its primary key, through doSelect(false), or to lock the
existing row, through doSelect(true).
The code in doDML calls the appropriate helper method depending on the value of the
operation it's being asked to perform.
Each of the helper methods uses the createCallableStatement method on the DBTransaction
interface to create a JDBC callable statement, bind its parameters, and then execute it.
The helper method for locking checks the Dname and Loc attributes after acquiring the lock to
make sure that the row has not been changed by a different transaction between the time the
current user selected it and the time that they are trying to modify it.
The DBA can now revoke insert/update/delete privileges from the Department table completely,
and all DML operations will be routed to the stored procedures for Dept entities that are
created, modified, or deleted.
11-489
Related topics
11-490
Working with View Objects, View Links, Application
Modules, and Clients
In the help contents, this book is divided into two main books:
● Understanding View Objects, View Links, and Application Modules
● Creating and Modifying View Objects, View Links, and Application Modules
11-491
Understanding View Objects, View Links,
Application Modules, and Clients
These topics describe important concepts about view objects, view links, and application
modules:
● What is a View Object?
● What Is a View Link?
● What Is an Application Module?
● When to Put Code in an Application Module or a View Object
● About Master-Detail Views
● About Application Module Pooling
● About Connection Pooling
● What is a View Attribute?
● About Transactions
● About Managing Rows in Memory at Runtime
● About Testing Business Components within JDeveloper
● About Business Component Properties
11-492
When to Map View Objects to Entity Objects
Generally, you want view objects to be associated with entity objects. This allows the rowsets
to support updates, inserts, and deletes with automatic triggering of business logic in the
underlying, related entity objects. Updates made through any view object in your session
automatically show up in other view objects displaying the same logical entity attributes. This
behavior is only possible when the view object and entity object are related. However, using
entity objects causes more objects to be created at runtime and placed in the cache, so you if
you don't need the benefits of entity objects, you don't need to use them.
If your view object only queries data and never inserts, updates, or deletes, it should usually not
be related to entity objects because this may not add useful functionality. There are two
exceptions to this rule:
● If you have a lot of repeated data because of a join, you can save memory by using
entity objects. For example, if you have a Dept table joined to an Emp table, department
information would be repeated for each employee, if you do not use entity objects.
● If multiple view objects access the same data, and one or more view objects can update,
insert, or delete data, then you might want to map all view objects to the entity objects so
the view objects can immediately see any unposted changes.
However, it is important to associate your view object to an entity object:
● When you want your view object to be notified that another updateable view object has
modified the same data.
● When you need to scroll and cache the read-only result.
● When the query is a join query.
When you will be joining tables that will result in much repeated data in each row (for
example joining EMP/DEPT where 100 rows in the join all come from Department 10). In
this case, associating your view object to an entity object will save significant memory
since Business Components for Java will only cache one entity object row for
Department 10 once. The 100 EMPs will reference the information for Department 10.
When to make view objects forward only
11-493
Under certain circumstances you can use ForwardOnly mode for your view object to save
memory and time by not caching any row data (vo.setForwardOnly(true)). For example,
use ForwardOnly mode:
● When you do not need to scroll backward through the results.
● When you do not iterate the results multiple times.
● When you do not refer to them again in the same session (for example, when you simply
print out the rows to a web page).
11-494
When to Put Code in an Application Module or a View
Object
An application module can store application-specific code on the business logic tier. For example, suppose
a view object named EmpView is shared by two client applications, and one client needs to calculate the
sum of all employee salaries each time a row is added to the view. You could add the code directly to
EmpView, but doing so increases the effective size of the object, adding to the processing burden on
every client and application that uses it. A more efficient approach is to add the code to the application
module. That way, the custom code is available only to clients that need it. The following figure shows both
approaches.
Code attached to an application module executes in the business logic tier, which will be more efficient
than executing the code on the client. For example, suppose a client form needs to calculate a value
based on values in a table. If that table contains (for example) 130 rows, the calculation requires that all
130 rows be brought to the client, resulting in 130 network round trips. Client-side performance can
deteriorate when working with large tables.
11-495
When the code resides in the application module, the data stays in the business logic tier. Performance is
optimized, because the client gets the result in a single network round trip. The Business Components for
Java framework handles the details of making selected application module methods available to clients.
11-496
11-497
About Master-Detail Views
View links affect the behavior of view objects within an application module. When a view object is used as
the detail end of a master-detail view link, it selects the restricted view specified by the association that
defines the view link. "Restricted" means that the data from the detail view object only shows rows that are
related to the current row in the master.
When it is not involved in a master-detail view link, a view object offers an unrestricted view of the data. That
is, all rows of data are available. For example, the following figure illustrates a situation where a project
provides two views, DeptView and EmpView, of the DEPT and EMP tables. For the purposes of an
application, you define aliases of the views: MyDeptView, MyEmpDetailView, and MyEmpView. You link
MyDeptView and MyEmpDetailView master-detail. In this case, the employee data available from
MyEmpDetailView depends on the current value from MyDeptView. For example, it will display only those
employee names associated with the current department number.
In MyEmpView, the view is unrestricted: all of the data from the EMP table is available. DeptView and
EmpView are view definitions.
The next figure shows MyEmpView operating without restrictions and fetching the specified columns from
every row of the EMP table.
11-498
In contrast, MyEmpDetailView is the detail end of a view link. Its result set is restricted by one or more
bind values, defined by the attributes of the view link. Therefore, it fetches only those rows containing the
specified bind values. The view link is effectively adding a WHERE clause to the SQL statement that defines
the view object. For example, the following figure shows MyEmpDetailView being used in the
DeptViewToEmpView link. Here, the bind value (defined by MyDeptView's deptno attribute) is 20, so
MyEmpDetailView fetches only rows where deptno equals 20. Bind values are provided by the master
view.
11-499
In summary, a detail view object in a view link selects a restricted view of the underlying data based on bind
values supplied by the master view. To select an unrestricted view, define a separate view object in the
application module. The code example below shows the different behavior of restricted and unrestricted
views, and how a detail view depends on the master view for bind values.
package d2e;
public class AliasDemo {

// Helper routine connects to the generic application module.

ApplicationModule appMod =
QueryDemo.getGenericAppMod(JboContext.PLATFORM_LOCAL);
// Call method to get UnrestrictedView.

ViewObject voEmp = appMod.findViewObject("MyEmpView");
printRows(voEmp); // Prints all rows in EMP.
// Assume MyDeptView and EmpView were linked

// master-detail at design time.
voEmp = appMod.findViewObject("EmpView"); // Restricted view.
printRows(voEmp); // No master view yet, so no rows printed.
ViewObject voMaster = appMod.findViewObject("MyDeptView");

voMaster.first(); // Get bind values from first row of master table.
printRows(voEmp); // Prints restricted view.
}
public static void printRows(ViewObject vo) {

System.out.println("ViewObject :"+vo.getName()+" - RowCount:"+vo.getRowCount() );
// Execute the query, print results to the screen.

vo.executeQuery();
while (vo.hasNext()) {
Row row = vo.next();
String rowDataStr = "";
// How many attributes (columns) is the view object using?

int numAttrs = vo.getAttributeCount();
// Column numbers start with 0, not 1.

for (int attrNo = 0; attrNo < numAttrs; attrNo++) {
// See also Row.getAttribute(String name).

Object attrData = row.getAttribute(attrNo);
11-500
rowDataStr += (attrData + "\t");
}
System.out.println(rowDataStr);
}
}
}
About View Links and Events
When two view objects are linked in a master-detail relationship, the default iterator for the master view
object fires events to refresh the detail view object. When the detail view object is created, the Business
Component for Java framework registers it as an event listener for the master's iterator. Thus, when the
iterator moves to another row in the master view object, the contents of the detail view object are refreshed
automatically, as shown in the following figure.
Figure 1:
The following code example assumes that an application module has been defined at design time to include
at least one view link. The code initializes the application module, gets the first link, gets the master and
detail view objects from the link, then displays each master row and the linked detail rows.
package d2e;
public class LinkDemo {


ApplicationModule appMod = QueryDemo.getGenericAppMod(JboContext.PLATFORM_LOCAL);
11-501
// Get the first link defined in the application module.
String[] linkNames = appMod.getViewLinkNames();
if (linkNames.length < 1) {
System.out.println("\n No links.");
return;
}
ViewLink link = appMod.findViewLink(linkNames[0]);
// Get view objects defined in the link.

ViewObject voMaster = link.getSource();
ViewObject voDetail = link.getDestination();
// Execute query and move through the master rows.

voMaster.executeQuery();
while (voMaster.hasNext()) {
printRow(voMaster.next());
// JDeveloper automatically refreshes the detail result set.

// Move through linked detail rows.
while (voDetail.hasNext()) {
printRow(voDetail.next());
}
}
}
// This is a helper method that prints data to the screen.

public static void printRow(Row row) {
String rowAttrs = "";
for (int i = 0; i < row.getAttributeCount(); i++) {
rowAttrs += (row.getAttribute(i) + "\t");
}
System.out.println(rowAttrs);
}
}
The next figure shows the event flow between master and detail view objects. When you define a link, the
Business Components for Java framework registers the detail view object to listen for events from the
corresponding master view object. When the current row in the master view object changes, the framework
fires an event and the detail view object responds by refreshing the detail view object. This action in turn
fires another event, which can be handled by registered listeners, if any.
11-502
11-503
An attribute is a characteristic of an entity object or view object, implemented as a JavaBean
property of the object class. An attribute can correspond to a SQL query result column, or be
independent of a column. There are five kinds of attributes:
Attribute Value derived from a Persisted in the database? Based on an entity attribute
kind database query? (cached at the entity level)?
persistent yes yes (the value outlives the class yes

that created it)
transient no no no
entity- no no yes
derived
SQL- yes no no
derived
dynamic no no no
Entity objects can have the following kinds of entity attributes:
● Persistent. A entity attribute that is persisted in the database (the Persistent attribute
setting is selected).
● Transient. A entity attribute that is not persisted in the database (the Persistent attribute
setting is deselected).
View objects can have the following kinds of view attributes:
● Persistent. A view attribute based on a persistent entity attribute. The data is cached in
the entity cache. For example, if you want to store data changes in the datasource, you
need a persistent view attribute.
● Entity-derived. A view attribute based on a transient entity attribute. The data is cached
in the entity cache and you can share it across multiple views.
● Transient. A view attribute that is not based on an entity attribute and does not contain a
SQL expression. The data is cached in the view cache. You write Java code to populate
the attribute.
11-504
● SQL-derived. A view attribute that is not based on an entity attribute and does contain a
SQL expression. The data is cached in the view cache.
● Dynamic. A view attribute that is created with the addDynamicAttribute method. You can
use it to store information created at runtime that you want to store with the row data. It is
used only by the view object that created it. Dynamic attributes are handled the same
way as design time attributes. Attributes can be any Serializable object. The data is
cached at the view object level.
The value of a SQL-derived attribute is the result of a SQL statement. For example, a
YearsOfService attribute might be the difference between an employee's hire date in the
database and the current date. Alternatively, you could create a transient attribute and write
code to perform a calculation in a Java file to set its value. In general, using SQL-derived
attributes is more efficient than performing data-intensive calculations in Java.
You can determine an attribute kind with the getAttributeKind method. Note that the
method refers to entity-derived attributes as row-associated.
In Business Components for Java, the term attribute is based on the UML definition, not the
XML definition. In UML, an attribute is a named property of a class that describes a range of
values that instances of that class might hold.
Related topics
Ways to Edit View Attributes
11-505
About Exposing View Links to Entity Objects
JDeveloper makes it possible for you to use the relationships defined by view links to better
define the results obtained while traversing entity objects. JDeveloper does this by letting you
create a method inside an entity object that provides easy access to data returned by the view
link. This feature has these advantages:
● Allows you to more easily access predefined view object result sets for use in defining
rules or calculated attributes in your entity object. Most of the interesting coding is done
at the entity object level—that is where you implement your business validation.
● Allows you to work with a smaller dataset. view links restrict the number of rows that are
returned based on a given condition; view objects can restrict the columns. This allows
the view link accessor on the entity object to make available just the data you need for
any calculation or business logic at the entity object level.
The view link makes it easy to write business logic which traverses from one object to a related
object. The view objects which comprise the view link allow arbitrary PL/SQL statements.
These statements can enable complex filtering and restriction of related datasets. Exposing the
view link as an entity accessor means that you can further enhance your business logic
programming model with prebuilt "finders" that find related collections of more interestingly
qualified pieces of dependent data.
The accessor can only exist on the entity object which corresponds to the selected attributes in
the source view object of the view link. Like view links, the accessor is unidirectional: the
accessor works with data in the detail view object.
What Gets Returned?
The accessor on the entity object passes parameters into a new view object which it
instantiates. The data in the view object is whatever data is defined by the entity object row, the
specified view link, and view object.
For example, as illustrated in the following figure, assume you have created the Dept and Emp
entity objects and their corresponding view objects. The Dept entity object has three rows,
corresponding to department numbers (Deptno) 10, 20, and 30. In the Emp entity object, all
terminated employees have their employee ID (Empno) set to -1. Assume also that a view link,
DeptToEmpVL, has been defined from Dept as the source, to Emp on the Deptno attribute. In
this case, the Dept entity object can instantiate a view object containing employee data
11-506
corresponding to department 10. It can also instantiate a view object containing employee data
corresponding to department 20, and so on.
You can define an accessor in the Dept Entity, getTerminatedEmps, that will return the
records of employees whose Empno is less than 0. This accessor works by searching the view
object containing employee data corresponding to a specified department number. The
accessor will return an iterator into the records that match Empno<0 for the current Dept row.
Working with Multiple Levels of Detail
As described above, the accessor on the entity object can traverse the view link to use data
returned by the destination view object. If you have multiple levels of detail in your application
module, once you get the view object result set, you are free to use any of the data that it
returns.
11-507
Related Topics
Exposing View Links to Entity Objects
11-508
About the Business Component Fault-in Mechanism
The Business Components for Java framework lets you define entity objects (mapping tables to
Java classes) and lets you build view objects using SQL statements over the tables to which
entity objects are related. The SQL SELECT statement associated with a view object lets you
select just the "slice" of relevant information from the tables related to the entity object. You can
select all, or only some of the attributes in the underlying entity object.
When you create the view object, you are encouraged to include only the attributes that the
client needs to work with. For example, suppose that you are writing a client application that
displays a list of 10 attributes in a form which a user can edit. Also suppose that the table
associated with the entity object, contains a total of 200 attributes. In this case, you can design
a view object that contains only the 10 attributes that will be displayed on the client. Note that
one of the attributes must be a primary key. If you use the JDeveloper View Object Wizard to
construct the view object, it will automatically include the primary key.
When the view object is executed, its SQL statement is sent to the database. This statement
will select the 10 attributes including any primary key columns. The framework uses the primary
key columns to uniquely identify each entity object instance: each instance corresponds to a
row in the database table. The entity object in its partially populated state (10 attributes
populated) is put in the entity cache.
Applications frequently read much more data than they write. So it is important that applications
performing reads and lookup only retrieve and cache just the information it needs. In the
example described above, only the 10 attributes are retrieved and put in the cache; the
remaining 190 attributes referenced by the entity object are not. This results in a savings in
terms of memory and performance.
If the user on the client enters a value that causes the business logic to ask for the value of one
of the excluded 190 attributes, then the framework uses the primary key value to go to the
database and retrieve all of the 200 attributes for the row. This is what the framework refers to
as "fault-in": the client's attempt to access an excluded attribute causes the entity object to
retrieve all of the attributes. Fault-in occurs on the entity object instance level. After the fault-in,
the cache contains one fully populated row which was the result of the fault-in.
When you design a view object, consider the following:
● Ensure that the view object's attribute list includes those attributes that are frequently
accessed. It must also include the primary keys from the tables corresponding to the
entity objects on which the view object was built.
11-509
● The Business Components for Java framework allows the client to access attributes that
were not included in the view object's attribute list. However, remember that accessing
excluded attributes will cause a fault-in, and the you will incur a memory and
performance cost. Too many fault-ins will lower performance significantly. It is important
to fine tune the view attribute list, particularly for entity objects that include many
attributes.
Fault-in Example
The following example, although clearly contrived, illustrates how a request for an excluded
attribute can trigger the fault-in mechanism.
Define a table in the database that defines the following employee information: employee
number, employee name, job title, hire date, and salary. The table definition would look like
this:
CREATE TABLE ORACLE_EMP

(EMPNO NUMBER(4) NOT NULL,
ENAME VARCHAR2(10),
JOB VARCHAR2(9),
HIREDATE DATE,
SAL NUMBER(7,2),
CONSTRAINT EMP_PRIMARY_KEY PRIMARY KEY (EMPNO));
Use JDeveloper to create a business components project. In the wizard, select the
Oracle_EMP table (this will create an OracleEmp entity object) and select the View Objects
and View Links and Application Module checkboxes. In the wizard, define the following
mappings for OracleEmp's attributes:
EmpNum -- EMPNO
EmpName -- ENAME
EmpJob -- JOB
EmpHireDate -- HIREDATE
EmpSal -- SAL
When the wizard asks you to select the view attributes to map, select the following:
EmpNum (corresponds to primary key)

EmpName
EmpJob
11-510
This creates the view object query:
SELECT (OE.EMPNO AS EMP_NUM, OE.ENAME AS EMP_NAME, OE.JOB AS EMP_JOB)

FROM ORACLE_EMP OE;
Where OE is the alias for the ORACLE_EMP table.
Now suppose that you create business logic that validates salary when the job changes. This
logic would be a validation on the setter method of the Job attribute (in the Emp entity object).
public void setJob(String value) {
// Retrieve the salary out of the entity.
// When getSal() is called on the entity the

// framework faults in all the excluded attributes.
Object sal = getSal(); // this line causes a fault-in
setAttributeInternal(JOB, value);
}
The getSal() method will attempt to fetch the value of Sal from the Entity cache. However,
since Sal was excluded from the SELECT statement, it will not be present. In response, the
Business Components for Java framework will fault-in the entire row and will partially populate
all of the attributes in the Entity cache for that row.
11-511
About Managing Rows in Memory at Runtime
While the business logic tier is running, it stores view rows in a cache in memory (the Java
heap). When the business logic tier needs to store many rows at once, you need to make sure
it doesn't run out of memory. To do so, you can specify that when the number of rows reaches
a certain size, the rows "overflow" to your database to be stored on disk. This feature is called
view row spillover.
Rows with large numbers of attributes or storing large volumes of data affect memory usage
more than smaller rows with less data.
Rows are grouped as nodes in memory
View row spillover is implemented as a binary tree, rather than an array, so it's more efficient.
When view row spillover is enabled, rows are stored in "nodes." You specify the maximum
number of "active" nodes (nodes in memory) per rowset and the maximum number of rows
each node can contain:
The default is 10 active nodes of a maximum 70 rows each.
When a row is full and another row is added, the node is "split" into two nodes and about half of
the rows are moved to the new node. So you have two nodes of about half of the maximum
number of rows in each node.
If a row is deleted from a node, the business logic tier checks if the node can be merged with
another of the same type to create one node from two.
You specify the number of active nodes and rows per view object instance. You can optionally
override these values in the XML file of a view object. You might want to override the values if
you need a different maximum value.
11-512
Realize that the number of nodes and rows you specify is an approximate number. For
example, if you specify a maximum of two nodes of ten rows each, you could possibly end up
with three nodes of five rows each in memory, if the business logic tier needs it.
Database tables store spillover rows
When there are more active nodes than is allowed in memory, spillover occurs. The business
logic tier creates tables using the same schema specified in your database connection
information and places rows in these tables. The following tables are created in your database:
● PCOLL_CONTROL — This management table is shared by application module

instances using the same JDBC connection URL. It is created immediately, before
spillover occurs.
● PCST_* — A new table is created for each transaction (top-level application module).
A least-recently-used algorithm determines which node is written to the database first.
Once a row is placed in the database, it does not return to memory until it is requested. A
database administrator must manually clear data in the tables when it is no longer used.
Currently, only the Oracle 8.1.7 database and later version are supported for spillover. If you
are not using this database, your rows are stored in memory only.
The business logic tier creates its own connection to the database. If you limit the number of
connections to the database through connection pooling, remember to add extra connections
for use by the spillover feature.
Rows in the entity cache are affected
When view rows spill to disk, the entity rows they refer to in the entity cache are released.
When the view row is brought back into memory, the entity rows are also brought back.
However, if there were modifications to the entity rows, they are not released because they are
part of a transaction. When the transaction has ended (through committing or aborting it), the
entity rows can be released.
So, you can control how much memory is used by the entity cache by
11-513
● using view row spillover
● committing transactions before there are a lot of modified entity objects
Related topics
Managing Rows in Memory at Runtime
11-514
View Object States and Events
The Business Components for Java framework follows the standard Java/EJB event delegation
model for propagating events among business logic tier objects. Publishers (also called
senders) fire events, subscribers (also called listeners) respond to them.
Java event types are classes that extend java.util.EventObject. The framework sends
an event from a publisher to a subscriber by invoking a method of the RowSetListener
interface on the subscriber and passing in an instance of the event type generated. The
subscriber registers listeners by using addEventTypeListener() on the publisher.
The publisher defines the set of events it emits by providing addEventTypeListener methods
which register specific listeners for those events.
A subscriber implements a specific EventListener interface, RowSetListener, that

extends java.util.EventListener. An EventListener interface defines one or more
methods to invoke in response to each specific event type handled by the interface.
The following Business Components for Java classes for built-in events can be found in the
oracle.jbo package. They can be published by various business components and are used
to manage multi-tier communications.
Event Class Description

Extends java.util.EventObject. All business component events subclass
JboEvent
this class.
NavigationEvent Fired when the iterator position in a view object changes. It provides the following
methods:
● getPreviousRow
● getPreviousRowIndex
● getNextRow
● getNextRowIndex
● toString
Base class for range oriented event. RangeRefreshEvent, and ScrollEvent

RangeEvent
subclass this class.
11-515
RangeRefreshEvent Fired when the range is refreshed, not when a row is updated--use
UpdateEvent for that. In addition to RangeEvent methods, it has the following
methods:
● getAllRowsInRange
● getRangeStart
● getRowCountInRange
● toString
ScrollEvent Fired when the range is scrolled. In addition to RangeEvent methods, it has the
following methods:
● getRangeStartBefore
● getScrollAmount
● getFirstNewRowRangeIndex
● getNewRowCountInRange
RowEvent RowEvent is the base class for other row-oriented events. It has the following
methods:
● getRow
● getRowIndex
InsertDeleteEvent Used for insert or delete event. In addition to RowEvent methods, it has the
following methods:
● getRowCountInRangeBefore
● getRowCountInRange
Note: getRowIndex returns the absolute row index, not range-relative.

InsertEvent Provides a toString method.
DeleteEvent Provides a toString method.
UpdateEvent Adds the following methods:
● getChangedAttrIndices
● getChangedAttrNames
11-516
11-517
View Object Exception Classes
code), throw an exception, or both. Following are some standard Java recommendations.
Related topics
Ways to Handle Errors in Business Component Applications
11-518
Creating and Modifying View Objects, View Links,
Application Modules, and Clients
These topics describe how to create and modify view objects, view links, and application
modules:
● Ways to Create View Objects, View Links, and Application Modules
● Ways to Edit View Objects, View Links, and Application Modules
● Testing Business Components
● Managing Rows in Memory at Runtime
● Exposing View Links to Entity Objects
● Pooling Connections
● Creating Methods for Clients to Use
● Working with Custom Properties
● Ways to Handle Errors
● Using the API to Customize and Use View Objects, View Links, and Application Modules
11-519
Ways to Create View Objects, View Links, and
Application Modules
These topics describe how to create view objects, view links, and application modules:
● Ways to Create Default View Objects, View Links, and Application Modules
● Creating a View Object
● Creating a View Link
● Creating an Application Module
Related Topics
11-520
Ways to Create Default View Objects, View Links,
and Application Modules
You can create default view objects in the following wizards:
● Business Components Project Wizard or Editor
● Package Wizard or Editor
● Entity Object Wizard
You can create default view links, based on existing associations, and a default application
module by using the Business Components Project Wizard or Editor or Package Wizard or Editor.
Related topics
11-521
Creating a View Object
The View Object Wizard lets you create a view object at design time.
Alternatively, you can create default view objects in the Business Components Project Wizard,
Entity Object Wizard or Editor, and Package Wizard or Editor. These view objects are a good
start, but you'll probably want to edit them in the View Object Editor so they're customized for
your application.
You can define the following general types of view objects, either at design time or dynamically
at runtime:
Does the view Does at least one You can use the view object for... And you get these benefits...
object contain view attribute map
a SQL query? to an entity
attribute?
yes yes querying, updating, inserting, and data consistency with other view
deleting data objects that map to the same
entity objects, and memory
savings
yes no querying data less overhead (and potentially
faster) than when you map to
entity objects, especially when
using forward only mode (where
there is no view caching)
no yes inserting data no initial query is executed,
which saves startup time
no no temporary collections of data can use the same consistent
interface for data and easily bind
data to a user interface
To create a view object with the View Object Wizard:

❍ Choose File | New, select Business Components, and double-click View Object.
❍ In the Navigator, right-click the business components package and choose New
View Object.
11-522
The View Object Wizard appears.

3. In the Name page, specify the name and package and optionally an existing view object
that your view object will extend from. Click Next.
4. In the Entity Objects page, optionally specify the entity objects that this view object maps
to. Click Next.
You can also modify the alias name for each entity object (table) used in the SQL query,
make an entity object read-only to a view object, and specify the type of reference
between entity objects (the relationship that pairs two entity objects).
5. In the Attributes page, specify the view attributes you want to include in this view object
and the order they will appear in the SQL query. Click Next.
You can define persistent, entity-derived, transient, and SQL-derived view attributes. If you
want dynamic view attributes, you need to write code.
6. In the Attribute Settings page, specify attribute settings. Click Next.
7. In the Query page, optionally refine the view object's SQL query of the datasource in one
of two modes: normal or expert, and optionally specify parameters or remove the query
altogether. Click Test to test the query. When you are finished defining the query, click
Next.
8. If you used expert mode in the Query page, then in the Attribute Mappings page make
sure that the columns in the SQL query are mapped to the correct view attributes, or
specify not mapped if you don't want an attribute to participate in the query. Click Next.
9. In the Java page, optionally specify that the wizard generate a Java file for the view
object class, the view row class, or both. Click Next.
By default, the wizard generates the view object class, but not the view row class. You
can edit these classes to customize the view object's behavior through its methods. You
can also generate these classes from a customized base class.
10. In the Finish page, click Finish to generate the view object.
The wizard generates an XML file, and optionally Java files, depending on what you
specified. The view object appears in the project in the Navigator.
Related topics
11-523
11-524
Specifying the Name and Package of a View Object
While creating a view object with the View Object Wizard, use the Name page to specify a
name and package for this view object. You can also specify a view object that this view object
extends from.
Field descriptions
Field Description
Name Type the name of the view object, which could be entityView, for example.
Package Type the package the view object should be placed in. Click Browse to
select an existing package. Note that the view object doesn't have to be in
the same package as an entity object it's based on, an application module
that contains it, or a view link that uses it.
Extends View Object (Optional) Type the name of an existing view object you want to extend.
Click Browse to select it from a dialog. (The view object must extend
directly or indirectly from oracle.jbo.server.ViewImpl.) This is a useful
feature if you want to provide additional functionality or extend a previously
created view object that you don't have the source for. See Extending an
Existing View Object.
To specify name and package information:
1. In the Name field, type the view object name.
To extend an existing view object:
1. In the Extends View Object field, click Browse to select a view object in your project to
extend.
2. In the Name field, optionally change the view object name.
11-525
● Click Next.
Related topics
11-526
Extending an Existing View Object
While creating a view object with the View Object Wizard, use the Parent dialog to select an
existing view object to extend. This page is organized in a tree structure. To select a view object,
click the view object name and click OK.
Just as view objects use SQL queries to work with filtered subsets of attributes and business logic
in entity objects, extended view objects work with the attributes and business logic in extended
entity objects. The extended view object provides the means of access to the new attributes, new
definitions and validations on existing attributes, and business logic that you have added to the
extended entity object.
Figure 1 illustrates the relationship between the original components, the extended components,
and the database tables. The original components usually belong to an existing application. The
extended components represent customizations of the original components--they have been
specialized to make the application more "site-specific" or to fit a different set of business
requirements.
For example, assume that a vendor delivers a package of components which includes the Emp
entity object and EmpView view object. The developers at the company that purchased the
package decide to customize the package components to fit their business requirements. The
developers begin by extending the Emp entity object to add additional attributes and business logic.
They then generate the database table to provide the datasource for the extended Entity (for more
information on customizing an entity object and generating a datasource for it, see Extending entity
objects).
11-527
To access the new, as well as the existing attributes and business logic in the extended entity
object NewEmpEx, the developers choose to extend EmpView, the view object that uses Emp. The
extended view object initially copies a SQL query from its parent, which references the original
entity object, Emp. To make the extended view object reference the extended entity object, certain
requirements have to be met:
● the attributes in the original entity object must be mapped to attributes in the extended Entity.
● the definitions of the usages of the attributes in the original entity object must be overridden
with the usages in the extended Entity.
● the view attributes that you want to work with must appear in the extended view object query
SELECT list. The list must also include the new attributes that were added to the extended
Entity.
● the SQL query must reference the appropriate datasource; that is, the table associated with
the extended entity object.
● (optional) make the necessary changes to the SQL query's FROM or WHERE clauses to get
just the slice of data you need. You also have the option of creating an arbitrary SQL
11-528
statement of any length or complexity using Expert Mode.
● the sequence and datatypes of attributes in the SELECT list must match the sequence and
datatypes expected by the application that will use the query results.
Using Exported Methods in Extended View Objects
If your original view object contains methods that you want to export to the client, they are inherited
by the extended view object. You do not need to make any changes to the method code. If you
substitute the extended view object throughout the application and deploy it to the business logic
tier, your client code will be able to use the method using the existing interface.
Creating a View Object Directly from an Extended entity object
There are situations where it is entirely valid not to extend the view object and instead, create a new
view object directly from the extended entity object. This is illustrated in the following figure. You
can use this approach when your new view object does not require any of the functionality defined
by the original view object or application. These view objects are especially useful when you are
building new UIs or JSPs that need only a particular view of the data, and do not have any
dependencies on the original application.
11-529
For example, assume that you created an extended entity object NewEmpEx where you simply
added the extra attributes PensionPlan and CurrentWithholding. If you want to build a UI or
JSP that uses only the data represented by PensionPlan and CurrentWithholding, it is not
necessary to extend the original view object. Instead, you can create a view object that uses only
these attributes in its SELECT list. The only restrictions on the view object's query is that it must
identify the correct datasource and the SELECT list must contain the Primary Key.
In general, creating a view object directly from the extended Entity is appropriate under these
conditions:
● you do not intend to use the new view object for substitution (the framework requires that the
substituted view object must be an inherited child of the original view object).
● the extended view object does not require any of the functionality provided by the original
view object. For example, there is no custom Java code written on the original view object.
To use the new view object as a part of the delivered application, you do not need the source code
for the original application module. Instead, you can extend the original application module and add
the view object to its data model.
To Extend a View Object
The topic Extending entity objects describes how you can extend the entity object Emp with
NewEmpEx, which contains the same attributes as Emp plus an additional YearsofService
attribute. The topic then described how to forward generate the NEWEMPEX table in the database
from the NewEmpEx entity object. This topic continues the example by describing how to extend the
EmpView view object with a view that corresponds to the extended entity object NewEmpEx.
1. Right-click the package that will hold the customized view object and select New View
Object. The View Object Wizard opens.
2. In the Name page, enter the name of the new view (NewEmpViewEx) in the Name field. To
offer you greater flexibility, note that in this page, the Name, Package, Extends View, and
Schema Object fields are editable.
3. Click the Browse button next to the Extends View field to open the Parent dialog. Use the
Parent dialog to select the view object from which NewEmpViewEx will be extended.
Typically, you will be extending a view object from the package of original components. In
this case, select EmpView, then click OK. Note, it is implied that the base view object is in a
11-530
package in the project. Click Next to proceed to the entity objects page.
4. In the entity objects page, the Available list box will display the entity objects available in the
original package of components and in the package of extended components. The Selected
list box will display the entity object that the base view object references (in this case, the
base view object is EmpView and the entity object it references is Emp). You can override
the definition of the Emp entity object with the extended Entity NewEmpEx as follows:
a. Select NewEmp in the Available list box and select Emp in the Selected list box
b. Click the right shuttle button. An alert box will open and display the message: "The
entity usage Emp will be updated from the entity Emp to the entity NewEmpEx which
extends it."
c. Click OK.
The definition of the original entity object Emp will be overridden with the definition of the
extended entity object NewEmpEx.
Alternatively, you can move NewEmpEx from the Available list box to the selected list box
without first selecting Emp in the selected list box. In this case the selected list box displays
both Emp and newEmp, and NewEmpViewEx is based on both entities; the attributes
inherited from EmpView are based on Emp, and the new attributes are based on
NewEmpEx. This means that NewEmpViewEx will query and update data in two tables: EMP
and NEWEMP.
5. In the Attributes page, notice in the Available list box that the extended view object has
available to it all of the extended entity object's attributes. The attributes in the Selected list
box should include all of the attributes that you want to be available to the extended view
object's query. Use the shuttle buttons to include the attributes you need in the Selected list
box. In this example, select the YearsofService attribute and shuttle it to the Available list
box. Click Next to proceed to the Attribute Settings page.
6. Click New to create a new attribute for the extended view object. Click Next to proceed to the
Attribute Settings page.
7. Use the Attribute Settings page to change the storage and update properties for the view
attributes you selected in the Attributes page. Click Next to proceed to the Query page.
8. In the Query page, enter the view object query. For an extended view object, the query must
11-531
satisfy the following conditions:
● Correctly identify the table from which the extended entity object will be reading
the data. Typically, this is the table for the extended Entity; NewEmpEx in this
case.
● The new attributes and the original attributes must be in the SELECT statement.
● The sequence and datatypes of attributes in the SELECT list must match the
sequence and datatypes expected by the application that will use the query
results.
Tip: When you are creating the query for your extended view object, it is
suggested that you first enable Non-Expert mode in the Query page, and
examine the default query that JDeveloper Design-Time builds for you. The
query built by the Design-Time in non-Expert mode is guaranteed to be correct.
Then, enable Expert Mode and modify the query without changing the SELECT
list.
For more information on editing an extended view object query, see Editing an
Extended View Object's SQL Query.
For the current example, the following SELECT statement would satisfy all three conditions:
SELECT Emp.YEARSOFSERVICE FROM NEWEMPEX EMP
So would this statement:
SELECT Emp.EMPNO, Emp.ENAME, Emp.JOB, Emp.MGR, Emp.HIREDATE,

Emp.SAL, Emp.COMM, Emp.DEPTNO, Emp.YEARSOFSERVICE FROM NEWEMPEX EMP
Click Next to proceed to the Attribute Mappings page.
9. The Attribute Mappings page gives you the opportunity to re-map query columns to attributes
if you deleted, added, or switched positions of columns in your Expert Mode SQL statement.
To change the mapping, click an attribute in the right side of the grid. A dropdown list lets you
select another attribute to map to the query column. You can also remove the mapping for a
particular query column. Query columns that are not mapped cannot be updated. When you
are finished with this page, click Next.
11-532
10. In the Java page, select the options that let you generate classes (that is, *Impl classes) for
the extended view object and (optionally) the view rows. After the framework creates these
classes, you can edit them to customize the extended view object's behavior.
11. Click Next, then Finish. The view object wizard generates the .java, .xml, and (optionally)
the view row .java files for the extended view object and adds their names to the Navigation
pane.
Editing an Extended View Object's SQL Query
Before you finish creating your extended view object, you will probably have to manually edit its
SQL query. This will be true especially if you have added new attributes or changed a datasource.
You can consider the original view object's query to be a reasonable starting point to begin your
edits. When you create your extended object, the view object wizard's Query page will provide you
with the original query depending on whether the original view object query was created with Expert
Mode enabled or disabled.
Like any attribute or property setting, the Expert Mode status of a view object can be inherited by
the extended object. For example, if the original view object was created with Expert Mode
disabled, then the view object wizard for the extended object will open with Expert Mode disabled.
Similarly, if the original view object was created in Expert Mode, then the Query page for the
extended object will open in Expert Mode.
You can immediately determine if a view object's query was constructed in Expert Mode by
examining its .xml file and looking for the value of the CustomQuery variable in the ViewObject
tag. For example:
<ViewObject
Name="DeptVExpertEx"
Extends="package28.DeptViewExpert"
BindingStyle="Oracle"
CustomQuery="true" <-- indicates Expert Mode is enabled
A value of true indicates that the view object's query was created in Expert Mode. False indicates
non-Expert Mode.
Editing in non-Expert Mode
If the original view object was created in non-Expert Mode (that is, with the Expert Mode check box
cleared), then the view object wizard for the extended object will open with Expert Mode disabled.
In this case, the Query Statement area of the Query page will display the default SQL query in a
read-only list box. To edit the query, select the Expert Mode check box. The read-only list box will
11-533
immediately change to an editable box. You can edit the existing query or delete it and paste in a
query from another source.
Editing with Expert Mode Enabled
If the original view object was created in Expert Mode, then the Query page for the extended object
will open in Expert Mode. In this case, the Query Statement area of the Query page will display an
empty, editable list box. Again, the SQL query from the original view object is a reasonable starting
point for your edits. You can copy the query from the original view object's .xml file and paste it in
the page. The query appears in the ViewObject section of the file, between the SQLQuery tags.
For example:
<SQLQuery><![CDATA[
SELECT Dept.DEPTNO, Dept.DNAME, Dept.LOC <-- SQL query
FROM DEPT Dept
]]></SQLQuery>
You can edit the query after pasting it into the page. As an alternative to working from the original
query, you can:
● manually enter your own query.
OR
● copy and paste a different query from another source.
Understanding the Generated Extended View Object Files
The NewEmpViewEx view object is created by extending the functionality of the EmpView view
object without any source code modification. JDeveloper creates a .java and a .xml file for
NewEmpViewEx which can be seamlessly integrated into the packaged application. The
NewEmpViewEx view object can now be used at runtime, however, you might want to add some
additional features, such as a calculated attribute, to its .java file. You can then substitute it for all
instances of EmpView in the original application. For information on how to substitute
NewEmpViewEx for all instances of EmpView in your application, see Substituting Business
Components.
The following is a code sample of NewEmpViewEx.xml, which was constructed in non-Expert

Mode. Notice that NewEmpViewEx.xml contains a SQL query based on the attributes of the
extended entity object it references. The file includes definitions of only new attributes or attributes
11-534
from the original view object that were overridden.
The code for view objects that are constructed in non-Expert Mode differs from that created in
Expert Mode. These differences are described in the discussion section that follows the code
sample.
1 <?xml version="1.0" encoding='WINDOWS-1252'?>

2 <!DOCTYPE ViewObject SYSTEM "jbo_03_01.dtd">
3 <ViewObject
4 Name="NewEmpViewEx"
5 Extends="package27.EmpView"
6 SelectList="Emp.EMPNO, Emp.ENAME, Emp.JOB, Emp.MGR, Emp.HIREDATE, Emp.SAL,
Emp.COMM, Emp.DEPTNO, Emp.SERVICEINYEAR"
7 FromList="NEWEMPEX Emp"
8 BindingStyle="Oracle"
9 CustomQuery="false"
10 ComponentClass="Extender.NewEmpViewExImpl" >
11 <DesignTime>
12 <Attr Name="_codeGenFlag" Value="20" />
13 </DesignTime>
14 <EntityUsage
15 Name="Emp"
16 Entity="Extender.NewEmpEx" >
17 <DesignTime>
18 <Attr Name="_ReadOnly" Value="false" />
19 <Attr Name="_EntireObjectTable" Value="false" />
20 <Attr Name="_queryClause" Value="false" />
21 </DesignTime>
22 </EntityUsage>
23 <ViewAttribute
24 Name="Hiredate"
25 EntityAttrName="Hiredate"
26 EntityUsage="Emp"
27 AliasName="HIREDATE" >
28 <DesignTime>
29 <Attr Name="_OverrideAttr" Value="true" />
30 <Attr Name="_DisplaySize" Value="0" />
31 </DesignTime>
32 </ViewAttribute>
...
// definitions of the other view attributes
...
11-535
</DesignTime>
</ViewAttribute>
</ViewObject>
Lines 4-9: The Name and Extends fields identify the name of the extended view object
(NewEmpViewEx) and the name of the original view object which it extends
(package27.EmpView). The SelectList field displays names of the attributes that will
participate in the query. By default, the SELECT list includes all of the view attributes. The
FromList provides an alias for the name of the table given in the SelectList field, and identifies
the correct datasource on which the query should operate. Since the query was constructed in non-
Expert Mode, the value of CustomQuery is "false".
If the view object query is constructed in Expert Mode, the SelectList and FromList fields are
replaced with a SQLQuery field that displays the arbitrary SQL statement, and the value of
CustomQuery is set to "true". The following is a snippet of the code the framework provides for a
view object constructed with an Expert Mode query.
...
CustomQuery="true"
ComponentClass="Extender.NewEmpViewExImpl" >
<SQLQuery><![CDATA[
Select * from NEWEMPEX Emp
]]></SQLQuery>
...
Line 10: The ComponentClass field identifies the name of the implementation file (that is, the
*Impl file) for the extended view object.
Lines 15, 16: The Name and Entity fields identify the name of the original entity object (Emp) and
the name of the extended Entity (Extender.NewEmpEx) which this extended view object
references.
Line 23: The definitions of the view attributes are placed within individual ViewAttribute tags.
Only new attributes and overridden attributes from the original view object are included in the
extended view object's XML file.
11-536
Selecting Entity Objects for a View Object and
Setting Usage Details
Object Editor, use the Entity Objects page to choose the entity objects that this view object maps
to.
You should map a view object to one or more entity objects, and base view attributes on entity
attributes, if you want a view object to
● be able to modify persistent data through entity objects

● retrieve the most up-to-date data in the cache
● access the same data as other view objects that map to the same entity objects
If you don't need these features, your application has less overhead, and might be faster, if you
don't map a view object to an entity object.
You can also modify the alias name for each entity object (table) used in the SQL query, make
an entity object read-only to a view object, and specify the type of reference between entity
objects.
New in this release are the Subtypes button and the Association End field.
Field descriptions
Field Description
A list of entity objects defined in the current workspace,
just the entity objects you need. To add an entity object
Available
to the Selected list, select it in the Available list and click
the right arrow (>). The view object can now have view
attributes based on the entity object's attributes.
11-537
(Optional) A list of entity objects that can be accessed by
this view object. As each entity is selected by the view
object, the name is made unique; for example, if you add
an entity object twice so you can create a join within one
table, you need unique names.
The first entity object you select defaults to updateable

Selected (the Read Only option is cleared). All succeeding entity
objects are defaulted to select Read Only and
Reference. See these field descriptions for guidelines on
setting them.
To remove an entity object from the list, select it and

click the left arrow (<).
If you are using polymorphic entity objects, select the

Subtypes base entity object in the Selected list and click Subtypes
to specify the child entity objects.
Select this option if you want to create either a join
(cartesian product) of two entity objects in the result set
or create a join with an appropriate filter by selecting
which association end to qualify the join's Where clause.
For example, let's say there are two self-join
associations in emp, such as emps who work for me and
Association End emps who work in the same location as me. A view
object based on Emp and Emp1 (both based on the
entity object emp) may select emps who work in the
same location as me, filtering the clause to create the
join.
A name that identifies each entity object usage. The alias

name is used in the view object's SQL query and in the
getter for the entity object (which is called in the view row
class). If you select the same entity object more than
Alias once, such as to accomplish a join within one table,
aliases distinguish between them. Although a unique
default name is generated for you, you might want to
customize the name so it's more meaningful. In addition,
sometimes you might want to shorten the view object's
SQL query by shortening the alias names.
Select the checkbox to prevent the view object from
modifying any entity attributes in the entity object. By
Read Only
default, the first entity object is updateable and
subsequent ones are read-only.
11-538
Select this checkbox if you want the information from this
entity object to be treated as reference information in this
view object, with automatic lookup. Attribute values are
dynamically fetched from the entity cache when a
controlling key attribute changes.
For example, take a view object called EmployeeList,

Reference which includes attributes from an Employee entity object
as well as attributes from a Department entity object. if
the Department entity object is flagged as a Reference,
then setting the Employee.DeptNo attribute in the view
object from 10 to 20 changes the department that the
current employee works in, and automatically retrieves
the proper department name into the current view.
To map an entity object to a view object:
1. Select an entity object in the Available list and click the right arrow (>).
The entity object appears in the Selected list. JDeveloper automatically changes the alias
name so it is unique.
2. While the entity object is selected in the Selected list, specify the Association End, Alias
name, Read Only, and Reference settings you need.
3. If you are using polymorphic entity objects, select the base entity object in the Selected
list and click Subtypes to specify the child entity objects.
4. Repeat for any other entity objects you need.
If you want to create a join within a table, for example, you need to add the entity object
more than once.
Related topics
11-539
11-540
Creating, Removing, and Ordering View Attributes
Object Editor, use the Attributes page to specify the view attributes you want to include in this
view object.
In this page, you can create the following types of view attributes, which are based on entity
attributes and are cached in the entity cache:
● Persistent. A view attribute based on a persistent entity attribute. If you want to store
data changes in the datasource, you need a persistent view attribute.
in the entity cache and multiple view objects can share the same data.
You can click New to create view attributes that are not based on entity attributes and are
cached in the view cache.
Note: To create dynamic attibutes at runtime, you need to write code that uses the
addDynamicAttribute method.
Mapping a view attribute to an entity attribute has the following advantages:
● The view attribute can modify persistent data through entity objects.
● The view attribute is populated with the most up-to-date data in the cache.
● The view attribute accesses the same cached data as other view objects that map to the
same entity attribute.
If you don't need these features, your application has less overhead, and might be faster, if you
don't map a view attribute to an entity attribute.
If your application has a graphical user interface, you should include only the attributes you
need for a form, to save memory and improve performance, but avoid fault-in. You must include
primary key(s) if the underlying entity objects are updateable; this is enforced by the wizard.
11-541
Field Description
A list of the entity objects you chose in the Entity Objects
page and their attributes. You can create view attributes
based on entity attributes by moving entity attributes
from the Available list to the Selected list: select one or
more attributes or nodes, and click the left arrow (>). Or
Available click the double left arrow (>>) to move all attributes. As
the attributes are moved, the wizard creates unique view
attribute names, which you can change in the Attribute
Settings page.
(Optional) A list of the view attributes in this view object.

To remove an attribute from the list, select one or more
attributes, and click the left arrow (<). To remove all
attributes, click the double left arrow (<<). If an attribute
has dependencies, you can't remove it; a dialog appears
which lets you view all dependencies so you can remove
Selected them, if needed.
To reorder the view attributes (which determines their

order in the SQL query), select one or more attributes,
and click the up or down arrow button until the selected
items are in the position you want.
(Optional) Click New to define a view attribute that is not

New based on an entity attribute. After you create the
attribute, it will appear in the Selected list.
To create a view attribute that is based on an entity attribute:
The Available list displays the entity objects and attributes you selected in the Entity Objects
page. Move one or more entity attributes from the Available list to the Selected list in one of
these ways:
● In the Available list, select an entity attribute, control-click to individually select multiple
attributes, or shift-click to select a range of attributes, and then click the right arrow (>).
● In the Available list, double-click an entity attribute.
● To move all attributes in an entity object, select the entity object in the Available list and
click the right arrow (>).
● To move all attributes in a package, select the package and click the right arrow (>). Or
simply click the double right arrow (>>).
11-542
Later, you can change the default name and settings of the view attribute in the Attribute
Settings page.
To create a view attribute that is not based on an entity attribute:
1. Click New.
2. In the Define New View Attribute dialog, define the attribute, and click OK.
The attribute appears in the Selected list.
To remove a view attribute:
To reorder view attributes:
The order of the view attributes determines their order in the SQL query. To change the order:
● In the Selected list, select a view attribute or control-click to select multiple attributes, and
click the up or down arrow button until the selected items are in the position you want.
● After you are finished with the editor, click Finish or OK to save your changes.
Related topics
11-543
11-544
Defining a New View Attribute
Object Editor, use the Define New View Attribute dialog to define a new view attribute that is not
based on an entity attribute. The attribute data is cached in the view cache.
In this dialog, you can create the following types of view attributes:
SQL expression. You write Java code to populate the attribute.
SQL expression.
The Selected in Query and Discriminator attribute settings are new in this release.
Field descriptions
Attribute Setting Transient Attribute SQL-Derived Attribute
Attribute Name Required Required

Attribute Type Required Required
Selected in Query When selected, this attribute appears in Selected
the view object's SQL Select statement.
Discriminator Selectable Selectable
Updateable Selectable Selectable
Alias Optional Optional, can use to prevent name
conflicts
Expression N/A (NULL) Required (not NULL)
Queriable N/A Selectable
11-545
To create a view attribute that is not based on an entity attribute:
1. Fill in the attribute settings, as outlined in the previous table.

2. Click OK.
The attribute appears in the Selected list of the Attributes page.
Related topics
11-546
Viewing and Customizing the SQL Statement of a
View Object
Object Editor, use the Query page to refine the view object's query of the datasource.
Attributes become part of the query if the Selected in Query setting is selected. SQL-derived view
attributes always have this setting. In addition, by default, all view attributes that are based on
entity attributes have this setting.
The Query page has two modes of operation:
● Normal mode is easier and more fool-proof, as most of the query is taken care of for you.
The SELECT and FROM portions of the SQL statement are automatically created, based
on the entity objects that the view object is based on, and on view attributes with the
Selected in Query setting. You can add the WHERE and ORDERBY portions of the query
as needed.
● Expert mode is useful if you want complete control over the SQL query, such as the
SELECT and FROM portions. In this mode, you are responsible for ensuring that the
mapping of SQL result columns to entity attributes is correct in the Attribute Mappings
page. You need to remap these items if you deleted, added, or switched positions of
columns in your custom SQL query, because the mappings might no longer be correct.
You can also use expert mode to remove a SQL query from the view object. You might
want to remove the SQL query if you are only inserting data, and want to save the
startup time association with the initial query; or you want to define temporary collections
of data using the same consistent business components interface and easily bind data to
the user interface.
Warning: If you enter expert mode and make changes, that work would be lost if you switch
back out of expert mode.
Field descriptions
Field Description
11-547
(Optional) In normal mode, the Generated Statement
field is not editable; it simply shows you the SELECT
statement that is being issued based on the list of
attributes selected in the Attributes page.
Generated Statement,
In expert mode, you can enter any valid SQL statement
Query Statement
in the Query Statement field.You also have the option of
entering your custom SQL query directly into the
generated XML file, as described in Pasting a Custom
Query in a View Object XML File.
Query Clauses
(Optional) For normal mode, type a WHERE clause

without the WHERE keyword. For example, to apply the
constraint where the department number equals 20,
Where
type:
DEPARTMENT_ID = 20
(Optional) Type an ORDER BY clause without the

ORDER BY keyword. For example, to order the query
output by department number, type DEPARTMENT_ID
directly in the Order By field. Alternatively, you can click
Edit to use the Select Attributes dialog to choose and
order attributes that are available for an ORDER BY
clause.
Note: The attributes listed in the Order By field will be

Order
cleared if you click Edit and then click OK in the Select
By
Attributes dialog that appears.
While you can add the ORDER BY clause directly to the

Query Statement field when you are in an expert mode,
it is still useful to keep the ORDER BY portion of the
clause separate, since the runtime engine might need to
append additional WHERE clauses to the query. Keeping
the ORDER BY clauses separated will ensure they are
applied correctly.
11-548
Select Expert Mode to edit the SQL query directly.
Expert mode allows greater control over the entire query
statement allowing you to edit it directly. In expert mode,
you are not restricted to WHERE and ORDER BY
statements; you can enter any valid SQL statement.
Expert Mode
Note that if you enter expert mode and make changes
there, that work may be lost if you choose to switch back
out of expert mode.
Select or deselect to determine whether you will pass

parameters to view objects in two styles: ? or :n, such as
in the following SQL fragments:
WHERE ? = foo AND ? = bar
WHERE :2 = bar AND :1 = foo AND :1 != :2
Use ? style parameters Notice in the first example that parameters are taken in
order. In the second example, parameters can be reused
and reordered.
Note: A view link will use the parameter style specified

on the destination view object. Once this has been set
and the view links created, changing it will require visiting
each of the view links through the edit wizards, and fixing
the SQL syntax.
Click Test to test whether the syntax of the SQL query is

valid. No other checking is performed. If the syntax is
valid, JDeveloper returns a message that the code is
Test valid. If the syntax is not valid, JDeveloper returns an
error message.
To specify a SQL query in normal mode:
1. Make sure Expert Mode is deselected.

2. If you want to use parameters, select Use ? style parameters.
3. Optionally type a clause in the Where field, Order By field, or both.
You can click Edit to add an Order By clause through a dialog.
4. Click Test to test the query.
Correct it, if necessary.
11-549
To specify a SQL query in expert mode:
1. Select Expert Mode.

The default SQL statement becomes editable.
2. If you want to use parameters, select Use ? style parameters.
3. Type your custom SQL statement in the Query Statement field. Optionally type a clause
in the Order By field or click Edit to add one.
While you can add the ORDER BY clause directly to the Query Statement field when you
are in an expert mode, it is still useful to keep the ORDER BY portion of the clause
separate, since the runtime engine might need to append additional WHERE clauses to
the query and you want to make sure they're applied correctly.
4. Click Test to test the query.
Correct it, if necessary.
5. Open the Attribute Mappings page to make sure the mapping between view attributes
and the datasource is correct.
Related topics
11-550
Ordering View Attributes in an Order By Clause
Object Editor, use the Select Attributes dialog to add attributes and order them for use in an
ORDER BY clause. The ORDER BY clause is constructed from the attributes you select, in top to
bottom order.
While you can add the ORDER BY clause directly to the SQL statement when you are in an
expert mode, it is still useful to keep the ORDER BY portion of the clause separate, since the
runtime engine might need to append additional WHERE clauses to the query. Keeping the
ORDER BY clauses separated will ensure they are applied correctly.
Field descriptions
Field Description
A list of the attributes that were defined in the Attributes
page. You can add attributes to an ORDER BY clause by
Available moving attributes from the Available list to the Selected
list: select one or more attributes, and click the left arrow
(>). Or click the double left arrow (>>) to move all
attributes.
A list of the attributes in the ORDER BY clause. To
remove an attribute from the list, select one or more
attributes, and click the left arrow (<). To remove all
Selected
To reorder the view attributes (which determines their
order in the ORDER BY clause), select one or more
attributes, and click the up or down arrow button until the
To add an attribute:
The Available list displays the attributes you defined in the Attributes page. Move one or more
attributes from the Available list to the Selected list in one of these ways:
● In the Available list, select an attribute, control-click to individually select multiple

attributes, or shift-click to select a range of attributes, and then click the right arrow (>).
● In the Available list, double-click an attribute.
11-551
● To move all attributes, select the package and click the right arrow (>). Or simply click
the double right arrow (>>).
Later, you can change the default name and settings of the view attribute in the Attribute
Settings page.
To remove an attribute:
To reorder attributes:
The order of the view attributes determines their order in the ORDER BY clause. To change the
order:
● In the Selected list, select one or more attributes, and click the up or down arrow button
until the selected items are in the position you want.
To apply changes:
● Click OK to apply changes to the Query page.
Related topics
11-552
Mapping View Attributes to SQL Columns
Object Editor, use the Attribute Mappings page to map the columns in the SQL query to the
correct view attributes. You only need, and can, specify mappings if you are working in expert
mode in the Query page. If you are working in normal mode, the mappings are made
automatically.
Field descriptions
Field Description
A list of the columns in the SQL query in the Query page.
Each of these columns needs to map to an attribute
(directly to its right in the View Attributes list). If the view
Query Columns attribute is based on an entity attribute, the data is stored
in the entity cache. If the view attribute is not based on
an entity attribute, the data is stored in the view cache.
A list of the view attributes that are mapped to each of

the columns of the query result (directly to its left in the
Query Columns list). Selecting a cell in this list brings up
a list of attributes you can choose from.
One of the choices in the list is Not mapped. This will

View Object Attributes
create a new attribute that has the name of the Query
Column that it is mapped to. Selecting this option makes
this column of the query result non-persistent. If you go
to another page and come back to the Attribute Settings
page, you will see this new attribute in the field.
To choose an attribute to map to a column:
1. Click a field in the View Object Attributes list.

It becomes editable.
2. Choose an attribute from the drop-down list, or choose Not mapped to create a new
attribute that isn't persisted in the database.
11-553
Related topics
11-554
Generating Java Source Files and Methods for View
Objects
Object Editor, use the Java page to specify whether the wizard generates a Java file for the
view object class, the view row class, or both. By default, the wizard generates the view object
class, but not the view row class. You can edit these classes to customize the view object's
behavior through its methods. You can also generate these classes from a customized base
class.
Field Description
View Object Class This setting applies to the ViewImpl class.
you can edit to customize the entity object class' behavior.
View Row Class These settings apply to the ViewRowImpl class.

that you can edit to customize the view row class' behavior.
Generate Select this checkbox to generate accessor methods (for example,
Accessors getJob and setJob). These accessor methods provide type-safe
access to the corresponding attribute fields. They also provide a
place to add your own custom code for validation and other uses.
Extends (Optional) Click Extends to select view object and row base classes
you want to use to generate the view object. Typically, in an
applications organization, the framework supplied by JDeveloper will
be customized by a core group and all view objects for the
organization may be built over this customized framework.
To generate a view object class:
class.
11-555
To generate a view row class:
2. Select the methods you want to generate.
class.
Related topics
11-556
The Files that Define a View Object
Depending on what you specified, when you click Finish, the wizard optionally generates a
Java file for the view object class, the view row class, or both. Or you can generate neither.
Each business component is defined in an XML file, which allows you to modify the
application's behavior without recompiling Java code. If you look at one of the Java or XML
files, you will see that each entity and view object has attributes corresponding to each column
in the table.
Related topics
Specifying Code Generation and Lazy Loading Options
11-557
Adding Custom Code to a View Object XML File
Pasting a Custom Query in a View Object XML File
If you create your SQL query in a text editor (such as Emacs or vi), the business components
framework makes it easy to paste it into your XML file:
1. In the XML file for your view object, ensure that the CustomQuery attribute for your view
object's <ViewObject...> element is set to "true". That is,
CustomQuery="true"
2. Enter the following lines in the file:
<SQLQuery><![CDATA[
paste your custom SQL here
]]></SQLQuery>
For example:
....
<ViewObject
Name="DeptView"
OrderBy="Dept.DNAME"
CustomQuery="true"
ComponentClass="package2.DeptViewImpl" >
<SQLQuery><![CDATA[
SELECT Dept.DEPTNO, Dept.DNAME, Dept.LOC, Dept.FAXNUM

FROM DEPT Dept
11-558
]]></SQLQuery>
...
3. Save your XML file.
Precautions for Editing the View Object XML File
● In the CDATA section, you do not have to quote special characters such as <, >, &, ', or ".
● You must use SQL column aliases in your custom SQL query statement so that the
names of each column matches its corresponding view attribute name (case-
insensitively). The wizard does this for you, but if you manually edit the view object XML
file, you must keep this rule in mind.
11-559
Creating a View Link
The View Link Wizard lets you create a view link at design time.
You can also create default view links, based on existing associations, by using the Business
Components Project Wizard, Package Wizard, and Entity Object Wizard. If you add an association
after you have created a view object, you can manually add the view link in the wizard.
To create a view link with the View Link Wizard:

❍ Choose File | New, select Business Components, and double-click View Link.
❍ In the Navigator, right-click the business components package and choose New
View Link.
The View Link Wizard appears.
3. In the Name page, select a view link name, the package the view link should be placed
in, and optionally an existing view link to extend. Click Next.
4. In the View Objects page, select the source (master) view object and the destination
(detail) view object. Click Next.
5. In the Role Attributes pages, select the attributes that define the relationship between the
source and destination view objects of a link. Click Next.
There is a separate page for source and destination; you must specify the same number
of attributes in each page, in order. You can optionally specify all attributes that define an
association: when you shuttle an association to the Selected Attributes list, the attributes
associated with that association automatically appear. Also, if you select an association
in the source, the matching attributes (if applicable) will be included by default on the
destination page. These attributes are used to formulate a SQL snippet, which you can
modify, if needed.
6. In the View Link SQL page, examine the default SQL expression used to filter the
records in the destination side of a view link and optionally modify it to perform any
11-560
additional valid SQL restrictions. You can click Test to make sure the SQL statement is
valid. Click Next.
Do not alter the SQL if you are creating a bidirectional view link.
7. In the View Link Properties page, set the cardinality, directionality, and optionally
generate accessors if you want to traverse the relationship in code. Click Next.
Related topics
The File that Defines a View Link
11-561
Specifying the Name and Package of a View Link
While creating a view link in the View Link Wizard, use the Name page to choose a name and
package for this view link. You may also specify an view link that this view link extends from.
Field descriptions
Field Description
Name Type the name of the view link, which describes the relationship, and
perhaps ends with the string "Link" to make it easy to identify.
Package Type the package the view link should be placed in. Click Browse to select
an existing package. Note that the view link doesn't have to be in the same
package as an application module that contains it or or a view object that
uses it.
Extends View Link (Optional) Type the name of an existing view link you want to extend. Click
Browse to select it from a dialog. This is a useful feature if you want to
provide additional functionality or extend a previously created view link that
you don't have the source for. See Extending an Existing View Link.
1. In the Name field, type the view link name.
To extend an existing view link:
1. In the Extends View Link field, click Browse to select a view link in your project to
extend.
2. In the Name field, optionally change the view link name.
11-562
● Click Next.
Related topics
11-563
Extending an Existing View Link
JDeveloper provides the extended view link feature to let you preserve the relationship between
view objects. In addition, by extending a view link, you can access any new attributes that might
have been added to the extended view objects. Extending the view objects and the link
between them preserves typesafe binding: any accessors written in the original view objects
will be inherited by the extended views and will be able to traverse the original view link.
As illustrated in the following figure, a view link defines a relationship between view objects
based on common attributes. View links have a designated source end and a destination end,
and imply a master-detail relationship. The link can be navigated only in the source (master) to
destination (detail) direction. That is, you can write a view link accessor method in the source
view object to access a desired result set in the destination view object. For example, assume
you have a DeptView and an EmpView view object, and that DeptView contains a getEmp()
method that retrieves a row set of Emp objects.
As illustrated in the following figure, an extended view link inherits the view link and view link
accessors of its parent. The accessor in the extended view object can still traverse the original
view link. If you extend the DeptView view object, the getEmp() method will be inherited by
NewDeptViewEx and will be able to retrieve data from EmpView.
11-564
Notice, however that extending the view objects does not extend the original view link between
them. You cannot call an accessor from NewDeptViewEx to NewEmpViewEx unless you
extend the view link. Extending the view link allows the view link to be updated to relate
extended view objects.
Extending the view link between the extended view objects gives you the flexibility of choosing:
● any of the new attributes from the extended view object as source and destination role
attributes.
● any of the pre-built associations on which to base the view link.
The following figure illustrates extending the existing view link from NewDeptViewEx to
NewEmpViewEx.
To Extend a View Link
1. Right-click the package that will hold the customized view link and select New View
Link. The View Link Wizard opens.
11-565
2. In the Name page, enter the name of the new view link (NewViewLinkEx) in the Name
field. To offer you greater flexibility, note that in this page, the Name, Package, and
Extends View Link fields are editable.
3. Click Browse to open the Parent dialog. Open the package of original components and
select the name of the view link that you want to extend. Click OK to close the dialog.
Click Next in the Name page to proceed to the Association Views page.
4. In the Association Views page, open the package containing the extended objects in the
Select Source View Object list and select the extended view object NewDeptViewEx.
NewDeptViewEx will act as the source of the extended view link. Next, open the
package containing the extended objects in the Select Destination View Object list and
select the extended view object NewEmpEx. NewEmpEx will act as the destination of the
extended view link. Click Next to proceed to the Source Role Attributes page.
5. In the Source Role Attributes page, select the view attributes that define the relationship
on the source end of the extended view link. You must specify the same number of
attributes for each view object, in the proper order, on both the source and destination
ends. Notice that any new attributes added to the extended view object are also
available. In this example, ensure that Deptno appears in the Selected Attributes list.
You can optionally specify all attributes that define a key from the Available
Associations list. When you shuttle a key to the Selected Attributes list, the attributes
associated with that key automatically appear. Also, if you select a key in the Source
Role Attributes page, the matching key (if applicable) will be included by default in the
Destination Role Attributes page. Click Next to proceed to the Destination Role Attributes
page.
6. In the Destination Role Attributes page, select the view attributes that define the
relationship on the destination end of the extended view object. You must specify the
same number of attributes for each view object, in the proper order, on both the source
and destination ends. Click Next to proceed to the Association SQL page.
7. In the Association SQL page, you can review, and if necessary, edit the generated SQL
code.
Note: If you want to use bind parameters (? or :) in the WHERE clause, you will need to
adhere to the style defined for the linked view object's query definition.
11-566
8. Click Finish to accept the code without changes. The Business Components for Java
framework generates code to implement the extended view link.
In the Navigation pane, notice that JDeveloper adds a new view link, NewViewLinkEx, to the
package of extended components.
Understanding the Generated Extended View Link Files
The NewFKLinkEx view link is created by extending the functionality of the

EmpForeignKeyLink view link without any source code modification. JDeveloper creates a
.xml file for NewFKLinkEx which can be seamlessly integrated into the packaged application.
The NewFKLinkEx view link can now be used at runtime. You can also substitute it for all
instances of EmpForeignKeyLink in the original application. For information on how to
substitute NewFKLinkEx for all instances of EmpForeignKeyLink in your application, see
Substituting Business Components.
The following is a code sample of NewFKLinkEx.xml.

2 <!DOCTYPE ViewLink SYSTEM "jbo_03_01.dtd">
3 <ViewLink
4 Name="NewViewLinkEx"
5 Extends="package27.EmpForeignKeyLink"
6 EntityAssociation="Extender.EmpForeignKeyAssoc"
7 Where=":1 = Emp.DEPTNO" >
8 <DesignTime>
9 <Attr Name="_isCodegen" Value="true" />
10 </DesignTime>
11 <ViewLinkDefEnd
12 Name="NewDeptViewEx"
13 Owner="Extender.NewDeptViewEx"
14 Source="true" >
15 <AttrArray Name="Attributes">
16 <Item Value="package27.DeptView.Deptno" />
17 </AttrArray>
18 </ViewLinkDefEnd>
19 <ViewLinkDefEnd
21 Owner="Extender.NewEmpViewEx" >
11-567
23 <Item Value="package27.EmpView.Deptno" />
24 </AttrArray>
25 <DesignTime>
26 <Attr Name="_finderName" Value="NewEmpViewEx" />
27 </DesignTime>
28 </ViewLinkDefEnd>
29 </ViewLink>
Lines 4-7: The Business Components for Java framework adds the Name, Extends and
EntityAssociation fields to the ViewLink tag to identify the name of the new view link
(NewViewLinkEx), the name of the original view link which it extends
(package27.EmpForeignKeyLink) and the name of the association which underlies it
(Extender.EmpForeignKeyAssoc).
The framework uses the WHERE clause in line 7 to define the view link. If the WHERE clause is
not specified, the framework builds the WHERE clause from the association specified in
EntityAssociation (line 6). If there is neither a WHERE clause nor an association, the
framework performs an equi-join between the package.ViewObject.attribute values listed in the
Item Value fields in the ViewLinkDefEnd tags (see line 16 and line 23).
Lines 12-16: The framework uses the Name, Owner, Source and Item Value fields within the
ViewLinkDefEnd tag to identify the name of the source end of the original association (Dept),
the new owner of the view link source end (Extender.NewDeptViewEx), whether the end is a
source (Source="true"), and the adds the name of the foreign key to the ItemValue tag in
the AttrArray section (package27.DeptView.Deptno).
Lines 20-23: Similarly, the framework uses the Name, Owner, and Item Value fields within
the ViewLinkDefEnd tag to identify the name of the opposite end of the original ViewLink
(Emp), the new owner of the association end (Extender.NewEmpViewEx), and the adds the
name of the foreign key to the ItemValue tag in the AttrArray section
(package27.EmpView.Deptno).
11-568
Specifying the View Objects to Link
While creating a view link in the View Link Wizard or editing a view link in the View Link Editor,
use the View Objects page to select source and destination view objects. The relationship
between the source and destination is the view link. The source end is also referred to as the
master end; the destination is referred to as the detail end.
Default view links are created if the business components framework detects a relationship
between view objects. In a default view link, the source view object references the entity object
containing the primary key of a foreign key constraint.
Field descriptions
Field Description
A list of view objects defined in the current project,
Select Source View just the view objects you need. Select the source view
Object object for the view link. For a default view link, the view
link uses the view object that references the entity object
containing the primary key.
A list of view objects defined in the current project,
just the view objects you need. Select the destination
Select Destination View view object for the view link. For a default view link, the
Object view link uses the view object that references the entity
object containing the foreign key.
To specify the view objects in the view link relationship:
1. Select the source view object in the Select Source View Object list.
2. Select the destination view object in the Select Destination View Object list.
11-569
Related topics
11-570
Specifying the Attributes in a View Link
Source and Destination Attributes pages to specify the attributes that define the relationship
between the view objects of a view link. Typically, these attributes represent key fields from the
underlying database table, but can be defined using any view attributes. These attributes are
used to formulate a SQL snippet that can be later modified.
At least one attribute must be selected in each view object to create a valid view link.
Field descriptions
Field Description
View Name The name of the source or destination entity object chosen in the View
Objects page.
Available Attributes A list of the view object's available attributes. To specify the attributes that
define the view link, select one or more attributes or nodes, and click the
left arrow (>) to add them to the Selected Attributes list. You must specify
the same number of attributes for each view object, in the proper order.
Alternatively, you can specify attributes by associations.
Available Associations A list of the associations for any entity objects on which the view object is
based. It is a quick way to choose view attributes based on underlying keys.
To specify attributes by association, select an available association and
click the left arrow (>) to add the attributes that define the key to the
Selected Attributes list.
While you can explicitly choose the attributes used for the relationship,
there may already be keys that exist that have the set of attributes selected.
If so, you can save time by selecting an available association from this list.
Another advantage of using an association is that if you select a key on the
source entity object, the matching key (if applicable) will be included by
default on the destination side.
Selected Attributes The attributes that define the view link between the view objects. To
remove an attribute from the list, select one or more attributes, and click the
left arrow (<).
To specify the attributes for an association:
1. In the Source Attributes page, select attributes from the source view object. Either:
❍ In the Available Attributes list, select a view attribute, control-click to individually

select multiple attributes, or shift-click to select a range of attributes, and then click
11-571
the right arrow (>). Or double-click an attribute.
❍ Select an association in the Available Associations list and click the right arrow
(>) to move its associated attributes to the Selected Attributes list. Or double-click
an association.
2. Click Next or the Destination Attributes tab.
3. In the Destination Attributes page, select the attributes from the destination view object.
You must specify the same number of attributes for each view object, in the proper order.
If you selected an association in the source page, the matching key (if applicable) will be
included by default on the destination page.
To remove an attribute from the Selected Attributes list:
● In the Selected Attributes list, select a view attribute, control-click to individually select
multiple attributes, or shift-click to select a range of attributes, and then click the left
arrow (<).
● Double-click an attribute in the Selected Attributes list.
Related topics
11-572
Customizing the SQL of a View Link
use the View Link SQL page to view and edit (if necessary) the SQL code that defines the view
lin between the source and destination view objects.
The View Link SQL page displays the default SQL expression that will be used to filter the
records in the destination side of a view link. The SQL query can be modified here to perform
any additional valid SQL restrictions.
Note: Do not make any changes to the SQL of a view link if you intend the view link to be
bidirectional (that is, if you intend to generate accessors in the destination view object or
destination entity object).
Field Description
Query Clauses
Source Attributes The attributes you chose for the source side of the view link (from the
Source Attributes page). The attributes are passed as parameters to the
detail view.
Where The SQL query snippet. You can modify it to add more restrictions. Any
changes you make are reflected in the Query Clause field below.
Note: The number of parameters, represented by question marks (?), must

match the number of source attributes. These parameters are position
sensitive; changing the order of them can change the result of your query.
Query Clause This display area shows the query statement with the parameters logically
substituted. This is the code that JDeveloper will use to make the link. You
can edit this query in the Where field above.
Test Click Test to see if the query statement is valid.
To change the Where clause:
1. Type a new Where clause in the Where field.

2. Click Test to verify the query.
11-573
Related topics
11-574
Specifying the Cardinality and Directionality of a
View Link
While creating a view link with the View Link Wizard or editing a view link with the View Link
Editor, in the View Link Properties page, you specify the behavioral aspects of the view link:
● cardinality
● whether to expose view link accessors that return data from the other side of the view
link and the names of the accessors.
After a view link is defined, the source view object can transparently use the view link accessor
to traverse the destination side of the view link.
This page has divisions on the left and the right for the source and destination sides of the view
link.
Related topics
11-575
Specifying the Cardinality of a View Link
Editor, in the View Link Properties page, you can specify the cardinality of a view link.
Cardinality helps to define the relationship between view objects by setting the minimum and
maximum number of members that may participate in a view link:
Field descriptions
Field Description
Source Cardinality Choose a cardinality setting for the source end of the view link.
Destination Cardinality Choose a cardinality setting for the destination end of the view link.
To specify cardinality:
Choose a Cardinality setting for the source and destination view objects:
● For a one-to-one relationship, both view objects should have 1.

● For a one-to-many relationship, the master view object can have 1 or 0..1 and the detail
*.
● For a many-to-many relationship, both view objects should have *.
Related topics
11-576
11-577
Exposing View Link Accessors
Editor, in the View Link Properties page, you can generate and name view link accessors,
which return data from the other side of the view link.
The accessors are placed in the view row class or the entity object class.
Field descriptions
Field Description
Generate Accessor The destination options are only available if you have not changed the view
link SQL on the View Link SQL page. If you want to expose accessors in
the destination view link, change the view link SQL back to the default.
In View Object (source) Select this option to generate an accessor in the source or destination view
object. This accessor returns a view row or a collection of view rows,
In View Object (destination) depending on the cardinality of the destination. For example, in a one-to-
many view link, if your source view object is DepartmentsView and your
destination view object is EmployeesView, selecting the source option
would generate an accessor in DepartmentsViewImpl that would return a
collection of view rows from EmployeesView; selecting the destination
option would generate an accessor in EmployeesViewImpl that would
return a view row from DepartmentsView.
In Entity Object (source) If the view object is based on exactly one entity object, select this option to
generate an accessor in that entity object. This accessor returns a view row
In Entity Object (destination) or a collection of view rows, depending on the cardinality of the destination.
For example, if DepartmentsView is based on Departments, the source
option would generate an accessor in DepartmentsImpl that would return a
collection of view rows from EmployeesView. If EmployeesView is based on
Employees, the destination option would generate an accessor in
EmployeesImpl that would return a view row from DepartmentsView.
Source Accessor Name Type a name for the accessor. For example, getDepartmentsView might
be a good name for an accessor that returns a row from
Destination Accessor Name DepartmentsView. The same name is used for both view object and
entity object accessors.
To generate an view link accessor:
1. For the source or destination view object, select Expose Accessor.
11-578
2. Optionally change the name of the accessor method in the Accessor Name field.
To not generate an association accessor:
❍ For the source or destination view object, deselect Expose Accessor.
Related topics
11-579
A view link is defined in an XML file.
11-580
Creating an Application Module
The Application Module Wizard lets you create application modules at design time. You can also
create a default application module by using the Business Components Project Wizard and
Package Wizard.
To create an application module with the Application Module Wizard:

❍ Choose File | New, click Business Components, and double-click Application
Module.
❍ In the Navigator, right-click a business components package and choose New
Application Module.
The Application Module Wizard appears.
3. In the Name page, specify an application module name, the package the application
module should be placed in, and optionally an existing application module to extend.
Click Next.
4. In the Data Model page, specify which view objects and view links will be included in the
application module, including any master-detail relationships. Click Next.
5. In the Application Modules page, specify any nested application modules you want to
include, and optionally supply a member name. Click Next.
When application modules are nested, the outermost (top-level) application module
provides the transaction context for the others. The member name identifies an instance
of an application module; if an application module is used more than once, member
names can help you distinguish between the instances. When you nest an application
module within another, the parent application module can use the objects and code in
the child application module.
6. In the Java page, specify if you want the wizard to generate a Java file for the application
module class. Click Next.
You need the Java file if you want to customize the application module behavior by
11-581
adding code.
Related topics
11-582
Specifying the Name and Package of an Application
Module
While creating an application module with the Application Module Wizard, use the Name page
to specify a name and package for this application module. You may also specify an application
module that this application module extends from.
Field descriptions
Field Description
Name Type the name of the application module, which describes the module, and
perhaps ends with the string "Module" to make it easy to identify.
Package Type the package the application module should be placed in. Click Browse
to select an existing package. Note that the application module doesn't
have to be in the same package as the view object, view links, and
application modules it contains.
Extends Application Module (Optional) Type the name of an existing application module you want to
extend. The application module must extend directly or indirectly from from
oracle.jbo.server.ApplicationModuleImpl. Click Browse to
select it from a dialog. This is a useful feature if you want to provide
additional functionality or extend a previously created view link that you
don't have the source for. See Extending an Existing Application Module.
1. In the Name field, type the application module name.
To extend an existing application module:
1. In the Extends Application Module field, click Browse to select an application module in
your project to extend.
2. In the Name field, optionally change the application module name.
11-583
● Click Next.
Related topics
11-584
Extending an Existing Application Module
While creating an application module with the Application Module Wizard, expand the tree and
select the application module you want to extend from.
An application module provides a logical container for the data model and optional
programming logic needed to support an application task. The data model includes not only the
view objects which the application will use, but also any view links which will establish the
automatic master-detail coordination behavior the client might require.
If your intention is to work with new views of the data by combining new or existing view objects
in a different configuration, it might be easier to create a new application module and add the
Views and their relationships to its data model. However if your intention is to augment and
leverage the existing data model, you can extend the application module.
The most common reason to extend the application module is to add new top-level views that
are not related to anything in the original data model, but are useful in the context of the
application. Other typical reasons why you might want to extend the existing application module
include:
● implement different initialization code for the application module.
● extending the data model to include new view objects and/or detail view objects.
● add new services or facilities to the application module.
An extended application module inherits the same data model and programming logic as the
original. By working with an extended application module, you can access all of the services
and facilities provided by the existing application. You are free to change the data model by
adding new views of data in the form of new top-level and detail view objects, view links, and
programming code. The only restriction on extending application modules is that you cannot
remove any of the features of the original data model.
For example, the following figure illustrates the changes you can make to the data model. In the
figure, the symbol VO represents view objects that belong to the original data model. The
symbol VO represents view objects added to the You can add view objects and create new
links for them (in red). Notice the original data model (in black) is unchanged.
11-585
To create the extended application module, you can make any of the following changes to the
original:
● create new or extended view objects as top-level or detail views, link them together, then
add them to the data model to return a different slice of the data.
● use existing view objects linked in a different configuration in the data model.
● expose new application module, view object, or view row methods that were hidden or
did not exist in the original application module's implementation file.
To Extend an Application Module
1. Right-click the package that will hold the customized application module and select New
Application Module. The Application Module Wizard opens.
2. In the Name page, enter the name of the extended application module (NewModuleEx)
in the Name field. To offer you greater flexibility, note that in this page, the Name,
11-586
Package, and Extends Application Module fields are editable.
3. Click the Browse button next to the Extends Application Module field to open the
Parent dialog. Open the package of original components and select the name of the
application module that you want to extend. Click OK to close the dialog. Click Next in
the Name page to proceed to the Data Model page.
4. In the Data Model page, select the top-level and detail view objects that you want to add
to the existing data model. For more information on adding objects to the data model,
see To Build a Data Model for the Application Module. Click Next to proceed to the Java
page.
5. In the Java page, select the Generate Java file(s) check box to generate an editable
Java file that you can edit to customize the application module's behavior. Typically, this
is the file where you would add methods that you want to expose to the client tier.
If this checkbox is cleared, JDeveloper generates only an XML file. Click Finish to
generate the extended application module.
JDeveloper generates a .xml file and an optional .java file for the extended application
module in the Navigator window.
Understanding the Generated Extended Application Module Files
The NewModuleEx application module is created by extending the functionality of the

Package27Module application module without any source code modification. JDeveloper
creates a a .xml and an optional .java file for NewModuleEx which can be seamlessly
integrated into the packaged application. The NewModuleEx application module can now be
used at runtime, however, you might want to add some additional features, such as adding an
application module method, to its .java file and exporting it for use by the client. You can then
substitute it for all instances of Package27Module in the original application. For information
on how to substitute NewModuleEx for all instances of Package27Module in your application,
see Substituting Business Components.
Notice that the extended application module XML file lists only the view objects and links that
were added to its data model. The following is a code sample of NewModuleEx.xml.
11-587
2 <!DOCTYPE AppModule SYSTEM "jbo_03_01.dtd">
3 <AppModule
4 Name="NewModuleEx"
5 Extends="package27.Package27Module"
6 ComponentClass="Extender.NewModuleExImpl" >
7 <DesignTime>
9 <Attr Name="_deployType" Value="0" />
10 <Attr Name="_exportName" Value="NewModuleEx" />
11 </DesignTime>
12 <ViewUsage
13 Name="NewDeptViewEx"
14 ViewObjectName="Extender.NewDeptViewEx" >
15 </ViewUsage>
16 <ViewUsage
18 ViewObjectName="Extender.NewEmpViewEx" >
19 </ViewUsage>
20 <ViewLinkUsage
21 Name="NewViewLinkEx"
22 ViewLinkObjectName="Extender.NewViewLinkEx"
23 SrcViewUsageName="Extender.NewModuleEx.NewDeptViewEx"
24 DstViewUsageName="Extender.NewModuleEx.NewEmpViewEx" >
25 <DesignTime>
27 </DesignTime>
28 </ViewLinkUsage>
29 </AppModule>
Lines 4-6: The Name and Extends fields identify the name of the extended application module
(NewModuleEx) and the name of the original application module which it extends
(package27.Package27Module). The ComponentClass field identifies the name of the
implementation file (that is, the *Impl file) for the extended application module.
Lines 12-14, 17, 18: The Name and ViewObjectName fields in the ViewUsage tag identify the
name and full package name of the view objects added to the extended application module's
data model.
Lines 20-24: The Name and ViewLinkObjectName fields in the ViewLinkUsage tag identify
the name and full package name of the extended view link. The SrcViewUsageName and
DstViewUsageName fields identify the names of the view link's source view object and the
destination view object.
11-588
11-589
Specifying the View Objects and View Links in an Application Module's
Data Model
While creating an application module with the Application Module Wizard or editing an application module with the Application
Module Editor, use the Data Model page to specify the views of data that your clients will use, including the view object instances that
the client needs and the view links specifying master-detail relationships. You can also create data models used exclusively by the
business logic tier, and not by clients.
If a view object is part of a view link, you can include the view object
● in a master-detail relationship where the detail data is based on ("restricted by ") the current master data,
● individually (not part of a master-detail),
● or both,
depending on the needs of the client or business logic tier. See the example later in this topic.
You can include view objects and view links from different packages in the data model. However, remember that if you ever want to
reuse the application module in another project, you will need to also include all packages used by the data model.
If you have nested application modules, you must open the application module in the wizard or editor and create the data models
separately. You do not see the data models of nested application modules in the Data Model page — you see the data model of the
application module you're creating or editing only.
After completing the wizard or editor, you can view and test the complete data model, including the top-level application module and
any nested applcation modules, in the Tester.
By setting up the data model at design time, you can program the client application to simply instantiate the application module it
needs and immediately find all the appropriately coordinated view objects ready-to-use, conserving network roundtrips and startup
time. Prebuilding the entire data model helps keep the client user interface thin. You can create multiple application modules with
different data models that clients can use for different purposes.
Field descriptions
Field Description
Available View Objects A list of view objects defined in the project that contains the application module, grouped by package. View objects that
are related through view links are displayed in a hierarchy, detail under master. Click the plus sign (+) to expand nodes or
the minus sign (-) to collapse them. Details are identified using this syntax: view_object via
view_link_from_master_to_detail.
To move a view object to the data model, follow the instructions later in this topic.
Data Model (Optional) A list of view object and view link instances in the data model. Master-detail relationships are displayed in a
hierarchy, detail under master. To include a master view, select the application module in the Data Model list, then shuttle
a view object from the Available View Objects list to the Data Model list. To include a detail view, while the master is
selected in the Data Model list, shuttle the detail view over from the Available View Objects list.
Note: If you want to insert a particular view as a detail of another, and there is no detail available in the Available View
Objects list, you need to define a view link that relates the master to the detail you want.
If you are using polymorphic view objects, click Subtypes to specify the children view objects.
11-590
Name A name that identifies the view object instance in the data model. JDeveloper provides a default name based on the view
object you select in Available View Objects. You can accept the default name, which will be added to the Data Model
when you click the right arrow (>), or change it. To provide a name before you add a view object, select the view object in
the Available View Objects list, type a new name in the field beneath the list, and click the right arrow (>); or to change the
name after you've added it to the data model, select a name in the Data Model list, type a new name in the field beneath
the list, and click Rename. When you work with the view object in code, you use this instance name to refer to it. The
name must be unique.
To add a view object instance to the data model:
1. In the Available View Objects list, select a view object directly beneath the package in the tree structure.
2. In the Data Model list, select the application module.
3. Click the right arrow (>) to move an instance to the Data Model list.
4. If you are using polymorphic view objects, click Subtypes to specify the children view objects.
To add a master-detail relationship to the data model:
You can add a master-detail relationship to the data model based on a pre-existing view link relationship.
1. Add the master view object instance to the data model, as described in the previous steps.
2. In the Data Model list, select the master view object instance.
3. In the Available View Objects list, select the detail view object instance, which must be directly beneath the view object in the
tree structure.
Click the plus sign (+) next to the master view object, if needed, to expand the tree structure. If you don't see the detail you
need, you first need to exit the Application Module Wizard or Editor and define a view link for this relationship.
4. Click the right arrow (>) to move the detail view object instance to the data model.
The detail view object instance will provide a restricted view of the underlying data based on key values in the master.
5. If you are using polymorphic view objects, click Subtypes to specify the children view objects.
To change a view object instance name in the data model:
You can change the name a view object instance has in the data model, for example, to make it more descriptive.
● To provide a name before you add a view object, select the view object in the Available View Objects list, type a new name in
the Name field beneath the list, and click the right arrow (>).
● To change the name after you've added it to the data model, select a name in the Data Model list, type a new name in the
field beneath the list, and click Rename.
To remove a view object instance from the data model:
11-591
You need to remove any details before you can remove a master.
● Select a view object instance in the Data Model list, and click the left arrow (<).
● To continue with the wizard, click Next.
Example
Let's say you have a view object for each of the entities in the following UML diagram, and a view link for each association:
Your data model might look something like this:
The master views are directly under the package. If you have view links, detail views appear under the master view based on the
11-592
view link relationships. In the Available View Objects list, they are identified as
view_object via view_link_from_master_to_detail
The data model expresses the following relationships:
● The CustomerView view object is linked to the OrdView view object by a one-to-many view link called OrderPlacedByLink.
● The OrdView view object is linked to the LineItemView view object by a one-to-many view link called ItemOrderedOnLink.
● The SupplierView view object is linked to the InventoryItemView view object by a one-to-many view link called
SuppliedByLink.
● The InventoryItemView view object is linked to the LineItemView view object by a one-to-many view link called
OrderForItemLink.
● The CategoryView view object is not linked to other view objects.
To simplify the data model, you can remove view objects and view links that you don't need.
The AppModuleImpl class will contain code that creates the view object and view link instances. For example:
public CustomerViewImpl getCustomerView()

{
return (CustomerViewImpl)findViewObject("CustomerView");
}
public ViewLinkImpl getOrderPlacedByLink()

{
return (ViewLinkImpl)findViewLink("OrderPlacedByLink");
}
Related topics
11-593
Nesting Application Modules
application module with the Application Module Editor, use the Application Modules page to
add nested application modules. When application modules are nested, the outermost (top-
level) application module provides the transaction context and can use the objects and code in
the nested application modules.
The Application Modules page shows one level of hierarchy — the nested application modules
directly under the application module you're creating or editing. If you want a nested application
module to have a nested application module, you need to edit the nested application module
separately in the wizard or editor.
You can include nested application modules from different packages. However, remember that
if you ever want to reuse the application module in another project, you will need to also include
all packages used by the top-level application module.
You can view and test the application module hierarchy in the Tester.
When you finish the wizard or editor, the AppModuleImpl class will contain code that creates
the nested application module instances. For example:
public ApplicationModuleImpl getAppModule()

{
return (ApplicationModuleImpl)findApplicationModule("AppModule");
}
Field descriptions
Field Description
Available A list of application modules defined in the current project. To select an application
module from the list, select it, and then click the right arrow (>). JDeveloper displays the
name in the Selected list. Note that an application module can only appear once in the
hierarchy; for example, if AppModule1 contains AppModule2, then AppModule2 can't
contain AppModule1.
Selected (Optional) A list of nested application modules in this application module. To remove
one from the list, select it, and then click the left arrow (<).
11-594
Alias A name that identifies an instance of an application module. If an application module is
used more than once, aliases can help you distinguish between the instances.
JDeveloper provides a default name based on the application module you select in the
Available list. You can accept the default name, which will be added to the Selected list
when you click the right arrow (>), or change it. To provide a name before you add an
application module, select the application module in the Available list, type a new name
in the field beneath the list, and click the right arrow (>); or to change the name after
you've added it to the Selected list, select a name in the Selected list, type a new name
in the field beneath the list, and click Rename. When you work with the application
module in code, you use this instance name to refer to it. The name must be unique.
To add a nested application module:
1. In the Available list, select an application module beneath a package in the tree
structure.
2. Click the right arrow (>) to move an instance to the Selected list.
To change an application module instance name:
You can change the name a nested application module instance has in the parent application
module, for example, to make it more descriptive.
● To provide a name before you add an application module, select the application module
in the Available list, type a new name in the field beneath the list, and click the right
arrow (>).
● To change the name after you've added it, select a name in the Selected list, type a new
name in the field beneath the list, and click Rename.
To remove an application module instance:
● Select an application module instance in the Selected list, and click the left arrow (<).
11-595
Related topics
11-596
Generating a Java Source File for an Application
Module
application module with the Application Module Editor, use the Java page to specify whether
the wizard generates a Java file for the application module class. By default, the wizard
generates the class. You can edit the class to customize the application module's behavior
through its methods. You can also generate this class from a customized base class.
Field descriptions
Field Description
Application Module When this checkbox is selected, JDeveloper generates a Java file you can edit to
Class: AppModuleImpl customize the application module class' behavior. Otherwise, JDeveloper generates
an XML file only.
Generate
Java
file(s)
Extends (Optional) Click Extends to select an application module base class that you want to
use to generate the application module. Typically, in an applications organization,
the framework supplied by JDeveloper will be customized by a core group and all
view objects for the organization may be built over this customized framework.
To generate an application module class:
class.
11-597
Related topics
11-598
The Files that Define an Application Module
An application module is a logical container for coordinated objects related to a particular task,
with an additional capacity for programming logic. Application modules provide a simple
runtime data connection model (one connection per application module) and a context for
defining and executing transactions.
An application module can contain view objects, view links, and other (nested) application
modules. It is defined in an XML file and optionally Java files.
When you complete the wizard, click Finish to create the application module. To quit the wizard
without saving any changes, click Cancel.
Related topics
11-599
Ways to Edit View Objects, View Links, and
Application Modules
These topics describe how to edit view objects, view links, and application modules:
● Editing a View Object
● Editing a View Link
● Editing an Application Module
● Ways to Edit View Attributes
Related Topics
11-600
Editing a View Object
The View Object Editor lets you create and edit view objects.
Default view objects are very simple in their definition. Use the View Object Wizard and Editor
to create and edit view objects so they are tailored to your needs. This might include a view
object that uses
● a subset of an entity object's attributes
● attributes from more than one entity object
● special SQL-derived or transient attributes
● non-default storage and updateability features
The ability of a view object to use multiple updateable entity objects enables one of the key
features of Business Components for Java: a single view object can update multiple entity
objects.
To edit a view object, in the Navigator, right-click the view object and choose Edit object. Or
double-click it.
When editing a view object, the editor lets you specify the following information, which you can
also set in the wizard:
● Selecting Entity Objects to be Used by a View Object
● Creating, Removing, and Ordering View Attributes
● Specifying View Attribute Settings
● Customizing the SQL Statement of a View Object
● Mapping View Attributes to SQL Columns
11-601
● Generating Java Source Files and Methods for View Objects
In addition, the editor lets you specify the following information, which you can't specify in the
wizard:
● Tuning View Object Performance by Adjusting the Row Fetch Size, Providing Query
Hints, and Specifying Page Iteration Mode
● Exporting View Object Methods
● Exporting View Object Row Accessor Methods
If you change a database table after you have created a view object and you need to modify
the view object, you can make the change manually in the View Object Editor. For example,
you can add attributes corresponding to new columns in the entity object.
Related topics
11-602
Exporting View Object Methods
While editing a view object in the View Object Editor, use the Client Methods page to select
view object methods to export, so the client can using the view object can call the methods
remotely.
Before you can use this page, in the Java page, you must generate the view object class.
Methods you've written in the view object class file appear in the Available list; to appear in the
list, they must be of a data type that implements the Serializable interface and be public.
You need to do a few other things before the client can use the methods, including making the
application module remotable (for remote mode), importing the package in the client code, and
invoking the method properly in the client code, as described in other parts of the online help.
Warning: For remotable application modules, the actual work to export the methods is done by
application modules using the view object. It is the Application Module Wizard code generation
step that takes the exported methods and generates the appropriate remote connection
mechanisms necessary to export the methods to the client applications. After you choose to
export a method, you must invoke the Application Module Editor for each of the application
modules using this view object. This step is necessary to regenerate the remote code to match
the new view object exported method interface.
Field descriptions
Field Description
A list of generated methods available for export (only
public methods implementing the Serializable
interface will be included in the list). You can export
Available methods by moving methods from the Available list to
the Selected list: select one or more methods, and click
the left arrow (>). Or click the double left arrow (>>) to
move all methods.
(Optional) A list of methods that will be exported. To
remove a method from the list, select one or more
Selected
methods, and click the left arrow (<). To remove all
methods, click the double left arrow (<<).
To add a method:
The Available list displays the public methods you can export. Move one or more methods from
the Available list to the Selected list in one of these ways:
11-603
● In the Available list, select a method, control-click to individually select multiple methods,
or shift-click to select a range of methods, and then click the right arrow (>).
● In the Available list, double-click a method.
● To move all methods, click the double right arrow (>>).
To remove a method:
● Select one or more methods in the Selected list, and click the left arrow (<).
● Double-click a method in the Selected list.
● Click the double left arrow (<<) to remove all methods.
To save changes:
Related topics
Creating Methods for Clients to Use
Exporting View Object Row Methods
Creating a Remote Application Module
Exporting Application Module Methods to Clients
11-604
While editing a view object in the View Object Editor, use the Client Row Methods page to
select view object row methods to export, so the client can using the view object can call the
methods remotely. Accessors are available for any row retrieved by the view object. This page
adds the methods you choose to your view object row implementation class and permits
remote clients that use the view object to access specific row instances, rather than requiring
them to access the view object's row collection.
Before you can use this page, in the Java page, you must generate the view row class. Methods
you've written in the view row class file appear in the Available list; to appear in the list, they
must be of a data type that implements the Serializable interface and be public.
You need to do a few other things before the client can use the methods, including making the
application module remotable (for remote mode), importing the package in the client code, and
invoking the method properly in the client code, as described in other parts of the online help.
Warning: For remotable application modules, the actual work to export the methods is done by
application modules using the view object. It is the Application Module Wizard code generation
step that takes the exported methods and generates the appropriate remote connection
mechanisms necessary to export the methods to the client applications. After you choose to
export a method, you must invoke the Application Module Editor for each of the application
modules using this view object. This step is necessary to regenerate the remote code to match
the new view object exported method interface.
Field descriptions
Field Description
move all methods.
(Optional) A list of methods that will be exported. To
remove a method from the list, select one or more
Selected
methods, and click the left arrow (<). To remove all
methods, click the double left arrow (<<).
To add a method:
11-605
To remove a method:
To save changes:
Related topics
11-606
Editing a View Link
The View Link Editor lets you edit view links.
To edit a view link, in the Navigator, right-click the view link and choose Edit link. Or double-
click it.
When editing a view link, the editor lets you specify the following information, which you can
also set in the wizard:
● Specifying the View Objects to Link

● Specifying the Attributes in a View Link
● Customizing the SQL of a View Link
● Specifying the Cardinality and Directionality of a View Link
Related topics
11-607
Editing an Application Module
The Application Module Editor lets you edit application modules.
To edit an application module, in the Navigator, right-click the application module and choose
Edit module. Or double-click it.
When editing an application module, you can specify the following information, which you can
also specify in the wizard:
● Specifying the View Objects and View Links in an Application Module's Data Model
● Nesting Application Modules
● Generating a Java Source File for an Application Module
In addition, the editor lets you specify the following information, which you can't specify in the
wizard:
● Creating a Remote Application Module
● Exporting Methods to Clients
Related topics
The Files that Define an Application Module
11-608
11-609
While editing an application module with the Application Module Editor, use the Remote page
to make an application module "remotable" and specify which platforms you intend to support
with this application module. JDeveloper generates the files appropriate for the platforms you
select. For more information about these files, see About Business Components and Wire
Protocols.
All business components are deployed in the context of an application module. An application
module has get methods for the view objects, view links, and nested application modules it
contains as well as exportable methods. Making the module remotable generates additional
classes for it, specific to its deployment platform.
Supporting one or more platforms enables three-tier application development. If you do not
choose to make a remotable application module, you are restricted to running in two-tier client-
server mode. Note that you can make your application module remotable at any stage in the
development cycle.
The editor can create three types of files for your target platform:
● files that are only used by the business logic tier (located in the server subpackage)
● files that are used in both the business logic and client tier (in the common subpackage)
● files that are used only in the client tier (in the client subpackage)
See Making an Application Module Remotable, later in this topic, for complete step-by-step
instructions involving more than just the Remote page of the Application Module Editor.
Field descriptions
Field Description
Remotable When selected, JDeveloper enables the target platforms in the Available list.
Application Module
11-610
Available A list of available platforms. To generate a remotable application module for a platform,
select one or more platforms, and then click the right arrow (>); or to add all platforms,
click the double right arrow (>>). JDeveloper displays the name in the Selected list.
Use the shuttle buttons to select from the following available target platforms.
Note: If you are deploying an EJB to Oracle 9iAS, you will most likely want to select
AppModule Session Bean (BMT). In certain specific cases you should choose one of
the other options. For more information, see About Service Beans and About
Container-Mananged and Bean-Managed Transactions.
AppModule Session Bean (BMT)
Select this option to generate the code necessary to

deploy a remote application module to Oracle 9iAS as
an application module session bean with bean-managed
transactions.
AppModule Session Bean (CMT)

deploy a remote application module to Oracle 9iAS as
an application module session bean with container-
managed transactions.
Service Session Bean (BMT)

deploy a remote application module to Oracle 9iAS as a
service bean with bean-managed transactions.
Service Session Bean (CMT)

deploy a remote application module to Oracle 9iAS as a
service bean with container-managed transactions.
CORBA Server for VisiBroker
Select this checkbox to generate the code necessary to

deploy a remote application module to VisiBroker.
Selected A list of platforms that you need a remotable application module for. To remove one
from the list, select one or more platforms, and then click the left arrow (<); or to
remove all platforms, click the double left arrow (<<).
11-611
Target Platform When you select one platform in the Selected list, the appropriate fields are enabled in
the Target Platform area.
EJB For any platform but CORBA, type the name of the EJB. This will be the name used in
Name the <ejb-ref> tags of clients. It can be any valid Java identifier.
Client For CORBA and application module session beans, enter the name of the client for
Project your application module. You can also designate a separate project that you must then
deploy with all of the clients to your application module. If you have not created the
client project yet, the editor will create one for you. Click Browse to browse for an
existing client project.
The editor will add the necessary files for this application module to the client project.
Files will be added to your client project only if you export methods in the Client
Methods page. If you did not, this field is not present. This field is also not present for
service beans; client methods will simply be added to the remote interface of the EJB.
To add a platform:
1. Select Remotable Application Module.

2. Move a platform from the Available list to the Selected list in one of these ways:
❍ In the Available list, select a platform, control-click to individually select multiple
platforms, or shift-click to select a range of platforms, and then click the right arrow
(>).
❍ In the Available list, double-click a platform.
❍ To move all platforms, click the double right arrow (>>).
Next, you need to add information in the Target Platform area as follows.
To add EJB name and/or client project information:
1. Select a platform in the Selected list.

2. Type information in the Target Platform fields.
To remove a platform:
● Select one or more platforms in the Selected list, and click the left arrow (<).
11-612
● Double-click a platform in the Selected list.
● Click the double left arrow (<<) to remove all platforms.
To save changes:
To make an application module remotable:
The following steps assume that the application module already defines the logical data model
and business methods needed to support an application task.
1. Select Remotable Application Module.
2. Select the target platform(s) you want to deploy to by moving them from the Available list
to the Selected list.
3. In the Client Methods page, specify any methods that you want to make available to
clients.
After you click Apply or OK to apply your changes, and you recompile the project, JDeveloper
creates a folder for each selected platform beneath the application module in the navigator.
Each of these folders contains a Server folder and a Common folder.
● The Server folder contains the files that will be deployed only to the server.
● The Common folder contains code that will be used by both the business logic tier and
client.
If you chose to export application module methods, the framework also creates a
Project_namePlatformClient.jpr folder beneath the project in the Navigator, for each
platform you chose (except service beans). This folder contains the client-side proxy for the
application module.
For EJBs, the framework also creates an ejb-jar.xml file. For more information about this
11-613
file, see About EJB Files Generated by JDeveloper.
Example
Let's say you have a project, hrProject, with an application module, hrPackageModule,
that you want to make remotable to an application module session bean with bean-managed
transactions and to a CORBA server for VisiBroker. After completing the Remotable and Client
Methods pages of the Application Module Editor, the framework generates these files and
folders:
● Beneath the application module node, the framework creates a beanmanaged folder and
a vb folder. Each of these folders contains a Common folder that contains files that will
go on both the business logic tier and client tier and a Server folder that contains files
that will go on the business logic tier only.
● Beneath the workspace node, the framework generates an hrProjectEJBClient.jpr folder

and an hrProjectVBClient.jpr folder which contain two different files both named
hrPackageModuleClient.java. Note that if you do not export methods, these folders
and files are not generated.
Related topics
Understanding the n-Tier Business Components Architecture
About Service Beans
About Container-Managed and Bean-Managed Transactions
Deploying BC4J as an EJB Session Bean to OC4J
Deploying BC4J as an EJB Session Bean to WebLogic
Starting CORBA Objects on VisiBroker
11-614
While editing an application module with the Application Module Editor, use the Client Methods
page to choose methods that you want to make available to clients when you use a two- and
three-tier application architecture, with the application module running in the business logic tier.
The editor will create the Java files necessary to support method exporting for the target
platforms you have selected in the Remote page. These files will be added to the business
logic tier project as well as to a client project.
Before you can add methods in this page, you need to add the custom methods to your
AppModuleImpl file. Also, you must select Generate Java files in the Java page.
When you click Apply or OK, an export interface file, directly or indirectly extending
oracle.jbo.ApplicationModule, is created. You need to do a few other things before the
client can use the methods, including importing the interface in the client code and invoking the
method properly in the client code, as described in Calling Methods from Clients.
Field descriptions
Field Description
move all methods.
A list of methods that will be exported. To remove a
method from the list, select one or more methods, and
Selected
click the left arrow (<). To remove all methods, click the
double left arrow (<<).
To add a method:
11-615
To remove a method:
To save changes:
Related topics
Understanding Deployment Configurations
Ways to Create and Export Business Logic Tier Methods to Clients
About Custom Client Methods
11-616
Ways to Edit View Attributes
You can edit attributes in the
● View Object Editor
● Attribute Editor
The View Attribute Editor is where you can specify properties and control hints at the attribute
level.
To use the View Attribute Editor, in the Navigator, select a view object. Then right-click an
attribute in the Structure pane and choose Edit attribute; or simply double-click it.
You can specify the following information in the View Attribute Editor:
● Editing View Attribute Settings
● Editing Entity Attribute Settings (if the view attribute is based on an entity attribute)
● Defining User Interface Control Hints
Related topics
What is a View Attribute?
11-617
Editing View Attribute Settings
While editing a view attribute in the Attribute Editor, use the View Attribute page to define
attribute settings for a view attribute.
Field descriptions
Attribute Persistent Entity-Derived Transient SQL-Derived

Setting Attribute Attribute Attribute Attribute
Attribute Name Default based Default based on Required Required

on entity entity attribute
attribute name name
Attribute Type Not modifiable; Not modifiable; Required Required
uses entity uses entity
attribute setting attribute setting
Selected in Query When When selected, When Selected
selected, this this attribute selected, this
attribute appears in the attribute
appears in the view object's appears in the
view object's SQL Select view object's
SQL Select statement. SQL Select
statement. statement.
Key Attribute When When selected, When When selected, this
selected, this this attribute is a selected, this attribute is a key
attribute is a key attribute. attribute is a attribute.
key attribute. key attribute.
Discriminator Selectable Selectable Selectable Selectable
Updateable Based on Based on entity Selectable Selectable
entity attribute attribute setting;
setting; can can make setting
make setting more restrictive.
more
restrictive.
Alias Default based Optional Optional Optional, can use to
on entity prevent name
attribute name; conflicts
optional, but
can use to
prevent name
conflicts
Expression N/A Optional N/A (NULL) Required (not NULL)
11-618
Queriable Selectable N/A N/A Selectable
To save changes:
● After you are finished, click OK to save your changes.

Related topics
11-619
The view objects that you design perform queries on their underlying entity objects. Often, as a
part of your application, you create business logic and validation rules to process the output
from view objects and the data values they can accept. By using the Business Component
Browser (also called the Tester, for short), you can ensure that your view object's business
logic and validation rules are working correctly before you deploy it or make it a part of a larger
application.
The Tester lets you test the output of your view objects as soon as you create them; you do not
have to create an application to run them. The Tester is an independent utility. It detects the
view objects present in an application module or package and creates a default application
module to run them. The view objects can either be independent, or in a master-detail
relationship defined by a view link.
The Tester helps you ensure that the business logic and validation rules are being applied
correctly by letting you insert, update, delete, and query view object data. It accepts changes
which meet business logic and validation rule criteria, and returns exceptions for changes that
do not. You can also use the Tester to create new view objects or links to query for different
output.
You can use the Tester to examine the output of an individual view object or of a master-detail
set of view objects defined by a view link. After you open the Tester and connect to a database,
it creates a default root application module, then installs your application module as a child of
the root. For view objects, the Tester displays the query results. For view links that coordinate
the output of two view objects, the Tester displays the query results, with the master-detail
relationship constructed for you.
To test the business logic tier:
1. In the Workspace view of the Navigator, right-click the application module and choose
Test.
JDeveloper compiles your project.
2. In the Connect dialog, make sure that the connection information is valid, and then click
Connect.
The Tester appears. Its Navigation pane displays all the view objects and view links in
the application module. You can display them in the right pane.
11-620
Remember that default view objects and view links were automatically generated based
on the database tables and key relationships.
3. Perform the operations you want to try in the Tester:
❍ Executing a View Object or Link Query
❍ Reexecuting a Query in the Tester
❍ Viewing and Changing Called Methods and Values in the Tester
❍ Examining Attribute Characteristics in the Tester
❍ Examining XML Output in the Tester
❍ Examining Diagnostic Information from the Tester
❍ Enabling Debug Tracing in the Tester
4. When you are finished testing your program, choose File | Exit to close the Tester.
11-621
Using the Tester Menus and Buttons
This topic describes the following Business Component Browser (Tester) features:
Menu Bar
Browser Icons
Data Navigation Icons
Menu Bar
The Tester has the following menu items:
File
Save Transaction State - Saves the application module state. Remember the transaction
ID to reload the state later.
Restore Transaction State - Reloads the application module state specified by the
transaction ID.
Note: The Tester uses "remove when reloaded" logic for persistence.
After you retrieve a saved state, it's removed from persistent storage,
so you can't reload it again. You would need to save it again to put it
back in persistant storage.
Exit - Closes the current database connection and exits the browser.
View
Data As XML - Displays the output of the view object or link in a frame in XML format. No
header or DTD information is supplied, but you can copy and paste the {}";poutput into a
file that does. You can also save the contents of the frame to disk.
Create
Application Module - Opens the Create Application Module dialog where you can create
11-622
a default application module in the Tester. To create a default application module, you
choose an existing application module in the JDeveloper package to act as a model.
View Object - Opens the Create View Object dialog where you can create a new view
object to display your data and exercise your business logic. These view objects are not
based on underlying entity objects; you construct them from either existing view objects
or SQL statements.
View Link - Opens the Create View Link dialog where you can create a new view object
to display your data and exercise your business logic. The new view link is not based on
underlying entity objects; instead, it is based on an existing view link or association.
Database
Commit - Commit changes.
Rollback - Rollback changes.
Help
Contents - Displays main Tester help.
About - Displays an informational box describing the Tester.
Browser Icons
Use the browser icons to manage the business component session and whether data changes
are saved to the database.
Saves changes that you made to the displayed data back to the database.
Discards changes that you made to the displayed data and restores the original values.
Data Navigation Icons
Use the navigation icons to navigate through your data. The following table describes the icons:
11-623
Go to the first record.
Go to the previous record.
Go to the previous page.
Go to the next record.
Go to the next page.
Go to the last record.
Insert a new record.
Delete a record.
Specify view criteria - opens the View Criteria dialog where you can search for, view, or remove data
based on specified attribute value.
Display results in a window - lets you detach the window containing the query results from the Tester.
Close the current tab panel.
11-624
Executing a View Object or Link Query
To execute the query, in the left pane, you can either:
● Double-click a view object or view link.
or
● Right-click a view object or view link and choose Show.
The Tester displays the query results in the right pane.
11-625
Reexecuting a Query in the Tester
Sometimes you might want to reexecute a view object or link query. For example, if you are
running another business components program or submitting PL/SQL queries, you might make
changes to the database contents. If you want database-level changes to be reflected in the
Tester, you can reexecute the query. If you do not reexecute the query, the original rows are
still in the Tester's cache.
● In the left pane, right-click a view object or view link that has already been executed and
choose Re-execute query
The results display in the right pane.
11-626
Viewing and Changing Called Methods and Values
in the Tester
In the Tester, you can examine the called methods and their values, and change some values.
1. Right-click an application module, view object, or view link in the left pane and choose
Properties.
The Business Component Properties dialog appears. The Property column of the
Properties dialog lists the name of the method; the Value column lists its current value.
Values in gray fields are read-only.
2. To change a value in a white field, double-click that field.
3. Click Close.
4. To activate a value change, click in a field.
For more information on the methods listed in the Properties column, see the Javadoc for these
APIs:
● oracle.jbo.ViewObject for view object methods
● oracle.jbo.ViewLink for view link methods
● oracle.jbo.ApplicationModule for application module methods
The following table provides a brief description of some of the oracle.jbo.ViewObject

methods. Note that the list of methods that the Tester displays will be different depending on
the object you select.
Property Description
ComponentObject.Name Name of the current view object.
ComponentObject.FullName The fully-qualified application module name, package name, and view
object name.
11-627
ComponentObject.DefName Name of the view definition from which this view object originated.
ComponentObject.DefFullName Package-qualified name of the view definition from which the view object
originated.
RowIterator.FetchedRowCount The number of rows currently fetched in the row set.
RowIterator.CurrentRowIndex The absolute index (not range index) of the current row object.
RowIterator.CurrentRowSlot The slot status of the current row (one of the SLOT_... constants).
RowIterator.RangeSize The size of the row set range. Set this method to -1 to return all rows.
RowIterator.RangeStart The starting position of the row set range (in absolute index).
RowIterator.RowCountlnRange The number of rows in the current range.
RowIterator.isRangeAtBottom True indicates that the last row of the range is the last row of the full set.
RowIterator.isRangeAtTop True indicates that the first row of the range is the first row of the full set.
11-628
Examining Attribute Characteristics in the Tester
The Tester lets you look at a variety of attribute characteristics, such as its Java and database
column names, its Java and SQL datatypes, and its storage and update properties.
1. Display a view object or link in the right pane.
2. Right-click an attribute name.
A popup displays the attribute characteristics.
3. Click in the Tester, outside the popup, to close it.
11-629
Examining XML Output in the Tester
In the Tester, you can look at the output of a view object or link as XML. Note that the Tester
does not provide a header or DTD information, but you can copy and paste it into a file that
does.
1. In the left pane of the Tester, select a view object or link.
2. Choose View | Data As XML.
The XML dialog appears.
3. Optionally click Save to save the contents of the frame to disk.
4. Click Close to close the XML dialog.
11-630
Testing Query Results
The Business Component Tester lets you validate new or changed values in the data displayed by a view
object. When you make changes to the data, the Tester compares the new values against the validation
rules or business logic that you defined for the underlying entity objects. If your new value passes the
business logic, then the Tester silently accepts it. If the new value does not pass the validation checks,
the Tester returns an error message in an alert box. So, testing query results is really testing whether your
validation rules and business logic is working correctly.
Note that to use this feature effectively, you should have some knowledge of the business logic which is
being applied to the data. That is, you should know which values will be accepted and which will raise an
error.
For example, suppose you defined a rule on the salary attribute Sal of the employee entity object Emp
such that salaries cannot be less than 1200. To test the rule, change the salary of the employee named
Blake in the MyEmpDetailView detail view. The change passes from the row in question to the Emp
entity object. Business logic attached to Emp executes and tests the new value. If the new value is greater
than 1200, it goes to the database. Otherwise, the Tester throws an exception.
To test the query results, you can:
● Change Data Values
● Query a Data Sample
If the query results are not what you expected or if you want to create different queries, you can use the
Business Component Tester to:
11-631
● Create new view objects
● Create new view links
Changing Data Values
You can exercise the validation rules and business logic you have defined by inserting, updating, and
deleting view object data. For example, suppose you just finished writing some business logic which
should fire if an employee's salary is greater than 1200. You can execute the Emp view object and change
the value of Sal to 1300 and see if your logic executes correctly.
To change view object or link data:
1. Double click a view object or view link in the navigator (or right-click the component and select
Show). The Tester executes the selected component and opens it in the browser.
2. Exercise the business logic by changing the values in any of the fields and then tabbing out of the
field. You can use any of the following methods to change data values:
● Delete the current field value.
● Replace the current field value with a different value or value of a different datatype.
● Insert a new record and enter values in the fields.
3. Values that pass the business logic or validation rules will be accepted and any logic dependent on
the values should execute. Values that violate the business logic or rules will return an exception in
an alert box.
Querying a Data Sample
When you are working with a view object or a master-detail set of view objects defined with a view link,
you can design a query to return only a subset of the data. Although the Business Component Tester
does not let you change the query for an existing view object, it will let you filter for data that meets
specific attribute values.
Use the Business Components View Criteria dialog to provide parameters for the query. Use the fields in
the dialog to construct a WHERE clause, where the elements of the clause are the attributes of the
current view. The query allows you to find just the row which you know contains some existing value that
11-632
you want to test. For example, suppose you just finished writing some business logic which should fire if
the status of an order changes from "New" to "Cancelled". You could use the Business Components View
Criteria dialog to query an order which was currently in the "New" state by using the criteria ='New' in the
Status attribute field. This would summon to the browser the first "New" order, and then you could try
changing "New" to "Cancelled" and see if your logic executes correctly.
The figure below illustrates the content of the Business Components View Criteria dialog for the
DeptView view object. Note that the dialog contains the same attributes as DeptView. For example, if
you wanted to view and test the data associated with department number 20, enter =20 in the Deptno
field and click Find. The browser will display the department name and location associated with
department 20.
To query view object and link data:
1. Double-click a view object or view link in the Navigator (or right-click a component and select
Show).
The Tester executes the component's query and opens it in the browser.
2. Right-click the component again and select Find. The Business Components View Criteria dialog
11-633
opens.
Note that you can also open the dialog by clicking the Specify View Criteria icon in the navigation
bar.
3. Enter values to return the row which contains some existing value that you want to test. If you do
not enter a value for an attribute, it is not included in the filter.
4. Click one of the buttons at the bottom of the dialog. The buttons perform these operations:
❍ Find - Displays the subset of data according to the values entered for the attributes.
❍ OR>> - Performs alternative query conditions. For example, you can enter =10 for Deptno
and =Accounting for Dname, then click OR>> then enter =20 for Deptno and =Sales for
Dname.
❍ Remove - Removes the current tab panel and its condition from the browser.
❍ Remove All - Removes all tabbed panels and their conditions from the browser.
❍ Cancel - Discards your changes and closes the Business Components View Criteria dialog.
❍ Help - Opens the help file associated with this dialog.
The contents of the data in the Business Component Browser will change to
reflect the output of the filter.
5. Insert, update, or delete the values in the fields that you want to test. Then tab out of the field.
Values that pass the business logic or validation rules will be accepted. Values that violate the
business logic or rules will return an exception in an alert box.
11-634
Creating an Application Module in the Tester
Use the Create Application Module dialog to create a default application module in the
Business Component Tester. To create a default application module, you choose an existing
application module in the JDeveloper package to act as a model. Typically, you will choose an
application module on the basis of which view objects and view links it uses. After you create
the default application module, the Tester will install the view objects and view links below it.
Application Module Name
Enter a name for your application module.
Application Module Definition Name
From the drop-down list, select the name of the application module that you want to use as a
model for your application module.
11-635
Creating View Objects in the Tester
Use the Create View Objects panel to construct new view objects to display your data and
exercise your business logic. These view objects are not based on underlying entity objects;
you construct them from either existing view objects or SQL statements.
From the View Object Creation Type drop-down list, select the method you want to use to
create your view object. The contents of the panel will change depending on your choice.
Select:
● From View Definition to create a new view object from an existing view object
● From Query Clauses to create a new view object from a simple SQL SELECT statement
on an entity object
● From SQL Statement to create a new view object from an arbitrary SQL statement
Creating View Objects from a View Definition
The Tester lets you create new view objects from existing view object definitions. The Tester
uses the existing view object as a factory class that can be used to generate new view objects.
You can use the new view object to exercise your business logic by updating, inserting, and
deleting data, and then saving your changes to the database. The view object itself cannot be
saved back to the project file.
View Object Name
Enter a name for your new view object.
View Definition
From the drop-down list, select the name of the view object on which you want to base the new
object.
Creating View Objects from Query Clauses
The Tester lets you create a new view object from a simple SQL query on an entity object. The
Tester lets you create a SQL query by entering values for the SELECT, FROM, WHERE, and
11-636
ORDER BY clauses. view objects that you create from SQL statements can be updated: you
can perform data inserts, updates, or deletes to the database. These view objects cannot be
saved back to the project file.
View Object Name
Entity Object Name
From the drop-down list, select the name of the entity object that you want to query.
SELECT / FROM / WHERE / ORDER BY
Enter your query criteria in the SELECT, FROM, WHERE, and ORDER BY fields.
Creating View Objects from a SQL Statement
The Tester lets you create a new view object from an arbitrary SQL statement. Typically, you
would use this panel when your SQL query is more complex than a simple SELECT statement.
For example, use this panel when you need to specify unions of tables. view objects that you
create from SQL statements can be updated: you can perform data inserts, updates, or deletes
to the database. These view objects cannot be saved back to the project file.
View Object Name
SQL Statement
Enter your SQL query statement in the list box. You can also copy and paste a SQL statement
from a text file into the box.
11-637
Creating View Links in the Tester
Use the Create View Links panel to construct new view links to display your data. The new view
link is not based on underlying entity objects; instead, it is based on an existing view link or
association. The Tester uses the existing link or association as a factory class that can
generate new view links. The Tester lets you specify which objects you want to use as master
and detail.
Typically, you base the definition of a new view link on an existing view link. However, if there
are no view links in your project, you can base the definition of the new view link on an existing
association.
The contents of the Create View Link panel changes depending one whether you are creating a
view link from an existing view link or an association.
View Object Creation Type
From the drop down list, select
● From View Link Definition to create a view link from an existing view link definition.
OR
● From Entity Association Definition to create a view link from an existing association.
View Link Name
Enter a name for your view link.
View Link Def Name/Entity Association
If you are creating a view link from an existing view link, select the existing view link to use as a
model for the new view link. The master-detail relationship defined by the view link will be
applied to the view objects you select on this panel.
If you are creating a view link from an existing association, select the existing association to
use as a model for the new view link. Similarly, the master-detail relationship defined by the
association will be applied to the view objects you select on this panel.
11-638
Master View Object
The drop-down list displays all of the view objects in your project. Select the name of the view
object that will serve as the master.
Detail View Object
The drop-down list displays all of the view objects in your project. Select the name of the view
object that will serve as the detail.
11-639
Querying Data with View Criteria in the Tester
When you are working with a view object or a master-detail set of view objects defined with a
view link, you can design a query to return only a subset of the data. Although the Business
Component Tester does not let you change the query for an existing view object, it will let you
query for data that meets specific attribute values.
Use the View Criteria dialog to provide parameters for the query. The fields in the dialog let you
construct a WHERE clause, where the elements of the clause are the attributes of the current
view. The query allows you to find just the row which you know contains some existing value
that you want to test.
Find
Displays the subset of data according to the values entered for the attributes.
OR
Executes alternative query conditions. For example, you can enter =10 for
Deptno and =Accounting for Dname, then click OR>> then enter =20 for
Deptno and =Sales for Dname.
Remove
Removes the current tab panel and its condition from the browser.
Remove All
Removes all tabbed panels and their conditions from the browser.
Cancel
Discards your changes and closes the View Criteria dialog.
11-640
Examining Diagnostic Information from the Tester
As you exercise business components, the Tester will direct any diagnostic information to
JDeveloper's Message window. Right-clicking the Message window will display a menu which
will let you:
● Copy the diagnostic information. You can then paste the information wherever you want.
● Save the diagnostic information to a file; that is, create a log file for the components
being tested.
● Change the log properties; that is, determine the type of diagnostic information logged
and its format.
● Clear the contents of the Message View; that is, clear the contents of the log for the
components being tested.
● Remove the Message View; that is, remove the log for the components being tested.
11-641
Enabling Debug Tracing in the Tester
By default, the Tester silences debug output. If you want to see business components
framework debug tracing output in the message view while running the Tester, then:
1. To launch the Tester, right-click the application module you want to test and choose
Test.
2. Provide appropriate connection information in the Connect dialog, and click Connect.
3. Select the node representing your application module at the root of the Tester tree and
choose Properties from the right-mouse menu.
4. In the Application Module Properties dialog that appears, set the jbo.debugoutput
property to the string value:
console to enable tracing to the message view
silent to silence the output
11-642
Managing Rows in Memory at Runtime
All view row spillover parameters are set on the business logic tier's Java VM.
To set Java VM parameters:
1. In the the Navigator, right-click a business component project and choose Project
Settings.
2. In the Configurations | Development | Runner pane, type the parameters in the Java
options field.
3. Click OK.
The values are added to the jboserver.properties file, which is stored in \lib\jbomt.zip.
When you deploy, you can include this file.
To enable view row spillover:
command line:
-Djbo.use.pers.coll=true
The default is false, meaning view row spillover is not enabled.
To set the maximum rows per node from the command line:
command line:
-Djbo.pers.max.rows.per.node=n
Where n is a number 5 or greater. The default is 70, meaning that there can be a maximum of
approximately 70 rows in a node at one time.
To set the node number from the command line:
11-643
command line:
-Djbo.pers.max.active.nodes=n
Where n is a number 2 or greater. The default is 10, meaning that there can be a maximum of
approximately 10 active nodes per session. The business logic tier will try to keep up to 10
active nodes in memory. When more nodes are created, under normal conditions, least
recently used nodes will be written to database first.
In addition, -1 is a valid value, meaning that spillover is disabled but you might still have nodes.
To set the maximum rows per node in a view object definition:
To the XML file of a view object, add the following attribute:
MaxRowsPerNode
Its value can be a number 5 or greater. The default is 70, meaning that there can be a
maximum of approximately 70 rows in a node at one time. This setting overrides the command
line setting for this view object.
To set the node number in a view object definition:
To the XML file of a view object, add the following attribute:
MaxActiveNodes
Its value can be a number 2 or greater. The default is 10, meaning that there can be a
maximum of approximately 10 active nodes per session. The business logic tier will try to keep
up to 10 active nodes in memory. When more nodes are created, under normal conditions,
least recently used nodes will be written to database first.
In addition, -1 is a valid value, meaning that spillover is disabled (but you might still have
nodes). This setting overrides the command line setting for this view object.
To clean up the view row spillover tables:
A database administrator must manually clear data in the database tables when it is no longer
used. You can use the script \bin\bc4jcleanup.sql, which contains instructions for scheduling a
cleanup routine to automatically clean up the database. Or you can use a procedure like the
11-644
following:
1. In the PCOLL_CONTROL table, look at the value of the UPDATEDATE column of a row.
Each row in the control table corresponds to a table for a transaction (the table name is
prefixed with PCST_ ).
2. If the UPDATEDATE is over one day old, write down the value in the TABNAME column,
then delete the row from PCOLL_CONTROL.
If the UPDATEDATE is less than a day old, you should not delete it.
3. If the delete succeeds, you can drop the view spillover table that was listed in the
TABNAME column.
If the delete fails with a lock conflict, that means the table is in use. You should not drop
the corresponding spillover table.
Related topics
About Managing Rows in Memory at Runtime
11-645
Exposing View Links to Entity Objects
JDeveloper makes it possible for you to use the relationships defined by view links to better
define the results obtained while traversing entity objects. JDeveloper does this by letting you
create a method inside an entity object that provides easy access to data returned by the view
link.
In this topic, an example illustrates how to expose view links to entity objects.
Assume that you want to write business logic that will delete from the database the records of
terminated employees for a given department. Assume also that your database represents
terminated employees by a negative employee number. You can create an accessor method
that will use the view link to return only those rows where the employee number is negative. To
do this, use the View Link Wizard to specify the source and destination view objects, the name
of the accessor method, the source and destination role attributes, and a SQL statement that
will return just the data you need.
After you already have a project with Dept and Emp entity objects, and DeptView and
EmpView view objects, you can perform the following steps to expose view links to entity
objects:
1. In the Navigator, right-click a business components package and choose New View Link
to open the View Link Wizard.
3. In the Name page, name the view link DeptToEmpVL. Click Next.
4. In the View Objects page, select DeptView as the source view and EmpView as the
destination view. Click Next.
5. In the Source Attributes and Destination Attributes pages, select Deptno. Click Next.
6. In the View Link SQL page, add AND Emp.Empno<0 to the Where field, so that the full
query statement reads Dept.DEPTNO = Emp.DEPTNO AND Emp.Empno<0.
7. In the View Link Properties page, select Generate Accessor In Entity Object and type
TerminatedEmps in the Accessor Name field. Click Next.
11-646
8. Click Finish to generate the view link.
JDeveloper adds code similar to the following to your DeptImpl.java file:
/**
* Uses the link DeptToEmpVL to return rows of EmpView
*/
public oracle.jbo.RowIterator getTerminatedEmps() {

return (oracle.jbo.RowIterator)getAttributeInternal(TERMINATEDEMPS);
}
To remove the records of terminated employees for a given department from the database, you
could write code like this on the Dept entity object:
public void purge() {

oracle.jbo.Row r;
oracle.jbo.RowIterator empRSI = getTerminatedEmployees();
while(empRSI.hasNext()) {
r = empRSI.next();
r.remove();
}
}
The purge() function is now an operator that is available on the Dept entity object. In this
manner, business logic and operators can be built up.
You can then use the purge() function as part of a program to remove terminated employees.
The following function, doProcess() tests whether purge()works correctly. The function
retrieves the Dept and Emp view objects, marks the first employee in the first department as
terminated, then calls purge() to remove the employee's record from the database.
public void doProcess() throws Exception {

appModule = getApplicationModule("HRappModule");
// get view usages

ViewObject deptVO = appModule.findViewObject("DeptView");
ViewObject empVO = appModule.findViewObject("EmpView");
// setup dataWriter to retrieve and output data

openWriter();
11-647
deptVO.setRangeSize(-1);
empVO.setRangeSize(-1);
deptVO.reset();
Row deptRow;
Row empRow;
// get the first emp row in the first department, mark the emp
// for termination by setting by setting empno = -1
deptVO.first();
empRow = empVO.first();
dataWriter.writeln("Employee to be terminated: "+

empRow.getAttribute("EmpName").toString());
empRow.setAttribute("EmpNum",new Integer(-1));
appModule.getTransaction().commit();
// Now purge all the Terminated emps
DeptVORowImpl dRow = (DeptVORowImpl)deptVO.first();

DeptImpl deptEO = dRow.getDeptUsage();
deptEO.purge();
appModule.getTransaction().commit();
closeWriter();
}
Related Topics
About Exposing View Links to Entity Objects
11-648
To access business logic in the business logic tier, follow these general steps:
1. Create the needed methods in the .java files for the business components you want
the client to work with. Then, use JDeveloper to mark the methods as available for
export.
2. Create a remotable application module to contain the methods you want to export.
Related topics
About Creating Methods for Clients to Use
11-649
Ways to Create and Export Business Logic Tier
Methods to Clients
This topic describes how to use the Business Components for Java framework to create the
methods you want to make available to clients. You can create exportable methods on:
● view objects
● view rows
In each of these cases, after you create the exportable methods, you must create a remotable
application module to contain them. Then, you must deploy the application module to the
platform of your choice. For information on how to create a remotable application module, see
Creating A Remotable Application Module. For information on how to deploy an application
module, see Deploying Business Components.
Methods Must Implement Serializable
When you write your methods, keep in mind that JDeveloper can accept any datatype that
implements the java.lang.Serializable interface. In a multi-tier environment, objects are
passed by value. Only objects that implement Serializable can be passed as arguments
and act as return values.
If a method returns (or takes arguments of) a datatype that does not implement
Serializable, then the method will not be able to pass values between the client and
business logic tier. The method will not appear in the list of available methods in the Client
Methods page of the Application Module or View Object Wizard when you create your
remotable application module.
11-650
Creating Exportable Application Module Methods
You create the application module methods that you want to export in the module's .java file.
Follow these general steps:
1. In the Java file that implements your application module, write methods that you want to
expose to the client tier.
2. Include the methods in a remotable application module.
3. Once you have the remotable application module, deploy it to the application tier.
11-651
Creating Exportable View Object Methods
You create the view object methods that you want to export in the object's .java file. Follow
these general steps:
1. In the Java file that implements your view object, write the methods you want to expose
to the client.
2. In the Navigation pane, right-click the View Object name, and select Edit. In the Client
Methods tab, select the methods you want to expose. Only exportable methods are
displayed in the methods list.
3. Click Apply, then Finish. JDeveloper creates a remote interface, named for the view
object, that contains the signatures of the exported methods.
11-652
Creating Exportable View Row Methods
You create the view row methods that you want to export in its containing view object's .java
file. Follow these general steps:
1. In the Navigation pane, right-click the View Object name, and select Edit. In the Java
tab, select Generate Java file and Generate accessors for the view row class. Click
Apply.
2. In the Client Row Methods tab, select the accessor methods you want to expose. Click
Finish. JDeveloper creates a remote interface, named for the view row, that contains the
signatures of the exported methods.
3. (Optional) In the generated Java file that implements your view row, you can add
business logic to the row accessor methods you will expose to the client.
11-653
Creating Delegators for Entity Object Methods
Your clients cannot directly access entity objects. If you want to expose entity object methods
to clients, you should create a delegator method on a view row class.
To create a delegator method:
1. Create an exportable view row method of the same name as the entity method you want
to call.
2. In the body of the view row method, find the relevant entity object using the
get<Entity>() accessor and call its method, for example:
public void grantRaise(int percent) {

getEmployees().grantRaise(percent);
}
11-654
Ways to Call Exported Methods on Clients
This topic describes how to invoke exported methods in client programs and contains these
sections:
● Invoking Exported Application Module Methods
● Invoking Exported View Object Methods
● Invoking Exported View Row Methods
The client program follows the coding pattern for EJBs. To use the exported methods, the
program must import the package or packages that contain the Java interfaces for the
application module and any view objects or view rows that have exported methods. These are
typically found in the common package. The common package contains the generated interfaces
and classes which are common to the remote client and the server tier. The program also
typically imports the oracle.jbo.* package.
To access an exported application module method, first get an instance of the application
module and cast it to the interface of the exported application module. This interface represents
a proxy for the application module—the actual objects and their methods reside on the
application tier. How you manipulate the proxy in the client tier will be replicated on the actual
objects in the application tier. Note that if your client program does not work with exported
application module methods, you do not have to perform the cast.
Similarly, when you work with exported methods for a view object or view row, first get an
instance of the application module that contains the objects. If the application module does not
export any methods or if the client program does not work with exported application module
methods, you do not have to perform the cast. Next, get a reference to the view object or Row
and cast its handle to the proxy interface for the object. How you manipulate the proxy in the
client tier will be replicated on the actual objects in the application tier.
11-655
Calling Exported Application Module Methods
The client program must import the package containing the Java interfaces for the application
module. It will also typically import the oracle.jbo.* package. For example:
import package4.common.*
// includes package4.common.HrAppmodule
import oracle.jbo.*
// includes generic application module oracle.jbo.ApplicationModule
To use the exported method:
1. Get an instance of the application module and cast it to the exported application module.
2. Work with the exported method.
For example:
// look up factory for the custom application module

ApplicationModuleHome home = (ApplicationModuleHome)
ic.lookup("package4.HrAppmodule");
// Call create() to get the application module instance;

// cast it to the custom application module
HrAppmodule hrAm = (HrAppmodule) home.create();
//
// Create the transaction code here.
//
// Call the application module exported method

hrAm.promoteAllEmps();
11-656
Calling Exported View Object Methods
The client program must import the package containing the Java interface for the view object
and the generic application module. For example:
// includes package4.common.EmpView
import oracle.jbo.*
To use the exported method:
1. Get an instance of the generic application module.
2. Get a reference to the view object and cast it to the custom proxy view object containing
the exported method.
For example:

ApplicationModule am = home.create();
// Get a handle to the view object - Cast it to the custom

// view object interface containing the exported method
EmpView empView = (EmpView) am.findViewObject("EmpView");
// Call the exported method

empView.promote();
Notice that if you are working with only the exported view object method, you do not have to
cast the application module to its exported interface.
11-657
Calling Exported View Row Methods
The client program must import the package containing the Java interface for the view row
object, the view object row-proxy, and the generic application module. For example:
// includes package4.common.DeptView
// includes package4.common.DeptViewImpl
import oracle.jbo.*
To use the exported view row accessor methods:
1. Get an instance of the generic application module.
2. Get a reference to the view row object and cast it to the view object row-proxy containing
the exported accessor method.
For example:

ApplicationModule am = session.createApplicationModule();
// Get a reference to the view object - Cast it to the custom

// view object interface containing the exported method
ViewObject deptView = am.findViewObject("DeptView");
// Call one of the view object methods that return a row

while ((row = deptView.next()) != null)
// Cast the row to the view row interface containing the

// exported accessor method
DeptViewRow deptRow = (DeptViewRow) row
// Call the accessor method on the row

System.out.println("DEPTNO :"+deptRow.getDeptNo());
11-658
Notice that if you are working with only the exported view row method, you do not have to cast
the application module to its exported interface.
11-659
Using the API to Customize and Use View Objects,
View Links, and Application Modules
The following topics describe some ways to use the API. See the Javadoc and the tutorials for
more information.
● Finding an Application Module Instance in Code
● Ways to Work with Transactions
● Implementing Pooling in Application Module Code
● Implementing a Custom Application Module Pool
● Creating and Finding a View Object Instance in Code
● Executing a View Object Query in Code
● Setting View Attribute Values in Code
● Using a View Object to Insert and Delete Rows in Code
● Creating and Changing View Object Queries in Code
● Using a Range of View Object Rows in Code
● Using Multiple View Object Row Iterators in Code
● Ways to Create View Link Instances in Code
● Using Transaction Utility Methods for Testing and Debugging
11-660
Ways to Work With Transactions
Once you have instantiated an application module, you can use the getTransaction()
method to obtain a Transaction object. This allows you to perform the following tasks.
Note: If you're using container-managed transactions in an application module called directly from a
client, you must use a client-demarcated transaction.

ApplicationModule.getTransaction()
Opening a Open a JDBC connection and begin a Transaction.connect()

JDBC database transaction. This is done
Connection automatically for you if you use
Transaction.reconnect()
for a createRootApplicationModule()
Transaction to instantiate the application module.
Transaction.isConnected()
Closing a ApplicationModule.getTransaction()
JDBC Create an instance of a view object
that was created at design time but not
Connection
added to the application module's data Transaction.disconnect()
from a
model, and add it to the data model.
Transaction
Manually Synchronize the application module ApplicationModule.getTransaction()

with the database. This is done
Posting
automatically for you when you commit
Changes in a Transaction.postChanges()
the transaction, but you can do it early
Transaction
by completing this task.
Committing a Commit a transaction and begin a new
Transaction one. Transaction.commit()
Rolling Back
Roll back a transaction and begin a
a
new one. Transaction.rollback()
Transaction
Implementing ApplicationModule.getTransaction()
Transaction Change row locking to optimistic or
Locking in pessimistic mode. Transaction.setLockingMode()
Code
11-661
Opening a JDBC Connection For a Transaction
When you first instantiate an application module, the business components framework
automatically connects to the JDBC connection specified in the configuration used. However, if
you later disconnect from the connection, you may want to reconnect to the same connection
on connect to a different one.
To open a JDBC connection:
1. Obtain the application module's Transaction object. For example, if your application
module instance is called myAM, you could use the following code to obtain the
Transaction:
import oracle.jbo;
Transaction myTrans=myAM.getTransaction();
2. If you want to connect to the same host and with the same credentials as the previous
transaction, call Tansaction.reconnect(). For example, with Transaction myTrans,
use the code:
myTrans.reconnect();
Note: In general, calling reconnect() will start a new database transaction. However,
if disconnect() was previously called with an argument of true, the old transaction
will be resumed.
3. If you want to connect to a different host or to connect as a different user, call
Transaction.connect(). This method has three possible signatures:
❍ Call Transaction.connect() with a single String argument to connect using
a JDBC URL that includes a username and password. For example:
String fullURL="jdbc:oracle:thin:hr/hr@localhost";
myTrans.connect(fullURL);
❍ Call Transaction.connect() with three String arguments to specify

username and password separately. For example:
String URL="jdbc:oracle:thin@localhost";
String user="hr";
11-662
String password="hr";
myTrans.connect(URL, user, password);
❍ Call Transaction.connect() with a String argument and a java.util.Properties object

to specify username, password, and (optionally) other properties as name-value
pairs. For example:
import java.lang.util;
String URL="jdbc:oracle:thin@localhost";
Properties info=new Properties();
info.put("user", "hr");
info.put("password", "hr");
info.put("defaultRowPrefetch","15");
myTrans.connect(URL, info);
4. Call Transaction.isConnected() to make sure the connection was successful. For

example:
if (!(myTrans.isConnected)) throw new Exception();
Related topics

Closing a JDBC Connection from a Transaction
Manually Posting Changes in a Transaction
Committing a Transaction
Rolling Back a Transaction
11-663
When you first instantiate an application module, the business components framework
automatically connects to the JDBC connection specified in the configuration used. You can
disconnect from this connection at any time using the Transaction.disconnect() method.
To close a JDBC connection:
Transaction:
import oracle.jbo;
2. If you want to disconnect and terminate your current database transaction (the server will
roll the transaction back), call Transaction.disconnect() with no arguments or with
an argument of true:
myTrans.disconnect();
3. If you want to disconnect and preserve the transaction state (the transaction will be
resumed when you call Transaction.reconnect()), call
Transaction.disconnect() with an argument of false:
myTrans.disconnect(false);
Related topics

Opening a JDBC Connection for a Transaction
11-664
11-665
When you commit a transaction, the business components framework will automatically
perform transaction-wide validation and post any changes in the cache to the database.
However, you may wish to post changes before you commit (for example, to activate database
triggers) or before you validate (for example, if your validation requires a new SQL statement to
be executed against the changed data). You can post changes at any time by calling the
Transaction.postChanges() method.
To manually post changes to the database:
Transaction:
import oracle.jbo;
2. Call Transaction.postChanges:
myTrans.postChanges();
Related topics

11-666
Use the Transaction.commit() method to validate all data, post changes to the database,
and commit.
To commit a database transaction:
Transaction:
import oracle.jbo;
2. Call Transaction.commit():
myTrans.commit();
Related topics

11-667
Use the Transaction.rollback()method to roll back a database transaction and discard
all changes in the cache.
To roll back a database transaction:
Transaction:
import oracle.jbo;
2. Call Transaction.rollback():
myTrans.rollback();
Related topics

11-668
Ways to Find Nested Application Module Instances
in Code
After you have instantiated an application module, you can complete the following tasks to find
or create nested application modules.

Finding a
Nested Find an instance of a nested
Application application module that was
added to a containing ApplicationModule.findApplicationModule()
Module in
application module's data
the Data model at design time.
Model
Finding a Create an instance of an
Nested application module that was
Application created at design time but not
nested in the containing ApplicationModule.createApplicationModule()
Module not
application modulel, and nest it
in the Data in the containing application
Model module.
11-669
Finding a Nested Application Module in the Data
Model
If you added a nested application module to the data model either previously in code or in
design time (using the Application Modules page of the Application Module Wizard), you can
retrieve it in either the business tier or the client by calling findApplicationModule() on
the application module. Pass the name of the application module usage (in the data model) to
this method.
ApplicationModule nestedAm =
rootAM.findApplicationModule("MyNestedAM");
Related Topics
Ways to Find Nested Application Module Instances in Code

Finding a Nested Application Module not in the Data Model
11-670
Finding a Nested Application Module not in the Data
Model
If you want to use an application module as a nested application module but did not designate it as
nested at design time, you can still access it at runtime by calling createApplicationModule()
on the containing application module. The application module to be nested will be added dynamically
to the containing application module's data model. createApplicationModule() takes two
String arguments. The first becomes the name of the nested application model usage in the data
model. The second is the possibly package-qualified name of the application module to be nested (the
name that you specified in the Application Module Wizard). You can call this method from the client or
the business logic tier.
String nestedAmUsageName="subAppMod";
String nestedAmName="demo.smallModule";
ApplicationModule nestedAm=containingAm.createApplicationModule(nestedAmUsageName,
nestedAmName);
Related Topics

Finding a Nested Application Module in the Data Model
11-671
Removing a View Object or Nested Application
Module from an Application Module in Code
If an view object instance is in the data model of an application module, you can remove it and
clean up its resources by calling ComponentObject.remove(). Both ViewObject and
ApplicationModule inherit from ComponentObject.
ViewObject mgrVO = am.findViewObject("Managers");

ApplicationModule nestedAm = am.findApplicationModule("smallAM");
mgrVO.remove();
nestedAM.remove();
Related topics

11-672
Traversing View Links in Code
If two view object instances stand in a master-detail relationship in your data model, the
business components framework will keep them synchronized--the current row in the master
will automatically determine what rows are loaded into the detail.
However, you may have a view link between two view objects that do not atand in a master-
detail relationship in the data model--the instances of both view objects might be independent,
or the destination view object might not be in the data model at all.
You can still get a RowSet for the destination object, automatically synchronized with a
particular source row, by calling the view link accessor on that row. If you have a bidirectional
view link, you can also get the RowSet for a source object by calling the view link accessor on
a destination row.
To call a view link accessor on a view row:
1. Make sure you have generated accessors for your view link.
2. Use the following code (in either the business logic tier or the client), where
<AccessorName> is the name of your view link accessor and <myRow> is the name of
your row:
RowSet destRows = (RowSet) myrow.getAttribute("AccessorName");
11-673
Executing a View Object Query in Code
This topic describes the key view object methods for executing a query:
● executeQuery
● hasNext
It also presents some view object query examples.
About executeQuery
A statement like the following executes the view object's current query statement and refreshes the collection of
results (with on-demand fetching, as is the norm).
myVO.executeQuery();
If the existing state of the view object includes pending changes (inserts, updates, deletes), they are cached in
the underlying entity cache
s and are not affected by refreshing the query. The changes are still pending and the inserted and updated rows
will appear in their current pending state in the view object.
The executeQuery method does not post, commit, or validate changes. Instead, call postChanges and
validate explicitly, as needed. For example:
// Pre-validate all changes in this view object

myVO.validate();
// or you can pre-validate all changes in the application module.

myVO.getApplicationModule().validate();
// Now post all changes

myVO.getApplicationModule().getTransaction().postChanges();
// Then re-execute the query

myVO.executeQuery();
If other database users add new rows to the database in the meantime, and they meet the WHERE criteria of
your view object, they will appear in the view object after calling executeQuery.
Methods such as setWhereClause that change the query clauses do not execute the query. You can change
the query clauses as many times as you want. However, the new query does not take affect until you call
executeQuery.
11-674
Data retrieved from the RowSet may not match the query clauses in the following scenario:
setWhereClause("a = 10") /* line 1 */

executeQuery()
fetch data /* line 3 */
setWhereClause("a != 10")
fetch more data /* line 5 */
Rows returned from line 5 will still have a = 10. Call executeQuery after line 4 to get rows with a != 10.
If you do the following, line 6 will show b = 11 (the pending, changed value set in line 4).

executeQuery()
retrieve a row /* line 3 */
row.setAttribute("b", 11) /* Say b was equal to 15 in the DB */
executeQuery() /* line 5 */
fetch rows /* line 6 */
In contrast, consider the following scenario, which changes an attribute in the WHERE clause:

executeQuery()
retrieve a row /* line 3 */
row.setAttribute("a", 11) /* NOTE we're setting "a" this time! */
executeQuery() /* line 5 */
fetch rows /* line 6 */
When you call executeQuery in line 5, changes to the row in line 4 have not been posted to the database. In
the database, this row still has a = 10. So, when you fetch rows in line 6, the row in line 3 is retrieved because
the database session still sees "a = 10" in the database. However, on the client, or internally in response to
row.getAttribute("a"), it will return 11, because the pending change (a=11) is still in the entity cache.
About hasNext
The hasNext method executes a view object's query if it has not already been executed. It is useful for looping
through a result set, as shown in the following code snippet.
vo.executeQuery();
Row row = vo.next(); // Get the next row in the result set.
System.out.println(row.getAttribute(1)); // Do something with the row.
View Object Query Examples
11-675
The following code example executes a query defined in a view object created using wizards at design time,
then scrolls through the result set. The scrolling of the result set happens in the printViewObject() method.
The example uses the generic application module and calls Row.getAttribute to access attributes.
package d2e;
import javax.naming.Context;
import javax.naming.InitialContext;
public class QueryDemo

{
public static void main(String[] args)
{
getGenericAppMod(JboContext.PLATFORM_LOCAL);
// Specify the XML file that defines the view object.

// Format: <package>.<filename>
String voDefFile = "d2e.EmpView";
// Identify the view object. Must be a valid Java identifier.

String voName = "demoVO";
// Create the view object within the context defined

// by the application module.
ViewObject vo = appMod.createViewObjectF(voName, voDefFile);
printViewObject(vo);
vo.remove();
}
public static ApplicationModule getGenericAppMod(String platform)

{
Hashtable env = new Hashtable(2);
env.put(Context.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
env.put(JboContext.DEPLOY_PLATFORM, platform);
try
{
Context ic = new InitialContext(env);
String theAMDefName = "d2e.D2eModule";
ApplicationModuleHome home = (ApplicationModuleHome)ic.lookup(theAMDefName);
ApplicationModule appMod = home.create();
appMod.getTransaction().connect("jdbc:oracle:thin:scott/tiger@pc3:1521:ORCL");
return appMod;
}
catch(Exception e)
{
}
return null;
11-676
}
public static void printViewObject(ViewObject vo)

{
// Execute the query, print results to the screen.
vo.executeQuery();
Row row = vo.next();
String rowDataStr = "";
// How many attributes (columns) is the view object using?

int numAttrs = vo.getAttributeCount();
// Column numbers start with 0, not 1.

for (int columnNo = 0; columnNo < numAttrs; columnNo++) {
// See also Row.getAttribute(String name).

Object attrData = row.getAttribute(columnNo);
rowDataStr += (attrData + "\t");
}
System.out.println(rowDataStr);
}
}
}
11-677
Ways to Navigate Rows in Queries
After a view object executes its query, you need to be able to find particular rows within the
query. The following topics describe how to navigate through queries to return particular rows.
● Finding the First Row in a Query

● Finding the Last Row in a Query
● Stepping Through a Query
● Stepping Backwards Through a Query
● Finding a Row in a Query by Primary Key
11-678
Finding the First Row in a Query
Find the first row in a view object's query by calling the view object's first() method. This
method both returns the first row in the query and sets the view object's current row to that row.
The following example uses first() to return the first row of the view object mgrVO.
"frags/first.frag"><first.frag>
Related topics

Finding the Last Row in a Query
Stepping Through a Query
Stepping Backwards Through a Query
Finding a Row in a Query by Primary Key
11-679
Find the last row in a view object's query by calling the view object's last() method. This
method both returns the last row in the query and sets the view object's current row to that row.
The following example uses last() to return the first row of the view object mgrVO.
"frags/last.frag"><last.frag>
Related topics

11-680
Step through a view object's query by calling the view object's next() method. This method
increments the view objects current row and then returns the new current row.
Before calling next(), you should call hasNext() to make sure the view object is not on its
last row.
The following example uses next() to step through the view object mgrVO and sum the
salaries of all of the managers.
"frags/next.frag"><next.frag>
Related topics

11-681
Step backwards through a view object's query by calling the view object's previous()
method. This method decrements the view objects current row and then returns the new
current row.
Before calling previous(), you should call hasPrevious() to make sure the view object is
not on its last row.
The following example uses previous() to step backwards through the view object mgrVO.
"frags/previous.frag"><previous.frag>
Related topics

11-682
1. Create an array of Objects corresponding to the parts of your primary key.
For example, if your primary key consists of a single attribute of type Number, create an
object array of length 1:
"frags/findByKey1.frag"<findByKey1.frag>
2. Create a Key using this array:
3. Call the view object's findByKey(key, length) method.
This method returns an array containing the first length view rows that correspond to
key:
4. Extract the desired row from the array:
Related topics

11-683
Setting View Attribute Values in Code
The following code example updates values in a database table by setting attributes of a
business component. The example uses the generic application module and calls
Row.setAttribute to set attributes.
In the code, take notice of the following:
● The salary is set in the updateAttr() method, by calling

row.setAttribute("Sal", newVal);
● The salary of the employee whose EMPNO is 7369 is changed to 6543.
● The new salary value is passed into updateAttr() from main().
package d2e;
import oracle.jbo.server.*;
public class SetAttrDemo {


// Specify the XML file that defines the view object.

// Format: <package>

String voName = "demoEmpVO";

ViewObject vo = appMod.createViewObject(voName, voDefFile);
Number newVal = new Number(6543);
if (updateAttr(vo, newVal)) {
try {
11-684
// Commit changes to the database, making
// updated data available to other application modules.
System.out.println("\n Transaction committed. \n");
}
catch (JboException ave) {
// Handle Entity-level validation exceptions here.

System.out.println("\n (Entity) Invalid value: " + newVal);
throw ave;
}
}
}
public static boolean updateAttr(ViewObject vo, Object newVal) {

boolean res = false;
// Optional: specify a WHERE clause to narrow the query.

vo.setWhereClause("EMPNO = 7369");
// Execute the query, set new attribute value. Only one row
// should be returned, so use vo.first().
vo.executeQuery();
Row row = vo.first();
try {
row.setAttribute("Sal", newVal);
}
catch (JboException ave) {
// Handle Attribute-level validation exceptions here.

System.out.println("\n (Attribute) Invalid value: " + newVal);
throw ave;
}
res = true;
}
return res;
}
}
11-685
Using a View Object to Insert and Delete Rows in Code
The following code example contains three methods in addition to main:
● addRow creates a row, fills in the columns, then adds it to the DEPT table.
Key methods: ViewObject.createRow and Row.setAttribute.
● deleteRow appends a WHERE clause to the default view of the DEPT table, executes the query,
then deletes each row in the result set.
Key method: ViewObject.removeCurrentRow
● commitAndShowChanges is a helper method that prints the updated table to the screen.
package d2e;
public class RowsDemo {

// Specify the Java file that defines the VO.

// Format: <package>
String voDefFile = "d2e.DeptView";

String voName = "demoDeptVO";

addRow(appMod, vo);
deleteRow(appMod, vo);
}
public static void addRow(ApplicationModule appMod, ViewObject vo) {
// Create a row and fill in the columns.

Row newRow = vo.createRow();
11-686
newRow.setAttribute("Deptno", new Number(14));
newRow.setAttribute("Dname", "Pubs");
newRow.setAttribute("Loc", "Honolulu");
vo.insertRow(newRow);
// Call a helper method.

commitAndShowChanges(appMod);
}
public static void deleteRow(ApplicationModule appMod, ViewObject vo) {
// Get row(s) to delete.

vo.setWhereClause(" deptno > 10 and deptno < 20 ");
// Delete row(s).
vo.executeQuery();
vo.next();
vo.removeCurrentRow();
}
// Call a helper method.
commitAndShowChanges(appMod);
}
public static void commitAndShowChanges(ApplicationModule appMod) {
// Helper method to print updated table.
try {
}
System.out.println("\n Could not commit changes.");
System.exit(0);
}
// Define and execute a simple SQL statement.
String sqlStr = "select * from dept ";
String dumpClass = "oracle.jbo.server.QueryDumpTab";
String result = appMod.getTransaction().dumpQueryResult(sqlStr, dumpClass, null);
// Print updated table.

System.out.println(result);
}
}
For more information on the dumpQueryResult() method, see Using Transaction Utility Methods.
11-687
11-688
Creating and Changing View Object Queries in Code
The examples in this topic show techniques for using SQL to define and modify query statements used by view
objects. The following table describes the example methods and lists the key Business Components for Java
framework methods each one uses.
Example Description Key framework methods

demoSimpleFetch A static SQL statement with all ApplicationModule.createViewObjectFromQueryStmt
information hard-coded.
Note: View objects created using
createViewObjectFromQueryStmt are
read-only because there are no underlying entity objects.
demoWhereClause A static SQL statement with a ViewObject.setWhereClause
WHERE clause added at run time.
demoParamFetch A query that takes one or more ViewObject.setWhereClauseParam,
parameters. ViewObject.setWhereClauseParams
ClausesDemo A class that shows how to use ViewObject.setWhereClause,
methods for working with query ViewObject.setOrderByClause,
clauses and query-by-example. ApplicationModule.createViewObjectFromQueryClauses,
ViewObject.createViewCriteria,
ViewCriteria.createViewCriteriaRow,
ViewCriteriaRow.setAttribute,
ViewCriteria.addElement,
ViewObject.applyViewCriteria
Simple Fetch Example
A static SQL statement with all information hard-coded.
public static void demoSimpleFetch(ApplicationModule appMod) {

// Define basic query string.
String sqlStr = "SELECT Emp.ename, Emp.mgr FROM EMP Emp ";
ViewObject vo = appMod.createViewObjectFromQueryStmt("QueryDemo", sqlStr);
vo.remove();
}
Where Clause Example
public static void demoWhereClause(ApplicationModule appMod) {

ViewObject vo = appMod.createViewObjectFromQueryStmt("whereDemo", sqlStr);
// Define and set WHERE clause. (See also ViewObject.setOrderByClause)
vo.setWhereClause(" Emp.mgr > 7700 ");
}
Parameter Fetching Example
The following examples uses the question mark (?) parameter style instead of the colon (:) style. The View Object
11-689
Wizard requires that you choose one style for use by your query. Be sure to set the Use ? style parameter field in
the View Object Wizard as appropriate for your dynamic query.
public static void demoParamFetch(ApplicationModule appMod, Object inParam) {
// Query takes one parameter: Emp.mgr.

ViewObject vo = appMod.createViewObjectFromQueryStmt("oneParam",
sqlStr);
vo.setWhereClause(" Emp.mgr > ? ");
// Set one parameter value. 0 specifies the first parameter.

vo.setWhereClauseParam(0, inParam);
// To remove or reset parameters, call vo.setWhereClauseParams(null).

// Query takes two parameters: Emp.mgr and Emp.sal.

sqlStr = "SELECT Emp.ename, Emp.mgr, Emp.sal FROM EMP Emp " +
"WHERE Emp.mgr = ? " +
"AND Emp.sal <= ? ";
vo = appMod.createViewObjectFromQueryStmt("multiParams", sqlStr);
// Use an array to set several parameters with one method call.

Object[] params = new Object[2];
params[0] = inParam;
params[1] = new Integer(3000);
vo.setWhereClauseParams(params);
// To remove or reset parameters, call vo.setWhereClauseParams(null).

}
Examples of Working with View Objects, SQL, and Query Clauses
The following example class shows how to use methods for working with view objects, SQL, and query clauses. It
also shows how to define criteria to support query-by-example.
package d2e;
public class ClausesDemo

{
11-690

String sqlStr = "SELECT empno, ename, job, mgr FROM EMP ";
// View object based on Query clauses.

ViewObject vo = appMod.createViewObjectFromQueryClauses("clausesVO",
"d2e.Emp",
"empno, ename, job, mgr",
"Emp",
null,
null);
demoWhereClause(vo);
demoOrderByClause(vo);
demoCriteria(appMod);
demoCreateFromClauses(appMod);
}
public static void demoWhereClause(ViewObject vo) {
// Define and set WHERE clause.

String whereStr = " Emp.empno = 7839 ";
vo.setWhereClause(whereStr);
System.out.println("Demo Where Emp.empno = 7839");
//Should print only one employee with empno = 7839

QueryDemo.printViewObject(vo);
// Replace the previous WHERE clause with the following.

System.out.println("Demo Where Emp.empno = 7566");
whereStr = " Emp.empno = 7566 ";
vo.setWhereClause(whereStr);
//Should print only one employee with empno = 7566

}
public static void demoOrderByClause(ViewObject vo) {
// Define and set ORDER BY clause.

String orderStr = " Emp.job ";
vo.setWhereClause("");
vo.setOrderByClause(orderStr);
System.out.println("Demo Order By Emp.job");
//Should print all employees ordered by Job column

11-691
// Replace the previous ORDER BY clause with the following.
orderStr = " Emp.mgr ";
vo.setOrderByClause(orderStr);
System.out.println("Demo Order By Emp.mgr");
//Should print all employees ordered by Mgr column

}
public static void demoCriteria(ApplicationModule appMod) {
// Create and populate criteria rows to support query-by-example.

ViewObject empView = appMod.createViewObject("emp",
"d2e.EmpView");
ViewCriteria vc = empView.createViewCriteria();
ViewCriteriaRow vcRow = vc.createViewCriteriaRow();
// ViewCriteriaRow attribute name is case-sensitive.

// ViewCriteriaRow attribute value requires operator and value.
// Note also single-quotes around string value.
vcRow.setAttribute("Job", "= 'MANAGER'");
vc.addElement(vcRow);
vcRow = vc.createViewCriteriaRow();
vcRow.setAttribute("Sal", "> 2500");
vc.addElement(vcRow);
empView.applyViewCriteria(vc);
// Multiple rows are OR-ed in WHERE clause.

System.out.println("Demo View Criteria");
//Should print employees that are MANAGER or have Sal > 2500
QueryDemo.printViewObject(empView);
}
public static void demoCreateFromClauses(ApplicationModule appMod)

{
String voName = "demoClauses";
String eoDefName = "d2e.Emp";
String selectClause = "E.EMPNO, E.ENAME, E.JOB, E.DEPTNO";
String fromClause = "EMP E";
String whereClause = "E.DEPTNO = 10 ";
String orderByClause = null;
ViewObject vo = appMod.createViewObjectFromQueryClauses(
voName,
eoDefName,
selectClause,
fromClause,
whereClause,
11-692
orderByClause);
System.out.println("Demo ViewObject created from clauses");
//Should print all employees for Dept = 10

// WHERE clauses are AND-ed together.

vo.setWhereClause("job = 'MANAGER' ");
System.out.println("Demo where clauses AND-ed together");
//Should print all employees for Dept = 10 and Job = 'MANAGER'

}
}
11-693
Using a Range of View Object Rows in Code
When you do not want to work with an entire result set, you can use a range to specify how many
rows to work with at a time (fetch). A range effectively defines a window you can use to access a
subset of the rows in a result set. Ranges are useful when the result set is large and you do not
want to bring all of the rows to the client, or when you want to display a certain number of rows in
a UI control. To define a range, specify a range size (number of rows) and the index of the first
row in the range. By default, the range size is set to 1 (note: a range size of -1 fetches all rows).
To work with a range, use a view object to call the methods below (range functionality is defined
in the oracle.jbo.RowIterator interface).
enumerateRowsInRange
getAllRowsInRange
getRangeIndexOf
getRangeSize
getRangeStart
getRowCountInRange
insertRowAtRangeIndex
scrollRange
scrollRangeTo
setCurrentRowAtRangeIndex
setRangeSize
setRangeStart
The following figure shows the effects of some of these methods. In the view at left, the range
size is set to 5 (setRangeSize(5)), so the range contains the first 5 rows of the result set.
Next, in the middle view, the start of the range is at row 4 (range start is 0-based, thus
setRangeStart(3)) of the result set and the range size is set to 3, so the range contains rows
4 through 6 of the result set. Finally, in the view at right, the range window is scrolled forward 4
rows. The range size does not change, so the range contains rows 8 through 10 of the result set.
11-694
The following code example shows how to use some of these methods to work with ranges. The
example assumes that a helper routine to initialize an application module has been implemented
elsewhere.
package d2e;
public class RangeDemo {


// Specify the Java file that defines the view object.


11-695
// Specify how many rows to fetch, then fetch them.

vo.setRangeSize(5); // vo.setRangeSize(-1) fetches all rows.
printRows(vo.getAllRowsInRange(), vo.getRangeStart()); // Gets rows 0 - 4.
// Range window starts at row 5. Row numbers start with 0.

vo.setRangeStart(4);
vo.setRangeSize(3); // Change range size.
// Range window scrolls 2 rows. Range size stays the same.

vo.scrollRange(-2); // Positive scrolls forward, negative scrolls back.
}

public static void printRows(Row[] rows, int rnum) {
for (int r = 0; r < rows.length; r++) {
for (int i = 0; i < rows[r].getAttributeCount(); i++) {
rowAttrs += (rows[r].getAttribute(i) + "\t");
}
System.out.println(rnum + "\t" + rowAttrs);

rnum += 1;
}
System.out.println("----");
}
}
11-696
Using Multiple View Object Row Iterators in Code
The business components run-time framework creates a default iterator for each view object.
You can also create iterators to use in addition to, or instead of the default iterator. The
interface oracle.jbo.RowIterator provides support for scrolling, row positioning, and
related functions. For scrolling through the result set, setRangeSize and scrollRange, play
an important role.
For example, suppose you want to give clients the option of scrolling through sets of rows
(perhaps simulating a Page-Down key) or one row at a time, as shown in the following figure.
The following code example creates one view object, uses the default iterator to display one
row at a time, and creates a second iterator to display a range of five rows. The examples
assume that a helper routine to initialize an application module has been implemented
elsewhere. For an example, see Finding an Application Module Instance in Code.
In the code below, setCurrentRowAtRangeIndex() moves the row index to the row specified. An
index of zero (o) will set it at the beginning of the range. Any other number specified moves the
index to that row in the specified range.
public static void pageDown() {

11-697



// The view object provides a default iterator.
// Create another iterator.

RowSetIterator secondIter = vo.createRowSetIterator("Two");
secondIter.setRangeSize(5);
// Array simulates user keystrokes/commands.

int[] keys = {1, 1, 5, 5, 1};
try {
vo.executeQuery();
for (int i = 0; i < keys.length; i++) {
switch (keys[i]) {
// Use the default iterator to print one row.

case 1 :
if (vo.hasNext()) {
Row[] rows = new Row[1];
rows[0] = vo.next();
printRows(rows);
}
break;
case 5 :
// Use the second iterator to print a range of rows.
secondIter.scrollRange(secondIter.getRangeSize());
printRows(secondIter.getAllRowsInRange());
break;
default :
11-698
System.exit(0);
break;
}
}
}
}
}

public static void printRows(Row[] rows) {
for (int r = 0; r < rows.length; r++) {
for (int a = 0; a < rows[r].getAttributeCount(); a++) {
rowAttrs += (rows[r].getAttribute(a) + "\t");
}
System.out.println(rowAttrs);
}
System.out.println("-------------");
}
The following code example uses two iterators to navigate through a table. The first (default)
iterator moves through the even-numbered rows while the second iterator moves through the
odd-numbered rows.
public static void oddEven() {

//amdemo.AppModDemo.getGenericAppMod(platform, -1);

String voDefFile = "d2e.DeptView";

String voName = "demoDeptVO";

// The view object provides a default iterator.
11-699
vo.setRangeSize(-1); // -1 = all rows
// Create another iterator.

RowSetIterator secondIter = vo.createRowSetIterator("Two");
secondIter.setRangeSize(-1); // -1 = all rows.
if (!vo.hasNext()) return; // Execute the query.

vo.executeQuery();
// Default iterator gets even-numbered rows.

// Second iterator gets odd-numbered rows.
long nRows = vo.getRowCount();
String msg = "";
for (int i = 0; i < nRows; i +=2) {
// Get and set row index values relative to a range.

// Index of first row = 0.
vo.setCurrentRowAtRangeIndex(i);
Row currRow = vo.getCurrentRow();
msg = " Default iterator (even): " + vo.getRangeIndexOf(currRow);
printRow(currRow, msg);
secondIter.setCurrentRowAtRangeIndex(i + 1);
currRow = secondIter.getCurrentRow();
msg = " Second iterator (odd): " + vo.getRangeIndexOf(currRow);
printRow(secondIter.getCurrentRow(), msg);
}
}

public static void printRow(Row row, String msg) {
for (int i = 0; i < row.getAttributeCount(); i++) {
rowAttrs += (row.getAttribute(i) + "\t");
}
System.out.println(msg + "\t" + rowAttrs);
}
11-700
Ways to Create View Link Instances in Code
At design time, you can invoke the View Link Wizard from the Package node to define a view
link definition. At runtime, you can use this design time information to instantiate a view link.
You can use a given view link definition more than once within an application module; the
business component framework uses view link instance names to distinguish between them.
The view link methods described in this section are also available from the DBTransaction
interface to create view links on the database transaction. These view links are anonymous in
that they do not have a name (that is, there is no viewLinkName parameter in their signature)
and do not require an application module. Business Components for Java assigns a system-
generated name to an anonymous view link.

Creating a
View Link
Instantiate a view link
from a ApplicationModule.createViewLink()
created at design time.
View Link
Definition
Creating a
View Link Create a view link based
ApplicationModule.createViewLinkFromEntityAssocName()
from an upon an association.
Association
Creating A
View Link Create a view link
by between two view ApplicationModule.createViewLinkBetweenViewObjects()
Associating objects in the data
View model.
Attributes
11-701
Creating a View Link from a View Link Definition
Use createViewLink() to instantiate a view link created at design time.
For example, assume that during design time, you used the View Object Wizard to create two view objects,
DeptVO and EmpVO inside of a package named package1. Then, assume that you invoked the View Link Wizard
from the package node to create a view link definition named MyViewLinkDef, that links DeptVO and EmpVO in
a master-detail relationship.
Then you can use the following code to create an instance of MyViewLink called vl. A view link usage called
MyLink1 will be added to the data model as a master-detail relationship between MyDept and MyEmp.
ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO");

ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO");
ViewLink vl = myAM.createViewLink("MyLink1", "package1.MyViewLinkDef", voDept, voEmp);
Related topics

Creating a View Link from an Association
Creating A View Link by Associating View Attributes
11-702
Use the createViewLinkFromEntityAssocName method to create a view link based on an association.
This method builds a view link definition from the association and creates a view link instance.
For example, during design time you can define view objects such as DeptVO for the DeptEO entity object,
and EmpVO for the EmpEO entity object. Then you can define an association named MyAssoc that associates
DeptEO to EmpEO. With this information, you can build a view link definition, say
MyViewLinkBasedOnAssoc, which relates DeptVO to EmpVO, based on this association. This relationship is
illustrated in the following figure:
During runtime, you can create a view link with code like this:

ViewLink vl = myAM.createViewLinkFromEntityAssocName("MyLink2", "package1.MyAssoc",
voDept, voEmp);
The primary difference between createViewLink and createViewLinkFromEntityAssocName is that

the former requires the view link definition name, and the latter requires the association name.
Related topics

Creating A View Link by Associating View Attributes
11-703
Creating a View Link by Associating View Attributes
Use the createViewLinkBetweenViewObjects method to create a view link by telling the
framework which view attributes to relate to each other. This method also gives you the option
of creating a view link accessor and specifying a custom association clause.
During design time, you could define view objects such as DeptVO and EmpVO but not define
an association or a view link definition.
During runtime, you can use createViewLinkBetweenViewObjects to create a view link

by relating attributes from DeptVO and EmpVO. For example, if both DeptVO and EmpVO have a
DeptNum attribute, you can associate the attributes and create the view link with the following
block of code:

// Build an attribute array, consisting of DeptVO.DeptNum.

AttributeDef[] deptAttrs = new AttributeDef[1];
deptAttrs[0] = voDept.findAttributeDef("DeptNum");
// Build an attribute array, consisting of EmpVO.DeptNum.

AttributeDef[] empAttrs = new Attributedef[1];
empAttrs[0] = voEmp.findAttributeDef("DeptNum");
ViewLink vl = myAM.createViewLinkBetweenViewObjects("MyLink3",
"Employees", // accessor name--more on this below
voDept, // master
deptAttrs,
voEmp, // detail
empAttrs,
null); // assoc clause
The createViewLinkBetweenViewObjects call builds a view link that makes voEmp a

detail of voDept. The voEmp view object will display employees for the current department in
voDept.
Using the Accessor Name
11-704
The createViewLinkBetweenViewObjects method lets you specify an accessor name.
The accessor lets you retrieve details by calling getAttribute with that name. In the above
code example, the accessor was specified as Employees (the second parameter). Calling
getAttribute on Employees will return an iterator through which you can enumerate
employees in the current department.
For example, you can write code like this that will return an iterator that can enumerate
employees in the first department.
Row row = voDept.first(); // get the first dept

RowIterator iter = (RowIterator) row.getAttribute("Employees");
If your code does not need an accessor, the accessorName parameter can be set to null.
Using the Association Clause
The createViewLinkBetweenViewObjects method lets you specify a custom association

clause, replacing the one generated by the business components runtime. Passing in null
means that the method will use the association clause generated by runtime which relates the
source attributes to the destination attributes. For example, since assocClause is null in the
above code snippet, runtime will use the equivalent of the PL/SQL association clause WHERE
voDept.DeptNum=voEmp.DeptNum.
Related topics

11-705
Using Transaction Utility Methods for Testing and
Debugging
The Transaction interface provides utility methods for testing and debugging queries and
applications, including:
● dumpQueryResult This method writes the result of the query to a (potentially very long)
string. It takes three parameters: the first is the SQL query statement. The second is the
class that dumps the result to a string. This class must implement the
oracle.jbo.server.QueryDump interface. The implementation of this class decides
what to do with the third parameter (which can be null). The Business Components for
Java framework provides these methods:
❍ oracle.jbo.server.QueryDumpCSV(), which dumps the query result as a

comma-separated BASIC text format. This method is not practical if the query
generates a large result set.
❍ oracle.jbo.server.QueryDumpTab() which dumps the query results in a tab-

separated text format.
● executeCommand This method takes one parameter: a valid SQL statement to be

executed by the server. The return value tells how many rows were affected by the SQL
statement.
Using dumpQueryResult
The following code example uses dumpQueryResult.
public static void demoSimpleFetch(ApplicationModule appMod) {

// Define and execute a simple SQL statement.
String sqlStr = "SELECT Emp.ename FROM EMP Emp ";
// dumpQueryResult is a utility method for testing queries.
String result = appMod.getTransaction().dumpQueryResult(sqlStr,
"oracle.jbo.server.QueryDumpTab",
null);
System.out.println(sqlStr);
System.out.println(result);
11-706
}
Using executeCommand
The following code example uses executeCommand. The SQL string is designed to update the
EMP table. This example passes the string to executeCommand, then prints a message to
report how many rows were actually updated.
public static void demoUpdateColumn(ApplicationModule appMod) {

String sqlStr = "UPDATE EMP " +
"SET MGR=7007 " +
"WHERE MGR=7698 ";
int n = appMod.getTransaction().executeCommand(sqlStr);
System.out.println("Updated " + n + " rows.");
}
Be careful when using executeCommand, because it will execute any valid SQL statement. For
example, you could perform an operation like the following DDL command:
appMod.getTransaction().executeCommand("DROP TABLE MYTEMPTABLE");
A pending database transaction could be committed inadvertently due to the implicit commit
performed by DDL operations, as well as having any row locks released.
11-707
About Customizing Existing Business Component
Applications
Applications developed with Business Components for Java are inherently easier to customize
than a typical enterprise application. This topic explores how a typical application is
customized, contrasts that with the benefits of using business components, and provides
instructions on how to extend business components.
Customizing a Typical Enterprise Application
Once an enterprise application has been delivered to a customer, it usually must be customized
after installation to tailor it to the needs of the particular site. In typical situations, these
customizations are made by obtaining the source code of the original application and modifying
it. On-site consultants or internal Information Technology engineers change the original source
code to make these customizations. Changing source code is potentially risky and causes re-
testing to ensure that the new features, as well as the original underlying functionality, work
correctly. After this expensive and time-consuming process, the customized application is
placed into service.
After a period of time, new versions of the original application are delivered to the site to fix
bugs or add new functionality in the base application. On-site consultants or internal
Information Technology staff must then:
● Re-obtain the new source code from the application provider.
● Diff and merge (that is, manually re-apply) all of the changed source code from the
previous customization with the new source code to determine where customizations
need to be re-applied.
● Manually re-apply the customizations to the new source code.
● Re-implement the customized application at the site.
● Re-test the modified components.
This entire process must be repeated each time a new version of the original application is
delivered.
11-708
Customizing Business Component Applications
In contrast, the Business Components for Java framework supports layered component
customization. This means that applications built and delivered as a set of business
components can be easily extended without modifying the original application source code.
Business components let you perform these customizations without requiring changes to the
original application's source code, and in a way that allows new versions of the original
application components to be "dropped-in" without requiring manual re-application of the
customizations.
The Business Components for Java framework allows the original component's existing
features to remain available while allowing you to add new features, attributes, and business
logic, or override some of the behavior of the original.
The customized components can optionally completely substitute the original component
implementations in the delivered application without touching the original application's source
code through "factory substitution". This means that if a customized "Order" component has
changed the way tax is calculated as part of its customizations, this new behavior can be
"substituted" into the existing order-entry system by creating a "CustomizedOrder" component
and substituting it for the original "Order" component.
Using JDeveloper to Customize Your Applications
JDeveloper wizards provide the functionality to let you extend the definition of existing business
components. You can extend:
● entity objects
● associations
● view objects
● view links
The wizards allow you to identify an existing component to serve as the base of the extended
component. JDeveloper then generates the Java and XML files for the extended component.
The extended component uses the Java extend capability to inherit the base component's
Java implementation class and metadata. You can extend this inheritance to multiple levels.
That is, you can create a component B which is extended from component A, then create a
11-709
component C which is extended from component B.
Steps for Customizing Business Components
The process of customizing components follows these general steps:
1. Create a JAR file containing the existing components and their project (.jpx) file.
Typically, this will already have been done for you by the application supplier.
2. Create a JDeveloper library for the JAR file and add it to the list of libraries for the new
project.
3. Import a package of existing components from the JAR file using the Import Package
option in JDeveloper.
4. Create a new package with a different name from the original to house the customized
components.
5. Use the wizards to create new components in your new package that extend the
appropriate components in the imported package.
6. Optionally, if you want the extended component to completely replace the original in an
existing application, substitute the extended component for the original.
11-710
Ways to Customize Existing Business Component
Applications
The following topics describe how to customize existing business component applications:
● Substituting Business Components
● Extending Business Components
11-711
When customizing business components, you can use a Business Components for Java
framework feature called substitution to build new applications. Substitution allows you to
replace all occurrences and usages of the original component in the existing application with
the customized component.
If you want one or more customized components to be completely substituted for existing
components throughout your system, use the Substitution page in the Business Components
Project Wizard. You do not have to modify any of the delivered application's source code to
accomplish this substitution. Instead, the wizard uses a factory-substitution design pattern to
provide the Business Components for Java runtime system with a substitution table which
maps the OldName of the existing component to the corresponding NewName which should
replace it. Now, whenever the application tries to create a component of type OldName, it will
create a component of type NewName instead. The wizard enters this information in your
project's .jpx project definition file.
The Business Components for Java runtime does not typically read the project's .jpx file. To
make the runtime read the .jpx file, you must add some additional information to the list of VM
parameters and to the runtime classpath.
Note: For the application model to remain valid, the custom component you are substituting
must either directly or indirectly extend the original component.
The procedure for substituting business components is the same whether you are substituting
entity objects, view objects, associations, view links, or application modules. However, each
component has its own substitution requirements and prerequisites. For more information about
the requirements and prerequisites for substituting each component type, see these sections:
● Substituting Extended Entity Objects
● Substituting Extended View Objects
● Substituting Extended Associations
● Substituting Extended View Links
● Substituting Extended Application Modules
11-712
To Substitute Business Components
1. Right-click the Project node and select Edit Business Components Project. The
Business Components Project Wizard opens.
2. In the Substitutions page, select the original component from the original package of
components in the Available pane, and the new component from the package containing
the extended components in the Substitutes pane, then click the Add button.
3. Click Finish to save the design time changes.
Updating a Substitution Definition
After you have created an extended component and substituted it throughout your application,
you might find that you want to test its behavior with a different extended component. In other
words, you might want to replace one extended component with another. The Business
Components for Java framework lets you substitute another extended component for the one
you originally created.
The Update button on the Business Components Project Wizard Substitution page lets you
replace one extended component with another extended component. For example, assume
that you have used the Substitutions page to substitute all instances of the Emp component with
the NewEmpEx component. Assume also, that you have created a TestEmp component with
different functionality than NewEmpEx and you want to test its performance in your application.
To update the substitution from NewEmpEx to TestEmp, follow these steps:
1. Right-click the project's .jpx file and select Edit. The Business Components Project
Wizard opens.
2. In the Substitutions page, select the substitution definition in the Substitutions list box
that you want to update.
3. Select the original component Emp from the original package of components in the
Available pane, then select the component with the new functionality that you want to
test, TestEmp from the package containing the extended components in the Substitutes
list box.
11-713
4. Click Update to replace the NewEmpEx substitution with TestEmp.
5. Click Finish to apply the Design Time changes.
Removing a Substitution Definition
The Remove button on the Business Components Project Wizard Substitution page lets you
discard the substitution of an extended component for an original component. Removing the
substitution definition will cause the application to use the original component.
1. Right-click the project's .jpx file and select Edit. The Business Components Project
Wizard opens.
2. In the Substitutions page, select the substitution definition in the Substitutions list box
that you want to discard.
3. Click Remove to discard the substitution.
4. Click Finish to apply the Design Time changes.
Applying the Substitutions at Runtime
After using the wizards to define the substitutions you want to make, the framework enters this
information in the project's .jpx file. The Business Components for Java runtime does not
typically read the project's .jpx file. To make the runtime read the .jpx file, you must add
some additional information to the project properties::
● identify the name of the project file to the Java VM.
● add the project's directory path to the runtime classpath.
To add this information, follow these steps:
1. From the JDeveloper menu bar, select Project | Project Settings to open the Project
Settings dialog box.
11-714
2. Open the Runner page. In the Java Options field, enter:
-Djbo.project=name
where name represents the directory-qualified name of the project

without the .jpx extension. For example:
-Djbo.project=myProjects\ExtendProject
3. Open the Paths page and add the project's directory path to the Output directories field.
11-715
Substituting Extended Entity Objects
Substituting an extended entity object allows any changes made to the original Entity to be
made available to all of its instances in the rest of the application. For example, if you have
added any new attributes or business logic to the extended entity object, substitution will allow
code in other parts of the application to use it.
Using JDeveloper to Substitute Extended Entity Objects
Use the Substitutions page of the Business Components Project Wizard to substitute an
extended entity object throughout your application. For the procedure to substitute an entity
object, see To Substitute Business Components. The framework makes an addition to the to
the Substitutes section of the project's .jpx file which identifies the name of the original entity
object and the name of the extended Entity that should be used instead.
For example, if you use the Substitutions page of the Business Components Project Wizard to
substitute the extended entity object NewEmpEx for the original entity object Emp throughout
your application, the framework adds a line to the Substitutes section of the project's XML
file. A portion of the project's XML file is included below:
...
<Substitutes>
<Substitute OldName ="package27.Emp" NewName ="Extender.NewEmpEx" />
</Substitutes>
...
11-716
Substituting Extended View Objects
Substituting extended view objects allows the code in your application to work with the results returned by the
queries over the new attributes and business logic added to the extended entity objects.
If you substitute an extended view object you must also ensure that you substitute the extended entity object
that it references. If the extended view object is the source or destination end of an extended view link you will
also have to substitute the extended view link.
Using JDeveloper to Substitute Extended View Objects
Use the Substitutions page of the Business Components Project Wizard to substitute an extended view object
throughout your application. For the procedure to substitute a view object, see To Substitute Business
Components. The framework makes an addition to the to the Substitutes section of the project's .jpx file
which identifies the name of the original view object and the name of the extended view that should be used
instead.
For example, if you use the Substitutions page of the Business Components Project Wizard to substitute the
extended view object NewEmpViewEx for the original view object EmpView throughout your application, the
framework adds a line to the Substitutes section of the project's XML file. A portion of the project's XML file
is included below:
<Substitutes>
<Substitute OldName ="package27.DeptView" NewName ="Extender.NewDeptViewEx" />
<Substitute OldName ="package27.EmpView" NewName ="Extender.NewEmpViewEx" />
<Substitute OldName ="package27.EmpForeignKeyAssoc" NewName ="Extender.NewFKAssocEx" />
<Substitute OldName ="package27.Dept" NewName ="Extender.NewDeptEx" />
</Substitutes>
Note that is is assumed that you have already substituted the extended entity objects NewEmpEx and
NewDeptEx for the original entity objects Emp and Dept, and the extended association NewFKAssocEx.
11-717
Substituting Extended Associations
Substituting an extended association allows any changes made to the original association, such as code added to
the association's XML file or new source and destination objects, to be made available to all of its instances in the
rest of the application. If you substitute the extended association, then you must ensure that the extended entity
objects it connects are also substituted. This is because the extended entity objects will typically have new attributes
that do not exist in the originals. Also, the the association might use these new attributes in its definition of the
source and destination role attributes.
As the previous figure illustrates, assume that when you extended the Emp entity object, you added a Loc (location)
attribute. Then when you create the extended association between NewEmpEx and NewDeptEx you can add Loc to
the lists of source and destination role attributes. If you then substitute the extended association into the application,
you must also substitute NewEmpEx (because Emp does not have a Loc attribute) and NewDeptEx (because Dept
does not recognize Loc as a source role attribute).
Using JDeveloper to Substitute Extended Associations
Use the Substitutions page of the Business Components Project Wizard to substitute the extended association
throughout your application. For the procedure to substitute an association, see To Substitute Business
Components. The framework makes an addition to the Substitutes section of the project's .jpx file which
identifies the name of the original association and the name of the extended association that should be used
instead.
extended association NewFKAsocEx for the original association EmpForeignKeyAssoc throughout your
application, the framework adds a line to the Substitutes section of the project's XML file. A portion of the
project's XML file is included below:
...
<Substitutes>
</Substitutes>
...
Note that it is assumed that you have already substituted the extended entity objects NewEmpEx and NewDeptEx
for the original entity objects Emp and Dept in the project file.
11-718
11-719
Substituting Extended View Links
Substituting an extended view link allows any changes made to the original view link, such as code added to
the view link's XML file or new source and destination objects, to be made available to all of its instances in the
rest of the application. If you substitute the extended view link, then you must ensure that the extended view
objects it connects (and the extended entity objects they reference) are also substituted. This is because the
extended view objects will typically have new attributes that do not exist in the originals. Also, the view link
might use these new attributes in its definition of the source and destination role attributes, and in the view link
query's WHERE clause.
As the previous figure illustrates, assume that when you extended the Emp entity object, you added a Loc
(location) attribute. This attribute will be added to the query when you create the extended view object
NewEmpViewEx. Loc is already an attribute of DeptView, and will automatically be included in the query of
the extended view object NewDeptViewEx. Then when you create the extended view link between
NewEmpViewEx and NewDeptViewEx you can add Loc to the lists of source and destination role attributes,
and also to the WHERE clause of the view link query. If you then substitute the extended view link into the
application, you must also substitute NewEmpEx and NewEmpViewEx (because Emp and EmpView do not have
a Loc attribute) and NewDeptEx and NewDeptViewEx (because Dept does not recognize Loc as a source
role attribute).
Using JDeveloper to Substitute Extended View Links
Use the Substitutions page of the Business Components Project Wizard to substitute the extended view links
throughout your application. For the procedure to substitute a view link, see To Substitute Business
Components. The framework makes an addition to the Substitutes section of the project's .jpx file which
identifies the name of the original view link and the name of the extended view link that should be used
instead.
extended view link NewFKLinkEx for the original view link EmpForeignKeyLink throughout your application,
the framework adds a line to the Substitutes section of the project's XML file. A portion of the project's XML
file is included below:
<Substitutes>
<Substitute OldName ="package27.Emp" NewName ="Extender.newEmp" />
11-720
<Substitute OldName ="package27.EmpForeignKeyLink" NewName ="Extender.NewFKLinkEx" />
</Substitutes>
Note that is is assumed that you have already substituted the extended entity objects NewEmpEx and
NewDeptEx for the original entity objects Emp and Dept, and the extended view objects NewEmpViewEx and
NewDeptViewEx for the original views EmpView and DeptView in the project file.
Note also that extending and substituting the association between the extended entity objects is optional and
has no effect on the extended view link between the views.
11-721
Substituting Extended Application Modules
An extended application module typically contains view objects, view links, and programming logic that are not
present in the original application module. Substituting the extended application module in your application lets you
propagate the new objects and functionality throughout the application. This allows the new objects to be used in
the same transaction as the existing objects.
If you include any extended view objects and view links in the extended application module's data model, they
must also be substituted. Similarly, for each of the extended view objects included in the data model, the extended
entity objects they reference must also be substituted.
Using JDeveloper to Substitute Extended Application Modules
Use the Substitutions page of the Business Components Project Wizard to substitute the extended application
module throughout your application. For the procedure to substitute an application module, see To Substitute
Business Components. The framework makes an addition to the Substitutes section of the project's .jpx file
which identifies the name of the original application module and the name of the extended application module that
should be used instead.
extended application module NewModuleEx for the original application module Package27Module throughout
your application, the framework adds a line to the Substitutes section of the project's XML file. A portion of the
project's XML file is included below:
<Substitutes>
<Substitute OldName ="package27.Package27Module" NewName ="Extender.NewModuleEx" />
<Substitute OldName ="package27.EmpForeignKeyLink" NewName ="Extender.EmpForeignKeyLinkEx"
/>
</Substitutes>
11-722
The following topics describe how to extend existing business components:
● Extending an Existing Entity Object
● Extending an Existing Association
● Extending an Existing View Object
● Extending an Existing View Link
● Extending an Existing Application Module
11-723
Once you have developed and delivered an enterprise application, you might find that you need
to add additional functionality or features. Business components are reusable, in that you can
tailor existing components to fit your needs. For example, if the delivered application includes
an EMP entity object, you might find that you need to extend its definition to include additional
information such as telephone number, years of service, pension plan, and business logic to
calculate the salary withholding based on the type of pension plan. This is only one way in
which you can customize an entity object. You can also customize entity objects by:
● Adding new attributes to entity objects. These additional attributes can capture extra
information that a particular site needs to track in addition to the base information that is
part of the supplied business components. For example, you can create an extended
Emp entity object with an added a YearsOfService attribute as a calculated value.
● Creating new entity objects to represent constructs that are specific to a certain site, and
associating these new entities to existing entity objects in the delivered application.
● Adding, changing, or supplementing the Java code on the entity objects in the delivered
application to tailor the business logic to a site's needs. For example, for a Customer
entity object you can create an extended entity object with business logic that examines
the Customer's Address attribute and determines shipping costs based on the distance
from the site.
● Adding additional validation rules to existing entity attributes. The effect of adding rules to
an attribute "ANDs" the rules. For example, assume there is a rule on a CreditRating
attribute in the original Customer entity object that requires its value to be greater than
200 points. In the extended entity object you can add an additional rule to test that the
payment status is not over due. If either rule fails an exception will be thrown.
● Changing default values for an entity attribute. For example, if an Emp entity object has a
Phone attribute, the extended entity object can list the site's main telephone number as
the default value. This can later be replaced with the direct telephone number for the
employee.
● Globally substituting existing components with ones you have extended without requiring
or modifying the application in which they are used. This topic is described in Substituting
Business Components in Packaged Applications.
11-724
Preparing the Database Tables
Just as an entity object in your application references a table in the database, an extended
entity object must also reference a table. There are two possible ways in which you can provide
a table to support the extended entity object:
● alter the existing database table to add the extra columns required. In this case, both the
original and the extended entity object will reference the same table.
OR
● create a new table in the database for the extended entity object whose leading columns
match the structure of the parent entity object's table. In this case, both the original and
the extended entity object will reference their own tables.
If you intend to have your application work with instances of both the parent and the extended
entity object concurrently, the simplest solution is for each entity object to have its own
database table. In this case, there are two possible ways to provide the database table for the
extended entity object:
● Create a table in the database that corresponds to the extended entity object. This table
must have at a minimum the same number of columns and the same Primary Key as the
table that corresponds to the base entity object (that is, the entity object you want to
extend). It is recommended that the table also have the same column order, although
this is not required. Then, you can add to the table any additional columns that you want
the extended component to have. In other words, the new table should have all of the
features as the original table, plus maybe some extra columns. Once you have created
the new table, use the Entity Object Wizard to generate the extended component from it.
● Create the extended entity object in the wizard, using the entity object that you want to
use as the base component. Then, select the extended entity object in JDeveloper's
Navigator and use the Create Database Objects command to forward generate a
corresponding table in the database. For example, given an Emp entity object that
references an EMP table, you can create the NewEmpEx entity object by extending Emp.
Then use forward generation to create the NEWEMP table in the database. This is
illustrated in the following figure.
11-725
To Extend an Entity Object
The following example illustrates the second possibility described above: creating the extended
entity object in the wizard, then using forward generation to to create the table in the database.
This example assumes that you have already creates a project, imported the package of
original components and created a package to house the extended components.
Suppose a vendor (Oracle, for example) sells an Emp component for working with employee
data, and a (fictional) company named Solutions Tech wants to customize it. Their developers
could take the following approach to create a custom NewEmp component.
1. Right-click the package that will hold the customized entity objects and select New
Entity Object. The Entity Object Wizard opens.
2. In the Name page, enter the name of the new entity object (NewEmpEx) in the Name
field. To offer you greater flexibility, note that in this page, the Name, Package, Extends
Entity, and Schema Object fields are editable.
3. Click the Browse button next to the Extends Entity field to open the Parent dialog. Use
the Parent dialog to select the entity object from which NewEmpEx will be extended. In
this case, select Emp, then click OK. Note, it is implied that the base object is in a
package in the project. Note: if you are creating the extended entity object from a pre-
existing table, see Creating an Extended Entity Object from a Pre-existing Table.
11-726
4. Click Next to proceed to the Attributes and Attribute Settings pages. Use these pages to
specify additional features for the NewEmpEx. For example, use the Define New Attribute
dialog (available by clicking New on the Attributes page) to create a YearsOfService
attribute of type Number. Use New From Table if you have made changes to any of the
existing entity object's attributes. Note that the Attributes page shows only new or
overridden attributes—not the entire set.
The attributes you define in these pages will be captured in the XML component
definition NewEmpEx.xml.
5. Optionally, use the Java page to generate Java classes for the extended entity object.
This will provide the ability to add domain-specific Java logic. The Java inheritance is
automatically set by the Wizard using the extends keyword in the Java source code.
Note, if Solutions Tech wants to override any pre-created business logic, then they can
edit this file.
6. Click Finish to create the new NewEmpEx entity object. The framework will creates a
.java and a .xml file for the extended entity object.
7. Right-click the package and choose Create Database Objects. In the Create Database
Objects dialog, shuttle NewEmpEx to the Objects to Create side and click OK. A table
corresponding to NewEmpEx will be created in the database.
Creating an Extended Entity Object from a Pre-existing Table
If you are creating an extended entity object from a pre-existing table, follow the steps 1, 2, and
3 described above. Instead of step 4, do this:
a. From the Database Schema drop-down list in the Name page, select the name of the
schema that contains the schema object that will provide the base definition for the
extended entity object.
b. Select the appropriate combination of Tables, Views, Synonyms, and Snapshots that
might contain the object you want to represent as an entity object.
c. In the Select Object field, select the name of the database object that that will provide
the base definition for the extended entity object.
11-727
After you complete these steps, continue with steps 5 and 6 above. Do not perform step 7,
using Create Database Objects to generate a table.
Understanding the Generated Extended Entity Object Files
The NewEmpEx entity object is created by extending the functionality of the Emp entity without
any source code modification. JDeveloper creates a .java and a .xml file for NewEmp which
can be seamlessly integrated into the packaged application. The NewEmpEx entity object can
now be used at runtime, however, you might want to add some additional features, such as
business logic or validation, to its .java file. You can then substitute it for all instances of Emp
in the original application. For information on how to substitute NewEmpEx for all instances of
Emp in your application, see Substituting Business Components.
Notice that the NewEmpEx entity object's XML file contains only the differences between the
definition of the original entity object and the extended version. The following is a code sample
of NewEmpEx.xml.

2 <!DOCTYPE Entity SYSTEM "jbo_03_01.dtd">
3 <Entity
4 Name="NewEmpEx"
5 Extends="package27.Emp"
6 DBObjectType="table"
7 DBObjectName="NEWEMPEX"
8 AliasName="NewEmpEx"
9 BindingStyle="Oracle"
10 CodeGenFlag="20"
11 RowClass="Extender.NewEmpExImpl"
12 DefClass="Extender.NewEmpExDefImpl" >
13 <DesignTime>
15 <Attr Name="_superClass" Value="package27.EmpImpl" />
16 <AttrArray Name="_publishEvents">
17 </AttrArray>
18 </DesignTime>
19 <Attribute
20 Name="Serviceinyear"
21 Type="oracle.jbo.domain.Number"
22 ColumnName="SERVICEINYEAR"
23 ColumnType="NUMBER"
24 SQLType="NUMERIC"
25 Precision="2"
11-728
26 Scale="0"
27 TableName="EMP1" >
28 <DesignTime>
29 <Attr Name="_DisplaySize" Value="0" />
30 </DesignTime>
31 </Attribute>
32 </Entity>
Lines 4-7: The Name, Extends, DBObjectType, and DBObjectName fields contain
information about the name of the extended component (NewEmpEx), the name of the
component which it extends (package27.Emp), the type of schema object that it references
(table), and the name of the database object (NEWEMPEX).
Lines 20-30: Notice that the Attribute tag contains information about the attribute that was
added to the extended entity object during Design Time. Information about the original
attributes will be obtained from the original component (package27.Emp). The only way that
the tag will contain information about the attributes in the original entity object, is if you selected
them in New From Table in the Attributes page, then changed their definition in the Attribute
Setting page.
11-729
Extending Associations
JDeveloper provides the extended association feature to let you preserve the association
relationship between extended entity objects. In addition, by extending an association, you can
access any new attributes that might have been added to the extended entity objects.
Extending the entity objects and the association between them preserves typesafe binding: any
association accessors written in the original entity objects will be inherited by the extended
entity objects and will be able to traverse the original association.
As illustrated in the following figure, an association defines a relationship between source and
destination entity objects based on common attributes. Each entity object can have an
accessor method that traverses the association. For example, assume you have a Dept and an
Emp entity object, and that Dept contains a getEmp() method that retrieves a row set of Emp
Objects for the given department, and Emp contains a getDept() method that retrieves the
current department.
As illustrated in the following figure, an extended entity object inherits the associations and the
association accessors of its parent. The accessor in the extended entity object can traverse the
original association. If you extend the Dept entity object, the getEmp() method will be
inherited by NewDeptEx and will be able to traverse the original association to retrieve data
from Emp. Similarly, if you extend the Emp entity object, the getDept() method will be
inherited by NewEmpEx and will be able to retrieve data from Dept.
11-730
Notice, however, that extending the entity objects does not extend the original association
between them. You cannot call a accessor from NewEmpEx to NewDeptEx (or from
NewDeptEx to NewEmpEx) unless you extend the association. An extended association allows
the association to be updated to relate extended entity objects.
Extending the association between the extended entity objects gives you the flexibility of:
● choosing any of the new extended entity attributes as source and destination role
attributes.
● changing the values of any of the pre-existing association properties such as cardinality
and composition.
The following figure illustrates an extended association between NewDeptEx and NewEmpEx.
To Extend an Association
11-731
The following example assumes that you have extended the original entity objects Dept and
Emp. The steps describe how to create an association between the extended entity objects
NewDeptEx and NewEmpEx by extending the association between the original entity objects.
1. Right-click the package that will hold the customized association and select New
Association. The Association Wizard opens.
2. In the Name page, enter the name of the new association (NewFKAssocEx) in the Name
field. To offer you greater flexibility, note that in this page, the Name, Package, and
Extends Association fields are editable.
3. Click Browse to open the Parent dialog. Open the package of original components and
select the association that you want to extend. Click OK to close the dialog. Click Next in
the Name page to proceed to the Association Entities page.
4. In the Association page, open the package containing the extended objects in the Select
Source Entity Object list and select the entity object NewDeptEx. NewDeptEx will act
as the source of the extended association. Next, open the package containing the
extended objects in the Select Destination Entity Object list and select the entity object
NewEmpEx. NewEmpEx will act as the destination of the extended association. Click Next
to proceed to the Source Role Attributes page.
5. In the Source Role Attributes page, select the entity attributes that define the relationship
on the source end of the extended association. You must specify the same number of
attributes for each entity object, in the proper order, on both the source and destination
ends. Notice that any new attributes added to the extended entity object are also
available. In this example, ensure that Deptno appears in the Selected Attributes list.
You can optionally specify all attributes that define a key. When you shuttle a key to the
Selected Attributes list, the attributes associated with that key automatically appear.
Also, if you select a key in the Source Role Attributes page, the matching key (if
applicable) will be included by default in the Destination Role Attributes page. Click Next
to proceed to the Destination Role Attributes page.
6. In the Destination Role Attributes page, select the entity attributes that define the
relationship on the destination end of the extended association. You must specify the
same number of attributes for each entity object, in the proper order, on both the source
and destination ends. Click Next to proceed to the Association Properties page.
11-732
7. In the Association Properties page, make any needed adjustments to the cardinality,
accessor, or composition properties. Click Next, then Finish to dismiss the Association
Wizard.
JDeveloper will generate a NewAssocEx.xml file to define the new association.
Understanding the Generated Extended Association Files
The NewFKAssocEx association is created by extending the functionality of the

EmpForeignKeyAssoc association without any source code modification. JDeveloper creates
a .xml file for NewFKAssocEx which can be seamlessly integrated into the packaged
application. The NewFKAssocEx association can now be used at runtime. You can also
substitute it for all instances of EmpForeignKeyAssoc in the original application. For
information on how to substitute NewFKAssocEx for all instances of EmpForeignKeyAssoc in
your application, see Substituting Business Components.
The following is a code sample of NewFKAssocEx.xml.

2 <!DOCTYPE Association SYSTEM "jbo_03_01.dtd">
3 <Association
4 Name="NewFKAssocEx"
5 Extends="package27.EmpForeignKeyAssoc" >
6 <DesignTime>
8 </DesignTime>
9 <AssociationEnd
10 Name="Dept"
11 Cardinality="0"
12 Source="true"
13 Owner="Extender.NewDeptEx" >
15 <Item Value="package27.Dept.Deptno" />
16 </AttrArray>
17 </AssociationEnd>
18 <AssociationEnd
19 Name="Emp"
20 Cardinality="-1"
21 Owner="Extender.NewEmpEx" >
11-733
23 <Item Value="package27.Emp.Deptno" />
24 </AttrArray>
25 </AssociationEnd>
26 </Association>
Lines 4,5: The Business Components for Java framework adds the Name and the Extends
fields to the Association tag to identify the name of the new association (NewFKAssocEx)
and the name of the original association which it extends
(package27.EmpEoreignKeyAssoc).
Lines 10-15: The framework uses the Name, Owner, Source, and Item Value fields within
the AssociationEnd tag to identify the name of one end of the original association (Dept),
the new owner of the association end (Extender.NewDeptEx), the source end of the
association (Source="true"), and adds the name of the foreign key to the ItemValue tag in
the AttrArray section (package27.Dept.Deptno).
Lines 19-23: Similarly, the framework uses the Name, Owner, and Item Value fields within
the AssociationEnd tag to identify the name of the opposite end of the original association
(Emp), the new owner of the association end (Extender.NewEmpEx), and the adds the name
of the foreign key to the ItemValue tag in the AttrArray section
(package27.Emp.Deptno).
11-734
About Developing Business Components for
Foreign Datasources
Business Components for Java can run against Oracle databases, as well as against
Microsoft's SQL Server and IMB's DB2. Depending on the needs of your application, there are
a number of different scenarios for development.
Scenarios for Development
There are a number of different configurations for connecting Business Components for Java to
a datasource.
● Oracle - For use with Oracle databases

● SQL92 - For use with SQL Server and DB2
● OLite - For use with an Oracle9i Lite database
● Switchable - For use with both Oracle and non-Oracle databases
● Custom - For use with a foreign database with custom data type mapping
The following sections detail these scenarios in more detail.
Oracle Scenario
This scenario is the default configuration if you have an Oracle database. This is the most
efficient configuration and allows you to take advantage of Oracle SQL constructs and JBO
domains, which leverage Oracle's efficient JDBC datatypes.
When you choose this configuration, these required libraries are added:
● JBO Oracle domains

● Oracle JDBC 8.1.7
SQL92 Scenario
This scenario allows you to run against Microsoft's SQL Server and IMB's DB2. This
configuration can be used to run against Oracle databases as well, but it will not perform as
well as the switchable scenario detailed below. In the SQL92 scenario you cannot use any
11-735
domain objects (you must use a Java type map). This will slow down performance.
For a complete walkthrough of connecting to a foreign datasource, see the topics SQL Server
Walkthrough and DB2 Walkthrough.
OLite Scenario
The OLite scenario is used exclusively for running against the Oracle9i Lite database. The
SQL92 configuration is very similar to this configuration and shares some of the same
limitations.
Switchable Scenario
This configuration is useful in that you can switch the target database at design time and
runtime, if you running both Oracle and SQL92-based databases. This configuration allows you
to take advantage of domain types, which are faster and more efficient than a Java type map,
but you are limited by the SQL92 dialect.
Note: In this scenario you must manually ensure that are using the appropriate domain
libraries. In the table below, notice that there are two domain types, Oracle and Generic. When
you are running against Oracle you must use the JBO Oracle domains. When running against
any other database you must switch your domain type to JBO generic domains. For more
information on switching datasources, see the topic Ways to Switch Datasources.
Custom scenario
If you have a database that uses enhanced datatypes not described adequately by the SQL92
standard, you will need to design a custom type map that maps the database types to Java
types. Like the SQL92 generic scenario, you are precluded from using domain types. There are
fewer SQL limitations in this scenario, but you should still be aware of them.
Understanding Connections, SQL Dialect, Type Maps, and Domains
For every development scenario there are four interconnected parts: JDBC connection, SQL
dialect, type map, and domains. JDeveloper is configured to work with an Oracle database by
default. To work with a different database, you must configure JDeveloper to use the
appropriate values. These values are displayed in the following table for comparison.
Scenario Connection URL SQL Dialect Type Map Domains
11-736
Oracle9i jdbc:oracle:thin Oracle Oracle JBO Oracle Domains
SQL92 jdbc:db_type:db_name:port SQL92 Java None*
OLite jdbc:polite:POLite OLite Java None*

Switchable jdbc:oracle:thin SQL92 Oracle JBO Oracle domains
jdbc:db_type:db_name:port JBO generic domains
Custom jdbc:odbc:db_name SQL92 Custom None*
Connection URL
Before you begin your project you must select a connection type. When you do this, the
business components framework chooses default values for the SQL dialect and type map.
These values appear in the drop down boxes in the Business Components Project Wizard.
The Connection URL for foreign datasources is jdbc:db_type:db_name:port where:
● db_type is the appropriate driver name, such as sqlserver or db2.

● db_name is the name given to the datasource. If you have not changed it, this
datasource name will be provided the default name.
● port
Typical connection URLs follow:
● For DB2: jdbc:db2:ORDENT

● For SQLServer: jdbc:microsoft:sqlserver://<db-
host>:1433;SelectMethod=cursor
Note from the SQL Server Driver documentation:
SelectMethod SelectMethod={cursor | direct}.
Determines whether or not Microsoft SQL Server "server cursors" are used for SQL
queries. Setting SelectMethod to direct allows SQL statements to be executed without
incurring server-side overhead for managing a database cursor over the SQL statement.
Direct mode is the most efficient for executing Select statements; however, applications
are limited to a single active statement while executing inside a transaction. If multiple
result sets are required from a single query execution, then the application must set
SelectMethod to direct.
SQL Dialect
11-737
Business Components for Java entity objects take responsibility for managing the data content
of relational tables. If the database connection is known to be an Oracle one, Business
Components for Java can perform several optimizations for you. If however, the application is
required to execute against arbitrary SQL datasources, these optimizations cannot be used.
We call the style of SQL generated on the application's behalf the SQL dialect.
Business Components for Java contains four SQL dialects:
● Oracle - Used only in the default Oracle9i scenario

● OLite - Used only in the OLite scenario
● SQL92 - Used in the SQL92 and switchable scenarios
● DB2 - Used when using the SQL92 scenario against a DB2 database.
After you choose your connection type, the framework knows which SQL dialect to use by
default. Any business components you create will reflect the appropriate SQL style. For
example, if you choose the SQL92 dialect, the binding will be ?-style instead of :1-style.
Note: The SQL dialect that the business component application designer uses in his custom
designed view objects must also match the dialect of the generated SQL.
Type Maps
The OLite and SQL92 scenarios do not permit the use of domains (except for Date and
Number). When domains are not available, Java types require that the database information is
converted to a Java representation and back again. This is done using a type map.
Business Components for Java contains two type maps:
● Oracle - Database columns are mapped to oracle.jbo.domain types

● Java - Database columns are mapped to Java types
If you have a database that uses enhanced datatypes not described adequately by the SQL92
standard, you will need to design a custom type map that maps the database types to Java
types.
Domains
Domain types are faster and more efficient than Java type maps, because they map directly to
11-738
the database types. The business components framework supplies two implementations of
oracle.jbo.domain types:
● JBO Oracle domains - These map efficiently through Oracle's JDBC driver
● JBO generic domains - These domains are mirrored implementations of the JBO Oracle
domains
Related Topics:
Limitations of Developing for Foreign Databases

Ways to Develop Business Components
About Type Maps
11-739
Limitations of Developing for Foreign Datasources
There are limitations when using Business Components for Java with non-Oracle databases.
When you chose to work with a different SQL dialect, the framework automatically changes the
SQL style to suit. However, you must be careful to use the appropriate dialect of SQL when
doing modifications to view objects. If, for example, you choose a SQL92 connection, during
development time you have to make sure that no Oracle-specific features are being used such
as Oracle Objects and Oracle-specific SQL.
This topic contains information on
● Generic limitations, which also apply to using OLite

● Limitations using DB2
● Limitations using SQL Server
Generic Limitations
● In both the SQL92 and OLite scenarios, your view objects must use JDBC style (?)
parameter binding.
● Do not use unsupported domains. For SQL92 and OLite, domain support is currently
limited to Char, Date, and Number.
● Do not use Forward Generation of constraints.
● If your rows do not have primary keys assigned, the IDE will force you to create one. If
you try and view an object in the Business Components Tester that does not have a
primary key assigned, you will receive an error.
● In the SQL92 mode using SQL Server, pessimistic locking for transactions is not
supported. You must choose optimistic locking, or no locking at all. Pessimisitic locking is
supported using DB2.
● Avoid using Oracle Object Types, CLOB, BLOB, Oracle specific SQL structs, and any
other data types that are not supported on your foreign database platform.
● When running JSPs, there is no support for local mode using the embedded OC4J
server, however, they are supported using the external OC4J server, provided the client
and middle tier are both deployed.
● BC4J does not have a persistent collection implementation for SQL Server or OLite in
this release. This means BC4J cannot use these datasources as a persistent store for
spill-to-disk or application module snapshots. For now, the user has the following
options:
11-740
❍ Use Oracle as persistent collection database. For example, use the
"jbo.server.internal_connection" property and specify a connection to an Oracle
database.
❍ Use a file for Applications Module snapshots and don't use spill-to-disk. To do this,
specify
jbo.test.passivateStateTo=file
as a property (either on command line or in the .properties file), and
jbo.pers.max.active.nodes=-1
The former puts AM snapshots into files and the latter turns off spill-to-disk.
Limitations Using DB2
The following are limitations on using BC4J with DB2:
Primary Keys
● DB2 does support ROWID but it is not an implicit column. This means that if the user
creates an entity object on a table that does not have a primary key, you canine use
ROWID as a primary key substitute.
● The user should be aware that when mapping a DB2 table to an entity object, at least
one attribute should be marked as primary key.
Note: It does not have to be the primary key constraint column in the database table, it
just needs to have unique values.
Data Types
● Oracle objects are not supported on DB2. This includes types like
oracle.jbo.domain.Array, Struct, etc.
● DBSequence and Sequence domains are not supported in this release.
● BC4J does not support LOB types in this release.
Sequences in DB2
The user needs to manage sequence interaction himself.
To create a sequence in DB2, execute:
11-741
● create sequence <seq-name> start with <val>
To drop a sequence in DB2, execute:
● drop sequence <seq-name> restrict
To get the next value from a sequence, execute:
● values nextval for <seq-name>
Note: This is the Oracle equivalent to:
select <seq-name>.nextval from dual
To get the current (previous) value from a sequence, execute:
● values prevval for <seq-name>
Note: The equivalent statement in Oracle is:
select <seq-name>.currval from dual
Outer Joins
The syntax for outer joins is different in DB2. DB2 does not support "(+)". So, the following SQL
statement in Oracle:
SELECT E.EMPNO, E.ENAME, E.JOB, E.DEPTNO AS EMP_DEPT_NUM,

D.DEPTNO, D.DNAME, D.LOC FROM EMP E, DEPT D WHERE E.DEPTNO = D.DEPTNO
(+) ORDER BY 1"
needs to be mapped to the following in DB2:
SELECT E.EMPNO, E.ENAME, E.JOB, E.DEPTNO AS EMP_DEPT_NUM, D.DEPTNO,

D.DNAME, D.LOC FROM EMP E LEFT OUTER JOIN DEPT D ON E.DEPTNO =
D.DEPTNO"
11-742
Limitations Using SQL Server
Using the Northwind and Pubs Samples with SQLServer
"Northwind" and "pubs" are built in databases samples that come with SQLServer2000. There
are some known issues when using these built-in databases in JDeveloper.
First you can change the ownership of the tables from "dbo" to your own SQL login account.
You can make a login say pubs_user for pubs database.
There is a database table called AUTHORS located in pubs database.
1. Go to pubs database and click on Tables.

2. Right click on authors and choose Design Table.
3. In design table click on the Table and Index properties icon.
4. Change owner from dbo to a user you create for pubs.
5. Start JDeveloper and login in as pubs_user in the connection manager.
6. You should now see authors and other tables you have changed to pubs_user ownership
in the database browser.
When running in design-time, AUTHORS and other tables with a primary key are not picked up.
You must put a primary key in manually to compile the project. This is a know issue. Some
tables like DISCOUNT do not have any primarily key, since BC4J design time requires a key
you will need to assign one attribute a key as well.
To be able to browse in the tester, make sure you add a driver class to the configuration and
choose this local configuration in the tester. However you will not be able to update without
errors and this is a known issue. For step-by-step instructions, see the SQL Server
Walkthrough topic.
Running JSPs in Local Mode for Foreign Datasources
For Type 4 JDBC Drivers, such as Microsoft SQL Server 2000 Driver for JDBC, you can deploy
a JSP in local mode by copying the needed JAR files to BC4J/lib. You will have to terminate
and restart the embedded server after copying over to BC4J/lib as they will not be picked up
dynamically as with external OC4J. For external OC4J, it is recommended you use
application.xml settings.
11-743
11-744
SQL Server Walkthrough
This topic walks you through the steps of creating a Business Components for Java (BC4J)
project against a Microsoft SQL Server database. Note that differences in the database
implementations and some limitations that you must observe. See the topic Limitations of
Developing for Foreign Datasources.
This walkthrough is organized by the following steps:
1. Requirements
2. Install the JDBC Driver
3. Prepare JDeveloper for Third-Party Connections
4. Specify Default Project Libraries
5. Create a New Connection
6. Start a Business Components Project
7. Test the Business Logic Tier
8. Configure the Application Module for a Client
9. Deploying to OC4J
Requirements
Before starting this walkthrough you need the following:
● Microsoft SQL Server 2000 Driver for JDBC.

● A SQL Server database, either local or remote.
● A database instance called ORDENT with a user named SCOTT and a login of SCOTT.
Your DB admin will need to use the SQL script located on the following path:
<jdev install>\BC4J\samples\sql\createdeptemp_sqlserver.sql
Alternatively, you can follow the directions below to set up your own SQL Server instance
Setting Up a Schema on a Microsoft SQL Server Instance
The database, security and user model for SQL Server differs from the Oracle model; follow
11-745
these steps to get started with connecting JDeveloper to SQL Server. This will create a
database called "ORDENT" and a user and login named "scott" with the password "tiger" (to
follow an Oracle tradition).
Note: You will need a Microsoft SQL Server installation and access to the client tools,
specifically Enterprise Manager and isql, Microsoft's command-line SQL processor.
1. Create the database:

Using Enterprise Manager and logged on as a system administrator (eg: sa/sa), create a
new database by
right clicking on the databases tab. Call it ORDENT.
2. Create a user and login:
Expand the database tab called ORDENT, right click on the Users node, and select
create new user.
a. Choose <new> from the Login name dropdown combo.
2. Choose SQL Server authentication for the authentication mode, and enter a name
of Scott, and tiger for the password.
3. Change the default database for this login to ORDENT.
4. Click the Database Access tab, and choose to allow Scott to access the ORDENT
database. Check the db_owner permit in database role field.
5. Click OK. You may have to reconfirm your password, then click Cancel.
3. Verify the settings:

The database ORDENT should have a user called Scott accessed via a global login
called Scott, whose default database is ORDENT.
4. Create the tables inside the ORDENT database:
a. Move to the directory containing the sample SQL scripts:
%JDEV_HOME%\BC4J\samples\sql
2. Connect to the database using isql and execute the script:
isql -U Scott -P tiger -S <dbserver> -i
createdeptemp_sqlserver.sql
5. Verify the tables:

Log onto the database using isql, and issue the following:
1> select * from dept

2> go
DEPTNO DNAME LOC
--- ----------- -------------
10 ACCOUNTING NEW YORK
20 RESEARCH DALLAS
11-746
30 SALES CHICAGO
40 OPERATIONS BOSTON
(4 rows affected)
1> select empno,ename,job from emp

2> go
empno ename job
---- ------ ---------
7369 SMITH CLERK
7499 ALLEN SALESMAN
7521 WARD SALESMAN
7566 JONES MANAGER
7654 MARTIN SALESMAN
7698 BLAKE MANAGER
7782 CLARK MANAGER
7788 SCOTT ANALYST
7839 KING PRESIDENT
7844 TURNER SALESMAN
7876 ADAMS CLERK
7900 JAMES CLERK
7902 FORD ANALYST
7934 MILLER CLERK
(14 rows affected)
6. Proceed with the walkthrough below.
Installing the JDBC Driver
To develop a business components project against SQL Server requires the Microsoft SQL
Server 2000 Driver for JDBC. You can download the driver from the following link:
http://www.microsoft.com/sql/downloads/2000/jdbc.asp
After downloading, follow the installation instructions in the install wizard. When setting up your
environment, the following default installation location is used throughout the remainder of this
tutorial:
C:\Program files\Microsoft SQL Server 2000 Driver for JDBC\lib
Preparing JDeveloper for Third-Party Connections

11-747
To prepare the JDeveloper IDE for third-party connections you need to edit the jdev.conf file.
This step requires that you shut down JDeveloper. You might want to print out these directions
first.
To prepare the JDeveloper IDE for third-party connections:
1. If JDeveloper is running, save your work and close down JDeveloper.

2. In a text editor, open <jdev_install>/jdev/bin/jdev.conf
You'll see a number of entries for AddJavaLibFile and AddJavaLibPath.
3. Create a new AddJavaLibPath entry that specifies the location of your SQL Server
Driver's lib directory. If you chose the default location your entry should look like this:
AddJavaLibPath C:/Program files/Microsoft SQL Server 2000 Driver
for JDBC/lib
Note: Make sure you use forward slashes (/) in the path.
4. In your text editor, save jdev.conf.
5. Start JDeveloper from the command line with the -verbose flag. While this step isn't
strictly necessary, this will allow you to see the system messages, which are important in
this walkthrough.
a. Open a command prompt.
2. Navigate to your <jdev_install>/jdev/bin directory.
3. Enter jdev -verbose
Now that JDeveloper is configured to handle third-party connections, you need to specify that
the proper libraries are included by default in your future projects.
Specifying Default Project Libraries
The next step is to add the relevant libraries to the default project settings.
1. From the Project menu, chose Default Project Settings.

2. In the navigation tree, under Configurations and then Development, click Libraries.
3. You need to add three SQL Server libraries: msbase.jar, msutil.jar, and mssqlserver.jar.
a. Click New
2. In the Library name field enter Other JDBC
3. Next to the Class path field, click Edit
11-748
4. Click Add Entry
5. Navigate to C:\Program files\Microsoft SQL Server 2000 Driver
for JDBC\lib and expand the folder
6. Control-click to select msbase.jar, msutil.jar, and either mssqlserver.jar
7. Click Select
8. Click click OK to close each dialog
Now that you've set up the IDE for third-party connections and specified that the appropriate
libraries be added to your project by default, you can create a connection.
Creating a New Connection
To create a new database connection, you'll use the Connection Wizard.
To create a new connection:
1. In the JDeveloper System Navigator, right-click the Connections node and choose New
Database Connection... to start the Connection Wizard
2. If the Welcome page appears, review the information there and click Next.
3. On the Type page, enter a connection name of SQLServer and in the Connection type
dropdown list, choose Third Party JDBC Driver. Click Next.
4. On the Authentication page, enter the Username and Password and select the checkbox
for Deploy password. Click Next.
5. On the Connection page, enter the Java class name and the URL.
Java class name: com.microsoft.jdbc.sqlserver.SQLServerDriver
URL: jdbc:microsoft:sqlserver://<db-host>:1433;SelectMethod=cursor
Note: There's a semicolon before SelectMethod=cursor.
Note on Select Method: From the MS SQL Server documentation:
SelectMethod={cursor | direct} determines whether or not Microsoft SQL
Server "server cursors" are used for SQL queries. Setting SelectMethod to direct allows
SQL statements to be executed without incurring server-side overhead for managing a
database cursor over the SQL statement. Direct mode is the most efficient for executing
Select statements; however, applications are limited to a single active statement while
executing inside a transaction. If multiple result sets are required from a single query
execution, then the application must set SelectMethod to direct.
6. On the Test page, click Test Connection. You should see a status message of
11-749
"Success".
If you get an error message, see the following table or check with your database
administrator:
If the error message states.... The problem is probably...

"Unable to find driver" a misspelling in the Java class name
"Error establishing socket" a misspelling on the machine name
"No suitable driver can be
a malformed URL
found"
"Login failed" make sure your password is correct
set the following parameter for the SQL Server DB connection
"Cannot open multiple cursors"
;SelectMethod=cursor
"Can't start a cloned connection
make sure you have not misspelled the parameter
while in manual transaction
;SelectMethod=cursor
mode"
7. Click Finish.
Starting a Business Components Project
If you have previously created a business components project against an Oracle database,
these steps will be familiar. The only difference is that you want to make sure you have
selected a SQL flavor of SQL92 and a Java type map. You also must specify that the proper
libraries are used in this project.
1. Create a new empty project.

2. In the System Navigator, right-click on your project node and chose Project Settings.
4. In the Available Libraries pane, select Other JDBC and shuttle it to the Selected Libraries
pane.
5. Click OK to close the dialog.
6. Right click on your project and choose New Business Components.
7. On the Connection page, from the dropdown lists, choose a SQL92 SQL flavor and a
Java type map. Click Next.
8. Enter a package name or accept the default name and click Next.
9. In the Business Components page you should see a list of the tables in your database.
Select DEPT and EMP and shuttle them to the Selected list.
10. Click Finish.
11-750
The quickest way to test the business logic tier is to use the Business Components Browser
(also called the Tester). In order to test your Java project, you need to let the spawned Java
virtual machine know about its executing environment. In particular, it needs to know how to
find the JDBC driver (via project libraries), and which JDBC driver to load (via a BC4J property
flag, which is controlled with a "Configuration").
To test the business logic tier with the Business Component Browser:
1. In the System Navigator, right-click on your application module node and choose
Configurations from the popup menu.
2. In the Configuration Manager, click Edit.
4. Scroll down to the property jbo.sql92.JdbcDriverClass and change it to
com.microsoft.jdbc.sqlserver.SQLServerDriver
6. In the System Navigator, right-click on your application module node and choose Test
7. For the application module connection, use the dropdown box to choose the
configuration you just edited, not the default one that is listed.
8. Click OK.
9. In the navigation pane of the Tester, right-click one of your view object members and
choose Show.
10. If you can scroll through the data, you have configured everything correctly.
Configuring the Application Module for a Client
While you can test the business logic tier easily using the Tester, there are additional
requirements for other types of client applications. When a client connects to the business logic
tier, it must use the correct SQL flavor, type map, and JDBC driver for the application module.
To set these values, you need to edit the configuration of your application module.
To edit the configuration of your application module:
1. In the System Navigator, right-click on your application module node and choose
11-751
Configurations.
2. In the Configuration Manager, click Edit.
3. In the Oracle Business Component Configuration dialog, click the Properties tab.
4. In the Property column, find jbo.TypeMapEntries and change the value to Java.
5. In the Property column, find jbo.sql92.JdbcDriverClass and change the value to
com.microsoft.jdbc.sqlserver.SQLServerDriver
6. In the Property column, find jbo.SQLBuilder and change the value to SQL92.
Deploying to OC4J
Once you've successfully completed and locally tested the project you can deploy it to OC4J.
But first you need to configure OC4J to work with foreign datasources.
To configure OC4J to work with foreign datasources:
1. In a text editor, edit the application.xml file in

<OracleHome>/j2ee/home/config/.
2. Add <library> tags pointing to msbase.jar, msutil.jar, and
mssqlserever.jar The syntax is <library path="<path>">
For example, if you used the default installation path, you would add the following tags to
the application.xml file:
<library path="C:\Program files\Microsoft SQL Server 2000 Driver

for JDBC\lib\msbase.jar">
for JDBC\lib\msutil.jar">
for JDBC\lib\mssqlserver.jar">
Note: You must use backslashes (\) in the path as illustrated above.
In addition, if you deploy a BC4J project that uses a foreign datasource while you have an
Oracle connection in JDeveloper, you may experience trouble with your deployed project.
There are two workarounds for this:
● When deploying to OC4J, remove all database connections in JDeveloper except for the
one pointing to your foreign datasource.
11-752
● Alternatively, edit the data-sources.xml file and add a <data-source> element for
your datasource manually. The syntax is:
<data-source
class="com.evermind.sql.DriverManagerDataSource"
name="SQLServerDS"
location="jdbc/SQLServerCoreDS"
xa-location="jdbc/xa/SQLServerXADS"
ejb-location="jdbc/SQLServerDS"
connection-driver="com.microsoft.jdbc.sqlserver.SQLServerDriver"
username="scott"
password="tiger"
url=jdbc:microsoft:sqlserver://<db-host>:1433;SelectMethod=cursor
User=<username>;Password=<password>
inactivity-timeout="30"
/
11-753
DB2 Walkthrough
This topic walks you through the steps of creating a Business Components for Java (BC4J)
project against a IBM DB2 Universal database for Windows NT version 7.2. Note that
differences in the database implementations and some limitations that you must observe. See
the topic Limitations of Developing for Foreign Datasources.
1. Requirements
2. Prepare JDeveloper for Third-Party Connections
3. Create a New Connection
4. Start a Business Components Project
5. Test the Business Logic Tier
6. Deploying to OC4J
Requirements
Before starting this walkthrough you need the following:
● IBM DB2 Universal database for Windows NT version 7.2, either local or remote.
● On the client machine, you need to have a DB2 client installation, because the Java
connectivity solution for DB2 that ships with the product requires native code.
● A database called ORDENT. Your DB admin will need to use the SQL script located on
the following path:
<jdev install>\BC4J\samples\sql\createdeptemp_db2.sql
Alternatively, you can follow the directions below to set up your own DB2 instance
Setting Up a Schema on DB2
The database, security and user model for DB2 differs from the Oracle model; follow these
steps to get started with connecting JDeveloper to DB2. This will create a database called
"ORDENT" and a user and login named db2admin with the password db2admin (or whatever
else you've used as your DB2 admin login and password).
11-754
1. Using the DB2 Control Center, create a database called ORDENT.
a. Open Start | Programs | IBM DB2 | Control Center
2. When the Control Center opens, choose the system (or DB host) and give your
administration user name and password.
3. Choose your database instance, for example DB2, right click on the databases
folder and select Create->Database from Wizard.
4. Follow the steps in the wizard to create ORDENT (use ORDENT for the database
name and the alias).
2. Locate the DB2 table creation script in

\BC4J\samples\sql\createdeptemp_db2.sql
3. Change the first line from
connect to ordent user scott using tiger
to whatever values you chose for your username and password. For example:
connect to ordent user db2admin using db2admin
4. To execute a script using DB2's command line processor, create a special DB2
command shell by executing the following:
START | Programs | IBM DB2 | Command Window
This creates a Windows NT command processor with special settings for DB2.
5. Invoke the command line processor with the -f switch to execute a script:
db2 -f createdeptemp_db2.sql
6. Verify that the contents of the tables are displayed at the end of the script execution.
7. Proceed with the walkthrough below.
Preparing JDeveloper for Third-Party Connections
To prepare the JDeveloper IDE for third-party connections you need to edit the jdev.conf file.
This step requires that you shut down JDeveloper. You might want to print out these directions
first.
To prepare the JDeveloper IDE for third-party connections:
1. If JDeveloper is running, save your work and close down JDeveloper.

2. In a text editor, open <jdev_install>/jdev/bin/jdev.conf
You'll see a number of entries for AddJavaLibFile and AddJavaLibPath.
3. Create a new AddJavaLibFile entry that specifies the location of your DB2 driver's
lib directory. If you chose the default location your entry should look like this:
11-755
AddJavaLibFile C:/Program Files/SQLLIB/java/db2java.zip
Note: Make sure you use forward slashes (/) in the path.
4. Add another entry for AddNativeCodePath. If you chose the default location your entry
should look like this:
AddNativeCodePath C:/Program Files/SQLLIB/bin
5. In your text editor, save jdev.conf.
6. Start JDeveloper from the command line with the -verbose flag. While this step isn't
strictly necessary, this will allow you to see the system messages, which are important in
this walkthrough.
a. Open a command prompt.
2. Navigate to your <jdev_install>/jdev/bin directory.
3. Enter jdev -verbose
Now that JDeveloper is configured to handle third-party connections, you need to specify that
the proper libraries are included by default in your future projects.
Creating a New Connection
To create a new database connection, you'll use the Connection Wizard.
To create a new connection:
1. In the JDeveloper System Navigator, right-click the Connections node and choose New
Database Connection... to start the Connection Wizard
2. If the Welcome page appears, review the information there and click Next.
3. On the Type page, enter a connection name of db2conn and in the Connection type
dropdown list, choose Third Party JDBC Driver. Click Next.
4. On the Authentication page, enter the Username and Password and select the checkbox
for Deploy password. Click Next.
5. On the Connection page, enter the Java class name and the URL.
Java class name: COM.ibm.db2.jdbc.app.DB2Driver
URL: jdbc:db2:ORDENT
Note: The last part (ORDENT) is the client connection alias.
6. On the Test page, click Test Connection. You should see a status message of
"Success".
If you get an error message, see the following table or check with your database
11-756
administrator:
If the error message

The problem is probably...
states....
"Unable to find driver" a misspelling in the Java class name
"Error establishing socket" a misspelling on the machine name
"No suitable driver can be
a malformed URL
found"
"Login failed" make sure your password is correct
7. Click Finish.
Starting a Business Components Project
If you have previously created a business components project against an Oracle database,
these steps will be familiar. The only difference is that you want to make sure you have
selected a SQL flavor of DB2 and a Java type map. You also must specify that the proper
libraries are used in this project.

2. Right click on your project and choose New Business Components.
3. On the Connection page, from the dropdown lists, choose your db2conn connection, a
DB2 SQL flavor and a Java type map. Click Next.
4. Enter a package name or accept the default name and click Next.
5. In the Business Components page you should see a list of the tables in your database.
Select DEPT and EMP and shuttle them to the Selected list.
6. Click Finish.
7. In the System Navigator, right-click on your project node and chose Project Settings.
9. In the Selected Libraries pane, select DB2 JDBC (it will be in red denoting that it does not
have a proper configuration yet) and click Edit.
Note: If the DB2 JDBC library does not exist, you can create one now.
10. Edit the library definition so that it points to the correct location of the zip file. If you chose
the default installation, the path would be the following:
C:\Program Files\SQLLIB\java\db2java.zip
11-757
The quickest way to test the business logic tier is to use the Business Components Browser
(also called the Tester).
To test the business logic tier with the Business Component Browser:
1. In the System Navigator, right-click on your application module node and choose Test
2. Click OK.
3. In the navigation pane of the Tester, right-click one of your view object members and
choose Show.
4. If you can scroll through the data, you have configured everything correctly.
Deploying to OC4J
Once you've successfully completed and locally tested the project you can deploy it to OC4J.
But first you need to configure OC4J to work with foreign datasources.
To configure OC4J to work with foreign datasources:
1. In a text editor, edit the application.xml file in

<OracleHome>/j2ee/home/config/.
2. Add <library> tags pointing to Program Files/SQLLIB/java/db2java.zip and
Program Files/SQLLIB/bin.
When you use a fixed path name, you must use the native slash direction for you
system. For example, on Windows, you must use backslashes:
<library path="C:\Program Files\SQLLIB\java\db2java.zip"/>

<library path="C:\Program Files\SQLLIB\bin"/>
Alternatively, if you have JDeveloper and DB2 on the same local drive you can use
relative path (in this case, use forward slashes). For example:
<library path="../../../../Program
Files/SQLLIB/java/db2java.zip"/>
<library path="../../../../Program Files/SQLLIB/bin"/>
11-758
If these values are not set correctly, you will receive errors in your OC4J console
concerning DB2 entries.
3. Now you can deploy your Business Components Project to OC4J.

4. If you deploy for example, as an EJB session bean, a file called data-sources.xml is
automatically added to the EAR file that you've deployed containing the correct data
source information. The data-sources.xml file in OC4J will not be used by default. The
only way to override this is to edit your application module properties to point to the
alternative data source. You will have to choose names that are different from the ones
that are in the automatically generated data-sources.xml file. A typical data-sources.xml
file may look like the following:
<data-source
name="IBMDB2DS"
location="jdbc/IBMDB2CoreDS"
xa-location="jdbc/xa/IBMDB2XADS"
ejb-location="jdbc/IBMDB2DS"
connection-driver="COM.ibm.db2.jdbc.app.DB2Driver"
username="scott"
password="tiger"
url="jdbc:db2:ORDENT"
inactivity-timeout="30"
/
11-759
Ways to Develop Business Components for Foreign
Datasources
Through JDeveloper, Business Components for Java has design-time and runtime support for
building business components against Oracle9i Lite and any generic (standards-based)
databases.
This means that you may want to:
● Develop an application that can use a SQL Server or DB2 database - Use this scenario
to connect to SQL Server or DB2. You can also configure Oracle9i to work in this mode,
but there are limitations.
● Develop an application that uses an Oracle9i Lite database - Use this scenario if you
want to develop and application for an Oracle9i Lite database.
● Develop an application that will allow you to switch databases - Use this scenario if you
want to be able to switch between Oracle9i and a standards-based database.
● Develop an application for a custom database - Use this scenario if you have a non-
Oracle database that uses enhanced datatypes not described by the SQL92 standard.
● Modify a legacy business components project - If you have a legacy business

components project, you can make it work with foreign datasources. Note that this is very
difficult and largely inadvisable. There is no wizard support for doing this.
● Develop an application by matching schemas - At design time, use an Oracle database

whose schema exactly matches the intended runtime schema. You can then modify your
application to use an Oracle9i Lite or generic SQL connection (SQL92) for runtime
testing and deployment. Note: Matching schemas is not the preferred way to develop a
business components application. In JDeveloper 3.1 and previous versions, there was no
design-time support for creating business components. Design-time support of business
components is now supported, and you are advised to create you applications by directly
connecting to the datasource, using one of the other options listed above.
11-760
Developing an Application for a Foreign Database
Business Components for Java supports connection to SQLServer and DB2 in this release. For
a step-by-step instructions see the following topics:
● SQL Server Walkthrough

● DB2 Walkthrough
Note: Before you start a business components project, you must chose which database
scenario you will use. You cannot change the SQL dialect and type map once you start the
project.
Additionally, you must observe certain limitations when building your business components
using the SQL92 connection.
11-761
Developing an Application for an Oracle9i Lite
Database
project.
If you want to use the Oracle9i Lite JDBC driver in JDeveloper to create connections and build
your business components against Oracle9i Lite databases, you must first configure
JDeveloper to work with Oracle9i Lite. If you have installed Oracle9i Lite version 5.0 in the
same Oracle home directory as JDeveloper, then JDeveloper should pick up the existence of
Oracle9i Lite automatically. If not, you may have to follow the directions below.
To configure a business component project for Oracle9i Lite:
1. Close JDeveloper. You may want to print these directions first.

2. Open jdev.conf in a text editor. This file is located in your [jdev_home]\jdev\bin
directory.
3. In the jdev.conf file, create a new AddJavaLibFile with the value
c:\orant\Mobile\classes\olite40.jar
Note: This assumes you installed Oracle9i Lite in the default directory. If you chose a
different location, make sure you specify the correct path.
Note: Make sure you add an entry for AddJavaLibFile and not AddJavaLibPath.
4. Also in the jdev.conf file, add a new entry for AddNativeCodePath with a value of
c:\orant\Mobile\sdk\bin.
Note: This assumes you installed Oracle9i Lite in the default directory. If you chose a
different location, make sure you specify the correct path.
5. Save and close jdev.conf.
6. Start JDeveloper.
It is recommended to start JDeveloper from the command line with the -verbose option.
This will let you see which libraries are being loaded. In the [jdev_home]\jdev\bin\
directory, open a command prompt and enter jdev -verbose
7. When JDeveloper opens, right click on the Connections node in the System Navigator
and choose New Connection.
8. Go through the connection wizard, specifying your OLite details.
9. Start JDeveloper and begin a business components project. In the Business
Components Project Wizard, make sure that the SQL dialect is OLite and Type map is
11-762
Java.
10. In the JDeveloper System Navigator, right click your project node and choose Project
Settings.
11. In the navigation pane of the Project Settings dialog box, click Libraries.
12. In the Available Libraries pane, select the Oracle8i Lite library and shuttle it to the
Selected Libraries pane.
13. Click Edit and make sure that the path is pointing to your installation of Olite40.jar.
14. Click OK to close the dialog box.
Additionally, you must observe certain limitations when building your business components
using the Oracle9i Lite connection.
11-763
Developing an Application for a Custom Database
project.
A custom database uses a SQL Server or DB2 connection, but adds a custom type map to
describe enhanced datatypes.
To configure a business component project for a custom database:
1. Create a custom type map.
2. Specify your type map by adding it to the classpath and to the wizard.
3. Follow the steps in the walkthrough topic, but note the following. In the Business
Components Project Wizard's Connection page, in the Type Map field, select your
named custom type map.
Additionally, there are a few limitations you should be aware of when developing business
components against a foreign datasource.
11-764
Modifying a Legacy Business Components for Java
Application for Foreign Datasources
Before you attempt to modify a legacy Business Components for Java application to use a
foreign datasource, you should understand the relationship between connections, SQL dialect,
type maps, and domains explained in the topic About Developing Business Components for
Foreign Datasources.
As a prerequisite, your legacy Business Components for Java application may not use any
Oracle-specific SQL or object types. The SQL should match the SQL92 dialect. You should be
familiar with the limitations of developing for foreign datasources. The SQL dialect in particular
must match exactly.
When you change SQL dialect, the Business Components for Java framework will
automatically update the entity objects so that they will work with the newly specified
connection type. View objects, on the other hand, remain unchanged. To make the legacy
application work with a different database configuration, you will need to examine every view
object in your project and, if necessary, change the SQL to suit the new dialect.
11-765
Developing an Application for Switchable
Databases
project.
In this development scenario you can build and run business components against Oracle9i and
one or more foreign databases by switching the connection.
To configure a business component project for switchable datasources:
1. Begin a business components project.

2. On the Connection page of the Business Component Project Wizard, click New to create
a new connection.
3. In the Connection dialog's Select a JDBC Driver field, the appropriate connection type.
4. Create your database connection.
❍ For a standards-based database, follow the steps for creating a connection in
Developing an Application for a Generic Database.

❍ For information on database connections, see Specifying the Connection to the
Database.
5. Click Test Connection for each connection. You should see the message "Success".
6. Repeat steps 2-5 for each connection.
7. Click OK.
8. Start a business components project.
9. In the Business Components Project Wizard's Connection page
a. In the SQL Dialect field, select SQL92.
b. In the Type Map field, select Oracle.
When you want to switch datasources you must switch the libraries and change the connection
first. Additionally, you must observe certain limitations depending on your connection type.
11-766
Switching Datasources
If you have a business components application that you have configured for a switchable
scenario,
1. Change the libraries in the JDeveloper IDE.

❍ If you are connecting to an Oracle database, choose JBO Oracle Domains.
❍ If you are connecting to a foreign database, chose JBO Generic Domains.
2. Change the connection.

a. In the Navigation pane, right click your business components project node and
chose Edit.
b. On the Connection page, select your other connection from the Connection drop
down box.
c. Click Finish.
11-767
About Using a Foreign Datasource by Matching
Schemas
Note: Matching schemas is not the preferred way to develop a business components
application. In JDeveloper 3.1 and previous versions, there was no design-time support for
creating business components, and matching schemas was the only way to create a business
components application against a foreign datasource. Design-time support of business
components is now supported, so you can create your applications by directly connecting to the
datasource. For more information, see About Developing Business Components for Foreign
Datasources.
You can develop your business components application using an Oracle database and expect
it to work with other databases as long as the schemas match exactly. You must be aware of
certain limitations when using databases other than Oracle. See Limitations of Developing for
Foreign Datasources for more information.
When you have finished developing your business components project and want to begin
runtime testing, you need to make several small changes in order to run against the foreign
database. You do not need to regenerate business components or modify SQL strings.
● Matching schemas with Oracle9i Lite
● Matching schemas with a standards-based database
11-768
Matching Schemas with Oracle9i Lite
You can run existing business components against Oracle9i Lite as long as your schemas
match and you keep in mind some limitations using Oracle9i Lite. You will not need to
regenerate business components or modify SQL strings.
To run existing business components against Oracle9i Lite:
1. Edit your Oracle9i connect string to use an Oracle9i Lite connection.
URL = "jdbc:polite:POLITE"
user = "scott"
password = "tiger"
Oracle9i Lite requires the three-argument form of the connection string.
2. Be sure your view objects use JDBC style parameter binding.
a. In the Workspace view of the Navigation Pane, right click a view object and
choose Edit.
b. Click the Query tab.
c. Select Use ? style parameters.
d. Repeat for each view object.
3. Change the SQLBuilder parameter to use an Oracle9i Lite database. There are several
ways to achieve this, depending on if you want to modify the project locally, distribute the
Oracle9i Lite capability to other developers, or toggle between Oracle9i Lite and Oracle9i
databases.
● Local project - When you want to modify your project locally, create a file with the name
bc4j.properties and place the file in your project's working directory (the one named
in Run/Debug working directory field on the Path tab of your Project Properties
dialog). The file you create must contain this line:
11-769
jbo.SQLBuilder=OLite
● Distributed project - When you want to distribute the Oracle9i Lite capability to other
developers, edit the oracle\jbo\server\jboserver.properties file in the
JDeveloper lib directory (in the jbomt.zip), to set the SQLBuilder parameter.
● Toggle databases - When you want to toggle between Oracle9i Lite and Oracle9i
databases, you can supply the SQLBuilder parameter in the Java VM Parameters
field on the Run/Debug tab of the Project Properties dialog, using the -D flag.
-Djbo.SQLBuilder=OLite
4. Add these Java libraries on the Libraries tab of the Project Properties dialog:
Oracle9i Lite
JBO Generic Domains
Note: By default JDeveloper installs an Oracle9i Lite library that points to

C:\orant\; however, if you installed Oracle9i Lite in another location, you will need to
change the library to use it.
5. If present, you must remove these libraries from the list to ensure your project does not
use conflicting domain implementations:
JBO Oracle Domains

Oracle9i JDBC
11-770
Matching Schemas with a Standards-based
Database
You can run existing business components against standards-based databases as long as your
schemas match and you keep in mind some limitations. You will not need to regenerate
business components or modify SQL strings.
To run existing business components against a foreign database:
1. Edit your Oracle connect string to use a generic SQL connection.
URL = "jdbc:odbc:db_name"
user = "scott"
password = "tiger"
Note that the three-argument form of the connection string is required.
2. Be sure your view objects use JDBC style parameter binding.
a. In the Workspace view of the Navigation Pane, right click a view object and
choose Edit.
b. Click the Query tab.
c. Select Use ? style parameters.
d. Repeat for each view object.
3. Change the SQLBuilder parameter to use a generic database. There are several
methods you can use to complete this step, depending on if you want to modify the
project locally, distribute the generic database capability to other developers, or toggle
between Oracle9i and generic databases.
● Local project - When you want to modify your project locally, create a file with the name
bc4j.properties and place the file in your project's working directory (the one named
in Run/Debug working directory field on the Path tab of your Project Properties
11-771
dialog). The file you create must contain this line:
jbo.SQLBuilder=SQL92
● Distributed project - When you want to distribute the generic database capability to
other developers, edit the oracle\jbo\server\jboserver.properties file in the
JDeveloper lib directory (in the jbomt.zip), to set the SQLBuilder parameter.
● Toggle databases - When you want to toggle between Oracle9i and generic databases,
you can supply the SQLBuilder parameter in the Java VM Parameters field on the
Run/Debug tab of the Project Properties dialog, using the -D flag.
-Djbo.SQLBuilder=SQL92
4. Add these Java libraries on the Libraries tab of the Project Properties dialog:
Your JDBC implementation

JBO Generic Domains
5. If present, you must remove these libraries from the list to ensure your project does not
use conflicting domain implementations:
JBO Oracle Domains

Oracle9i JDBC
11-772
About Type Maps
A type map matches Java datatypes to SQL types. For example, see the following table.
Java SQL
Boolean BIT
Float REAL
Long BIGINT
java.math.BigDecimal NUMERIC
java.sql.Date DATE
Business Components for Java contains two type maps:
● Oracle - Database columns are mapped to oracle.jbo.domain types

● Java - Database columns are mapped to Java types
If you are using a foreign datasource you may need to customize the type map to adequately
describe the mapping of the data in your database to their corresponding Java formats.
To view a sample type map class, see Sample Type Map Class.
Note: You must choose a type map before starting a business components project, you cannot
change it afterwards.
11-773
Creating a Custom Type Map
You may need to employ a custom type map if you are using a Oracle9i Lite or a standards-
based database (SQL92), and are connecting to databases that uses enhanced data types.
To create a custom type map:
1. From the File menu, choose New.
2. In the Object Gallery, click Class, and then OK.
3. In the Class Wizard, name the type map class.
4. Accept the default values for the remaining fields and click OK.
(The Extends field should contain java.lang.Object, the Public and Generate
constructor checkboxes should be selected.)
5. Add the following import statements:
import oracle.jbo.common.JboTypeMap;
import java.sql.*;
6. Click OK to generate your skeleton class.
7. Add code to map your Java types to SQL types. A sample type map class is provided.
11-774
Specifying a Custom TypeMap for Generic JDBC
You may need to employ a custom type map if you are using a standards-based SQL type, and
are connecting to databases that use proprietary data types. To specify a custom type map:
1. Create a custom type map class which would define the mappings and Compile the
class.
2. Put the type map class is in the classpath:
a. Close JDeveloper.
b. In a text editor, open jdev.conf in the [jdev_home]/jdev/bin directory.
c. Add a new AddJavaLibFile entry specifying the classes directory where your
custom type map class can be found. You can give the absolute path
(C:/JDeveloper/..) or follow relative path. For example:
AddJavaLibFile ../mywork/workspace_name/project_name/classes
3. Make the type map class accessible from the wizard:

a. In a text editor, open the jbo.properties file in the
[jdev_home]/jdev/system directory.
b. Add the line oracle.jbo.TypeMap#=<shortname>,<fullclassname>
where:
# An integer which you increment for each new type map class
<shortname> The name of the type map that shows up in the wizard
<fullname> The full path of the type map class
For example: oracle.jbo.TypeMap2=DB2,<package_name>.<class_directory>
oracle.jbo.TypeMap1=Access,mypackage.AccessTypeMap
Note: In the above examples, notice that AccessTypeMap.class and
DB2TypeMap.class are referred to by class name only (no path or .class
extension). Both classes are assumed to be in the classpath already. If not, you
must use the package-qualified name.
4. Modify the JDeveloper's Default Project Settings to include the BC4J runtime library.
a. Start JDeveloper.
2. From the Project menu, select Default Project Settings.
3. In the navigation tree, click Libraries.
4. Shuttle BC4J Runtime to the Selected Libraries list.
5. Click OK.
11-775
5. Create a new business component project. In the Business Component Project Wizard's
Connection page, select your type map from the drop down box.
When you create business components, the newly created components will have the
type mappings specified in your class.
11-776
Sample TypeMap Class
The following is a sample Java type map class, which you can use to model your own custom type map class. For
more information on type maps, see About Type Maps.
// Copyright (c) 2000 Oracle Corporation

/*
Java Object Type ---- JDBC Type
------------------------------------------
String ----- CHAR, VARCHAR, or LONGVARCHAR
java.math.BigDecimal ----- NUMERIC
Boolean ----- BIT
Integer ---- INTEGER
Long ---- BIGINT
Float ----- REAL
Double ----- DOUBLE
byte[] ----- BINARY, VARBINARY, or LONGVARBINARY
java.sql.Date ---- DATE
java.sql.Time ----- TIME
java.sql.Timestamp ---- TIMESTAMP
Clob ---- CLOB
Blob ---- BLOB
Array ----- ARRAY
Struct ----- STRUCT
Java class ---- JAVA_OBJECT
-------------------------------------------------
*/ /**
* The entries are formatted as follows:
* COLUMN_TYPE
- column type in the database
* JAVA_CLASS_NAME -
Java class which should store in-memory data from the given column-type
* JDBC_SQL_TYPE
- Name of the jdbc sql type id that the subsequent integer-entry represents.
* JDBC_SQL_TYPE_ID - Integer
value from java.sql.Types or a corresponding Types list in jdbc.
* DISPLAY_LENGTH
- Default size for various String/Character types.
* NUMERIC_TYPE - The value is listed as true for
all numeric types
*
*/
import oracle.jbo.common.JboTypeMap;
import java.sql.*;
public class SampleJDBCTypeMapEntries extends Object

{
public SampleJDBCTypeMapEntries() {
new JboTypeMap("NUMBER"
,"java.math.BigDecimal","NUMERIC",java.sql.Types.NUMERIC,null,true);
new JboTypeMap("INTEGER" ,"java.lang.Integer","INTEGER",java.sql.Types.INTEGER,null,true);
new JboTypeMap("DATE" ,"java.sql.Date","DATE",java.sql.Types.DATE,null);
new JboTypeMap("VARCHAR2" ,"java.lang.String","VARCHAR",java.sql.Types.VARCHAR,null);
11-777
}
}
11-778
Java Type Map Entries
The following table lists the standard Java data types and their mappings. These types are
used to map table columns to entity attributes.
Database Column Type Java Class Name JDBC Type JDBC SQL Type ID Int
NUMBER java.lang.Boolean BIT BIT -7
VARCHAR2 java.lang.String VARCHAR VARCHAR 12
NVARCHAR2 java.lang.String VARCHAR VARCHAR 12
CHAR java.lang.String CHAR CHAR 1
LONG java.lang.String LONGVARCHAR LONGVARCHAR -1
NUMBER java.lang.Integer NUMERIC NUMBER 2
NUMBER java.math.BigDecimal NUMERIC NUMBER 2
TIMESTAMP java.sql.Timestamp TIMESTAMP TIMESTAMP 93
DATE java.sql.Date DATE DATE 91
STRUCT java.lang.Object STRUCT STRUCT 2002
STRUCT java.lang.Object OTHER OTHER 1111
11-779
Using XML with Business Components
This book contains miscellaneous topics about XML.
● Implementing XML Messaging
● About Business Components, XML, and Packages
● Using the XML Parser
● Using Special Characters in XML
● Retrieving Metadata from a Custom Lookup Implementation
Note that there is a situation where XML rendering from a view object can loop infinitely. If you
create two view objects, say DepartmentsView and EmployeesView, with two view links:
● One with DepartmentsView as master and EmployeesView as detail, and

● One with EmployeesView as master and DepartmentsView as detail
then calling writeXML on either of the views can generate infinite loops as Business
Components for Java recursively traverses these relationships. For example, if you use the
Business Components for Java wizards to generate default entity objects, view objects, view
links, and an application module for the EMPLOYEES and DEPARTMENTS tables in the
Oracle9i "common schema," the presence of foreign keys from DEPARTMENTS to
EMPLOYEES and EMPLOYEES to DEPARTMENTS will cause this situation to occur with view
links from one to the other, and vice versa. The workaround is to delete one of the view links, or
create two different view objects based on DEPARTMENTS and recreate the view links so that
DepartmentsView links to EmployeesView and EmployeesView links to DepartmentsView2.
11-780
About Business Components, XML, and Packages
The business components framework represents each business component using a
combination of XML and Java code. The XML code defines the metadata representing
declarative settings and features of the object. The Java code implements the object's
behavior.
Business components reside in packages using semantics identical to packages in Java. By

convention, the files DeptView.xml and DeptViewImpl.java (shown in the following figure)
are in the package d2ePackage because they reside in the directory d2ePackage.
Each Java file records the package to which it belongs by including code like the following:
package d2ePackage;
...
public class DeptViewImpl extends oracle.jbo.server.ViewObjectImpl {
...
}
Similarly, each XML file records the package to which it belongs by including code like the
following:
<ViewObject
Name="DeptView"
...
ComponentClass="d2ePackage.DeptViewImpl">
The d2ePackage.xml file contains references to its containees.
Related topics
11-781
11-782
Using the XML Parser
Including the Oracle XML parser in your Java programs allows you to write applications that
can search and process XML documents. The XML parser is written in Java, and facilitates
processing an XML document as either:
● a tree of W3C DOM (Document Object Model) objects
OR
● a stream of SAX events
The parser also checks whether an XML document is well-formed, and optionally, if it is valid. It
also contains an integrated XSLT processor for transforming XML documents.
In the samples\xmlsamples directory, the JDeveloper project JDevXMLExamples.jpr

contains several Java programs that demonstrate some of the ways in which you can use the
XML parser. You can open the project in JDeveloper and inspect the individual files. You can
also run the files from the Navigation pane:
1. Open the project in JDeveloper: samples\xmlsamples\JDevXMLExamples.jpr.
2. From the JDeveloper menu bar, select Project | Project Properties, open the Paths tab,
and ensure that these libraries are present in the Java libraries list box:
❍ Oracle XML Parser 2.0
❍ Oracle XML SQL Utility
❍ Oracle 8.1.6 JDBC
If they are not present, click Add and select the libraries from the
Select a Java Library dialog.
3. To run individual .java files, right-click them in the Navigation pane and select Run.
11-783
Files in the Example XML Project
This section provides a brief description of the files in the example XML project
JDevXMLExamples.jpr.
XMLForQueryResults.java
The XMLForQueryResults.java program uses the ConnectionHelper.java program to

connect to the database. The XMLForQueryResults.java program performs a query and
generates XML query results using the OracleXMLQuery class from the Oracle XML SQL
Utility for Java.
TransformedShoppingCart.java
The TransformedShoppingCart.java program loads Sample.xml file from an input

stream and uses the XML parser and the selectNodes() method to search for particular
nodes. The program prints the results, using the style sheet Sample.xsl to determine the
output format.
To run the program successfully, you must copy Sample.xml and Sample.xsl to the project
output path JDeveloper_Home\myclasses, where JDeveloper_Home represents the
JDeveloper home directory.
ParseXMLfromURL.java
The ParseXMLfromURL.java program uses the XML parser to parse an XML file from a
given URL passed as the first argument on the command line. The program prints the results. If
the program cannot parse the file successfully, it prints an error. The program also checks that
the format of the given URL is valid.
To run this program from JDeveloper, select Project | Project Properties from the menu bar,
and enter the argument name in the Run/Debug tab of the Properties dialog.
ParseXMLfromString.java
The ParseXMLfromString.java program uses the XML parser to parse an XML file from a
string and prints the results. If the parser encounters an error, the program prints the line and
column number where it occurred, the offending expression, and an error message.
11-784
FindElement.java
The FindElement.java program uses the XML parser and an XPath expression to search
the Sample.xml file for specific nodes. The XPath expression specified in
FindElement.java locates all Item elements at any level of the document which have a Qty
child whose value is greater than zero, and a Discount child whose value greater than four.
To run the program successfully, you must copy Sample.xml and Sample.xsl to the project
output path JDeveloper_Home\myclasses, where JDeveloper_Home represents the
JDeveloper home directory.
ConnectionHelper.java
The ConnectionHelper.java program selects the appropriate connection for the user
name/password SCOTT/TIGER based on whether the program is running inside the Oracle8i
database. If the program is running inside the database it chooses the Server (KPRB) driver. If
not, it chooses the JDBC Thin driver.
Sample.xsl
The Sample.xsl file contains a sample XSL style sheet that is used by several programs in
this project. It provides the structure and format for printing the contents of a "shopping cart"
used in a very simple e-commerce paradigm.
Sample.xml
The Sample.xml file contains sample data in XML format that is used by several programs in
this project. The file reflects a very simple e-commerce "shopping cart" paradigm and contains
the titles, item numbers, quantities, and price discounts of fictitious books.
XSLT.java
The XSLT.java file contains helper routines to select nodes from XML files, using Oracle's
XSLT engine. The helper routines use the built-in selectNodes() methods supported by
oracle.xml.parser.v2.XMLNode interface.
11-785
Using Special Characters in XML
When you use wizards to customize any string in your XML file, you can use the following
special symbols: <, >, &, ', ". You can also use these symbols when you are editing a query in
Expert Mode or when you are manually entering SQL code into XML files between CDATA
tags.
If you are editing your XML files manually, and your SQL statement is not between CDATA
tags, do not use special symbols in the WHERE clause, because the XML Parser will throw a
parsing exception. Instead, use the following escape sequences to represent these symbols.
The number in each sequence is the ASCII value of that character.
Symbol (Name) Escape Sequence

< (less-than) < or <
> (greater-than) > or >
& (ampersand) &
' (apostrophe or single '
quote)
" (double-quote) "
Related topics
11-786
Retrieving Metadata from a Custom Lookup
Implementation
The Business Components for Java framework owes much of its flexibility to its metadata-
driven architecture. Business components metadata is described in XML, while their companion
Java classes provide component implementations.
By default, the framework locates XML component definition files by looking for XML files as
resources in the CLASSPATH. However, advanced users can provide a custom metadata
lookup implementation that retrieves the metadata from anywhere you want.
The following figure shows the classes and interfaces involved in business components
metadata lookup:
Given a request to lookup the metadata for the component named

oracle.apps.requisition.LineItem, the default implementation of the
11-787
getMetaDataStream() method calls getResourceAsStream() to open the file
/oracle/apps/requisition/LineItem.xml from the CLASSPATH.
To provide a custom metadata lookup mechanism you need to provide a class that implements
the oracle.jbo.server.xml.XMLContext interface. For convenience, we provide a base
implementation of such a class in oracle.jbo.server.xml.XMLContextImpl that you
can extend rather than writing the implementation of every method in the XMLContext
interface yourself.
Most custom lookup schemes can be achieved by extending XMLContextImpl and overriding
the following method:
public InputStream getMetaDataStream(url)
The lookup method in XMLContextImpl implements a component name substitution

mechanism based on entries in the XMLContext interface's namespace that have been bound
to new names through calls to:
XMLContext.bind("oldname","newname")
that the framework makes upon finding:
<Substitutes>
<Substitute OldName="x.y.Department" NewName="q.p.NewDepartment"/>
<Substitute OldName="a.b.Employee" NewName="c.e.Employee"/>
</Substitutes>
in the project file (*.jpx) whose name is provided by the value of the Factory-Substitution-List
property in the /oracle/jbo/server/jboserver.properties property file.
Note: Setting the Factory-Substitution-List can be performed with the

-Djbo.project=mypackage.MyProject option on the command line.
Currently, the lookup implementation also translates the component name into a URL path
name so that a request by the framework to lookup the component name:
oracle.apps.requisition.LineItem
will be passed to getMetaDataStream as the String:
11-788
/oracle/apps/requisition/LineItem.xml
and a request by the framework to lookup a project metadata file like:
mypackage.MyProject.jpx
will be passed to getMetaDataStream as the String:
/mypackage/MyProject.jpx
Note: In future releases, lookup will likely return the substituted package name like
oracle.apps.requisition.LineItem without converting it to a URL path name as part of
the lookup implementation. You can plan ahead now by either:
● Reimplementing all the methods in XMLContext yourself, so you can perform the
substitution in your own XMLContext implementation (or ignore substitutions altogether)
or
● Simply program your getMetaDataStream implementation today in a way that checks

for the presence of slashes in the name and converts them to dots and removes .xml
extension if the slashes are present.
If your getMetaDataStream implementation already wants the component to be translated

into an URL name (or can make use of it just the same in this format as a primary key into
some runtime dictionary) then you can provide a simple implementation of
getMetaDataStream like:
import oracle.jbo.server.xml.XMLContextImpl;
import java.net.*;
import java.io.*;
public class HTTPXMLContextImpl extends XMLContextImpl {

public HTTPXMLContextImpl(Hashtable env) {
super(env);
}
public InputStream getMetaDataStream(String name) {
11-789
String urlBase = "http://metadataserver.company.com";
InputStream iStr = null;
try {
iStr = (new URL( urlBase + name )).openStream();
}
catch (MalformedURLException m) { return null; }
catch (IOException i) { return null; }
return iStr;
}
}
This is a very simple implementation of a custom XMLContext. It overrides the default

behavior to fetch the metadata for a component like:
oracle.apps.requisition.LineItem
whose name will be passed to getMetaDataStream as:
/oracle/apps/requisition/LineItem.xml
from a webserver at URL
http://metadataserver.company.com/oracle/apps/requisition/LineItem.xml
Of course the implementation could be more sophisticated, requesting metadata from an

arbitrary service. This service could even dynamically materialize business components XML
metadata based on querying database-driven, runtime dictionary information.
Once you have created your custom implementation class, you need to tell the business
components runtime to use your implementation instead of the default. This is accomplished by
setting the value of the MetaObjectContext property in the
./oracle/jbo/server/jboserver.properties file. By default that file resides in the
jbomt.zip archive in the .\lib subdirectory of the JDeveloper install home.
The example below shows the jboserver.properties file which has been edited to have
the MetaObjectContext property set to use the sample HTTPXMLContextImpl class
above, and the Factory-Substitution-List property set to use the
mypackage.SomeProject project file to find the factory substitution list.
# ------------------------------------------------------------------------
11-790
# File: oracle.jbo.server.jboserver.properties
# Cont: JBO Runtime Property Definitions
# Desc:
# ------------------------------------------------------------------------
# XML Context Factory and context for Meta Object lookup.

MetaObjectContextFactory = oracle.jbo.server.xml.DefaultMomContextFactory
# MetaObjectContext = oracle.jbo.server.xml.XMLContextImpl
# XML Context Customized by user : For test only
MetaObjectContext = HTTPXMLContextImpl
# Is lazy loading property for MOM: Recommended value = true

IsLazyLoadingTrue = true
# User Substitution List through "Substitute Mechanism"

Factory-Substitution-List = mypackage.SomeProject
#SessionClass = oracle.jbo.server.SessionImpl
# Type of SQLBuilder interface to load

jbo.SQLBuilder = Oracle
#jbo.SQLBuilder = OLite
# ------------------------------------------------------------------------
# end of file
# ------------------------------------------------------------------------
11-791
Using XML Metadata Properties that Affect XML
Generation
The following custom properties affect XML generation when using the writeXML method of a
view object or row.
Property Name Value Valid For
XML_ELEMENT a legal view objects

element and view
name attributes
XML_ROW_ELEMENT a legal view objects
element
name
XML_CDATA any value view attributes
(not empty)
XML_EXPLICIT_NULL any value view objects
(not empty) and view
attributes
XML_ELEMENT
If the XML_ELEMENT custom property is present for a view object, its value is used as the
XML element name for the view object in XML, when it is generated using the writeXML
method and "consumed" by the readXML method.
If the XML_ELEMENT custom property is present for a view attribute, its value is used as the
XML element name for the attribute in XML, when it is generated the writeXML method and
"consumed" by the readXML method.
11-792
<Departments>
<DeptViewRow>
<Empno>1010</Empno>
</DeptViewRow>
</Departments>
<DeptView>
<DeptViewRow>
<Empno>1010</Empno>
<Sal>1234</Sal>
</DeptViewRow>
</DeptView>
XML_ROW_ELEMENT
If the XML_ROW_ELEMENT custom property is present for a view object, its value is used as
the XML element name for each row of query results produced by the view object in XML, when
it is generated the writeXML method and "consumed" by the readXML method.
● XML_ROW_ELEMENT="Department" in the view object properties
<Departments>
<Department>
<Empno>1010</Empno>
</Department>
</Departments>
11-793
<DeptView>
<DeptViewRow>
<Empno>1010</Empno>
<Sal>1234</Sal>
</DeptViewRow>
</DeptView>
XML_CDATA
If the XML_CDATA custom property is set to a not empty value for a view attribute, then its
value will be output as a CDATA section instead of as plain text.
XML_EXPLICIT_NULL
If the XML_EXPLICIT_NULL custom property is set to a not empty value for a view object, then
any attribute with a null value will generate an XML element that looks like:
If the XML_EXPLICIT_NULL custom property is set to a not empty value for a view attribute,
then in the case that the indicated attribute has a null value, the system will generate an XML
element that looks like:
11-794
About Business Components and Oracle Object
Types
The business component representation of Oracle Object Types depends on how the objects
are created and used in the database. Briefly, if the object is created as a column object, the
business component representation is that of a domain. If the the object is created as an object
table, the business component representation is that of an entity object.
For more detailed information how Oracle Object Types are represented as business
components, see the following topics:
● Representing Column Objects

● Representing Object Tables
● Representing VARRAYS
● Representing Nested Tables
For information on using Oracle Objects as business components, see the following topics:
● Using Oracle Objects as Business Components

● Forward Generating Oracle Objects from Domains
● Representing an Oracle Object Type with a User-defined Domain
● Replacing an Oracle Object with a REF to a Table
Related Topics

Representing VARRAYS
Using Oracle Objects as Business Components
Forward Generating Oracle Objects from Domains
Representing an Oracle Object Type with a User-defined Domain
Replacing an Oracle Object with a REF to a Table
11-795
11-796
Representing Column Objects as Business
Components
The business component representation of Oracle Object Types depends on how the object is
defined and used. If the object is used as a column object, the business component
representation is that of a domain. To illustrate this point, see the following example:
Suppose you created the EMPLOYEE table in the database with the following SQL code:
CREATE TABLE Employee

(
EmpId Number,
Name VARCHAR2(30),
Street VARCHAR2(30),
City VARCHAR2(25),
State CHAR(2),
Zip Number
);
Instead of representing the individual address members you can create an address type that
contains the Street, City, State and Zip elements. Call this new datatype address_t. The
address_t datatype is defined as follows:
CREATE TYPE address_t AS OBJECT -- a user defined datatype

(
City VARCHAR2(25),
State CHAR(2),
Zip Number
);
The address_t datatype can now be used in place of all the individual address members. If
you were to recreate the EMPLOYEE table now with the address_t datatype it would look like
the following:
CREATE TABLE Employee

(
EmpId Number,
Name VARCHAR2(30),
Address address_t, -- note the Oracle Object datatype
);
11-797
Oracle Object Types created in this way are represented as business components domains.
These domains are automatically created when you create a default business component
project. You can edit the domain using the Domain Wizard.
Related Topics

11-798
Representing Object Tables as Business
Components
The business component representation of Oracle Object Types depends on how the object is
defined and used. If the object is created as an object table, the business component
representation is that of an entity object. To illustrate this point, see the following example:
Like the column object example, you start with an Oracle Object called address_t. The
address_t datatype is defined as follows:
CREATE TYPE address_t AS OBJECT -- a user defined datatype

(
City VARCHAR2(25),
State CHAR(2),
Zip Number
);
Instead of using the address_t type as a datatype, you create a table from the type:
CREATE TABLE Address OF address_t
In this case, all the data members of address_t make up the columns of the database table.
Access to the State attribute, for example, is through address_t.state.
Oracle Object Types created in this way are represented as business components entity
objects. You may select the entity objects to create using the Business Components Project
Wizard. You can edit the object table representation using the Entity Object Wizard.
Related Topics

11-799
11-800
The business component framework maps database types to Java types based on a
predefined type map. Nested tables are mapped as a domain, to
oracle.jbo.domain.Array. Domians for nested tables are automatically created when you
are performing reverse generation. Although you can reverse engineer a domain from a nested
table in the database, you cannot forward-generate nested tables from the framework.
You work with a nested table the same way that you work with a domain.
Nested Tables that Contain Oracle Object Types
If you have a nested table that contains Oracle Object Types, the domain for the Oracle Object
Type is created by the business components framework when you reverse engineer business
components. The nested table is represented by oracle.jbo.domain.Array. A separate
domain is created for the Oracle Object Type.
Related Topics

11-801
Using Oracle Objects and Business Components
The following information is incomplete in the beta release. Additional information will be
supplied in a future release.
Using Scoped and Unscoped REFs
There are two kinds of Refs, scoped and unscoped:
● Scoped Refs, the object pointed to is always in the table.

● Unscoped refs are used for polymorphic references.
For forward generation, unscoped Refs are not supported, nor are methods on objects, or
nested tables.
FKs and Unscoped Refs
Information to be included in a future release.
Accessing Attributes
View objects have limited support for the object.attribute scheme. If mapped as a domain, the
entire object is brought into memory, not just the required attribute.
For example:
SELECT id, address.street

FROM customer c
etc...
This won't work using business components, because you have to bring in the entire address
domain object.
UI Support
There is currently no design-time support for Oracle Objects.
Nested Tables
11-802
You cannot create a domain for nested tables.
Object Methods
Ther is no mapping between database methods and entity methods. Also, there is no support
for methods that were created on the objects.
Related Topics

11-803
Forward-generating Oracle Objects in the Database
You can create Oracle Object Types in the database by creating a business component domain
and then forward generating the database object. Forward generation of object tables from
entity objects is not supported.
To forward generate an Oracle Object Type from a new domain:
1. In the System Navigator, right click on your business component package and choose
Create Domain.
2. When the Domain Wizard opens, review the information on the Welcome page and click
Next.
3. Enter a Name and Package for the domain or accept the defaults.
4. Select the checkbox for Domain for an Oracle Object Type.
5. Do not select any items on the Available Types list, as you are creating a new one.
6. Enter the name of your new type in the Selected Type field.
7. Click Next.
8. On the Settings page, click New.
9. Provide a name in the New Domain Attribute box.
10. Select the appropriate Java type and database type for the attribute.
11. Repeat steps 8-10 until you have added as many fields as are required.
12. Click Finish.
13. In the Navigation Pane, right click on your business component package and choose
Create Databse Objects.
14. In the Create Database Objects dialog, shuttle the domain you created to the Objects to
Create list.
15. Click OK.
The domain you created is now an Oracle Object Type in the database.
Related Topics
11-804
11-805
Business Components Reference
This book presents reference information on the following topics:
● Data types
● Reserved words
● Controlling JDBC Behavior
● Controlling Diagnostic Messages
● JBO Error Messages
11-806
Business Component Reserved Words
The following table lists reserved words. Do not use these words to name your objects,
variables, or methods. Also, avoid using words that could cause name collisions in the base
class or could duplicate other objects in the container with the same name.
Reserved Word Remarks

abstract Java
ALTER SQL
AND SQL
AVG SQL
BEGIN SQL
BETWEEN SQL
boolean Java
break Java
byte Java
byvalue Java
CASCADE SQL
case Java
CAST SQL
cast Java
catch Java
char Java
CHECK SQL
class Java
clone Java method
COALESCE SQL
const Java
CONSTRAINT SQL
CONTAINS SQL
continue Java
COUNT SQL
CREATE SQL
DEFAULT SQL
default Java
DELETE SQL
11-807
DO SQL
do Java
double Java
DROP SQL
ELSE SQL
else Java
END SQL
equals Java method
EXISTS SQL
extends Java
false Java
final Java
finalize Java method
finally Java
float Java
for Java
FROM SQL
FUNCTION SQL
future Java
generic Java
getClass Java method
goto Java
GROUPBY SQL
hashCode Java method
IF SQL
if Java
implements Java
import Java
inner Java
INSERT SQL
instanceof Java
int Java
interface Java
IS SQL
java Java
11-808
KEY SQL
LIKE SQL
long Java
MAX SQL
MIN SQL
native Java
new Java
NOT SQL
notify Java method
notifyAll Java method
NULLIF SQL
operator Java
OR SQL
ORDERBY SQL
outer Java
OVERLAPS SQL
package Java
PRIMARY SQL
private Java
protected Java
public Java
REFERENCES SQL
rest Java
return Java
ROWID SQL
SELECT SQL
short Java
SQL SQL
static Java
SUM SQL
super Java
switch Java
synchronized Java
TABLE SQL
THEN SQL
11-809
this Java
throw Java
throws Java
toString Java method
transient Java
true Java
try Java
UNION SQL
UNIQUE SQL
UPDATE SQL
var Java
VIEW SQL
void Java
volatile Java
wait Java method
WHERE SQL
while Java
11-810
JDBC is often the underlying database connection protocol. You can control these JDBC
features:
● maximum open cursors
● fetch mode
● JDBC call tracing
You can specify or override the value of these properties on the Java command line or in the
Java Options field of Project Settings dialog, by selecting the current project in the Navigator
and choosing Project | Project Settings | Runner. Use the following syntax:
-Dvariable=value
For example, the following property sets the maximum number of open cursors to 10:
-Djbo.max.cursors=10
Maximum Open Cursors
jbo.max.cursors controls the maximum number of open cursors allowed for the database
connection. The default value is 50, which is the Oracle database default.
Fetch Mode
jbo.fetch.mode controls the fetch mode for view objects. Allowed values are:
Value Description
as.needed Fetch rows as needed. In other words, JDBC ResultSet and Statement
are kept open and rows are retrieved as requested. (Default)
all Fetch all rows and close the ResultSet and Statement.
When view objects are linked master-detail and there are many master rows, set
11-811
jbo.fetch.mode to all to get the best performance. Otherwise, you might run out of memory
or cursors as detail rowsets are kept open.
JDBC Calls
jbo.jdbc.trace controls tracing of business component calls to JDBC. Allowed values are:
Value Description
false Suppress JDBC tracing information. (Default)
true Output JDBC tracing information.
When this tracing is turned on (true), JDeveloper generates diagnostic messages like these:
[###] import java.util.*; // JBO-JDBC-INTERACT

[###] import java.sql.*; // JBO-JDBC-INTERACT
[###] import java.io.*; // JBO-JDBC-INTERACT
[###] public class JDBCCalls // JBO-JDBC-INTERACT
[###] { // JBO-JDBC-INTERACT
[###] public Connection conn = null; // JBO-JDBC-INTERACT
[###] public CallableStatement cStmt = null; // JBO-JDBC-INTERACT
[###] public PreparedStatement pStmt = null; // JBO-JDBC-INTERACT
[###] public Statement stmt = null; // JBO-JDBC-INTERACT
[###] public ResultSet rslt = null; // JBO-JDBC-INTERACT
[###] public static void main(String argv[]) // JBO-JDBC-INTERACT
[###] { // JBO-JDBC-INTERACT
Related topics
Tuning View Object Performance by Adjusting the Row Fetch Size, Providing Query Hints, and
Specifying Page Iteration Mode
11-812
Controlling Diagnostic Messages
Business component diagnostics can be controlled by setting various jbo.xxx system properties. By
default, the system property definitions reside in the file Diagnostic.properties in the
.\oracle\jbo\common path on the CLASSPATH.
A default version of this file is supplied in the .\lib\jbomt.zip library. You can permanently
change the default settings by extracting this file from the .zip archive, changing the values of the
properties in the file, and making it available earlier in your project's library path. The file must appear
before the library named "JBO Runtime" in the appropriate .\oracle\jbo\common subdirectory.
For a description of the properties in the Diagnostic.properties file, see Diagnostic Message
Properties. For an example of the Diagnostic.properties file, see Sample Diagnostic Properties
File.
Performing One-time Overrides
You can perform a "one-time" override of any diagnostic property by entering the appropriate value in
JDeveloper's Project's Properties dialog.
1. Select Project | Project Properties on the JDeveloper menu bar to open the project's Property
dialog. Select the Run/Debug tab.
2. Enter a new value for the system property you want to change as a command-line switch in the
Java VM Parameters field, following the Java VM's -D flag.
For example, to suppress the reporting of diagnostics, enter the value

-Djbo.debugoutput=silent in the Java VM Parameters field.
3. Click OK to close the dialog and enable your change.
Diagnostic Message Properties
The following sections describe the properties you can set in the Diagnostic.properties file. For
an example of the Diagnostic.properties file, see Sample Diagnostic Properties File.
Determining Message Routing
Syntax: jbo.debugoutput={silent|console|routing_classname}
11-813
This property determines how you want to route diagnostic messages. The routing is determined by
an implementation of the oracle.jbo.common.IDiagnostic interface. The value you give to the
jbo.debugoutput property determines which implementation of the interface to use.
● silent - suppresses diagnostic messages; implemented by

oracle.jbo.common.SilentDiagnosticImpl.
● console (default) - directs messages to the console; implemented by

oracle.jbo.common.ConsoleDiagnosticImpl.
The debugoutput property also supports a pluggable diagnostic implementation. For example, you
can write a class, anyCorp.ACDiagnosticImpl, that implements
oracle.jbo.common.IDiagnostic to provide special instructions for routing the output. You can
then pass the fully qualified class name of anyCorp.ACDiagnosticImpl to debugoutput instead
of console or silent.
Displaying the Calling Function
Syntax: jbo.logging.show.function={true|false}
The value of this property determines whether the name of the function which calls the diagnostic is
displayed. Note that displaying the function name is expensive in terms or performance. The default
value is false.
For an example of how the calling function is displayed in a diagnostic message, see Sample
Diagnostic Message.
Displaying Line Numbers
Syntax: jbo.logging.show.linecount={true|false}
The value of this property determines whether diagnostic message lines are numbered. The default
value is true.
For an example of how line numbers are displayed in a diagnostic message, see Sample Diagnostic
Message.
Setting the Logging Threshold
Syntax: jbo.logging.trace.threshold={[0-9]}
11-814
Trace messages have an integer threshold number associated with them. The range is 0-9 inclusive.
All messages currently in the system have level 3. If you have a debug build, there will be additional
messages at level 6. The default value is 3.
The value of the trace threshold property determines which trace messages will print. If the level of the
message is less than or equal to the value given to the parameter, then the message will print. If the
level of the message is greater than the parameter, then the message will not print. For example, if the
threshold value is set to 3, then messages at level 0, 1, 2, and 3 will print. Messages at levels 4, 5, or
higher will not print.
Setting the Prefix for Diagnostic Messages
Syntax: jbo.debug.prefix={prefix}
This property determines the prefix added to level 6 messages executed through debug diagnostics.
Note that debug diagnostics are available only with a debug build of the business components
product. The default value is DBG.
Displaying the Time Between Debug Calls
Syntax: jbo.logging.show.timing={true|false}
The value of this property determines whether the time between debug calls is displayed. The amount
of time is measured in milliseconds. The default value is false.
For an example of how the timing is displayed in a diagnostic message, see Sample Diagnostic
Message.
Displaying a Message's Trace Level
Syntax: jbo.logging.show.level={true|false}
The value of this property determines whether the trace level associated with a message is displayed.
Note that this property is not normally used; in release mode, all debug messages are level 3. The
default value is false.
For an example of how the trace level is displayed in a diagnostic message, see Sample Diagnostic
Message.
Viewing Diagnostic Messages While Executing in an Oracle8i Database
11-815
When business components are executing inside an Oracle8i database, its output is stored in the log
file associated with the database instance. This log file can be found at:
<ORACLE_HOME>ADMIN\<DB_SID\udump\<DB_SID>S000.TRC
To upload an updated version of the Diagnostic.properties file to the database while executing
inside an Oracle8i database, you can use the loadjava utility:
1. Set the diagnostics console option in the Diagnostic.properties file:
jbo.debugoutput=console
2. Use the loadjava utility to upload the file:
loadjava -v -r -user jbo/jbo@testserver:1521:ORCL -thin

oracle\jbo\common\Diagnostic.properties
Sample Diagnostic Message
The following is a sample diagnostic message that is issued when the message routing is set to
console mode (that is, jbo.debugoutput=console).
<3>[11] (10) RowSetHelper.getListeners Getting listeners ready...
In this sample message:
● <3> - indicates that the message was issued at trace level 3
● [11] - indicates that this is trace line number 11
● (10) - indicates that 10 milliseconds have elapsed since the last trace message
● RowSetHelper - the name of the class from which the trace message was issued
● getListeners - the name of the function from which the trace message was issued
● Getting Listeners ready ... - the text of the trace message
11-816
Sample Diagnostic Properties File
Here is a sample Diagnostic.properties file:
# ------------------------------------------------------------------------
# File: oracle.jbo.common.logging.Diagnostic.properties
# Cont: Diagnostic.properties file for DEBUG build of Business Components for Java
# Desc: This is the file used to determine the way that Diagnostic
# calls in the code are handled: all the properties below can be
# overridden by specifying then as -D switches to the java VM
# ------------------------------------------------------------------------
# Which implementation of IDiagnostic to use: console|silent|classname

# classname is the fully qualified name of a user-defined class that
# implements the IDiagnostic interface
jbo.debugoutput=console
# --------------------------------------------------
# Sample DebugOutput Line
# --------------------------------------------------
# <3>[11] (10) RowSetHelper.getListeners Getting listeners ready...
# In the above example:
# <3> - the message is issues at trace level 3
# [11] - this is trace line number 11
# (10) - 10 ms have elapsed since the last trace message
# RowSetHelper - class from which the trace message was issued
# getListeners - function from which the trace message was issued
# Getting Listeners ready ... - test of the trace message
# --------------------------------------------------
# Show calling function: false|true

jbo.logging.show.function=false
# Show a linecount as each diagnostic line is output (true|false)

jbo.logging.show.linecount=true
# Logging cutoff threshold: any trace messages with a level

# higher than this threshold will be suppressed.
# For a release build, system Diagnostic messages are at level 3
# Additionally, in a Debug build, DebugDiagnostic messages are at level 6
jbo.logging.trace.threshold=3
# Prefix string to display on DebugDiagnostic lines

# Debug build only
jbo.debug.prefix=DBG
11-817
# Show elapsed time info every call (true|false)
jbo.logging.show.timing=false
# Show level of trace statement

jbo.logging.show.level=false
# ------------------------------------------------------------------------
# end of file
# ------------------------------------------------------------------------
11-818
Business Components for Java Error
Messages
The prefix "JBO-" signifies that the following messages were generated by Oracle Business Components
for Java. All messages are listed in order by the message code number.
Each error message contains an error number, an exception type, a cause, and an action. In some cases
there may be multiple causes and/or actions.
JBO-25000: UnknownSQLTypeException
Cause: SQLType name passed to NullValue constructor is invalid.
Action: Provide a valid SQLType name. See oracle.jbo.server.OracleTypeMapEntries

for a list of valid SQLType names. Names are like "VARCHAR", "CHAR", "NUMBER", etc.
JBO-25001: NameClashException
Cause: A business component of this name already exists in the application module.
Action: Provide a different name for the business component. If you provide a null value or null string
for the name, the framework will create a unique name within the scope of the application module.
JBO-25002: NoDefException
Cause: No business component definition found with the given name in the project classpath.
Action: Provide a correct name for the business component definition. If the definition is not in the
classpath, you must include it there. Names are of the format
myProjectPackage.BusinessPackage.BusinessComponent. This error can also occur if
there is a case conflict, as when the database expects "DEPTNO" and receives "Deptno" instead.
JBO-25003: NoObjException
Cause: No business component object found with the given name in the application module.
Action: Provide a different name for the business component object or create a new business component
with the given name.
11-819
JBO-25004: InvalidDefNameException
Cause: An attempt has been made to associate a definition name with a type for which it is not valid.
Action: The name should be a valid Java identifier with no spaces or punctuation. Names are of the
format myProjectPackage.BusinessPackage.BusinessComponent
JBO-25005: InvalidObjNameException
Cause: An attempt has been made to associate a business component name with an object for which it is
not valid.
Action: The name should be a valid Java identifier with no spaces or punctuation. Names are of the
format myProjectPackage.BusinessPackage.BusinessComponent
JBO-25006: InvalidParamException
Cause: The parameters passed to a business component method are invalid.
Action: See the Javadoc for the method that throws this exception. Expand the call-stack for the correct
parameters. E.g., DBTransactionImpl.executeCommand() throws this exception when
command parameter is null or an empty String.
JBO-25007: InvalidOperException
Cause: Resetting row validation for a default RowIterator of a view object or a RowSet is not permitted.
Action: Reset the RowValidation flag for the RowSet or view object. This will create another iterator for
the RowSet or view object to navigate to another row without validating.
Cause: An attempt has been made to remove a view object that is participating in a view link.
Action: Remove the view link before removing the view object.
JBO-25009: oracle.jbo.domain.DataCreationException
Cause: A domain object could not be created with the given value. Either a domain constructor that
accepts the given value does not exist, or there is no conversion method in the domain object for the
given value type, or the domain's constructor threw an unexpected exception.
11-820
Action: Confirm that the value being passed is valid with respect to the domain-type being created. E.g.,
passing a String value like "One" to the oracle.jbo.domain.Number constructor will throw this
exception.
JBO-25010: oracle.jbo.domain.DomainValidationException
Cause: Validation failed with the given value in a domain constructor. This exception is thrown in the
validate() method of a domain type.
Action: Provide a valid value for the domain type.
Cause: An attempt has been made to invoke an invalid navigation method for a forward-only view object
or RowSet.
Action: Either remove the forward-only setting for the view object or RowSet, or do not invoke
navigation methods other than next() on the forward-only view object or RowSet.
Cause: The client has attempted to locate view rows that has the given entity row as the primary entity
row. However, it has been discovered that the entity row's entity definition does not match the entity
definition of the view object's primary entity object base.
Action: The entity row used to locate view rows must be based on the same entity definition.
JBO-25013: TooManyObjectsException
Cause: Attempting to add a new entity to the cache with the primary key the same as an existing entity.
This exception is thrown when uniquing a newly fetched/created entity with the cached set of entities.
Action: The primary key value may not be unique for this entity-type. Fix by adding more attributes to
the Key definition for this entity type, so that each row for this entity is uniquely identifiable. Or fix the
primary key value so that this entity has a unique key identifier.
JBO-25014: RowInconsistentException
Cause: The database value does not match the cached value for this entity object. This could happen
when another user or operation has committed modifications to the same entity-row in the database. This
11-821
exception can also be thrown if the equals() method on one of the domain-type attributes in the entity
fails.
Action: Choose from the following options:
● Verify that another user or operation has not modified the same row in the database. If this entity
has attributes of a domain type verify that the equals() method on these domains do not fail
when comparing the existing cached value with the newly fetched value.
● For any attributes/columns that are updated by the database, modify the entity attribute definition
by selecting Refresh after update on the Attribute Settings page of the Entity Object Wizard.
● Use view.executeQuery() frequently, especially after any operations that result in data
being changed.
Cause: Attempting to execute a query for a view object or RowSet after closing or removing the view
object or RowSet.
Action: Verify that the view object or RowSet is not removed or closed.
JBO-25016: ReadOnlyViewObjectException
Cause: Attempting to modify data for a view object which is declared to be read only. This includes
creating a new row for this view object, removing a Row, or modifying attributes of a ViewRow for this
view object.
Action: Create a view object with ReadOnly flag set to false to modify the data.
JBO-25017: RowCreateException
Cause: An unexpected exception occurred while creating a new entity instance.
Action: The entity may not have a public default constructor. Fix the cause for InstantiationException or
IllegalAccessException that appears in the details of this exception.
Cause: An unexpected exception occurred while creating a new ViewRow instance.
Action: The ViewRow may not have a public default constructor. Fix the cause for
InstantiationException or IllegalAccessException that appears in the details of this exception.
11-822
JBO-25019: RowNotFoundException
Cause: Attempting to lock a non-existing row in the database. This could occur when the cache has an
entity which was subsequently deleted from the database by another user or operation.
Action: Remove the current entity from the entity-cache by calling remove(). Or re-synchronize the
cache with the database, by rolling-back the current transaction or by committing the existing set of
changes and then dropping the entity-cache.
Cause: Attempting to find a referenced entity in the ViewRow failed due to a changed foreign-key value.
Action: Provide a valid foreign-key value or remove the current one.
Cause: A domain object could not be created with the given value. Either a domain-constructor that
Action: Confirm that the value being passed is valid with respect to the domain-type being created. E.g.,
passing a String value like "One" to oracle.jbo.domain.Number constructor will throw this
exception.
JBO-25022: ViewLinkAlreadyExistsException
Cause: Attempting to set the Master RowSet for this RowSet more than once.
Action: Do not invoke setMasterRowSetIterator more than once on a RowSet.
JBO-25023: oracle.jbo.domain.GenericDomainException
Cause: An expected domain exception occurred.
Action: Contact BC4J Technical Support.
JBO-25024: JboException
Cause: Attempting to use an obsolete TypeMap constructor.
11-823
Action: Verify that the TypeMaps in use for this version of framework is compatible. See example
TypeMaps in oracle.jbo.server.OracleTypeMapEntries
JBO-25025: ReadXMLException
Cause: An error occurred during reading the XML data for a view object. This exception may contain
other ReadXMLExceptions.
Action: Fix the contained Row- or Attribute-level exceptions in the details for this exception.
JBO-25026: RowReadXMLException
Cause: An error occurred during reading the XML data for a ViewRow. This exception may contain
other ReadXMLExceptions for contained RowSets or Attributes.
Action: Fix the RowSet- or Attribute-level exceptions in the details for this exception.
JBO-25027: AttributeReadXMLException
Cause: An error occurred during reading the XML data for an attribute of a ViewRow. This exception
may contain other JboExceptions thrown from the set method for this attribute.
Action: Fix the JboException in the details for this exception.
Cause: A domain object could not be created with the given value. Either a domain-constructor that
Action: Confirm that the value being passed, is valid with respect to the domain-type being created. E.g.,
passing a String value like "One" to oracle.jbo.domain.Number constructor will throw this
exception.
Cause: The named data class (may be a domain) could not be found.
Action: Make sure that the data class is accessible from the CLASSPATH and is a valid data class.
JBO-25030: InvalidOwnerException
11-824
Cause: This entity is a detail in a composition association and no container entity could be found. This
could occur while creating a new entity instance by passing a non-existing master key value, or when
updating the foreign-key value in this entity and there is no master entity with that foreign-key value.
Action: Provide a valid foreign-key value to the create() method or setAttribute() method so
that an appropriate master row is found for this entity.
Cause: The client has attempted to access an attribute of a view which is mapped to an entity row, but
the corresponding entity row is null. If the view object consists of multiple entity object bases and if the
secondary entity object bases are reference-only, the entity rows may be null if the foreign key linking
the primary entity to the secondary entity object is null.
Action: In such a situation, the user is not allowed to access attributes of missing entity rows.
JBO-25032: JboSerializationException
Cause: Failure trying to make the application module state or transaction state passive.
Action: The passivation target store (Database, File or Memory) may have reported an exception. See
the details of this exception for errors from the target store.
JBO-25033: JboSerializationException
Cause: Trying to activate the application module state or transaction state failed.
Action: The passivation target store (Database, File or Memory) may have reported an exception. See
the details of this exception for errors from the target store. The given ID (in case of activation) may be
invalid/not found.
Cause: The client has attempted to locate a row with a stale row handle. This error may be raised if the
client tries to take a row out of one query collection and use its handle to find a row in another query
collection. Note that if the client calls executeQuery on a RowSet, it may receive a new query
collection. Thus, you may get this error if the client retrieves a row from a RowSet, takes its row handle,
calls executeQuery(), and then tries to locate the row using the saved handle.
This exception may also be raised if a row reference is used across transaction boundaries and the row
11-825
handle has become stale and hence the corresponding row cannot be found.
Action: Make sure that your row handle is not stale. Perhaps, find the row again using its primary key
before attempting to act on the row.
Cause: An application attempted to change an application module's passivation store after it had been
initialized.
Action:The passivation store (Database, File or Memory) may only be initialized once. If the customer
application logic has not specified a passivation store when the serialization framework is invoked, the
passivation store is initialized by the BC4J framework. Check the client application logic for invocations
of ApplicationModuleImpl.setStoreForPassiveState which are invoked after the
application module passivation store has been initialized.
JBO-25036: InvalidObjAccessException
Cause: An application invoked an object operation that is not supported in the object's current state.
Action: Remove the invalid operation invocation or provide exception handling logic.
JBO-25037: NoObjException
Cause: This row set is a detail in a master-detail relationship, but it is missing a master row set iterator.
Most likely, this occurred because a master row set iterator is removed through a call to
removeMasterRowSetIterator() and has not be replaced with an appropriate one.
Action: Call setMasterRowSetIterator() to provide a valid master row set iterator.
JBO-25038: InvalidParamException
Cause: The parameters passed to a business component method are invalid.
Action: Refer to error message for EXC_INVALID_PARAMETER (JBO-25006) for info. Difference
between this error msg and EXC_INVALID_PARAMETER is that this one does not include a reason. In
general, we recommend using EXC_INVALID_PARAMETER instead of
EXC_INVALID_PARAM_NO_EXPL_GIVEN.
11-826
Cause: The client attempted to work with the current row of a row set iterator, but the iterator has no
current row.
Action: Position the iterator to the correct row and perform the operation.
Cause: The row containing a large object was not locked before attempting to call a method on the large
object that could potentially change the data of the object.
Action: Lock the row before attempting to get an output stream or write into a large object domain
instance.
JBO-25200: NotConnectedException
Cause: The application module is not connected to the database.
Action: Provide a valid set of connection credentials to connect to a database.
JBO-25201: AlreadyConnectedException
Cause: Trying to re-establish a database connection.
Action: Disconnect the current database connection before trying to re-establish the JDBC connection.
Cause: Attempting to call a method that is either not implemented or not supported.
Action: This method is not available on the called object. E.g. setAttribute() in
oracle.jbo.Key class is not implemented and will throw this exception.
JBO-25222: ApplicationModuleCreateException
Cause: There are a number of reasons the application module could not be created:
● If your business components are deployed in local mode, they may not be on the classpath.
● You may have unresolved classes on the server.
● You may not have granted Java2 permissions.
● Your Java pool size may be too small.
11-827
Action: Depending on the cause, chose from the following actions:
If your business components are deployed in local mode, they may not be on the classpath.
If this is the cause of the error, the exception will usually be followed by a different exception, JBO-
25002: NoDefException. If this occurs, make sure you've done all of the following:
1. Made a library for your business components.

2. Added a library to your client's project properties.
3. Included the library on the "libraries" page when you created a deployment profile for your client
(whether your client was a web application or a command-line application).
4. Copied the library with your client to the target platform (whether your client was a web
application or a command-line application).
5. Included all the files you copied (including the library) when you set the classpath on the target
platform.
You may have unresolved classes on the server.

Try the following procedure to resolve any unresolved classes on the database.
1. In the System Navigator, right-click the JDBC connection you used to deploy the Business
Components project.
2. Choose Invoke SQL*Plus from the context menu.
3. Copy and paste the following SQL*Plus script into the SQL*Plus window.
set termout off
set echo off
set heading off
set pages 999
set linesize 2000
set feedback off
select 'alter java class "'||
replace(dbms_java.longname(object_name),'/','.')||'" resolve;'
from user_objects
where object_type='JAVA CLASS'
and status = 'INVALID'
spool C:\temp\resolve.sql
/
spool off
set echo on
set termout on
@C:\temp\resolve.sql
You may not have granted Java2 permissions.

If this is the cause of the error, there will be permissions errors in the database trace file. To correct the
11-828
problem, see the help topic "Granting Permissions on a Business Components EJB" for information on
granting Java2 permissions.
Note: The location of the database trace file varies from installation to installation, but in a default
Windows NT installation, the file will be in the directory ORACLE_HOME\admin\orcl\ udump and
will have the form orcl????.trc.
Your Java pool size may be too small

Business Components for Java deployed as EJBs work best with a Java pool size of at least 50MB. Edit
your init.ora file and check the java_pool_size parameter. If it is under 50MB, change it,
restart your database, and try your connection again.
Cause: When business components are running inside JServer, only one root application module may be
created. This is because JServer (already) provides one transaction context.
Action: It is illegal to attempt to create multiple root transactions when running inside JServer.
Cause: Trying to retain the application module state during a transaction disconnect failed.
Action: The disconnect and retain application module state target requires that no database state exist
before the transaction connection is closed. Examples of database state include open database cursors in
non-forward only view objects, database locks, and uncommitted database changes. The client should
clean up this state by fetching or resetting any open view objects and committing any uncommitted
changes.
Cause: This application module definition contains recursive references to child application modules.
For example, if application module definition appMod1 contains a child application module of appMod2,
and appMod2 contains appMod1, this error will be raised.
Action: Remove recursive application module definition references.
Cause: The user has attempted to create a view link (in an application module) that will result in a
recursive loop of view links. The error message should show a chain of recursive master-detail
11-829
relationships.
Action: If a static view link is causing the recursion, remove the view link from the application module.
If a dynamic view link is causing the recursion, remove the code that creates the recursive view link.
Cause: While traversing the parenthood chain for application modules, a child application module was
found with no container (parent) application module.
Action: If this application has added custom business component classes, it may be that the application
code is attempting to access a child application module before it is fully initialized. If this is not the case,
this error probably represents some internal error in BC4J framework, in which case contact BC4J
Technical Support.
Cause: A business component is found without a container (parent) application module.
Action: If this application has added custom business component classes, it may be that the application
code is attempting to access a business component before it is fully initialized. If this is not the case, this
error probably represents some internal error in BC4J framework, in which case contact BC4J Technical
Support.
Cause: A dirty entity cache cannot be cleared. The client asked to clear an entity cache but some rows in
the entity cache have been modified. An entity cache with modified rows cannot be cleared.
Action: Do not attempt to clear an entity cache with modified rows in it.
JBO-25305:
Cause:
Action:
JBO-25306: JTPersistenceException
Cause: Could not persist a design-time attribute into the XML file.
11-830
Action: Identify the offending design-time attribute and contact BC4J Technical Support.
JBO-25306: JTPersistenceException
Cause: XML file is not open.
Action: Contact BC4J Technical Support with how you ran into the problem.
Cause: Attempting to load metadata objects failed. It may have unexpected data or the XML data may be
corrupt.
Action: Verify that the XML metadata for various components is valid.
JBO-26001: NoXMLFileException
Cause: Could not open the named XML file for reading.
Action: Try the following:
● Make sure that the file is present. In particular, if the file is to be found in a Zip/JAR file, make
sure that the Zip/JAR file is included in the CLASSPATH.
● This error is also reported if the name of the XML file does not match the object Name specified
in the XML file. If the file system support case insensitive file names (e.g., Windows NT), make
sure that the file name matches the object Name in the XML file in case-sensitive fashion.
● For a JPX file, this error is reported if the JPX file is missing the JboProject XML tag. Check
the JPX file to make sure that the valid tag is in there.
● One XML file may be extending another XML file (specified by the Extends element in this XML
file). This error is reported if the base XML file is not found.
● When loading the XML file for a package (JboPackage tag), this error is reported if some
unexpected error occurs while loading a containee.
In all of the above cases, a more descriptive message may be printed on Diagnostic. If you are not seeing
Diagnostic messages, you can run your application with Diagnostic turned on, as in "java -
Djbo.debugoutput=console ...", to see Diagnostic messages.
JBO-26002: PersistenceException
Cause: Some XML parsing exception (oracle.xml.parser.v2.XMLParseException) was

thrown.
11-831
Action: The XMLParseException information is output to Diagnostic. If you are not seeing diagnostic
messages, you can run your application with diagnostic turned on, as in "java -
Djbo.debugoutput=console ...", to see diagnostic messages.
Cause: An error occurred while loading entity object definitions. An attribute index in the Java class for
this entity has a mismatch with the index in the definition, or an attribute index is missing in the Java
class.
Action: Ensure that the indices of attributes in the definition for this entity match the indices defined in
the Java class for this entity.
Cause: An attempt was made to set the base definition of another definition object, e.g., setting B's base
definition to A (i.e., B Extends A). However, A already extends B. Setting a recursive (circular)
subclassing relationship among definition objects is illegal.
Action: Review your subclassing hierarchy of your definition objects and correct errors.
Cause: The fetch mode specified in the view definition XML file is not valid.
Action: Check the content of the XML file for the view definition. Look for an XML element named
"FetchMode". Make sure that the value for that element is valid. Valid values are:
"FETCH_AS_NEEDED", "FETCH_ALL", and "FETCH_DEFAULT".
Cause: The fetch size specified in the view definition XML file is not valid.
"FetchSize". Make sure that the value for the element is a positive integer.
Cause: The maximum fetch size specified in the view definition XML file is not valid.
11-832
"MaxFetchSize". Make sure that the value for the element is a non-negative integer, or
"MAX_FETCH_UNLIMITED", or "MAX_FETCH_DEFAULT". A MaxFetchSize of 0 is the same as
MAX_FETCH_UNLIMITED.
Cause: A problem is found in resolving a view link definition or an association. In case of a view link,
this error may be caused by the fact that the source or destination view object cannot found. Or, if the
view link ends have attribute names, this error may indicate that the named attributes cannot be found.
Similarly, for an association, this error indicates that either source or destination entity object or
attributes involved in the association cannot be found.
Action: Make sure the XML definition for the view link/association has correct view object/entity
object/attribute names.
Cause: This error occurs if the application uses meta object serialization files (.ser files) instead of XML
files. It indicates that after the .ser file is deserialized, the top level object returned from deserialization is
not an instance of oracle.jbo.server.xml.JboElementImpl.
Action: This probably means that the .ser file is corrupt.
Cause: Entity attribute name in the view definition XML file is invalid or is not found.
Action: Make sure that the entity name is valid. Also, check to make sure that the named attribute does
exist in the entity object. The entity object is identified by the EntityUsage element.
Cause: Attribute definition found in XML file is invalid. It is missing SQLType value.
Action: Correct the error in the XML file.
Cause: The view link definition in the XML file is missing either the source or destination view link end.
For a view link XML file, two elements named ViewLinkDefEnd should be found.
11-833
Action: Correct the error in the XML file.
Cause: Meta object name passed for lookup is invalid.
Action: Normally, the meta object name is a dot-separated name of the meta object. For an entity object
named Emp in package1.example, the correct name would be package1.example.Emp. To correct,
locate where the invalid name is coming from (could be meta object names mentioned in an XML file, or
the name of the project, etc.) and change the name to a valid one.
Cause: A view definition does not include a discriminator column of an entity base. If an entity base has
discriminator columns, it must include all of them in the view object's attribute mapping.
Action: Change the view definition to include discriminator column attributes.
Cause: You cannot set customer query (calling setQuery()) on a view object if it is the detail view
object in a master detail view link.
Action: Do not call setQuery() if the view object is a detail.
Cause: An association definition in an XML file is invalid. In particular, this error means that either of
the two association ends ("AssociationEnd" elements in the XML file) are missing "Attributes", which
lists source or destination attributes.
Action: Correct the error(s) in the XML file.
Cause: An attempt was made to post a row with no attribute set. Some databases (in particular Oracle)
do not allow an INSERT statement with no VALUE specified.
Action: Set some attributes on the row before attempting to insert it into the database.
11-834
Cause: Attempting to remove a master which has detail entities. In the case of a composition, a master
cannot be removed if it has details.
Action: Remove all the details of this master by accessing the details through an association and
removing all of them.
Cause: The application code tried to take a row from one row set (or view object) and insert it into
another row set (view object). In response, the framework will make a "copy" of the row in the new row
set. This new row will share references to the underlying entity objects. However, if the source and
destination row sets do not share any entity object bases at all, this operation will fail as it does not find
any entity rows to share.
Action: When attempting to take a row from one row set and insert into another, make sure that they
share at least one entity object base.
Cause: A NullPointerException was thrown while parsing an XML file. A possible cause for this is that
the DTD file is missing (oracle.jbo.dtd.jbo*.dtd).
Action: Make sure the appropriate DTD file is present.
JBO-26022: CustomClassNotFoundException
Cause: Custom class could not be found and loaded. The custom class may be for a component (e.g.,
view object), a definition (e.g., view definition), or a row (e.g., view row, entity row).
Action: Make sure that the named class is reachable from the CLASSPATH. The detail exception (if
present) will give you more specific reasons why the attempt to locate and load the custom class failed.
JBO-26023: CustomClassNotFoundException
Cause: Custom class was found and loaded, but it is invalid in that it is not assignable to a framework
(super) class.
Action: Make sure that the custom class subclasses the appropriate framework (super) class.
11-835
Cause: An error occurred while creating initial context. This error usually carries a detail exception
which will give further information on the cause of the error.
Action: If BC4J is running inside JServer, make sure that the database user (schema) has the
setContextClassLoader permission. To grant this, the database system administrator can invoke the
following PL/SQL procedure:
EXEC DBMS_JAVA.GRANT_PERMISSION('&&1',
'SYS:java.lang.RuntimePermission', 'setContextClassLoader', null);
Cause: An error occurred while trying to get System properties. Specifically, System.getProperties() call
failed.
Action: If BC4J is running inside JServer, make sure that the database user (schema) has the proper
property permission. To grant this, database system can invoke the following PL/SQL procedure:
EXEC DBMS_JAVA.GRANT_PERMISSION('&&1',
'SYS:java.util.PropertyPermission', '*', 'read');
Cause: An error occurred while trying to get load properties.
Action: Check to see if the named properties file contains valid Java properties.
Cause: While initializing a view row, the system found an entity object base with discriminator column
attributes. However, the discriminator column values coming from the view row do not match any of the
entity objects (the entity for the entity object base or any of its extended entities).
Action: Make sure that the view row's discriminator column values match one and only one entity
object.
Cause: A view definition does not include a primary key attribute of an entity base. When a view object
uses an entity as one of its entity bases, it must include all primary key attributes of the underlying entity
object.
11-836
Action: Change the view definition to include all primary key attributes.
JBO-26030: AlreadyLockedException
Cause: This row has already been locked by another user or transaction.
Action: Try locking the row again and the operation should succeed after the other user or transaction
has released the lock.
JBO-26041: DMLException
Cause: Some database error occurred while posting (writing) an entity to the database. This error
normally carries a detail exception from the database which will give further information about the
database failure.
Action: Look at the details of the exception and address the database problem.
Cause: A database failure occurred while trying to generate an object ID (OID) and object reference
(REF). When a new row is created on an entity which maps to an Oracle object table, an OID and REF
for the new row are generated. This executes a SQL statement like select a.oid, make_ref(,
a.oid) ... Somehow, this statement is failing.
Action: Check the following:
● Are you using the right version of Oracle database?

● Is the table in question an object table?
This error normally carries a detail exception from the database, which will give further information
about the database failure. Take a look at the detail exception and address the database problem.
Cause: An attempt was made to generate an object ID (OID) and/or a reference (REF) on a database
system that does not support Oracle objects.
Action: Do not try to create OID or REF on a database system that does not support Oracle objects.
11-837
Cause: The application tried to get an estimated row count (getEstimatedRowCount()) on a row
set. While building the appropriate query statement, executing it, and retrieving the estimated count, an
error occurred. This error is accompanied by the SQL statement that caused the error. Also, it normally
carries a detail exception from database, which will give further information about the database failure.
Action: Take a look at the SQL statement and the detail exception and address the database problem.
Cause: A database error occurred while trying to generate an object ID (OID) from the primary key. This
operation is valid only if the table in question is an object table and if the table specifies that the
reference (REF) is PK based.
Action: Check the following:
● Are you using the right version of Oracle database?

● Is the table in question an object table?
● Does this object table use a PK-based REF?
This error normally carries a detail exception from database which will give further information about
the database failure. Take a look at the detail exception and address the database problem.
Cause: A SQLException occurred while trying to register a JDBC driver.
Action: Fix the underlying SQLException.
Cause: A SQLException occurred while trying to open a JDBC connection.
Cause: A SQLException occurred while trying to close a JDBC connection.
11-838
Cause: A SQLException occurred while trying to close a JDBC connection.
Cause: A SQLException occurred during the commit phase of this transaction.
Cause: A SQLException occurred during the rollback phase of this transaction.
Cause: An exception occurred while adding a JDBC connection to a pool that was already full.
Action: Modify the class that is using the pool to check the pool size before adding a new connection to
the pool.
Cause: The user attempted to return a connection to a pool that was not responsible for managing that
connection.
Action: Modify the class that is using the pool to ensure that the connection belongs to the pool before
returning the connection to the pool.
Cause: A client request was timed out while waiting for a connection to be returned to the pool.
Action: Increase the maximum pool size in order to accommodate 2x the maximum expected active
request size.
11-839
Cause: A SQLException occurred while setting up metadata JDBC statement.
Action: Fix the underlying SQLException. There might be a datatype mismatch between the attributes of
the view object and columns in the SQL for it.
Cause: An unexpected exception occurred while executing the SQL to fetch data for an entity instance or
lock it.
Action: Fix the cause for the SQLException in the details of this exception.
JBO-26081: SQLDatumException
Cause: A SQLException occurred when converting data from JDBC to

oracle.jbo.domain.Struct attributes.
Action: Fix the conversion errors as suggested in SQLException.
JBO-26100: AfterCommitException
Cause: An exception occurred in the afterCommit notification phase of the transaction.
Action: Verify the exception in the details of this exception. Fix the failing afterCommit()
overridden methods in the entities or transient TransactionListener objects registered with the transaction
to listen into the commit/rollback cycle.
JBO-26101: AfterPostException
Cause: An exception occurred in the afterPost phase of the transaction.
Action: Verify the exception in the details of this exception. Fix the failing afterPost() overridden
methods in the entities or transient TransactionPostListener objects registered with the transaction to
listen into the post cycle.
JBO-26102: AfterRollbackException
Cause: An exception occurred in afterRollback notification phase of the transaction.
Action: Verify the exception in the details of this exception. Fix the failing afterRollback()
overridden methods in the entities or transient TransactionListener objects registered with the transaction
11-840
to listen into the commit/rollback cycle.
JBO-27001: ReadOnlyAttrException
Cause: This association attribute is marked readonly.
Action: Cannot modify the value of the association attribute as it is marked readonly.
JBO-27002: AttrSetValException
Cause: A custom validation rule failed to validate an attribute value.
Action: Fix the attribute value so that it passes the custom validation rule.
JBO-27003: ValidationException
Cause: Modified or new entities in this view object failed to validate.
Action: Fix the failing entity values and revalidate the view object.
Cause: Attempting to modify a read-only entity-attribute.
Action: Do not modify a readonly attribute value.
Cause: Modified or new entities within this application module or nested application module failed to
validate.
Action: Fix the failing entities and then re-validate this application module.
JBO-27006: AttrValException
Cause: An attribute cannot be found by the given name during validation.
Action: Entity metadata could be corrupt as there is an attribute which is to be validated but no definition
could be found for that attribute in the metadata.
11-841
Cause: Attempting to validate a ViewRow failed.
Action: Fix the failing entities or attributes as found in the details of this exception.
Cause: Attempting to modify a ViewRow attribute that is readonly
Action: Either change the Updateable flag for the View Attribute or do not attempt to update readonly
attributes.
Cause: Attempting to validate entities and attributes failed during validation of buffered attributes in
Deferred Validation mode. (Not available in 3.x)
Action: Fix the failure cases.
JBO-27010: ValidatonException
Cause: For strings, the length of the string value provided for an attribute is more than the max-length
this attribute expects. For Numeric values, the length of the value (in string form) is more than what the
attribute expects.
Action: Fix the attribute value with respect to the precision and scale information for the failing attribute.
Cause: A validation rule for an attribute failed either due to an unexpected exception in validating the
attribute with that rule, or due to failure in evaluating the NOT operation on the rule.
Action: Fix the attribute value so that it validates against the failing rule.
Cause: The custom method validator attached to an entity returned false, indicating a failure in the
validation for that entity.
Action: Fix the cause for failure in the custom validation method for this attribute.
11-842
Cause: The custom method validator attached to an attribute returned false indicating a failure in
validation for that attribute in the custom method.
Action: Fix the cause for failure in the custom validator method for this attribute.
JBO-27014: AttrValException
Cause: The attribute value cannot be null as it has been marked mandatory.
Action: Provide non-null values for mandatory attributes.
Cause: In validating a master, some child entities were found that could not be validated. This occurs
only in the case when there is a composition association between the master and detail entities.
Action: Fix the attribute values in the child entities so that they are valid when the child entities are
validated by the master
JBO-27016: InvalidAttrKindException
Cause: An unexpected attribute kind found in the definition for a view object.
Action: Fix the attribute kind information in the xml-metadata definition for attributes in this view
object.
JBO-27017: KeyNotFoundException
Cause: While loading the metadata definition for this entity, there was no attribute marked as the
primary key.
Action: Set at least one attribute as the primary key for this entity type, so that entities of this type can be
uniquely identified.
Cause: The type of attribute value provided as an argument to the set() method for this attribute is not
an instance of the Java type that this attribute expects.
11-843
Action: Convert the argument to a proper Java type, such that it is an instance of the Java type that this
attribute expects.
JBO-27019: AttrGetValException
Cause: An unexpected exception occurred in setAttribute method. Getter methods should throw a
subclass of JboException so that custom exception messages are thrown/shown to the caller. This
exception could also be thrown if the getter is not a public Java method.
Action: Do not throw any exception other than sub-classes of JboException from any business logic
code in the getter method for an attribute. Also verify that the getter method is a public Java method.
Cause: An unexpected exception occurred in setAttribute method. Setter methods should throw a
subclass of JboException so that custom exception messages are thrown/shown to the caller. This
exception could also be thrown if the setter is not a public Java method.
Action: Do not throw any exception other than sub-classes of JboException from any business logic
code in the setter method for an attribute. Also verify that the setter method is a public Java method.
JBO-27021: AttributeLoadException
Cause: An unexpected exception occurred during fetching values from a JDBC result set into an
attribute for a row object. There could be conversion errors between the return type from JDBC for the
attribute and its Java type.
Action: Verify that the JDBC-SQL type and Java type for the attribute are compatible. Fix any
conversion errors or domain exceptions that are in the details of this exception.
JBO-27022: AttributeLoadException
Cause: An unexpected exception occurred during fetching values from a JDBC result set into an
attribute for a row object. There could be conversion errors between the return type from JDBC for the
attribute and its Java type.
Action: Verify that the JDBC-SQL type and Java type for the attribute are compatible. Fix any
conversion errors or domain exceptions that are in the details of this exception.
JBO-27023: DeferredTxnValidationException
11-844
Cause: An unexpected exception occurred during validating changes in a transaction.
Action: Verify the details for DeferredRowValidationException and fix those errors.
JBO-27024: DeferredRowValidationException
Cause: An unexpected exception occurred during validating a row.
Action: Verify the details for DeferredRowValidationException and fix those errors at the row level. The
details can also contain DeferredAttrValidationExceptions which needs to be fixed as well.
JBO-27025: DeferredAttrValidationException
Cause: An unexpected exception occurred during validating an attribute of a row.
Action: Verify the details for JboExceptions and fix those errors at the row level.
JBO-27101: DeadEntityAccessException
Cause: Trying to refer to an invalid/obsolete entity. This could occur if some business logic has held on
to an entity reference which was removed and the transaction has been posted or committed. It could also
occur if a reference entity has been removed from the cache and any ViewRow is attempting to access it.
Action: Use findByPrimaryKey to find a valid entity of the desired key instead of holding on to a
reference to an entity instance.
JBO-27102: DeadViewRowAccessException
Cause: Trying to access a ViewRow which is part of an obsolete/invalid collection. This could happen if
a reference to the ViewRow is held by some business logic while the containing view object was
removed.
Action: Find the referenced ViewRow either by re-querying or using findByKey methods to get a valid
reference to the ViewRow.
JBO-27120: SQLStmtException
Cause: Failed to execute a query. This could occur when trying to execute a query for a SQLValue
domain class or a Sequence domain.
Action: Fix the cause for the SQLException thrown by JDBC found in the details of this exception.
11-845
Cause: Failed to execute a SQL statement.
Cause: Failed to prepare a JDBC PreparedStatement.
Cause: Failed to prepare a JDBC CallableStatement.
Cause: Failed to create a JDBC Statement object with the given set of parameters.
Cause: Failed to find a java type for a column-type in the given dynamic ViewObject query.
Action: Either provide a typemap that maps the selected columns in the query or leave out the erring
column-type from the query.
Cause: When using global transactions you cannot use the transactional datasoource for acquiring the
internal connection. Action: Explicitly specify the jdbc url that should be used for creating the internal
connection by setting the
oracle.jbo.common.PropertyConstants.INTERNAL_CONNECTION_PARAMS property
JBO-28000: PCollException
11-846
Cause: The client specified a custom persistent collection through the jbo.pcoll.mgr property.
However, the class specified could not be located or loaded.
Action: Make sure that the name specified for jbo.pcoll.mgr is for a valid class name. The class
name should be fully qualified with the package name. A special keyword None represents no persistent
collection manager, i.e., no spilling to disk will occur.
Cause: An error occurred while attempting to get a JDBC connection for persistent collection
management.
Action: Make sure that the database connection URL is correct. The detail to this exception will give
further information on the problem.
Cause: An error occurred while creating "persistent collection control table." Normally, the control
table's name is PCOLL_CONTROL.
Action: Check to make sure that the connection has appropriate authority to create a table. The detail to
this exception will give further information on the problem.
Cause: An unexpected error occurred while attempting to delete the persistent collection control row.
Action: Look at the details of this exception for further information on the problem and how to address
it.
Cause: An error occurred while trying to lock the persistent collection control row. This error is thrown
in two situations:
● An unexpected database error occurred while attempting to lock the row.

● After the persistent collection manager committed changes to database, it tried to lock the control
row. Between the time of commit and lock attempt, another user somehow managed to lock the
row and not release it within a set time. In this case, the detail will be null.
Action: In the first case, see the details of this exception for further information on the database problem.
11-847
In the second case, make sure that no other user locks the control rows outside the Business Components
framework.
Cause: An unexpected error occurred while attempting to update the persistent collection control row.
it.
Cause: An error occurred while attempting to create a database table to store persistent collection
material.
it.
Cause: An unexpected error occurred while attempting to commit persistent collection changes.
it.
Cause: An unexpected error occurred while attempting to get the system date from the database. For the
Oracle persistent manager, the SQL statement used for this would be "select sysdate from dual".
it.
Cause: An unexpected error occurred while passivating objects into the persistent store. An exception
may have been thrown during serialization.
it.
11-848
Cause: An unexpected error occurred while activating objects from the persistent store. An exception
may have been thrown during deserialization.
it.
Cause: An unexpected error occurred while inserting a passivation row into the persistent store table.
it.
Cause: An unexpected error occurred while updating a passivation row in the persistent store table.
it.
Cause: An unexpected error occurred while deleting a passivation row from the persistent store table.
it.
Cause: An unexpected error occurred while retrieving a passivation row from the persistent store table.
it.
Cause: The client attempted to retrieve a row in a persistent collection by an id, but the by-id access is
not enabled on the persistent collection.
11-849
Action: Enable by-id access by calling PCollection.enableIdAccess.
Cause: The client attempted to retrieve a row by an id, but the id value is invalid. The id must be greater
than 0.
Action: Give a valid id.
Cause: While attempting to activate an object of a given id, an internal integrity problem was found. In
particular, a node which was thought to be passivated was found to be active.
particular, a child node/element expected to be found in a node is missing.
Cause: An unexpected error occurred while deleting all passivation rows from the persistent store table.
it.
particular, the root node of the persistent collection is no good. It is either (1) null, (2) has younger or
older sibling, or (3) has a parent node. None of these should apply to the root node.
JBO-28100: ResourcePoolException
Cause: Either the JDBC connection pool or the application pool were unable to create a new pooled
11-850
JDBC connection or application module.
Action: If the exception details indicate that an exception occurred while creating a JDBC connection
then check the JDBC connection description to ensure that it references a valid, live database instance.
If the exception details indicate that an exception occurred while creating an application module then
check the application module configuration to ensure that it references a valid, live application server and
application application module class.
Cause: The application attempted to mark a pooled resource which has already been available in the
resource pool as available.
Action: Remove the application logic that invokes

{@link oracle.jbo.pool.ResourcePool.setAvailable(Object)}, or move the application logic such that it
occurs only once before the resource is made available.
Cause: A client request was timed out while waiting for a resource to be returned to the resource pool.
Action: Increase the maximum resource pool size in order to accommodate the maximum expected
active request size. If the exception details indicate that the exception was thrown while waiting for an
application module in the application pool then the maximum pool size may be increased with the BC4J
property, jbo.ampool.maxpoolsize. If the exception details indicate that the exception was thrown while
waiting for a JDBC connection in the BC4J JDBC connection pool then the maximum pool size may be
increased with the BC4J property, jbo.maxpoolsize.
Cause: A pool request was made for a resource that does not belong to the pool.
Action: Ensure that the pool request is accessing the same pool instance that was used to acquire the
resource instance.
Cause: Invalid entities still found in the validation list of the transaction after attempting to validate all
invalid entities for the VALIDATION_THRESHOLD 10 times (by default).
11-851
Action: Fix any logic that invalidates entity instances in the validation cycle (perhaps in overridden
validateEntity() methods) such that all entities are valid before the VALIDATION_THRESHOLD limit
is reached.
Cause: There are invalid entities or entities in the post list of the transaction after trying to post all
changes for the POST_THRESHOLD 10 times (by default).
Action: Fix any logic that places entities in the transaction's list of entities to be validated or posted in
the post cycle, such that all entities get posted before the POST_THRESHOLD is reached.
Cause: Invalid entity instances found in the transaction in the beforeCommit phase.
Action: Fix any business logic that invalidates entity instances in postChanges() such that there are no
more invalid entities after all changes are posted during the commit cycle.
Cause: If an unexpected exception occurs during a framework operation, this exception is thrown, with
the unexpected exception included in the details of this exception.
Action: Fix the cause for the exception in the details for this JboException.
JBO-30000: ApplicationPoolException
Cause: The application attempted to create an application pool with the same name as an existing
application pool.
Action: Correct the application logic that is creating an application pool. Validate that a pool with the
given name has not already been registered with the pool manager.
Cause: The pool failed to create an application module instance during checkout.
Action: Correct the application's configuration properties.
11-852
Cause: The application attempted to checkin an application module that was not checked out from the
pool.
Action: Remove redundant releaseApplicationModule invocations from the application logic.
Cause: The application attempted to invoke an application pool method with an application module that
was not created by that application pool instance.
Action: Correct the application logic. Use the session cookie that was used to acquire the application
module instance to acquire a reference to the application pool that created that application module
instance.
Cause: The application attempted to access the application pool with a session cookie that is not
registered with that application pool.
Action: Correct the application logic. The application should not reference the application pool directly.
Use the session cookie interface for all application pool interaction.
Cause: The application attempted to release a session cookie lock that it did not hold.
Action: Internal exception. Please contact support.
Cause: A session cookie request thread timed out while waiting for the session cookie lock.
Action: Verify that all threads that have acquired a session cookie lock have properly released the
session cookie lock when they have completed their task. If the lock is properly released then increase
the wait timeout period for the request that was interrupted.
Cause: The application attempted to modiby the availability status of an application module that is
already in active pool use.
11-853
Action: Remove the application logic that is updating the application module availability status.
Cause: The web server attempted to replicate a session cookie with an existing, active cookie.
Action: Internal exception. Please contact support.
Cause: The application attempted to create a session cookie with an invalid set of cookie parameters.
Action: Correct the application logic that creates the session cookie. Verify that the cookie session id,
application id, and application pool reference are all not null.
Cause: The application attempted to create a session cookie in an application pool that already contains
that session cookie.
Action: Correct the application logic that creates the session cookie. Remove the existing session cookie
before creating a new one in that pool.
Cause: The application attempted to change the session cookie environment after the session cookie
became active.
Action: Correct the application logic that sets the session cookie environment. Move all logic that
changes the session cookie such that it occurs before the session cookie becomes active. A session cookie
is active after it is first used to acquire an application module.
Cause: The application attempted to remove a session cookie from the pool while that cookie had an
application module instance checked out.
Action: Correct the application logic that removes the session cookie from the application pool. Be sure
to invoke SessionCookie.releaseApplicationModule before invoking
ApplicationPool.removeCookie(SessionCookie).
11-854
Cause: The application attempted to serialize a session cookie while that cookie had an application
module instance checked out or which the cookie was locked by a client request thread.
Action: Correct the serialization logic such that the session cookie is serialized after the session cookie
application module has been released to the application pool and after all client requests have released
their cookie locks.
Cause: The application request thread was timed out while waiting for an available appliation module
instance in the pool.
Action: Prevent wait timeouts by increasing the maximum pool size.
Cause:: Name of the definition Java class missing in the JClient XML file.
Action:: Every metaobject in JClient must have name of the definition object's Java class in the XML
file. Correct the error by regenerating XML file in the design time.
Cause:: The iterator binding is of the wrong Java class. Some controls expect to work with a
JUIterRowBinding, while others with JUIterRangeBinding. This error indicates that the supplied iterator
binding is not of the expected class.
Action:: If the error is caused by some client code that supplies an iterator binding, correct the code to
supply an iterator binding of the correct class. If the error is caused by framework code, contact BC4J
Technical Support with the stack trace.
Cause:: The form binding has already been registered with an application (JUApplication) object. It is
illegal to try to set the form binding's application object again.
Action:: This error typically means a program error. Contact BC4J Technical Support with the stack
trace.
11-855
JBO-55001: VariantException
Cause: Unexpected type was provided to Variant utility.
Action: Provide an expected type as reported in the exception.
Cause: The data-type passed to the Variant utility from a Validation rule is invalid. This could be due to
a corrupt XML-metadata definition in the component's XML file.
Action: Fix the component XML for the offending validation rule.
Cause: The name of the variant type passed to the Variant utility from a Validation rule is invalid. This
could be due to a corrupt XML meta data definition in the component's XML file.
Action: Fix the component XML for the offending validation rule.
11-856
Oracle Business Components for Java Glossary
ABCDEFHIJMNOPQRSTUVWX
Alias attribute setting
application module
application module class
Application Module Wizard and Editor
association
Association Wizard and Editor
attribute
Attribute Editor
attribute settings
business component
Business Components for Java
Business Components Project Wizard and Editor

11-857
business logic
business logic tier
cardinality setting
Change Indicator attribute setting
client
composition
connection
connection pooling
CORBA
Create Database Objects Tool
Default Value attribute setting
Discriminator attribute setting
domain
11-858
Domain Wizard and Editor
EJB
entity
Entity Constraint Wizard
entity definition class
entity object
entity object class
Entity Object Wizard and Editor
Expression attribute setting
fault-in mechanism
forward generation
forward only mode
framework
11-859
H
HTML
IIOP
iterator
JDBC
JSP
Key Attribute attribute setting
11-860
Mandatory attribute setting
metadata
Name attribute setting
ODBC
optimistic locking
Package Wizard and Editor
packages
Persistent attribute setting
pessimistic locking
Primary Key attribute setting
Project Wizard
11-861
property
Queriable attribute setting
Refresh After attribute setting
reverse generation
rollback
row object
Selected in Query attribute setting
server
SID
snapshot
stored procedure
11-862
synonym
Tester
thin client
transactions
Type attribute setting
type map
UML
Unique attribute setting
Updateable attribute setting
validation logic
validation rule
11-863
view
view link
View Link Wizard and Editor
view object
view object class
View Object Wizard and Editor
view row class
wizards
XML
11-864
Alias attribute setting
This setting appears in the Attribute Settings page of the View Object Wizard and Editor and in
the Attribute Editor. For a view attribute, the alias becomes part of the view object's SQL
statement when it is different from the attribute name (the default); for example, if you enter
myEname as the alias for the Ename attribute, the SQL statement will contain the clause
Emp.Ename as myEname. An alias is useful if you have two attribute names that are the
same, such as the primary and foreign keys in a join, and you need to make their names
unique.
11-865
application module
The business logic tier has one or more application modules that the other tiers — clients and
the database — interact with. An application module performs a specific application task, for
example, handling online orders or processing salary increases. An application module has
these main characteristics:
● It represents the data model that your client uses. To create the data model, the
application module contains business components, including instances of view objects and
view links. (This containership is similar to how a Java frame can contain instances of
components, such as a list box and a grid control.)
● It can contain other application modules, called nested application modules. One
application module can contain a variety of simpler application modules that together
provide complex functionality. For example, an OnlineOrders application module could
contain an AddNewCustomer application module.
● It keeps track of all changes that affect data in the database. The top-level application
module provides a transaction context for the view object instances it contains, including
those in all nested application modules. This is an important consideration when deciding
what application modules your application needs. For example, you could combine
creating an order and adding a customer into the same transaction.
● It provides remotely accessible methods, which implement the application module

behavior. You can add custom methods and selectively export those public methods you
want clients to use. For example, an application module that processes employee salary
increases might export methods for finding employee salary information and adding the
raise.
● A top-level application module has one connection to the database.
● You can deploy the same application module in multiple configurations, such as CORBA,
EJB, or locally, without changing its code. Also, the same application module can be
used in a physical one-tier, two-tier, or three-tier application (tiers on one, two, or three
computers) without code changes. You are not tied to a particular deployment platform
after development is complete.
● As discrete units, application modules are easily reused in the business logic tiers of
other applications.
11-866
When programming your business logic tier, business logic is placed at different levels to make
business components easily reusable:
● An entity object contains business logic pertaining to a single business entity. All view
objects based on the entity object share the logic. At the entity level, calculations are
performed in Java code.
● A view object contains logic pertaining to a view, which is defined by a SQL SELECT
statement. This can include SQL-calculated expressions, joins, unions, nested
subselects, and so on. You can also add code to the Java source, for example, you can
propagate events to the UI, or create a method that calls an entity method that you want
to expose for this view.
● An application module's source files can contain logic specific to the task it performs —
logic not appropriate to put in an entity object or view object, which multiple application
modules performing different tasks can use. If two applications use the same view, you
would put logic specific to one of the applications in its application module source files
instead of in the entity or view object source files. As a general guideline, if you have one
form per task, you could structure your application so there is one application module per
form. An application module represents a data model for a task that is accomplished
within one transaction.
An application module lets you gather data tailored to a client interface (such as a form), so
data can be retrieved in one network roundtrip instead of multiple trips. You can also perform
calculations in the business logic tier through remotely accessible methods, reducing client
overhead. For bulk operations on application data, you can perform the operation in the
business logic tier without downloading all of the data to the client; changes to the data the
client is currently viewing is automatically synchronized.
To create and edit an application module at design time, use the Application Module Wizard and
Editor. You can also create a default application module by using the Business Components
Project Wizard and Package Wizard.
At runtime, a client creates an instance of an application module for its use. It can create an
instance of an application module you created at design time, or an instance of the base
application module class, called a generic application module. You can use a generic application
module when you want a container for dynamically created view objects, view links, and
application modules. For example, if you have a complex application with a client menu
11-867
containing many tasks, you might decide to create a generic application module that
instantiates application modules as needed, based on the menu choice, within the same
transaction.
A client can use application module instances in a pool. For example, in the case of a web
application, you may have 1,000 users but you know that only 100 will be using a certain
application module at one time. So you keep 100 application module instances in a pool. When
a client needs an application module instance, it takes a free one from the pool and releases it
to the pool after either committing or rolling back the transaction. Because the instance is
precreated, end users are saved the time it takes to instantiate the application module when
they want to perform a task. Typically, web-based JSP clients use pools.
11-868
application module class
A Java class extending directly or indirectly from oracle.jbo.server.ApplicationModuleImpl. The
Application Module Wizard, Business Components Project Wizard, or Package Wizard can
generate this class. You can add custom code to the source file, such as methods specific to
the application module task but not appropriate to place in a view object or entity object class.
You can optionally specify that this class extend from a custom class (which must directly or
indirectly extend the ApplicationModuleImpl class and be in the project classpath); for example,
you might do this if you want to reuse code that's already been written or if your organization
decides to customize the business components framework to meet specific needs.
11-869
Application Module Wizard and Editor
These tools let you create and edit application modules. You can also create a default
application module by using the Business Components Project Wizard and Package Wizard.
While the business components project is open, to create an application module with the
Application Module Wizard either:
● Choose File | New, select Business Components, and double-click Application Module.
● In the the Navigator, right-click a business components package and choose New
Application Module.
To edit an application module, in the Navigator, right-click the application module and choose
Edit module. Or double-click the application module.
When creating an application module, the wizard lets you specify the following information,
listed by page:
● Name page. An application module name (perhaps ending with the string "Module"), the
package the application module should be placed in, and optionally the class the
application module extends (which must extend directly or indirectly from from
oracle.jbo.server.ApplicationModuleImpl).
● Data Model page. Specify which view object and view link instances will be included in the
application module. View objects in the application module's project appear in the
Available list: master views appear directly beneath the package, while detail views
(related by view links) appear beneath the master view. To include a master view, select
the application module in the Data Model list, then shuttle a view object from the
Available View Objects list to the Data Model list. To include a detail view, while the
master is selected in the Data Model list, shuttle the detail view over from the Available
View Objects list. If a view object is used in the data model more than once, the
instances must have a different names to prevent naming conflicts.
● Application Modules page. When application modules are nested, the outermost (top-
level) application module provides the transaction context for the others. The Available
list displays all application modules in the project; if you shuttle an application module to
the Selected list, it becomes nested within the application module you are defining in the
wizard. Optionally supply a name that identifies an instance of an application module; if
11-870
an application module is used more than once, names can help you distinguish between
the instances. When you nest an application module within another, the parent
application module can use the objects and code in the child application module.
● Java page. If you want to customize the application module behavior by adding code,
you can specify that the wizard generate a Java file for the application module class.
When editing an application module, the editor lets you specify the following information, in
addition to the previous pages (except for the Name page):
● Remote page. When you are ready to deploy, select Remotable Application Module to
generate proxies, stubs, and skeleton classes. You must select this option to create a
physical three-tier application (with each tier on a different computer). For each
distributed object deployment type you select, you can specify the client projects where
you want the files to be generated. Three types of files are created for your target
platform: files that are only used by the business logic tier (located in the server
subpackage), files that are used in both the business logic and client tier (in the common
subpackage), and files that are used only in the client tier (in the client subpackage).
● Client Methods page. Select methods to export, so a client can use them in a tier-
independent manner. Methods you've written in the application module class file appear
in the Available list; to appear in the list, they must be of a data type that implements the
Serializable interface. To export them, move them to the Selected list. Before you can
use this page, in the Java page, you must select Generate Java File(s). When you click
OK, an export interface file, directly or indirectly extending oracle.jbo.ApplicationModule,
is created. You need to do a few other things before the client can use the methods,
including importing the interface in the client code and invoking the method properly in
the client code, as described in the Business Components for Java online help.
● Property page. To add a property, type a property name and value, then click Add. You
can also add and edit values for existing properties, and delete properties.
11-871
association
Defines a relationship between two entity objects based on common attributes. The relationship
can be one-to-one or one-to-many; you can implement a many-to-many relationship either by
using an entity object based on an intersection table or by using two one-to-many associations.
The association allows entity objects to access the data of other entity objects through a
persistent reference. Although the same type of relationship can also exist at the table level
through a foreign-key relationship or object REF, an entity object only needs an association to
access the data of another entity object. You can create associations regardless of whether the
database has the corresponding referential integrity constraints.
An example of a relationship is a one-to-many association between departments and

employees; they might have a relationship where the Dept entity object has a Deptno attribute
that is related to the DeptNo attribute of the Emp entity object.
You can define and edit associations in the Association Wizard and Editor. You also can
generate default associations, based on referential integrity constraints in existing tables
(reverse generation), by using the Business Components Project Wizard and Package Wizard. For
forward generation, creating associations can optionally add foreign-key constraints to the tables
you generate. If you add referential integrity constraints to tables after you've already generated
entity objects, you can simply go into the Entity Object Editor and click Finish to create the new
association.
Through optional association accessors in the entity objects, you can access data on the other
side of the association. For example, inside the Dept entity object, you could call the getEmps
method and retrieve a row set of Emp entity objects that reflect the employees working in the
current department; the next time you call getEmps, it returns the same row set. Your code can
traverse associations in either direction (master to detail, and detail to master). An entity object
can traverse multiple associations to get the data it needs.
An association can be a composition, where the source entity object "owns" the destination
entity object: no destination entity object can be created without the owning entity object
existing first.
A business component association is an implementation of the UML association concept.
11-872
Association Wizard and Editor
These tools let you create and edit associations. You can also create default associations,
based on referential integrity constraints in existing tables (reverse generation), by using the
Business Components Project Wizard and Package Wizard.
For forward generation, creating associations can optionally add relationships to the tables you
generate; for example, you might want other applications (that don't use Business Components
for Java) to have access to the same relationships. You create tables from entity objects by
using the Create Database Objects Tool.
While the business components project is open, to create an association with the Association
Wizard either:
● Choose File | New, select Business Components, and double-click Association.
● In the the Navigator, right-click a business components package and choose New
Association.
To edit an association, in the the Navigator, right-click the association and choose Edit
association. Or double-click the association.
When creating an association, the wizard lets you specify the following information, listed by
page:
● Name page. An association name (pick something that describes the relationship,
perhaps ending with the string "Assoc" to make it easy to identify) and the package the
association should be placed in. Ideally, the association resides in the same package as
the entity objects it associates, but this is not required.
● Entity Objects page. Select the entity objects you want to associate. After the association
is defined, the entity objects can use the association to transparently traverse to the
other side of the association in a predefined manner. For example, the employees of a
department might be accessed through a department by issuing the call
deptImpl.getEmps().
● Attributes pages. Select the attributes that define the relationship between the entity
objects of an association. (You must specify the same number of attributes for each
11-873
entity object, in the proper order.) You can optionally specify all attributes that define a
key: when you shuttle a key to the Selected Attributes list, the attributes associated with
that key automatically appear. Also, if you select a key in the source page, the matching
key (if applicable) will be included by default on the destination page.
● Association Properties page. Specify behavioral aspects of the association, including

cardinality, whether to expose association accessors that return data from the other side
of the association, the names of the accessors, whether to generate key constraints
during forward generation, whether the association is a composition, and whether to
implement cascade delete. The accessors are placed in the entity object class.
● Intersection and Generate Related Associations pages. Specify aspects of a many-to-

many association.
When editing an association, the editor lets you specify the same information, except it
excludes the Name page.
If you add database constraints to tables after you've already generated entity objects for them,
you can simply go into the Entity Object Editor and click Finish to create the new associations.
11-874
attribute
A characteristic of an entity object or view object, implemented as a JavaBean property of the
object class. An attribute can correspond to a database column, or be independent of a column.
There are five kinds of attributes:
Attribute Defined where? Value derived from a Persisted in the database?

kind database query?
persistent entity or view object yes yes (the value outlives the class that
level created it)
transient entity or view object no no
level
entity-derived view object level no no
SQL-derived view object level yes no
dynamic view object level, at no no
runtime
Entity objects can have the following kinds of attributes:
● Persistent. A entity attribute that is persisted in the database (the Persistent attribute
setting is selected).
● Transient. A entity attribute that is not persisted in the database (the Persistent attribute
setting is deselected).
When you first create an entity object using reverse generation, a persistent entity attribute is
created for each table column. After, if you change the table, you need to manually change the
attribute.
View objects can have the following kinds of attributes:
● Persistent. A view attribute based on a persistent entity attribute. The data is cached at
the entity object level.
at the entity object level.
11-875
SQL expression. The data is cached at the view object level.
SQL expression. The data is cached at the view object level.
● Dynamic. A view attribute that is created with the addDynamicAttribute method. You can
use it to store information created at runtime that you want to store with the row data. It is
used only by the view object that created it. Dynamic attributes are handled the same
way as design time attributes. Attributes can be any Serializable object. The data is
cached at the view object level.
In Business Components for Java, the term attribute is based on the UML definition, not the
XML definition. In UML, an attribute is a named property of a class that describes a range of
values that instances of that class might hold.
11-876
Attribute Editor
The Attribute Editor lets you edit entity and view attributes. To access the editor, in the
Workspace view of the Navigator, select an entity object or view object, then right-click an
attribute in the Structure pane and choose Edit attribute. The Attribute Editor lets you specify
properties at the attribute level.
When editing an attribute, the wizard lets you specify the following information, listed by page:
● Entity Attribute page. Settings include attribute and column name, attribute and column
type, default value, whether it is updateable always, when new, or never, whether to
refresh after update or insert, whether it is used to indicate the row has changed, and
whether it is a primary key, mandatory, persistent, queriable, and unique. In general, if you
are performing reverse generation, you don't want to change the primary key,
mandatory, database column name, column type, and unique settings that were received
from the table. For forward generation, the primary key, mandatory, persistent, database
column name, column type, and unique settings are used to generate tables.
● View Attribute page. Settings include attribute and alias name, attribute type, default
value, SQL expression, whether it is updateable always, when new, or never, and
whether it is queriable. (view attributes only)
● Validation page. Add, edit, or remove validation rules. New rules can be applied at the
entity object level, attribute level, or both. Rules can be reordered within a level, which is
useful when you have multiple validation rules per attribute and want to control the order
of rule firing. (entity attributes only)
11-877
attribute settings
Attributes can have the following settings. For entity attributes, the settings can affect forward
generation or the settings can be derived from an existing table (reverse generation).
SQL- Entity-
Persistent Transient Persistent Transient
Derived Derived
Attribute Forward Reverse Attribute Attribute Attribute Attribute
Attribute Attribute
Setting Generation Generation (entity (entity (view (view
level) level) (view (view
level) level)
level) level)
Attribute N/A Default Required Required Default Required Required Default

Name based on based on based on
column entity entity
name; you attribute attribute
can change name name
it to any
Java
identifier
name.
Attribute N/A Default Required Required Not Required Required Not
Type based on modifiable; modifiable;
column data uses entity uses entity
type; you attribute attribute
can choose setting setting
another
type in the
list.
Default N/A N/A Optional Optional N/A N/A N/A N/A
Value
Primary Key Becomes From the Selectable Selectable, N/A (the N/A N/A N/A (the
the table's table; it but you entity entity
primary must match should attribute attribute
key, or part the table. leave it setting setting
of it if you deselected applies) applies)
specify in most
multiple cases
primary
keys for a
table (a
composite
key)
11-878
Selected in N/A N/A N/A N/A When When Selected When
Query selected, selected, selected,
this this this
attribute attribute attribute
appears in appears in appears in
the view the view the view
object's object's object's
SQL SQL SQL
Select Select Select
statement. statement. statement.
Discriminator N/A N/A Selectable Selectable Selectable Selectable Selectable Selectable
Mandatory Becomes a From the Selectable Selectable N/A (the N/A N/A N/A (the
mandatory table; this entity entity
column in value must attribute attribute
the table (a match the setting setting
NOT NULL table, or you applies) applies)
constraint might get
is problematic
generated runtime
for that behavior or
column in an
the table). exception.
Persistent Only All attributes Selected Deselected N/A (the N/A N/A N/A (the
persistent derived from entity entity
attributes the table attribute attribute
are added are setting setting
to the table. persistent; if applies) applies)
you change
it, this
column
does not get
populated
through the
business
components
framework.
Selected in N/A N/A N/A N/A When When When When
Query selected, selected, selected, selected,
this this this this
attribute attribute attribute attribute
appears in appears in appears in appears in
the view the view the view the view
object's object's object's object's
SQL SQL SQL SQL
Select Select Select Select
statement. statement. statement. statement.
11-879
Updateable N/A N/A Selectable Selectable Based on Selectable Selectable Based on
entity entity
attribute attribute
setting; setting;
can make can make
setting setting
more more
restrictive. restrictive.
Refresh N/A N/A except Selectable N/A N/A (the N/A N/A N/A
After when the entity
java.sql.type attribute
for this setting
attribute is applies)
CHAR, then
all Refresh
After
checkboxes
are
selected.
Database Becomes From the Required; N/A N/A (the N/A N/A N/A
Column the table's table; it it must entity
Name column must match match the attribute
name the table. table. setting
applies)
Column Becomes From the Required; N/A N/A (the N/A N/A N/A
Type the table's table; it it must entity
column must match match the attribute
data type the table. table. setting
applies)
Queriable N/A N/A Selectable N/A Selectable N/A Selectable N/A
Unique If selected, From the Selectable N/A N/A (the N/A N/A N/A
the column table; it entity
has a must match attribute
unique the table. setting
constraint. applies)
Change N/A N/A Selectable N/A N/A N/A N/A N/A
Indicator
11-880
Alias N/A N/A N/A N/A Default Optional Optional, Optional
based on can use to
entity prevent
attribute name
name; conflicts
optional,
but can
use to
prevent
name
conflicts
Expression N/A N/A N/A N/A N/A N/A Required Optional
11-881
business component
An application-specific component derived from the business components framework:
● application module
● view object
● entity object
● view link
● association
● domain
It is implemented as an XML metadata file and possibly one or more Java files.
The XML file stores metadata: the descriptive information about features and settings of an
application that you can declare with the Business Components for Java wizards and editors
during design time. Some examples of metadata are names and types of attributes, a SQL
query, and validation rules. The Java file(s) store the component’s custom code, which
implements application-specific behavior. Information that is descriptive in nature is stored as
XML while programmatic information is in Java.
Business components are organized into a standard Java package structure. For example, if a
view object named DeptView is in the package MyDept, then the MyDept directory would
contain the files DeptView.xml and DeptViewImpl.java. You specify the package while creating
a component in a wizard and it places the files in the correct locations for you.
The XML description might have:
<ViewObject
Name="DeptView"
...
ComponentClass="MyDept.DeptViewImpl">
11-882
The Java code might have:
package MyDept;
...
public class DeptViewImpl extends
oracle.jbo.server.ViewObjectImpl {
...
}
11-883
When you are creating a business logic tier, you create a business components project that
contains certain framework classes. The Business Components Project Wizard helps you create
a business components project.
11-884
Business Components for Java
A programming framework, implemented in Java and XML, that enables productive
development, deployment, and flexible customization of multi-tier, database-savvy applications
from reusable business components. These three-tier applications are made of a client, a
business logic tier containing the business logic and database views, and a database server
containing tables with the data the application uses. You can use the Business Components for
Java wizards and editors to build the business logic tier based on your specifications; you can
create both Java and JSP clients using the JDeveloper development environment; Oracle9i
provides the database server. Because business rules, views, and custom code are stored in a
separate tier, clients can be "thin" so they are easier to install and maintain: changes in the
business logic tier often require no modification to the clients that use it.
The business logic tier is made of one or more application modules that contain view objects,
representing views of data and optionally including calculations. View objects can use entity
objects, representing business entities and mapping to database tables, to enforce business
logic. View links represent master-detail relationships between view objects and are also
contained in an application module; associations represent bidirectional relationships between
entity objects. These modular components are easy to customize, maintain, and reuse in other
applications. The component-based framework handles many repetitive coding tasks, including
master-detail coordination, locking, and transaction management, including changes in the
business logic tier’s data cache and posting changes to the database.
By using the Business Components for Java design-time wizards and editors, you can build
business logic tiers by defining the characteristics of components: their attributes, relationships,
and business rules. Business Components for Java generates Java source code and XML
metadata to implement the behavior you have specified. Because the code inherits from a
framework, the Java source files are concise and do not contain large amounts of generated
code, so it's easy to see where to add your custom code. You can use JDeveloper to add the
Java code to enhance or change the behavior, and easily test the application services,
independently of the deployment platform. Business Components for Java then helps you
deploy application modules (without modification) across three possible physical tiers (client,
application server, and database) depending on the type of client you are deploying. Clients
include VisiBroker CORBA server objects, EJB session beans, web modules (JSP, XSQL
page, servlets), and Java Stored Procedures. Oracle9iAS Containers for J2EE (OC4J) is the
recommended deployment platform for J2EE applications. Refer to the Packaging and
Deploying book in the JDeveloper Help system for more information.
11-885
Business Components Project Wizard and Editor
This wizard appears automatically after creating a business components project in the Project
Wizard. Alternatively, you can choose Wizards | Business Components while a project is
selected. The wizard helps you specify
● the connection to the database for development
● the package name
● for reverse generation, the tables (and views, synonyms, and snapshots) used to create
default entity objects, as well as associations, which are based on referential integrity
constraints already in these tables (optional)
● default view objects, based on the entity objects, and view links, based on the
associations (optional)
● a default application module (optional)
You can also create and edit entity objects, associations, view objects, and view links by using
the Entity Object Wizard, Association Wizard, View Object Wizard, and View Link Wizard.
To edit an existing business components project, right-click a business components project and
choose Edit project to access the Business Components Project Editor. It lets you view and
specify connections, specify whether to generate Java and XML code or just XML code, and
view and specify registered validation rules. A few benefits of generating Java code are that you
have access to strongly typed accessors instead of just having to use the generic getAttribute
and setAttribute methods that return an object, and you can write code in the setter method.
If you select a business components project in the Navigator and choose Wizards | Business
Components, the wizard that appears is called the Package Wizard; it provides the same
functionality as the Business Components Project Wizard, except omits the Connections page.
11-886
business logic
Business logic includes validation logic, default value logic, deletion logic, and calculations,
which you should implement at the entity object level. Some examples of business logic are
tracking why a customer returned a product, or bidding rules between potential suppliers to
choose the best deal.
11-887
business logic tier
A basic business logic tier contains one or more application modules that provide access to view
objects and view links, which in turn rely on entity objects and associations. You can test your
business logic tier in the Tester.
11-888
cache
The business logic tier stores data it receives from a database and clients in two types of
caches: an entity cache and a view cache.
11-889
cardinality setting
Helps define the relationship between objects by setting the minimum and maximum number of
members that may participate in an association:
11-890
Change Indicator attribute setting
This setting appears in the Attribute Settings page of the Entity Object Wizard and Editor and in
the Attribute Editor. For a persistent entity attribute, selecting this setting means that the attribute
is used to determine whether any persistent attribute in the entity object has changed. The first
time the user changes the value of an attribute in a row, the business logic tier attempts to lock
the row (pessimistic locking mode) or tries to commit (optimistic locking mode); at this time, it
checks whether the data values in its cache match the database. The Change Indicator
attribute setting determines whether the business logic tier checks a single attribute or multiple
attributes, which involves more overhead. So, a change in the attribute value between when the
data is first brought into the entity object instance in the cache and when the data is first
modified is used to indicate that the entire row has been changed by another user. Only one
attribute in an entity object can have this setting. Often, the attribute is a time stamp column or
a sequence number.
11-891
client
A software application that requests the service, data, or processing of another application,
which can be on a local or remote computer. See also thin client.
11-892
composition
An association in which a parent entity object "owns" a child entity object: the parent object is a
container for one or more child objects. If a child entity object is modified, the child entity object
is validated; in addition, this relationship triggers validation of the parent entity object.
For inserts, updates, and deletes, the child entity object is considered part of the parent entity
object. A parent entity object containing valid child entity objects cannot be deleted until all of
the contained child entity objects are deleted. When attempting to change a child entity object,
the business logic tier attempts to lock the parent entity object; the owning parent entity object
must be successfully locked or the change will not be allowed. For example, if you make an
airline reservation, you cannot reserve a seat on a flight if there already exists a reservation in
your name.
A child entity object cannot exist without its parent. When a child entity object is created, the
foreign key assignments are made, and the parent entity object must have non-null values for
the primary key. At runtime, if a child entity object changes, the parent is marked as needing
validation. During a commit, the parent entity object is validated, then the child entity object is
validated.
11-893
connection
To connect to a database during development, you define a Connection object, including a
connection name (used by JDeveloper), username, password, role (a named group of
privileges that a database administrator can create, required for IIOP), and driver. When you
are ready to deploy, you can switch to the deployment database, if you developed using a
different database. You can connect using JDBC or IIOP.
11-894
connection pooling
Since version 3.2 of Business Components for Java, connection pooling is the default behavior.
Instead of one JDBC connection being created for each application module instance, and being
destroyed when the instance disconnects, application modules can now reuse a pool of
connections. There is one connection pool for each JDBC connection URL, including the
username and password.
Opening a connection to a database is a time-consuming process that can sometimes take

longer than getting the data itself. The advantage of connection pooling is that clients can have
faster response times, because they are saved the time of creating the database connection.
Instead, they can reuse a connection created by another application module instance.
In addition to using the default connection pooling behavior, you have these options:
● You can set the maximum number of connections in a pool.
● You can disable connection pooling.
● You can create and use a custom connection pool manager.
11-895
CORBA
The Common Object Request Broker Architecture (CORBA) is an Object Management Group
(OMG) specification. It defines the framework used to create distributed object computing
systems, including definitions for static and dynamic invocation interfaces, an interface
repository, and an object request broker (ORB).
11-896
Create Database Objects Tool
Lets you create database tables based on the information in entity objects and, if specified, their
database constraints as specified in the Entity Constraint Wizard. This is called forward
generation. To access the tool, in the Navigator, right-click a business components package and
choose Create Database Objects.
11-897
Default Value attribute setting
This setting appears in the Attribute Settings page of the Entity Object Wizard and Editor and the
Domain Wizard and Editor, and in the Attribute Editor.
For an entity attribute, this setting is an optional default value. When the business logic tier
creates a new row containing that attribute, the attribute gets this value by default. This setting
is needed if the attribute is a discriminator.
For a view attribute, this setting is needed if the attribute is a discriminator.
For a domain, this default value is inherited by all attributes of this domain type and cannot be
changed in the Entity Object Wizard or Editor or in the Attribute Editor.
Note that an instance of the Java type for this attribute must be creatable with the default value.
11-898
Discriminator attribute setting
A discriminator attribute makes your view object's result set polymorphic: that is, the result set
can contain different types of objects, and the client can process the result set without having to
know about the different types of objects.
11-899
domain
A domain defines the type of values an attribute can have. A domain object is a developer-
defined data type, an immutable Java class encapsulating a scalar value or a structure, with
simple validation built into the constructor of the domain. The validation check occurs when an
object of that domain type is created. The advantages of creating domains are:
● Simple validations are performed once, against the domain definition, when the data is
created. Then, the data object can be passed between the tiers without the need for
reconstruction or revalidation.
● You can define settings and then share them with all attributes that are based on a given
domain.
JDeveloper provides a Domain Wizard and Editor for defining domains. You can use the
resulting class on the thin client as well as the business logic tier to hold values of a specific
type, such as a social security number. You can write code to format or validate the input string
in the domain's validate method, which is called by all constructors. Domain classes can be
associated with each field in a form. The form could directly instantiate an instance of the
domain class with the field's given input string.
In the Domain Wizard and Editor, you can specify settings so that all attributes of that domain
type inherit those settings. Attributes may further restrict domain settings, but may not make
them less restrictive. For example, a domain could be marked Persistent, meaning no transient
attribute can be of that domain type.
After you have created a domain object, you can use it as a data type for an attribute. For
example, you could create a domain named SSNumber, and write validation code for it that
ensures that the resulting data type is a string of nine characters.
Domains are always serializable Java objects. In the business components framework, it is
recommended that domains have a constructor that can accept at least one of the native Java
types, like String, byte[], Integer, and so on.
The business components framework also provides some predefined domains.
11-900
Domain Wizard and Editor
These tools let you create and edit domains.
While the business components project is open, to create a domain with the Domain Wizard
either:
● Choose File | New, click the Business Components tab, and double-click Domain.
● In the Workspace view of the Navigator, right-click a business components package and
choose Create Domain.
To edit a domain, in the Workspace view of the Navigator, right-click the domain and choose
Edit domain.
When creating a domain, the wizard lets you specify the following information, listed by page:
● Name page. A domain name (pick something that describes the relationship, perhaps
ending with the string "Domain" to make it easy to identify when you are choosing data
types in a wizard) and the package the domain should be placed in.
● Domain Settings pages. Specify attribute settings, including attribute and column type,
default value, whether it is updateable always, when new, or never, whether to refresh
after update or insert, and whether it is a primary key, mandatory, persistent, queriable, and
unique.
When editing a domain, the editor lets you specify information in the Domain Settings page,
and also provides the following page:
You can write validation code in the domain's Java file (which was created by the wizard). For
example, you could make sure a data type is a string of nine characters.
11-901
EJB
The Enterprise JavaBeans standard specifies a cross-platform component architecture for the
development and deployment of multi-tier, distributed, scaleable, object-oriented Java
applications. Also known as a Server Bean.
11-902
entity
In UML terms, a domain-specific noun, such as a customer, order, or item.
11-903
Entity Constraint Wizard
Lets you add constraints, which are used when you generate tables with the Create Database
Objects Tool (forward generation). To access the wizard, in the Workspace view of the
Navigator, right-click an entity object and choose Create Entity Constraint.
You can also create constraints while you define associations. In the Association Properties
page of the Association Wizard and Editor, select Use Database Key Constraints to
automatically create a constraint based on the association.
An entity constraint is a business logic tier object that represents a key constraint in the
database. An entity constraint describes, in terms of entity objects and attributes, the database-
level relationships between tables and columns. You select the entity object's attributes and
define the constraint in terms of database integrity constraints such as primary, foreign, check,
or unique. When you create a database object based on an entity object, the definition of the
entity constraint is used to detect associations between tables, create the specified key
constraints in the database, and ensure that data in the database is valid and conforms to the
key constraints.
11-904
entity definition class
A class extending directly or indirectly from oracle.jbo.server.EntityDefImpl. It stores runtime
metadata describing the entity object, including attributes, events, validators, associations, and
properties. When instantiated, it describes all instances of the entity object class. A client can call
methods to find information about the entity object, such as the attribute names and types,
database source, and so on. There is one entity definition class instance per entity XML file.
You can use the Entity Object Wizard and Editor to generate this Java class for an entity object
when you need custom create and find methods. This class is a good place to group together
methods that are used by all entity object instances. For example, you can optionally modify the
createDef method to use properties from another source (in addition to or instead of the XML)
when the entity definition is instantiated.
If an entity object publishes or subscribes to an event (as specified in the Publish and
Subscribe pages of the Entity Object Wizard and Editor), most of the event code is generated in
the definition files of the entity objects that publish and subscribe.
extend the EntityDefImpl class and be in the project classpath); for example, you might do this
11-905
entity object
In general terms, entity objects encapsulate the business policy and data for
● the logical structure of the business, such as product lines, departments, sales, and
regions
● business documents, such as invoices, change orders, and service requests
● physical items, such as warehouses, employees, and equipment
Specifically, an entity object stores the business logic and column information for a database
table (or view, synonym, or snapshot). You can create entity objects from existing database
tables (reverse generation) or define entity objects and use them to create database tables
(forward generation).
When you use a Business Components for Java wizard to create entity objects from existing
tables, each column in the database table becomes an entity attribute, which can have the
same name as the column or a different name that is more meaningful to your business
application; an entity object can have an attribute for each column or use a subset if a table
contains information for more than one entity. The attributes of an entity object store data type
information as specified in the database table they were derived from, including primary and
foreign key relationships, the number of characters allowed, precision and scale specifications,
and object REFs.
You can create and edit entity objects by using the Entity Object Wizard and Editor. Usually, you
have one entity object per table. If you have multiple entity objects per table, make sure that
each updateable attribute appears in one entity object only; otherwise, you could make changes
in a row that are not reflected in the other entity object.
During runtime, each entity object instance represents a row in the database table and stores
its data. There is only one instance per row, and all instances of the same entity class are
cached together. Multiple view object queries returning the same row refer to the same entity
object instance, so updates are visible to all view objects; one entity object can be used by
multiple view objects.
Entity objects are not exposed to clients. Instead, clients access an entity object’s data through
one or more view objects. In the view row class, you can expose entity object methods to a
11-906
client by writing a view object method that calls the method you want to expose.
Relationships between entity objects are expressed through associations; they match attributes,
typically key fields, from source and destination entity objects. Methods that return rows and
row sets through the association are available on the entity object class.
You implement the majority of your business logic in entity objects. For example, validation rules
(such as "sal > 700") can ensure that the values returned by a query are valid or that users do
not enter invalid data into a table. Business logic is defined and updated in one place, with the
benefit that multiple clients can use it and be instantly updated when changes are needed.
To decide what entity objects your application needs, you usually use UML object-oriented
modeling techniques.
11-907
entity object class
A class directly or indirectly extending from oracle.jbo.server.EntityImpl. When it is instantiated,
it becomes one row. You can use the Business Components Project Wizard, Package Wizard or
Editor, or Entity Object Wizard or Editor to generate this Java class for an entity object if you want
to customize methods, such as add custom validation logic code to the validateEntity method or
attribute setter methods, or calculate attribute values in the getter methods. You can specify that
this class extend from a custom class (which must directly or indirectly extend the EntityImpl
class and be in the project classpath); for example, you might do this if you want to reuse code
that's already been written or if your organization decides to customize the business
components framework to meet specific needs. In the wizard, you can optionally generate
● accessor methods (for example, getJob and setJob), which provide type-safe access to
the corresponding attribute fields and a place to add your own custom code for validation
● data manipulation methods, including lock, which you can modify to customize the entity
object's locking behavior, and doDML, which you can modify to customize its update,
insert, and delete logic. The lock method is called by the framework whenever an entity's
row in the database is locked for modifications. The doDML method is called by the
framework with appropriate DML command, to insert, update or delete the row
corresponding to the entity instance during the Transaction-Commit cycle. This method
can be overridden to modify the update behavior. For example, instead of directly
updating through a SQL statement as the framework does, update through a procedure
call to the database.
● create method, which you can modify to customize or add additional initialization features
to the entity object's create logic, for example, setting default values for attributes
● remove method, which you can modify to customize or add clean-up code to the entity
object's remove logic, for example, you might need to delete child objects in a
composition
11-908
Entity Object Wizard and Editor
These tools let you create and edit entity objects. You can also create default entity objects in
the Business Components Project Wizard and Package Wizard or Editor. The entity objects can be
based on existing tables (reverse generation) or be used to create database tables (forward
generation).
While the business components project is open, to create entity objects with the Entity Object
Wizard either:
● Choose File | New, click Business Components, and double-click Entity Object.
● In the Navigator, right-click the business components package and choose New Entity
Object.
To edit an entity object, in the Navigator, right-click the entity object and choose Edit object. Or
simply double-click it.
When creating an entity object, the wizard lets you specify the following information, listed by
page:
● Name page. The name of the entity object (which can be the same as a table name, or
different if, for example, the table name doesn't adequately reflect what you're using the
entity object for or you want to use a different language), the package the entity object
should be placed in, and the class the entity object extends (it must extend directly or
indirectly from oracle.jbo.server.EntityImpl). Optionally specify the database table (or
view, synonym, or snapshot) used to create an entity object, as well as associations, which
are based on joins already in these tables.
● Attributes and Attributes Settings pages. Remove attributes you want to exclude from the
entity object (for example, if they are in the database table but you don't want them in the
entity object), change the attribute order (useful for forward generation — the order of the
attributes will be the order of the columns in the table), and define new attributes (for
example, a transient attribute that has a value you calculate in the Java file or if you are
defining columns for forward generation). Usually, you have one entity object per table; if
you have multiple entity objects, make sure that each updateable attribute appears in one
entity object only. Settings include attribute and column name, attribute and column type,
default value, whether it is updateable always, when new, or never, whether to refresh
after update or insert, whether it is used to indicate the row has changed, and whether it
11-909
is a primary key, mandatory, persistent, queriable, discriminator, and unique. In general, if
you are performing reverse generation, you don't want to change the primary key,
mandatory, database column name, column type, and unique settings that were received
from the table. For forward generation, the primary key, mandatory, persistent, database
column name, column type, and unique settings are used to generate tables.
● Java page. If you want to customize an entity object, you can specify that the wizard
generate a Java file for the entity definition class, the entity object class, the entity
collection class, or a combination. By default, the wizard generates the entity object
class, but not the other classes.
● Finish page. Optionally create a default view object containing the attributes you
specified in the entity object. You can edit the view object in the View Object Editor.
When editing an entity object, the editor lets you specify the following information, in addition to
the pages provided with the wizard (except the Finish page):
● Tuning page. Specify if you want to use the Update Batching API to update entity objects
at runtime. No coding is required. Using this API usually improves performance, except
where there is only one modified row.
● Validation page. Add, edit, or remove validation rules. New rules can be applied at the
entity object level, attribute level, or both. Rules can be reordered within a level, which is
useful when you have multiple validation rules per attribute and want to control the order
of rule firing.
● Publish and Subscribe pages. Use the Publish page to define, edit, or remove events to
be published by the entity object; the wizard generates event code in the Java files for
the entity object class and the entity definition class. You can specify attributes that are
delivered with the event. To send an event, call the method of the same name. Use the
Subscribe page to select the events (defined in the project) that the entity object will
listen for. When the event is triggered, the entity object responds by calling the specified
method. You can specify how the event will be delivered: deliver the event to the
instances of the entity object as subscribed in program logic (addListener), or to those
entity objects that are associated to the publisher, by the selected association.
● Properties page. To add a property, type a property name and value, then click Add. You
11-910
If you add referential integrity constraints to tables after you've already generated entity objects
for them, you can simply go into the Entity Object Editor and click Finish to create the new
associations. For other database table changes, you can make the change manually in the
Entity Object Editor. For example, you can add attributes corresponding to new columns.
11-911
Expression attribute setting
the Attribute Editor. For a SQL-derived view attribute, a valid SQL expression is used to define
the value of the attribute.
11-912
fault-in mechanism
If a user of a client enters a value that causes the business logic to ask for the value of one of
the excluded attributes in a view object, then the business logic tier uses the primary key value to
go to the database and retrieve all of the attributes for the row (including the excluded ones).
This is called "fault-in:" the client's attempt to access an entity attribute that is not included in
the view causes the entity object to retrieve all of the remaining attributes. Fault-in occurs on the
entity object instance level; only the effected rows are faulted in. After the fault-in, the cache
contains one fully populated row that was the result of the fault-in. This on-demand faulting
prevents request failure.
For example, if you have a view object that includes the employee level and name, and when
you change the level to 3 from 4 the entity object checks the salary, then you are attempting to
read an attribute not included in the view. To avoid fault-in and two trips to the database, you
can include the salary in view.
When you design a view object, consider the following:
● Faulting can be avoided by making sure the view object includes the attributes that the
entity business logic makes reference to. This is particularly important if you query and
modify a large number of rows.
● When optimizing performance, remember that fault-in incurs a memory and performance
cost. Too many fault-ins will lower performance significantly. It is important to fine tune
the view attribute list, particularly for entity objects that include many attributes.
11-913
forward generation
You first define your entity objects in the Entity Object Wizard and Editor, then use them to create
your database tables and optionally constraints with the Create Database Objects Tool. See also
reverse generation.
11-914
forward only mode
You can use the setForwardOnly method in a view object to prevent data from entering the
entity cache. Only one row is worked with at a time, and the data cannot be changed. If you
won't be changing data and there is not a lot of repeated data, using forward only mode can
save memory resources and time, because fewer objects are created. Forward only mode is
useful when you are fetching data and reading it once, such as formatting data for a web page,
or for batch operations that proceed linearly.
11-915
framework
A class library with built-in application functionality. Using a framework involves specializing
base classes to introduce application-specific behavior, allowing the framework to coordinate
many of the basic interactions between objects.
For the business components framework, the classes are in oracle. jbo.*.
11-916
HTML
The Hypertext Markup Language is a non-proprietary language for publishing hypertext on the
World Wide Web. It is based on SGML. HTML uses tags to structure text into headings,
paragraphs, lists, hypertext links, and so on, which you can display in a web browser.
11-917
IIOP
Internet Inter-ORB Protocol, the protocol used for communication between Object Request
Broker (ORB) clients and servers. It is used with CORBA.
11-918
iterator
Each view object provides a default iterator (through the oracle.jbo.RowIterator interface) that a
client can use to navigate through its result set. A view object does not execute a query until its
iterator requests data. The iterator can enumerate the contents of a row set, including providing
forward and back navigation, and next and previous navigation. The row iterator can be used
with ranges to iterate over a range of rows in a UI more easily, including letting you use relative
navigation within the range. Range-aware row iterators are useful for grid controls.
11-919
JDBC
Java Database Connectivity is an API specification for retrieving and manipulating data in a
database from Java code. Requests are in SQL. A JDBC-ODBC bridge lets you access
databases through ODBC.
11-920
JSP
JavaServer Pages technology provides a fast way to create dynamic web pages by using XML-
like tags and scriptlets written in Java. It lets you rapidly develop server- and platform-
independent web-based applications. JavaServer Pages are an extension of the Java Servlet
API.
11-921
Key Attribute attribute setting
the Attribute Editor.
For a view attribute, when selected, the attribute is a key attribute for this view object. If the
corresponding entity attribute is Updateable and a Primary Key, Key Attribute must be selected.
If the corresponding entity attribute is not updateable, you can deselect Key Attribute if the
query does not depend on this attribute and you want to save system resources.
11-922
Mandatory attribute setting
When selected, each entity object row instance must have a non-null value for this attribute. If it
does have a null value, the row is considered to be invalid when you navigate away from it or
try to commit.
If an entity attribute is of a domain type, and the Mandatory attribute setting is set in the domain,
you cannot override the setting in the Entity Object Wizard or Editor or Attribute Editor.
Note: If NOT NULL columns in the database are not marked Mandatory in the entity attribute,
then when the entity object is posted to the database, a DMLException can occur due to a NOT
NULL constraint violation. This may be too late in the application logic to report to a user so,
ideally, the Mandatory setting should be the same as the settings in the database table. At
runtime, the framework checks that Mandatory attributes are not null at the same time that the
entity object is validated (the validateEntity method is called).
11-923
metadata
Data about another set of data (your application data), such as how it should be formatted.
Business Components for Java represents metadata as XML definition files, containing
information about the structure and behavior of your business components. It contains
descriptive information about the features and settings of an application that you can declare
with the Business Components for Java wizards and editors during design time. Some
examples of metadata are the names and types of attributes, a SQL query, and validation rules.
Information that is descriptive in nature is stored as XML while programmatic information is in
Java.
11-924
Name attribute setting
This setting appears in the Attribute Settings page of the View Object Wizard and Editor and the
Entity Object Wizard and Editor, and in the Attribute Editor.
The required attribute name setting specifies the name that the attribute is referenced by in the
Business Components for Java wizards, the Java source code, and the XML files.
11-925
ODBC
Open Database Connectivity is a standard API for accessing a database. Applications can use
SQL requests to access databases, and ODBC converts it into a request that this database
understands. ODBC was created by the SQL Access Group. A JDBC-ODBC bridge allows
applications using JDBC to reach ODBC-accessible databases.
11-926
optimistic locking
When an entity object uses optimistic locking, at commit time, the entity object attempts to lock
its corresponding row in the database. If the entity object is part of a composition, the framework
first tries to lock the parent entity object. If the attempt to lock is unsuccessful, an exception is
thrown. Also see pessimistic locking. Locking is defined in the oracle.jbo.Transaction interface
through the setLockingMode method.
11-927
Package Wizard and Editor
These tools let you create and edit packages. They provide some of the same functionality as
the Business Components Project Wizard.
While the business components project is open, to create a package with the Package Wizard,
do one of the following:
● Choose File | New, click the Business Components tab, and double-click Package.
● In the Workspace view of the Navigator, right-click the business components project and
choose Create Package.
● In the Workspace view of the Navigator, select the business components project and
choose Wizards | Business Components.
To edit a package, in the Workspace view of the Navigator, right-click the package and choose
Edit package.
The wizard and editor help you specify
● the package name
● tables (and views, synonyms, and snapshots) used to create default entity objects, as well
as associations, which are based on referential integrity constraints already in these
tables (optional)
● default view objects, based on the entity objects, and view links, based on the
associations (optional)
● a default application module (optional)
You can also create and edit entity objects, associations, view objects, and view links by using
the Entity Object Wizard and Editor, View Object Wizard and Editor, Association Wizard and Editor,
and View Link Wizard and Editor.
11-928
packages
In a business components project, you need to decide what business components you want to
group in the same package, so they have access to package private methods and variables,
and which business components should be in different packages. Business components in
separate packages can interact through public methods and variables; you can also reuse the
packages in other projects as needed. As a general guideline, you can create the following
packages in your business components project(s) for each application:
● business logic package, including entity objects and associations as well as view objects
used for filtering and validation
● presentation package, including the application module as well as view objects and view
links that project and filter data for the UI
● client package
● interface and domain package, which are common to both tiers and you might want to
upgrade it separately
You need to functionally decide what objects to put together in packages according to what
methods you want internal team members to use versus what you want external teams to use.
If it gets delivered together as a component, put it in one package. Different application feature
teams might need to be able to work independently on their functionality.
11-929
Persistent attribute setting
For an entity attribute, select this setting to make the attribute persistent (the entity saves it in
persistent storage — the datasource). Deselect it for a transient attribute.
If an attribute is of a domain type, and the Persistent attribute setting is set in the domain, you
cannot override the setting in the Entity Object Wizard or Editor or Attribute Editor. So for
transient attributes, Persistent should be not selected in the domain.
11-930
pessimistic locking
When an entity object uses pessimistic locking, the first time one of its attributes is successfully
modified, including passing any validation, the entity object attempts to lock its corresponding
row in the database. If the entity object is part of a composition, the framework first tries to lock
the row for the parent entity object. If the attempt to lock is unsuccessful, an exception is
thrown. Also see optimistic locking. Locking is defined in the oracle.jbo.Transaction interface
through the setLockingMode method.
11-931
Primary Key attribute setting
This setting appears in the Attribute Settings page of the Entity Object Wizard and Editor and
Domain Wizard and Editor, and in the Attribute Editor. For an entity attribute, when selected, this
attribute is (or is part of) the entity object's primary key. (More than one attribute can make up a
primary key.)
If an attribute is of a domain type, and the Primary Key attribute setting is set in the domain, you
cannot override the setting in the Entity Object Editor.
11-932
Project Wizard
After choosing File | New Project, the Project Wizard appears, which lets you create a new
project. You specify
● the name of the project file (JPR)
● the type of project (such as a project containing business components)
● the default package for the project
● the source path(s) under which all source files must be placed
● the directory where JDeveloper places compiled files
● project information, including the project title, author, copyright, company, and
description, which the wizard can place in an automatically generated HTML file entitled
"Project Notes" (optional)
If you create a business components project, the Business Components Project Wizard appears
after you click Finish.
11-933
property
In a business components project, properties are name/value pairs of type string that you can
use as metadata to drive runtime behavior. (Do not confuse them with JavaBean properties:
they're different.) Domains, entity objects, view objects, application modules, and entity and view
attributes can have properties. The properties are stored in the component's XML file.
You can define any properties you need in the appropriate Property page of a wizard or editor,
such as the Entity Object Wizard and Attribute Editor. Some uses of properties are
● in application modules, to indicate what style of generic user interface template to use; to
provide runtime hint information to control the style of display for information in the
application module
● in domains, to globally set default display style hints and format masks for certain
attribute types
● in entity and view objects, as needed, to override default hints provided by domains
For example, an attribute could have a Label property that specifies what the label should be
when the attribute is displayed in the UI. Another example is when you are laying out a
presentation space and want to use a mask (or picture string). To define properties for a string
that represents a social security number, you could create a SSN-MASK property with a value
of 000-00-0000. At runtime, you could evaluate the property name and apply the proper
formatting when appropriate.
Attribute and domain properties can be overridden to be more restrictive. Following is the
hierarchy, from least restrictive to most restrictive:
● domain property
● entity attribute property
● view attribute property
For example:
11-934
nameLength domain Dept entity object DeptView view object
type String Dname attribute of nameLength Dname attribute of nameLength
type type
length property has the value 20
length property of the attribute length property of the attribute
Designed to limit the length of a has the value 15 has a value of 10
department name to a string of
20 characters
The length property on the entity object's Dname attribute overrides the domain character limit
of 20 characters; so a department name can be 15 characters. The length property on the view
object's Dname attribute overrides the department name limit; so a department name can be 10
characters.
You can get and set properties at runtime by using methods defined in the NamedObjectImpl
class, such as getProperty, setProperty, getProperties, and getPropertiesAsStrings. Other
classes extend this class, including EntityDefImpl, ViewObjectImpl, ApplicationModuleDefImpl,
and AttributeDefImpl. Clients can query properties and make decisions based on property
values, but cannot set properties.
11-935
Queriable attribute setting
This setting appears in the Attribute Settings page of the View Object Wizard and Editor, the Entity
Object Wizard and Editor, and the Domain Wizard and Editor, and in the Attribute Editor.
For an entity attribute, when selected, the attribute can participate in a view object's query
condition. If not selected, the information cannot be queried (BLOB types, for example).
For a view attribute, when selected, the attribute can participate in a query condition. For a
persistent attribute, if the columns (to which attributes of this type are mapped) can be part of a
query filter (a WHERE clause), then this setting should be selected. For example, this property
should be selected for NUMBER column types, but not set for BLOB types. This attribute will be
suppressed from Query by Form interfaces generated by JDeveloper.
If an attribute is of a domain type, and the Queriable attribute setting is set in the domain, you
can override the setting in the View Object Wizard or Editor, but not in the Entity Object Wizard
or Editor.
11-936
Refresh After attribute setting
A persistent entity attribute can optionally have one or both of the following settings:
● Refresh After Update — After the entity object performs an update (the data in an entity
object instance is placed in an existing row in the database), the entity object retrieves
the value of the attribute from the corresponding database field. So the effect of any
database triggers will be reflected back in the entity cache. For example, if you have a
Date Updated field, after a row update, the database adds the new update date to the
field, so the entity object instance needs the new value.
● Refresh After Insert — After the entity object inserts a new row in the database, the entity
object retrieves the value of this attribute from the corresponding database field. For
example, you can use this feature to assign primary key values from a sequence in a
database trigger (after insert, the database generates the sequence number and the
entity object retrieves the new attribute value).
If an attribute is of a domain type, and the Refresh After attribute setting is set in the domain,
you cannot override the setting in the Entity Object Wizard or Editor.
11-937
reverse generation
You first define your database tables (and views, synonyms, and snapshots), then use them to
create entity objects in the Entity Object Wizard or Editor, Business Components Project Wizard,
and Package Wizard or Editor. See also forward generation.
11-938
rollback
Discards the changes made in the current transaction. The second half of the recovery
procedure. After the roll forward, any changes that were not committed must be undone. After
the redo log files have been applied, the rollback segments are used to identify and undo
transactions that were never committed, yet were recorded in the redo log. Oracle completes
this step automatically.
11-939
row object
Any object that implements a oracle.jbo.Row interface. When a view object query fetches one or
more result rows, individual rows are represented by Row objects. Each column value in the
result row is accessed through an attribute of a row interface. The row interface has methods
like getAttribute and setAttribute.
11-940
Selected in Query attribute setting
This setting appears in the Attribute Settings page of the View Object Wizard and Editor. When
selected, the attribute appears in the view object's SQL Select statement; otherwise, it doesn't.
11-941
server
The provider of services requested by a client. A single machine can be both a client and a
server depending on the software configuration.
11-942
SID
A unique name for an Oracle database instance. To specify a connection to a database, users
must specify the desired SID.
11-943
snapshot
A read-only copy of a master table located on a remote node. A snapshot can be queried, but
not updated; only the master table can be updated. A snapshot is periodically refreshed to
reflect changes made to the master table. In this sense, a snapshot is really a view with
periodicity.
11-944
stored procedure
A code module, stored in a DBMS, which performs an operation on the database. They are
often written in SQL.
11-945
synonym
An alias for a table, view, snapshot, sequence, procedure, function, or package. It is another
name assigned to a table for easy identification. For example, if you refer to tables residing in
other accounts or databases, you may find it convenient to define a synonym for the long string
of identifiers. If a table name changes, you can simply redefine the synonym rather than rewrite
all related queries. Synonyms are used to mask the real name and owner of an object, provide
public access to an object, provide location transparency for tables, views, or program units of
a remote database, and simplify the SQL statements for database users. A synonym can be
public or private.
11-946
Tester
To access the Business Components Tester (also called the Business Components Browser),
in the Navigator, right-click an application module and choose Test.
The Oracle Business Components Tester is an example of a generic, thin Java client
application. It uses the dynamic capabilities of the framework's client APIs to interrogate the
runtime metadata of any application module that you want to exercise, and presents a directory
of the view objects and view links contained by the current application module. The Tester
creates dynamic Swing-based forms for each view object you want to browse, and dynamic
master-detail forms for each view link that you want to test.
The Oracle Business Components Tester visually exposes all of the runtime features of the
framework including:
● view objects, which can be executed, scrolled, and have the values in any of their
columns changed,
● entity object business logic, which will be enforced when changes to related view object
columns are made so you can verify that domains are set up properly, that default value
logic functions correctly, that validation code is working, and that association lookups do
what you expect,
● multiple view objects, which include the same entity attributes stay synchronized when
changes are made through any of them,
● view linked view objects are automatically master-detail coordinated as you scroll
through master records to any level of depth,
● application modules can be tested in any supported deployment configuration from a

single application: Local, Remote CORBA/EJB in a physical business logic tier, as well as
Remote CORBA/EJB inside of Oracle8i.
When you commit, all pending changes are communicated to the database by the underlying
entity objects in the cache.
11-947
thin client
A client that retrieves only the data necessary for display, while business logic is performed in
another tier.
11-948
transactions
A transaction is an interface to manage database operations. All operations to modify data in a
transaction must succeed before the server will accept the changes. These operations include
methods that set attribute values, standard SQL calls (such as INSERT, UPDATE, and
DELETE), or more specialized calls such as calling Java stored procedures or SQL packages.
A transaction is an atomic unit; the effects of the operations in a transaction can be either all
committed (saved to the database) or all rolled back (undone).
For example, when a client using a banking service transfers money from a savings account to
a checking account, the transaction consists of three separate operations: decrement the
savings account, increment the checking account, and record the transaction in a transaction
journal. If all three operations are performed to maintain the accounts in proper balance, the
transaction is committed and the effects of the operations applied to the database. But, if
something (such as insufficient funds, invalid account number, or a hardware failure) prevents
any of the operations from completing, the entire transaction must be rolled back so that the
balance of all accounts is correct.
Transactions also provide multi-user consistency to a shared store of data. When a client
changes data, locks ensure that other clients don't make other changes until the first client is
finished. When a transaction is committed or rolled back, the locks are released.
Business Components for Java application modules provide default transaction and concurrency
support. No coding is required unless you want to customize the default behavior.
When programming with business components, the principles of transaction management are
the same from the business logic tier as from a client:
1. Create an application module that connects to the database and establishes a context for
the transaction.
2. Execute a query.
3. Manipulate the result set (set attributes, validate values).
4. Commit changes to the database (making the new data available to other application
modules) or roll them back, as appropriate.
11-949
The business components framework uses a batch-oriented (as opposed to a change-oriented)
approach to synchronize changes in any cached state with the database state. This approach
provides the following benefits:
● Changes are buffered in an in-memory cache.
● Changes in the cache are synchronized with the database using a series of database
manipulation operations. This series of operations is typically referred to as posting. (In
Business Components for Java, posting is performed in the commit cycle, or by
specifically calling postChanges on the Transaction interface.)
● Validations occur on some combination of each state change made and just prior to
posting because individual changes may have left the cache in an invalid database state.
11-950
Type attribute setting
This Attribute Type setting appears in the Attribute Settings page of the View Object Wizard and
Editor, the Entity Object Wizard and Editor, and the Domain Wizard and Editor, and in the Attribute
Editor.
The Database Column Type setting appears in the Attribute Settings page of the Entity Object
Wizard or Editor and the Domain Wizard and Editor, and in the Attribute Editor (except for view
attributes).
Depending on the type map you use, the wizards and editors fill in logical default types for you.
For an entity attribute, the Attribute Type setting is the Java data type or domain type of the
attribute. All Java variables have a type, and the type restricts the kinds of objects that can be
assigned to it. You also specify a Database Column Type, which is the SQL datatype of the
database column; it is used to derive the default Java JDBC type at runtime. The SQL data
type must correspond the Java data type, or you can get runtime exceptions, particularly for
string conversions. During forward generation, the Database Column Type becomes the column
type in the database.
The Database Column Type is the basic column data type, and the precision and scale (if
applicable) for that column. For example:
● For a Name attribute, you could represent it as VARCHAR2 in the database with a
maximum length of 30 characters. In that case, the Database Column Type would be
VARCHAR2(30).
● For an Amount field, the column type could be NUMBER(10, 2) to indicate that the
number should 2 decimal digits after the period (.) so you can represent valid currency
values.
● Where there's no precision or length information required, the Database Column Type
should simply be the column data type, such as VARCHAR2, BLOB or CLOB, or RAW.
For a view attribute, the Attribute Type setting is the Java data type or domain type of the view
attribute. For persistent and entity-derived attributes, you can't change the type from that
specified in the corresponding entity attribute.
For a domain, the Attribute Type setting is the Java type of the domain. You can optionally
specify a Database Column Type.
11-951
If an entity attribute has an Attribute Type that's a a domain, and the Database Column Type is
set in this domain, you cannot override the Database Column Type setting in the Entity Object
Wizard or Editor.
11-952
type map
Business Components for Java needs to map Java types in the business logic tier to SQL types
in the database. It does so with a type map. You can use the type map provided with Business
Components for Java, or define your own custom type maps.
11-953
UML
The Object Management Group's (OMG) Unified Modeling Language is a general, notational
language, based on earlier standards like Booch, OMT, and OOSE, for specifying and
visualizing complex software. It is ideal for large object-oriented projects.
11-954
Unique attribute setting
For a persistent entity attribute, when this setting is selected, there can be only one row with a
certain value (each row has a unique value in this column). During forward generation, the
corresponding not null database constraint is created.
If an attribute is of a domain type, and the Unique attribute setting is set in the domain, you
cannot override the setting in the Entity Object Wizard or Editor.
11-955
Updateable attribute setting
This setting appears in the Attribute Settings page of the View Object Wizard and Editor, the Entity
Object Wizard and Editor, and the Domain Wizard and Editor, and in the Attribute Editor. This
setting determines whether you can call a setAttribute method on an attribute. An attribute must
have one of the following Updateable settings:
● Always — The selected attribute may be updated in the business logic tier's cache.
● While New — The attribute can be updated only while the object is new: before the first
time it is committed. After it is committed to the database, this attribute becomes read-
only.
● Never — The attribute cannot be updated using the framework. For example, you can
use this setting for attributes whose values are populated in the database through
triggers. Tip: you might want to consider removing the setter methods.
For a persistent or entity-derived view attribute, the updateability of the attribute can be
restricted further than that of the corresponding entity attribute, but it can't be made "more
updateable." So if the entity attribute setting was Never, but the view attribute setting was
Always, the setting would remain Never. The same principle applies if an attribute is of a
domain type.
11-956
validation logic
Business Components for Java provides a framework for defining, implementing, and executing
validation logic in the business logic tier. The validation framework provides a consistent
programming model that hides internal implementation details. It frees you to focus on rules
that prevent users from entering invalid values into the database.
Note that validation is different from an integrity (or "database") constraint. An integrity
constraint is a declarative way to define a business rule for a column of a table. Integrity
constraints are defined with a table and are stored as part of the table's definition, centrally in
the database's data dictionary, so that all database applications adhere to the same set of
rules. You can use integrity constraints (in addition to validation) when some clients do not use
Business Components for Java.
You can define and apply validation logic in the following ways, either using a programmatic
(Java) or declarative (XML) technique. If you have multiple levels of validation, the validation
will trigger in this order, from first to last.
● Using domains as data types for entity and view attributes. (Programmatic) A domain
object validates data in its constructor. You can also apply rules and add code to a
domain object's validate method to further refine the business logic. A domain lets you
share attribute-level validation across entity object, view object, or both. Depending on
how you program your client, the validation can be triggered at the client or at the
business logic tier. For example, you might create a Price attribute of a Currency domain
type; if the domain is downloaded onto the client, the moment a user clicks out of a field,
they get feedback if they didn't enter the currency correctly. Domains are reusable
among attributes. For example, a CreditCard domain would be very reusable — you
wouldn't have to add this code in every entity object that needs it and you could update it
in one place.
● Editing entity validation methods. (Programmatic) The business components framework

can generate setAttribute methods for entity objects (for example, Dept.setLoc). Here
you can add validation that occurs before or after the attribute is set. In setter method,
you would add rules that are affected only by that attribute value and that do not need to
be reused often.
● Adding code to the validateEntity method. (Programmatic) The base entity class provides
a validateEntity method that your entity objects can override. Entity validation occurs
before moving from one row to another. It is useful for validating values of two or more
attributes; for deferring validation of individual fields until values for the entire row have
11-957
been entered; for validating values in separate entity objects that are associated. For
example, a Salary attribute may need to check other field values, such as job title,
currency, and so on. Another example is a date range, where the begin date must be
less than the end date.
● Applying validation rules to entity objects and attributes. (Declarative) Validation rules
encapsulate reusable patterns of validation that you can use by supplying appropriate
parameter values. You can use the Entity Object Wizard and Editor and Attribute Editor to
define and apply simple rules without writing code. When you use the wizard (as
opposed to writing code by hand), it generates XML, enabling you to customize rules
without recompiling Java code. You can use predefined validator types or define your
own. You could implement more complex rules in your own custom validation classes;
then you can register the classes as validator types and apply them, the same as the
predefined rules.
● Defining a composition. (Programmatic) A composition provides parent and child

hierarchic validation on the view object level. The validateEntity method of the parent
validates the children. For example, there should be no line item unless it's in an order.
The business components framework supports various validation levels: you can validate
attributes, entities, and the logical business objects. JDeveloper invokes validation logic at the
appropriate level when data is created or changed, and assumes that data already in your
tables is valid. So a query could return a result set that contains invalid values (for example,
from legacy data entered before the validation logic was applied), but a user cannot enter an
invalid value into the table. The framework invokes rules on contained objects before invoking
rules on top-level objects.
11-958
validation rule
In entity objects, you can use validation rules to ensure that the values returned by a query are
valid or that users do not enter invalid data into a table (for example, that an employee's salary
must be greater than 700). Validation rules are JavaBeans that encapsulate reusable validation
code for use across entity objects.
In the Validation page in the Entity Object Wizard and Editor and Attribute Editor, you can specify
validation rules and validation levels, and an execution order within the same level. A validation
level indicates whether the rule is applied to the attribute level or the entity object level,
depending on which you select. Applying validation rules involves attaching XML metadata to
an entity object. When you use the wizard (as opposed to writing everything by hand), it
generates XML, enabling you to customize rules without recompiling Java code.
At runtime, attribute-level validation rules are invoked when the attribute value is modified
through a generated setter method, or by the setAttribute method called on the entity object.
The entity-level validation rules are invoked when the current row in the client's iterator changes
from this entity object to the next; or during the commit cycle if an entity object is invalid; or by
an explicit validate method call on the entity object.
Business Components for Java provides predefined rules, and you can create your own.
In the Registered Rules page of a Business Components Project Editor, you can create and
register a custom validation rule, implemented in a validation class that is in your project. Either
click New to create a new class, then customize it, or register a class you've already
customized. Registered validation rules are stored as a list with the project's XML definition
(JPX file). You can apply registered rules to an entity object or attribute the same as you would
one of the predefined validation rules.
11-959
view
A datasource made up of columns from one or more database tables, combined into one
logical table. It is a custom-tailored presentation of the data in one or more tables. Also known
as a stored query. Views are a kind of virtual table — an object that acts like a table when you
execute a query, but is really a pointer to either a subset of a table, a combination of tables, or
a join of two or more tables.
In UML, a view is a projection of a model. A projection is a mapping from a set of elements to a

subset of itself. A projection of a model, which is seen from a given perspective or vantage
point and omits entities that are not relevant to this perspective.
11-960
view link
Defines a relationship between view objects, which represent views of tables. The relationship
can be one-to-one or one-to-many, and you can use multiple view links to create a many-to-
many relationship. The View Link Wizard and Editor lets you specify source and destination view
objects, and links them using attributes selected from the view objects.
An example of a one-to-many relationship could be a DepartmentView view object linked to a

EmployeeView view object in a master-detail relationship. With this view link, you could
efficiently look at information about employees in a particular department.
An example of a more complex one-to-many relationship could be a CustomerView view object

linked to an OrderView view object in a master-detail relationship, and the OrderView view
object linked to an ItemView view object in a master-detail relationship. So a user could quickly
look at the items in a particular customer's order in one form.
View links can be created based on associations, but an association is not needed to use a view
link. View links are navigable in one direction (master to detail, not detail to master), while
associations are bidirectional. So if you want to traverse both directions between two view
objects, you need to create two view links. If the default relationship does not provide adequate
functionality, you are able to create complex relationships through the Association SQL page of
the View Link Wizard or Editor.
If a view object is specified as a detail view in a link, the view object restricts the data to the
detail information (like adding a WHERE clause to the SQL statement that defines the view
object); otherwise, view objects provide unrestricted views, with all data available. In other
words, a view link selects a correlated view of underlying data based on bind values supplied
by the master view.
When two view objects are linked in a master-detail relationship in an application module, the
default (or first) iterator for the master view object fires events to refresh the detail view object.
When the detail view object is created, the business component framework registers it as an
event listener for the master's iterator. So, when the iterator moves to another row in the master
view object, the contents of the detail view object are refreshed automatically.
You can reuse view links in application modules. You can also create view links dynamically at
runtime using the business components API.
Note that if a view link is based on an existing association, and the association has been
defined as a composition, then when creating a detail view row, the master view row must exist
11-961
and have non-null key values. If the association has not been defined as a composition, no
such restriction applies.
In UML terms, a link is an instance of an association that represents a connection between two
or more objects.
11-962
View Link Wizard and Editor
These tools let you create and edit view links. You can also create default view links, based on
existing associations, by using the Business Components Project Wizard, Package Wizard, and
Entity Object Wizard.
While the business components project is open, to create a view link with the View Link Wizard
either:
● Choose File | New, select Business Components, and double-click View Link.
● In the the Navigator, right-click a business components package and choose New View
Link.
To edit a view link, in the Navigator, right-click the view link and choose Edit link. Or double-
click it.
When creating a view link, the wizard lets you specify the following information, listed by page:
● Name page. A view link name (pick something that describes the relationship, perhaps
ending with the string "Link" to make it easy to identify), the package the view link should
be placed in, and optionally an existing view link to extend.
● View Objects page. Select the source (master) view object and the destination (detail)
view object.
● Source and Destination Attributes pages. Select the attributes that define the relationship
between the source and destination view objects of a link. (There is a separate page for
source and destination; you must specify the same number of attributes in each page, in
order.) You can optionally specify all attributes that define an association: when you
shuttle an association to the Selected Attributes list, the attributes associated with that
association automatically appear. Also, if you select an association in the source, the
matching attributes (if applicable) will be included by default on the destination page.
These attributes are used to formulate a SQL snippet, which you can modify, if needed.
● View Link SQL page. Examine the default SQL expression used to filter the records in
the destination side of a view link and optionally modify it to perform any additional valid
SQL restrictions. You can click Test to make sure the SQL statement is valid.
11-963
● View Link Properties page. Specify cardinality and whether to expose view link
accessors, which you can use if you want to traverse the relationship in code. The
accessors can be placed in the view row class or the entity object class. After the link is
defined, the view object (or entity object) can use the link accessor to traverse to the
destination side of the link. For example, the employees of a department might be
accessed through a department by issuing the call getEmps. (For default view links, the
source view object contains the primary key and the destination view object contains the
foreign key.)
When editing a view link, the editor lets you specify the same information.
If you add an association after you have created a view object, you can manually add the link in
the wizard.
11-964
view object
Uses SQL queries to specify filtered subsets of attributes from entity objects. The views of data
are SQL-based and separate from the underlying entity objects, enabling flexible data retrieval
to support the required UI. In other words, you can query a set of data exactly as you want to
show it in the display. View objects provide clients with row sets they can scroll through and
update without concern for or knowledge of the underlying entity objects. Clients manipulate
data by navigating through the result set, getting and setting attribute values; changes are
made to the data in the underlying database when the transaction is committed. Relationships
between view objects are expressed using view links. Each view object provides a default
iterator that you can use to navigate through its result set.
View objects are often used to:
● Provide an additional level of security by restricting access to a predetermined set of

rows and columns. For example, you could create a view object where columns
containing sensitive data (such as salaries) are not selected.
● Hide data complexity. For example, a view object can display columns or rows from
multiple entity objects. Such a view object hides the fact that the data is coming from
several tables.
● Customize presentation. Using a view object, you can rename columns without affecting
the entity objects on which the view object is based.
● Store complex queries. A query could perform extensive calculations on table data. By
saving this query in a view object, the calculations are performed only when the view
object's query is executed. The calculation is executed before the data is retrieved from
the database.
● Improve efficiency of the application by using fast-executing, optimized SQL, selecting

only the data you need.
You can define multiple view objects per entity object, and a view object can select data from
multiple entity objects. Data is cached at the entity object level and all view object references
within the same transaction share the cache, so changes made through one view object are
immediately available to other view objects in the same transaction.
11-965
When you define a view object, you can specify which underlying entity objects are read-only
and which support read/write operations on participating attributes in the view object's attribute
list.
In the Application Module Wizard and Editor, you can choose the view links that you want to use
to link view objects in master-detail relationships. View links can also be specified in code that
executes at runtime. Detail view objects are automatically synchronized with their respective
master view objects.
An application module can use the same view object more than once, such as an unrestricted
view and a detail view; you can specify aliases to represent the various usages of a given view
object.
11-966
view object class
A class extending directly or indirectly from oracle.jbo.server.ViewObjectImpl. You can use the
Business Components Project Wizard, Package Wizard or Editor, or View Object Wizard and Editor
to generate this Java class if you want to customize methods, such as an overridden create
method so you can dynamically modify aspects of the view definition for that view object
instance; for example, automatically setting bind variables in the Where clause or automatically
adding Where clause criteria for security or filtering. You can also verify client IDs so they can
only query their own information from a multi-client table, instead of having each form add this
Where clause. You put methods in the view object class rather than in the view row class if they
operate on the default rowset and are not specific to a row but are specific to that view object.
extend the ViewObjectImpl class and be in the project classpath); for example, you might do
this if you want to reuse code that's already been written or if your organization decides to
11-967
View Object Wizard and Editor
These tools let you create and edit view objects. You can also create default view objects in the
Business Components Project Wizard, Entity Object Wizard or Editor, and Package Wizard or
Editor.
Default view objects are very simple in their definition. Use the View Object Wizard and Editor
to create and edit view objects so they are tailored to your needs. This might include a view
object that uses
● a subset of an entity object's attributes
● attributes from more than one entity object
● special SQL-derived or transient attributes
● non-default storage and updateability features
The ability of a view object to use multiple updateable entity objects enables one of the key
features of Business Components for Java: a single view object can update multiple entity
objects.
While the business components project is open, to create view objects with the View Object
Wizard either:
● Choose File | New, select Business Components, and double-click View Object.
● In the Navigator, right-click a business components package and choose New View
Object.
To edit a view object, in the Navigator, right-click the view object and choose Edit object. Or
double-click it.
When creating a view object, the wizard lets you specify the following information, listed by
page:
● Name page. The entity object(s) used to create the view object (if any), the name of the
11-968
view object (which could be entityView), an alias for the view object (to prevent naming
conflicts and distinguish detail views from unrestricted views, for example), whether
attributes in each entity object are read-only to this view object, whether a change to a
foreign key means it should refer to a different field or to update that field value (for
example, in an order entry application, whether a change to an item ID means you are
ordering a different inventory item or changing the inventory item's item ID), and the
package the view object should be placed in. If you are performing updates, you need to
specify an entity object; also, if you are retrieving a join of information, it is best to have
entity objects. However, if you are querying data for read-only purposes, no entity object
is needed. Entity objects enable updateability and validation, keeping rows uniquely in
memory.
● Entity Objects page. The entity object(s) used to create the view object (if any), the name
of the view object (which could be entityView), an alias for the view object (to prevent
naming conflicts and distinguish detail views from unrestricted views, for example),
whether attributes in each entity object are read-only to this view object, whether a
change to a foreign key means it should refer to a different field or to update that field
value (for example, in an order entry application, whether a change to an item ID means
you are ordering a different inventory item or changing the inventory item's item ID), and
the package the view object should be placed in. If you are performing updates, you need
to specify an entity object; also, if you are retrieving a join of information, it is best to
have entity objects. However, if you are querying data for read-only purposes, no entity
object is needed. Entity objects enable updateability and validation, keeping rows
uniquely in memory.
● Attributes and Attributes Settings pages. Specify attributes you want to include from the
entity object, define new attributes (you can define transient or SQL-derived attributes),
and specify attribute settings. Settings include attribute name, attribute type, alias, SQL
expression, whether it is updateable always, when new, or never, and whether it is
selected in the view object's query and queriable. You want to include only the attributes
you need for a form in the client UI, to save memory and improve performance, but avoid
fault-in. You must include primary key(s) if the underlying entity objects are updateable;
this is enforced by the wizard.
● Query page. Optionally customize the view object's SQL statement. You can add
WHERE and ORDERBY clauses. Click Browse to select attributes by which to order the
query results. If you want to modify the query in other ways, such as the automatically
generated SELECT and FROM clauses, you can select Expert Mode. Click Test to verify
that the SQL statement is syntactically correct.
11-969
● Attribute Mappings page. If you selected Expert Mode, you can map query result
columns to view \these items if you deleted, added, or switched positions of columns in
your custom SQL query, because the mappings will no longer be correct.
● Java page. If you want to customize a view object, you can specify that the wizard
generate a Java file for the view object class, view row class, or both. By default, the
wizard generates the view object class, but not the view row class.
When editing a view object, the editor lets you specify the following information, in addition to
the previous pages:
● Client and Client Row Methods pages. Select methods to export, so the client can use
them remotely. Methods you've written in the view object class file appear in the
Available list; to appear in the list, they must be of a data type that implements the
Serializable interface. To export them, move them to the Selected list. Before you can
use this page, in the Java page, you must select Generate Java File for the view object
class. You need to do a few other things before the client can use the methods, including
making the application module remoteable, importing the package in the client code, and
invoking the method properly in the client code, as described in the Business
Components for Java online help.
If you change a database table after you have created a view object and you need to modify
the view object, you can make the change manually in the View Object Editor. For example,
you can add attributes corresponding to new columns in the entity object.
11-970
view row class
A class extending directly or indirectly from oracle.jbo.server.ViewRowImpl. You can use the
View Object Wizard or Editor to generate this Java class if you want to customize methods, such
as implement custom logic for calculating values for this view (in attribute getter methods). This
class can hold methods acting on row; methods that need the data in one row to operate. In the
view object class, you can add methods that operate on row set. In addition, you can expose
entity object methods to clients by creating row class methods that call a method in an entity
object.
extend the ViewRowImpl class and be in the project classpath); for example, you might do this
customize the business components framework to meet specific needs. In the wizard you can
optionally choose to generate accessor methods (for example, getJob and setJob), which
provide type-safe access to the corresponding attribute fields and a place to add your own
custom code for validation.
11-971
wizards
Business Components for Java provides the following wizards, editors, and tools:
● Project Wizard
● Package Wizard
● Application Module Wizard and Editor
● Entity Object Wizard and Editor
● View Object Wizard and Editor
● Association Wizard and Editor
● View Link Wizard and Editor
● Domain Wizard and Editor
● Attribute Editor
● Create Database Objects Tool
● Entity Constraint Wizard
● Tester
● Deploy Tools
11-972
XML
The Extensible Markup Language defines a universal standard for electronically exchanging
data. XML specifies a rigorous, text-based way to represent the structure inherent in data so
that it can be authored and interpreted unambiguously. Its simple, tag-based approach
leverages developers’ familiarity of HTML but provides a flexible, extensible mechanism that
can handle the gamut of "digital assets" from highly structured database records to
unstructured documents and everything in between.
11-973
UML Modeling
● UML Modeling
● Modeling Basics
❍ Configuring a Project for Modeling
❍ Creating a New Diagram

❍ Opening a Diagram
❍ Saving a Diagram
❍ Closing a Diagram
❍ Deleting a Diagram
❍ Viewing a Diagram
❍ Publishing a Diagram as a Graphic
❍ Importing a Model
❍ Diagram Layout Basics
■ Aligning Elements on a Diagram
■ Distributing Elements on a Diagram

■ Displaying Page Breaks on a Diagram
■ Showing, Hiding and Snapping to the Diagram Grid
■ Changing the Size of Grid Cells
■ Creating, Moving and Removing Elbows on a Connector
■ Straightening Lines on a Diagram
■ Minimizing the Number of Diagram Pages
■ Ordering Overlapping Elements on a Diagram
❍ Diagram Element Basics

■ Creating Multiple Elements Quickly
■ Selecting Elements on a Diagram

■ Resizing a Diagram Element
■ Cutting, Copying, and Pasting a Diagram Element
■ Moving a Diagram Element
■ Adding an Element to a Diagram
12-1
■ Changing the Font of a Diagram Element
■ Changing the Color of a Diagram Element
■ Undoing the Last Graphical Action
● Modeling Java Classes

❍ Class Diagram Notation
❍ Creating a Model of Java Classes

■ Creating a New Diagram
■ Modeling a Java Class

■ Modeling a Java Interface
■ Modeling an Inner Java Class or Inner Java Interface
■ Modeling a Java Attribute
■ Modeling a Java Operation
■ Modeling an Association Between Classes
■ Modeling a Generalization
■ Modeling a Realization Relationship
■ Modeling a Dependency
■ Modeling a Package
■ Creating and Attaching a Constraint to a Diagram Element
■ Creating and Attaching a Note to a Diagram Element
❍ Modifying Modeled Java Classes

■ Changing the Properties of a Class Model Element
■ Converting a Modeled Java Class to a Modeled Java Interface

■ Converting a Modeled Java Interface to a Modeled Java Class
■ Adding Javadoc Comments for a Class Model Element
■ Displaying Related Elements on a Diagram
■ Deleting a Class Model Element
■ Moving an Element between Class Diagrams
■ Changing the Way Class Diagram Elements are Displayed
❍ Generating and Reverse-Engineering Java Source Code
12-2
■ Reverse Engineering a Java Source File
■ Generating Java Source Code from a Modeled Class
■ Generating Javadoc Comments for a Class Model Element
■ Navigating to Code Generated for an Element
❍ Transforming Java Classes into Entity Objects

■ Creating an Entity Object from a Modeled Java Class
● Modeling Business Components

❍ Class Diagram Notation
❍ Creating a Model of Business Components

■ Modeling an Entity Object

■ Modeling an Entity Object Attribute
■ Modeling an Entity Object Operation
■ Modeling a Domain
■ Modeling an Association Between Business Components
■ Modeling a Generalization
■ Modeling a Dependency
■ Modeling a Package
■ Creating and Attaching a Constraint to a Diagram Element
❍ Modifying Modeled Business Components

■ Changing the Properties of a Class Model Element
■ Deleting a Class Model Element

■ Moving an Element between Class Diagrams
■ Changing the Way Class Diagram Elements are Displayed
❍ Reverse-Engineering Table Definitions to Business Components

■ Reverse-Engineering a Table Definition to an Entity Object
❍ Using Your Modeled Entity Objects

■ Creating a Database Object from a Modeled Entity Object
12-3
■ Using Modeled Entity Objects With Java Classes
■ Displaying the Java Class Implementation for an Entity Object
■ Displaying Related Elements on a Diagram
● Modeling Activities
❍ Activity Diagram Notation
❍ Creating a Model of Activities, Flows and Pseudostates

■ Creating an Activity
■ Creating a Composite Activity
■ Creating a Subactivity State
■ Creating a Transition
■ Creating a Pseudostate
■ Creating an Object Flow State
■ Creating Additional Classifier in States
■ Requirements for a Drill-Down Diagram
■ Deleting Diagram Elements
❍ Partitioning an Activity Diagram Using Swimlanes

■ Creating a Swimlane
■ Creating a Child Swimlane

■ Showing or Hiding Swimlanes
● Modeling Activities for E-Business Integration

❍ E-Business Integration Essentials
■ Oracle9i Advanced Queuing and E-Business Integration
■ About AQ Queue Definitions
■ Editing AQ Definitions
■ Business Event System and E-Business Integration

■ About BES and Hubs
12-4
■ About Business Event System Definitions
■ About BES and Integration Points
■ About BES and Decision Points
■ Oracle Workflow and E-Business Integration

■ About Generating Workflows for Integration/Decision Points
■ About Monitoring Business Processes
■ Hub and Spoke Integration
❍ Creating a Hub
❍ Creating a System Instance
❍ Changing a Single Instance Swimlane to Multiple Instance
❍ Deleting System Instances
❍ Moving a Transition
❍ Ways to Create Integration Points
■ Integration Point Essentials
■ About Simple Integration Points
■ About Decision Points

■ About Synchronization Points
■ About Broadcast Mode
■ Defining an Integration Point

■ Generating Integration Points
■ Files Generated by the E-Business Integration Generator
■ Using Custom Instance Routing Logic
■ Using Custom Content Routing Logic
❍ Creating Messaging Adapters

■ Messaging Adapter Essentials
■ Messaging Architecture
■ Messaging Adapter Library

■ More on Deployment Profile Selectors
■ Basic Adapter Architecture
12-5
■ Basic Sending Adapter
■ Basic Receiving Adapter
■ Business Components for Java Adapter Architecture

■ Business Components for Java Sending Adapter
■ Business Components for Java Receiving Adapter
■ Creating Basic Messaging Adapters

■ Generating the Basic Sending Adapter Client Code
■ Writing Your Own Basic Sending Adapter Client Code

■ Generating the Basic Receiving Adapter Client Code
■ Writing Your Own Basic Receiving Adapter Client Code
■ Creating Business Components for Java Messaging Adapters

■ Generating the Business Components for Java Sending Adapter
Client Code
■ Writing Your Own Business Components for Java Sending Adapter
Client Code
■ Generating the Business Components for Java Receiving Adapter
Client Code
■ Writing Your Own Business Components for Java Receiving Adapter
Client Code
■ Subclassing the Business Components for Java Receiving Adapter
■ Using the AdapterMessage Class for Message Payloads
❍ Deploying Generated E-Business Integration Files

■ About Deployment
■ About Deployment Profiles

■ Testing Deployment Success
12-6
UML Modeling
Oracle9i JDeveloper supports two kinds of UML diagrams: class diagrams and activity
diagrams.
Class diagrams can be used to create models containing the following:
● models of Java classes, from which Java source code can be generated
● models of Java classes, reverse-engineered from your existing Java source code
● models imported from an XMI file
● models of business components, which are visualizations of underlying business
components, from which database objects can be generated
● models of business components, reverse-engineered from existing table definitions
Activity diagrams can be used to create models containing the following:
● models of activities, flows and states to illustrate a process

● models of activities from which e-business integration code can be generated.
The following topics describe how to create UML diagrams with JDeveloper.
● Modeling Basics
● Modeling Java Classes
● Modeling Business Components
● Modeling Activities
● Modeling Activities for E-Business Integration
Related Topics
12-7
12-8
Modeling Basics
The following topics describe how to perform basic diagram operations in JDeveloper.
● Configuring a Project for Modeling
● Creating a New Diagram
● Opening a Diagram
● Saving a Diagram
● Closing a Diagram
● Deleting a Diagram
● Viewing a Diagram
● Publishing a Diagram as a Graphic
● Importing a UML Model into JDeveloper
Related Topics
Diagram Layout Basics
Diagram Element Basics
12-9
Configuring a Project for Modeling
You can configure a JDeveloper project's settings to specify the root locations of the package
hierarchies for modeled elements available to that project. The model path is configured by
default, so you only need to change it if you want to:
● include model element files to your model that are stored somewhere else
● store new model element files somewhere else.
Modeled elements can be shared between projects by adding their file system location to the
model path for a project.
Note: Removing an entry from the model path for a project may cause elements to be removed from
diagrams if those elements are no longer visible to the project.
When working with UML models in the Navigator pane, you may find it easier when viewing
your elements using the Category view. To display the Navigator pane in Category view, see
Changing Views in the Navigator.
Setting the model path for a project:
1. Right-click the project whose model path you want to specify.
2. Choose Settings...
3. Select the Common | Modelers node on the left of the Project Settings dialog.
4. Enter the file system location for your project's model elements in the Model Path field.
Multiple file system locations must be separate by semicolons.
Note: The order in which file system locations are entered in the Model Path signifies the
order in which the folders are searched for a model element, for example these folders
could be the 'roots' of the package hierarchies used by a model. The first location
specified in the model path is also the location in which new model elements are stored.
5. Click OK.
12-10
Related Topics
Adding an Element to a Diagram
12-11
Creating a New Diagram
New UML diagrams can be created in any project in JDeveloper.
To create a new diagram:
1. Right-click on the project in which you want to create a new diagram, then choose New
UML Diagram...
OR
Click the project in which you want to create a new diagram, choose File | New... from
JDeveloper's menu, then select UML Diagram in the left pane of the New dialog.
2. Select either Activity Diagram or Class Diagram in the right panel, then click OK.
3. Enter the package for the diagram, and the diagram name, then click OK.
Note: The default package for a diagram is the default package specified in the project's
settings.
An empty diagram is created in the specified package in the current project, and opened
in the content area.
Note: New elements created on this diagram will be created in the diagram's package.
Related Topics
12-12
Opening a Diagram
Previously saved class diagrams and activity diagrams can be opened from JDeveloper's
Navigator pane.
To open a diagram:
● Double-click the diagram's node in the Navigation pane.
OR
● Select the diagram from the Navigator pane, then drag it onto a blank part of the content
area.
OR
1. Right-click the name of the diagram you want to open.
2. Choose Activity Diagram or Class Diagram from the menu.
Related Topics
Saving a Diagram
Closing a Diagram
12-13
Saving a Diagram
In JDeveloper, class and activity diagrams are saved in their own file. Many of the elements,
and their properties, displayed on a diagram are also saved in their own files. Changes to
display properties, positions, sizes, and what is included on the diagram are stored in the
diagram file. JDeveloper offers two different save options for diagrams: Save and Save All.
Note: As changes to a diagram can cause changes to the underlying diagram elements, the Save
All command will save all changes to the diagram, and all of the underlying elements that it displays.
If you edit the properties of diagram elements and decide to exit JDeveloper, if you do not save
these outstanding changes (that is, changes to underlying elements) you will lose your latest
changes.
When you save a diagram using either Save or Save All, you will also be prompted to save any
other previously unsaved changes related to the current diagram. This is to maintain the
integrity of diagrams when they are reloaded by ensuring the elements displayed on the
diagrams are the same as the saved versions.
To save all diagrams and elements in all workspaces in JDeveloper's Navigation pane:
● Choose File | Save All in JDeveloper's menu bar.
OR
● Click the Save All icon on JDeveloper's toolbar.
To save changes to an existing diagram:
1. Click the diagram you want to save.
2. Choose File | Save in JDeveloper's menu bar.
OR
● Click the Save icon on JDeveloper's toolbar.
12-14
Related Topics
Opening a Diagram
12-15
Closing a Diagram
You can close any diagram that is opened in JDeveloper.
To close a diagram:
● Click the diagram you want to close from those listed in the Navigator pane, then choose
Windows | Close from JDeveloper's main menu.
OR
● Click the diagram you want to close, the press Ctrl+F4.
OR
● Right-click the Editor window tab displaying the name of the diagram you want to close,
then choose Close Editor.
Note: If there are any unsaved changes, either to the diagram, or the elements displayed
on the diagram, you will be prompted to save these changes before continuing.
Related Topics
Saving a Diagram
Opening a Diagram
12-16
Deleting a Diagram
Activity and class diagrams can be deleted from the file system without deleting the definitions
of most of the elements displayed on them.
To delete a diagram:
1. Select the diagram that you want to remove in JDeveloper's Navigator pane.
2. Choose Edit | Erase From Disk to remove the diagram from JDeveloper and the file
system.
Note: This command removes the diagram file from the file system and removes the
diagram from the Editor window, if it is currently open. The files corresponding to many of
the elements displayed on the diagram remain in the Navigator and on file system.
Related Topics
Opening a Diagram
Saving a Diagram
Closing a Diagram
12-17
Viewing a Diagram
You can change the magnification at which a diagram is displayed.
To increase the magnification of the diagram:
● Click the Zoom In toolbar icon at the bottom right corner of the diagram window.
OR
● Click the diagram, then choose Model | Zoom | Zoom In.
To decrease the magnification of the diagram:
● Click the Zoom Out toolbar icon at the bottom right corner of the diagram window.
OR
● Click the diagram, then choose Model | Zoom | Zoom Out.
To display the diagram at its original size:
● Click the Normal Size toolbar icon at the bottom right corner of the diagram window.
OR
● Click the diagram, then choose Model | Zoom | Normal Size .
To display the entire diagram:
● Click the Fit to Window icon at the bottom right corner of the diagram window.
OR
● Click the diagram, then choose Model | Zoom | Fit to Window.
12-18
To display the selected elements at the maximum size:
● Click the Zoom to Selected icon at the bottom right corner of the diagram window.
OR
● Click the diagram, then choose Model | Zoom | Zoom to Selected.
Related Topics
12-19
Publishing a Diagram as a Graphic
Diagrams can be saved as JPEG (.jpg) or Scalable Vector Graphics (.svg) files for use in
documents, or on web pages.
To publish a diagram as a graphic:
1. Right-click on the surface of the diagram that you want to publish as a graphic, then
choose Publish Diagram...
OR
Click on the surface of the diagram that you want to publish as a graphic, then choose
Model | Publish Diagram...
2. Select destination folder for the graphic file.
3. Enter a name for the graphic file, complete with either the .jpg or .svg file extension.
4. Click OK.
Related Topics
Viewing the Diagram
Minimizing the Number of Diagram Pages
12-20
Importing a UML Model Into JDeveloper
UML models created using other modeling software can be imported into JDeveloper if the
models conform to UML 1.3 and the XMI conforms to the XMI 1.1. DTD.
Currently only class model elements can be imported into JDeveloper, specifically: diagrams,
packages, classes, interfaces, associations (not n-ary associations), generalizations,
dependencies and realizations.
Restrictions
● XMI must be UML 1.3 conformant
● Must be TogetherJ OMG XMI 1.1 or Rational Rose (Unisys) XMI 1.1
● Must import into an empty project
● Multiple inheritance is not supported
● Constraints are not supported
● Diagram information (such as color, size, location, and font) is not imported
● Notes are not supported as this information is saved with the diagram and not the UML
model
● If a datatype is not part of the java.lang package (eg. List) and is not fully qualified (ie.
java.util.List) it will appear on the diagram as if it were a user created datatype
● No association generalization is supported
● No extensions are imported. Anything starting with XMI, tagged values/stereotypes will
be ignored, for example, <Diagram>...</Diagram>
● Only a single XMI file containing the whole UML class model is supported.
12-21
● Although dependencies are displayed in the Navigator pane, they will not be
automatically displayed on the diagram.
Note: If a DTD is specified in the XMI file, you must provide this with the XMI file, or comment it out.
To import a UML model:
1. Right-click the empty project into which you want to import a UML model from those
listed in the Navigator pane, then choose New UML Diagram.
OR
Click the empty project into which you want to import a UML model from those listed in
the Navigator pane, choose File | New, then click UML Diagrams in the left pane of the
New dialog.
2. Select Class Diagrams from XMI Import, then click OK.
3. Select the XML file containing the XMI that has been exported from your other modeling
tool, then click Open.
One class diagram is created for each package in the model, and one diagram is created
for all the other elements that are not in a package, for example, those at project level.
Relationships, such as associations, generalizations and realizations, between packages
in the model will not be drawn on the diagrams.
Related Topics
About Importing a UML Model Into JDeveloper
12-22
New pages on a diagram are created automatically when elements are created on, or dragged
onto, the gray border surrounding the edge of the diagram. Page breaks are displayed as a
dashed blue line on the diagram.
Note: Unused pages are automatically removed from the diagram. For example, if a diagram covers
more than one page, but one of its pages only contains only one element, if that element is moved to
another page, the blank page is automatically removed from the diagram.
Diagram items that are created or moved on the diagram can be automatically aligned, or
'snapped', to the grid lines that are nearest to them, even if the grid is not displayed on the
diagram.
The following topics describe how to lay out diagrams.
● Aligning Elements on a Diagram
● Distributing Elements on a Diagram
● Displaying Page Breaks on a Diagram
● Showing, Hiding and Snapping to the Diagram Grid
● Changing the Size of the Grid Cells
● Creating, Moving and Removing Elbows on a Connector
● Straightening Lines on a Diagram
● Minimizing the Number of Diagram Pages
● Ordering Overlapping Elements on a Diagram
12-23
Related Topics
12-24
Aligning Elements on a Diagram
You can align a set of selected elements both vertically and horizontally on a diagram. You
should align shapes in one direction only, otherwise they will overlap.
To align elements on a diagram:
1. Right-click the diagram elements you want to align on the diagram, then choose Align.
OR
Select the diagram elements you want to align on the diagram, then choose Model |
Align.
2. Select the alignment for the elements:
❍ Select the vertical alignment: None, Top, Middle or Bottom
❍ Select horizontal alignment: None, Left, Center or Right
3. Use the Adjust Size checkboxes to set the size of the selected elements:
❍ Select the Same Height checkbox if you want all the selected elements to have the
same height. The new element height is the average height of the selected
elements.
❍ Select the Same Width checkbox if you want all the selected elements to have the
same width. The new element width is the average width of the selected elements.
4. Click OK.
Related Topics
Distributing Elements on a Diagram
12-25
Ordering Overlapping Elements on a Diagram
Moving a Diagram Element
12-26
You can change the location of elements on a diagram so that they have equidistant vertical
and horizontal spacing.
Note: The outermost selected elements on the vertical and horizontal axes are used as the bounds
for distributing the selected elements. To fine tune the distribution of the selected elements, move
the outermost elements in the selection, then redistribute the elements.
To distribute elements on a diagram:
1. Right-click the diagram elements you want to distribute on the diagram, then choose
Distribute.
OR
Select the diagram elements you want to distribute on the diagram, then choose Model |
Distribute.
2. Select the distribution for the elements:
❍ Select Vertical to create equidistant vertical spacing between elements
❍ Select Horizontal to create equidistant horizontal spacing between elements
3. Click OK.
Related Topics
12-27
Displaying Page Breaks on a Diagram
Page breaks can be displayed, or hidden, on activity diagrams and class diagrams. Page
breaks are displayed as dashed blue lines on the diagram surface.
To display page breaks on the active diagram:
1. Right-click the surface of the diagram on which you want to display page breaks, then
choose Visual Properties.
OR
Click the surface of the diagram on which you want to display page breaks, then choose
Model | Visual Properties.
2. Select the Show Page Breaks checkbox to display page breaks on the active diagram.
3. Click OK.
To display page breaks on new diagrams:
1. Choose Tools | Preferences on JDeveloper's menu.
2. Click UML Diagram in the left pane of the dialog.
3. Click either Activity Diagram or Class Diagram in the left pane of the dialog.
4. Select the Show Page Breaks checkbox to display page breaks on new diagrams.
5. Click OK.
Related Topics
Showing, Hiding and Snapping to the Diagram Grid
12-28
Viewing a Diagram
12-29
Diagram elements that are created or moved on a diagram can be automatically aligned, or
'snapped', to the grid lines that are nearest to them, even if the grid is not displayed on the
diagram.
Note: By default, elements are snapped to the grid on the class diagrams, but not on activity
diagrams.
To display the grid on the current diagram:
1. Right-click the surface of the diagram on which you want to display the grid, then choose
Visual Properties.
OR
Click the surface of the diagram on which you want to display the grid, then choose
Model | Visual Properties.
2. Select the Show Grid checkbox to display the grid on the current diagram.
3. Click OK.
To display the grid on new diagrams:
4. Select the Show Grid checkbox to display the grid on new diagrams.
5. Click OK.
To snap diagram elements to the grid on the current diagram:
12-30
1. Right-click the surface of the diagram on which you want to snap elements to the grid,
then choose Visual Properties.
OR
Click the surface of the diagram on which you want to snap elements to the grid, then
choose Model | Visual Properties.
2. Select the Snap to Grid checkbox to snap diagram elements to the grid.
1. Click OK.
Note: The grid does not have to be displayed on a diagram for elements to be snapped
to it.
To snap diagram elements to the grid on new diagrams:
4. Select the Snap to Grid checkbox to snap elements to the grid on new diagrams.
5. Click OK.
Note: The grid does not have to be displayed on a diagram for elements to be snapped
to it.
Related Topics
Changing the Size of Grid Cells
Viewing the Diagram
12-31
Changing the Size of Grid Cells
The grid cells on the diagram are square, so only one value is required to determine their size.
The value that you specify for the grid cells changes both the height and width of the cells.
To change the size of the grid squares for the current diagram:
1. Right-click the diagram surface of the diagram, the grid size for which you want to
change, then choose Visual Properties.
OR
Click the diagram surface of the diagram, the grid size for which you want to change,
then choose Model | Visual Properties.
2. Enter the grid size for the current diagram in the Grid Size (Diagram Units) field.
Note: To change the grid size, the Snap to Grid checkbox must be checked.
3. Click OK.
To change the size of the grid squares for new diagrams:
4. Enter the grid size for new diagrams in the Grid Size (Diagram Units) field.
Note: To change the grid size, the Snap to Grid checkbox must be checked.
5. Click OK.
Related Topics
12-32
Viewing the Diagram
12-33
Creating, Moving and Removing Elbows on a
Connector
An elbow on a connector (transition, association, generalization, implementation, dependency
or note attachment) enables you to route it around other elements on the diagram.
To add a new elbow to a connector on the diagram:
● Shift+click on the connector where you want to create a new elbow.
To move an elbow on a connector:
1. Press and hold down the mouse button on the connector elbow that you want to move.
2. Drag the cursor to the position to which you want to move the elbow, then release the
mouse button.
Note: To make a line either horizontal, vertical or diagonal, hold down the Ctrl key while
you move the cursor.
To remove an elbow from a connector:
● Shift+click the connector elbow that you want to remove.
Related Topics
Selecting Elements on a Diagram
Straightening Lines on a Diagram
12-34
Lines on a diagram (associations, generalizations, realizations, transitions, dependencies and
note attachments) can be straightened to be horizontal, vertical or 45 degree diagonal.
To straighten a line on a diagram:
● Select the lines that you want to straighten on a diagram, then choose Model | Straighten
Lines.
OR
Right-click the lines you want to straighten on a diagram, then choose Straighten Lines.
To straighten all lines on a diagram:
1. Click the surface of the diagram to ensure no element is selected.
2. Choose Model | Straighten Lines.
OR
Right-click the diagram surface, then choose Straighten Lines.
Related Topics
Creating, Moving and Removing Elbows on a Connector
12-35
Minimizing the Number of Diagram Pages
A diagram might take up an excessive amount of space on the drawing surface. The Minimize
Pages option reduces the number of pages required to display the diagram. The diagram may
be moved automatically so that it is centered on the remaining diagram pages, but the relative
positions of the diagram elements are preserved.
Note: New pages are automatically added to a diagram whenever you create a new diagram
item on, or move a current diagram item to, an area of the diagram window that is outside the
current diagram boundary.
To minimize the number of pages used for the active diagram:
● Right-click the surface of the active diagram, then choose Minimize Pages.
OR
● Click the surface of the active diagram, then choose Model | Minimize Pages.
Related Topics
12-36
You can change the relative order of elements that overlap each other on a diagram. Applying
Bring to Front to an element will ensure that it always appears on top when another element
overlaps it. Similarly, Send to Back will ensure that the element always appears beneath any
overlapping elements.
To bring elements to front of a diagram:
● Right-click the element on the diagram that is overlapped by another element, then
choose Bring to Front.
OR
● Right-click the element on the diagram that is overlapped by another element, then
choose Model | Bring to Front.
To send elements to the back of the diagram:
● Right-click the element on the diagram that is overlapping another element, then choose
Send to Back.
OR
● Click the element on the diagram that is overlapping another element, then choose
Model | Send to Back.
Related Topics
12-37
The following topics describe how to perform basic operations on diagram elements in
JDeveloper.
● Creating Multiple Elements Quickly
● Selecting Elements on a Diagram
● Resizing a Diagram Element
● Cutting, Copying and Pasting a Diagram Element
● Moving a Diagram Element
● Adding a Element to a Diagram
● Changing the Color of a Diagram Element
● Changing the Font of a Diagram Element
● Undoing the Last Graphical Action
Related Topics
12-38
Creating Multiple Elements Quickly
You can quickly create multiple elements of the same type on a diagram.
To quickly create multiple diagram elements of the same type:
● Press and hold down Shift, then click the required element icon on the Component
Palette, then click on the diagram surface to create the element.
Note: The name of the element can be entered while the default element name is
highlighted.
The selected icon will remain selected, allowing you to create multiple instances of the
selected element type, until you select another icon on the Component Palette.
Related Topics
12-39
Elements can be selected on diagram individually, in groups or within a defined area.
To select all elements on the active diagram:
● Choose Edit | Select All.
OR
● Press Ctrl+A.
Note: You can deselect individual elements by holding down Ctrl and clicking on them.
To select specific diagram elements on the active diagram:
1. Ensure you are in select mode by clicking the Select icon on the Component Palette.
2. Press and hold down the Ctrl key, then click the elements on the diagram surface that
you want to select.
To select all elements in a given area of the active diagram:
2. Position the cursor at the corner of the area on the diagram in which you want to select
the elements, then press and hold down the mouse button.
3. Drag the mouse over the required area and release the mouse button. This procedure
selects all elements wholly within the rectangle.
To deselect a selected element in a group of selected elements:
12-40
2. Press and hold down the Ctrl key.
3. Click the element, or elements, on the diagram that you want to deselect.
12-41
Resizing a Diagram Element
You can resize a diagram item by selecting it and dragging the grab bars until the item is the
required size.
On class diagrams, you can also automatically resize all diagram elements so they are
displayed with optimal vertical size to display all the entries in each compartment, and allow
new items to be created 'in-place' in each compartment.
Note: Certain element types also have internal grab bars, that are displayed when an element is
selected. These internal grab bars are for resizing the compartments of those diagram elements.
To resize a diagram element manually:
1. Select the element you want to resize from those displayed on the diagram.
2. Position the cursor on any grab bar on the diagram element, then click hold down the
mouse button.
The cursor will be displayed as a double-headed arrow when it is over a grab bar.
3. Drag the grab bar until the diagram element is the required size, then release the mouse
button.
To automatically resize all class diagram elements to their optimal vertical height:
1. Choose Tools | Preferences, then select UML Diagram | Class Diagrams.

OR
Right-click the diagram surface, with no elements selected, then choose Visual
Properties.
2. Select Automatically Resize Shapes.
Note: If the Automatically Resize Shapes option is enabled, vertical grab bars are
disabled.
3. Click OK.
12-42
Related Topics
12-43
Cutting, Copying, and Pasting a Diagram Element
You can cut, copy and paste elements on a diagram. Each time you copy or cut selected
diagram elements, they are placed on a clipboard, overwriting its previous contents. The
contents of the clipboard can then be pasted back onto the active diagram or another diagram.
Note: To move items over a longer distance, it may be more convenient to use Edit | Cut and Edit |
Paste instead of dragging and dropping them.
To cut a diagram element from a diagram:
● Select the element you want to cut, then click the Cut icon on the JDeveloper
toolbar.
OR
1. Right-click the element you want to cut from the diagram.
2. Choose Cut from the right-mouse menu.
Notes:
When you cut an element from a diagram, the element is not removed from the file
system.
If you cut an element from the diagram that is necessary for the display of another
element, the dependent element is also removed from the diagram.
To copy a diagram element to the clipboard:
● Select the element you want to copy, then click the Copy icon on the JDeveloper
toolbar.
OR
1. Right-click the element you want to copy.
2. Choose Copy from the right-mouse menu.

12-44
To paste the contents of the clipboard onto a diagram:
● Click the Paste icon on the JDeveloper toolbar.
OR
1. Position the cursor where you want to paste the clipboard contents.
2. Choose Paste from the right-mouse menu.
Related Topics
12-45
You can move one or more diagram elements at the same time by selecting the elements and
dragging them on the diagram surface. This is the easiest way of moving elements a short
distance on a diagram. To move elements over a longer distance, it may be more convenient to
use Edit | Cut and Edit | Paste.
To move diagram elements:
1. Select the element, or elements, to be moved from those displayed on the diagram.
2. Press and hold down the mouse button on the selected elements.
3. Drag the selected elements to their new position.
4. Release the mouse button.
Note: If an element is moved to a position where it overlaps another element, the

elements are displayed on top of one another. You can specify which element is
displayed at the front by right-clicking the element and choosing Bring to Front.
Related Topics
12-46
Business components, classes from existing Java libraries and model elements can be added
to a diagram.
Classes can be included on a diagram from both compiled Java class files and Java source
files. If you include a Java source file on a diagram, it is represented on the diagram as a
modeled Java class which has been reverse-engineered from the class definition, and
synchronized with its source file. If an included class is from a compiled class file, the resulting
modeled Java class shown on the diagram is a read-only representation of that class.
On activity diagrams, you cannot reuse transitions, pseudostates, subactivity states, or other
secondary elements. Also, you cannot reuse an object flow state, but you can reuse the
classifier in state that it is based on and create a new object flow state against it. In the case of
activities, the suffix(reuse) is added to its name. For example, Ship Order(reuse).
Note: Only activity model elements can be included on activity diagrams, and only class model
elements can be included on class diagrams.
The list of model elements available to be included on the diagram is derived from the Model
Path in the project's setting. For more information, see Configuring a Project for Modeling. The
list of library elements available to be included on the diagram is derived from the project's
Source Path or Class Path.
To add an element to a diagram:
1. Select the element you want to include from those displayed in the Navigator pane, then
drag it onto the diagram.
OR
Right-click the diagram surface onto which you want to include an element from your
model, then choose Add to Diagram...
OR
Click the diagram surface onto which you want to include an element from your model,
then choose Model | Add to Diagram...
2. Select the element you want to include on the diagram.
12-47
3. Click OK.
Related Topics
12-48
Changing the Font of a Diagram Element
You can change the font of specific diagram elements, or all new elements of a specific
element type on a diagram.
To change the font of a selected element:
1. Right-click the element the font of which you want to change, then choose Visual
Properties...
OR
Select the element the font of which you want to change, then choose Model | Visual
Properties...
2. Select the Font node.
3. Select the font details for the element type in the right-hand pane.
❍ Choose the font name from those listed in the Font dropdown list.
❍ Select the point size of the font from those sizes listed in the Size dropdown list.
❍ Select whether to apply a style to the font: bold and/or italic.
An example using the current font settings is displayed in the Example area. To view the
font example at actual size, rather than the default of 12 point, select the Actual font size
checkbox.
To change the default font of new diagram elements:
1. Choose Tools | Preferences from the JDeveloper menu.
2. Select the UML Diagram node in the left-hand pane of the dialog.
3. Select either Class Diagram or Activity Diagram.
12-49
4. Select the element type for which you want to specify the default font.
5. Select the Display node for that element type.
6. Select the Font node.
7. Select the font details for the element type in the right-hand pane.
❍ Choose the font name from those listed in the Font dropdown list.
❍ Select the point size of the font from those sizes listed in the Size dropdown list.
❍ Select whether to apply a style to the font: bold and/or italic.
An example using the current font settings is displayed in the Example area. To view the
font example at its actual size, check the Actual font size checkbox.
Related Topics
Changing the Color of a Diagram Element
12-50
You can change the color of elements on a diagram.
To change the color of a selected element:
1. Right-click the element the color of which you want to change, then choose Display
Properties...
OR
Select the element the color of which you want to change, then choose Model | Visual
Properties...
2. Select the Colors node.
3. Click the Line Color, Fill Color or Font Color button, depending on which one you want
to change.
4. Select the color from those displayed, or click Edit to choose a different color.
❍ Enter the RGB value of the required color in the RGB values section.
❍ Click on the required base color in the Color Selector, then move the pointer to the
position on the color bar to the right of the Color Selector to choose a shade of the
selected color.
The color that will be used for that element type is displayed in the Selected Color box.
To change the default color for new diagram elements:
2. Select the Diagram node in the left-hand pane of the dialog.
3. Select either Class Diagram or Activity Diagram.
12-51
4. Select the element type the default color of which you want to specify.
5. Select the Display node for that element type.
6. Select the Colors node.
7. Select the line color and fill color for the element type in the right-hand pane.
❍ Enter the RGB value of the required color in the RGB values section.
❍ Click on the required base color in the Color Selector, then move the pointer to the
position on the color bar to the right of the Color Selector to choose a shade of the
selected color.
The color that will be used for that element type is displayed in the Selected Color box.
Related Topics
12-52
Undoing the Last Graphical Action
You can undo and redo the most recent graphical actions you have made in a diagram.
Graphical actions are actions that change the appearance of elements on the diagram surface,
such as:
● cutting and pasting elements on class diagrams
● altering the position and size diagram elements
● changing the font, color, and line width of diagram elements
For example, if you resize an element on the diagram, you can return the element to its
previous size using undo.
Note: Any change to a diagram element that is not purely graphical, such as changing the properties
of that element, cannot be undone. Changing the properties of an element also prevents any
previous graphical changes from being undone.
To undo the last graphical action on a diagram:
● Choose Edit | Undo from JDeveloper's menu.
OR
● Click the Undo icon on JDeveloper's toolbar.
To redo an previously undone graphical action on a diagram:
● Choose Edit | Redo from JDeveloper's menu.
OR
● Click the Redo icon on JDeveloper's toolbar.
12-53
Related Topics
12-54
The goal of modeling Java classes using the Class Modeler is to capture the essential
information requirements of the system (the classes in the problem domain, their properties and
their inter-relationships). You can generate Java source code from these modeled elements,
which can then be augmented with business logic to complete your Java application. For more
information on modeling Java classes, see Creating a Model of Java Classes.
When Java source code is generated from class model elements, or when class model
elements are reverse-engineered from Java source code, the model elements and the source
code become 'synchronized'. Once 'synchronized', changes to the Java source code are
reflected in the modeled elements, and changes to the model are reflected in the Java source
code. For more information, see Generating and Reverse-Engineering Java Source Code.
Using a model of Java classes you can:
● model the elements in your system, together with their properties (attributes) and
behavior (operations)
● create interfaces to define the services that the elements provide
● create relationships between elements to show how the elements are associated
● create inheritance structures between classes
● define the implementation of interfaces.
Note: Each diagram presents a visualization of just one aspect of the modeled system; collectively,
all the class diagrams in a model could present visualizations of the complete system.
Related Topics
12-55
12-56
The notation used on class diagrams created in JDeveloper is illustrated below.
Java classes and interfaces are represented on class diagrams as boxes divided into four
horizontal compartments. By default, interfaces do not display the inner classes compartment.
Entity objects represented on class diagrams do not have an inner classes compartment. The
operations compartment of modeled entity objects are divided into two categories:
«Business» and «Framework». User-defined operations are displayed under the
12-57
«Business» category and operations generated by the BC4J framework are displayed under
the «Framework» category.
Note: If a compartment is not large enough (horizontally or vertically) to display its entire
contents, an ellipsis (...) is displayed in the lower right corner of the compartment.
Stereotypes
Each type of class, or association, on a class diagram is identified by a stereotype which is

displayed inside guillemets (« and ») at the top of the class box, or above an association line.
These stereotypes are as follows (click on the name for more information on that type):
● «java class»
● «interface»
● «package»
● «entity object»
● «domain»
● «constraint»
● «association»
● «bc4j association»
Code Generation
When Java code has been generated for a modeled Java class or interface, or if a modeled
Java class or interface were reverse-engineered from a Java class, an icon is displayed in the
top left corner of the modeled element on the diagram.
Attribute and Operation Visibility
All attributes and operations display symbols to represent their visibility. The visibility symbols
are:
12-58
Symbol Attribute or Operation
¶ Package
+ Public
- Private
# Protected
Related Topics
Modeling Business Components
Changing the Way Class Diagram Elements are Displayed
12-59
The following topics describe how to create a model of Java classes.
● Creating a New Class Diagram
● Modeling a Java Class
● Modeling a Java Interface
● Modeling an Inner Java Class or Inner Java Interface
● Modeling a Java Attribute
● Modeling a Java Operation
● Modeling a Realization Relationship
● Modeling a Generalization
● Modeling an Association Between Classes
● Modeling a Dependency
● Modeling a Package
● Creating and Attaching a Constraint to a Diagram Element
● Creating and Attaching a Note to a Diagram Element
● Generating Java Source Code from a Modeled Class
There are many ways in which you can create a model of Java classes. One such way is
12-60
illustrated below.
Related Topics
Modifying Modeled Java Classes
12-61
Modeling a Java Class
Java classes, together with their attributes and operations, can be modeled on any class
diagram in JDeveloper. For more information on creating a class diagram, see Creating a New
Diagram.
To model a Java class on a class diagram:
1. Click the Java Class icon on the Component Palette.
2. To create the class at the default size, click on the diagram where you want to create the
class.
OR
To create the class at a different size, click on the diagram, drag the class box to the
desired size, then release the mouse button.
3. Enter the name of the class, then press Enter.
4. Double-click the modeled class to specify more of its properties.
OR
Right-click the modeled class, then choose Properties to specify more of its properties.
Related Topics
About Modeled Java Classes
Modeling an Inner Java Class or Inner Java Interface
Modeling a Java Attribute
Modeling a Java Operation
Changing the Properties of a Class Model Element

12-62
Java Class - General Properties
12-63
Modeling a Java Interface
A modeled Java interface defines a set of operations that can be implemented by one or more
Java classes. Interfaces can be modeled on any class diagram in JDeveloper. For more
information on creating a class diagram, see Creating a New Diagram.
To model a Java interface on a class diagram:
1. Click the Java Interface icon on the Component Palette.
2. To create the Java interface at the default size, click on the diagram where you want to
create the Java interface.
OR
To create the Java interface at a different size, click on the diagram, drag the Java
interface box to the desired size, then release the mouse button.
3. Enter the name of the Java interface, then press Enter.
4. Double-click the modeled Java interface to specify more of its properties.
OR
Double-click the modeled Java interface, then choose Properties to specify more of its
properties.
Related Topics
About Modeled Java Interfaces
12-64
Interface - General Properties
12-65
Modeling an Inner Java Class or Inner Java
Interface
To create an inner Java class or inner Java interface, you must first have modeled the Java
class, or Java interface, of which the inner class or interface is to be a member.
Note: If the compartment containing inner classes and inner interfaces is not displayed on a
modeled class or interface, right-click the modeled element and choose Visual Properties. Select
the Show Inner Classes checkbox, then click OK.
To model an inner Java class or inner Java interface:
1. Model the Java class or Java interface that you want to be a member of another Java
class or Java interface.
2. Double-click on the class that you want to be a member of another class.
3. Enter the name and package name of the class of which you want this class to be a
member in the Namespace field.
Note: The name of the owning class must be qualified with the name of the owning
class' package. For example, to make the Java class OrderState an inner class of the
Java class Order which is in package OrderEntry, the inner class must have its
package name set to OrderEntry::Order on the diagram.
To create an inner class or inner interface on the owning class or interface:
1. Select the modeled class or interface on the diagram for which you want to add an inner
class or inner interface.
2. Click on the inner classes compartment of the modeled class or interface, immediately
below any existing inner classes or inner interfaces.
Note: If this is the first inner class or inner interface for this class or interface, click
directly below the «inner classes» or «inner interfaces» labels in the inner classes
compartment of the class or interface.
3. Enter the name of the inner class or inner interface.
12-66
4. Press Enter.
Related Topics
About Modeled Inner Java Classes and Inner Java Interfaces
12-67
Attributes representing Java fields, can be added to modeled Java classes and interfaces on
class diagrams.
Note: You can change how attributes are displayed on a diagram, for more information see
Changing the Way Class Diagram Elements are Displayed.
To model an attribute on a class diagram:
● Double-click the modeled class on the diagram, or on the Navigator pane, for which you
want to add an attribute. Then click on the Attributes page of the Class Properties
dialog, click Add then enter the attribute name and details.
OR
1. Click on the attributes compartment of the modeled class for which you want to add an
attribute, immediately below any existing attributes.
Note: If there is no space below the existing attributes on the modeled class, drag the
grab bar below the attributes compartment to make the compartment larger.
2. Enter the visibility (+ (public), - (private) or # (protected) for Java classes), name and
datatype of the attribute. For example:
+ name : java.lang.String
If no visibility character is provided for an attribute, a default of package (¶) visibility is

used for the attributes of Java classes. Attributes of Java interfaces can only have public
visibility (+).
Note: If an attribute type from the java.lang package is entered without a package
prefix, for example, String or Long, an attribute type prefix of java.lang. is
automatically added.
If no type is given for an attribute, a default type of 'String' (java.lang.String) is

used. Visibility is defaulted to Package for Java classes, and Public for Java interfaces.
To change the visibility, or any other property, of the attribute, double-click the class on
the diagram or on the Navigator pane, then change the details of the attribute.
12-68
3. Press Enter.
Related Topics
About Modeled Java Attributes
Changing the Properties of a Diagram Element
Attributes Properties
12-69
Operations, representing Java methods, can be added to modeled Java classes and interfaces
on class diagrams.
To model an operation on the class diagram:
● Double-click the modeled class on the diagram, or on the Navigator pane, for which you
want to add an operation. Then click on the Operations page of the Class Properties
dialog, click Add then enter the operation name and details.
OR
1. Click on the operations compartment of the modeled class for which you want to add an
operation, immediately below any existing operations.
Note: If there is no space below the existing operations on the modeled class, drag the
grab bar below the operations compartment to make the compartment larger.
2. Enter the visibility (+ (public), - (private) or # (protected) for Java classes), name, and
optionally, the parameter types and names, and return type of the operation. The
operation return type must be preceded by a colon (:). For example:
+ getName(String CustNumber) : java.lang.String
If no visibility character is provided for an operation on a Java class, a default of package

(¶) visibility is used. Operations on Java interfaces can only have public visibility (+).
Note: If a return type from the java.lang package is entered without a package prefix,
for example, String or Long, a return type prefix of java.lang. is automatically
added is Java has been generated for the operation's class.
If no parameter types are provided, then the operation will be defined with no
parameters. A return type is not required for a constructor. If no return type is specified, a
default return type of void is used. The visibility of operations is defaulted to Package.
To change the visibility, or any other property, of the operation, double-click the class on
the diagram or on the Navigator pane, then change the details of the operation.
3. Press Enter.
12-70
Related Topics
About Modeled Java Operations
Changing the Way Class Diagram Elements are Displayed
Operations Properties
12-71
Modeling an Association Between Classes
An association is a relationship between two classes. There are three types of association:
simple association, weak aggregation and strong aggregation (composition).
You can create associations between two Java classes, between two interfaces or from a Java
class to a Java interface.
To create an association between two elements:
1. Click the icon for the association you want to create, from those listed on the Component
Palette:
❍ 1..* Association
❍ Directed 1..1 Association
❍ Directed 1..* Association
❍ Directed Strong Aggregation
Note: The navigability and multiplicity of an association end can be changed after
it has been created.
2. Click the class at the 'owning', or 'from', end of the association.
3. Click the class at the 'to' end of the association.
4. Click the association line on the diagram, then click the text fields adjacent to the
association to enter:
❍ a role name for each end of the association

❍ the multiplicity for each end of the association
❍ a verb describing the association
To define an association end as weakly or strongly aggregated:
1. Right-click the association the aggregation of which you want to define.
12-72
OR
Double-click the association the aggregation of which you want to define.
2. Choose Properties...
3. Click the Association Ends tab to display the association end properties.
4. Select the name of the association end the aggregation of which you want to change.
5. Select Aggregation (Weak) or Aggregation (Strong) from the Aggregation dropdown list.
6. Click OK.
Related Topics
About Modeled Associations
Association - General Properties
Association - Association Ends Properties
12-73
Modeling a Generalization
A generalization is the relationship between a more specific element and a less specific
element, and defines the inheritance structure in the model. Generalization relationships can be
created between two Java classes, between two Java interfaces or between two entity objects.
Note: Only one generalization relationship can be modeled from a Java class or entity object
because multiple inheritance is not supported by Java. More than one generalization can be
modeled from a Java interface.
To create a generalization between two classes, interfaces or entity objects:
1. Click the Generalization icon on the Component Palette.
2. Click the specialized class, interface or entity object in the relationship.
3. Click the generalized class, interface or entity object in the relationship.
The arrow head on the generalization line always points toward the generalized element
and away from the specialized element. It is common practice to position a generalized
element above its specialized element on the diagram.
Related Topics
About Modeled Generalizations
Generalizations Properties
12-74
Modeling a Realization Relationship
A realization relationship identifies which Java class, or classes, implement a Java interface.
To model an implementation between a Java interface and a Java class:
1. Click the Realization icon on the Component Palette.
2. Click the Java class you want to implement the Java interface.
3. Click the Java interface you want to implement.
The arrow head on the realization line always points toward the Java interface and away
from the implementing Java class. It is common practice to position the Java interface
above its implementing Java class on the diagram.
Note: You can copy operation signatures from a modeled interface to its modeled
implementing Java class by holding down Ctrl, then dragging the operations from the
interface to the implementing class.
Related Topics
About Modeled Realization Relationships
Realizations Properties
12-75
Modeling a Dependency
Dependencies can be added to class diagrams to document where one element has a
dependency on another.
To model a dependency between two diagram elements:
1. Click the Dependency icon on the Component Palette.
2. Click the element at the 'from' end of the dependency association.
3. Click the element at the 'to' end of the dependency association.
Information on a dependency between elements can be recorded by creating and

attaching a constraint or note to the dependency.
Related Topics
About Modeled Dependencies
Creating and Attaching a Note to a Diagram Element
Creating and Attaching a Constraint to a Diagram Element
12-76
Modeling a Package
Packages can be modeled on class diagrams to show the dependencies between an element
and another package. Only dependencies can be created to, or from, a modeled package on a
diagram.
To model a package:
● Drag a package from the Navigator pane, and drop it on the diagram.
OR
1. Click the Package icon on the Component Palette.
2. To create the package at the default size, click on the diagram where you want to create
the package.
OR
To create the package at a different size, click on the diagram, drag the package box to
the desired size, then release the mouse button.
3. Enter the name of the package, then press Enter.
Note: A package name cannot be changed after it has been created.
The package is created inside the package in which the diagram resides.
Note: You can display a class diagram for the package by either double-clicking the package, or by
right-clicking the package and choosing Drill Down. If a class diagram does not already exist of the
package, a new diagram is created for the package.
Related Topics
About Packages
12-77
Creating and Attaching a Constraint to a Diagram
Element
Constraints can be created on a class diagram to document a required condition relating to a
diagram element.
To model a constraint on a class diagram:
1. Click the Constraint icon on the Component Palette.
2. To create the constraint at the default size, click on the diagram where you want to
create the constraint.
To create the constraint at a different size, click on the diagram, drag the constraint box
to the desired size, then release the mouse button.
3. Enter the text for the constraint, then click OK.
To attach a constraint to an element on a class diagram:
1. Click the Attach icon on the Component Palette.
2. Click on the modeled constraint.
3. Click on the element to which you want to attach the constraint.
Related Topics
About Modeled Constraints
12-78
Creating and Attaching a Note to a Diagram Element
A note is a graphical object on a diagram containing textual information. Notes are often used
for adding comments to a diagram or the elements on a diagram. A note can be attached to
one or more elements. A note is stored as part of the current diagram and not as a separate file
system element.
To model a diagram note:
1. Click the Note icon on the Component Palette.
2. To create the note at the default size, click on the diagram where you want to create the
note.
OR
To create the note at a different size, click on the diagram, drag the note box to the
desired size, and release the mouse button.
3. Enter the text for the note.
To attach a note to an element on a diagram:
1. Click the Attach icon on the Component Palette.
2. Click on the note.
3. Click on the element to which you want to attach the note.
12-79
Modifying Modeled Java Classes
The following topics describe how to modify class model elements.
● Changing the Properties of a Class Model Element
● Converting a Modeled Java Class to a Modeled Java Interface
● Converting a Modeled Java Interface to a Modeled Java Class
● Adding Javadoc Comments to a Class Model Element
● Displaying Related Elements on a Diagram
● Deleting a Model Element
● Moving an Element Between Class Models
● Changing the Display of Elements on a Class Diagram
Related Topics
Generating and Reverse-Engineering Java Source Code
12-80
The properties of class model elements can be changed after they have been created.
Class names, packages (except for modeled entity objects), attribute names and return types
and operation signatures can all be changed by clicking on them on the diagram, then entering
the new details. The visibility of attributes and operations, together with the other properties of
class model elements can be changed using the element's Properties dialog.
To change the properties of a selected element:
1. Right-click the element on the diagram, or in the Navigator pane, the properties for which
you want to change, then choose Properties...
OR
Select the element on the diagram, or in the Navigator pane, the properties of which you
want to change, then choose Edit | Properties...
OR
Double-click, the element on the diagram, or in the Navigator pane, the properties for
which you want to change.
2. Make any changes you require. If a property cannot be changed, a message informs you
of the reason.
3. Select OK.
Related Topics
Changing the Display of Elements on a Class Diagram
12-81
Converting a Modeled Java Class to a Modeled Java
Interface
You can convert a modeled Java class into a modeled Java interface either on the diagram, or
in the generated Java code for the class.
Rules for converting modeled Java classes to modeled Java interfaces:
● If a generalization exists between two classes, if the specialized class is converted to an

interface, the generalization is removed.
● If a generalization exists between two classes, if the generalized class is converted to an

interface, the generalization becomes a realization.
● If a realization exists between a class and an interface, if the class is converted to an

interface, the realization becomes a generalization.
If you convert a class to an interface, attributes and operations that were defined on the class
will be explicitly defined as public in the interface, even though they are implicitly defined as
public final static in the model.
To convert a modeled Java class to a modeled Java interface on the diagram:
● Select the modeled Java class you want to convert to a modeled Java interface, then
choose Model | Convert to Interface.
OR
● Right-click the modeled Java class you want to convert to a modeled Java interface, then
choose Convert to Interface.
Related Topics
Converting a Modeled Java Interface to a Modeled Java Class
12-82
Converting a Modeled Java Interface to a Modeled
Java Class
You can convert a modeled Java interface into a modeled Java class either on the diagram, or
in the generated Java code for the interface.
Rules for converting modeled Java interfaces to modeled Java classes:
● If a generalization exists between two interfaces, if the specialized interface is converted

to a class, the generalization becomes a realization.
● If a generalization exists between two interfaces, if the generalized interface is converted

to a class, the generalization is removed.
● If a realization exists between an interface and a class, if the interface is converted to a

class, the realization becomes a generalization.
● If a realization exists between an interface and a class, but the class is also a
specialization of another class, if the interface is converted to a class, the realization is
removed as multiple inheritance for class is not supported.
When you convert an interface to a class, the attributes of the class will be explicitly defined as
public static final, and operations will be defined as public abstract, even if this was only implied
when the class was an interface.
To convert a modeled Java interface to a modeled Java class on the diagram:
● Select the modeled Java interface you want to convert to a modeled Java class, then
choose Model | Convert to Class.
OR
● Right-click the modeled Java interface you want to convert to a modeled Java class, then
choose Convert to Class.
12-83
Related Topics
Converting a Modeled Java Class to a Modeled Java Interface
12-84
Adding Javadoc Comments to a Class Model
Element
Comments can be defined for modeled Java classes, Java interfaces, attributes, operations
and association ends. These comments are persisted as Javadoc comments in the generated
Java code for the model elements when Java is generated for those elements.
Note: Javadoc entered for Java class or Java interface is displayed immediately above the class or
interface definition in the generated Java.
To enter Javadoc comments for a Java class or Java interface:
1. Double-click the Java class or Java interface, either on the diagram or in the Navigator
pane, for which you want to enter Javadoc comments.
2. Click the Javadoc tab on the element's properties dialog.
3. Enter the Javadoc for the element.
If you want to display a large editor window for entering comments, click the Edit...
button.
4. Click OK.
To enter Javadoc comments for an attribute or an operation:
1. Double-click the Java class or Java interface, either on the diagram or in the Navigator
pane, an attribute of operation of which you want to enter Javadoc comments against.
2. Click the Attributes or Operations tab.
3. Select the attribute or operation for which you want to enter Javadoc comments.
4. Click the Javadoc... button.
5. Enter the Javadoc for the element.
12-85
6. Click OK.
To enter Javadoc comments for an association:
1. Double-click the association for which you want to enter Javadoc comments.
2. Click the Association Ends tab.
3. Select the association end for which you want to enter Javadoc comments.
4. Click the Javadoc... button.
5. Enter the Javadoc for the association end.
6. Click OK.
Related Topics
Generating Java Source Code From a Modeled Class
12-86
Displaying Related Elements on a Diagram
Elements related to those currently displayed on the diagram can be brought onto the diagram.
Related elements include elements that:
● generalize, or are generalized by, the selected element

● implement, or are implemented by, the selected element
To display related elements on a diagram:
● Select the element for which you want to display related elements from those displayed
on the diagram, then choose Model | Show | Related Elements.
OR
● Right-click the element for which you want to display related elements from those
displayed on the diagram, then choose Show Related Elements.
Related Topics
Displaying the Java Class Implementation for an Entity Object
12-87
Deleting a Model Element
Elements that have become obsolete can be deleted. When you remove an element from a
diagram, you can either:
● remove the element from the diagram, but not from the model and the file system
● remove the element from the diagram, the model and from the file system
Notes:
● If you delete an element from the file system, the element is also removed from any
diagrams on which it appears.
● File | Remove from IDE menu option is not available for model elements.
To remove an element from the diagram:
● Right-click the diagram element that you want to remove from the diagram, then choose
Remove from Diagram.
OR
● Select the diagram element that you want to remove from the diagram, then choose File |
Cut from JDeveloper's menu.
To remove an element from the diagram, the model and the file system:
● Right-click the diagram element that you want to delete, then choose Delete from Model.
OR
● Select the element you want to delete, from those listed in the Navigator pane, then
choose File | Erase from Disk.
Related Topics
12-88
About Deleting Class Model Elements
12-89
Moving an Element Between Class Diagrams
A modeled element can be included on more than one diagram. To do this you can either drag
and drop the element from one diagram to another, or add the modeled element to a diagram.
Note: You can share element definitions between models of Java classes by adding the root
location of the package hierarchy containing the element you want to add to a model to the Model
Path in the model's project settings. When the Model Path is changed, the Navigator pane is
automatically updated, and model elements may be added or removed from the project depending
on what is visible to the project.
Related Topics
12-90
Changing the Way Class Diagram Elements are
Displayed
You can specify which properties of selected diagram elements are displayed, and which
properties are displayed by default on new diagram elements.
To specify how properties are displayed on selected elements:
1. Right-click the diagram element the display of which you want to specify.
2. Choose Visual Properties...
3. Choose which details you want to display in the name compartment, and which other
compartments you want to display.
Note: To change the way attributes and operations are displayed on Java classes,
interfaces and entity objects, click the Attributes or Operations node in the tree.
4. Select the element display preferences for the selected element.
5. Click OK.
To specify how properties are displayed on new elements:
2. Select UML Diagram | Class Diagram in the left pane of the dialog.
3. Select the element type (Java Class, Interface, Domain, Entity Object) the display of
which you want to specify.
4. Select Shape in the left pane of the dialog.
Note: To change the way that attributes and operations are displayed on Java classes,
interfaces and entity objects, click the Attributes or Operations node in the tree.
12-91
5. Select the element display preferences for the element type.
6. Click OK.
Related Topics
12-92
Generating and Reverse-Engineering Java Source
Code
Java source files can be generated from modeled Java classes created in JDeveloper.
Modeled Java classes and interfaces can also be reverse-engineered from existing Java
source files.
Java Class Generation
Java class and interface definitions can be generated from Java classes and interfaces
modeled on a class diagram. Class attributes are generated as fields, operations are generated
as method stubs. Association ends for navigable associations are generated as either
protected fields or protected arrays depending on their multiplicity. Generalizations are
generated as an extends statement, whereas realization relationships are represented as
implements statements.
Note: Whenever Java source code is generated from modeled elements the created source
files are automatically navigated to in the Navigator pane.
Java Source Code Reverse-Engineering
Many parts of a class model can be reverse-engineered from Java source code. Classes (and
inner classes), interfaces (and inner interfaces), attributes, operations, generalizations and
certain associations can all be reverse-engineered.
If a reverse-engineered Java class implements an interface already modeled on the diagram,

the realization relationship is automatically modeled between the class and the interface.
To reverse-engineer an association between classes, the field representing the association in

the Java source must be preceded by a Javadoc tag of @association
<association_name> destination_classname. If the type of the field in the Java source
is a collection type (for example, List), then the multiplicity of that association end will be
defined as * in the modeled association. For example, to define an association between
classes Order and OrderItem, both in package orderEntry, the following Javadoc tag
must be used:
/**
*
12-93
*@association <orderEntry.OrderEntryItems> orderEntry.OrderItem
*/
private List m_items;
Note: Whenever modeled elements are reverse-engineered from Java source code the
modeled elements are automatically navigated to in the Navigator pane.
Model and Code Synchronization
When a modeled Java class or interface is used to generate a Java source file, or when
modeled elements are reverse-engineered from Java source, the modeled Java class and
generated Java source file become 'synchronized'. Synchronization of models with generated
source files ensures that any changes made to the model are automatically made to the
source, and vice versa.
Every time you switch views (from diagram to code, or from code to diagram), or do an explicit
save, any changes made on the diagram are automatically reflected in the code, and similarly,
any changes made in the code are automatically reflected on the diagram.
Note: If you have generated Java source from a modeled element in the Class Modeler, then
rename, move or delete the generated Java source file, the Class Modeler will regenerate a skeleton
Java class from the modeled element when you next modify that model element's definition,
however, under certain conditions this may not happen. Before renaming or moving a generated
Java source file it is advised that you first back up your source files.
Code Generation Icon
Related Topics
Generating Java Source Code From a Class Model

12-94
Reverse-Engineering a Java Source File
About Reorganizing Generated Java Source Code
Adding Javadoc Comments for a Class Model Element
12-95
Reverse-Engineering Java Source Code
Modeled Java classes and Java interfaces can be reverse-engineered from existing Java
source code.
To reverse-engineer Java source code to modeled elements:
1. Click the Java source file that you want to reverse-engineer.
Note: The Java source file that you want to reverse-engineer must be visible to the
current project. To make Java source files visible from a certain location, add that
location to the Source Path in the project settings.
2. Drag the selected Java source file onto an open class diagram.
Java source files can contain multiple Java class and Java interface definitions. All class
and interface definitions in a Java source file are reverse-engineered to individual
modeled Java classes and Java interfaces. For more information on reverse-engineering
Java source code, see Generating and Reverse-Engineering Java Source Code.
Note: If you add to a diagram a Java class that had previously only been defined in a Java source
file, a modeled Java class is automatically reverse-engineered and displayed on the active class
diagram. For more information on including Java classes on a diagram, see Including a Java Class
on a Diagram.
Related Topics
12-96
Generating Java Source Code from a Modeled Class
Java source code can be generated from modeled Java classes and Java interfaces.
To generate Java source for a class model element:
● Right-click the Java class or Java interface for which you want to generate Java source
code, then choose Generate Java.
OR
● Select the Java class or Java interface for which you want to generate Java source code,
then choose Model | Generate | Generate Java.
1. Right-click the Java class or Java interface for which you want to generate Java source
code, then choose Properties.
2. Select On (synchronized) from the Java Generation dropdown list.
3. Click OK.
For more information on generating Java source code, see Generating and Reverse-
Engineering Java Source Code.
To generate Java source code for an entire diagram:
● Right-click the class diagram that is displaying the Java classes and Java interfaces for
which you want to generate Java source code, then choose Generate Java for Diagram.
OR
● Click the surface of the class diagram that is displaying the Java classes and Java
interfaces for which you want to generate Java source code, then choose Model |
Generate | Generate Java for Diagram.
12-97
To generate Java source code for all newly created Java classes and Java interfaces:
● Right-click on the class diagram that you want to generate Java source code for newly
created elements, then choose Automatically Generate Java.
OR
● Click on the surface of the class diagram that you want to generate Java source code for
newly created elements, then choose Model | Generate | Automatically Generate
Java.
Java source code will be generated automatically for all new Java classes and Java
interfaces that are then created on the diagram.
Related Topics
12-98
Navigating to Code Generated for an Element
You can display the Java source code for a modeled Java class or interface if Java source
code has been generated from that modeled element, or if the modeled element has been
reverse-engineered from Java source code.
To display the Java source code generated for a model element:
● Right-click the element on the diagram the source code for which you want to display,
then choose Go to Source.
OR
● Select the element on the diagram the source code for which you want to display, then
choose Model | Go to Source.
The generated Java source file for the modeled Java class or is displayed in the Code
Editor.
Related Topics
12-99
Transforming Java Classes to Entity Objects
Modeled Java classes and Java interfaces can be transformed into entity objects. Associations
between classes or interfaces, realizations and any inheritance structure modeled using
generalizations are also transformed.
Note: If an association between two Java classes is transformed, the classes at both ends of the
association are also transformed. Also, if a class extends another class using a generalization, both
the specialized and generalized classes are transformed.
If you transform the same elements more than once, the entity objects to which they are
transformed are updated rather than new ones created.
To transform modeled Java classes to entity objects:
● Select the Java classes and/or Java interfaces that you want to transform to entity
objects from those displayed either on a class diagram, or in the Navigator pane, then
choose Model | Transform to Business Components.
OR
● Right-click the Java classes and/or Java interfaces that you want to transform to entity
objects from those displayed on a class diagram, then choose Transform to Business
Components.
The submenu provides three options for the transformation:

❍ Model Only—Creates the new entity objects only in the Navigator pane, not on the
diagram.
❍ Same Diagram—Creates the new entity objects on the same diagram as the
classes on which they are based.
❍ New Diagram—Creates the new entity object on a new class diagram. You will be
prompted for the name of the new diagram before one is created. The owning
package for the new diagram is defaulted to the owning package of current
diagram, although this can be changed if you want your new diagram to be located
in a different package.
Note: A valid database connection is required for the creation of entity objects. If a
valid database connection is not currently defined in JDeveloper, you will be
prompted to create one before continuing.
12-100
Related Topics
12-101
Creating an Entity Object from a Modeled Java
Class
Entity objects can be created based on the definitions of Java classes modeled in JDeveloper.
Note: Java classes and Java interfaces are transformed into entity objects. Associations between
classes are transformed to entity object associations.
To create an entity object only in the Navigator pane, from a modeled Java class:
● Right-click the modeled Java class from which you want to create an entity object, then
choose Transform to Business Components | Model Only.
OR
● Select the modeled Java class from which you want to create an entity object, then
choose Model | Transform to Business Components | Model Only.
To create an entity object, from a modeled Java class, on the current diagram:
choose Transform to Business Components | Same Diagram.
OR
choose Model | Transform to Business Components | Same Diagram.
To create an entity object, from a modeled Java class, on a new diagram:
choose Transform to Business Components | New Diagram.
OR
choose Model | Transform to Business Components | New Diagram.
12-102
Related Topics
Creating a Model of Business Components
12-103
Modeling business components, such as entity objects, captures the basic data requirements of
the system. Entity objects form the semantic building blocks of an information system,
representing the classes that characterize the problem domain. They are objects that users and
domain experts nominate as relevant for the operation of the business.
Whenever an entity object is modeled, the underlying Java source code implementation and
XML metadata definition of the entity object is also created.
Using a model of entity objects you can:
● encapsulate a set of data items (attributes) and the methods that define the behavior of
the class
● visualize entity objects, domains and the associations that define the inter-relationships
between them
Entity objects are part of the Oracle Business Components framework. For more information on
Oracle Business Components, see What Are Business Components?
Related Topics
12-104
The following topics describe how to create a model of business components.
● Creating a New Class Diagram
● Modeling an Entity Object
● Modeling an Entity Object Attribute
● Modeling an Entity Object Operation
● Modeling a Domain
● Modeling an Association Between Business Components
● Modeling a Generalization
● Modeling a Dependency
● Creating and Attaching a Constraint to a Diagram Element
Related Topics
Modifying Modeled Business Components
Reverse-Engineering Table Definitions to Business Components
Extending Your Modeled Entity Objects

12-105
12-106
Modeling an Entity Object
Entity objects can be modeled on any class diagram.
Note: To model an entity object on a class diagram requires a valid database connection
defined in JDeveloper. If you don't have a valid database connection in JDeveloper, you will be
prompted to create one before continuing.
To model an entity object on the diagram:
1. Click the Entity Object icon on the Component Palette.
2. To create the entity object at the default size, click on the diagram where you want to
create the entity object.
OR
To create the entity object at a different size, click on the diagram, drag the entity object
box to the desired size, then release the mouse button.
3. Enter the name of the entity object, then press Enter.
4. Double-click the modeled entity object to specify more of its properties.
OR
Right-click the modeled entity object, then choose Properties to specify more of its
properties.
Related Topics
About Modeled Entity Objects
Modeling an Entity Object Attribute
Reverse-Engineering a Table Definition to an Entity Object
12-107
Entity object attributes can be created on entity objects modeled on class diagrams either by
entering the attribute directly onto the modeled entity object on the diagram, or using the Entity
Object Wizard.
To model an entity object attribute:
● Double-click the modeled entity object on the diagram, or on the Navigator pane, for
which you want to add an attribute, then enter the attribute name and details on the
Attributes page of the Entity Object Wizard.
OR
1. Select the modeled entity object on the diagram, for which you want to add an attribute.
2. Click on the attributes compartment of the modeled entity object, immediately below any
existing attributes.
Note: If this is the first attribute for this entity object, click at the top of the attributes
compartment on the entity object.
3. Enter the name and datatype, or domain, for the attribute. For example:
name : String
Notes:
If an attribute type from the java.lang package is entered without a package prefix, for
example, String or Long, an attribute type prefix of java.lang. is automatically
added.
To create an attribute with a domain as its type, the domain must be qualified with its
package name.
4. Press Enter.
Related Topics
12-108
About Entity Object Attributes
Modeling an Entity Object Operation
12-109
Modeling an Entity Object Operation
Although methods cannot be created directly on entity objects modeled on a class diagram,
operations created on the underying entity objects are displayed on the diagram.
Note: All operations you define against a modeled entity appear in the «Business» category of the
operations compartment of the modeled entity object.
To add operations on entity objects:
1. Select the modeled entity object on which you want to model operations then choose
Model | Show | Implementation Files.
OR
Right-click the modeled entity object and choose Show Implementation Files.
This creates a modeled Java class from the .java file that implements the entity object.
2. Add a Java operation to the modeled implementation class. See Modeling a Java
Operation.
OR
Right-click the modeled implementation class, choose Go to Source, then add the
methods to the Java source using the Code Editor.
Related Topics
About Entity Object Operations
12-110
Modeling a Domain
Domains can be modeled on class diagrams to represent attribute domains for business
components.
Note: To model a domain on a class diagram requires a valid database connection defined in
JDeveloper. If you don't have a valid database connection in JDeveloper, you will be prompted
to create one before continuing.
To model a domain on the diagram:
1. Click the Domain icon on the Component Palette.
2. To create the domain at the default size, click on the diagram where you want to create
the domain.
OR
To create the domain at a different size, click on the diagram, drag the domain box to the
desired size, then release the mouse button.
3. Enter the name of the domain, then press Enter.
4. Double-click the modeled domain to specify more of its properties.
OR
Right-click the modeled domain, then choose Properties to specify more of its properties.
Note: Only the package name and the domain name are displayed on a modeled
domain.
Related Topics
About Modeled Domains
12-111
12-112
Modeling an Association Between Business
Components
An association is a relationship between entity objects. There are two types of association
between entity objects: simple and strongly aggregated (composition).
Note: Entity objects can only be associated to other entity objects.
To create an association between two classes:
1. Click the Association icon on the Component Palette.
2. Click the entity object at the 'owning' or 'from' end of the association.
3. Click the entity object at the 'to' end of the association.
A simple association is modeled between these two entity objects with a default
multiplicity value assigned at each end of the association.
4. Click the association line on the diagram, then click the text fields adjacent to the
association to enter:
❍ a role name for each end of the association
❍ the multiplicity for each end of the association
❍ a verb describing the association
To define an association end as strongly aggregated (composition):
1. Right-click the association the aggregation of which you want to define.
OR
Double-click the association the aggregation of which you want to define.
2. Choose Properties...
12-113
3. Click the Association Properties tab.
4. Check the Composite Association checkbox.
5. Click OK.
Related Topics
About Modeled Business Components Associations
12-114
Modifying Modeled Business Components
The following topics describe how to modify modeled business components.
● Changing the Properties of a Class Model Element
● Deleting a Model Element
● Moving an Element Between Class Diagrams
● Adding an Element to a Diagram
● Changing the Way Class Diagram Elements are Displayed
Note: The properties of modeled business components can also be changed using the Entity Object
Wizard. For more information on this, see Creating an Entity Object.
Related Topics
12-115
About Reverse-Engineering Table Definitions to
Business Components
The definitions of tables available through connections set up in JDeveloper can be used as the
basis for entity objects on a class model.
For more information on reverse-engineering table definitions to entity objects and

associations, see About Generating Entity Objects, Associations and Database Tables.
Related Topics
Reverse-Engineering a Table Definition to an Entity Object
12-116
Reverse-Engineering a Table Definition to an Entity
Object
Modeled entity objects can be created on a class diagram from table definitions accessible via
an existing database connection in JDeveloper.
To reverse-engineer table definitions to entity objects:
1. Open the class diagram on which you want to create an entity object based on a table
definition.
OR
Create a new class diagram for business components.
2. Expand the Connections node in the Navigator pane.
3. Expand the node for the database connection in which the table definition you want to
reverse-engineer to an entity object is stored.
4. Expand the user on that connection.
5. Expand the Tables node.
6. Click the table, the definition of which you want to use to create an entity object, and drag
it to the open class diagram.
Note: To reverse-engineer several tables to entity objects, hold down the Ctrl key, select
the tables in the Navigator you want to reverse-engineer, drag these tables onto the
open class diagram, then release the Ctrl key.
Related Topics
About Modeled Entity Objects
12-117
12-118
Using Your Modeled Entity Objects
You can further extend your model of entity objects by doing the following:
● Generate a table definition for a modeled entity object. For more information, see
Creating a Database Object from a Modeled Entity Object.
● Create default application modules, view objects and viewlinks for modeled entity
objects. For more information see, Creating Default Business Components.
● Model 'helper' Java classes for modeled entity object. For more information, see Using
Modeled Entity Objects With Java Classes.
● Display the implementation Java code for a modeled entity object. For more information,
see Displaying the Java Class Implementation for an Entity Object.
● Display elements that are related to a modeled entity object. For more information, see
Displaying Related Elements on a Diagram.
Related Topics
12-119
Creating a Database Object from a Modeled Entity
Object
Database tables can be created from modeled entity objects and object types can be created
for domains (where applicable). The database objects are created on the entity object's
database connection.
Important: Database objects cannot be created for business component definitions, using the
following procedures, if they do not have complete definitions.
An entity object is incomplete if it does not have:
● A Schema Object name set (for example, if this property has been cleared)
● any attributes
● any attributes specified as part of the primary key
An association definition is incomplete if it has its 'Use Database Key Contraints'

flag set, but does not have source or destination attributes selected.
Note: The entity object's database connection must be for a user with the correct privileges to create
database objects on the database.
To create a database object from a selected modeled entity object:
1. Select the modeled entity object for which you want to create a database object.
2. Choose Model | Generate | Database Objects.
OR
Right-click the diagram surface and choose Create Database Objects.
Note: You may need to refresh the Navigator pane before you can see the new
database object.
To create a database object from all entity objects on a diagram:
1. Click the diagram surface to deselect any currently selected elements.
12-120
2. Choose Model | Generate | Database Objects for Diagram.
OR
Right-click the diagram surface and choose Create Database Objects for Diagram.
Note: You may need to refresh the Navigator pane before you can see the new
database object.
12-121
Creating Default Business Components
You can create default View Objects, View Links and an Application Module to complete the
Business Component framework for either selected entity objects on your class diagram, or for
all entity objects on your diagram. The elements created are as follows:
● Default view objects are created for modeled entity objects
● Default view links are created between the view objects, representing the associations
between modeled entity objects
● An application module is created for the whole model.
Note: Each time default business components are created for modeled entity objects, new default
view objects and view links are created. If an application module already exists for your model, it will
be updated to reflect the most recent creation of default business components.
To create default business components for selected modeled entity objects:
1. Select the entity objects and associations for which you want to create default business
components.
2. Hold down Ctrl and click the right-mouse button.
3. Choose Default Business Components.
To create default business components for all entity objects on a diagram:
1. Click on the diagram surface to deselect any currently selected elements.
2. Click the right-mouse button.
3. Choose Default Business Components for Diagram.
12-122
Related Topics
Extending Your Modeled Entity Objects
12-123
Using Modeled Entity Objects With Java Classes
Although you can create an association directly between a Java class generated from a
modeled entity object and a Java class modeled on a class diagram, this does not extend the
Business Component framework which the entity object's Java source implements. 'Helper'
classes can be modeled where supplementary Java classes are required to work with modeled
entity objects.
To model a relationship between an modeled entity object and a modeled Java class:
1. Right-click the entity object on the class diagram the generated Java source code for
which you want to display on the diagram.
2. Choose Show Implementation Files.
This displays on the diagram a modeled Java class reverse-engineered from the Java
source code of the entity object's implementation class.
3. Model the 'helper' Java class on the diagram.
You can now model a dependency, or an association, between the 'helper' class and the
modeled implementation class for the entity object.
Related Topics
Modeling a Dependency
12-124
Displaying the Java Class Implementation for an
Entity Object
Each modeled entity object has an underlying Java source file which contains the
implementation code for that element. These implementation files can be displayed on the
diagram as modeled Java classes.
To display a modeled Java class of the implementation of an entity object:
● Select the entity object on the diagram, the Java implementation of which you want to
model on the diagram, then choose Model | Show | Implementation Files.
OR
● Right-click the entity object on the diagram, the Java implementation of which you want
to model on the diagram, then choose Show Implementation Files.
A modeled Java class is displayed on the diagram for the Java class that implements the
entity object.
Related Topics
Displaying Related Elements on a Diagram
12-125
Modeling Activities
The following topics describe how to model the activities, pseudostates and transitions that
encapsulate the operation of a system.
● Activity Diagram Notation
● Creating a Model of Activities, Flows and Pseudostates
● Partitioning an Activity Diagram
Related Topics
Modeling Basics
Modeling Activities for E-Business Integration
12-126
Activity Diagram Notation
The notation used on activity diagrams created in JDeveloper is illustrated below.
Note: A swimlane that has been defined as the hub for the system displays the hub icon. If multiple
instances are defined on a swimlane, the multiple instances icon is displayed on the swimlane.
If a channel or an adapter is defined on a transition, an icon symbolizing this is displayed on the

transition:
Channel
Channel with an adapter
Activity Diagram Elements:
● Swimlanes
● Activities
● Object Flow States
● Transitions
● Pseudostates (INITIAL, OR, AND, FINAL)
12-127
Related Topics
Creating a Model of Activities, Flows and Pseudostates
Partitioning an Activity Diagram
E-Business Integration Essentials
Ways to Create Integration Points
Creating Messaging Adapters
Deploying Generated E-Business Integration Files
12-128
Creating a Model of Activities, Flows and
Pseudostates
The following topics describe how to create a model of activities, flows and pseudostates.
● Creating a New Diagram
● Creating an Activity
● Creating a Composite Activity
● Creating a Subactivity State
● Creating a Transition
● Creating a Pseudostate
● Creating an Object Flow State
● Creating Additional Classifier in States
Related Topics
Partitioning an Activity Diagram
12-129
Creating an Activity
An activity represents a process that is performed in a business or system. An activity can
represent a single process or it can represent a subactivity model (that is, the activity can be
broken down into a set of subactivities which themselves form an activity model). An activity
that represents subactivities is known as a composite or "drill-down" activity. A composite
activity has a composite icon in the bottom right hand corner of the activity shape.
To create an activity:
1. Click the Activity icon in the Component Palette.

2. Click the location in the diagram panel (that is, the area to the right of the vertical bar)
where you want to place the activity.
3. Enter the activity's name by overtyping the default name or by using the Activity
Properties dialog.
Note: It is advisable to avoid using activity names that start with the four characters 'top '
(where the fourth character is a space). This is because when you create a new diagram, the
modeler prefixes the name of the diagram with these characters and automatically creates an
activity of that name to represent the root of the model. For example if you create a diagram
called 'order processing' an activity will be created in your project called 'top order
processing'.
For information on the properties you can define for activities, see Activity - General Properties.
Related Topics
About Activities
Activity - General Properties
Creating a Composite Activity
12-130
Any activity can made into a composite or "drill-down" activity. You do this by drilling down into
the activity and defining its subactivity model in the resulting activity diagram. This diagram is
also known as a "drill-down" diagram.
When you create a composite activity, the activity modeler creates a new diagram where you
can define the systems that the composite represents. In the drill-down diagram, you define the
swimlanes, activities, and other model elements elements in the same way as you define them
in the top-level diagram.
To create a composite activity:
1. Right-click the activity that will represent a composite activity, and select Drill Down from
the menu.
The activity modeler creates an empty drill-down diagram and places the composite icon
in the activity shape that you selected for drill-down.
2. Use the new diagramming surface to define the swimlanes and draw the business
processes that the composite activity represents.
For e-business integration to detect and process a drill-down diagram, the final object flow
states in the drill-down diagram must match the object flow states leading from the composite
activity in the top-level diagram. For more information, see Requirements for a Drill-Down
Diagram.
While you are in the drill-down diagram, you can return to the top-level activity by right-clicking
the diagram and selecting Drill Up from the menu.
Related Topics
Creating an Activity
Requirements for a Drill-Down Diagram
12-131
12-132
Creating a Subactivity State
A subactivity state is a reuse of an existing activity. In each of the following cases a subactivity
state is created on the diagram surface with the name activity_name (re-use).
To create a subactivity state by using drag and drop:
1. Left-click the activity in the Navigator pane that you want to reuse.
2. Drag the activity onto the diagram surface.
3. Release the mouse button.
To create a subactivity state using Add to Diagram option:
1. Right-click in a swimlane on the diagram surface and choose Add to Diagram.

2. Navigate down the Model Elements and package nodes to the activity you want to reuse.
3. Select the activity and click OK.
To create a subactivity state with the Copy and Paste commands:
These steps assume that the activity that you want to reuse already exists on the diagram
surface.
1. Right-click the activity that you want to reuse and choose Copy.
2. Position the cursor where you want to reuse the activity.
3. Right-click and choose Paste.
Related Topics
Subactivity State - General Properties
12-133
Creating a Transition
Transitions are used to indicate how the activity model flows from activity to activity.
To create a transition:
1. Click the Transition icon in the Component Palette.
2. Click the source element of the transition and then click the target element.
Note: The activity modeler will not allow you to draw transitions that break UML rules. For a
description of the situations where the modeler does not allow you to draw transitions, see
Understanding Invalid Transitions.
For information on the properties you can define for transitions, see Transition - General
Properties and Transition - Integration Properties.
Related Topics
About Transitions
Understanding Invalid Transitions
Transition - General Properties
Transition - Integration Properties
Creating, Moving and Removing Elbows on Connectors
12-134
Creating a Pseudostate
Use pseudostates to combine or split up transitions to indicate possible parallel and/or mutually
exclusive paths through the activities of the diagram.
Note: Only one INITIAL state can be created in a diagram. The INITIAL and FINAL states are
created at a default size. There is no drag rectangle for these elements.
To Create a Pseudostate:
1. Click one of the pseudostate icons on the Component Palette:
AND
OR
INITIAL
FINAL
where you want to place the pseudostate.
Related topic
About Pseudostates
12-135
Creating an Object Flow State
In UML, an object flow state represents the action of a given object being put into a given state
by an activity. In the e-business integration context, an object flow state represents a message
or event that is passed from one activity to another.
To create an object flow state:
1. Click the Object Flow State icon on the Component Palette.
where you want place the object flow state.
Related Topics
About Object Flow States
Adding an Element to the Diagram
Creating Additional Classifier in States
Object Flow State - General Properties
Classifier in State - General Properties
Object - General Properties
Object - Classifier in State Properties
12-136
Creating Additional Classifier in States
You can create additional classifier in states for an existing object from the Navigator pane or
by copying and pasting an object flow state already displayed on the diagram.
Note: You cannot use the Component Palette to create additional classifier in states for an existing
object. When you create an object flow state from the Component Palette, the activity modeler
creates a new object flow state for a new classifier in state against a new object. When you attempt
to overtype the name of an object created from the Component Palette with one that already exists,
the activity modeler will respond with a validation error. This is because the modeler will interpret
your action as an attempt to create two objects with the same name in the same package.
To create additional classifier in states from the Navigator pane:
1. Right-click the name of the object you want to work with in the Navigator pane and
choose Properties.
2. In the Classifier in State tab of the Object Properties dialog, click Add to create a new
classifier in state.
3. Enter the name of the new classifier in state.
4. Repeat steps 2 and 3 for each additional classifier in state you need.
5. Click OK. The new classifier in states are created for the object.
6. To include an object flow state with the new classifier in state in your diagram either:
use the Add to Diagram option and select the classifier in state.
OR
select the object in the Navigator pane. In the Structure window open the Classifier in
States node and find the classifier in state you want to use. Select the state, and drag
and drop it onto the diagram surface.
To create additional classifier in states with the Copy and Paste commands:
These steps assume that the object for which you want to create additional classifier in states is
already used by an object flow state on the diagram.
1. Right-click the object flow state on the diagram surface and choose Copy.
2. Position the cursor where you want to place the object flow state with the new classifier
12-137
in state.
3. Right-click and choose Paste. An object flow state of the same type that you copied, but
with the classifier in state [new state] will appear on the diagram surface.
4. Overtype [new state] with a unique name.
5. Repeat steps 3 and 4 for as many different classifier in states as you need to create for
the object flow state.
Related Topics
About Object Flow States
Creating an Object Flow State
12-138
Requirements for a Drill-Down Diagram
A composite activity can represent subactivity diagrams of an arbitrary level of detail and complexity. Like the top-level diagram, the drill-
down diagram represents business process flows in terms of swimlanes, activities, object flow states, and routing. It also possesses one
INITIAL state to indicate the starting state of the systems represented by the diagram and one or more FINAL states to indicate its ending
state.
The results of the business processes represented by the drill-down diagram must be passed to the top-level so that they can be
incorporated into the rest of the activity model. To do this, the final activity before the FINAL state in the drill-down diagram uses an object
flow state to pass a message to the top-level diagram. In the top-level diagram, the message is captured by an identical, matching object
flow state leading from the drill down activity, and passes it on to the rest of the system.
Note: You can apply copies of existing elements by using the Add to Diagram command.
For the Activity Modeler to detect and process the contents of a composite activity correctly, it must find matching object flow states in the
sub-activity and top-level diagrams. If the activity modeler cannot find matching object flow states, then the drill-down is ignored.
Figure 1 illustrates an example of matching object flow states in the sub-activity and top-level diagrams. The Clear for Export composite
activity represents a system that ends with the Get Export License activity. The License[obtained] object flow state passes the [obtained]
state to the top level where it is caught by the License[obtained] object flow state leading from Clear for Export.
Figure 1: A Composite Activity, Illustrating Matching Object Flow States in the Top-level and the Drill-Down Diagrams
Decision Points in Drill-Down Activities
In a decision point, two or more outcomes are possible. The outcomes are represented by object flow states. The content-based routing
code that you supply determines the branch by which the message will be routed. If the drill-down diagram ends with a decision point,
then copies of each of the participating object flow states must appear leading from the composite activity in the top-level diagram. This
message routing information is passed from the object flow state in the drill-down diagram to the corresponding object flow state in the
top-level diagram and is then sent to the rest of the system.
For example, in Figure 2 Clear for Export is a composite activity, where either Obtain Export License or Obtain Special Clearance in the
drill-down diagram must be satisfied before the order can be cleared. The content-based routing code that you supply, determines
whether the License[obtained] or Clearance[obtained] message is sent to the top level diagram. In the top-level diagram, the message
and routing information is captured by the copy of the appropriate object flow state and the message is sent on to the rest of the system.
You also do this by defing signals on the transitions between the object flow state and the end points on the drill down diagram, then
defining events which are raised by these defined signals against the transitions whose source is the top level activity. This removes the
need to include copies of the object flow states on the top level diagram.
Figure 2: A Composite Activity, Illustrating Matching Object Flow States for a Decision Point
12-139
Synchronization Points in Drill-down Activities
Synchronization points represent a join where only one object flow can proceed. If the drill-down diagram ends with a synchronization
point, a copy of the object flow state representing the message must appear in the top-level diagram.
For example, in Figure 3, Clear for Export is a composite activity where License[obtained] and Declaration[completed] must both
complete before the Order[cleared] message can be sent. The Order[cleared] message is captured by the corresponding object flow
state in the top-level diagram and sent on to the rest of the system.
Figure 3: A Composite Activity, Illustrating Matching Object Flow States for a Synchronization Point
Related Topics
12-140
About Activities
12-141
Deleting Diagram Elements
You can remove an element from the diagram by right-clicking the element and choosing Cut,
Remove from Diagram, or Delete from Model. While Cut or Remove from Diagram will remove
the element from the current diagram, it will not remove the element from your file system. This
is because the element might be used in another diagram.
The difference between the Cut, Remove from Diagram, and Delete from Model commands
depends on whether you apply them to a primary element or a secondary element:
● Cut—Select Cut on a secondary element to remove it from the diagram. Selecting Cut
on a primary element removes it from the diagram, plus any secondary elements it might
own. The element will still be defined for the current project and will still be visible in the
Navigator pane.
Cut places the element on the clipboard such that it can be pasted anywhere, even after
it has been removed from the diagram. This is the distinction between Cut and Remove
from Diagram.
● Remove from Diagram—Select Remove from Diagram on an element to remove it from

the diagram, but not from the model. The element will still exist in the file system and will
still be available to be added to a diagram. If you select Remove from Diagram on a
secondary element, such as a pseudostate, object flow state, or subactivity state, it will
be removed from the model as well as from the diagram. This is because a secondary
element cannot exist outside of the diagram it is hosted on.
● Delete from Model—Select Delete from Model to completely remove the element from
the file system. The element will disappear from the model, the diagram, and the
Navigator, but it will not be removed from the file system until a save (File | Save or Save
all) has occurred. Until a save is done, the element can reloaded into the model in any of
these ways:
❍ File | Open will return the file to the Navigator; you can then drag and drop it onto
the diagram.
❍ The file will still appear in the Add to Diagram dialog until a save occurs, so it can
also be included back into the diagram and hence the model.
❍ Close down the diagram and reopen it without an intermediate save to bring the
file back into the model.
After a save is performed, however, the element will not be able to be retrieved.
12-142
Related Topics
Understanding Primary and Secondary Elements
12-143
Partitioning an Activity Diagram Using Swimlanes
Activity diagrams can be partitioned using swimlanes to visually, and semantically, separate
different parts of the systems you are modeling. Swimlanes can be contained within other
swimlanes, these are called child swimlanes.
In UML, a swimlane is used to logically group activities in the diagram into a specific area. For
example, you could use a swimlane to represent the activities that are performed within an
organizational unit in a business model.
In e-business integration, however, a swimlane is used to represent a system for a generation

profile.
In e-business integration, a swimlane can have a single instance or multiple instances. You can
add instances to an existing single-instance swimlane or delete instances from a multi-instance
swimlane.
A swimlane can be defined as a hub for e-business integration.
Related Topics
Creating a Swimlane
Creating a Child Swimlane
Showing or Hiding Swimlanes
12-144
Creating a Swimlane
This topic describes how to create a swimlane to allow it to participate in messaging. Also
provide information for the channels that represent the endpoints for communication. For each
channel, you identify the adapters that mediate between the sending and receiving applications
and the BES. You can define swimlanes with a single instance or with multiple instances.
To create a swimlane with a single instance:

2. Click on the diagram surface.
A swimlane will be created in the diagram.
3. Open the Swimlane Properties dialog to enter information about the swimlane. To open
the dialog, either double-click the swimlane or select the swimlane and choose
Properties from the right mouse menu. In the Swimlane Properties dialog, use the:
❍ Name tab to enter the name of the system instance. About
❍ Channels page of the Channels/Adapters tab to define channels on the swimlane.

About
❍ Messaging Adapters page of the Channels/Adapter tab if your application needs
an Oracle Messaging Adapter to enqueue or dequeue messages. About
❍ Instances tab to define an instance, the database connection to the system that
the instance represents, the AQ Servlet, and the deployment profiles.
Note: You can define multiple system instances against a single swimlane. The multiple instance
icon will appear in the upper left corner of the swimlane.
Related Topics
About Swimlanes
Changing a Single Instance Swimlane to Multiple Instance
12-145
Swimlane - General Properties
Channels and Adapters Properties
Swimlane - Instances Properties
12-146
You can define swimlanes that are owned by other swimlanes. Child swimlanes are treated as
separate systems—they are not dependent on their parent swimlanes, nor do they inherit any
properties from them.
To create a child swimlane:
2. Click the swimlane that you want to use as the parent.
A child swimlane will be created, indented beneath the parent. For information on the properties
you can define for swimlanes, see:
● Swimlane - General Properties.
● Swimlane - Channels and Adapters Properties
● Swimlane - Instances Properties
Note: As an alternative, you can create a child swimlane from an existing swimlane. To do this,
select a swimlane in the diagram and while holding down the SHIFT key, drag it into another
swimlane. Release the mouse button and SHIFT key. The swimlane becomes a child
swimlane.
Related Topics
About Swimlanes
Creating a Swimlane
12-147
12-148
The activity modeler lets you show or hide swimlanes on your diagram.
There might be situations when you would want to hide swimlanes. For example, if you want to:
● use the activity modeler simply to sketch the relationships between business activities
● model the relationships between business activities but do not want to commit the
activities to a particular system
● hide some of the complexity in a diagram.
● hide child swimlanes so that the contents of the both the child and parent swimlanes are
displayed on the parent.
Note: If you add objects to the diagram while the swimlanes are hidden, then display
swimlanes, these objects will be displayed at the bottom of the diagram, not owned by any
swimlane.
To Show/Hide Swimlanes on a Diagram:
● If swimlanes are currently displayed, right-click anywhere on the diagram and choose
Hide Swimlanes.
● If swimlanes are currently hidden, right-click anywhere on the diagram and choose Show
Swimlanes.
To Show/Hide Child Swimlanes:
● If child swimlanes are currently displayed, right-click on the parent swimlane and choose
Hide Descendant Hierarchy. The parent swimlane then displays a plus sign to signify it
contains child swimlanes. The parent swimlane also now displays the contents of the
child swimlanes.
● If child swimlanes are currently hidden, right-click on the parent swimlane and choose
Show Descendant Hierarchy.
Related topic
12-149
Creating a Swimlane
12-150
Modeling Activities for E-Business Integration
The activity modeler in JDeveloper allows you to visualize and generate the integration
between e-business applications either within a corporate intranet or across the internet. The
activity modeler allows you to model business process flows and to capture the additional
semantic data to define executable processes, routing and queues. The process is expressed
in terms of activities, systems (that perform the activities within swimlanes) and routing (for
example conditions, alternatives etc. represented by pseudostates). The business process
model also defines the objects that are being processed in terms of objects and states, for
example, in an Order Entry system an Order can be taken, filled, shipped and billed.
The activity modeler provides a framework that allows applications which are part of separate
systems to exchange information asynchronously. Each system may already have in place a
messaging solution such as Oracle AQ, or a solution from another provider. The framework
provides the means of allowing communication between the applications through instances of
these different messaging systems. Communication can be broadcast, or can require content-
based routing of messages in order to deliver messages to the correct recipients.
The following topic describe how to model activities for e-business integration:
● E-Business Integration Essentials
● Ways to Create Integration Points
● Creating Messaging Adapters
● Deploying Generated E-Business Integration Files
Generate Business Processes
Each point where the process crosses from one system to another is known as an integration
point. The generator defines the appropriate events in the Oracle Workflow Business Event
System (BES) to link processes across integration points. The process is generated as a hub
and spoke architecture, where management of the process is centralized on the hub. The hub
and spoke option additionally generates, on the hub, a single unified workflow that represents
the whole end-to-end process.
Generate Process Integration Points

12-151
The activity modeler uses Oracle AQ and the BES, to integrate end-to-end processes. It
defines the queues that carry messages across integration points. At execute time an activity in
one system raises an event and the BES enqueues a corresponding message; at the other side
of the integration point the routing mechanism makes the delivered message available for
dequeue.
Normally the dequeuer will be on a different host system than the enqueuer, so the queue entry
must be propagated to the target host before it is accessible to the next stage of the process.
For each integration point the generator will create:
● appropriate queues, accessible to the enqueuer and the dequeuer(s)

● propagation through the hub for routing decisions
Generate Code to Message Enable Business Components for Java

Applications
Many applications that implement activities in a business process are existing workflow-
enabled applications (such as Oracle Applications), or wrappered legacy applications. But
many new applications will be built using the Business Components for Java framework. For
these applications the messaging generator implements a framework to message-enable
Business Components for Java applications and allow them to act as adapters between legacy
systems and the messaging infrastructure.
12-152
E-Business Integration Essentials
The following topics discuss the essentials of e-business integration supported by the Activity
Modeler.
● Oracle9i Advanced Queuing and E-Business Integration
● Business Event System and E-Business Integration
● Oracle Workflow and E-Business Integration
Related Topics
Ways to Create Integration Points
12-153
About Advanced Queuing and E-Business
Integration
The Oracle e-business infrastructure uses Oracle Advanced Queuing (AQ) to carry messages
between Oracle-based systems. AQ provides a robust, scalable, message queuing system
integrated with the database. AQ provides gateways to major queuing products such as BES,
and a JMS interface to communicate with Java-language programs. To enable
communications, AQ provides queues, queue tables, and propagation rules. AQ support can be
turned off in cases where non-AQ messaging software has to be used.
About Queues and Queue Tables
AQ queue tables are relational database tables with support for queuing operations. They can
contain one or more queues of messages. A message consists of:
● Control information - used by AQ to manage messages.
● Payload - information stored in the queue.
Manipulating AQ Queues
You can use standard SQL to:
● Access the payload, control information, and history
● Optimize access
Queues can be created, altered, started, stopped, and dropped by using the Oracle AQ
administrative interfaces.
About Propagation Rules
Applications that use the database can send and receive data via queues. Propagation
transfers messages from one queue to another queue that can potentially be on a different
system. The rules for message propagation that are followed by e-business integration ensure
that a message enqueued at the source of an integration point appears for dequeue at the
target end of the integration point. Messages can be propagated by SQL*Net, HTTP or HTTPS.
12-154
The Business Event System always places outbound messages on an AQ queue. Actual
propagation of the message can either be by the AQ itself or implemented using third-party
message gateways.
The generated propagation definitions allow the messages to be carried to remote queues. For
this, AQ sets up a propagation schedule by using the AQ name, the name of the system to
which messages should be propagated, and the protocol. Individual queues on the target
system are addressed using either recipient lists on individual messages or a publish-subscribe
mechanism.
If you are not communicating with an Oracle system, or if AQ propagation is not available, you
can use Oracle Message Broker (OMB) for message propagation. OMB can also be used to
propagate over firewalls, which makes it an acceptable choice for applications that require
Internet propagation.
About Agents
An agent is a queue user. This could be an end user or an application. There are two types of
agents:
● producers who place messages in a queue (enqueuing)
● consumers who retrieve messages (dequeuing)
Any number of producers and consumers may be accessing the queue at a given time. Agents
insert messages into a queue and retrieve messages from the queue by using the Oracle AQ
API.
An agent is identified by its name, address, and protocol.
● The name of the agent may be the name of the application or a name assigned by the
application. A queue can itself be an agent, enqueuing or dequeuing from another
queue.
● The address field is a character field of up to 1024 bytes that is interpreted in the context
of the protocol. For instance, the default value for the protocol is 0, signifying a database
link address. In this case, the address for this protocol is of the form:
12-155
queue_name@dblink
where queue_name is of the form [schema.]queue and dblink can be either a fully
qualified database link name or the database link name without the domain name.
● The protocols supported by e-business integration are SQL*Net, HTTP or HTTPS.
Using AQ with Other Queuing Products
AQ interfaces with other major queuing products. For example, e-business integration uses
Oracle Workflow BES as an optional event system interfaced onto AQ messaging. BES makes
it easier to integrate existing Workflow processes in the local system and can also perform
conditional routing of messages based on their content. Where there is no BES or local
workflows, you can, as an alternative, directly invoke the AQ messaging infrastructure, and use
built-in content-based routing features.
AQ provides a JMS interface to allow applications written in Java to access queues.
Related Topics
AQ Queue Definitions
12-156
About AQ Queue Definitions
In a simple integration point example, two queues are defined for each integration point, one for
the source channel (out channel) and one for the target channel (in channel). The BES in the
hub listens to an inbound queue onto which applications can queue events. It then executes the
subscription, sending the events to the appropriate target. Two message propagations are set
up: one from the source system to the BES on the Hub, and one from the BES to the target
system. Figure 1 illustrates this schematically.
Figure 1: Communications Initiated by Queues on Source and Target Systems
If the systems use Oracle AQ for messaging, the e-business integration code generator creates
an AQ queue definition file for each system. The AQ queue definition file is an XML file that
contains the name and queue table of every queue to be created, and the AQ propagation
schedules. Deployment will use this file to run commands on the database to create the
queues.
Target Systems That Do Not Use Oracle AQ
If the target system does not use Oracle AQ for its messaging, an AQ queue definition will not
be generated for it. The BES however, will always be present in the Oracle-based hub. In this
case, for information on how to create queues, refer to the documentation for the queuing or
messaging service that is used by the system. Queue propagations have to be set up, as
appropriate, for the third-party queueing software used.
Source Systems That Do Not Use Oracle AQ
If the source system does not use Oracle AQ for its messaging, it will still require the use of a
BES in order to route its messages. The BES will always be present in the Oracle-based hub.
The AQ definition created will reside on the BES with which the source system communicates.
Queue propagations have to be set up, as appropriate, for the third-party queueing software
used.
12-157
As an alternative, the source system might indirectly use the BES on an AQ-based hub to route
its messages. In either case, an AQ queue definition must be generated to allow applications
on the sending system to communicate with the BES.
Related Topics
Advanced Queuing and E-Business Integration
Editing AQ Definitions
12-158
Editing AQ Definitions
You can edit the AQ definitions generated by the Activity Modeler. An AQDefinitions.xml file is
generated for each swimlane. AQDefinitions.xml is comprised of three sections:
AQDefinition, AQTableDefinition and PropagationDefinition. You can enter your
own values into the blank properties in this file to configure your queues, queue tables and
propagation schedules.
Below is a list of the AQ properties that aren't exposed through the AQDefinitions.xml file as
they are defaulted by the deployment code:
● Queue_payload_type on queue tables: generated queue tables always have their

payload type as SYS.AQ$_JMS_TEXT_MESSAGE
● Multiple_consumers on queue tables: all queue tables are multiple-consumer tables
● Compatible on queue tables: all queue tables are 8.1 compatible
● Queue_type on queues: all queues are NORMAL-type queues.
Note: You should not modify any of the property values created in AQDefinitions.xml by the
generator, as these are key to the infrastructure produced by the E-Business Integration Generator
and other generated definitions (for example, those in BESDefinitions.xml) expect these properties
to have the generated values. You can set values for properties left blank by the generator, but must
ensure that they contain valid values, otherwise deployment of the AQ definitions will fail.
The AQDefinitions.xml file populates three procedures in the DBMS_AQADM package:
● DBMS_AQADM.CREATE_QUEUE_TABLE
● DBMS_AQADM.CREATE_QUEUE
● DBMS_AQADM.SCHEDULE_PROPAGATION
For more information on these procedures, including the valid values for the DBMS_AQADM
procedures, refer to the appropriate section of the 'Oracle9i Supplied PL/SQL Packages and
Types Reference'.
Related Topics
About AQ Definitions
12-159
12-160
Business Event System and E-Business Integration
In e-business integration, the applications that you want to integrate almost always belong to
separate systems; the systems themselves might already have a messaging solution in place
such as Oracle AQ or some non-Oracle solution. The Oracle Workflow Business Event System
(BES) provides the link between these different messaging systems by providing a framework
that allows applications to asynchronously exchange information. The BES supports
communications that can be broadcast, or that might require content-based routing of
messages to deliver them to the correct recipients.
The BES provides a workflow-enabled solution for e-business integration requirements. It is an

application service that uses AQ to transport business events between systems, supporting the
following types of integration:
● system integration messaging hubs

● distributed applications messaging
E-business integration only supports hub-based architecture; it does not support distributed
messaging.
The BES consists of a registry of events and systems which, through the use of subscriptions,
can be used to notify applications on different systems of things which have happened within
other applications on other systems. BES events are named using the fully qualified name of
the classifier in state that they represent.
The BES also provides an API which allows the BES to handle messages either sent from or
targeted to systems that have their own messaging format: JMS, for example. The BES can
also identify each event independently of the messages that the event enqueues. This lets you
work with events and messages independently. By monitoring the raising of these events you
can track the progress of a particular instance of a business process.
The BES is a routing hub that can be configured to work with different messaging systems,
such that each of its spokes do not need any awareness of what messaging systems are used
on other spokes, or indeed on the hub itself. In fact, if the source and target systems are both
using AQ for messaging, BES is not needed at all. However, using BES offers distinct
advantages. The BES allows:
● asynchronous event-based transfer of messages.

● the invocation of Oracle Workflow processes related to events received. These Workflow
models allow content-based routing of messages and also allow the current state of a
12-161
process to be monitored.
If the source or the target system is not using AQ, then the BES can communicate with a
product which fulfills this purpose (such as Oracle Message Broker) to transport messages to
non-AQ systems.
Related Topics
About Business Event System Definitions
About BES and Integration Points
About BES and Decision Points
About BES and Hubs
12-162
About BES and Hubs
In a hub and spoke architecture, all messages must pass through the hub. The BES on the hub
is responsible for managing and executing all of the event subscriptions for all events across
the system. The BES does this by creating propagations between the event-raising channels
on the systems, and one or more inbound event queues on the hub.
The inbound event from the queues can be read by the hub's BES. For example, the
propagation is created and deployed by the generator, and will be set up such that messages
enqueued locally by the Take Order activity will be automatically propagated to a queue on the
BES. The propagation is available for use by the Hub system at runtime. The same applies to
the propagation between the Hub and Shipping systems: it is set up and deployed by the
generator and available for use by the Hub system at runtime.
The BES in the Hub system looks up the event subscriptions and finds that events of type
Order[received] must be sent to the Shipping system. It enqueues the event onto a local
outbound queue and sets up a propagation rule to pass the message to a queue on the
Shipping system from which the adapter to Ship Order can receive it. This example is illustrated
in Figure 1.
Figure 1: Schematic Representation of BES Communications Between Activities in a Hub-based

Implementation
12-163
Integration/Decision Points in Hub-based Activity Diagrams
In a hub-based system, the activity modeler generates a workflow and a set of BES definitions
only for the hub and enters all of the monitoring events. This workflow applies to the entire
diagram and is created by merging together all of the individual workflows created for the
individual decision/integration points.
The systems that act as the spokes in the process require only queue and propagation
definitions. Applications wishing to send messages to the hub should enqueue to one of the
generated queues, from which messages will be propagated to corresponding queues on the
hub. The BES will be listening for these messages and, if necessary, will invoke Oracle
Workflow processes to perform content-based routing, before forwarding the messages to their
intended recipients.
12-164
Related Topics
About Business Event System and E-Business Integration
Using Custom Routing Logic
12-165
The e-business integration code generator produces all of the code and definitions required to support
communication between two applications on separate systems. It produces output for these BES definitions:
● systems
● channels
● events
● event subscriptions
For a simple integration point, there will be one event raised, which is then sent (via the Business Event System)
from one channel on one system to another channel on another system. To define an integration point, definitions
of all of these objects must be generated. More complex integration points could be initialized by more than one
event, and could involve more than one target. For an example of a more complex integration point, see Figure 1.
This figure uses a portion of the Queued Shipping example to show the parts of the diagram which are the basis of
the Business Event System definitions. In the diagram:
● the source channel is linked to the transition between the Take Order activity and the Order[received] object
flow state.
● Order[received] object flow state provides the business event.
● the target channels are linked to the transitions that run from the OR pseudostate to the Ship Domestic and
Clear for Export activities. Rules defined on the two transitions which have the OR pseudostate as their
source determine which transition the message is routed to.
● the systems Orders, Domestic Shipping, Overseas Shipping and Hub become the BES systems.
Figure 1: BES Definitions in a Integration Point Diagram
12-166
Systems
A system is represented in a diagram by a swimlane. After integration point generation, each swimlane yields one
or more system definitions, where a system is a network addressable computer system. Systems are treated as
being independent of each other. Although the activity modeler lets you represent child systems, this is mostly as a
graphical convenience for the user. There is no dependence or inheritance of properties between parent and child
systems. The e-business integration code generator creates separate sets of definitions for each system. To
generate integration points, e-business integration needs information about the source and target systems,
particularly whether there are multiple instances of either system.
Channels
A channel is an addressable point of communication on a system. For a given integration point, there is an out
channel associated with the source activity and an in channel associated with the target activity.
Events
At least one BES event will be generated in every integration point. The nature of the event is determined by the
object flow state which lies between the sending and receiving activities.
Event Subscriptions
An event subscription is an instruction that tells the BES what to do when it receives an event of a given type from
a particular source. When the the BES receives an event, it can perform one of these actions:
● send the message from an out channel on its owning system to an in channel on some other system
● give the event to a Workflow
● invoke a PL/SQL or Java stored procedure which will do some processing involving the message
12-167
Related Topics
About BES and Hubs
12-168
The following example uses a simplified version of the Queued Shipping example to depict an integration
point. In it, all messages of type Order[received] are simply passed from the Orders system to the Shipping
system.
Figure 1: Diagram of a Simple Integration Point
In this example, the Oracle Workflow's Business Event System, which runs on the Hub, implements the
communication between the Take Order application and the Allocate Stock application. Message
propagation is set up between the Take Order application and the BES, and between the BES and the
Allocate Stock application. These instances are set up so that when the appropriate events are raised
locally, they are sent to the Hub where the event subscriptions allow the messages to be distributed to the
appropriate target. For more information about how the BES works on the Hub, see About BES and Hubs.
To implement a solution to the example in Figure 1, the BES on the hub must contain definitions for these
elements:
● Orders system
● Shipping system
● Hub system
● Order[received] event
● out channel which the Take Order activity uses to send the message.
12-169
● in channel which the Allocate Stock activity uses to receive the message.
● subscription which tells the BES to send Order[new] events from the out channel on the Orders
system to the in channel on the Shipping system
In the BES, channels are implemented as queues with propagations between them for the transmission of
messages, see Figure 2.
Figure 2: Schematic Representation of the Relationship Between Channels on Different Systems
BES and Multi-instance Integration Points
A multi-instance integration point occurs where there are multiple instances of the source and/or target
system. Adding multiple instances of the source system means that any one of a number of systems has the
potential to raise an event of a given type and send it to a specified target.
Adding multiple instances of the target system adds an additional parameter to message routing:
determining the instances that should receive the message. Using the simple integration point example
illustrated in Figure 1, assume that there are multiple instances of the Shipping system. There are two
possible choices for routing an Order[received] message to the Shipping system:
● broadcast mode: the message is sent to all system instances
In broadcast mode, event subscriptions are defined for Order[received] which send the message to
each Shipping instance's in channel.
● non-broadcast mode: the message is sent to only one, or to a subset of all system instances
In non-broadcast mode, the content of the message must be evaluated by workflow to determine the
correct recipient of the message. The BES holds a subscription for the appropriate event which
invokes the Workflow. This evaluates the message using a custom evaluation function to determine
the recipients.
12-170
Related Topics
About BES and Hubs
12-171
The following example introduces a more complex but still relatively common case. When the Order[received]
message is raised on the Orders system, there are two possible destinations for it. The destination that will be the
ultimate target will be determined by the shipping address of the customer. This information is stored inside the
message itself. Some evaluation on the message has to be performed to determine the correct destination of the
message.
Figure 1: Diagram of a Decision Point with Two Possible Targets
In this case, when the BES receives notification that an Order[received] event has happened, it cannot immediately
pass the message onto another application. Instead, it uses the routing and decision-handling capabilities of Oracle
Workflow to evaluate the message and decide where it should be sent. Oracle Workflow invokes user-specified Java
code as part of the process of making the decision. Depending on the result, one of the two target activities will be
activated.
The full list of definitions required to implement this content-based routing as illustrated in Figure 1 is:
● the sending system
● the target systems
● the hub
● the event sent by the sending system
● out channel which the sending activity uses to send the message
12-172
● in channel which the receiving activity uses to receive the message
● subscription which tells the BES to send the events to a workflow
● the code that is written on the transition which evaluates the event message and invokes functions to send the
message to the correct recipient (for more information, see Using Custom Content Routing Logic).
Related Topics
About BES and Hubs
12-173
Oracle Workflow and E-Business Integration
Oracle e-business integration uses Oracle Workflow, which has the ability to manage complex
user-based business processes, such as the routing mechanism through decision and
synchronization points. Oracle Workflow receives inbound business event messages from the
BES to initiate or continue processes, and initiates outbound business event messages from a
process.
The BES cues workflow to process a decision point or synchronization; after processing, the
workflow returns the resulting event messages to the BES. In the case of a decision point, the
workflow determines the routing. In the case of a synchronization point, it ensures that the
incoming messages have arrived, storing any early arrivals if necessary, before sending them
on to their recipient.
To use Oracle Workflow as the routing mechanism, it must be installed on the same database
as the Business Event System. This will happen automatically when you install the Oracle
Workflow 2.6 Server.
Related Topics:
About Generating Workflows for Integration/Decision Points
About Monitoring Business Processes
12-174
About Generating Workflows for
Integration/Decision Points
In e-business integration, Oracle Workflow uses the custom content routing code you supply to
determine the routing in a decision point. The Java code you supply will be invoked by the
'Evaluate Rules' activity in the Workflow. The result returned by the Java code enables
Workflow to decide which route to take through the decision point.
The relationship between activities and object flow states in the activity diagram are
represented as relationships between activities in Oracle Workflow. Transitions in the activity
diagram map to workflow transitions. OR pseudostates in the activity diagram map to rule-
evaluating activities in workflow. The Java code you supply is invoked via Java reflection by a
pre-written library procedure which reads the name of the function to invoke from an attribute
on the Evaluate Rules activity in the workflow. The result code that is returned enables
workflow to decide which route to take through the decision point.
Figure 1: A Decision Point
Figure 2: Corresponding Workflow Diagram
12-175
You write the rules in the form of Java code on the transitions that have their sources on the
OR pseudostate. The activity modeler uses the code to generate a class file which workflow
uses for routing. For more information on the code that you supply for content-based routing
and the file that is generated, see Using Custom Content Routing Logic.
If the receiving system has multiple instances, Oracle Workflow will invoke the Java code you
supply to determine which instances should receive the message. For more information on the
code that you supply for instance-based routing and the file that is generated, see Using
Custom Instance Routing Code.
Workflows for Synchronization Points
Defining synchronization points does not require you to write any rule evaluation code. Hence,
synchronization points can be implemented entirely in a workflow.
At runtime, activities after the synchronization point should not occur until all of the transitions
into the point have been activated. Workflow has the ability to store any items that arrive at the
synchronization point early.
Matching Messages for Synchronization
There may be many messages sent to the BES from Export License[obtained] and
Declaration[completed]. The key to being able to perform synchronization correctly is knowing
which particular License[obtained] goes together with which particular Declaration[completed].
The messages cannot be arbitrarily paired together. The BES can correctly match messages
through its support of correlation keys. Messages involved in a synchronization are only
12-176
forwarded by the hub if the correlation keys of the messages match. Correlation keys on all
related messages in the same process must be the same. User applications may need to be
modified to ensure that this takes place.
Workflows for Monitoring Processes
An activity diagram can contain many integration, decision, and synchronization points. Oracle
Workflow has the ability to generate workflows for each individual integration, decision, and
synchronization point, and then merge them together into one workflow for the entire diagram.
Complete process monitoring Workflows will be generated only if all of the swimlanes in the
activity model are single-instance. If any one swimlane is multi-instance, then a series of
individual mini-Workflows will be produced instead, one for each decision or synchronization
which the model contains.
In hub-based systems, in addition to synchronization or decision points, the activity modeler will
additionally generate workflows for simple integration points where just one message is being
passed to one recipient. In an Oracle Workflow diagram, simple integration points look like
individual activities that wait for the arrival of the object state. Such a diagram is illustrated in
Figure 3.
Figure 3: Oracle Workflow Diagram for a Simple Integration Point
The Oracle Workflow Monitor lets you track the progress of workflow processes through the
system. For information on the Oracle Workflow Monitor, see Monitoring Business Processes.
12-177
About Monitoring Business Processes
At runtime, the ability to trace the progress of executing processes is vital for monitoring the
effectiveness of business processes and for tracking critical processes. As well as generating
the messaging infrastructure, JDeveloper also generates a workflow process, executable by
Oracle Workflow, that provides a console for monitoring business processes. Typically, users
choose to run this monitoring process in the hub.
The Oracle Workflow Monitor gives you the ability to review and administer your business
processes from a standard Web browser. The monitor provides a graphical Java applet to
review your business processes. In a single picture you can see which processes have
completed, which are active, and which are yet to be performed. If you need more detail on a
task, it is available through detail status tabs. The Workflow Monitor can let you manually
intervene in a process whenever necessary.
Complete process monitoring Workflows will be generated only if all of the swimlanes in the
activity model are single-instance. If any one swimlane is multi-instance, then a series of
individual mini-Workflows will be produced instead, one for each decision or synchronization
which the model contains.
For instructions on how to set up and use the Oracle Workflow Monitor, see your Oracle
Workflow documentation.
12-178
Hub and Spoke Integration
The hub and spoke architecture, which is supported by e-business integration, uses a central
server which acts as the focal point for applications to communicate with. This central machine
is the hub, and the applications communicating through the hub are the spokes.
In a hub and spoke architecture, the number of interfaces that are needed is much smaller than
in point to point integration. Each application requires two interfaces: one outbound to the hub,
and another, inbound from the hub. To add a new application, you simply connect it to the hub
using inbound and outbound interfaces. Because all messages pass through the hub, the hub
can provide central services for message processing and handling.
A hub and spoke architecture also insulates the spokes from change. The spokes have no
knowledge of the process because all routing and decision making are performed in the hub. If
the process changes, the spokes do not need to be involved unless the change process directly
affects them. If a spoke receives and sends the same messages even if the sources and
destinations of the messages change, then the spoke can remain ignorant of any change in the
process because it is all managed by the hub.
12-179
Key services that a hub can provide are:
● Transformation—The message formats used by source and destination systems may

be different, and may even be incompatible. The hub can use data transformation tools
to map one message format into another.
● Message retention—Messages contain information about business events that happen
across the enterprise. If the hub retains messages after they have been transported, the
database of information can be analyzed at a later date.
● Routing—The hub is able to apply rules to control the routing of messages, and to
support a variety of different routing models, such as publish and subscribe, non-
broadcast or broadcast.
● Monitoring—The ability to trace the progress of executing processes is vital for

monitoring the effectiveness of business processes and also for tracking critical
processes. A hub can be used to monitor executing business processes from a central
location.
Hub and spoke integration is generally implemented using Message Oriented Middleware
(MOM) such as Oracle Advanced Queuing (AQ).
Applications respond to business events by producing a message. The message is sent to the
hub (published) by the application. Depending on the capabilities of the MOM in the hub, the
message can be forwarded to a single application, or to multiple applications. The applications
may explicitly subscribe to a given message type, such as “New Orders”, or the message may
be broadcast to all, or a specific subset of applications.
The messaging infrastructure is generally asynchronous. This means that: the source of
message simply publishes a message, and does not wait for a reply from any of the receiving
applications. Messages can be stored in queues, providing some resilience to failures.
Messages are buffered in either the source application or the hub until the receiving
applications are available.
12-180
Creating a Hub
You can designate a swimlane to act as the hub. You can either:
● select a swimlane that represents an existing system to act as the hub
OR
● create a new swimlane whose sole purpose is to act as a hub
In either case, only a single-instance swimlane can act as the hub. Only one swimlane can act
as a hub in a diagram.
Only the name and instance properties, such as connection and AQ Servlet, need to be defined
for a swimlane that will act as the hub. Channels do not need to be defined on the swimlane, as
they will be provided automatically by the e-business integration code generator.
After you designate the swimlane to act as the hub, the icon on the swimlane changes to
.
To create a hub from a new swimlane:
1. Create a single-instance swimlane. How

2. Right-click the swimlane and select Select As Hub from the menu.
To create a hub from an existing swimlane:
● Right-click an existing single-instance swimlane and select Select As Hub from the
menu.
Note: If a swimlane is already selected as the hub for the diagram, and you select another
swimlane to be the hub, then the swimlane that was previously selected will revert to being a
normal swimlane. The newly selected swimlane will become the hub. There can only be one
hub in a diagram.
To deselect a swimlane as a hub:
12-181
● Right-click the swimlane representing the hub and select Deselect As Hub from the
menu.
Related Topics
Creating a Swimlane
12-182
Creating a System Instance
System instances are defined on swimlanes created on activity diagrams.
To define a system instance, double-click the swimlane on which you want to define a system
instance and set the following properties:
● The name of the system instance. About

● The database connection to the system that the instance represents. This connection
name must be unique on the activity diagram.
● the AQ Servlet, and the deployment profiles. You need to prefix the URL with either
HTTP:// or HTTPS:// to identify the required protocol.
Note: You can define multiple system instances against a single swimlane. The multiple
instance icon will appear in the upper left corner of the swimlane.
Related Topics:
Creating a Swimlane
12-183
Changing a Single Instance Swimlane to Multiple
Instance
You can transform a single instance swimlane into a multiple instance by defining additional
instances. For example, assume that you originally prototyped a swimlane for a single Buyer.
Then you decide to extend this process in the production implementation to support multiple
Buyers as part of an Exchange.
The following steps assume that:
● an activity diagram has been defined with swimlanes already created

● instance, channel, and optional messaging adapter inforamtion has been defined for a
single instance swimlane
To migrate a single instance swimlane to a multiple instance:
1. Right-click the swimlane for which you want to create another instance, and select
Properties.
OR
Right-click the name of the swimlane in the Navigator pane and select Properties.
2. Use the Instances tab of the dialog to create additional instances of the swimlane. How
3. Click OK to commit your changes and dismiss the Swimlanes dialog. The multiple
instance icon will appear in the upper left corner of the swimlane.
Related Topics
About Swimlanes
Creating a Swimlane
12-184
Swimlane - General Properties
Swimlane - Channels and Adapters Properties
Swimlane - Instances Properties
12-185
Deleting System Instances
This topic describes the effect on the generated code of deleting system instances from the
diagram.
Deleting a Source System Instance
Deleting an instance of a source system does not cause any changes to the definition files
because each instance is programmatically isolated from all of the other instances. There will,
however, be one less system instance definition generated in the sending system's
instanceInformation.xml file. This will cause one less system to be deployed.
Deleting a Destination System Instance
Deleting an instance from a multi-instance system implies that you are removing one of the
physical implementations of the system. For example, the Eastern and Western Shipping
Centers are branches of the Domestic Shipping Center. In the Queued Shipping example, this
is represented as the Domestic Shipping Center swimlane. If the Eastern Shipping Center
closes, then the corresponding instance can be deleted from the diagram. In this case, the
generated code for the integration point between the Order Entry and the Domestic Shipping
Centers will change.
Deleting a destination system instance has these implications for your generated code:
● One less instance will be created in the sending system's instanceInformation.xml

file.
● One less instance will be created in the receiving system's

instanceInformation.xml file.
● In the hub's BES, one less TO agent definition and one less system definition will be
generated.
● In the sending system's workflow definitions, one less TO_AGENT will be created.
● If you are generating an integration point in broadcast mode, one less event subscription
to carry the message to the destination will be generated.
12-186
● If you are generating an integration point in non-broadcast mode or generating a decision
point, the contents of the .wft file will change to reflect the new list of destination system
instances.
● If the number of destination instances drops from two to one, the instance routing code
will no longer be invoked at runtime.
For the routing code which you would write yourself to send messages to the correct recipients,
you probably would not have to make any changes to the content-based routing code.
However, you might need to change the instance selector code which routes non-broadcast
messages to the correct recipients.
12-187
Moving a Transition
A typical example of editing an existing transition is by changing the number of instances in its
destination system.
Changing the Destination From a Single Instance System to a Multi-

instance System
If the destination system of a transition changes from a single instance to a multiple instance,
you will typically have to make these changes to the definitions of your system and transition:
● change the name of the queue table and protocol, if necessary.
● adjust the value of the Broadcast flag.
● if you are performing the integration in non-broadcast mode, enter your instance selector
code in the Instance selector code field.
● change the name of the channels that the transition will use. The transition will need to
use a channel that has been defined for the system.
● ensure that the adapters have been defined correctly for the channels. Define a new
adapter for each new channel.
You will notice these changes in your generated code:
● an additional instance will be generated in the instanceInformation.xml file.
● instead of one BES definition for WF_AGENT and WF_SYSTEMS, multiple definitions
(one for each instance) will be generated.
● instead of only one event subscription to carry the message, multiple event subscriptions
(one for each instance) will be generated if broadcast mode is enabled.
Changing the Destination from a Multi-instance System to a Single

12-188
Instance System
If the destination of a transition changes from a multiple instance to a single instance, you will
typically have to make these changes to the definitions of your system and transition:
● change the name of the queue table and protocol, if necessary.
● any code that you provided in the Instance selector code field will be ignored.
● the value of the Broadcast flag will be discarded.
● change the channel for the transition. The transition will need to use a channel that has
been defined for the system.
● ensure that adapters has been correctly defined for the channels.
You will notice these changes in your generated code:
● instead of multiple BES definitions for WF_AGENT and WF_SYSTEMS, there will be
only one.
● if the integration was previously performed in broadcast mode, then instead of multiple
event subscriptions, a single event subscription will be generated.
12-189
Ways to Create an Integration Point
You can create the following general types of integration points:
● simple integration points—Here a message is sent directly from the source system to the
target system without going through an AND or OR pseudostate and without any content-
based routing.
● decision points—These include OR pseudostates where a single input transition splits

into two or more outbound transitions only one of which is chosen, and require content-
based routing of the message to determine its destination.
● synchronization points—These include AND or OR joins where two or more input

transitions result in a single output transition.
To be processed by the e-business integration code generator, these types require a message
to be sent from one system to another. All of these types can support multiple instance
systems.
Related Topics
About Simple Integration Points
Creating a Simple Integration Point
About Decision Points
About Synchronization Points
12-190
Integration Point Essentials
Integration points define the communication between sets of activities defined in a system.
The essential definitions required to work with integration points are:
● About simple integration points
● About decision points
● About synchronization points
● About broadcast mode
● About generating integration points
Related Topics
Defining an Integration Point
Generating Integration Points
12-191
In a simple integration point diagram, messages are sent from an activity on the sending system to an
activity on the target system. There is no AND or OR pseudostate; nor is there any specialized routing.
There are many possible ways to draw the elements contributing to a simple integration point, but all have
these things in common:
● a sending system
● a receiving system
● at least one channel defined on the sending system
● an optional sending adapter defined on the sending system channel
● at least one channel defined on the receiving system
● an optional receiving adapter defined on the receiving system channel
● a sending activity in the sending system
● a receiving activity in the receiving system
● an object flow state representing the message that is sent.
● a transition from the sending activity to the object flow state
● a transition from the object flow state to the receiving activity
The sending activity creates the message, represented by the object flow state, which is sent to the
receiving activity. Adapters might be required by the sending and/or receiving activity. These adapters,
which are owned by the channels, take the data from the sending activity and transform it into a format that
is suitable for transmission via the BES. They also take the message from the BES and transform it into a
format that can be used by the receiving system. Channels, which are defined on each system, provide the
communication endpoints to which messages are sent, and from which messages are received. The
channel properties define the mechanism that will be used to transmit the message (for example, whether it
is Oracle AQ messaging and what messaging protocol is used).
The channels must be associated with the sending and receiving activities. To do this use the transition's
12-192
Channel property. On the transition from the sending activity, this property identifies the Out channel; on the
transition to the receiving activity it identifies the In channel.
The following figure illustrates a simplified version of the queued shipping example. The Take Order activity
in the Orders system creates the Order[received] message. The Out channel identified on the transition
leading from Take Order provides the messaging mechanism and protocol to use. The message is passed
to the Allocate Stock activity in the Shipping system via the In channel identified on the transition leading
into the activity.
Figure 1: Simple Integration Point
Related Topics
12-193
About Decision Points
A decision point is a type of integration point where a decision is made at runtime as to the routing of the
message. Typically, the decision is made by analyzing the message body according to the content-based
routing code that you write in the transition's Condition Code property. Based on the results of the analysis,
the event is sent to the appropriate receiving activity. This is known as "conditional" or "content-based" routing.
Note: You are not limited to using only one decision in an integration point. If needed, you can chain decisions to
determine the appropriate target in an integration point. The generator will produce the appropriate Workflow and
Java to implement the decision tree.
There are many possible ways to draw the elements contributing to a decision point, but all have these things
in common:
● a sending activity in the sending system
● an object flow state representing the message that is sent.
● a transition from the sending activity to the object flow state
● a transition from the object flow state to the OR pseudostate
● transitions from the OR pseudostate to the receiving activities with rules defined to determine which
transition to choose.
12-194
The sending activity creates the message, represented by the object flow state, which is sent to one or more
of the receiving activities. Adapters might be required by the sending and/or receiving activity. These adapters,
which are owned by the channels, take the data from the sending activity and transform it into a format that is
suitable for transmission via the BES. They also take the message from the BES and transform it into format
that can be used by the receiving system. Channels, which are defined on each system, send and receive the
message. The channel properties define the mechanism that will be used to transmit the message (for
example, whether it is AQ messaging and what messaging protocol is used).
The channels must be associated with the sending and receiving activities. To do this use the transition's
Channel property. On the transition from the sending activity, this property identifies the Out channel; on the
transition to the receiving activity, it identifies the In channel. The pseudostate and the routing rules defined on
the transition determine how the message should be routed to the receiving system.
The following example illustrates a decision point. In it, the Take Order activity generates a new order
(Order[received]). The custom content routing Java code that you define on the transitions leading from the
pseudostate, analyzes the XML content of the message and determines whether it should be sent to the Clear
for Export activity in the Overseas Shipping system or to the Allocate Stock activity in one of the instances of
Domestic Shipping system.
Figure 1: Decision Point
Decision Points and Multiple Instance Systems
If the message is routed to the Domestic Shipping system, the generator will consult the value of the
transition's Broadcast flag when generating the integration point code. If broadcast is selected, the generator
creates code to send the message to all of the system instances.
12-195
If broadcast is not selected, the generator uses the code which you provide in the Instance Selector Code
property of the appropriate transition. This is where you can add your own message routing logic for specific
instances.
If the message is routed to the Overseas Shipping Center subsystem (which is a single instance system), the
value of the broadcast flag is ignored.
Variations on Decision Points
Sometimes the shape of a diagram can be misleading. What looks like a decision point can in reality be either
a simple integration point or might not be an integration point at all.
Decisions Made Within the Activity
A variation on a decision point is where the decision is made within the activity. In this case, no routing code
needs to be generated. A message is raised by the sending application signals that the BES on the hub
doesn't need to do any further evalution prior to routing the message. The e-business integration code
generator will treat this case as a simple integration point.
Figure 2: Two Ways to Represent a Decision Made in an Activity
12-196
In both cases the routing is determined entirely by the activity itself. No routing code needs to be generated.
The BES will be given a Result[success] or Result[failure] event from the activity.
Note: The BES can only control the routing of messages after the appearance of an object flow state in the diagram.
Anything that happens before an object flow state appears in an integration point is assumed to be done by sending
activities. In the two diagrams above, there is no decision point between the object flow states and their receiving
activities, hence no need for routing.
12-197
About Synchronization Points
A synchronization point represents a join of two or more concurrent flows of control and can be one of two types: AND or OR.
There are many possible ways to draw the elements contributing to a synchronization point, but all have these things in common:
● at least two sending activities in the sending system
● an object flow state for each sending activity, representing the messages that are sent.
● transitions from the sending activities to the object flow states
● transitions from the object flow states to the join (either an OR or AND pseudostate)
● a transition from the join to the receiving activity
The sending activities create the messages, represented by the object flow states. At an AND join, processing waits until all the
messages have reached the join. All will be sent to the receiving activity.
Figure 1: Synchronization Point with an AND Pseudostate
12-198
At an OR join, only one incoming message has to reach the join before processing continues. Only this message will be sent to
the activity, other correlated ones will be discarded. This is illustrated in Figure 2.
Figure 2: A Synchronization Point with an OR Pseudostate
Variations on Synchronization Points
As mentioned above, there are many different ways to draw a diagram that contains a synchronization point, but not all are
interpreted by the generator in the same way.
The following figure illustrates an object flow state drawn after the synchronization, which implies that the wait is done by the
activities in the sending system. The generator will interpret this diagram as a simple send.
Figure 3: Simple Send: Object Flow State Follows the Pseudostate
12-199
In Figure 4, only one of the sending activities participating in the synchronization point has an object flow state. In this case, the
generator will interpret this diagram as a simple integration point.
Figure 4: Simple Integration Point: One Object Flow State on One Sending Activity
12-200
About Broadcast Mode
When generating an integration point for a multi-instance destination, the message can be sent
to the receiving activity in broadcast mode or non-broadcast mode. Broadcast mode is a
property belonging to transitions. You set the mode with the Broadcast checkbox in the
properties dialog of the transition leading to the target activity.
In broadcast mode, a message is sent to all of the instances of the receiving system. The e-
business integration code generator will create all of the required code to route the message to
all of the instances.
In non-broadcast mode, the message is sent to only selected instances. In this case, you must
write the custom instance routing code that will route the message to the appropriate instance.
The Transition Properties dialog provides an Instance Selector Code property where you can
enter the code.
Related Topics
Integration Properties on Transitions
Using Custom Instance Routing Logic
12-201
There are many possible ways to draw the elements representing a simple integration point.
The minimum information that you must provide to generate a simple integration point is
described in About Simple Integration Points.
An integration point can be created with a single instance destination, a multiple instance
destination in broadcast mode or multiple instance destination in non-broadcast mode.
Note: To define an integration point, you must first have created the necessary elements on an
activity diagram. These elements are: a swimlane, an INITIAL pseudostate and two or more
activities separated by an object flow state (representing the message that is sent between the
systems) connected together using transitions.
Although the properties required to define an integration point can be set on the individual
elements that comprise the integration point, all the required properties for an integration point
can defined using the E-Business Integration Wizard.
To define an integration point:
1. Click the diagram on which the elements required to define the integration point are
displayed.
3. Click Next on the Welcome page of the wizard.
The integration points that are on the diagram are listed, together with their current
status.
❍ a blue check mark is displayed next to fully defined integration points
❍ a red cross is displayed next to integration points that are not fully defined
4. Select the integration point you want to define.

5. Click Next to define system instances and channels on the swimlanes in the selected
integration point.
Note: A swimlane is defined if it has at least one system instance, the database
connection property of which must be unique for all instances on the active diagram
6. Click Next to define channels for the end points in your integration point, and whether the
channel is broadcast, or selective by entering instance selector code.
Note: If the same channel is used for two different applications, once a message has
been dequeued to go to the wrong application it cannot be enqueued again.
7. Click Next to define the decision points in your integration point by entering a guard
12-202
condition, and optionally entering Java condition code.
8. Click Next to view a summary of the definitions entered for the integration point.
9. Click Finish.
10. Click Yes to return to the start of the wizard to continue defining the e-business
integration.
11. Select the swimlane you want to act as the hub for your e-business integration by
selecting the radio button in the Hub column next to the name of the swimlane.
Note: Only a swimlane for which a single system instance has been defined can be
selected as the hub.
12. Click Finish.
Related Topics
Generating an Integration Point
12-203
Generating Integration Points
The e-business integration generator can be used to generate the selection of integration
points you choose in the E-Business Integration Wizard. It creates a Generated EBI Files folder
under the current project and subfolders for each swimlane defined in the project. Each
swimlane folder contains a subfolder corresponding to a diagram in which it is defined. For a
description of the generated files themselves, see Files Generated by the E-Business
Integration Code Generator.
To generate integration points:
1. Click the diagram on which you have defined your integration point to ensure that it is
active.
3. If the Welcome page is displayed, click Next to display the Overview page of the E-
Business Integration Wizard.
4. Select the Generate checkbox for the integration points you want to generate.
Note: You can only select the Generate checkbox for an integration point if that
integration point has been fully defined. Integration points that are fully defined are
displayed with a blue check mark .
5. Select the hub for the e-business integration.
6. Click Finish.
7. Click Yes on the confirmation dialog listing the structures to be generated.
A progress monitor opens and tracks the file generation. The progress is also recorded in
the log window. If prompted whether to add the project to the source path, click Yes.
Click OK to dismiss the alert box that opens when generation is complete. The generator
creates a Generated EBI Files folder in the Navigator window and stores the generated
files under it.
12-204
Related Topics
Files Generated by the E-Business Integration Code Generator
Using Custom Content Routing Logic
12-205
Files Generated by the E-Business Integration
Generator
The activity modeler generates the files for messaging when you select the diagram and
choose Model | Generate | E-Business Integration from the right mouse menu.
The generator creates a Generated EBI Files folder under the current project and subfolders
for those swimlanes that take some active part in the process on the diagram. In other words,
empty swimlanes or swimlanes which are never entered won't have a subfolder created for
them. Each swimlane folder contains a folder corresponding to a diagram in which it is defined.
The individual files which are generated define:
● AQ definitions
● BES definitions
● Workflow definitions
● instance information
● deployment profiles
● custom routing logic
Note: After the files are generated, they are automatically saved. The only exception is that you
must save the project after adding the Generated EBI Files folder. Otherwise the
Generated EBI Files folder will not be visible the next time JDeveloper is started.
AQ Definitions
An AQ definitions file will be generated if the system can send or receive messages, and it is an
Oracle database-based system. This is an XML file that stores the names of the AQ queues,
the queue tables that they should be stored in, and details of any propagation schedules which
may be defined for its queues. All other properties of the queue will be defaulted when the
12-206
queue is created. AQDefinitions.xml uses the instance information file to find the name of
the database connection that it will use to access the target system. For more information on
editing AQ definitions, see Editing AQ Definitions.
BES Definitions
The generator creates a BESDefinitions.xml file and stores it in the hub's subfolder. This is
an XML file that stores the names of the systems, agents, events, and event subscriptions that
will be used in messaging between the systems. During deployment, only the events are
deployed as is without modification. For the system, agent, and event subscription information,
BESDefinitions.xml uses the instance information file to make the following modifications
to them for deployment:
● one system definition is assigned for each system instance

● one agent for each instance is assigned to each channel
● one event subscription is assigned to each instance of a target system.
Workflow Definitions
The generator generates a WorkflowDefinitions.wft file and places it in the hub's

subfolder. The WorkflowDefinitions.wft file can be opened and used by Oracle
Workflow. If the systems have multiple instances, then the system instance names in the
instance information file are used to modify the addresses of any agents that are used to send
or receive messages. You can use Oracle Workflow Builder to modify the layout of the
generated workflow.
Instance Information
The generator creates an instanceInformation.xml XML file for each system and stores it
in the system's subfolder. This file contains the names and properties of all of the system's
instances such as instance names, connection names, AQ Servlet URLs, and system IDs. The
file also contains instance information for any systems that are referenced. This file is used
during deployment to apply the BES, AQ, and workflow definitions to the appropriate instances.
Deployment Profiles
The generator creates XML-based deployment profiles for the Generated EBI Files folder
and for each of the system subfolders. Each folder is a directly-deployable node. For more
information see About Deployment Profiles.
12-207
Custom Routing Logic
The generator creates the RoutingLogicdiagram_name.java file to determine the routing of

messages through decision points and to multiple instances. This file contains:
● the Java code that you enter in the Condition Code property of the Transition Properties
dialog to perform the message evaluation. At runtime, the condition code receives all the
messages, then determines how the message should be routed. For more information on
the contents of this file, see Using Custom Content Routing Logic.
● the Java code that you enter in the Instance Selector Code property of the Transition
Properties dialog to perform the message evaluation. At runtime, the condition receives
all messages, then determines the instance to which the message should be routed. For
more information on the contents of this file, see Using Custom Instance Routing Logic.
12-208
When messages are being sent in non-broadcast mode to systems with multiple instances, you must provide
custom instance routing logic to decide which instances should receive the message. The code that you write must
fulfill these requirements:
● the code must evaluate the contents of an array of message elements, where each message is of type
org.w3c.dom.Document
● the code must determine whether the message should be sent to the instance whose name is passed to it
● the code must return a boolean value
● comments entered in the Condition Code field will not be displayed in the generated code.
You can enter the custom instance routing logic as a block of Java code in the Transition Properties dialog that
belongs to the transition that leads to the activity in the multi-instance system. To enter the code, you can either:
● enter the code directly in the Instance Selector Code property of the dialog
OR
● click the Edit button beneath the Instance Selector Code property to open a code editor
When you generate from the activity diagram, a class file for the routing code called
RoutingLogicdiagram_name.java is created. The generator produces one routing file for each activity diagram. This
file contains the routing code for each target of an integration point that lies in a multi-instance system. By default,
the class will be placed into the same package as the activity diagram from which it was generated.
The code that you provide will be generated into the Java file the first time that you run the e-business integration
code generator. If you run the generator again, the method that was generated the first time will be left unchanged.
This is in case you make any modifications to the method after generation.
Note: the RoutingLogicdiagram_name.java file also contains the custom content routing logic for each decision
point in the diagram that requires content-based routing.
For each decision point requiring routing to a particular instance, the file contains one or more
instanceSelectorActivity_name(Document[] messages, String agentName, String agentInstance) methods. The
number of methods for each decision point depends on how many target systems have multiple instances.
The content of all the messages available to the decision (normally only one message, but in the case of a
combined decision and synchronization point there may be more) will be accessible through the array messages,
containing objects of type org.w3c.dom.Document. It is also passed the name of the BES agent, agentName, and
the name of the individual instance the agent services, agentSystem.
For example, Figure 1 illustrates a decision point where a message can be routed to a multiple instance system.
The Order[received] message can be sent either to the Clear for Export activity in the Overseas Shipping system or
to the Ship Order activity in one of the instances of the multiple-instance Domestic Shipping system.
12-209
The Domestic Shipping system has two instances: the Eastern Shipping Center and the Western Shipping Center.
In this example, assume that the message contains a RECIPIENT field that lists the name of the shipping center to
which the message should be sent. Your instance selector code can use the value of this field to determine the
destination of the message.
Figure 1: Decision Point Requiring Instance Selector Code
You enter the code in the Instance Selector Code property in the properties dialog for the transition from the OR
pseudostate to the Ship Order activity. The code that you would enter to determine which instance receives the
message could look like this:
for (int i=0; i<messages.length; i++)

{
Document msg=messages[i];
Element docEl=msg.getDocumentElement();
NodeList nodes=docEl.getElementsByTagName("destination");
Node node=nodes.item(0);
Text orderCode=(Text) node.getFirstChild();
if (orderCode.getData().equals(agentInstance))
{
return true;
}
}
return false;
Related Topics
About Transitions
12-210
12-211
Using Custom Content Routing Logic
Decision points require the content of an message to be examined and evaluated against some criteria that you
provide. The result of the evaluation determines how the message should be routed. You enter the evaluation criteria
in the form of Java code in the Condition Code property of the Transition Properties dialog. As an alternative, you can
use a code editor by clicking the Edit button. The code that you write must fulfill these requirements:
● one block of code Java code must be written on each transition whose source is the OR pseudostate in selected
instances in non-broadcast mode
● the code must evaluate the contents of an array of message elements, where each message is of type
org.w3c.dom.Document.
● the code must return a boolean value.
● comments entered in the Condition Code field will not be displayed in the generated code.
When you generate from the activity diagram, it creates a class file for the routing code called
RoutingLogicdiagram_name.java. The generator produces one routing file for each activity diagram. This file
contains the routing code for each decision point in the diagram that requires content-based routing. By default, the
class will be placed into the same package as the activity diagram which it was generated from.
The code that you provide will be generated into the Java file the first time that you run the e-business integration code
generator. If you run the generator again, the method that was generated the first time will be left unchanged. This is in
case you make any modifications to the method after generation.
Notes:
● The RoutingLogicdiagram_name.java file also contains the custom instance routing logic for routing
messages to selected instance in non-broadcast mode.
● After the activity modeler generates the RoutingLogicdiagram_name.java file, you must edit it to add import
statements for all of the classes that are used in your routing code.
For each decision point requiring routing, the file contains a makeDecisionidentifier(Document[] messages)
method. This method is passed an array of message elements, where each message is of type
org.w3c.dom.Document. It invokes private methods that correspond to the transitions that have the decision point
as a source and it returns a result code that enables workflow to decide which route to take through the decision point.
The makeDecision method has private isDecisionidentifierRuleXTrue(Document[] messages) methods for

each transition whose source is the OR-pseudostate in the decision point. The method body is the Java code that you
provided to the Condition Code property for the transition.
The e-business integration code generator will generate each block of Java code as a method with a boolean return
value.
The content of all the messages available to the decision (normally only one message, but in the case of a combined
decision and synchronization point there may be more) will be accessible through the array messages, containing
objects of type org.w3c.dom.Document.
Once you have defined all of your Java code, the generator places all of the methods inside a class,
RoutingLogicdiagram_name.java, and adds the method which can be invoked from Oracle Workflow by a special
12-212
workflow function activity.
For example, assume that you have a decision point that determines message routing based on the value of a
customer order. If the order value is less than 1000, stock is allocated. If the value is greater than 1000, a credit check
is performed. The diagram for such a decision point could look like this:
Figure 1: Decision Point Requiring Content-Based Routing
The condition code which you would enter on the transition connecting the OR and the Check Credit activity to test for
order value greater than 1000 could look like this:
for (int i=0; i < messages.length;i++)

{
Element docEl = messages[i].getDocumentElement();
NodeList valueNodes = docEl.getElementsByTagName("VALUE");
if (valueNodes.getLength() > 0)
{
Node valueNode = valueNodes.item(0);
Text valueText = (Text) valueNode.getFirstChild();
int valueFromNode = Integer.parseInt(valueText.getData());
return valueFromNode > 1000;
}
}
return false;
The condition code which you would enter on the transition connecting the OR and the Allocate Stock activity to test
for order value less than or equal to 1000 could look like this:
for (int i=0;i < messages.length;i++)

{
12-213
Element docEl = messages[i].getDocumentElement();
NodeList valueNodes = docEl.getElementsByTagName("VALUE");
if (valueNodes.getLength() > 0)
{
Node valueNode = valueNodes.item(0);
Text valueText = (Text) valueNode.getFirstChild();
int valueFromNode = Integer.parseInt(valueText.getData());
return valueFromNode <= 1000;
}
}
return false;
Related Topics
About Transitions
12-214
The activity modeler generates code that will let you initialize and start the messaging adapters
from the client. It also generates an XML adapter properties file that contains the values used to
initialize the adapter. If you do not want to use the client code generated by the activity
modeler, you can write your own client code and properties file.
See the following topics for more information on generating and writing client code for the Basic
and Business Components for Java Messaging Adapters:
Basic Messaging Adapter Client Code
Generating the Basic Sending Adapter Client Code
Writing Your Own Basic Sending Adapter Client Code
Generating the Basic Receiving Adapter Client Code
Writing Your Own Basic Receiving Adapter Client Code
Business Components for Java Messaging Adapter Client Code
Generating the Business Components for Java Sending Adapter Client Code
Writing Your Own Business Components for Java Sending Adapter Client Code
Generating the Business Components for Java Receiving Adapter Client Code
Writing Your Own Business Components for Java Receiving Adapter Client Code
Related Topics
About Messaging Adapters
Basic Sending Adapter
12-215
Basic Receiving Adapter
Business Components for Java Sending Adapter
Business Components for Java Receiving Adapter
Subclassing the Business Components for Java Receiving Adapter
12-216
Messaging Adapter Essentials
To participate in messaging, an application can use an adapter. An adapter is a piece of
software that is used to translate the information from an application into a form suitable for
transmission, and to rebuild the received information into the form required by the receiving
application. These adapters send and receive information asynchronously via queues.
The e-business integration Messaging Adapter Framework provides two types of adapters: a
Basic adapter and a Business Components for Java adapter. Both of these types make the
logical distinction between a sending and a receiving adapter. The adapters can be used in hub-
based system.
The adapters generated by e-business integration are only one of many kinds of adapters that
can serve the purpose of translating information. There's no need to specify an adapter if that
capability is being provided from elsewhere. An example would be a pre-built adapter provided
by a specialist vendor.
Related Topics
About Channels
Messaging Adapter Library
Basic Adapter Architecture
Business Components for Java Adapter Architecture
12-217
Messaging Architecture
This topic describes the relationship between the messaging services used by e-business
integration. Figure 1 illustrates the architecture.
Communication begins when an adapter on an application system notifies the Oracle Workflow
Business Event System (BES) that an event, for example an event associated with the
Order[received] object flow state, has occurred. The BES looks up its event subscriptions in
order to identify the target system(s) that events of this type must be sent to. If there is a
decision to be taken as to the destination system, perhaps based on the size or type of the
order, Workflow is invoked to evaluate the message content. Once a target has been identified,
the BES passes the message to a queue on that system.
The architecture illustrated in Figure 1 uses the Java Messaging Service (JMS) as the interface
to the queuing system, in this example, Oracle's Advanced Queuing (AQ). AQ is used for
passing messages asynchronously to and from the database.
Figure 1: Messaging Services Used by e-business integration
Database—AQ/JMS Interface
Advanced Queuing is Oracle’s database-integrated message queuing system. It not only

provides all the functionality of traditional enterprise messaging systems, but also is a complete
message management system. The messages carry object data as their payload, and use AQ
as a means of moving data out of and in to the database. Advanced Queuing implements and
extends the JMS API specification to provide a Java interface to AQ and to provide additional
features unique to Advanced Queuing.
12-218
AQ/JMS—Adapter Interface
In order to participate in messaging, an application system must use an adapter. Adapters are
used to translate the information from an application into a form suitable for transmission, and
to rebuild the received information into the form required by the receiving application. These
adapters send and receive information asynchronously via queues.
Business Components for Java Adapters
One such adapter used by e-business integration is based on Business Components for Java.
A Business Components for Java adapter is illustrated in Figure 2. When business event data
(such as a new order) is entered into a database, Business Components for Java makes the
data available as a Java Object. In Business Components for Java terms, this means that the
business data appears as Entity Objects, View Objects, and Application Modules.
Figure 2: A Business Components for Java Adapter
Business Components for Java includes methods to convert these components to and from
XML. Data can be converted into XML and placed on a message queue. The message payload
is the XML data derived from the original business data in the database. This message is
routed to one or more destination systems, which reverse this process to store the data in the
remote databases.
12-219
The e-business integration Messaging Adapters library is an extensible framework to facilitate
generation and rapid development of message-enabled classes and Business Components for
Java components. It builds upon the existing XML features provided by the Business
Components for Java framework and the messaging features provided by JMS/Oracle AQ. The
Messaging Adapters framework also provides fully integrated code generation from the
JDeveloper activity modeler with little additional work.
The e-business integration Messaging Adapters reside in the oracle.bm.ebiadapters

package, which is included in the JDeveloper library ebiadapters.jar. This library can be
found in the file system under JDevHome\lib.
The adapters in the e-business integration Messaging Adapters Runtime Library are described
in more detail in these topics.
Basic Message Adapters:
● Basic Sending Adapter

● Basic Receiving Adapter
Business Components for Java Message Adapters:
● Business Components for Java Sending Adapter

● Business Components for Java Receiving Adapter
● Subclassing the Business Components for Java Receiving Adapter for specifying custom
behavior
Other classes in the e-business integration Messaging Adapters Runtime Library:
● oracle.bm.ebiadapters.AdapterFailureException—An
AdapterFailureException is thrown when any of the adapters encounters an
exception at runtime. For example, the exception could be caused by connecting to the
database, creating the session, or the JMS connection. Instead of immediately
propagating or showing the original exception, a new AdapterFailureException is
created. This contains a readable, one-line statement of the reason why this exception
occurred. The original exception is accessible via the getOriginalException()
method.
12-220
● oracle.bm.ebiadapters.AdapterMessage—An AdapterMessage is a wrapper
that is required for message payloads that are sent and received using the e-business
integration Messaging Adapters. For more information, see Using the AdapterMessage
Class for Message Payloads.
Related Topics
Setting Messaging Adapter Properties
12-221
More on Deployment Profile Selectors
If you have defined messaging adapters for any of the swimlane's channels, then for each
system instance, you must assign a deployment profile to each adapter. This is because
channels can be defined against swimlanes. If a channel has a messaging adapter, then the e-
business integration code generator will generate code into the target class that will instruct it to
use a messaging adapter library class.
Deployment profile selectors allow you to choose the way that messaging adapters are
deployed to the target systems previously defined for those adapters. For every deployable
instance for an adapter, you must specify the profile used for the deployment.
12-222
Basic Adapter Architecture
The Basic adapter provides generic enqueuing and dequeuing services and can be used with
any type of application. Figure 1 illustrates the Basic sending and receiving adapters in the
context of a Hub-based system.
Figure 1: Basic Sending and Receiving Adapters in the Context of a Hub-based System
These adapters require you to provide custom code to deliver data:
● from the database to the sending adapter

● from the receiving adapter to the database
12-223
The Basic sending adapter accepts String data from the custom code on the sending system
and forms it into a message payload and enqueues it on the messaging system. The Basic
receiving adapter simply dequeues a message from the queuing system and passes its
String payload to your custom code.
Related Topics
12-224
The Basic Sending Adapter oracle.bm.ebiadapters.BasicSendingAdapter can be used for
enqueuing messages to an Oracle AQ. The messages that it works with do not have to be in XML; they
can have any content, as long as they can be represented as a java.lang.String.
The Basic Sending Adapter simply accepts the application data as an array of AdapterMessage objects.
Each AdapterMessage object wraps a String payload. You must provide the code that wraps the
String payload in an AdapterMessage object and form them into an array. The adapter then enqueues
the AdapterMessage array. If you require any custom behavior, you would write your own code and apply
it either before or after the enqueue action. You cannot subclass the adapter.
The Basic Sending Adapter can be used from any Java class. There are no dependencies on any
Business Components for Java code, so that this adapter can be used anywhere. It could be used in a
Business Components for Java application module, although it is more likely that within the context of an
application module you will want the greater functionality provided by the Business Components for Java
Sending Adapter.
The activity modeler can generate the Basic Sending Adapter client code to initialize and start the adapter
or you can write your own client code. You must then write your own code to call the adapter client code
when you need to use the adapter.
Sending Messages
The following steps describe what happens once the adapter is started by calling the sendMessage()
method, and how the send request is serviced. For more information, refer to the generated Basic
Sending Adapter client code.
1. A generated method in the client code calls the sendMessage method. This determines the name
of the properties file, reads the properties, and starts the adapter. The initialization values are
validated. If any of the values are incorrect, an AdapterFailureException is thrown. If the
values are correct, the adapter is started.
final public void sendMessage(Object this_ref, AdapterMessage[] messages) throws

AdapterFailureException
2. Within the sendMessage method, the messages in the AdapterMessage[] array parameter are
enqueued to the specified queue one at a time.
If there is any exception during the sending process, such as connecting to the database, creating
the session, or the JMS connection, an AdapterFailureException is thrown.
3. When all of the messages have been sent, control returns to the client code.
12-225
Related Topics
Using the AdapterMessage Class for Message Payloads
12-226
The Basic Receiving Adapter oracle.bm.ebiadapters.BasicReceivingAdapter can be used for dequeuing messages from
an Oracle AQ. The messages that it receives do not have to be in XML; they can have any content, as long as they can
be represented as a java.lang.String.
The Basic Receiving adapter simply dequeues an AdapterMessage object from the queue. If you require the message
payload to be unwrapped or any custom behavior, you would write your own code and apply it either before or after the
dequeue action. You cannot subclass the adapter.
The Basic Receiving adapter can be used from any Java class. There are no dependencies on any Business
Components for Java code, so this adapter can be used anywhere. It could be used in a Business Components for Java
application module, although it is more likely that within the context of an application module you will want the greater
functionality provided by the Business Components for Java Receiving adapter.
The activity modeler can generate the Basic Receiving adapter client code to initialize and start the adapter or you can
write your own client code. You must then write your own code to call the adapter client code when you need to use the
adapter.
Receiving Messages
The following steps describe the call stack for the Basic Receiving adapter. They describe what happens once the
adapter is started (by calling the receiveMessage() method), and how the receive request is serviced. For more
information, refer to the generated Basic Receiving adapter client code.
1. A generated method in the client code calls the receiveMessage method. This determines the name of the
properties file, reads the properties, and starts the adapter. The initialization values are validated. If any of the
values are incorrect, an AdapterFailureException is thrown. If the values are correct, the adapter is started.
final public AdapterMessage receiveMessage(Object this_ref) throws AdapterFailureException
2. Within receiveMessage, the AdapterMessage object is dequeued. If necessary, the method will wait for a
message object to arrive.
If there is any exception during the sending process, such as connecting to the database, creating the session or
the JMS connection, an AdapterFailureException is thrown.
3. After dequeuing the message, control returns to the receiveMessage method.

4. The receiveMessage method returns control to the client code.
Related Topics
12-227
12-228
Business Components for Java Adapter Architecture
The Business Components for Java adapters work with XML data and are designed to be used
with Business Components for Java applications. Figure 1 illustrates Business Components for
Java sending and receiving adapters in the context of a hub-based system.
Figure 1: Business Components for Java Sending and Receiving Adapters in the Context of a Hub-based
System
The Business Components for Java sending adapter accepts view objects as data from a Business
Components for Java application, writes them as XML, and enqueues them on an Oracle AQ.
The receiving adapter dequeues the adapter message object, parses it, optionally transforms it
according to an XSL stylesheet, and incorporates it into a view object. Unlike the other adapters,
you can subclass the Business Components for Java Receiving adapter to provide your own code
for message transformation, parser error handling, and transaction handling.
12-229
Related Topics
12-230
The Business Components for Java sending adapter oracle.bm.ebiadapters.BC4JSendingAdapter
can be used for writing the contents of a Business Components for Java view object as XML and then
enqueuing this XML as an array of AdapterMessage objects on an Oracle AQ. It should be noted that while
there are Business Components for Java Sending and Receiving adapters which can provide e-business
integration, you are not required to use them together in pairs.
The Business Components for Java Sending adapter takes an array of AdapterMessage objects, where
each AdapterMessage wraps a view object. You must provide the code to wrap the view objects in
AdapterMessage objects and then form them into an array. The adapter then enqueues the array of
messages. If you require XSL message transformation, you can make it part of the sending process; it does
not have to occur before the enqueue. You cannot subclass the adapter.
The activity modeler can generate the Business Components for Java Sending adapter client code to
initialize and start the adapter or you can write your own client code. In either case, the code must appear
within the context of a Business Components for Java application module. This is because the code needs
access to the application module's view objects. To get this access, a this reference passes the application
module context to the adapter. After providing the client code, you must then write your own code to call the
adapter client code when you need to use it.
Business Components for Java Sending Adapter Call Stack
The following steps describe the call stack for the Business Components for Java Sending adapter. They
describe what happens once the adapter is started (by calling the sendMessage method), and how the
send request is serviced. For more information, refer to the generated Business Components for Java
Sending adapter client code.
1. A generated method in an application module in the client code calls the sendMessage method. This
determines the name of the properties file, reads the properties, and starts the adapter. The
initialization values are validated. If any of the values are incorrect, an AdapterFailureException
is thrown. If the values are correct, the adapter is started.
final public void sendMessage(ApplicationModule appMod, AdapterMessage[] messages)
Each of the view objects in the array is sent to be written as an XML message.
2. Within sendMessage, the contents of each view object is written out in XML.
If there is any exception during the sending process, such as connecting to the database, or creating
the session or the JMS connection, an AdapterFailureException is thrown.
3. One at a time, a single message object is enqueued onto the specified queue.
4. The enqueue method returns to get the next message object.
12-231
5. When all of the adapter message objects have been sent, control returns to the client code.
Related Topics
12-232
The Business Components for Java receiving adapter oracle.bm.ebiadapters.BC4JReceivingAdapter can
be used for dequeuing an AdapterMessage object from an Oracle AQ, parsing it, and incorporating it into a view
object. It should be noted that while there are Business Components for Java sending and receiving adapters which
can provide e-business integration, you are not required to use them together in pairs.
Business Components for Java receiving adapter has features not shared by other adapters. You can:
● choose the service lifetime of the adapter. That is, you can have the adapter service only one message then
finish, or you can have the adapter wait for and service messages indefinitely.
● subclass the adapter class to add your own message transformation, parser error handling, and transaction
handling code. Since the adapter could potentially run indefinitely, having the flexibility to implement your own
logic is advantageous.
The activity modeler can generate the Business Components for Java receiving adapter client code to initialize and
start the adapter or you can write your own client code. In either case, the code must appear within the context of a
Business Components for Java application module. This is because the code needs access to the application
module's view objects. To get this access, a this reference passes the application module context to the adapter.
Incorporating Messages into View Objects
When the Business Components for Java receiving adapter receives an XML message, it must decide into which
view object it should incorporate the message. The first time that the adapter runs, it builds a mapping table. This
mapping table pairs the view object names with the values of their corresponding XML_ELEMENT document element
property (or the default, if one has not been set). Then, when the adapter receives a message, it does a lookup on
the document element tag name and retrieves the name of the view object into which the XML message should be
incorporated.
XML_ELEMENT is a Business Components for Java custom property. Its value is used as the XML element name for
the view object in XML when it is generated using the writeXML method and "consumed" by the readXML method.
By default, the XML_ELEMENT name is the same as the name of the view object.
Encountering Non-unique Document Element Properties
View objects have custom properties that allow you to override the value of the XML_ELEMENT property. If you use
these methods to override the element values and your changes result in two or more view objects having the same
value for XML_ELEMENT, then the table lookup will choose the first match it finds.
Business Components for Java Receiving Adapter Call Stack
The following steps describe the call stack for the Business Components for Java Receiving adapter. They describe
what happens once the adapter is started (by calling the receiveMessage() method), and how the receive request
is serviced. For more information, see the generated Business Components for Java Receiving adapter client code.
1. A generated method in the client code calls the Business Components for Java receiving adapter method. The
receiving adapter is initialized from an XML properties file with the name of the JDBC driver, JDBC URL, the
queue name, JMS agent name, AQ schema name, schema password, and service lifetime. The initialization
12-233
values are validated. If any of the values are incorrect, a AdapterFailureException is thrown. If the values
are correct, the adapter is started.
final public void receiveMessage(ApplicationModule appmod) throws AdapterFailureException
2. A message is dequeued from the specified queue. If necessary, the method will wait for a message to arrive.
3. If you choose to provide your own message transformation code, a template method will be called that will
enforce the method call order in the adapter.
4. The custom transformation is called if you want to provide your own code to transform the message payload.
For example, you could use this method to transform the date format or convert the currency used in the
message. This method could also be used to call other code for logging or auditing. The
doCustomTransformation method does not have any message transformation code of its own, so if you do
not override it, it has no effect on the message payload.
public String doCustomTransformation(String XMLMessage)
5. The Oracle XML Parser is called to parse the dequeued and optionally transformed message.
You can provide your own custom error handling code to handle any errors that occur during parsing. For
example, you could write a message to a log file or raise an alert box. Override the following method only if you
want to provide your own error handling code. The method does not have any error handling code of its own,
so if you do not override it, it has no effect.
public void doParseErrorHandling(Exception e, String m_messagePayload)
6. The parsed XML document is incorporated into the relevant view object using Business Components for Java
readXML() rules.
7. You can provide your own routines to commit the transaction and changes to the view object. Override the
following method only if you want to provide your own commit code. By default, a commit is performed after
each message is incorporated into the relevant view object.
public void handleTransaction(ApplicationModule appMod, int numOfMessagesReceived)
8. Control returns to the method that dequeues XML messages.

9. If serviceMultipleMessages is set to false (Service lifetime=Single in the Adapters page), control
returns to the client code. This is because serviceMultipleMessages=false indicates that only a single
message will be serviced. If serviceMultipleMessages=true (Service lifetime=Many), the adapter waits
for another message to be dequeued.
Related Topics

12-234
12-235
Creating Basic Messaging Adapters
The following topics describe how to create basic messaging adapters:
● Generating the Basic Sending Adapter Client Code
● Writing Your Own Basic Sending Adapter Client Code
● Generating the Basic Receiving Adapter Client Code
● Writing Your Own Basic Receiving Adapter Client Code
12-236
The activity modeler generates:
● Java client code to initialize and start the Basic Sending Adapter
● an XML adapter properties file that contains the values used to initialize the adapter
If you do not want to use the client code generated by the activity modeler, you can write your
own client code and properties file.
The code that the activity modeler generates and the values in the properties file are based on
your choice of options in the Messaging Adapter page of the Swimlane Properties dialog. In this
case, to generate client code for the Basic Sending Adapter, choose:
This Messaging Adapter field Has this value

Has Sending Adapter selected
Trace selected or clear
Direction Sending
Type Basic
Target Class the name of a valid Java class
Stylesheet URL not applicable
Depth Count not applicable
Service Lifetime not applicable
Use Subclass not applicable
Note: Comments entered in the code on the properties dialog will not be displayed in the generated
code.
After generating the adapter client code, you must write your own code to call the adapter client
code when you need to use it.
The following is a sample of the Java code generated for the Basic Sending Adapter client.
BasicSendingAdapterClientCode.java
public void sendMessage(AdapterMessage[] messages)

{
12-237
try
{
BasicSendingAdapter adapter = new BasicSendingAdapter();
adapter.sendMessage(this, messages);
}
catch(AdapterFailureException adapterExcept)
{
adapterExcept.printStackTrace();
}
}
Description of the Basic Sending Adapter Client Code
The following sections describe the features of the generated client code.
Call Tracing and Debugging Methods
Before the adapter is started (using the sendMessage() method) the generator can insert
debug trace method calls based on the value of the Trace checkbox in the Messaging Adapter
page. By default, the checkbox is clear. This causes the adapter.setShowTrace method to be
omitted: no tracing or debugging comments will be written by default. The code sample above
was generated with the Trace checkbox clear.
If the checkbox is selected, then an adapter.setShowTrace(true) is generated in the code and

tracing comments are enabled. When tracing comments are enabled, the default output stream
is System.out. If you wish, you can change this in the generated file by calling the
setPrintStream() method with a java.io.PrintStream object. This allows the writing of trace
comments to a file, for example.
Call the sendMessage Method
Once the initialization properties and any tracing and debugging methods have been set, the
adapter can be started using the sendMessage() method. The messages in the
AdapterMessage[] array parameter are enqueued to the specified queue, and control returns to
the client code when this is done. If any kind of exception arises during the sending process, an
AdapterFailureException is thrown and control returns to the catch clause.
You could add your own code to the generated file to iterate around the sendMessage()
method as many times as you want. However, this is not advised because:
● the AdapterMessage[] parameter allows you to send multiple messages in one call to
sendMessage().
12-238
● each time you call sendMessage() a new JDBC connection is created. When the method
finishes the JDBC connection is closed. Hence, iterating around the sendMessage()
method in client code is not advised.
Catch Exception Block
The generator creates a catch block for exceptions and includes a printStackTrace() method for
debug tracing. If you wish, you could add a getOriginalException().printStackTrace() statement
to get the original exception.
Defining Basic Sending Adapter Properties
If you direct the activity modeler to generate the Basic Sending Adapter client code, it also
generates an XML properties file that contains all of the information necessary to allow the
adapter to communicate with an Oracle AQ queue. The name of the file follows the convention
Classname-sender-apf.xml, where Classname is the name of the class which contains the
adapter.sendMessage() call for the adapter. The adapter uses the properties file at runtime and
stores it in the same directory as the Classname.class adapter file. In the case of this Basic
Sending Adapter example, the XML properties file has the name
BasicSendingAdapterClientCode-sender-apf.xml.
The following is a sample properties file for a Basic Sending Adapter.
BasicSendingAdapterClientCode-sender-apf.xml
<?xml version = '1.0' encoding = 'UTF-8'?>

<!DOCTYPE adapterProperties>
<?Oracle-JDeveloper Object2Dom = '1.0'?>
<adapterProperties>
<jdbcDriver>oracle.jdbc.driver.OracleDriver</jdbcDriver>
<jdbcURL>jdbc:oracle:thin:@address:1521:address</jdbcURL>
<queueName>widgetqueue</queueName>
<queueSchemaName>queues</queueSchemaName>
<queueSchemaPassword>queues</queueSchemaPassword>
</adapterProperties>
The following table describes the properties used in the Basic Sending Adapter XML properties
file.
12-239
Property Description and Example
the name of the JDBC driver class to use.
jdbcDriver This value is derived from the database
connection.
the JDBC URL to the schema containing
jdbcURL the Oracle AQ on which to enqueue the
messages. This value is derived from the
queueSchemaName the name of the AQ schema.
queueSchemaPassword the password of the AQ schema.
queueName the name of the Oracle AQ.
agentName the name of the channel (that is, the JMS

agent).
Related Topics
12-240
Writing Your Own Basic Sending Adapter Client
Code
Instead of using the Basic Sending Adapter client code generated by the Activity Modeler, you
can write your own client code and properties file. For example, you would write your own code
if you did not want to use the activity modeler or its code generating capabilities but still wanted
to use the adapters.
Create the Basic Sending Adapter Properties File
Create an XML properties file for the Basic Sending Adapter and store it in the same package
as the class that will use the adapter. The file must define these properties:
● jdbcDriver
● jdbcURL
● queueSchemaName
● queueSchemaPassword
● queueName
For a description of how the file should be named, where it should be stored, and a description
of the above properties, see Defining Basic Sending Adapter Properties. This section also
includes an XML properties file that you can use as a guide. The order in which you list the
properties in the file is not important.
Create the Basic Sending Adapter Client Code
The client code for the Basic Sending Adapter must include the same features that are included
in the generated adapter.
1. Create a Java class file.

2. Write the code for the Basic Sending Adapter client in the Java class file. The adapter
code must include the same features that are used for the generated client code. These
features are described in Generating the Basic Sending Adapter Client Code. This topic
also includes sample client code that you can use as a guide.
3. Add your own programming logic to the file.
4. Write your own code to call the adapter client code when you need to use the adapter.
12-241
Related Topics
12-242
Generating the Basic Receiving Adapter Client
Code
● Java client code to initialize and start the Basic Receiving Adapter
case, to generate client code for the Basic Receiving Adapter, choose:

Has Receiving Adapter selected
Direction Receiving
Type Basic
Target Class the name of a valid Java class
Stylesheet URL not applicable
Depth Count not applicable
code.
The following is a sample of the Java code generated for the Basic Receiving adapter.
BasicReceivingAdapterClientCode.java
public AdapterMessage receiveMessage()

{
AdapterMessage message = null;
12-243
try
{
BasicReceivingAdapter adapter = new BasicReceivingAdapter();
message = adapter.receiveMessage(this);
}
{
}
return message;
}
Description of the Basic Receiving Adapter Client Code
Before the adapter is started (using the receiveMessage() method) the generator can insert
page. By default, this checkbox is clear. This causes the adapter.setShowTrace method to
be omitted: no tracing or debugging comments will be written by default. The code sample
above was generated with the Trace checkbox clear.
If the checkbox is selected, then an adapter.setShowTrace(true)is generated in the code

and tracing comments are enabled. When tracing comments are enabled, the default output
stream is System.out. If you wish, you can change this in the generated file by calling the
setPrintStream() method with a java.io.PrintStream object. This allows the writing of
trace comments to a file, for example.
Call the Receive Message Method
adapter can be started using the receiveMessage() method. The method dequeues an
AdapterMessage object from the specified queue (or waits for one to arrive, if necessary), then
returns control to the client code. If any kind of exception arises during the receiving process,
an AdapterFailureException is thrown and control returns to the catch clause.
Each call to the adapter dequeues one AdapterMessage object. If there is an AdapterMessage
object on the queue when the receiving adapter is started, the object will be returned
immediately. If there is no object on the queue, then the receiving adapter will wait until one
12-244
arrives and then dequeue it. If the receiving adapter appears to hang, it is simply waiting for an
AdapterMessage object to arrive on the queue. When the method finishes, the JDBC
connection is closed. Currently, this means that if you want to dequeue more than one
AdapterMessage object with the Basic Receiving adapter, you can add your own code to the
generated file to iterate around the receiveMessage() method which opens and closes a
new JDBC connection each time.
The generator creates a catch block for exceptions and includes a printStackTrace()
method for debug tracing. If you wish, you could add a
afe.getOriginalException().printStackTrace() statement to get the original
exception.
Defining Basic Receiving Adapter Properties
If you direct the activity modeler to generate the Basic Receiving adapter code, it also
generates an XML properties file that contains all of the information necessary to allow the
adapter to communicate with an Oracle AQ queue. The name of the file follows the convention
Classname-receiver-apf.xml, where Classname is the name of the class which contains
the adapter.receiveMessage() call for the adapter. The adapter uses the properties file at
runtime and stores it in the same directory as the Classname.class adapter file. In the case of
the Basic Receiving Adapter, the XML properties file has the name
BasicReceivingAdapterClientCode-receiver-apf.xml.
The following is a sample properties file for a Basic Receiving Adapter.
BasicReceivingAdapterClientCode-receiver-apf.xml

<adapterProperties>
<agentName>AGENT1</agentName>
<jdbcURL>jdbc:oracle:thin:@ukp14096:1521:ukp14096</jdbcURL>
12-245
The following table describes the properties used in the Basic Receiving Adapter XML
properties file.
jdbcDriver the name of the JDBC driver class to use. This value is
derived from the database connection.
the JDBC URL to the schema containing the Oracle AQ on
jdbcURL which to enqueue the messages. This value is derived from
the database connection.
agentName the name of the channel (that is, the JMS agent).
Related Topics
12-246
Writing Your Own Basic Receiving Adapter Client
Code
Instead of using the Basic Receiving Adapter client code generated by the Activity Modeler, you
can write your own adapter and properties file. For example, you would write your own code if
you did not want to use the activity modeler or its code generating capabilities but still wanted
to use the adapters.
Create an Adapter Properties File
Create an XML properties file for the Basic Receiving Adapter and store it in the same package
as the class that will use the adapter. The file must define these properties:
● jdbcDriver
● jdbcURL
● queueSchemaName
● queueName
of the above properties, see Defining Basic Receiving Adapter Properties. This section also
includes an XML properties file that you can use as a guide. The order in which you list the
properties in the file is not important.
Create the Basic Receiving Adapter Client Code
The client code for the Basic Receiving Adapter must include the same features that are
included in the generated adapter.
1. Create a Java class file.

2. Write the code for the Basic Sending Adapter client in the Java class file. The adapter
code must include the same features that are used for the generated client code. These
features are described in Generating the Basic Receiving Adapter Client Code. This topic
also includes sample client code that you can use as a guide.
12-247
Related Topics:
12-248
Creating Business Components for Java Messaging
Adapters
The following topics describe how to create message adapters for Business Components for
Java:
● Generating the Business Components for Java Sending Adapter Client Code
● Writing Your Own Business Components for Java Sending Adapter Client Code
● Generating the Business Components for Java Receiving Adapter Client Code
● Writing Your Own Business Components for Java Receiving Adapter Client Code
● Subclassing the Business Components for Java Receiving Adapter
12-249
Generating the Business Components for Java
Sending Adapter Client Code
● Java client code to initialize and start the Business Components for Java Sending
Adapter
The code the activity modeler generates and the values in the properties file are based on your
choice of options in the Messaging Adapter page of the Swimlane Properties dialog. In this
case, to generate code for the Business Components for Java Sending Adapter, choose:

Has Sending Adapter selected
Type BC4J
Target Class the name of a valid BC4J application module
(optional) the absolute or relative URL of the
Stylesheet URL
stylesheet to use for XSL transformations
the depth of view links to be traversed when
Depth Count
getting data from a view object
code.
The following is a sample of the Java code generated for the Business Components for Java
Sending adapter client.
BC4JSendingAdapterClientCode.java
public void sendMessage(AdapterMessage[] messages)
12-250
{
try
{
BC4JSendingAdapter adapter = new BC4JSendingAdapter();
adapter.sendMessage(this, messages);
}
{
}
}
Description of the Business Components for Java Sending Adapter

Client Code
Before the adapter is started (using the sendMessage() method), the generator can insert
debug tracing method calls based on the value of the Trace checkbox in the Messaging
Adapter page. By default, this checkbox is clear. This causes the adapter.setShowTrace
method to be omitted: no tracing or debugging comments will be written by default. The code
sample above was generated with the Trace checkbox clear.
If the checkbox is selected, then adapter.setShowTrace(true)is generated in the code

setPrintStream() method with a java.io.PrintStream object to change the default.
This allows the writing of trace comments to a file, for example.
Call the Send Message Method
adapter can be started using the sendMessage() method. Each call to the adapter will
enqueue an AdapterMessage array on the specified queue. Control returns to the client code
when this is done. If any kind of exception arises during the sending process, an
AdapterFailureException will be thrown and control will return to the catch clause
12-251
getOriginalException().printStackTrace() statement to get the original exception.
Defining Business Components for Java Sending Adapter

Properties
If you direct the activity modeler to generate the Business Components for Java Sending
Adapter client code, it also generates an XML properties file that contains all of the information
necessary to allow the adapter to communicate with an Oracle AQ queue. The name of the file
follows the convention Classname-sender-apf.xml, where Classname is the name of the
class which contains the adapter.sendMessage() call for the adapter. The adapter uses the
properties file at runtime and stores it in the same directory as the Classname.class adapter
file. In the case of this Business Components for Java Sending Adapter example, the XML
properties file has the name BC4JSendingAdapterClientCode-sender-apf.xml.
The following is a sample properties file for a Business Components for Java Sending Adapter.
BC4JSendingAdapterClientCode-sender-apf.xml

<adapterProperties>
<depthCount>0</depthCount>
<jdbcURL>jdbc:oracle:thin:@address:1521:address</jdbcURL>
<stylesheetURL>http://localhost/stylesheet.xsl</stylesheetURL>
The following table describes the properties used in the Business Components for Java
Sending Adapter XML properties file.

the depthcount parameter value to pass to the writeXML()
depthcount method on oracle.jbo.ViewObject. This represents the depth of
view links to be traversed when getting data from a view object.
12-252
jdbcDriver the name of the JDBC driver class to use. This value is derived
from the database connection.
the JDBC URL to the schema containing the Oracle AQ on
jdbcURL which to enqueue the messages. This value is derived from the
stylesheetURL optional: absolute or relative URL of the stylesheet to use for

XSL transformations.
Related Topics
12-253
Writing Your Own Business Components for Java
Sending Adapter Client Code
Instead of using the Business Components for Java Sending Adapter generated by the Activity
Modeler, you can write your own adapter and properties file. For example, you would write your
own code if you did not want to use the activity modeler or its code generating capabilities but
still wanted to use the adapters.
Create the Business Components for Java Sending Adapter

Properties File
Create an XML properties file for the Business Components for Java Sending Adapter and
store it in the same package as the class that will use the adapter. The file defines these
properties:
● depthcount
● jdbcDriver
● jdbcURL
● queueSchemaName
● queueName
● stylesheetURL (optional)
of the above properties, see Defining Business Components for Java Sending Adapter
Properties. This section also includes an XML properties file that you can use as a guide. The
order in which you list the properties in the file is not important.
Create the Business Components for Java Sending Adapter Client

Code
The client code for the Business Components for Java Sending Adapter must include the same
features that are included in the generated adapter.
There is no requirement that the adapter client code should operate within its own method (like
12-254
the sendMessage() method in the generated code sample). However, it is strongly advised
that the code should reside within its own method, preferably with the same naming
conventions as used in the code sample. This is because the activity modeler generators will
generate code that is within its own method. Also, this makes the adapter code available as an
isolated unit for clients using the Business Components for Java components.
1. Create a Java application module file.

2. Write the code for the Business Components for Java client in the file. The code must
include the same features that are used for the generated client code. These features
are described in Generating the Business Components for Java Sending Adapter Client
Code. This topic also includes sample client code that you can use as a guide.
Related Topics
12-255
Generating the Business Components for Java
Receiving Adapter Client Code
● Java code to initialize and start the Business Components for Java Receiving adapter
If you do not want to use the client code generated for you by the activity modeler, you can
write your own client code and properties file.
case, to generate client code for the Business Components for Java Receiving adapter,
choose:

Has Messaging Adapter selected
Direction Receiving
Type BC4J
Target Class the name of a valid BC4J application module
(optional) the absolute or relative URL of the
Stylesheet URL
stylesheet to use for XSL transformations
the depth of view links to traverse when storing XML
Depth Count
data in a view object
Service Lifetime Single or Many
select and provide the fully qualified path to the
subclassed Business Components for Java Receiving
Use Subclass Adapter file only if you are generating client code for a
subclassed version of the Business Components for
Java Receiving Adapter
code.
The following is a sample of the Java code generated for the Business Components for Java
Receiving adapter client.
12-256
BC4JReceivingAdapterClientCode.java
public void receiveMessage()

{
try
{
BC4JReceivingAdapter adapter = new BC4JReceivingAdapter();
adapter.receiveMessage(this);
}
{
}
}
Description of the Business Components for Java Receiving

Adapter Client Code
The following sections describe the features of the generated code.
Before the adapter is started (using the receiveMessage() method) the generator can insert
page. By default, this checkbox is clear. This causes the adapter.setShowTrace method to
be omitted: no tracing or debugging comments will be written by default. The code sample
above was generated with the Trace checkbox clear.
If the checkbox is selected, then an adapter.setShowTrace(true)is generated in the code

setPrintStream() method with a java.io.PrintStream object. This allows the writing
of trace comments to a file, for example.
Call the Receive Message Method
Once the initialization properties have been set, the adapter is started using the
receiveMessage() method. Each call to the adapter will cause the adapter to wait until a
message arrives on the specified queue. When a message arrives, it is dequeued and
incorporated into the relevant view object. If the serviceMultipleMessages parameter is
12-257
set to true (Service lifetime=Many in the Messaging Adapter page ), then the adapter will loop
and infinitely service messages as they arrive. If serviceMultipleMessages is set to
false (Service lifetime=Single), the adapter will service a single message, then control will
return to the calling method. If any kind of exception arises during the receiving process, an
AdapterFailureException will be thrown and control will return to the catch clause.
getOriginalException().printStackTrace() statement to get the original exception
Defining Business Components for Java Receiving Adapter

Properties
If you direct the activity modeler to generate the Business Components for Java Receiving
adapter code, it also generates an XML properties file that contains all of the information
necessary to allow the adapter to communicate with an Oracle AQ queue. The name of the file
follows the convention Classname-receiver-apf.xml, where Classname is the name of the
class which contains the adapter.receiveMessage() call for the adapter. The adapter
uses the properties file at runtime and stores it in the same directory as the Classname.class
adapter file. In the case of this Business Components for Java Receiving adapter example, the
XML properties file has the name BC4JReceivingAdapterClientCode-receiver-
apf.xml.
The following is a sample properties file for a Business Components for Java Receiving
adapter.
BC4JReceivingAdapterClientCode-reciever-apf.xml
?xml version = '1.0' encoding = 'UTF-8'?>

<adapterProperties>
<agentName>AGENT1</agentName>
<depthCount>0</depthCount>
<jdbcURL>jdbc:oracle:thin:address:1521:address</jdbcURL>
<stylesheetURL>http://localhost/stylesheet.xsl</stylesheetURL>
12-258
<serviceMultipleMessages>false</serviceMultipleMessages>
The following table describes the properties used in the Business Components for Java
Receiving Adapter XML properties file.

the depthcount parameter value to pass to the readXML() method on
depthcount oracle.jbo.ViewObject. This is the depth of view links to traverse when
storing XML data in the view object.
the name of the JDBC driver class to use. This value is derived from
jdbcDriver
the database connection.
the JDBC URL to the schema containing the Oracle AQ on which to
jdbcURL enqueue the messages. This value is derived from the database
connection.
a Boolean that determines whether the adapter services a single
serviceMultipleMessages
message or loops indefinitely: true=indefinite, false=single.
stylesheetURL optional: the URL of the stylesheet to use for XSL transformations.
Related Topics
12-259
Writing Your Own Business Components for Java
Receiving Adapter Client Code
Instead of using the Business Components for Java Receiving Adapter client code generated
by the activity modeler, you can write your own adapter and properties file. For example, you
would write your own code if you did not want to use the activity modeler or its code generating
capabilities but still wanted to use the adapters.
Create Business Components for Java Receiving Adapter

Properties File
Create an XML properties file for the Business Components for Java Receiving Adapter and
store it in the same package as the class that will use the adapter. The file defines these
properties:
● depthcount
● jdbcDriver
● jdbcURL
● queueSchemaName
● queueName
● stylesheetURL (optional)
● serviceMultipleMessages
of the above properties, see Defining Business Components for Java Receiving Adapter
Properties. This section also includes an XML properties file that you can use as a guide. The
order in which you list the properties in the file is not important.
Create the Business Components for Java Receiving Adapter Client

Code
The client code for the Business Components for Java Receiving adapter must include the
same features that are included in the generated adapter.
12-260
There is no requirement that the adapter code should operate within its own method (like the
receiveMessage() method in the generated code sample). However, it is strongly advised
that the code should reside within its own method, preferably with the same naming
conventions as used in the code sample. This is because the activity modeler generators will
generate code that is within its own method. Also, this makes the adapter code available as an
isolated unit for clients using Business Components for Java components.
1. Create a Java application module file.

2. Write the code for the Business Components for Java client in the file. The code must
include the same features that are used for the generated client code. These features
are described in Generating the Business Components for Java Receiving Adapter Client
Code. This topic also includes sample client code that you can use as a guide.
Related Topics
12-261
Subclassing the Business Components for Java
Receiving Adapter
You can subclass the Business Components of Java Receiving Adapter to implement your own
programming logic. You can override methods in this class to add your own code for:
● message transformation
● parser error handling
● transaction handling
To direct the activity modeler to generate client code for the subclassed adapter use the Adapters
page of the Swimlane Properties dialog. In this page select the Use Subclass checkbox and enter
the fully qualified class name of the subclassed file.
Writing the Subclass Code
To subclass the reveiving adapter, you must extend the BC4JReceivingAdapter class,
oracle.bm.ebiadapters.BC4JReceivingAdapter, and override methods to provide your own
functionallity. For example:
class MyAdapterSubclass extends oracle.bm.ebiadapters.BC4JReceivingAdapter

{
...
}
Overriding Message Transformation
The custom message transformation method:
public String doCustomTransformation(String message)

{
//
// Place your message transformation code here
//
return newMessage;
}
is called after dequeuing the message from the Oracle AQ. Override this method to implement your
own message transformation code. This method is applied before parsing so the message itself does
12-262
not have to be in XML. The method returns a String newMessage. You must ensure that the
returned string must be valid XML otherwise parsing will fail.
Custom message transformation represents whatever code that is needed so that your particular
Business Components for Java application can use the dequeued data. For example, it can:
● contain specific code to transform data sent in a proprietary format into XML
● perform validation on the data
● change the format of the data so that it can be accepted by the receiving application. For
example, assume that your applications deal with financial transactions. The application in the
sending system works with financial data in dollars and dates in MM-DD-YYYY format; the
Business Components for Java application in the receiving system works with financial data in
Euros and dates in DD-MM-YYYY format. In this case, your systems integration plan would
have to include implementing custom message transformation in the receiving adapter to
translate the message from its format in the sending system into a format that could be used
by the receiving system. The custom transformation would typically operate on the message
after it is dequeued from Oracle AQ and translated into XML.
● perform message auditing or logging
This method does not have any default message transformation code of its own. Applying this
method without adding any of your own code has no effect on the message.
Overriding Parser Error Handling
The parser error handling method:
public void doParseErrorHandling(Exception e, String Message)

{
//
// Place your message transformation code here.
//
}
is called if an error (XMLParseException, SAXException or IOException) occurs while parsing

the dequeued message payload. Note that in a receiving adapter which is servicing multiple
messages, a parsing error will not cause the entire adapter to fail. This method can be used for
cleanup. Override this method to implement your own parser error handling logic. After handling the
error, control returns to the message servicing loop.
This method does not have any default parser error handling code of its own. Applying this method
without adding any of your own code has no effect.
12-263
Overriding Transaction Handling
The transaction handling method:
public void handleTransaction(ApplicationModule appmod, int numOfMessageReceived)
{
//
// Place your transaction handling code here
//
is called to commit the application module and close the transaction. By default, this method commits
the transaction on the application module after each message is received. Override this method if
you require different or more complex behavior. For example, to increase throughput, you could use
the numOfMessagesReceived parameter to commit the application module after 10 messages are
received.
Note: It is strongly recommended that you commit after receiving every message; otherwise, you might
lose data.
Related Topics
12-264
Using the AdapterMessage Class for Message
Payloads
The AdapterMessage class (oracle.bm.ebiadapters.AdapterMessage) is a wrapper that is
required for message payloads that are sent and received using the e-business integration
Messaging Adapters. The AdapterMessage class can wrapper payloads of two different types:
● java.lang.String when the payloads are used by the Basic adapters

● oracle.jbo.server.ViewObject when the payloads are used by the Business Components
for Java adapters
Using the AdapterMessage Objects with the Basic Adapters
You create a new instance of an AdapterMessage containing a String payload by using the call:
AdapterMessage message = AdapterMessage.newStringMessage(payload)
where payload is of type java.lang.String.
For the Basic Sending Adapter, the sendMessage method in the generated client code takes
an array of AdapterMessage objects, where each object contains a java.lang.String payload.
You must provide the code that wrappers the application data as AdapterMessage objects and
forms them into an array before passing them to the adapters.
The Basic Receiving Adapter receives a single AdapterMessage at a time and returns it from
the generated client code. Similarly, you must provide the code that unwraps the data that it
returns. For example, you can retrieve the payload from the AdapterMessage object using the
getPayload() method and then cast the payload back to its original type.
Using AdapterMessage Objects with the Business Components for

Java Adapters
You create a new instance of an AdapterMessage containing a ViewObject payload by using

the following call:
AdapterMessage message = AdapterMessage.newViewObjectMessage(payload)
12-265
where payload is of type oracle.jbo.server.ViewObject.
For the Business Components for Java Sending Adapter, the sendMessage method in the
generated client code takes an array of AdapterMessage objects, where each object contains
an oracle.jbo.server.ViewObject payload. You must provide the code that wrappers the
application data as AdapterMessage objects and forms them into an array before passing them
to the adapters.
Using the BESAdapterMessage Subclass
The BESAdapterMessage class (oracle.bm.ebiadapters.BESAdapterMessage) is a subclass of

AdapterMessage. It provides additional functionality which is needed by the e-business
integration generators to achieve full integration. In addition to setting the payload, the
BESAdapterMessage class allows you to set metadata properties which are mapped to JMS
header fields. Some of these properties are mandatory and some are optional. For example,
the setEventName(String eventName) and setEventKey(String eventKey) methods can be
used to set the mandatory Event Name and Event Key properties. Once set, these properties
are mapped to JMS header properties to allow the JMS messages to be correctly propagated
between Oracle AQ queues.
Writing Your Own AdapterMessage Subclass
The AdapterMessage class lets you send message payloads between adapters. If you need to
send metadata in addition to the data in the payload, or if you need to specify custom methods
of mapping properties into and out of the JMS header of the message, you can write your own
subclass of AdapterMessage.
Using the AdpaterMessage Property Map
Subclasses of AdapterMessage can use the property map in the AdapterMessage base class
to store and retrieve properties. The class contains methods that let you manipulate the
contents of the property map and provide a custom mapping of properties into and out of the
JMS header.
Some of the key methods that you can use to manipulate the contents of the map are:
● public Object addProperty(String key, Object value)—adds a key/value

pair to the property map
● public Object getProperty(String key)—searches for a property by its key
and returns its associated value
12-266
● public boolean hasProperties()—determines whether the properties map within
an AdapterMessage stores any custom properties
If you want to subclass the AdapterMessage object to provide a custom method of mapping
properties to the JMS header, override the encodeProperties and decodeProperties methods.
These methods describe how to put the custom properties in (or take them out of) the JMS
header.
● protected TextMessage encodeProperties(TextMessage message)— this

method on AdapterMessage (or a subclass which overrides it) is called whenever a
sending adapter is about to send a message. If you write your own AdapterMessage
subclass, the javax.jms.TextMessage parameter allows you to take properties
stored in the custom properties map and store them in the JMS header however you
want. You can do this by directly calling methods on TextMessage such as
setJMSType(String type) and setStringProperty(String key, String
value).
● protected TextMessage decodeProperties(TextMessage message)— this
method is called whenever the receiving adapters receive a message. In a similar way,
you can override this method to get properties from the JMS header and place them in
the AdapterMessage base class custom properties map.
Related topic
12-267
JDeveloper helps you automatically deploy the files generated by the e-business integration
code generators such that all of the systems defined by your diagram can participate in
messaging.
The hierarchy in which the files are generated allow you different deployment options. You can
deploy:
● all of the generated files for all of the systems in the project
● all of the files for a single system that were generated by all of the diagrams in which it is
used
● all of the files for a single system that were generated by a single diagram
In each case, when you deploy, the results of each individual deployment step will be listed in
the log window. If a deployed system has multiple instances, the names of all of its instances
will be listed, and the log window will report on the deployment of the files to each of the
instances.
This topic assumes:
● You have successfully modeled and generated the integration points defined in your
diagrams.
● The source and target systems exist, and have all of the required software installed on
them (Oracle8i database, Workflow server, and so on).
● You have linked all of the systems and system instances on the diagram with database
connections.
Notes:
● To automatically deploy the Workflow WFT files that are generated from the Activity
Modeler's E-Business Integration Generator, the Workflow Loader utility must be
available on the system that JDeveloper is running on. The Workflow Loader is only
supplied as part of the Oracle Workflow Server installation, and so at least part of this
installation must be present on the same system as JDeveloper. If the Workflow loader is
not available locally the WFT files must be moved to the Workflow server system and
loaded there manually.
● In this release, basic messaging adapters can only be deployed as part of a Simple
12-268
Archive deployment. This restriction does not affect BC4J messaging adapters.
To deploy all generated files for all of the systems in the project:
1. Locate the Generated EBI Files folder for the project you want to deploy. You can
find this folder in the JDeveloper Navigator pane.
2. Right-click the Generated EBI Files folder and choose Deploy from the menu.
If the deployment of an individual systems fails, you can select it in JDeveloper's Navigator
pane and redeploy it separately after correcting any errors.
To deploy files for a single system that were generated by all of the diagrams in which it is used:
1. Locate the folder corresponding to the swimlane whose system definitions you want to
deploy. You can find this folder in the JDeveloper Navigator pane.
2. Right-click the swimlane folder and choose Deploy from the menu.
If the deployment of the files generated for an individual diagram fails, you can select it in
JDeveloper's Navigator pane and redeploy it separately after correcting any errors.
To deploy all of the files for a single system that were generated by a single diagram:
1. Locate the swimlane folder that contains the diagram folder that contains the system
definitions you want to deploy. You can find this folder in the JDeveloper Navigator pane.
2. Right-click the diagram folder and choose Deploy from the menu.
Related Topics
About Deployment
About Deployment Profiles
Testing Deployment Success
12-269
12-270
About Deployment
When the modeler generates the integration files, it stores them in the file system and displays
them in the JDeveloper Navigator pane. The folders are organized as follows:
Generated EBI Files folder

Swimlane S1 folder
Diagram D1 folder
File1.xml
File2.xml
...
Diagram D2 folder
File3.xml
File4.xml
...
Swimlane S2 folder
Diagram D1 folder
...
The top-level folder, Generated EBI Files, contains all of the generated files for the project
organized by swimlane. Each swimlane folder contains all of the files generated for that
swimlane by all of the diagrams in which it is used. Each diagram folder contains the XML files
that it generated for the swimlane under which it appears.
AQ definitions, Oracle Workflow, BES definitions, instance information files are deployed onto
the server that acts as the hub. The hub becomes responsible for controlling the message flow
between systems. AQ definitions and instance information files are deployed to the servers that
act as the spokes. The server information is obtained from the connection information that was
entered for each swimlane definition.
An XML deployment profile is associated with each folder in the hierarchy. By selecting and
deploying a folder, you are really executing the underlying deployment profile.
You can choose to deploy at any of the levels represented by a folder. This gives you added
flexibility in your deployment strategies. The following table describes which files are deployed
when you select a particular folder.
Table 1: System Files Which are Deployed, by Selecting a Particular Folder
12-271
Select this folder... to deploy these files
the Generated EBI Files all of the generated files for all of the systems in the project will be
folder deployed simultaneously
all of the files for a single system that were generated by all of the
a swimlane folder
diagrams in which it is used
a diagram folder all of the files for a single system that were generated by a single diagram
Recovery from Deployment Errors
This hierarchical approach to deployment gives you the added flexibility of being able to easily
recover from deployment errors. For example, assume that you selected a swimlane folder to
deploy all of the files for the system in all of the generated diagrams in which it was used.
Assume also that during the deployment, the deploying of the files associated with one of the
generated diagrams fails. This will not end the deployment process; instead, it will continue
deploying the files from the other generated diagrams.
When deployment is finished, you can examine the diagram that failed, make any corrections
that are needed, and regenerate files for the diagram. You can then redeploy the files for only
that diagram.
Related Topics
Deploying E-Business Integration Generated Files
12-272
The activity modeler uses XML deployment profiles to store information about deployment,
such as the names of the files that must be deployed, the messaging protocol to be used, and
the type and location of the remote systems. Each deployment profile is associated with a
folder in the hierarchy of files that the activity modeler generates.
The top level folder, Generated EBI Files, contains folders for each swimlane defined in the
project. Each swimlane folder contains a folder for each diagram in which the swimlane is used.
These diagram folders contain the system definitions for the swimlane, for that particular
diagram. Figure 1 illustrates these folders in the hierarchy of generated files in JDeveloper's
Navigator pane.
By creating deployment profiles on each folder on each of these levels, e-business integration
gives you a high degree of flexibility in your deployment strategy. You deploy files by right-
clicking a folder and choosing Deploy from the menu. This executes the associated deployment
profile which instructs the activity modeler which files to deploy to the remote systems. The files
which are deployed depend on the folder that you select.
Deployment Profile for the Top-level Folder
The Generated EBI Files folder is associated with the EBIGenerated_ProjectX.xml profile.
This profile contains a list of all of the swimlanes for which system definitions have been
generated. If you choose to deploy the Generated EBI Files folder, then the activity modeler will
deploy all of the system definitions generated from all of the diagrams in the project.
Deployment Profiles for the Swimlane-level Folders
Each swimlane level folder is associated with a swimlane_name.xml profile. Each

swimlane_name.xml profile contains a list of all of the diagrams from which system definitions
have been generated for the swimlane. If you choose to deploy a swimlane level folder, then
the activity modeler will deploy all of the system definition files for the swimlane that have been
generated from all of the diagrams in which it is used.
Deployment Profiles for the Diagram-level Folders
Each diagram level folder is associated with a diagram_name.xml profile. Each

diagram_name.xml profile lists the system definition files that have been generated for the
swimlane under which the diagram folder appears. If you choose to deploy a Diagram level
folder, then the activity modeler will deploy all of the system definition files that were generated
12-273
for the swimlane in the specified diagram.
Related Topics
About Deployment
12-274
The most simple deployment you could perform would be deploying the files of a receiving-only
system to a remote database. To do this you need access to a database where 8.1.6 or higher
has been installed. Select the system name in the Navigator pane and choose Deploy from the
right mouse menu.
The Deployment Progress dialog displays the results of the deployment:
● A blue check mark is displayed against a deployment profile if it has been

successfully deployed.
● A red cross is displayed against a deployment profile if it has not been successfully
deployed, for example, if the database version is too old.
More detailed messages about the deployemnt are displayed in the Log window.
Note: To demonstrate sending and receiving, you need at a minimum of two databases with 8.1.6 or
later installed. One of the databases will act as the hub and must have Oracle Workflow installed.
There would also have to be an application on the sending system that would enqueue messages to
the BES and an application on the receiving system that would dequeue messages from the BES.
Related Topics
About Deployment
12-275
Developing Enterprise JavaBeans
● Developing Enterprise JavaBeans
● Types of Enterprise JavaBeans

● About EJB Files Generated by JDeveloper
● Working with EJB Projects
❍ Importing Existing EJBs to a Project
❍ Migrating EJBs from 3.2.3 to 9i
● Modifying EJBs with the EJB Class Editor

❍ Adding, Deleting, and Editing EJB Methods
❍ Using EJB Finders with CMP Entity Beans

❍ Adding Container Managed Persistence to a Field
● Running and Testing an EJB

● EJB Walkthroughs
❍ Developing a Stateless Session Bean
❍ Developing an Entity CMP EJB From a Table
13-1
JDeveloper provides powerful tools for creating, modifying, and deploying J2EE-compliant
Enterprise JavaBeans (EJBs).
To develop EJBs in JDeveloper:
1. Create an EJB using one of the EJB wizards

2. Edit the EJB with the EJB Class Editor
3. Add business logic with the Code Editor
4. Test the EJB using the embedded OC4J Server
5. Deploy the EJB
6. Test the EJB remotely
These steps are examined in closer detail below. For a complete walkthrough of developing an
EJB, see the topic EJB Walkthroughs.
Creating EJBs with the EJB Wizards
For creating EJBs, JDeveloper provides the Enterprise JavaBean Wizard and the Create CMP
Entity Beans from Tables Wizard. The Enterprise JavaBean wizard can be used to create any
type of EJB, while the Create CMP Entity Beans from Tables Wizard is used specifically for
reverse-engineering CMP entity EJBs from database tables.
● To access either wizard, select File | New... and from the Enterprise JavaBean category
and choose the desired wizard.
Editing the EJB with the EJB Class Editor
To modify an EJB's classes, JDeveloper provides the EJB Class Editor. The EJB Class Editor
is a GUI interface used for modifying Java (and sometimes XML) code in your EJB. By
modifying the EJB through this editor, changes within the EJB's classes are synchronized.
● To open the EJB Class Editor, right click an EJB in the System Navigator and choose
EJB Class Editor.
13-2
For more information on using the EJB Class Editor, see the topic, Modifying EJB Properties.
Also, you can get context-sensitive help by pressing the F1 key or clicking the Help button
when using the EJB Class Editor.
Adding Business Logic with the Code Editor
After you have added methods using the EJB Class Editor, you can implement their behavior in
the Code Editor.
● To open the Code Editor, right click on an EJB file in the System Navigator and choose
Code Editor.
Testing the EJB Using the Embedded OC4J Server
To test your EJBs you need to run a client program that can call methods on the EJB.
JDeveloper provides a sample client utility that will help you create clients quickly. You can then
run and test EJBs using the embedded OC4J Server, which simplifies the process. The
embedded OC4J server runs within JDeveloper. You do not need to create a deployment
profile to use this server, nor do you have to initialize it. After you test your EJBs locally, you
can deploy them remotely with no further changes.
● To create a sample client to run agains this server, right click an EJB in the System
Navigator and choose Create Sample Java Client, choosing the embedded OC4J server
option.
● To start the embedded OC4J server, right click an EJB in the System Navigator and
choose Run.
Deploying the EJB
Oracle9iAS provides OC4J as a container for EJBs. An OC4J-specific deployment profile is

generated by default. You can also create a WebLogic-specific deployment profile. Information
on EJB deployment can be found in the following topics:
● Creating and Deploying a J2EE EJB Module (EJB JAR) to OC4J

● Creating and Deploying an EJB JAR to WebLogic
13-3
Testing the EJB Remotely
JDeveloper can also create a sample client for use with a remote server. You generate the
sample client in the same manner as a local client, providing the remote connection details.
For more information, see the topic Running and Testing an EJB.
Related topics
About EJB Files Generated by JDeveloper

EJB Walkthroughs
13-4
Types of Enterprise JavaBeans
Enterprise JavaBeans can be entity beans or session beans. An entity bean usually represents
a database connection. Entity beans can manage their own persistence (bean-managed
persistence, or BMP) or have its container manage it (container-managed persistence, or
CMP). Session beans, on the other hand, are usually non-persistent and are destroyed by the
container when it is no longer needed.
Entity Beans
An entity bean represents persistent data in a database, as well as methods that act on that
data. In a relational database context, one bean exists for each row in a table. A unique primary
key identifies each entity bean to a record. When you create an entity bean with the EJB
Wizard, it creates an entity bean by using a create() method, as well as its primary key.
An entity bean can manage its own persistence or have its container manage it. In general, the
life cycle of an entity bean is not limited by the life cycle of the virtual machine in which it
executes. If the virtual machine crashes, or the database rolls back the current transaction, the
entity bean and its references from other clients are not destroyed. Later, a client can reconnect
to the same entity bean using its object reference and primary key or when its container reloads
its state.
CMP Beans
A container-managed persistence (CMP) entity bean delegates its persistence tasks to its
container, which frees you to develop the business logic for your EJB. When you deploy your
entity bean with JDeveloper, JDeveloper identifies the CMP fields in the deployment descriptor
and how they are mapped to the database. The container generates the necessary logic to
persist the entity bean.
Fields that are mapped to the database are called container-managed fields. These fields can
be any Java primitive type or serializable object which you can create and manage through the
EJB Designer.
You can create CMP beans from scratch using the Enterprise JavaBean Wizard. You can also
reverse-engineer CMP beans from a database table. To do this, you run the Create CMP Entity
Beans From Table Wizard. This wizard will create a CMP EJB for each table you specify in the
database.
BMP Beans
13-5
A bean-managed persistence (BMP) bean requires that you explicitly write the persistence logic
for it. In addition to knowing database technology, you'll need to explicitly map the bean's fields
into the database.
Session Beans
A session bean is created by a client and exists only for the duration of a single session. A
session bean performs operations on behalf of the client such as reading, writing, or updating a
database; however, session beans do not represent data to be stored in a database. Session
beans can also be transactional; however, since they are not persistent, they cannot be
recovered after a system crash.
Session beans can be stateless or can maintain conversational state across methods and
transactions. The state describes the conversation between a session bean and its client. The
EJB container manages this conversational state of a session bean and destroys the session
bean when it is no longer needed.
Unlike entity beans, session beans are used as private resources only by the client that created
the session bean. A session bean hides its identity and is anonymous, unlike an Entity Bean
that exposes its identity using its primary key.
Stateful Session Beans
A stateful session bean extends its client application and performs tasks on its behalf and
maintains a state related to its client. This state maintains a conversation between the client
and the stateful session bean. Methods within a stateful session bean can read and write data
to and from this conversational state, which can be shared among other methods within that
bean. A stateful session bean services only one client at a time.
Unlike entity beans, stateful session beans do not represent data to be stored in a database,
and do not survive database or system crashes.
Stateless Session Beans
This type of session EJB has no internal state, which means it doesn't need to be passivated
and can service multiple clients efficiently. Unlike a stateful session bean, a stateless session
bean is not dedicated to one client, allowing other EJB objects to use multiple instances of one
stateless session bean.
Related topics
13-6
13-7
About EJB Files Generated by JDeveloper
The EJB wizards generate the EJB framework for you, which complies with the EJB
architecture specification.
Note: The EJB architecture specification describes the design goals, the roles in
the application development and deployment lifecycle, and the contracts that
ensure the compatibility of the various roles. It also contains useful background
information about many of the terms and concepts referenced in the JDeveloper
documentation. The specification is available from Sun Microsystems at
http://java.sun.com/products/ejb/docs.html.
The EJB wizards are used to:
● Create the Enterprise Bean class for several types of Enterprise JavaBeans: Container
Managed Persistence (CMP) entity beans, Bean Managed Persistence (BMP) entity
beans, stateless session beans, and stateful session beans.
● Generate the home interface needed to create an EJB object. The inclusion of the
ejbCreate() method allows you to deploy the EJB to Oracle9iAS immediately, without
having to manually code the method.
● Enable a selection of home interface methods (and create a default method).
● Generate the remote interface.
● Enable a selection of remote interface methods.
When using the EJB wizards, you cannot create new methods to include in the home and
remote interfaces. The EJB Wizard defines one create() method by default for the home
interface. To add or remove other methods in the EJB class, you can run the EJB Class Editor
to select the methods to expose in the Bean interfaces.
Note: You must use the Code Editor to create other eligible methods for the home
interface and the methods for the remote interface that you require for your
deployment. Once you have developed the eligible methods, you can run the EJB
Class Editor again and select the methods to include in the home and remote
interfaces.
The EJB Wizard will create a basic class that contains only the methods required to implement
the bean interface. The remote and home interfaces are derived from this class.
When you create an EJB using the EJB Wizard, JDeveloper generates the following classes for
13-8
you:
● EJB classes
❍ Enterprise Bean class
❍ Home interface
❍ Remote interface
❍ Optionally, a class for entity Beans
● ejb-jar.xml Deployment Descriptor

❍ orion-ejb-jar.xml file
❍ weblogic-ejb-jar.xml file (this file is not generated by default)
About the Enterprise Bean Class and Interface Classes
When you create an EJB with the wizard, JDeveloper creates an EJB folder which contains the
Enterprise Bean class, home interface, and remote interface for the EJB. This folder appears
as a subfolder in the System Navigator with the same name you provided as the EJB remote
interface in the EJB Wizard.
About the ejb-jar.xml Files
The ejb-jar.xml file specifies attributes of the bean including transactional properties, and
provides instructions for the EJB container about how the bean expects to interact with the
container. The ejb-jar.xml file is generic - it doesn't contain any application server-specific
properties.
JDeveloper can generate ejb-jar.xml files specific to an application server. The orion-ejb-jar.xml
file is generated by default, and is used for deployment to OC4J. To generate a container-
specific file for WebLogic, select WebLogic Deployment Descriptor from the Enterprise
JavaBeans category in the New dialog box.
Related topics

Understanding Enterprise JavaBeans
Creating Enterprise JavaBeans
13-9
13-10
Working with EJB Projects
An EJB project can contain at most one EJB module. An EJB module is one or more EJBs that
share a single deployment descriptor. The first time an EJB project is created using the wizard,
an ejb-jar.xml file is created. A single EJB module can contain multiple EJBs, which you can
add using the EJB wizards. Multiple JDeveloper projects are required if you need more than a
single EJB module.
There are a number of project-level tasks you can do in JDeveloper, including:
● Adding EJBs to a Project

● Deleting EJBs from a Project
● Opening an Existing EJB Module
● Renaming EJBs in a Project
● Importing Existing EJBs to a Project
● Migrating EJB Projects from 3.2.3 to 9i
Adding EJBs to a Project
You can add new EJBs to a project by right-clicking on the EJB Module in the System
Navigator and choosing New Enterprise JavaBean from the context menu. The EJB Wizard will
lead you through the rest of the process.
To add existing EJBs to a project, see Importing Existing EJBs to a Project.
Deleting EJBs from a Project
To delete an EJB from a JDeveloper Project (EJB Module), select the EJB in the System
Navigator and choose File | Remove From IDE.
Importing/Opening an Existing EJB Module
Each JDeveloper project can contain at most one EJB module (ejb-jar.xml file). To open an
existing EJB module in JDeveloper, see the topic Importing Existing EJBs to a Project.
Renaming EJBs in a Project

13-11
To rename an EJB, right-click the EJB node in the System Navigator and choose Rename.
13-12
Importing Existing EJBs to a Project
You can add pre-built EJBs to a JDeveloper project by opening them in the IDE.
To add an existing EJB module to a JDeveloper project:
1. From the File menu, choose Open.

2. Navigate to the location of your EJB module (ejb-jar.xml file) and select it. Click OK.
3. Note that If the EJB has source path entries, you may need to add the source path files
to the project as well. Note that if the EJB has source files, you may need to add the
source path directly to the project's source path as well.
13-13
Migrating EJBs from 3.2.3 to 9i
If you have existing EJB projects developed in JDeveloper 3.2.3, they can be easily migrated to
JDeveloper9i.
To open an EJB project created in JDeveloper 3.2.3:
1. From the File menu, choose Open.

2. Navigate to the location of your .jpr file and select it. Click OK.
The .jpr file is opened in the System Navigator.
Additional Migration Issues
● When you migrate an EJB from 3.2.3 to 9i, the .ejx file is interpreted as an EJB module,
but the name remains the same (.ejx) in the System Navigator. Any operations you
would perform on an EJB module can be performed on the .ejx file.
● In 3.2.3 you were allowed to create more then one deployment descriptor per project.
The EJB spec now calls for a single deployment descriptor; if you had more than one
deployment descriptor, they are merged into a single deployment descriptor with the
name ejb-jar.xml. The single deployment descriptor is added to the project, while the
other descriptors are not. Note that if there are duplicate entries in the deployment
descriptors, these should be filtered out by using the deployment descriptors Settings
dialog box or by editing the ejb-jar.xml file.
● In 3.2.3, the security role is set to public by default. After migrating to 9i, you need to
change this security role to the proper one, or remove the security roles and method
permissions. Otherwise you will get an error.
● When migrating CMP entity beans from 9i Beta to 9i, you must run the OC4J EJB
Descriptor Wizard and assign a datasource to each CMP bean. The wizard is accessed
from the Enterprise JavaBeans category in the New dialog box (select File | New).
13-14
Modifying EJBs with the EJB Class Editor
To access the EJB Class Editor, select an EJB node in the System Navigator and then right-
click and choose EJB Class Editor. For additional help on any of these operations, click Help
or press the F1 key on your keyboard.
Related topics
13-15
Adding, Deleting, and Editing EJB Methods
Once an EJB has been added to your project, you can add, delete, or edit the methods in it. To
add methods, you use the Methods page of the EJB class editor. This ensures that changes
are synchronized with the remote and home interfaces. For information on Finder methods on a
CMP entity Bean, see the topic, Using EJB Finders.
To add, delete, or edit methods:
1. In the System Navigator, right-click an EJB node and choose EJB Class Editor.
2. Click the Methods tab.
3. To add a method to your EJB, click the Add button. The Method Settings dialog box
appears.
4. Add or edit the method properties as necessary. When you're finished, click OK.
5. To delete the method, click the X icon.
6. To re-edit the method's properties, click select the method in the list and click Edit.
For context-sensitve help, click the Help button on the EJB Class Editor or press the F1 key.
Related topics
Modifying EJBs with the EJB Class Editor

Using EJB Finders
13-16
Using EJB Finders with CMP Entity Beans
Finders are methods that are used to get information from a specific EJB instance. They are
similar to a stored query, like a SQL SELECT statement. Only entity beans can have finders.
Creating Finders
The EJB Class Editor for a CMP Entity Bean has a tab labeled Finders.
To open the Finders page:
1. In the System Navigator, right-click on a CMP entity EJB and choose EJB Class Editor.
2. At the bottom of the editor, click on the Finders tab.
Default-generated Finders
The following finder methods are generated by default by the wizards.
● findByPrimaryKey - This finder is required for all entity EJBs.

● findAll() - This finder returns a collection of all the EJBs.
Adding Finders
To add a new Finder method, click the Add button. The Create CMP Finder Method dialog box
opens, where you can edit the method, its parameters, and the exceptions it throws.
For more information on using this page, click Help or press the F1 key.
Adding Finders in the Methods Page
On the Methods page of the EJB Class Editor, you can also add finder methods. Since CMP
entity beans do not implement them, finders entered here entered here won't appear on the
methods page after you create it, but on the Finders page.
13-17
Adding Container Managed Persistence Fields to an
EJB
You can add container managed persistence (CMP) to a field through the EJB Class Editor.
To add a CMP field through the EJB Class Editor:
1. From the System Navigator window, double-click the CMP EJB file that you want to edit.
The EJB Class Editor appears.
2. Click the Fields tab at the bottom.
3. Click the Add button.
4. Select the Container Managed Persistence (CMP) field.
5. Click Next to edit the next field, or click Done to exit the Fields Settings editor.
The selected field is now CMP enabled.
13-18
Running and Testing Enterprise JavaBeans
To test your EJBs you might need to run a client program that can create or find EJB instances
and call their remote interface methods. JDeveloper provides a sample client utility that will help
you create clients quickly. You can run and test EJBs using either the embedded OC4J Server
or a remote server, and the sample client utility can be used to create a client for either type.
Testing EJBs Using the Embedded OC4J Server
The embedded OC4J server runs within JDeveloper. You can run and test EJBs quickly and
easily using this server, and then deploy your EJBs with no changes to them. You do not need
to create a deployment profile to use this server, nor do you have to initialize it.
To run a sample client on the embedded OC4J server:
1. In the System Navigator, right click on an EJB and choose Run.

Notice in the Message pane that OC4J has been launched.
2. Right click on an EJB and choose Create Sample Java Client from the context menu.
3. The default choice is to create a client for the embedded OC4J server, so you can click
OK.
The client is created and opens in the code editor.
4. If your client is for a CMP EJB, code is generated to invoke the findAll() method,
iterating through the retrieved instances and printing the property values to System.out.
Otherwise edit your sample client to call the desired home and remote methods.
5. In the System Navigator, right-click the sample client and choose Run.
The Message pane shows you the running output.
Testing EJBs Using a Remote Server
To test EJBs on a remote server you need to deploy the EJB and then create a sample client.
(If you deploy first, then the framework can pick up the deployed applications, which will
populate the client's pick list).
To run a sample client on a remote server:
1. Launch your application server.

2. In the System Navigator, right-click your project node and choose New.
13-19
3. In the New dialog box, click the Deployment Profiles category and choose J2EE EJB
Module.
The new deployment profile is displayed in the System Navigator.
4. Right click the deployment profile and choose Deploy to New Connection.
5. In the dialog box, specify the application server you want to use. (The OC4J server that
ships with JDeveloper is selected by default.) Click OK.
6. In the System Navigator, right click on the deployment profile and chose Deploy to
<named connection>.
7. In the System Navigator, right click on an EJB and choose Create Sample Java Client.
8. In the dialog box, choose to connect to a Remote App Server. The combo boxes should
list any deployed J2EE applications, choose one.
9. Click OK.
The client is created and displayed in the System Navigator.
10. Right-click the client and choose Run.
Related topics
13-20
EJB Walkthroughs
To illustrate the complete development process for creating, editing, and deploying Enterprise
JavaBeans, there are two topics that walk you through the complete process.
● Developing a stateless session bean - This topic walks you though the procedure of
developing and deploying a stateless session EJB using the Enterprise JavaBean
Wizard. You can also create other types of EJBs with this wizard, and while this
walkthrough won't address them specifically, the process is quite similar.
● Developing a CMP entity bean from a table - This topic walks you though the procedure
of developing and deploying CMP entity beans that are generated from database tables.
Requirements
● To deploy the EJB to the embedded OC4J server does not impose any additional
requirements. To deploy the EJB to a remote connection, you will need to create an
Oracle9iAS connection. For more information, see the topic Specifying Connection
Information to Oracle9iAS.
● To develop a CMP entity bean from a table you need a database connection to the
sample schema tables in Oracle9i.
13-21
Developing a Stateless Session Bean
This topic walks you though the procedure of developing and deploying a stateless session
EJB using the Enterprise JavaBean Wizard. You can also create other types of EJBs with this
wizard, and while this walkthrough won't address them specifically, the process is quite similar.
1. Requirements
2. Creating a New Workspace and Project
3. Creating and Editing an EJB
4. Running an EJB within the JDeveloper IDE
5. Deploying the EJB
6. Creating and Running a Sample Client
Requirements
● To deploy the EJB, you will need to create an Oracle9iAS connection. For more
information, see the topic Specifying Connection Information to Oracle9iAS.
1. From the File menu choose New...

2. In the New dialog box, click the Projects category and select Workspace.
3. Without changing the path, change both the workspace directory name and file name to
ejb. Click OK.
The New Project dialog box will appear.
4. Without changing the path, change both the directory name and file name to
stateless. Click OK.
The workspace and project are added to the System Navigator.
Creating and Editing an EJB

13-22
To create a new EJB:
1. In the System Navigator, right-click on the project node (stateless.jpr) and select New...
2. In the New Object dialog box, click on the Enterprise JavaBeans category and then
select Stateless Session Bean. Click OK.
The Enterprise JavaBean Wizard opens.
3. Review the information on the Welcome page of the wizard and click Next.
4. On the Name and Type page, accept the default name (MySessionEJB) and type
(SessionBean (Stateless)) and click Next.
5. You can use the default values for the rest of the wizard. Click Finish.
Your EJB is added to the System Navigator and the EJB Class Editor is launched.
6. From the File menu, choose Save All.
Adding a Method to the EJB
The EJB Class Editor provides a GUI interface for modifying your EJB. For this example, you
will add a new method, calc(), and a parameter, value.
To add a new method to the EJB:
1. In the EJB Class Editor, click the Methods tab.

2. Click the add (+) button to open the Method Settings dialog box.
3. Select the checkbox for EJB Interface Method.
4. In the Method name field type calc.
5. Click the Parameters tab at the top of the page.
6. Click the add (+) button to add a new parameter.
7. Click in the Name cell and enter value.
8. Click OK to close the Method Settings dialog box.
The new method is added to the EJB Class Editor.
9. In the System Navigator, expand the node for MySessionEJB and double-click
MySessionEJBBean.java to open it in the Code Editor.
10. Scroll through the code to find your new calc() method and replace return null; with
the following:
return value + value;
13-23
Testing an EJB Using Embedded OC4J
JDeveloper provides a sample client utility that will help you create clients quickly. You can run
and test EJBs using either the embedded OC4J Server or a remote server. The sample client
utility can be used to create a client for either type.
The embedded OC4J server is started automatically by JDeveloper. You can run and test EJBs
quickly and easily using this server, and then deploy your EJBs with no changes to them. You
do not need to create a deployment profile to use this server, nor do you have to initialize it.

OK.
The client is created and opens in the code editor.
4. In the code, uncomment the create() call.
5. Also uncomment the generated method call to calc(), replacing it with the following:
System.out.println(mySessionEJB.calc("a"));
In a typical development scenario, you would use the embedded OC4J server to test your
application as you developed it. Once completed, you would deploy it to a remote server. In this
next step, you'll deploy your EJB to a remote OC4J server.
Deploying the EJB to a Remote OC4J Server
To deploy the EJB you will perform the following three steps.
1. Create a new deployment profile

2. Start OC4J
3. Deploy the EJB (you may need to specify a new connection first)
13-24
Create a new deployment profile:
1. In the System Navigator, right-click on your EJB and choose New...

2. In the New Object dialog box, click on the Deployment Profiles category, and then select
J2EE EJB Module (EJB JAR file). Click OK.
3. In the Save Deployment Profile dialog box, rename the File name to
MySessionEJB.deploy and click Save.
4. In the J2EE EJB Module Deployment Profile Settings dialog box, accept the defaults and
click OK.
Your new MySessionEJB deployment profile is added to the System Navigator.
To start OC4J:
If you have already initialized OC4J, you can skip this step.
1. Open a command prompt.

2. Navigate to your installation of OC4J.
If you do not have OC4J installed, see the topic Specifying Connection Information to
Oracle9iAS
3. At the command line, enter java -jar oc4j.jar
You should see a message indicating that OC4J is running.
You are now ready to deploy the EJB. If you want to deploy the EJB to an established
connection to Oracle9iAS, in the System Navigator, right click your MyEntityEJB deployment
profile and choose Deploy to <connection name>. To deploy the EJB to a new connection,
follow the directions below:
To deploy the EJB to a new connection to Oracle9iAS:
1. In the System Navigator, right click the deployment profile you just created
(MySessionEJB) and choose Deploy to | New Connection.
3. Enter a Connection name of Oracle9iAS and click Next.
4. On the Authentication page, enter an appropriate user name and password. Click Next.
5. On the Connection page, accept the defaults or enter the appropriate information. Click
13-25
Next.
6. Click Test Connection. If you get an error message, check your connection information.
7. Click Finish.
Now that your EJB is deployed, you can generate a sample client again and test it.
Testing a Remote EJB
Testing a remote EJB is similar to using the embedded OC4J server, you just need to specify
additional details when you generate the sample Java client.
To run a sample client on a remote OC4J server:
1. In the System Navigator, right-click an EJB and choose Create Sample Java Client from
the context menu.
2. In the Sample EJB Client dialog box, select the option to Connect to Remote App
Server.
3. In the J2EE Application Name field enter MySessionEJB
4. In the Oracle9iAS Connection Name field enter Oracle9iAS
5. Click OK.
Your sample client is added to the System Navigator and opens in the Code Editor.
6. In the code, uncomment the generated method call to calc(), replacing it with the
following:
System.out.println(mySessionEJB.calc("a"));
Congratulations, you have completed the walkthrough for a stateless session EJB.
13-26
Developing and Deploying a CMP Entity Bean From
a Database Table
This topic steps you through the procedure of developing and deploying a container-managed
persistence (CMP) entity EJB generated from a database table.
1. Requirements
2. Creating a New Workspace and Project
3. Creating CMP EJBs from Database Tables
4. Testing an EJB Using Embedded OC4J
5. Deploying the EJB to a Remote OC4J Server
6. Testing a Remote EJB
Requirements
● A database connection to the Oracle9i sample schemas.

● To deploy the EJB to the embedded OC4J server does not impose any additional
requirements. To deploy the EJB to a remote connection, you will need to create an
Oracle9iAS connection. For more information, see the topic Specifying Connection
Information to Oracle9iAS.
Putting your EJB files into a new project makes browsing packages easier and simplifies
deployment.
1. From the File menu choose New...

2. In the New Object dialog box, click the Projects category and select Workspace.
3. Without changing the path, change both the workspace directory name and file name to
ejb. Click OK.
13-27
The New Project dialog box will appear.
4. Without changing the path, change both the directory name and file name to
cmp_table. Click OK.
The workspace and project are added to the System Navigator.
Creating CMP EJBs From Database Tables
You use the Create CMP Entity Beans from Table Wizard to create CMP EJBs from database
tables.
To create new CMP EJBs from database tables:
1. In the System Navigator, right-click on the project node (cmp_table.jpr) and select New...
2. In the New dialog box, click on the Enterprise JavaBeans category and then select
Container-managed Entity Beans From Tables. Click OK.
The Create CMP Entity Beans from Table Wizard opens.
3. Review the information on the Welcome page of the wizard and click Next.
4. On the Select Tables page, chose a connection to the HR table from the dropdown list.
If you do not have a connection listed, click New to open the Connection Wizard.
a. Review the information on the Welcome page and click Next.
2. On the Type page, enter a connection name of myJdbcConn. Click Next.
3. On the Authentication page, enter HR for both the Username and Password.
4. Select the checkbox for Deploy password. Click Next.
5. On the Connection page, enter the appropriate connection information. If you do
not know these values, contact your database administrator. Click Next.
6. Click Test Connection. If you do not see the message "Success" check your
connection details with your database administrator.
7. Click Finish.
5. In the Table name pattern field, enter "D".

This will show you all the tables that begin with "D".
6. In the Available tables list, select DEPARTMENTS and shuttle it to the Selected tables
list.
7. In a similar manner select the EMPLOYEES table and shuttle it to the Selected tables list.
8. Click Next.
9. On the Create Entity Beans page, you can change the name and other details of the
13-28
bean, or select a preexisting bean. For this walkthrough you will accept the defaults.
Click Next to view the Summary page, and then click Finish.
Your EJB is added to the System Navigator.
Testing an EJB Using Embedded OC4J
JDeveloper provides a sample client utility that will help you create clients quickly. You can run
and test EJBs using either the embedded OC4J Server or a remote server. The sample client
utility can be used to create a client for either type.
The embedded OC4J server runs inside the same process as JDeveloper. You can run and
test EJBs quickly and easily using this server, and then deploy your EJBs with no changes to
them. You do not need to create a deployment profile to use this server, nor do you have to
initialize it.

OK.
The client is created and opens in the code editor. Notice that a findAll() method is
created by default.
In a typical development scenario, you would use the embedded OC4J server to test your
application as you developed it. Once completed, you would deploy it to a remote server. In this
next step, you'll deploy your EJB to a remote OC4J server.
Deploying the EJB to a Remote OC4J Server
Deploying your EJB follows the following steps:
1. Create a Deployment Profile
13-29
2. Start OC4J
3. Deploy the EJB (you may need to specify a new connection first)
Note: When deploying a CMP EJB, if there is already a table in the database with the same
name as your CMP EJB, no new table or columns will be created. If you want to create a new
CMP EJB, first you must drop the existing table from the database.
Create a new deployment profile:
1. In the System Navigator, right-click on your EJB and choose New...

2. In the New Object dialog box, click on the Deployment Profiles category, and then select
J2EE EJB Module (EJB JAR file). Click OK.
3. In the Save Deployment Profile dialog box, rename the File name to
MyEntityEJB.deploy and click Save.
4. In the J2EE EJB Module Deployment Profile Settings dialog box, accept the defaults and
click OK.
Your new MyEntityEJB deployment profile is added to the System Navigator.
To start OC4J:
If you have already initialized OC4J, you can skip this step.
1. Open a command prompt.

2. Navigate to your installation of OC4J.
If you do not have OC4J installed, see the topic Specifying Connection Information to
Oracle9iAS
3. At the command line, enter java -jar oc4j.jar
You should see a message indicating that OC4J is running.
You are now ready to deploy the EJB. If you want to deploy the EJB to an established
connection to Oracle9iAS, in the System Navigator, right click your MyEntityEJB deployment
profile and choose Deploy to <connection name>. To deploy the EJB to a new connection,
follow the directions below:
To deploy the EJB to a new connection to Oracle9iAS:
1. In the System Navigator, right click the deployment profile you just created
13-30
(MyEntityEJB) and choose Deploy to | New Connection.
3. Enter a Connection name of Oracle9iAS and click Next.
4. On the Authentication page, enter an appropriate user name and password. Select the
checkbox to Deploy Password. Click Next.
5. On the Connection page, accept the defaults or enter the appropriate information. Click
Next.
6. Click Test Connection. If you get an error message, check your connection information.
7. Click Finish.
Now that your EJB is deployed, you can generate a sample client again and test it.
Testing a Remote EJB
Testing a remote EJB is similar to using the embedded OC4J server, you just need to specify
additional details when you generate the sample Java client.
To run a sample client on a remote OC4J server:
1. In the System Navigator, right-click an EJB and choose Create Sample Java Client from
the context menu.
2. In the Sample EJB Client dialog box, select the option to Connect to Remote App
Server.
3. In the J2EE Application Name field enter MyEntityEJB
4. In the Oracle9iAS Connection Name field enter Oracle9iAS
5. Click OK.
Congratulations, you have completed the walkthrough for a CMP entity EJB.
13-31
Packaging and Deploying
● Packaging and Deploying

● OC4J Deployment Application Directory Structure
● About OC4J Data Sources
● Configuring Your Project for Deploying
● Editing Deployment Descriptors (XML)
● List of J2EE Deployment-Related References
● Basic Deployments
❍ Creating and Deploying a Simple Archive to Your File System
❍ Deploying an Executable JAR File
● Ways to Deploy to the Oracle9i Database

❍ Loading Java into the Oracle9i Database
❍ Loading and Publishing Java Stored Procedures in the Oracle9i Database
● Creating Application Server Connections

❍ Creating a Connection to OC4J
❍ Creating a Connection to BEA WebLogic
● Ways to Deploy J2EE Applications

❍ About Deployment Profile Dependencies
❍ Deploying a J2EE Client Deployment Archive (client JAR)

❍ Deploying Java Client Web Archive for Java Web Start
❍ Deploying a JClient Web Archive for Java Web Start
❍ Assembling and Deploying a J2EE Enterprise Archive (EAR)
❍ Deploying Web Applications
■ Deploying a WAR to OC4J
■ Deploying a WAR to WebLogic
14-1
■ Deploying an Applet as a WAR File
■ Deploying a Tag Library for JSP 1.1
■ Deploying Web Applications to Apache Tomcat
■ Deploying a Web Application to Other Application Servers
❍ Deploying EJB JARs

■ Deploying an EJB JAR to OC4J
■ Deploying an EJB JAR to WebLogic

■ Deploying EJBs Built on SQLJ Files
■ Customizing the EJB Descriptors for OC4J Deployment (orion-ejb-jar.xml)
■ Customizing the EJB Descriptors for WebLogic Deployment (weblogic-ejb-
jar.xml)
● Ways to Deploy Business Components for Java (BC4J)

❍ About Business Components for Java Deployment
❍ BC4J Prerequisites for OC4J Deployment

❍ Loading BC4J Runtime Libraries to OC4J
❍ BC4J Prerequisites for WebLogic Deployment
❍ Loading BC4J Runtime Libraries to WebLogic
❍ Deploying BC4J as a Simple Archive File
❍ Deploying JClient as a BC4J Simple Archive
❍ Testing Deployed J2EE Modules with the Business Components Browser
■ Deploying a BC4J Web Application to OC4J
■ Deploying a BC4J Web Application to WebLogic

■ Deploying a BC4J UIX Application
■ Deploying BC4J Web Applications to Apache Tomcat
■ Deploying BC4J as an EJB Session Bean to OC4J

■ Sample Client Code for an EJB Client Deployed to OC4J
■ Deploying BC4J as an EJB Session Bean to WebLogic
■ Sample Client Code for an EJB Client Deployed to WebLogic
❍ Deploying CORBA Objects on VisiBroker
14-2
■ Setting Up the Classpath to Run BC4J Applications
■ Starting Corba Objects on VisiBroker
■ Starting a Business Components Project Using Bind Mode
■ Starting a Business Components Application Using the Naming Service
■ Setting Up the VisiBroker Gatekeeper
■ Modifying HTML Files to Use Visibroker Bind Mode

■ Modifying HTML Files to Use the Visibroker Naming Service
■ Testing with the Business Components Browser

■ Testing Using Bind Mode
■ Testing Using Collocate Mode
■ Testing Using Naming Service
● Ways to Deploy Web Services

❍ Deploying J2EE Web Services to OC4J
❍ Deploying a Web Service to an Oracle9i Release 2 SOAP Server

❍ Deploying a Web Service to an Apache SOAP Server
❍ Deploying an EJB Web Service
■ Deploying an EJB Web Service
■ Registering EJB Web Service Providers with OC4J

■ Deploying a J2EE EJB Module (EJB JAR) to OC4J
■ Deploying an EJB Web Service to Oracle9i SOAP Server
14-3
Packaging and Deploying Using JDeveloper
The Packaging and Deploying book provides information on creating and deploying deployment
profiles in Oracle9i JDeveloper to Oracle9iAS Containers for J2EE (OC4J). A deployment
profile stores information about the deployment, such as the package type, the files that must
be deployed with the profile, and the type and location of the remote system.
Oracle recommends using OC4J for all Java deployment instead of the Oracle Enterprise Java
Engine (EJE). OC4J does not require the use of a middle-tier database.
JDeveloper lets you deploy your J2EE applications to the embedded Oracle9iAS Containers for
J2EE (OC4J) in JDeveloper or to a standalone OC4J instance. See About Deploying on
Oracle9i Application Server for information on deploying to an Oracle9i Application Server
using the Oracle Enterprise Manager.
Before packaging and deploying your applications and J2EE components, read these topics for
a better understanding of the deployment process:
● About Deploying to the Oracle9i Application Server

● OC4J Deployment Application Directory Structure
● About OC4J Data Sources
● Configuring Your Project for Deploying in the Embedded OC4J
● Editing Deployment Descriptors (XML)
● Understanding the n-Tiered Business Components Architecture
● List of J2EE Deployment-Related References
● About Deployment Profile Dependencies
The following sections are included in this book:
14-4
Describes how to create and deploy a simple archive to your
Basic Deployments
file system or deploy an executable JAR file.
Describes how to load Java into the Oracle9i Database and

Ways to Deploy to the Oracle9i Database load and publish Java Stored Procedures in the Oracle9i
Database.
Describes how to create an application server connection to

Creating Application Server Connections Oracle9iAS Containers for J2EE (OC4J) and BEA WebLogic
6.x.
Describes how to create and deploy J2EE applications such

as EJB JARs, servlets, JSPs, client JARs, and tag libraries to
Ways to Deploy J2EE Applications to Oracle9iAS Containers for J2EE (OC4J) and BEA
WebLogic 6.x. This section also covers deployments to
Webstart and Apache Tomcat.
Ways to Deploy Business Components Describes how to create and deploy Business Components
for Java (BC4J) web applications and EJBs to Oracle9iAS
for Java
Containers for J2EE (OC4J) and BEA WebLogic 6.x.
Describes how to create and deploy Business Components

Deploying CORBA Objects on VisiBroker
for Java (BC4J) CORBA components on VisiBroker.
Describes how to create and deploy Web services to

Ways to Deploy Web Services
Oracle9i SOAP Servers and Apache 2.2 SOAP Servers.
14-5
Within Oracle9i JDeveloper, Java application developers can develop, debug, run, CodeCoach,
profile, and test their Java2 Enterprise Edition (J2EE) applications using the embedded
Oracle9iAS Containers for J2EE (OC4J) or a standalone OC4J instance.
OC4J includes containers for the J2EE APIs which enable users to run their J2EE-based
applications entirely in the standard Java Development Kit (JDK) executing on the Java Virtual
Machine (JVM).
The J2EE facilities provided by the Oracle9iAS containers include an Enterprise JavaBeans
(EJB) container, a Java Servlet container, and a JavaServer Pages Translator and runtime
(OJSP). These containers offer a very lightweight, easy to use, high performance J2EE
environment.
Within JDeveloper, developers can also deploy their J2EE applications to JDeveloper's
embedded OC4J server for development or testing purposes. Optionally, developers can
deploy to a standalone OC4J instance that is not embedded or within an Oracle9i Application
Server (Oracle9iAS). JDeveloper uses the Oracle9iAS Containers for J2EE administration
console command-line tool, admin.jar, to deploy to the embedded OC4J or standalone
OC4J.
However, within Oracle9iAS, the Oracle HTTP Server communicates with its own embedded
OC4J to deliver J2EE applications to Oracle9iAS. In this case, rather than deploying directly to
OC4J, your system administrator would use the Oracle Enterprise Manager to deploy the J2EE
Enterprise Archive (EAR) file which was generated in JDeveloper.
Specifically, the Oracle Enterprise Manager Web site provides a process for deploying new
applications into an OC4J server using the OC4J Enterprise Manager Home Page. You can
also use the OC4J Home Page for high-availability, clustering, and other services.
For more information on Oracle9iAS administration, management, and deployment of J2EE

applications to OC4J using the Oracle Enterprise Manager Web site, refer to the "Oracle9i
Application Server Administrator's Guide" Release 2 (9.0.2) Part Number A92171-01, which is
provided with the Oracle9iAS documentation library.
Notes:
● The terms "Oracle9iAS" and "OC4J" may be used interchangeably in JDeveloper's

deployment documentation. However, in JDevelper, when you choose to deploy an
application to an OC4J instance by right-clicking the deployment profile in the Navigator,
14-6
your J2EE applications are actually being deployed into one of the appropriate
Oracle9iAS containers for J2EE in the OC4J server.
● As of Oracle9iAS v1.0.2.2, Oracle recommends using OC4J for all Java deployment,
instead of Oracle Enterprise Java Engine (EJE). OC4J is a feature of Oracle9iAS
Standard Edition in v1.0.2.2 and beyond and does not require the use of a middle-tier
database. Oracle9i JDeveloper supports deployment to the specified OC4J 2.0 server
connection.
● JDeveloper also supports deployments to BEA WebLogic 6.x and Apache Tomcat.
● You must create an OC4J server connection or to a WebLogic application server before
deploying.
● Oracle9iAS Web Services provide complete infrastructure for developing, deploying and
managing Web Services. Oracle9i JDeveloper facilitates efficient development and
deployment of Web services to Oracle9iAS. OC4J is the runtime platform for Web
Services.
Related Topics

Configuring Your Project for Deploying
Ways to Deploy to Oracle9i Database
Ways to Create Application Server Connections
Deploying Web Applications to Apache Tomcat
14-7
Deploying your J2EE applications to the embedded Oracle9iAS Containers for J2EE (OC4J) in
JDeveloper or to a standalone OC4J instance is a completely automated process involving the
following main steps:
1. Create a workspace and project.

2. Create an OC4J server connection.
3. Create a JDeveloper J2EE deployment profile for your J2EE application. JDeveloper
uses a deployment profile to store information about the deployment, such as the
package type, the files that must be deployed with the profile, and the type and location
of the remote system. Deployment profiles are saved to the project folder and are named
with a .deploy filename extension for J2EE application deployments or .bcdeploy for
business components for Java application deployments.
4. Specify or edit the J2EE module's deployment profile settings.
5. Deploy the deployment profile. You are presented with three deployment options. You
can choose to deploy the standard J2EE archive file (for example, WAR, EJB JAR, client
JAR, or Enterprise Archive (EAR) file) to a local or network drive or deploy it directly to
the OC4J server instance or BEA WebLogic 6.x.
Note: See About Deploying on Oracle9i Application Server for information on deploying to an
Oracle9i Application Server using the Oracle Enterprise Manager.
Deploying to Local Disk or Network Drive
If deploying the deployment profile to your local disk or network drive, JDeveloper packages the
individual module into its standard J2EE archive file. Choosing this deployment option makes
sense if you want to test your application locally or if you want to deploy to a J2EE application
server other than Oracle9iAS.
Deploying to Oracle9iAS Containers for J2EE (OC4J)
When you create a WAR or an EJB JAR deployment profile and choose the option to deploy
directly to an OC4J instance, JDeveloper automatically wraps the single WAR or EJB JAR into
an Enterprise Archive (EAR) file and sends the EAR file to OC4J.
If you are deploying directly to OC4J, JDeveloper creates both the J2EE module archive file(s)
14-8
and the EAR file. When creating the EAR file in JDeveloper, you have centralized control over
the process of application assembly. You can mix and match any combination of J2EE EJBs,
J2EE web modules, or J2EE client modules during assembly. In this case, JDeveloper is
actually assembling a minimal EAR file automatically and sending that to OC4J.
When you invoke the deployment profile, the project and, in some cases, accompanying
libraries are also packaged with the standard J2EE archive files. In the case where archive files
are deployed to OC4J as EJB applications or web applications, Oracle9i JDeveloper can
deploy, run, and test the J2EE application as soon as deployment completes.
JClient Deployment
Deployment of JClient applications which are bound to business components is a special case.
In addition to the files in your JClient project, you must include various business component
libraries on the client side. You may also need to make modifications to your files based on the
location of your business components. See Deploying JClient as a BC4J Simple Archive for
more information.
JDeveloper also lets you deploy J2EE applications as CORBA objects on VisiBroker. The
deployment process is similar to the deployment on Oracle9iAS with some additional manual
steps.
WAR Deployment Example
The main steps for creating a J2EE Web Module or Web Archive (WAR file) in JDeveloper and
preparing for deployment are as follows:
1. Create servlets and JSPs.

2. The servlets and JSPs are packaged automatically into a WAR file which also includes
the web.xml deployment descriptor.
3. Deploy the EAR file which contains the WAR to one or more OC4J instances.
OC4J provides automatic compilation of servlets and automatic deployment when the
server receives a WAR archive. OC4J automatically decompresses the WAR archive
and installs the application. This shortens the develop, compile, and deploy cycle of
building J2EE applications.
The "J2EE Blueprints" is an integrated set of documentation and example applications that
illustrate best practices for developing J2EE compatible applications. Refer to the "Packaging
and Deployment" chapter. You can download a copy from:
14-9
http://java.sun.com/j2ee/download.html#blueprints
Related Topics

14-10
About J2EE Applications and How They Are
Packaged and Deployed
Application components such as EJBs and servlets are packaged and deployed to Java2
Enterprise Edition (J2EE) containers using standard archive formats and also includes a J2EE
application deployment descriptor. The deployment descriptor information contains all of the
declarative data required to deploy the components in the module and saved in an XML
configuration file. The deployment descriptor for a J2EE module also contains assembly
instructions that describe how the components are composed into an application.
The following table lists component types and their associated J2EE module, archive package
type, and deployment descriptor(s):
Archive Package
Component Types Module Type Deployment Descriptor
Type
ejb-jar.xml
orion-ejb-jar.xml
Enterprise JavaBeans (EJB) J2EE EJB Module EJB JAR weblogic-ejb-jar.xml
Servlets, JavaServer Pages

J2EE Web Module WAR web.xml
(JSPs), HTML, gif images
J2EE Client
Java Application JAR application-client.xml
Module
Enterprise Archive (EAR files)
JDeveloper provides full support for J2EE Enterprise Archive (EAR) file deployment to an OC4J
instance including the embedded OC4J server. The primary task associated with the EAR
deployment profile is application assembly. According to the J2EE specification, every
application must be assembled and packaged as an EAR file prior to deployment to a J2EE
server.
When you create a Web Application Archive file (WAR) or an EJB JAR deployment profile and
choose the option to deploy directly to the specified OC4J connection, JDeveloper
automatically wraps the single WAR or EJB JAR into an EAR file and sends the EAR file to the
OC4J instance or one of the other supported application servers including BEA WebLogic 6.x
and Apache Tomcat.
14-11
If you have multiple WAR, EJB JAR, and/or client JAR profiles, these are assembled and
packaged into an EAR file before deployment. This is done by creating a J2EE Enterprise
Archive (EAR file). With JDeveloper, you assemble other modules into the EAR file before
deploying them to the J2EE server connection. Choosing to deploy an EAR file also makes
sense if you want to deploy your application to a J2EE server such as Oracle9i Application
Server. See About Deploying on Oracle9i Application Server for information on deploying to an
Related Topics

Assembling and Deploying a J2EE Enterprise Archive (EAR)
About Deployment Profile Dependencies
14-12
OC4J Deployment Application Directory Structure
Whenever you deploy an application, OC4J automatically generates the OC4J-specific XML
files with the default elements. JDeveloper lets you edit these files or add to the existing XML
files from JDeveloper. It copies the XML files to where your original development directory for
the application and changes it in this location. If you change the XML file within the deployed
location, OC4J simply overwrites these changes when the application is deployed again. The
changes only stay constant when changed in the development directories.
For all OC4J-specific XML files, you can add these files within the recommended development
structure as shown below:
<appname>
|-------META-INF
| `-------application.xml
|
|-------ejb
| |-------EJB classes (my.ejb.class maps to /my/ejb/class)
| `-------META-INF
| |-------ejb-jar.xml
| `-------orion-ejb-jar.xml
|-------web
| |-------index.html
| |-------JSP pages
| `-------WEB-INF
| |----web.xml
| |----orion-web.xml
| `----classes
| `-------Servlet classes
`-------client
|-------Client classes
`-------META-INF
|-------application-client.xml
`-------orion-application-client.xml
You can provide all application XML files in either of the following:
● Within the application directory as specified by J2EE. This is recommended because it

keeps the global and default configuration files separate from the application-specific
configuration files.
● JDeveloper recognizes the deployment descriptor file in the META-INF/application-
client.xml found in the first entry of the sourcepath. Any other names and locations for
application-client.xml file will be ignored.
14-13
● Within the config directory with all of the OC4J server XML files. Refer to the
"Oracle9iAS Containers for J2EE User's Guide" Part Number A95880-01 provided with
the Oracle9iAS documentation library for information on the deployed location of the
application files including these files.
Related Topics
Customizing the EJB Descriptors for OC4J Deployment (orion-ejb-jar.xml)

Customizing the EJB Descriptors for WebLogic Deployment (weblogic-ejb-jar.xml)
14-14
J2EE applications such as servlets and EJBs retrieve connections to the database through
java.sql.DataSource objects. The class entry used must be
com.evermind.sql.DriverManagerDataSource and the connection entry used must be
the oracle.jdbc.driver.OracleDriver class. Data sources are factories that return
JDBC connections to business data in an Oracle9i database.
If you are using JDeveloper's embedded Oracle9i Application Server Containers for J2EE
(OC4J) server to run, debug, profile, or CodeCoach your EJB applications, a <data-source>
element is automatically created for each JDBC database connection defined in JDeveloper
and written to the embedded OC4J server's data source file. JDeveloper ensures that this file is
updated accordingly as new data source elements are created and whenever the embedded
OC4J server is started. Do not edit this file as this may affect the proper running of the
embedded OC4J server.
For deployment to a remote OC4J instance, all data sources are defined in the data-
sources.xml file. When you deploy a WAR or EJB, the latest data-sources.xml file is
automatically packaged and deployed with the Enterprise Archive (EAR) file. For each
configured database instance, there should be a corresponding <data-source> element in the
data-sources.xml file which is located in the following OC4J directory:
<ORACLE_HOME>/j2ee/config
When deploying Business Components for Java applications to a remote OC4J instance,
JDeveloper generates the data sources file based on the database connection name you have
chosen in the Business Components Deployment Wizard to build the BC4J project. Also, the
data-sources.xml file is automatically packaged and deployed with the Enterprise Archive
(EAR) file. For more information, see:
● Deploying BC4J as an EJB Session Bean to OC4J

● Deploying BC4J as an EJB Session Bean to WebLogic
● Deploying a BC4J Web Application to OC4J
● Deploying a BC4J Web Application to WebLogic
Sample data-sources.xml
14-15
<data-source
name="OracleDS”
schema="database-schemas/oracle.xml"
location="jdbc/oracle9iCoreDS"
xa-location="jdbc/xa/OracleXADS"
ejb-location="jdbc/oracle9iDS"
connection-driver="oracle.jdbc.driver.OracleDriver"
username="Scott"
password="tiger”
url="jdbc:oracle:thin:@dlsun1630:1521:ORCL"
/>
See also: For more information about OC4J data sources, see the "Oracle9iAS Containers for
J2EE User's Guide" which is provided with the
Oracle9iAS documentation library.
Foreign Data Sources Support
If you have configured other types of JDBC connections besides Oracle, the driver information
and connection details from the connection descriptor file, connections.xml, are also
included in the data-sources.xml file and bundled with the deployed .ear file used by the
embedded OC4J server. These connections are added to the data-source entry in the data-
sources.xml file.
If you are connecting to heterogeneous databases such as Microsoft, SQLServer, Sybase, and
DB2, refer to the the Merant documentation for installing Merant JDBC drivers.
Note: For more information on foreign data source support and configuration, refer to the
Oracle9i JDeveloper Release Notes.
Related Topics

14-16
14-17
Configuring Your Project for Deploying to the
Embedded OC4J Server
If you are using the embedded OC4J server to run, debug, profile, CodeCoach, and test your
deployments, you can configure your project settings for deployment. For example, you can
select to compile your project before deploying, specify which OC4J installation to use, the port
assignments for the embedded OC4J server, and the OC4J host name and IP address.
To configure your project's deployment options to run the embedded OC4J server in
JDeveloper:
1. Choose Tools | Preferences... from the main menu.

2. Click the Deployment node to see all the options.
3. Configure the deployment options as required:
a. Select Compile Before Deploying especially if you are planning to deploy J2EE
modules which have cross-project dependencies.
Notes: JDeveloper lets you select J2EE module deployment profile dependencies
across projects in the same workspace. You can select dependencies on the
Profile Dependencies page which you can access by right-clicking the deployment
profile icon (.deploy) in the Navigator and choosing Settings. From the
Deployment Profile Settings panel, click the Profile Dependencies node to display
its page.
If the project you are deploying does not have any deployment profile
dependencies, then only that project in the workspace will be compiled before
deploying. However, if deployment profile dependencies exist, then all projects in
the workspace which contain these dependencies, will also compile before
deploying.
b. Select Automatically fill in <ejb-ref> elements in web.xml to have JDeveloper
automatically insert any <ejb-ref> elements to the web module deployment
descriptor file, web.xml, whenever EJB dependencies are included in the WAR
profile. If this check box is cleared, you should make sure that the web.xml is
complete and accurate before deployment.
c. By default, JDeveloper uses the OC4J server installed automatically with
JDeveloper when running, debugging, profiling, and CodeCoaching. However, if
you want to use another instance of OC4J, specify its location in the OC4J
Installation to Use for Running and Debugging text field.
d. Enter the appropriate Port Assignments for Embedded OC4J: HTTP, RMI, JMS.
e. Enter the Host Name or IP Address Used to Refer to Embedded OC4J.
14-18
4. For more information, click Help.
For information on how to configure a remote OC4J instance for deployment, see "Oracle9iAS
Containers for J2EE User's Guide" Part Number A95880-01 which is provided with the
Oracle9iAS documentation library.
Related Topics

14-19
Once a J2EE module deployment profile is created, JDeveloper also generates an associated
deployment descriptor. Application components are packaged and deployed to Java2
Enterprise Edition (J2EE) containers using standard archive formats and also includes a J2EE
application deployment descriptor. The deployment descriptor information contains all of the
declarative data required to deploy the components in the module and saved in an XML
configuration file. The deployment descriptor for a J2EE module also contains assembly
instructions that describe how the components are composed into an application.
These deployment descriptors appear in the Navigator. You may wish to make modifications to
the deployment descriptor, for example to add or delete elements in the xml file.
To edit deployment descriptors:
1. In the Navigator, right-click the deployment descriptor you want to edit.

❍ The J2EE module deployment descriptor names display as follows in the
Navigator:
❍ web.xml: J2EE Web Module deployment descriptor
❍ ejb-jar.xml:J2EE EJB JAR Module deployment descriptor
❍ orion-ejb.jar.xml: OC4J platform-specific EJB JAR Module deployment descriptor
❍ weblogic-ejb.jar.xml: BEA WebLogic platform-specific EJB JAR Module
deployment descriptor
❍ application-client.xml: J2EE Client Module deployment descriptor
❍ taglib.tld: J2EE Tag Library deployment descriptor
2. Choose Settings from the context menu.

The appropriate Deployment Descriptor dialog is displayed by default.
Note: If you prefer to edit the deployment descriptor's XML file, choose Code Editor in
the context menu instead.
3. Click the tree options in the left frame to edit the deployment descriptor settings as
required.
For more information about EJBs, see the "Oracle9i Application Server Enterprise JavaBean
Developer's Guide and Reference" Part Number A95881-01, which is provided with your
Oracle9iAS documentation library. This guide tells you what you need to know to develop EJBs
in the OC4J environment.
14-20
Note: JDeveloper recognizes the deployment descriptor file in the META-INF/application-
Related Topics

14-21
The following is a list of references to information and documentation relating to JDeveloper's
support for developing and deploying Java2 Enterprise Edition (J2EE) applications:
Oracle9i Application Server
Oracle9i Application Server v1.0.2.2 introduced Oracle9iAS Containers for J2EE or "OC4J" for
short. These are containers for the J2EE APIs which enable users to run their J2EE-based
applications in the standard Java Development Kit (JDK) executing on the Java Virtual Machine
(JVM).
Upon installation of Oracle9iAS, see the "Oracle9iAS Containers for J2EE User's Guide"
Release 2.0 (Part Number A95880-01) and "Oracle9i Application Server Administrator's Guide"
Release 2 (Part Number A92171-01) for important information, including instructions on how to
configure data sources in OC4J to use against the Oracle9i database.
Note: Oracle9i JDeveloper requires OC4J Release 2 which is also the default application
server embedded in JDeveloper. You can run, debug, profile, and CodeCoach your code
directly in JDeveloper's embedded OC4J server.
For general Oracle9iAS Container for J2EE information and updates, visit:
● http://otn.oracle.com/docs/tech/java/oc4j
● http://www.oracle.com/ip/deploy/ias/index.html
● http://otn.oracle.com/sample_code/tech/java/oc4j/content.html
● http://otn.oracle.com/products/ias/content.html
For web seminars, visit:
http://www.oracle.com/ip/deploy/ias/index.html?eclass.html
Oracle9iAS user community
If you want to ask a question to the Oracle9iAS user community, please see the Oracle
Technology Network discussion forum at:
● http://otn.oracle.com/forums/Oracle9iAS.html
14-22
Sun J2EE References
● The "J2EE Blueprints" is an integrated set of documentation and example applications

that illustrate best practices for developing J2EE compatible applications. Refer to the
"Packaging and Deployment" chapter. You can download a copy from:
● The EJB Container in Oracle9iAS provides full support for EJB 1.1 and significant parts
of EJB 2.0. For more information about the standard EJB 1.1 Deployment Descriptors,
see Chapter 16 of the specification which you can download from:
http://java.sun.com/products/ejb/docs.html
● The Web Container in Oracle9iAS provides full support for Servlets 2.2 and Java Server
Pages (JSP) 1.1. For more information, refer to the Sun Microsystems Java Servlet
Specification, Version 2.2 which you can download from:
● Oracle9iAS provides full support for J2EE Client applications. For more information, refer
to "Chapter 9, Application Clients in the J2EE Platform Specification 1.2" which you can
download from:
http://java.sun.com/j2ee/download.html
J2EE Community
Provides the latest information about J2EE events, discussions, patterns, resources, white
papers, and reviews within the community.
http://www.theserverside.com
Oracle9i Java Documentation References
The following is a list of J2EE guides provided with the Oracle9iAS Release 2.0 (version 9.0.2)
documentation library:
Oracle9i Application Server Administrator's Guide

Part Number A92171-01
Oracle9iAS Containers for J2EE User's Guide
14-23
Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference
Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference
Oracle9iAS Containers for J2EE Servlet Developer's Guide
Oracle9i Application Server Enterprise JavaBean Developer's Guide and Reference
Oracle9i JDBC Developer's Guide and Reference
Oracle9i SQLJ Developer's Guide and Reference
The following is a list of Oracle9i database-related guides provided with the Oracle9i Database
Release 9.0.1 documentation library:
Java Developer's Guide

Oracle9i Java Tools Reference
Oracle9i Java Stored Procedures Developer's Guide

OracleJSP Support for JavaServer Pages Developer's Guide and Reference
Oracle9i SQL Reference
These guides are also accessible online from the Oracle Technology Network (OTN) at:
http://otn.oracle.com
You must register online before using OTN; registration is free.
14-24
Related Topics

14-25
Basic Deployments
The basic deployments provided by JDeveloper include:
● Deploying a Simple Archive to Your File System

● Deploying an Executable JAR File
14-26
Deploying a Simple Archive to Your File System
JDeveloper has various deployment modes for different applications. However, you may want
to quickly and simply deploy your application as a JAR or ZIP file to your file system.
To create and deploy a simple archive in JDeveloper:
1. With a project selected in the JDeveloper Navigator, choose File | New... to open the
New Object dialog. Select Deployment Profiles in the Categories list and choose Simple
Archive in the Items list.
2. Click OK.
3. Specify a location for the simple archive's deployment profile or accept the defaults.
The deployment profile is named with a .deployfilename extension.
4. Click Save.
The Simple Archive Deployment Profile Settingspanel displays.
5. In the Files page, choose which files you want packaged in the archive.
6. Select Automatically include files added to project if you want any new or additional
files in your project to be automatically added to the project and the deployment profile.
7. In the How should the selected source files be deployed? list box, choose how the
output file(s) is deployed.
8. In the JAR Options page, specify additional parameters for the JAR file and manifest file.
9. In the Dependency Analyzer page, the check box tree displays the list of libraries that
are in your project's current active configuration. If you want to repackage the contents of
other libraries in your output JAR file, select the appropriate check boxes.
10. Select the appropriate radio button corresponding to how the libraries will be used.
11. (advanced) If you require further refinement to the Dependency Analyzer settings, click
Filters on the tree to the left of this panel.
Setting filters is not required for a typical deployment.
12. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
modules from another deployment profile. JDeveloper supports deployment profile
dependencies across projects in the same workspace. Select the check box next to the
<name_of_deployment_profile>.deploy you want included with the deployment.
The newly created simple archive deployment profile icon appears in the Navigator
below the specified project.
14-27
14. Select and right-click in the Navigator.
15. Choose the Deploy to option to display the Deploy to Java Archive File (JAR) dialog
from which you can choose the location for the simple archive. By default, the simple
archive is deployed in the current project's directory.
16. (optional) If you want to edit the simple archive deployment profile settings, right-click
and choose Settings.
Related Topics
Deploying an Executable JAR File
Deploying Java Client Web Application Archive for Java Web Start
Deploying Business Components for Java as a Simple Archive File
Deploying JClient as a BC4J Simple Archive
14-28
You can make your simple archive or J2EE Client Module into an executable JAR file that you
can launch with the java -jar myapp.jar command in the following way:
1. Select and right-click the simple archive or client icon in the Navigator to display the
context menu.
2. Choose Settings.
3. Click JAR Options in the tree.
4. Select Include Manifest File (META-INF/MANIFEST.MF).
5. In the Main Class field, enter the fully qualified name of the class containing the main
method you invoke when using java -jar.
6. Click OK.
7. Launch the executable JAR file from the command line with the following command:
java -jar myapp.jar
where myapp is replaced with your JAR file name.
Related Topics
Creating and Deploying a Simple Archive to Your File System

Creating and Deploying a J2EE Client Module Deployment Profile (client JAR)
Running a Project From the Command Line
14-29
JDeveloper provides the following way to deploy to the Oracle9iAS database:
● Loading and Publishing Java Stored Procedures in the Oracle9i Database

● Loading Java into the Oracle9i Database
14-30
Loading Java into the Oracle9i Database
The loadjava profile is very similar to the simple archive profile, except that the selected
contents of the profile will be uploaded into the Oracle9i database via the command-line tool
loadjava. For more information about this command, refer to "Chapter 1, Oracle9i Java Tools
Reference" (Part No. A83727-01, page 1-7) provided with the Oracle9i database
documentation library.
Make sure that you have configured a database connection in JDeveloper before you complete
this task.
To create and deploy loadjava in JDeveloper:
New gallery. Select Deployment Profiles in the Categories list and choose Loadjava in
the Items list.
2. Click OK.
3. Specify a location for the deployment profile or accept the defaults.
4. Click Save.
The Loadjava Deployment Profilepanel displays.
11. Click Loadjava Options on the tree to the left of this panel and configure the loadjava
options including the Privileges and Resolver settings.
If you require help to configure any of the loadjava options, refer to the "Chapter 1,
Oracle9i Java Tools Reference"which is provided with your Oracle9idatabase
14-31

The newly created loadjava deployment profile icon appears in the Navigator pane
13. Select and right-click . The context menu displays the database connections available.
14. Choose one of these database connections.
The Java application's source files are uploaded directly into the selected database.
15. (optional) If you want to edit the loadjava deployment profile, right-click and choose
Settings...
Note: If you are deploying your files "As both compiled files and source files" and the you've
selected either -resolve or -andresolve in the Resolver page, then the deployment profile will
only upload the source files. The reason is that when loadjava resolves the uploaded .java
source files, loadjava also compiles the .java source files into .class files. You will only see
the source files when previewing the loadjava deployment profile settings.
Related Topics
Loading and Publishing Java Stored Procedures in the Oracle9i Database
14-32
Loading and Publishing Java Stored Procedures in
the Oracle9i Database
Stored procedures are Java methods published to SQL and stored in an Oracle9i database for
general use. With stored procedures, you can implement business logic at the server level,
thereby improving application performance, scalability, and security. The Oracle9i database
provides Java applications with a dynamic data-processing engine that supports complex
queries and different views of the same data. All client requests are assembled as data queries
for immediate processing, and query results are generated on the fly.
To load and publish java stored procedures in the Oracle9i database with JDeveloper:
New Object dialog. Select Deployment Profiles in the Categories list and choose Stored
Procedures in the Items list.
2. Click OK.
3. Specify a location for the deployment profile or accept the defaults.
4. Click Save.
The Stored Procedures Deployment Profile Settingspanel displays.
5. On the Loadjava Options page, configure the loadjava options including the Privileges
and Resolver settings.
If you require help to configure any of the loadjava options, refer to the "Chapter 1,
Oracle9i Java Tools Reference"which is provided with your Oracle9idatabase

The newly created stored procedures deployment profile icon appears in the Navigator
8. Select and right-click to view the options on the context menu.

9. Choose Add Stored Procedure to choose which methods you want to publish as a
stored procedure. For each Java method callable from SQL, a call spec is required,
which exposes the method's top-level entry point to the database. Typically, only a few
14-33
call specs are needed. Oracle9i JDeveloper generates the call spec for you from this
page.
10. Select a method and click Settings.
If a method on the list is dimmed, this indicates a problem with deploying this method as
a Java stored procedure. Click Why not?for an explanation.
Refer to the "Oracle9i Java Stored Procedures Developer's Guide"for more information.
11. Configure the Method Settings as required. These settings allow you to customize the
parts of the CREATE PROCEDURE and CREATE FUNCTION SQL statements that are
used to customize the stored procedure.
See the "Chapter 9 in the Oracle9i SQL Reference"for more information about the
CREATE FUNCTION, CREATE PROCEDURE, CREATE PACKAGE, and CREATE
PACKAGE BODYstatements which are used by the stored procedure deployment profile.
12. The context menu displays Deploy to from which you can choose an available database
connections.
13. In the Navigator, select and right-click .
14. Choose Add PL/SQL Package.
15. In the Add PL/SQL Package dialog, enter the name of a PL/SQL package that you want
to start building.
icon indicates a PL/SQL procedure
icon indicates a PL/SQL function
16. Choose Preview SQL Statements to display a dialog that shows the SQL statements
used to publish the the specifically selected item in the Navigator. In the case of top-level
procedures or functions and packages, you will see complete SQL statements. In the
case of packaged procedures or functions, you will only see fragments of SQL
statements which represent the portion of the CREATE PACKAGE BODY statement
corresponding to the packaged procedure or function.
17. Choose Deploy to and select one of the already existing database connections or
choose New Connection to display the Database Connection Wizard.
The Java application's source files are uploaded directly into the selected database.
18. (optional) If you want to edit the stored procedures deployment profile, right-click and
choose Settings...
Note: If you are deploying your files "As both compiled files and source files" and the you've
selected either -resolve or -andresolve in the Resolver page, then the deployment profile will
only upload the source files. The reason is that when loadjava resolves the uploaded .java
source files, loadjava also compiles the .java source files into .class files. You will only see the
14-34
source files when previewing the loadjava deployment profile settings.
Related Topics
14-35
Oracle9i JDeveloper supports deployment of your applications to Oracle9iAS Containers for
J2EE (OC4J) or to BEA WebLogic 6.x. Click the link which corresponds to the type of
application server connection you want to create:
● Creating a Connection to Oracle9iAS Containers for J2EE (OC4J)

● Creating a Connection to BEA WebLogic
JDeveloper lets you deploy your J2EE applications to the embedded Oracle9iAS Containers for
J2EE (OC4J) in JDeveloper or to a standalone OC4J instance. See About Deploying on
Related Topics

14-36
Creating a Connection to Oracle9iAS Containers for
J2EE (OC4J)
Oracle9iAS Containers for J2EE (OC4J) enables users to run and deploy their J2EE-based
applications in the standard Java Development Kit (JDK) executing on the Java Virtual Machine
(JVM). However, you must first specify the connection information to OC4J instance to which
you want to deploy. If you are deploying to the embedded OC4J server provided with
JDeveloper, you would enter localhost connection information. JDeveloper supports
deployment to OC4J connections that are not embedded in Oracle9i Application Server.
Important: If you plan on deploying your applications to an Oracle9i Application Server (rather
than deploying directly to a standalone OC4J), your system administrator will use the Oracle
Enterprise Manager Web site to deploy your new applications into an OC4J server using the
OC4J Enterprise Manager Home Page. For more information on Oracle9iAS administration,
management, and deployment of J2EE applications to OC4J using the Oracle Enterprise
Manager Web site, refer to the "Oracle9i Application Server Administrator's Guide" Release 2
(9.0.2) Part Number A92171-01, which is provided with the Oracle9iAS documentation library.
See also About Deploying on Oracle9i Application Server when you plan to deploy to an
Oracle9i Application Server.
Note: Some dialog boxes and wizards within JDeveloper also let you create an OC4J server
connection.
To create a connection to an OC4J instance:
1. In the Navigator, click + to expand the Connections node.
2. Right-click Application Servers.

3. Choose New Connections from the context menu.
The Connection Wizard - Welcome page is displayed.
4. Click Next.
5. Enter a Connection Name for this connection.
6. Choose Oracle9i Application Server from the Connection Type list box.
7. Click Next.
8. In the Username field, enter the administrator's user name to access OC4J. This name
was specified when OC4J was installed.
9. In the Password field, enter the administrator's password to access OC4J.This name
was specified when OC4J was installed.
14-37
10. Select the Deploy Password check box if you want to bypass authentication the next
time you make this connection. Your password is deployed with your project's
connection.xml file.
11. Click Next.
12. In the URL field, enter the location of the OC4J instance.
The valid URL format is as follows:
ormi://<hostname>:<port>/ or ormis://<hostname>:<port>
where <hostname> is the TCP/IP DNS name of the machine in which the Oracle9iAS
Containers for J2EE are installed. If they are installed in the same machine in which
JDeveloper is installed, enter "localhost" and <port> is the TCP/IP port number. If no port
number is specified, then the default is applied.
13. In the Target Web Site field, enter the name of the Web site containing your deployed
J2EE application files. All Web applications deployed to this connection will be bound to
this specified Web site.
14. In the Local Directory Where admin.jar for Oracle9iAS is Installed, you may need to
enter the location of the Oracle9iAS Containers for J2EE administration console
command-line tool (admin.jar).
Note: Oracle9i JDeveloper uses a default value which is valid for Oracle9iAS Release 2.
You only need to change this value if the version of Oracle9iAS you are using for
deployment is not Release 2.
15. Click Next.
16. Click Test Connection.
17. If your connection is successful, click Finish. Otherwise, click Back to return to the
previous wizard pages and fix any configuration(s) setting.
The configuration to deploy your J2EE applications on Oracle9iAS is complete.
Click the Help button for additional information on any page.
Notes:
● If the default configuration is used, you should be able to access the Oracle9iAS
application server at:
http://localhost:8888
connection information is also contained in the principals.xml file on Oracle9iAS. For

more information, refer to the "Oracle9iAS Containers for J2EE User's Guide" Release
14-38
2.0 (Part Number A95880-01) which is provided with the Oracle9iAS documentation
library.
● If you are deploying Business Components, see also BC4J Deployment Prerequisites for
OC4J Deployment.
Related Topics
Creating and Deploying a J2EE EJB Module (EJB JAR) to OC4J
Creating and Deploying a J2EE Web Module Deployment Profile (WAR) to OC4J
BC4J Deployment Prerequisites for OC4J Deployment
Deploying a BC4J Web Application to OC4J
14-39
Creating a Connection to BEA WebLogic
JDeveloper supports deployment of J2EE EJB deployment profiles created in JDeveloper to a
BEA WebLogic 6.x application server. Before you deploy, copy the weblogic.jar file and
create a WebLogic connection in JDeveloper.
Important: Copy the weblogic.jar file from your WebLogic installation directory (the default
location is c:/bea/wlserver6.1/lib) to the following JDeveloper directory:
jdev_home/jdev/lib/ext
To create a connection to a BEA WebLogic 6.x instance:
1. In the Navigator, click + to expand the Connections node.
2. Right-click Application Servers.

3. Choose New Connections from the context menu.
The Connection Wizard - Welcome page is displayed.
4. Click Next.
5. Enter a Connection Name for this connection.
6. Choose Weblogic Server 6.x from the Connection Type list box.
7. Click Next.
8. In the Username field, enter the administrator's user name to access the WebLogic
server. This name was specified when the WebLogic server was installed.
9. In the Password field, enter the administrator's password to access the WebLogic
server.This name was specified when the WebLogic server was installed.
10. Select the Deploy Password check box if you want to bypass authentication the next
time you make this connection.
11. Click Next.
12. Enter the hostname and port number of the WebLogic server on which your J2EE
applications (.jar, .war, .ear) are deployed.
13. (optional) In the Target Node field, configure this setting only if your WebLogic
application server is configured to distinguish non-administrative server nodes by name.
This helps to indicate how a J2EE application is to be distributed among the backend
nodes.
14. In the Path to weblogic.jar Containing WebLogic Client, enter the fully-qualified location
of the browser-based WebLogic Server Console tool.
14-40
15. Click Next.
16. Click Test Connection.
17. If your connection is successful, click Finish. Otherwise, click Back to return to the
previous wizard pages and fix any configuration(s) setting.
The configuration to deploy your J2EE applications on the WebLogic application server is
complete.
Click the Help button for additional information on any page.
Notes:
If the default configuration is used, you should be able to access the WebLogic application
server at:
http://localhost:7001
For more information, see the "WebLogic Server 6.1 Administration Guide" which can be found
at:
http://e-docs.bea.com
Related Topics
BC4J Setup and Deployment Prerequisites for WebLogic Deployment

Creating and Deploying a WAR to WebLogic
Creating and Deploying an EJB JAR to WebLogic
Deploying a BC4J Web Application to WebLogic
Loading BC4J Runtime Libraries to WebLogic
14-41
JDeveloper provides many way to deploy your J2EE Applications including the following:
Deployments to Oracle9iAS Containers for J2EE (OC4J)
● Creating and Deploying a J2EE EJB Module (EJB JAR) to OC4J

● Creating and Deploying a J2EE Web Module Deployment Profile (WAR) to OC4J
● Creating and Deploying a J2EE Client Module Deployment Profile (client JAR)
● Creating and Deploying a J2EE Enterprise Archive (EAR) to OC4J
● Creating and Deploying a Tag Library for JSP 1.1
Deployments to BEA WebLogic 6.x
● Creating a Connection to BEA WebLogic

● Creating and Deploying a WAR to WebLogic
● Creating and Deploying an EJB JAR to WebLogic
Other Deployments
● Deploying a Web Application to Other Application Servers

● Deploying Java Client Web Archive for Java Web Start
● Deploying a JClient Web Archive for Java Web Start
● Deploying Web Applications to Apache Tomcat
Note: See About Business Components for Java (BC4J) Deployment for information on BC4J
deployments supported in JDeveloper.
Related Topics
14-42
14-43
JDeveloper is designed to take full advantage of all the benefits in Java technology: scalability,
portability, and programming ease. The J2EE application model encourages developers to
create specific types of components (EJB, JSP, servlet, client applications), each performing a
specific function within the J2EE application. For example, an Internet shopping application
could have EJBs that perform the login and checkout functions, JSPs or servlets that perform
web server tasks like processing transactions, HTML and images that describe the items in the
shopping catalog. However, all of these application components and classpaths must be
deployed on the application server to run in concert.
In JDeveloper, you create a project to store a set of files that define a JDeveloper program or
portion of a program. In this way, several developers can work on developing their own
individual components for a J2EE application before they add their project into JDeveloper's
common workspace. Additionally, when components are kept in separate projects, it is easier to
troubleshoot errors since you can debug projects individually in JDeveloper.
When developing J2EE components, it is very common for J2EE components to depend on
each other. This is why, JDeveloper provides a way for you to build and deploy an application
that is composed of several modules directly in the deployment profile. Since a deployment
profile is the concrete representation of a software module, it makes sense to keep track of
dependencies between modules here. Specifying profile dependencies is an important part of
the application assembly process. When deploying, JDeveloper will recurse through all profile
dependencies and make sure that all modules are packaged and deployed as specified by the
deployment profiles.
Note that if the project you are deploying does not have any deployment profile dependencies,
then only that project in the workspace will be compiled before deploying. However, if
deployment profile dependencies exist, then all projects in the workspace which contain these
dependencies, will also compile before deploying.
You can select dependencies on the Profile Dependencies page which you can access by right-
clicking the deployment profile icon (.deploy) in the Navigator and choosing Settings. Only
deployment profiles in the current workspace are listed and available for selection. Click the
Help button from this panel for more information.
Avoiding Circular Dependency
Avoid deployment profiles which have "cycles" or "circularities" in the inter-profile dependencies.
For example, you would have a circular dependency in this scenario:
14-44
● Profile A depends on Profile B
● Profile B depends on Profile C
● Profile C depends on Profile A
When JDeveloper encounters a circular dependency, it will attempt to deploy anyway. However,
a warning is displayed in the deployment log window identifying the circular dependencies that
were found. The presence of a circular dependency generally means that module boundaries
have not been established correctly. It is normally possible to arrange classes and modules so
that the same semantic relationships of the modules can be preserved without the circular
dependency.
Circularities legitimately occur between Java packages and even between framewoks of several
packages each. However at some point of complexity, it is very important to avoid circularities in
order to preserve the level of abstraction and encapsulation provided by a module. Since
deployment profiles are intended to represent such modules, all detected circular dependencies
are identified in the warning messages in the Deployment log window.
After selecting the deployment profile dependencies, you can run, debug, CodeCoach, or profile
your application within the embedded OC4J server. Thus, you are not required to deploy your
J2EE modules to a remote OC4J instance each time you want to test the application.
Alternatively, when you are ready to deploy all the J2EE modules and components to a remote
OC4J instance, you can also choose to create a J2EE Enterprise Archive (EAR) file for
deployment. Rather than choosing deployment profile dependencies, you would choose which
specific J2EE modules to deploy as a single EAR file.
For more information about the J2EE application model, see:
http://java.sun.com/j2ee/overview2.html
Related Topics
About Deploying to the Oracle9i Application Server
14-45
14-46
Creating and Deploying a J2EE Client Module
Deployment Profile (client JAR)
A J2EE Client module is packaged as a client JAR file which contains one or more Java
application components and a client deployment descriptor file named application-client.xml.
JDeveloper lets you create the deployment profile containing the Java application components
and the deployment descriptor file and packages them into a standard J2EE archive for
deployment.
Note: You must create an application server connection to either OC4J or WebLogic before
deploying the client JAR.
To create and deploy a J2EE Client JAR in JDeveloper:
1. With a project selected in the JDeveloper Navigator, choose File | New...

2. Select Deployment Profiles in the Categories list and choose Client JAR file - J2EE
Client Module in the Items list.
3. Click OK.
4. Specify a location for the client's deployment profile or accept the defaults.
5. Click Save.
The J2EE Client Module Deployment Profilepanel displays.
14-47
The newly created client deployment profile icon appears in the Navigator below the
specified project.
15. Select and right-click . The context menu displays these deployment options:
a. Deploy to JAR file: the Client module is packaged as an client JAR file and saved
to the local project directory.
b. Deploy to EAR file: the Client module is packaged as an Enterprise Archive (EAR)
file and saved to the local project directory.
c. Deploy to <Name_of_application_server_connection>: the Client module is
packaged as a client JAR. JDeveloper also generates an EAR file which contains
the client JAR before deploying to the selected OC4J or WebLogic connection.
16. Choose one of these deployment options.

The Client module is deployed to the target application server directory. For OC4J, see
OC4J Deployment Application Directory Structureor refer to the "Oracle9iAS Containers
for J2EE User's Guide"Part Number A95880-01 provided with the Oracle9iAS
documentation library for information on the deployed location of the application files
including the client JAR file.
17. (optional) If you want to edit the Client module deployment profile, right-click and choose
Settings...
Notes:
● If you require further assistance for any field on any page, click Help.
● Oracle9iAS provides full support for J2EE Client applications. For more information, refer
to "Chapter 9, Application Clients in the J2EE Platform Specification 1.2" which you can
download from:
http://java.sun.com/j2ee/download.html
● Make sure that the client deployment descriptor is located inside the client JAR file as
follows:
META-INF/application-client.xml
Note: JDeveloper recognizes the deployment descriptor file in the META-INF/application-
14-48
Related Topics
14-49
Deploying a Java Client Web Application Archive
for Java Web Start
You can use JDeveloper's simple J2EE web deployment process to set up the web server
before downloading and running the application using Java Web Start. The process of
deploying involves creating a connection to Oracle9iAS Containers for J2EE (OC4J).
Note: If your application accesses files outside of the Java Web Start software, it will be necessary
to grant security permissions in the JNLP file and sign your JAR files. Instructions to verify JAR files
is available among the JDeveloper TechNotes on the Oracle Technology Network (OTN) at:
http://technet.oracle.com/docs/products/jdev/technotes/listing.htm
Once the application resides on the web server, it becomes very easy to maintain. Java Web
Start takes care of identifying and downloading application updates each time the user runs the
application.
To deploy Java client applications to the web server:
1. Create a simple JAR archive of your Java client application.

2. Run the Java Client Web Start Wizard to generate the JNLP file and HTML file for use
with Java Web Start.
4. Select Deployment Profiles in the Categories list and choose WAR File - J2EE Web
Module in the Items list.
5. Click OK to create a WAR file which contains the JNLP file, the simple JAR file, and the
HTML file. For more information, see Creating and Deploying a J2EE Web Module
Deployment Profile (WAR) to OC4J.
The newly created WAR deployment profile icon appears in the Navigator below the
specified project.
a. Deploy to <Name_of_server_connection>: the Web module is packaged as a
WAR. JDeveloper also generates an EAR file which contains the WAR before
deploying to the selected application server connection which you created earlier.
b. Deploy to New Connection...: Launches the Connection Wizard which lets you
create a new OC4J application server connection.
c. Deploy to WAR file: the Web module is packaged as a WAR file and saved to the
14-50
local directory you specified in step 5. Choose this option if you want to deploy to a
production web server running a non-OC4J container. Right-click the <client_war>
profile in the Java client project and choose Deploy to WAR File to generate the
WAR file. You must proceed to install the WAR file on the non-OC4J web server.
d. Deploy to EAR file: the Web module is packaged as an Enterprise Archive (EAR)
file and saved to the local directory you specified in step 3.
Refer to the "Oracle9iAS Containers for J2EE User's Guide" Part Number A95880-01
provided with the Oracle9iAS documentation library for information on the deployed
location of the application files including the WAR and EAR files.
6. (optional) If you want to edit the Web module deployment profile, right-click and choose
Settings...
Notes:
● Make sure that the Web application deployment descriptor is located inside the Web
Application Archive (WAR) file as follows:
WEB-INF/web.xml
Related topics
Running Applications and Applets with Java Web Start in JDeveloper

14-51
Deploying a JClient Web Application Archive for
Java Web Start
You can use JDeveloper's simple J2EE web deployment process to set up the web server
before downloading and running the application using Java Web Start. Before you can deploy
to a production OC4J web server, you must first create a connection to Oracle9iAS Containers
for J2EE (OC4J).
Note: When you want to deploy Business Components to a remote OC4J or VisiBroker web server,
granting security permissions in the JNLP file and signing your JAR files may be necessary to run
the application using Java Web Start. Instructions to sign JAR files is available among the
JDeveloper TechNotes on the Oracle Technology Network (OTN) at:
http://technet.oracle.com/docs/products/jdev/technotes/listing.htm
To deploy JClient web application archive for Java Web Start:
1. Run the JClient Java Web Start Wizard to generate the deployment profiles that describe
your JClient application.
2. Create the business components project and the JClient project before creating your
archive files to ensure you archive the latest source files.
The newly created WAR deployment profile icon appears in the Navigator below the
specified project.
3. Select and right-click the <bc4jlibs.ear> profile in the JClient project and choose Deploy
to set up the context roots in OC4J for the various runtime libraries required by the
JClient application.
4. Select and right-click the <client> profile in the JClient project and choose Deploy to
create a Java Archive in your public.html directory.
5. Select and right-click the <mymt> profile in the JClient project and choose Deploy to
create a simple ZIP archive in your public.html directory.
6. To deploy the archives to OC4J, right-click the <client_war> profile in the JClient project
and choose Deploy to automatically generate the WAR file and deploy the application
components. You must choose a connection to the desired web server. Refer to the
application files including the WAR and EAR files.
Settings...
14-52
To run the JClient application from OC4J using Java Web Start:
2. Open the .html file that the JClient Java Web Start Wizard added to your JClient project
in your web browser.
3. Click the Launch JClient Project link to run your application using the Java Web Start
software.
Note: The next time you run the application, Java Web Start will download only those class
Notes:
WEB-INF/web.xml
Related topics


14-53
14-54
Assembling and Deploying a J2EE Enterprise
Archive (EAR)
Oracle9i JDeveloper lets you build a Web Module deployment profile that can specify EJB
Module dependencies. Thus, when the Web Module is deployed to an Oracle9iAS Containers
for J2EE (OC4J) instance, the EJB JAR files corresponding to the EJB Module dependencies
are also packaged with the WAR file in a single Enterprise Archive (EAR) file that is sent to the
application server instance.
This release of JDeveloper does not have an import facility for an EAR file. If you have an EAR
file that you want to deploy in JDeveloper, you must first import the EJB(s) and WAR(s)
contained in the EAR into individual projects in a single workspace. Then, create an EAR file
which can be deployed to OC4J, as instructed in the steps below.
Some application servers such as Oracle9iAS Containers for J2EE (OC4J) let you deploy a
J2EE application as an EAR file. When you choose the option to Deploy to JAR file or Deploy
to WAR file, JDeveloper packages the individual J2EE module into its specified JAR or WAR
file. You must therefore create the JAR or WAR file first before these packaged forms of the
modules are ready to be assembled into the EAR file.
This assembling task involves choosing which already-packaged J2EE deployment archive
types to include and assemble as part of the EAR fo;e. You can choose to mix and match any
combination of packaged WAR, EJB JAR, and/or client JAR files depending on your specific
J2EE application requirements. When you choose Deploy to <name_of_OC4J_instance> for a
WAR profile or EJB profile, JDeveloper is actually assembling a minimal EAR file automatically
and sending that to specified OC4J. The EAR deployment profile provides you with centralized
control over the process of application assembly.
Note: You must create a connection to an OC4J instance or BEA WebLogic before deploying
the EAR file.
To assemble and deploy a J2EE Enterprise Archive (EAR):

2. Select Deployment Profiles in the Categories list and choose EAR file - J2EE
Application in the Items list.
3. Specify a location for the J2EE EAR deployment profile or accept the defaults.
4. Click Save.
14-55
The J2EE Application Deployment Profile Settings panel displays.
5. The General page displays the default location of the EAR file. You can specify another
location for this file.
6. Enter an Application Name and Description for this EAR file.
7. The Application Assembly page displays all the J2EE modules (WAR and EJB JAR)
currently available and saved in your project. Select the check box next to the module(s)
that you want to assemble and package with the EAR file.
8. Click OK.
9. Select and right-click <EAR_deployment_profile>. The context menu displays these
deployment options:
❍ Deploy to <Name_of_application_server_connection>: the application is
packaged as an Enterprise Archive (EAR) file which contains all the J2EE modules
before deploying to the selected application server connection.
❍ Deploy to EAR file: the application is packaged as an Enterprise Archive (EAR)
file and saved to the local directory you specified in step 5. See About Deploying
on Oracle9i Application Server for information on deploying the EAR file to an
10. (optional) If you want to edit the J2EE application deployment profile, right-click and
choose Settings...
Notes:
● The J2EE application is deployed to the target directory on your application server. For
Oracle9iAS, see OC4J Deployment Application Directory Structure or refer to the
application files including the EAR file.
● The Web Container in OC4J provides full support for Servlets 2.2 and Java Server
● The EJB Container in OC4J provides full support for EJB 1.1 and significant parts of EJB
2.0. For more information about the standard EJB 1.1 Deployment Descriptors, see
Chapter 16 of the specification which you can download from:
14-56
Related Topics
14-57
Deploying Web Applications
JDeveloper lets you create and deploy J2EE web application deployment profiles to various
application servers including OC4J, WebLogic 6.x, and Tomcat:
● Deploying a WAR to OC4J

● Deploying a WAR to WebLogic
● Deploying a Tag Library for JSP 1.1
● Deploying Web Applications to Apache Tomcat
● Deploying a Web Application to Other Application Servers
14-58
Creating and Deploying a J2EE Web Module
Deployment Profile (WAR) to OC4J
A J2EE Web module is packaged as a Web Application Archive (WAR) file which contains one
or more web components (servlets, JSPs) and a deployment descriptor file named web.xml.
JDeveloper lets you create the deployment profile containing the web components and the
deployment descriptor file and packages them into a standard J2EE Enterprise Archive (EAR)
file for deployment. JDeveloper takes the resulting EAR and deploys it to one or more OC4J
instances.
Note: Make sure to create a connection to OC4J before deploying the WAR file.
To create and deploy a J2EE Web Module in JDeveloper:

3. Click OK.
4. Specify a location for the web application's deployment profile or accept the defaults.
The deployment profile is named with a .deploy filename extension.
5. Specify a location for the WAR file and click Save.
6. The J2EE Web Module Deployment Profile panel displays.
a. The General page displays the project's default location of the WAR file and the
EAR file. You can specify other locations for these files.
b. For the Enterprise Application Name, you can inherit the name set in the J2EE
project settings or override it by entering another name in the text field provided.
c. For the Web application's context root field, you can inherit the name set in the
J2EE project settings or override it by entering the application root or virtual path
for the web application files.
d. The WAR File page displays the contents of the current project's HTML Root
Directory. By default the entire HTML Root directory is deployed every time you
generate a WAR file.
e. On the WEB-INF/classes page, you can choose which files to remove from the
packaged WAR file by clearing the appropriate check boxes next to the file(s).
f. Select Automatically include files added to project if you want any new or
additional files in your project to be automatically added to the project and the
14-59
deployment profile.
g. In the How should the selected source files be deployed? list box, choose how
the output file(s) is deployed.
h. The WEB-INF/lib page displays a list of libraries that are in your project's current
active configuration. By default, no libraries are selected since typically you do not
want to repackage a library that already exists in your active configuration.
However, if you do want to repackage the contents of other libraries in your output
WAR file, select the appropriate check boxes.
i. Select the appropriate radio button corresponding to how these libraries will be
used.
j. (optional) Click Applet Options if you want to include an applet in your deployment
profile. See Deploying an Applet as a WAR File.
k. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
dependencies across projects in the same workspace. Select the check box next
to the <name_of_deployment_profile>.deploy you want included with the
deployment.
l. Click OK when you are done.
The newly created WAR deployment profile icon <webapp>.deploy appears in
the Navigator below the specified project.
c. Deploy to WAR file: the Web module is packaged as a WAR file and saved to the
local directory or mapped network drive you specified in step 6.1.
file and deployed to the local directory or mapped network drive you specified in
step 6.1. See About Deploying on Oracle9i Application Server for information on
deploying the EAR file to an Oracle9i Application Server using the Oracle
Enterprise Manager.
Settings...
14-60
Notes:
● The Web module is deployed to the target deployment directory. See OC4J Deployment
Application Directory Structure or refer to the "Oracle9iAS Containers for J2EE User's
Guide" Part Number A95880-01 provided with the Oracle9iAS documentation library for
information on the deployed location of the application files including the WAR and EAR
files.
WEB-INF/web.xml
Related Topics
Deploying a Web Application to Other Application Servers
14-61
A J2EE Web module is packaged as a Web Application Archive (WAR) file which contains one
or more web components (servlets, JSPs) and a deployment descriptor file named web.xml.
JDeveloper lets you create the deployment profile containing the web components and the
deployment descriptor file and packages them into a standard J2EE Web Archive (WAR) file for
deployment.
Note: You must first create a connection to BEA WebLogic before creating the deployment
profile.
To create and deploy a J2EE Web Module in JDeveloper to WebLogic:

3. Click OK.
4. Specify a location for the web application's deployment profile or accept the defaults.
5. Specify a location for the WAR file and click Save.

6. The J2EE Web Module Deployment Profile panel displays.
a. The General page displays the default location of the WAR file and the EAR file.
You can specify other locations for these files.
d. The WAR File page displays the contents of the current project's HTML Root
Directory. By default, the entire HTML Root directory is deployed every time you
generate a WAR file.
e. On the WEB-INF/classes page, you can choose which files to remove from the
packaged WAR file by clearing the appropriate check boxes next to the file(s).
f. Select Automatically include files added to project if you want any new or
additional files in your project to be automatically added to the project and the
deployment profile.
g. In the How should the selected source files be deployed? list box, choose how
14-62
the output file(s) is deployed.
h. The WEB-INF/lib page displays a list of libraries that are in your project's current
active configuration. By default, no libraries are selected since typically you do not
want to repackage a library that already exists in your active configuration.
However, if you do want to repackage the contents of other libraries in your output
WAR file, select the appropriate check boxes.
i. Select the appropriate radio button corresponding to how these libraries will be
used.
j. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
deployment.
k. Click OK when you are done.
The newly created WAR deployment profile icon <webapp>.deploy appears in
WAR. JDeveloper deploys the WAR file to the selected WebLogic application
server connection which you created earlier.
b. Deploy to WAR file: the Web module is packaged as a WAR file and saved to the
local directory or mapped network drive you specified in step 6.1. Or, you can use
the BEA WebLogic Server Console to deploy this WAR file. See your WebLogic
Server documentation for more information.
c. Deploy to EAR file: the Web module is packaged as an Enterprise Archive (EAR)
file and deployed to the selected WebLogic application server. Or, you can use the
BEA WebLogic Server Console to deploy this EAR file. See your WebLogic Server
documentation for more information.
Settings...
Notes:
● The J2EE Web Container in WebLogic provides full support for Servlets 2.3 and Java
Server Pages (JSP) 1.1. For more information, refer to the Sun Microsystems Java
Servlet Specification, Version 2.2 which you can download from:
14-63
WEB-INF/web.xml
Related Topics
BC4J Setup and Deployment Prerequisites for WebLogic Deployment
14-64
In JDeveloper, deploying applets involves creating a J2EE Web Archive (WAR) file. If you want
to create a standalone applet for deployment, you must create an applet deployment profile.
Make sure that you've completed these tasks before deploying an applet:
● Create an Applet
● Create an Applet HTML file (lets you create the applet deployment profile)
● Create an Application Server Connection
Note: If you did not create an applet deployment profile when the Applet HTML file was
created, you can do so as follows:

3. Click OK.
To package an applet for deployment:
1. Below the project, select and right-click the <applet_name> deployment profile
icon and choose Settings...
The J2EE Web Module Deployment Profile Settings panel displays.
2. Click the Applet Options node.
3. Specify the applet deployment path and packaging information as required.
Note: The location for the applet files must correspond to the CODEBASE attribute of
the APPLET tag in the applet HTML file. To verify this information, right-click the applet
HTML icon in the Navigator and choose Code Editor.
4. Click the Applet Classes node.
5. From this page, select or remove files from your project for deployment as an applet.
Also, choose how the source files will be deployed.
6. Click the Applet Archives node.
7. From this page, choose any other libraries that you want to be repackaged with the
applet's J2EE Web Archive (WAR) file.
8. Click OK.
14-65
9. (optional) If you are creating a Web application that also includes servlets and JSPs,
click the other nodes in the J2EE Web Module Deployment Profile panel and edit the
settings as required.
10. Select and right-click the <applet_name> deployment profile icon and choose any of
the available deployment options:
a. Deploy to <Name_of_server_connection>: the applet is packaged as a WAR.
JDeveloper also generates an EAR file which contains the WAR before deploying
to the selected application server connection which you created earlier.
create a new application server connection to OC4J.
c. Deploy to WAR file: the applet is packaged as a WAR file and saved to the path
you specified in step 2.
d. Deploy to EAR file: the applet is packaged as an Enterprise Archive (EAR) file and
saved to the path you specified in step 2.
11. (optional) If you want to edit the applet deployment profile, right-click and choose
Settings...
Notes:
● Make sure that the deployed applet files are in a separate location from any other Web
application files you've deployed.
Related Topics
Debugging an Applet
Running an Applet
Connecting to an EJB from an Applet or Application

14-66
The Tag Library for JSP 1.1 deployment profile lets you build your own tag libraries and deploy
your project as a JAR file that meets the requirements of the tag library specification in JSP 1.1.
You can then use your custom tag library in a web project, for example, that will ultimately be
deployed as a WAR file or passed on to other developers.
To create and deploy a custom tag library for JSP 1.1 in JDeveloper:

2. Select Deployment Profiles in the Categories list and choose Taglib JAR file - Tag
Library for JSP 1.1 in the Items list.
3. Click OK.
4. Specify a location for the tag library deployment profile or accept the defaults.
5. Click Save.
The Tag Library Deployment Profile Settingspanel displays.
13. (optional) Click Profile Dependencies if the deployment profile depends on tag libraries
or simple archives from another deployment profile. JDeveloper supports deployment
profile dependencies across projects in the same workspace. Select the check box next
to the <name_of_deployment_profile>.deploy you want included with the deployment.
14-67
The newly created tag library deployment profile icon appears in the Navigator below
the specified project.

16. Choose the Deploy to option to display the Deploy to Java Archive File (JAR) dialog
from which you can choose the location for the tag libraries. By default, the tag libraries
is deployed in the current project's directory.
17. (optional) If you want to edit the tag libraries deployment profile settings, right-click and
choose Settings...
Notes:
● Make sure that the Web deployment descriptor is located inside the Web Application
Archive (WAR) file as follows:
WEB-INF/web.xml
● Make sure that the Tag Library Descriptor (TLD file) is located inside the tag library JAR
file as follows:
META-INF/taglib.tld
Related Topics
Working with JSP Tag Libraries in JDeveloper
Creating a Custom JSP Tag Library in JDeveloper
14-68
You can use JDeveloper's integrated development environment to create your generic J2EE
JSPs and servlets as well as Business Components for Java (BC4J) Web applications.
JDeveloper supports automatic deployment of your web applications to an Oracle9iAS

Containers for J2EE (OC4J) instance and lets you create a J2EE Web Archive (WAR) file for
deployment to BEA WebLogic 6.x.
However, deploying your J2EE Web applications to the Apache Tomcat 4.0 server involves two
main steps:
● Loading BC4J Runtime Libraries to Apache Tomcat (performed once only)

● Creating a Web Application Archive (WAR) File for Deployment to Apache Tomcat
Loading BC4J Runtime Libraries to Apache Tomcat
You need to perform this step only once, the first time you deploy web applications created in
JDeveloper to Apache Tomcat. For subsequent deployments, perform the steps in the next
section only and restart Tomcat whenever you add a new WAR file.
To load BC4J runtime libraries to Apache Tomcat 4.0:
You must first copy the various JDeveloper runtime libraries, which are in different JDeveloper
directories, to the following location:
<Apache Tomcat 4.0 Home>/lib
1. In <JDEV_HOME>/bc4j/lib, copy the BC4J runtime libraries to <Apache Tomcat

4.0 Home>/lib:
❍ bc4jct.jar
❍ bc4jctejb.jar
❍ bc4jdomorcl.jar
■ Note: If you are using the Oracle type mappings, use bc4jdomorcl.jar.
If the application was built using "Java" type mapping, use

bc4jdomgnrc.jar which is located in <JDEV_HOME>/bc4j/jlib. Only
one of these files is required depending on which mapping type you are
using to build your application.
14-69
❍ bc4jhtml.jar
❍ bc4jimdomains.jar
❍ bc4jmt.jar
❍ bc4jmtejb.jar
❍ bc4juixtags.jar
❍ collections.jar
❍ datatags.jar
❍ uixtags.jar
2. For UIX component support and JDeveloper runtime support, in <JDEV_HOME>/jlib,

copy these files to <Apache Tomcat 4.0 Home>/lib.
❍ jdev-cm.jar
❍ uix2.jar
❍ share.jar
❍ regexp.jar
3. For JDBC database retrieval and character conversion, copy these files from
<JDEV_HOME>/jdbc/lib to <Apache Tomcat 4.0 Home>/lib:
❍ classes12.jar
❍ nls_charset12.jar
4. For interMedia Text (Oracle9i feature for storing, retrieving, and manipulating audio,
document, image, and video data in an Oracle database) support, copy these files from
<JDEV_HOME>/ord/jlib to <Apache Tomcat 4.0 Home>/lib:
❍ ordim.jar
❍ ordhttp.jar
4. For runtime support, copy this file in <JDEV_HOME>/sqlj/lib to <Apache Tomcat

4.0 Home>/lib:
❍ runtime12.jar
5. For XML support, copy the xmlparserv2.jar file in the <JDEV_HOME>/lib to

<Apache Tomcat 4.0 Home>/lib.
6. For runtime support, copy jdev-rt.jar in the <JDEV_HOME>/jdev/lib to <Apache
Tomcat 4.0 Home>/lib.
5. For BC4J web application image and cascading stylesheet support, copy the
14-70
webapp.war file which is located in the <JDEV_HOME>/BC4J/redist to the
following location:
<Apache Tomcat 4.0 Home>/webapps
6. In <JDEV_HOME>/BC4J/redist, copy the cabo.war file which contains the UIX
libraries to <Apache Tomcat 4.0 Home>/webapps.
Creating a Web Application Archive (WAR) file for Deployment to

Tomcat
1. In JDeveloper, make sure that you've created a workspace and a project.

2. Make sure that you've created your Web application (JSP, servlet).
3. (optional) If your Web application is accessing business logic in the Oracle9i database,
make sure that you've created your BC4J project.
Note: For BC4J applications, the the WAR deployment profile is automatically
generated. You can edit any of these settings by right-clicking the WAR deployment
profile icon and choosing Settings... from the context menu. (skip step 4)
4. Create a J2EE Web Module (WAR) deployment profile by choosing File | New.
a. Select Deployment Profiles in the Categories list and choose WAR File - J2EE
Web Module in the Items list.
b. Click OK.
c. Specify a location for the deployment profile and click Save.
d. The J2EE Web Module Deployment Profile panel displays.
i. On the General page, enter a default location for the WAR file. You can
either specify the location of your deployed Web applications directly in the
<Apache Tomcat 4.0 Home>/webapps/<subdirecory>
(recommended) or specify another location.
Keep the default settings for the remaining fields on the General page.
Note: On Tomcat, the system administrator will assign a context path to
your application in the conf/server.xml file. Refer to Apache Tomcat
ii. Click OK when you are done.
iii. Locate the newly created WAR deployment profile icon which appears in
5. Select and right-click the WAR deployment profile icon and choose Deploy to WAR
file from the context menu.
14-71
6. (optional) If you specified <Apache Tomcat 4.0 Home>/webapps path in step 4, you
can skip this step as the generated Web application files are deployed directly.
Otherwise, you'll have to copy the unpacked directory hierarchy into a subdirectory below
<Apache Tomcat 4.0 Home>/webapps.
7. Stop Tomcat.
8. Restart Tomcat for all changes to take effect.
9. When Tomcat is started, it will automatically expand the Web application archive file, and
execute the application in your browser.
Notes:
● If you require further assistance for any field on any page in JDeveloper, click Help.
● For more information about Apache Tomcat, see
http://jakarta.apache.org/tomcat/index.html
WEB-INF/web.xml
Related Topics

14-72
Deploying a Web Application to Other Application
Servers
If you are not deploying to either of the supported application servers (OC4J or BEA WebLogic
6.x), you can still deploy the generated WAR to another J2EE application server by specifying
the target server location. However, this target server must be installed locally or mapped to a
network drive.
If you want to deploy the Web Archive (WAR) or Enterprise Archive (EAR) file to a remote
target server, you must manually copy the the WAR or EAR file to the appropriate deployment
location on the target server. The standard J2EE location would be the /WEB-INF directory on
the target server but this varies depending on the application server. Please refer to your
particular application server's documentation for this information.
To deploy a Web application to other application servers:
1. Once you've created your J2EE Web Module deployment profile using JDeveloper,
select and right-click right-click <web_app_name> from the Navigator.
2. Choose Settings...
3. Click the General node in the left frame.
4. In the WAR file field, specify the deployment location for your Web application's WAR file
on your target server.
5. In the EAR file field, specify the deployment location for the Web application's EAR file
on your target server.
6. Click OK.
7. Right-click <web_app_name>.
8. Choose the appropriate deployment option from the context menu:
a. Deploy to WAR file: the Web module is packaged as a WAR file and saved to the
local directory or mapped network drive you specified in step 4.
b. Deploy to EAR file: the Web module is packaged as an Enterprise Archive (EAR)
file and saved to the local directory or mapped network drive you specified in step
5.
Refer to your specific application server's documentation for additional deployment details.
14-73
Related Topics
Creating and Deploying a J2EE Enterprise Archive (EAR) to OC4J
14-74
Deploying EJB JARs
JDeveloper lets you create and deploy Enterprise JavaBeans (EJBs) deployment profiles to
various application servers including OC4J and WebLogic 6.x:
● Deploying an EJB JAR to OC4J

● Deploying an EJB JAR to WebLogic
● Deploying EJBs Built on SQLJ Files
● Customizing the EJB Descriptors for OC4J Deployment (orion-ejb-jar.xml)
● Customizing the EJB Descriptors for WebLogic Deployment (weblogic-ejb-jar.xml)
14-75
Creating and Deploying a J2EE EJB Module (EJB
JAR) to OC4J
A J2EE EJB module is packaged as an EJB JAR file which contains one or more EJB
components and two EJB deployment descriptor files named ejb-jar.xml and orion-ejb-
jar.xml. JDeveloper lets you create the deployment profile containing the EJB components
and these deployment descriptor files and packages them into a standard J2EE EJB JAR
archive for deployment.
Note: You must create a server connection to OC4J before deploying the EJB JAR file.
To create and deploy a J2EE EJB JAR file in JDeveloper to OC4J:

2. Select Deployment Profiles in the Categories list and choose EJB JAR file - J2EE EJB
3. Click OK.
4. Specify a location for the EJB deployment profile or accept the defaults.
5. Specify a location for the EJB JAR file and click Save.
6. The J2EE EJB Module Deployment Descriptor panel appears.
a. The General page displays the default location of the EJB JAR file and the EAR
file. You can specify other locations for these files.
b. In the Files page, choose which files you want packaged in the archive.
c. In the Dependency Analyzer page, the check box tree displays the list of libraries
that are in your project's current active configuration. If you want to repackage the
contents of other libraries in your output JAR file, select the appropriate check
boxes.
d. Select the appropriate radio button corresponding to how the libraries will be used.
e. (advanced) If you require further refinement to the Dependency Analyzer settings,
click Filters on the tree to the left of this panel. Setting filters is not required for a
typical deployment.
f. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
modules from another deployment profile.JDeveloper supports deployment profile
14-76
deployment.
g. Click OK.
The newly created EJB deployment profile icon appears in the Navigator pane
7. Select and right-click the <ejb_name> deployment profile icon and choose any of the
available deployment options:
a. Deploy to <Name_of_server_connection>: the EJB is packaged as an EJB JAR.
JDeveloper also generates an EAR file which contains the EJB JAR before
Refer to the "Oracle9iAS Containers for J2EE User's Guide" Part Number A95880-
01 provided with the Oracle9iAS documentation library for information on the
deployed location of the application files including the EJB JAR and EAR files.
c. Deploy to JAR file: the EJB module is packaged as an EJB JAR file and saved to
the local directory or mapped network drive which you specified in step 6.1.
d. Deploy to EAR file: the EJB module is packaged as an Enterprise Archive (EAR)
6.1. See About Deploying on Oracle9i Application Server for information on
deploying the EAR file to an Oracle9i Application Server using the Oracle
Enterprise Manager.
8. (optional) If you want to edit the EJB module deployment profile, right-click the EJB
deployment profile and choose Settings...
Notes:
● The EJB Container in Oracle9iAS provides full support for EJB 1.1 and significant parts
of EJB 2.0. For more information about the standard EJB 1.1 Deployment Descriptors,
see Chapter 16 of the specification which you can download from:
● Make sure that the EJB deployment descriptor is located inside the EJB JAR as follows:
META-INF/ejb-jar.xml
14-77
Related Topics
Sample Business Components EJB Command-line Client Deployed to OC4J
Running an EJB
Debugging an EJB
14-78
A J2EE EJB module deployed to a BEA WebLogic server is packaged as an EJB JAR file
which contains one or more EJB components and two EJB deployment descriptor files named
ejb-jar.xml and weblogic-ejb-jar.xml. JDeveloper lets you create the deployment
profile containing the EJB components and these deployment descriptor files and packages
them into a standard J2EE EJB JAR archive for deployment to WebLogic.
Note: You must create an application server connection to BEA WebLogic before deploying the
EJB JAR file.
To create and deploy a J2EE EJB JAR file in JDeveloper to WebLogic:
1. After you create your EJB with JDeveloper, both the ejb-jar.xml and orion-ejb-
jar.xml files are automatically generated for you. They appear in the Navigator below
your project.
Note: You can ignore the orion-ejb-jar.xml file since this is only used for an
Oracle9iAS Containers for J2EE (OC4J) deployment.
3. Select Deployment Profiles in the Categories list and choose EJB JAR file - J2EE EJB
4. Click OK.
b. In the Files page, choose which files you want packaged in the archive.
c. In the Dependency Analyzer page, the check box tree displays the list of libraries
boxes.
d. Select the appropriate radio button corresponding to how the libraries will be used.
e. (advanced) If you require further refinement to the Dependency Analyzer settings,
click Filters on the tree to the left of this panel. Setting filters is not required for a
typical deployment.
14-79
f. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
deployment.
g. Click OK.
The newly created EJB deployment profile icon appears in the Navigator below
8. Create the weblogic-ejb-jar.xml file by choosing File | New ... | Enterprise

JavaBeans | WebLogic EJB Descriptor (weblogic-ejb-jar.xml).
Note: Or, this file is automatically generated later when you actually deploy to an existing
WebLogic connection.
9. (optional) If you want to edit the weblogic-ejb-jar.xml file, right-click its icon in the
Navigator and choose Settings... Otherwise, the first generated version will be deployed.
Note: If changes are made to the weblogic-ejb-jar.xml file, you'll need to include
this updated version in the EJB JAR before redeploying. See Customizing the EJB
Descriptors for WebLogic Deployment (weblogic-ejb-jar.xml) for more information.
a. Deploy to <Name_of_server_connection>: the EJB is packaged as an EJB JAR
and deploys it to the selected application server connection which you created
earlier.
create a new WebLogic application server connection.
c. Deploy to JAR file: the EJB module is packaged as an EJB JAR file and saved to
the local directory or mapped network drive you specified in step 7.1. Use the BEA
WebLogic Server Console to deploy this EJB JAR file. See your WebLogic Server
Notes:
● For more information about the standard EJB 1.1 Deployment Descriptors, see Chapter
16 of the specification which you can download from:
14-80
For clients that access EJBs on the WebLogic server, the following code is required in the
client:
env.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "system");
env.put(Context.SECURITY_CREDENTIALS, "welcome1");
env.put(Context.PROVIDER_URL, "t3://localhost:7001");
Related Topics
Running an EJB
Debugging an EJB
Sample Client Code for an EJB Client for WebLogic
14-81
Deploying EJBs Built on SQLJ Files
If you have an EJB that is built on a SQLJ file, you must add two libraries to the deployment
profile.
To add SQLJ libraries to the deployment profile:
1. In the Navigator, right-click your existing <ejb_name> deployment profile icon and
choose Settings.
b. In the Dependency Analyzer page, the check box tree displays the list of libraries
boxes.
c. Select the appropriate radio button corresponding to how the libraries will be used.
d. (advanced) If you require further refinement to the Dependency Analyzer settings,
click Filters on the tree to the left of this panel.
e. In the right pane, choose 1) Before Dependency Analysis and click Add.
f. In the Add Dependency Analyzer Filter dialog box, in the Type dropdown list,
choose Include Package Tree.
g. Click Browse... and navigate to your project's package. Select the common.*
libraries and click OK.
h. Similarly, add the server.* packages from your project.
i. Click OK.
The modified EJB deployment profile icon appears in the Navigator pane below
Refer to the "Oracle9iAS Containers for J2EE User's Guide" Part Number A95880-
01 provided with the Oracle9iAS documentation library for information on the
14-82
a. Deploy to New Connection...: Launches the Connection Wizard which lets you
b. Deploy to JAR file: the EJB module is packaged as an EJB JAR file and saved to
the local directory you specified in step 6a.
c. Deploy to EAR file: the EJB module is packaged as an Enterprise Archive (EAR)
file and saved to the local directory you specified in step 2a. See About Deploying
on Oracle9i Application Server for information on deploying the EAR file to an
Notes:
● The EJB Container in OC4J provides full support for EJB 1.1 and significant parts of EJB
2.0. For more information about the standard EJB 1.1 Deployment Descriptors, see
Chapter 16 of the specification which you can download from:
Related Topics
Running an EJB
14-83
Debugging an EJB
14-84
Customizing the EJB Descriptors for OC4J
Deployment (orion-ejb-jar.xml)
The J2EE application deployment information is contained within XML configuration files. Each
application type has its own configuration files. For an EJB JAR file deployed to Oracle9iAS
Containers for J2EE (OC4J), two deployment descriptors are generated and used to define the
EJB deployment descriptors:
ejb-jar.xml
Represents the standard J2EE EJB JAR deployment descriptor defined by Sun
Microsystems. For more information about the standard EJB 1.1 Deployment
Descriptors, see Chapter 16 of the specification which you can download from:
orion-ejb-jar.xml
Represents the OC4J platform-specific deployment descriptors for EJBs and contains
the deploy time information for an EJB JAR deployed to Oracle9iAS. If you have
implementation-specific information, you can supplement the ejb-jar.xml with the
orion-ejb-jar.xml file. This file is used to specify the initial deployment properties.
After each deployment in JDeveloper, this deployment file is altered to reflect any newly
added deployment descriptor information.
The orion-ejb-jar.xml file contains the following settings:
❍ Time-out settings
❍ Transaction retry settings

❍ Session persistence settings
❍ Transcation isolation settings
❍ CMP mappings
❍ OR mappings
❍ Finder method specifications
❍ JNDI mappings
The orion-ejb-jar.dtd is contained in oc4j.jar. After you decompress this JAR, all
DTDs for the OC4J server files are located in the Meta-inf directory.
To customize the EJB descriptors for OC4J deployment (orion-ejb-jar.xml):
14-85
your project.
2. If you want to edit any of the standard J2EE deployment descriptors, select ejb.jar.xml
and choose Settings... .
3. Modify any of the settings on this panel and click OK when you are finished.
4. If you want to edit any of the OC4J platform-specific deployment descriptors, select
orion-ejb.jar.xml and choose Settings...
6. When your EJB JAR module is deployed to a remote OC4J, both of these deployment
descriptors are included in your <ejb-jar>.ear file.
Note: For a local deployment to the embedded OC4J server, these deployment
descriptors and the resulting classes are reside in the embedded OC4J location.
7. Click Help on any deployment descriptor page for more information.
Related Topics

14-86
Customizing the EJB Descriptors for WebLogic
Deployment (weblogic-ejb-jar.xml)
The J2EE application deployment information is contained within XML configuration files. Each
application type has its own configuration files. For an EJB JAR file deployed to BEA WebLogic
6.x, two deployment descriptors are generated and used to define the EJB deployment
descriptors:
ejb-jar.xml
Represents the standard J2EE EJB JAR deployment descriptor defined by Sun
Microsystems. For more information about the standard EJB 1.1 Deployment
Descriptors, see Chapter 16 of the specification which you can download from:
weblogic-ejb-jar.xml
When packaging your J2EE application for deployment to a BEA WebLogic 6.x
application server, you can also customize the deployment descriptors to include
additional platform-specific deployment settings.
For detailed descriptions on the WebLogic platform-specific deployment descriptor
elements in the weblogic-ejb-jar.xml file, please refer to the current
documentation for WebLogic Server 6.1. The "Programming WebLogic Enterprise
JavaBeans WebLogic" documentation which contains this information is currently located
at:
http://edocs.beasys.com/wls/docs61/ejb/reference.html
To customize the EJB descriptors for WebLogic deployment (weblogic-ejb-jar.xml):
your project. The weblogic-ejb-jar.xml file is created when you choose File |
New... | Enterprise JavaBeans | WebLogic EJB Descriptor (weblogic-ejb-jar.xml) or
when you attempt to deploy to an existing WebLogic connection.
2. If you want to edit any of the standard J2EE deployment descriptors, select ejb.jar.xml
and choose Settings...
4. If you want to edit any of the WebLogic platform-specific deployment descriptors, select
14-87
weblogic-ejb.jar.xml and choose Settings...
6. When your EJB JAR module is deployed to a WebLogic instance, both of these
deployment descriptors are included in your <weblogic_ejb_jar>.ear file.
7. Click Help on any deployment descriptor page for more information.
Important: Whenever you edit the weblogic-ejb-jar.xml file, make sure to include the
updated version of this file in the EJB JAR file you are deploying to your application server.
Related Topics

14-88
About Business Components for Java (BC4J)
Deployment
JDeveloper lets you deploy Business Components for Java in the following ways:
● Deploying Business Components for Java as a Simple Archive

● Deploying JClient and BC4J as a Simple Archive
● Deploying a BC4J Web Application to OC4J
● Deploying a BC4J Web Application to WebLogic
● Deploying BC4J Web Applications to Apache Tomcat
● Deploying BC4J as an EJB Session Bean to OC4J
● Deploying BC4J as an EJB Session Bean to WebLogic
● Starting a CORBA Server Object on a VisiBroker Server
Deploying business components involves three main steps which you must perform:
1. Perform all BC4J prerequisites.

2. Create the deployment profile.
3. Deploy from the deployment profile.
When business components are deployed as a J2EE Web module, the business components
are packaged as a Web Application Archive (WAR) file which the client code can access.
Deploying as a J2EE Web module is especially suited to client code, such as JavaServer
Pages and servlets, that run on fast, shared machines.
When business components are deployed as a CORBA server object or an EJB session bean,
the business components run in a separate tier (middle-tier) from the client programs. For
example, the CORBA object runs on the VisiBroker server and the EJB session bean runs on
an EJB server such as Oracle9iAS.
At deployment time, the application module must be made available (remoteable) to the client
code. This means creating an EJB remote interface and/or client-side proxies for application
module methods which must be deployed to the client platform. For more information, see:
14-89
● Sample Client Code for an EJB Client Deployed to OC4J
● Sample Client Code for an EJB Client Deployed to WebLogic
With JDeveloper, you can make the application module available (remoteable) from two places:
● From the Application Module Remote tab (selecting the Remoteable Application Module
check box)
● From the Business Components Deployment Profile Wizard - Step 2 (Select
AppModules to Support the Selected Platform)
Notes:
● See Understanding the n-Tiered Business Components Architecture for more

information.
● JDeveloper lets you deploy your J2EE applications to the embedded Oracle9iAS
Containers for J2EE (OC4J) in JDeveloper or to a standalone OC4J instance. See About
Deploying on Oracle9i Application Server for information on deploying to an Oracle9i
Application Server using the Oracle Enterprise Manager.
Related Topics

About BC4J Configuration Properties
14-90
BC4J Deployment Prerequisites for OC4J
Deployment
Before deploying a BC4J project, make sure that you have met the following deployment
prerequisites:
Step 1: Start OC4J
JDeveloper includes an embedded OC4J server which is automatically started when you run,
debug, profile, CodeCoach, and locally deploy your applications without having to deploy to a
remote OC4J instance. See the Help topics related to the embedded OC4J server for more
information.
Refer to the OC4J Readme.txt and the "Oracle9iAS Containers for J2EE User's Guide"
Release 2.0 (Part Number A95880-01) provided with the Oracle9iAS documentation library for
important information, including installation instructions and how to configure JDBC data
sources in Oracle9iAS Containers for J2EE.
To start OC4J from the command line using the start command:
java -jar oc4j.jar
Step 2: Create an application server connection(s)
Create a connection to Oracle9iAS Containers for J2EE (OC4J).
Step 3: Create a Business Components for Java project
You'll need to create a BC4J project using the Business Components Package Wizard.
Step 4: Define Business Component Runtime Properties for Web Applications
For web application deployments, make sure that the server connection information to connect
to deployed business components is properly configured in the bc4j.xcfg file. This file
defines all of the deployment configurations of a particular application module in the business
components project and permits data tags and data web beans to access a specific view object
belonging to the application module.
See About BC4J Configuration Properties and Defining Business Component Runtime
14-91
Properties in the bc4j.xcfg File for Web Applications for more information.
Step 5: Deploy bc4j.ear to OC4J
When deploying BC4J web applications, make sure that the bc4j.ear file is deployed to OC4J.
This file contains the required web application and UIX files required for deployment. You only
need to perform this task one time (not every time a BC4J web application is deployed).
In the Navigator, right-click bc4j.ear on the Navigator (below

<projectname_jpr_War.deploy>) and choose Deploy to <application_server_connection>.
Related Topics

Deploying Business Components for Java as a Simple Archive
Deploying JClient and BC4J as a Simple Archive
14-92
Loading BC4J Runtime Libraries to OC4J
The following is a list of Business Components for Java (BC4J) runtime libraries which must
exist on your application server before you deploy any Business Components for Java (BC4J)
applications. If you are deploying to Oracle9i Application Server Release 2.0, these runtime
libraries are installed with the server.
● bc4jct.jar
● bc4jctejb.jar
● bc4jdomorcl.jar
❍ Note: If you are using the Oracle type mappings, use bc4jdomorcl.jar. If the
application was built using "Java" type mapping, use bc4jdomgnrc.jar which is
located in <JDEV_HOME>/bc4j/jlib. Only one of these files is required
depending on which mapping type you are using to build your application.
● bc4jhtml.jar
● bc4jimdomains.jar
● bc4jmt.jar
● bc4jmtejb.jar
● bc4juixtags.jar
● collections.jar
● datatags.jar
● uixtags.jar
Note: The embedded OC4J server's application.xml file contains a listing of the J2EE
application runtime files and sets the classpath to these files. You can find application.xml
in your JDeveloper installation directory at:
<JDEV_HOME>/j2ee/home/config
For UIX component support and JDeveloper runtime support, these files are also installed on
OC4J.
● jdev-rt.jar
● jdev-cm.jar
● uix2.jar
14-93
● share.jar
● regexp.jar
Other Required Files
Oracle9iAS should also have the following files already installed for successful BC4J
deployment:
● jdev-cm.jar
● nls_charset12.jar
● xmlparserv2.jar
interMedia Text
If you are using interMedia Text (Oracle9i feature for storing, retrieving, and manipulating
audio, document, image, and video data in an Oracle database), you would also require the
following files which are located in the following directories:
● <JDEV_HOME>/ord/jlib
❍ ordim.jar
❍ ordhttp.jar
● <JDEV_HOME>/sqlj/lib
❍ runtime12.jar
Copying BC4J Runtime Libraries to OC4J for Web Application

Deployment
If your OC4J server is not using the embedded OC4J server which is included with JDeveloper
or if your OC4J server does not seem to have the Business Components for Java framework
14-94
installed, you can set up your OC4J server with the BC4J runtime libraries. You require a
complete JDeveloper installation which includes these libraries and which you will copy to the
target OC4J server. OC4J is installed in the <OC4J_HOME>/j2ee/home directory or the "OC4J
Home".
To deploy BC4J web applications to an OC4J server not running JDeveloper:
1. From an existing JDeveloper installation, copy the entire <JDev_Home> directory tree to
your target OC4J server machine.
Note: If you do not plan to use the JDeveloper IDE on your server machine, you can omit
the <JDev_Home>/jdev directory and its subdirectories.
2. Copy the application.xml file from the JDeveloper j2ee\home\config directory to
the <OC4J_HOME>\j2ee\home\config directory. This file contains a listing of the
JDeveloper runtime files and sets the classpath for all of these files.
3. In JDeveloper, make sure that you created an OC4J server connection that successfully
connects to your target (external) OC4J 2.0 server. For example, this connection can be
named "MyExternalOC4J."
4. In JDeveloper, select bc4j.ear in the Navigator and deploy it to the target OC4J server
by choosing Deploy to <target_OC4J_server> from the context menu.
Note: The bc4j.ear contains support for the BC4J web application image and
cascading stylesheet and UIX libraries. You can also find the bc4j.ear file in
<JDev_Home>\BC4J\redist directory.
5. Add the BC4J Web dependencies to your web application's WAR file:
1. Select the <MyProject_jar_War>.deploy deployment profile in the Navigator and
choose Settings... from the context menu.
2. Click WEB-INF/lib to display a list of libraries that are in your project's current
active configuration.
3. Click the following groups of dependencies to add them to your WAR file:
1. BC4J Runtime
2. Oracle Intermedia
3. Connection Manager
4. BC4J Oracle Domains

deployment.
14-95
6. Select the deployment profile and choose Deploy to <target_OC4J_server> from the
context menu.
7. If necessary, start the OC4J application server with the following command:
% Java -jar oc4j.jar <options>
8. Point your browser at your external OC4J server and try your application.
Note:
● In Oracle9iAS, the Oracle HTTP Server communicates with its own embedded OC4J to
deliver J2EE applications to Oracle9iAS. In this case, rather than deploying directly to
OC4J, your system administrator would use the Oracle Enterprise Manager to deploy the
J2EE Enterprise Archive (EAR) file which was generated in JDeveloper. Specifically, the
Oracle Enterprise Manager Web site provides a process for deploying new applications
into an OC4J server using the OC4J Enterprise Manager Home Page. You can also use
the OC4J Home Page for high-availability, clustering, and other services.
For more information on Oracle9iAS administration, management, and deployment of

J2EE applications to OC4J using the Oracle Enterprise Manager Web site, refer to the
"Oracle9i Application Server Administrator's Guide" Release 2 (9.0.2) Part Number
A92171-01, which is provided with the Oracle9iAS documentation library.
Related Topics

14-96
BC4J Setup and Deployment Prerequisites for
WebLogic Deployment
Before deploying a BC4J project to WebLogic, make sure that you have met the following setup and
deployment prerequisites:
● Setup Prerequites
● Deployment Prerequisites
Setup Prerequisites
Step 1: Verify that all BC4J Runtime libraries are installed
Ensure that the BC4J runtime libraries are installed on WebLogic.
application runtime files and sets the classpath to these files. These files are also located in your
JDeveloper installation directory in:
<JDEV_HOME>/bc4j/lib
Step 2: Define JDBC Data Sources
Define your JDBC data sources for distributed transactions on WebLogic. For more information, see
the "WebLogic Server 6.1 Administration Guide" which can be found at:
http://e-docs.bea.com">http://e-docs.bea.com
Step 3: Start the WebLogic Application Server
Your BEA WebLogic 6.x server must be started before you attempt to deploy J2EE modules. The
following is a start WebLogic command script that may help you to run the server:
:runWebLogic
echo on
set PATH=.\bin;%PATH%
set ORACLE_HOME=k:
14-97
set BC4J_LIB=%ORACLE_HOME%\bc4j\lib
set DOMAIN_JAR=%BC4J_LIB%\bc4jdomgnrc.jar
set BC4J_JARS=%BC4J_LIB%\bc4jmt.jar;%BC4J_LIB%\bc4jmtejb.jar;%BC4J_LIB%\collections.jar
set BC4J_JARS=%BC4J_JARS%;%DOMAIN_JAR%
set
OTHER_JARS=%ORACLE_HOME%\lib\xmlparserv2.jar;%ORACLE_HOME%\jdbc\lib\classes12.jar
set ORACLE_CLASSPATH=%BC4j_JARS%;%OTHER_JARS%
set JBO_JAVA_OPTS=-Djbo.debugoutput=console -Djbo.use.pers.coll=false -

Djbo.SQLBuilder=SQL92
set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar;%ORACLE_CLASSPATH%
echo off
echo.
echo ***************************************************
echo * To start WebLogic Server, use the password *
echo * assigned to the system user. The system *
echo * username and password must also be used to *
echo * access the WebLogic Server console from a web *
echo * browser. *
echo ***************************************************
Deployment Prerequisites
Step 1: Create an application server connection(s)
Create an application server connection to BEA WebLogic 6.x. When you do this, you specify the
location of the weblogic.jar file in your WebLogic installation directory.
Step 2: Create a Business Components for Java project
You'll need to create a BC4J project using the Business Components Package Wizard.
Step 4: Define Business Component Runtime Properties for Web Applications
For web application deployments, make sure that the server connection information to connect to
deployed business components is properly configured in the bc4j.xcfg file. This file defines all of
the deployment configurations of a particular application module in the business components project
and permits data tags and data web beans to access a specific view object belonging to the
application module.
14-98
See About BC4J Configuration Properties and Defining Business Component Runtime Properties in
the bc4j.xcfg File for Web Applications for more information.
Step 5: Deploy bc4j.ear to WebLogic
When deploying BC4J web application applications, make sure that the bc4j.ear file is deployed to
your WebLogic application server. This file contains the required web application and UIX files
required for deployment. You only need to perform this task one time (not every time a BC4J web
application is deployed).
In the Navigator, right-click bc4j.ear on the Navigator (below <projectname_jpr_War.deploy>)

and choose Deploy to <WebLogic_application_server_connection>.
Related Topics

Creating a Connection to BEA WebLogic
Deploying BC4J Web Applications to Apache Tomcat
14-99
You can use JDeveloper's integrated development environment to create your generic J2EE
JSPs and servlets as well as Business Components for Java (BC4J) Web applications.
JDeveloper supports automatic deployment of your Web applications to Oracle9iAS Containers
for J2EE (OC4J). You can use the WebLogic Server Console to deploy the generated WAR or
EAR files to the BEA WebLogic 6.x application server.
If you are not using a WebLogic startup script to load the necessary BC4J libraries from your
classpath, you'll need to load these libraries manually as follows.
To load the BC4J runtime libraries to WebLogic 6.x:
You must first copy the various JDeveloper runtime libraries, which are in different JDeveloper
directories, to the following location:
<BEA_HOME>/wlserver6.1/lib
1. In <JDEV_HOME>/bc4j/lib, copy the BC4J runtime libraries to <BEA_HOME>/lib:

❍ bc4jct.jar
❍ bc4jctejb.jar
❍ bc4jdomorcl.jar
■ Note: If you are using the Oracle type mappings, use bc4jdomorcl.jar.
If the application was built using "Java" type mapping, use

bc4jdomgnrc.jar which is located in <JDEV_HOME>/bc4j/jlib. Only
one of these files is required depending on which mapping type you are
using to build your application.
❍ bc4jhtml.jar
❍ bc4jmt.jar
❍ bc4jmtejb.jar
❍ bc4juixtags.jar
❍ collections.jar
❍ datatags.jar
❍ uixtags.jar
2. For UIX component support and JDeveloper runtime support, in <JDEV_HOME>/jlib,
14-100
copy these files to <BEA_HOME>/lib.
❍ jdev-cm.jar
❍ uix2.jar
❍ share.jar
❍ regexp.jar
3. For JDBC database retrieval and character conversion, copy these files from
<JDEV_HOME>/jdbc/lib to <BEA_HOME>/lib:
❍ classes12.jar
❍ nls_charset12.jar
3. For interMedia Text (Oracle9i feature for storing, retrieving, and manipulating audio,
document, image, and video data in an Oracle database) support, copy these files from
<JDEV_HOME>/ord/jlib to <BEA_HOME>/lib:
❍ ordim.jar
❍ ordhttp.jar
4. For runtime support, copy this file in <JDEV_HOME>/sqlj/lib to <BEA_HOME>/lib:

❍ runtime12.jar
5. For XML support, copy this file in <JDEV_HOME>/lib to <BEA_HOME>/lib:

❍ xmlparserv2.jar
6. For runtime support, copy jdev-rt.jar in the <JDEV_HOME>/jdev/lib to

<BEA_HOME>/lib.
7. In <JDEV_HOME>/BC4J/redist, copy the cabo.war file which contains the UIX
libraries to <BEA_HOME>/lib.
application runtime files and sets the classpath to these files. You can find application.xml
in your JDeveloper installation directory at <JDEV_HOME>/j2ee/home/config.
Related Topics
14-101
Deploying BC4J Web Applications to Apache Tomcat
14-102
Deploying Business Components for Java as a
Simple Archive File
Before deploying a Business Components for Java project, you must have already created a
project with business components using the Business Components Package Wizard.
The BC4J deployment process involves three main steps: copying the Business Components
runtime libaries to OC4J or WebLogic, building a deployment profile, and deploying using the
deployment profile.
The JDeveloper deployment profile wizards create all the necessary code to deploy business
components to a simple archive.
To deploy Business Components for Java as a simple archive file:
1. Make sure that you've completed all the BC4J prerequisites.

2. With a Business Components for Java project selected in the JDeveloper Navigator
pane, right-click and choose Deploy... to display the Business Components Deployment
Wizard.
Note: You can also display the Business Components Deployment Wizard by choosing
File | New...Select Deployment Profiles in the Categorieslist and choose Simple Archive
Files in the Itemslist.
3. This wizard guides you in the creation of business components deployment profile
type(s). Click Next.
4. Choose Simple Archive Files from the Available list and use the move button to shuttle it
to the Selected list.
5. Click Next.
6. In the Profile Name field, enter or browse to the full path and name for this deployment
profile.
Note: The BC4J deployment descriptor file should be named with a .bcdeployfilename
extension.
7. Select the Deploy check box.

8. You'll see a listing of the selected deployment profile(s).
Click Finishwhen you are done.
9. The deployment profile for the simple archive is created. The Business Components
deployment profile icon <ProjectName>.bcdeploy appears in the Navigator below your
14-103
project.
10. Click + to expand this icon and to display the subprofiles:

<ProjectNameMiddleTier>.deploy: contains the class and XML files
<ProjectNameCommon>.deploy:files shared between Oracle9iAS and the client
11. (optional) You can right-click on any of these subprofile icons to perform a variety of
tasks including: display deployment profile settings, deploy to a Java Archive file,
Preview, and so on.
Related Topics

Deploying a Simple Archive to Your File System
14-104
Deploying a JClient application and Business Components for Java (BC4J) as a simple archive
is supported in Oracle9i JDeveloper. To do this, you would create a single JAR file containing
both your business component for Java logic and the client application files.
To deploy JClient and BC4J as a simple archive:
1. Make sure that a database connection to the data source exists.

Note: In the Database Connection Wizard - Step 2 of 4: Authentication, the Deploy
Password check box must have been selected.
2. Create a Business Components project using the Business Components Package
Wizard.
3. In a new project, create a JClient application in JDeveloper.
4. With the JClient project selected in the JDeveloper Navigator, right-click

<client_project_name> and choose New... to display the New Object dialog.
5. Select Deployment Profiles in the Categories list and choose Simple Archive in the
Items list.
6. Click OK.
profile.
Note: The deployment profile is named with a .deployfilename extension.
8. Click Save.
The Simple Archive Deployment Profile Settingspanel displays.
9. In the Files page, choose which files you want packaged in the archive. Normally, all files
in your JClient project should be selected.
11. On the How should the selected source files be deployed? list box, choose how the
12. On the JAR Options page, specify additional parameters for the JAR file and select
Include Manifest File. Be sure to enter the fully qualified location of the Main Class. For
example, package2.FrameDepartmentsViewEmployeesView2.
13. On the Dependency Analyzer page, the check box tree displays the list of libraries that
are in your project's current active configuration. For this deployment, you want to
repackage the contents of other libraries in your output JAR file to include the required
14-105
libraries.
Select the check boxes next to the following libraries:
❍ Business Components libraries: select the Workspace<projectname> and
classes
❍ Oracle JDBC: classes12.zip and nls_charset12.jar
❍ Connection Manager: jdev-cm.jar
❍ JClient Runtime: bc4jui.jar
❍ Oracle XMLParser v2: xmlparserv2.jar
❍ JDeveloper Runtime: jdev-rt.jar
❍ BC4J Runtime: select all files in this library (excluding those you've already
selected)
Note: If you are using Oracle InterMedia in your client application, you must also
select the Oracle Intermedia library from this list.
14. Select the Include all of their contents in the output radio button so that the entire
contents in the selected libraries are included in the output JAR.
The newly created simple archive deployment profile icon appears in the Navigator

19. Choose the Deploy to option to display the Deploy to Java Archive File (JAR) dialog box
from which you can choose the location for the simple archive. By default, the simple
archive is deployed in the current project's directory.
20. (optional) If you want to edit the simple archive deployment profile settings, right-click
and choose Settings...
21. To test your client application, run the application from the JDeveloper's installation
directory at the following location:
<JDEV_HOME>/jdk1.3/bin/jdk1.3/bin
The command to run is as follows:
14-106
java -jar <name_of_application.jar>
If successful, the JClient application should run.
Notes:
● If you want to install the client application on another machine(s), be sure to install JDK
1.3 in the jdk1.3\bin directory.
● To see a listing of the files contained in the JAR file, right-click the simple archive
deployment profile and choose Preview from the context menu.
Related Topics
Creating and Deploying a Simple Archive to Your File System

14-107
Testing a Deployed J2EE Module with the Business
Components Browser
After you've deployed your J2EE module, you can test it using either the Business Components
browser or a custom code client.
Testing using the Business Components browser:
1. In the Navigator, right-click the Business Component's application module icon and
choose Test.
2. The Oracle Business Component Browser - Connect dialog appears.
Enter the required information including the Middle Tier Server Type: Local, VisiBroker,
and Oracle9iAS EJB.
3. Enter the connection information and the the location of your application module.
4. Click Connect.
5. The Oracle Business Component Browser is displayed from which you can test the
deployed application module.
You can also create additional Application Modules, View Objects, and View Links from
this browser.
Related Topics

14-108
When creating a BC4J web application using JDeveloper, a J2EE Web Module (WAR file) is
generated containing both the Business Components for Java (BC4J) and the web application
files. The JDeveloper deployment profile wizards create all the necessary code to deploy
business components as a Web module to the embedded OC4J server or to a standalone
OC4J instance. Typically, a JSP client accesses the BC4J application in a J2EE Web Module
configuration. The JSP client can also include data tags, data web beans, XSQL, tag libraries,
and UIX tags to access the business components.
Important: Before deploying your BC4J web application, ensure that you've met all the
prerequisites including creating an OC4J server connection before deployment and defining
server connection information to the deployed business components in the bc4j.xcfg file.
This file defines all of the deployment configurations of a particular application module in the
business components project and permits data tags and data web beans to access a specific
view object belonging to the application module.
See About Deploying on Oracle9i Application Server for information on deploying to an

Oracle9i Application Server using the Oracle Enterprise Manager and BC4J Setup and
Deployment Prerequisites for more information.
To deploy a BC4J web application to an OC4J server instance:
1. (optional) If you do not want to deploy your business components logic directly to the
J2EE Web Module, you must first create a BC4J deployment profile and choose to
configure an EJB session bean. For more information on the common deployment
configurations and how to determine whether to deploy directly to the Web Module, see
Understanding the n-Tiered Business Components Architecture.
2. Create a client application project (for example, BC4J JSP) containing your client
application files.
Note: When selecting the Application Module and deployment configuration, choose the
configuration that you want your JSP to use to connect to the deployed application
module. For example, choosing <YourApplicationModule>Local would deploy the
business logic to the Web Module. Choosing <YourApplicationModule>9iAS
instructs the JSP to use the business logic in the EJB session bean (created in step 1).
3. Upon creation of the client application project, JDeveloper generates the J2EE Web
Module deployment descriptor (web.xml) and the J2EE Web Module deployment
profile. The web.xml file defines the standard web application deployment descriptor
parameters.
14-109
4. To edit the J2EE Web Module deployment descriptor, right-click web.xml on the
Navigator and choose Settings. The Web Application 2.2 Deployment Descriptor dialog
lets you edit any of the standard deployment descriptor settings. Alternatively, you can
choose Code Editor if you are knowledgeable about the web.xml format.
For more information on these parameters, refer to the Sun Microsystems Java Servlet
http://java.sun.com/products/servlet/.
5. JDeveloper also generates a J2EE Web Module Deployment Profile which is
represented by <myappwar>.deploy on the Navigator. If you want to edit the J2EE
Web Module (WAR) deployment profile, right-click and choose Settings. The J2EE
Web Module Deployment Profile Settings panel includes:
d. In the WEB-INF/LIB page, verify that the required BC4J project libraries are
included in the dependency analysis. For example, the
Workspace_jws_projectname_jpr_classesPackageModule should be selected.
e. Select the appropriate radio button corresponding to how these libraries will be
used.
f. (optional) Click Applet Options if you want to include an applet in your deployment
profile. See Deploying an Applet as a WAR File.
g. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
deployment.
h. Click OK when you are satisfied with the Web Module deployment profile settings.
See Web Module Deployment Profile for more information about creating the Web
Module deployment profile.
6. If this is the first time you are deploying a JSP application, right-click bc4j.ear on the
Navigator (below <myappwar>.deploy and choose Deploy to
<application_server_connection> where <application_server_connection> refers to the
name of the OC4J server connection you created earlier.
14-110
Note: The bc4j.ear file contains the necessary web application, Cabo, and UIX files
for successful BC4J web application deployment. You only need to do this step the first
time you deploy a JSP application.
7. To deploy the client application project, right-click <myappwar>.deploy and choose
Deploy to <application_server_connection>. See "Deployment Options" below for more
information.
Note: In step 2, if you chose to deploy the business logic to the Web Module, the
business component files are also added to the Web module. However, if you chose to
deploy the business logic as an EJB session bean, then the Web Module only contains
the client application files.
In both cases, the client application files including the WAR and EAR files are included in
the Web module and deployed to the target OC4J instance. See OC4J Deployment
Application Directory Structure or refer to the "Oracle9iAS Containers for J2EE User's
Guide" Part Number A95880-01 provided with the Oracle9iAS documentation library for
information on the deployed location of the application files including the JAR and EAR
files.
8. You can access the web application in a browser by entering its application URL. For
example:
http://hostname:<portnumber>/<virtual path>/<sitename>/main.html
where virtual path is the context root you specified in the deployment profile (step 5.3).
Deployment Options
You can also choose to deploy the subprofiles separately in the following ways:
1. From the Navigator, right-click <myappwar>.deploy.

2. You can also choose from the following deployment options in the context menu:
a. Deploy to <application_server_connection>: the Web module is packaged as a
deploying to the selected OC4J server instance.
create a new OC4J server connection.
c. Deploy to JAR file: the Web module is packaged as a JAR file and saved to the
local directory or mapped network drive.
file and saved to the local directory or mapped network drive specified in step 5.1.
See About Deploying on Oracle9i Application Server for information on deploying
the EAR file to an Oracle9i Application Server using the Oracle Enterprise
14-111
Manager.
Notes:
WEB-INF/web.xml
Related Topics

14-112
When creating a BC4J web application using JDeveloper, a J2EE Web Module (WAR file) is
generated containing both the Business Components for Java (BC4J) and the web application
business components as a Web module. Typically, a JSP client accesses the BC4J application
in a J2EE Web Module configuration.
The JSP client can also include data tags, data web beans, XSQL, tag libraires, and UIX tags
to access the business components.
prerequisites including creating an application server connection to BEA WebLogic before
deployment and defining server connection information to deployed business components in
the bc4j.xcfg file. This file defines all of the deployment configurations of a particular
application module in the business components project and permits data tags and data web
beans to access a specific view object belonging to the application module. See BC4J Setup
and Deployment Prerequisites for more information.
To deploy a BC4J web application to WebLogic:
2. Create a client application project (for example, BC4J JSP) containing your client
application files.
configuration that you want your JSP to use to connect to the deployed application
business logic to the Web Module. Choosing <YourApplicationModule>WLS
instructs the JSP to use the business logic in the EJB session bean (created in step 1).
3. Upon creation of the client application project, JDeveloper generates the J2EE Web
parameters.
4. To edit the J2EE Web Module Deployment Descriptor, right-click web.xml on the
Navigator tree and choose Settings. The Web Application 2.2 Deployment Descriptor
14-113
dialog lets you edit any of the standard deployment descriptor settings. Alternatively, you
can choose Code Editor if you are knowledgeable about the web.xml format.
http://java.sun.com/products/servlet/.
5. JDeveloper also generates a J2EE Web Module Deployment Profile which is
represented by <myappwar>.deploy on the Navigator. If you want to edit the J2EE
Web Module (WAR) deployment profile, right-click and choose Settings. The J2EE
Web Module Deployment Profile Settings panel displays.
e. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
deployment.
f. Click OK when you are satisfied with the Web Module deployment profile settings.

Deploy to. See "Deployment Options" below for more information.
In both cases, the client application files including the WAR are included in the Web
module and deployed to WebLogic.
example:
http://hostname:<portnumber>/<virtual path>/<sitename>/main.html
14-114
where virtual path is the context root you specified in the deployment profile (step 5).
Deployment Options

WAR. JDeveloper deploys the WAR file to the selected WebLogic application
server connection which you created earlier.
b. Deploy to WAR file: the Web module is packaged as a WAR file and saved to the
local directory or mapped network drive you specified in step 5.1. Or, you can use
the BEA WebLogic Server Console to deploy this WAR file. See your WebLogic
Server documentation for more information.
c. Deploy to EAR file: the Web module is packaged as an Enterprise Archive (EAR)
5.1. Or, you can use the BEA WebLogic Server Console to deploy this WAR file.
See your WebLogic Server documentation for more information.
Notes:
WEB-INF/web.xml
Related Topics

14-115
14-116
When creating a BC4J UIX application using JDeveloper, a J2EE Web Module (WAR file) is
generated containing both the Business Components for Java (BC4J) and the UIX application
business components as a Web module. Typically, a UIX client accesses the BC4J application
in a J2EE Web Module configuration. The UIX client can also include data tags, data web
beans, XSQL, tag libraries, and UIX tags to access the business components.
prerequisites including creating a connection to an OC4J server before deployment and
defining server connection information to deployed business components in the bc4j.xcfg
file. This file defines all of the deployment configurations of a particular application module in
the business components project and permits data tags and data web beans to access a
specific view object belonging to the application module.
See About Deploying on Oracle9i Application Server for information on deploying to an

Oracle9i Application Server using the Oracle Enterprise Manager and BC4J Setup and
Deployment Prerequisites for more information.
To deploy a BC4J UIX application to an OC4J server instance:
2. Create a client application project (for example, BC4J UIX) containing your client
application files.
configuration that you want your UIX to use to connect to the deployed application
business logic to the Web Module. Choosing <YourApplicationModule>9iAS or
<YourApplicationModule>WLS instructs the UIX to use the business logic in the EJB
session bean (created in step 1).
3. Upon creation of the client UIX application project, JDeveloper generates the J2EE Web
parameters.
14-117
4. To edit the J2EE Web Module deployment descriptor, right-click web.xml on the
Navigator and choose Settings. The Web Application 2.2 Deployment Descriptor dialog
lets you edit any of the standard deployment descriptor settings. Alternatively, you can
choose Code Editor if you are knowledgeable about the web.xml format.
5. JDeveloper also generates a J2EE Web Module deployment profile which is represented
by <myappwar>.deploy on the Navigator. If you want to edit the J2EE Web Module
(WAR) deployment profile, right-click and choose Settings. The J2EE Web Module
Deployment Profile Settings panel includes:
e. (optional) Click Profile Dependencies if the deployment profile depends on J2EE
deployment.
f. Click OK when you are satisfied with the Web Module deployment profile settings.

Deploy to <application_server_connection>. See "Deployment Options" below for more
information.
In both cases, the client application files including the WAR and EAR files are included in
the Web module and deployed to the target OC4J deployment directory. The
14-118
server.xml and default-web-site.xml are updated accordingly. For OC4J, see
OC4J Deployment Application Directory Structure or refer to the "Oracle9iAS Containers
for J2EE User's Guide" Part Number A95880-01 provided with the Oracle9iAS
documentation library for information on the deployed location of the application files
including the JAR and EAR file.
example:
http://hostname:<portnumber>/<virtual path>/<sitename>/Main.uix
where virtual path is the context root you specified in the deployment profile (step 5.3).
Deployment Options

a. Deploy to <application_server_connection>: the Web module is packaged as a
deploying to the selected OC4J server instance.
create a new application server connection.
c. Deploy to JAR file: the Web module is packaged as a JAR file and saved to the
local directory or mapped network drive specified in step 5.1.
file and saved to the local directory or mapped network drive specified in step 5.1.
See About Deploying on Oracle9i Application Server for information on deploying
the EAR file to an Oracle9i Application Server using the Oracle Enterprise
Manager.
Notes:
WEB-INF/web.xml
14-119
Related Topics

14-120
When deploying a BC4J as an EJB session bean to the embedded OC4J server or to a
standalone Oracle9iAS Containers for J2EE (OC4J) instance you must ensure that the BC4J
runtime libraries are installed in OC4J or BEA WebLogic, build a deployment profile, and
deploying the application using the deployment profile. The JDeveloper deployment wizards
create all the necessary code to deploy business components as an EJB session bean.
Important: Before deploying your BC4J EJB application, ensure that you've met all the
prerequisites in BC4J Setup and Deployment Prerequisites. See also About Deploying on
To deploy BC4J as an EJB session bean to an OC4J server instance:
1. With the BC4J project selected in the JDeveloper Navigator, right-click

<ProjectName>.jpx and choose Deploy... to display the Business Components
Deployment Wizard.
File | New.... Select Deployment Profiles in the Categorieslist and choose Business
Components EJB Session Bean Profile in the Itemslist.
3. A list of deployment profiles displays. Select EJB Session Beans from the Available list
and use the move button to shuttle it to the Selected list.
4. Click Next.
profile. This name also becomes the display name in the Navigator.
Note: The BC4J deployment profile is named with a .bcdeployfilename extension.
6. In the Deploy to list box, choose the EJB container type corresponding to the application
server to which you are deploying.
7. In the Server Connection field, choose an existing application server connection. Or, you
can create an application server connection by clicking New... to display the Connection
Wizard.
8. You can leave the Deploy check box clear for now. If you select the Deploy check box, it
creates the EJB JAR and EAR files when the wizard is complete and in the case of an
OC4J deployment, deploys them directly to the default connection.
14-121
9. A list of EJB types displays. Select one of more EJB types from the Available list and use
the move button to shuttle it to the Selected list. In most cases, choosing AppModule
Session Bean (BMT) would be appropriate. If you are unsure about what to choose, you
can refer to these links for more information:
a. About Business Components Service Beans
b. About Container-Managed and Bean-Managed Transactions
c. Using Client-Demarcated Transactions
4. Click Next.
5. Select the Create AppModule Configurations check box to create the bc4j.xcfg
configuration file. This file is required for client access to the BC4J application. See
Defining Business Component Runtime Properties in the bc4j.xcfg File for Web
Applications.
6. Click Data Source... to enter connection information to the data source which contains
the business data.
a. In the Data Source field, enter the Java Naming and Directory Interface (JNDI)
name of the data source you will use in the following form:
jdbc/<connectionname>DS where <connectionname> is the name of the
database connection you have chosen in the Business Components Deployment
Wizard to build the BC4J project. By default, distributed transactions are enabled,
in which case you would enter the appropriate ejb-location for the JTA which
matches the ejb-location setting in the data-sources.xml file.
b. In the appropriate fields, enter the data source's user name and password to
access the data source.
c. In the Internal Data Source field, enter the <location> value in the data-
sources.xml file in the following form: jdbc/<connectionname>CoreDS
d. Click OK.
e. Click Help for more information.
7. In the Available list, select the application module(s) you want to deploy as an EJB
session bean. To do this, select the Application Module (for example,
PackageModule) from the Available list and move it to the Selected list.
Note: To prepare an application module for deployment, you must generate classes and
interfaces that allow a client program to access your deployed module and its service
methods. JDeveloper creates the code that gives you remote access to the application.
The generated code makes it possible to deploy an application remotely and build a
client interface without having to build any interface by hand.
8. Click Next.
14-122
The Business Components Deployment Wizard - Summarydialog displays. Review the
BC4J deployment profile settings.
9. Click Finish.
The deployment profile for this platform is created. The Business Components
deployment profile icon <ProjectNameEJB>.bcdeployappears in the Navigator below
your project.
10. To deploy the BC4J project, right-click <ProjectNameEJB>.bcdeploy and choose

Deploy. The application files including the JAR and EAR file are deployed to the OC4J
application server you specified earlier in Step 7.
Refer to the "Oracle9iAS Containers for J2EE User's Guide"Part Number A95880-01
provided with the Oracle9iAS documentation library for information on the deployed
location of the application files including the JAR and EAR files.
Deployment Options
1. From the Navigator, click + to expand <ProjectNameEJB>.bcdeploy and to display

the subprofiles:
<ProjectNameCommon>.deploy:files shared between the business components and the
client
<ProjectNameEJB>.deploy: contains the business logic in the EJB session bean
2. Right-click any of these subprofile icons to perform a variety of tasks including: display
deployment profile settings, deploy to a Java Archive file, Preview, and so on.
You can also choose from the following deployment options when right-clicking
<ProjectNameEJB>.bcdeploy:
Deploy to JAR file: the J2EE EJB module is packaged as a EJB JAR file and saved to
the local directory.
Deploy to EAR file:the J2EE EJB module is packaged as an Enterprise Archive (EAR)
file and saved to the local directory. See About Deploying on Oracle9i Application
Serverfor information on deploying the EAR file to an Oracle9iApplication Server using
the Oracle Enterprise Manager.
Deploy to <Name_of_appsvr_connection>:the J2EE EJB module is packaged as a EJB
JAR. JDeveloper also generates an EAR file which contains the EJB JAR before
14-123
deploying to the selected OC4J connectionyou created.
Related Topics
14-124
Sample Client Code for an EJB Client Deployed to OC4J
Rather than using the Business Components browser, you can also choose to test your BC4J project with
the following two client code samples for connecting to an AppModule deployed as an EJB session bean to
Oracle9iAS Containers for J2EE (OC4J):
● Sample 1
● Sample 2
Sample 1
package mypackage;
import oracle.jbo.client.Configuration;
public class sampleClient

{
public sampleClient()
{
}
public static void main(String arg[]) {
String _am = "mypackage.MypackageModule"; //App Module name

String _cf = "MypackageModule9iAS"; // EJB Config name
String _wcf = "MypackageModuleWLS"; //Weblogic EJB config name
String voMemberName = "DeptView"; // Name of the View Object
//Use _wcf if you are accessing BC4J application deployed as

//as EJB session bean in weblogic
ApplicationModule myam =
(ApplicationModule)Configuration.createRootApplicationModule(_am,_cf);
// Find the viewobject included in the appmodule

ViewObject vo = myam.findViewObject(voMemberName);
// Iterate over the viewobject to get the rows
Row r = vo.first();
while (r != null)
{
// Iterate over the current row and get
// all the attributes
for (int i = 0; i < vo.getAttributeCount(); i++)
{
String attrName = vo.getAttributeDef(i).getName();
String attrVal = r.getAttribute(i).toString();
System.out.println(attrName + " = " + attrVal);
}
14-125
r = vo.next();
}
}
}
Sample 2
import javax.naming.*;
import oracle.job.client.*;
/***
** Sample client code for connecting to an appmdoule deployed
** as an EJB session bean to Oracle9iAS server.
***/
public class SampleEJBClient
{
{
/**
** Change the following String's to match your appmodule name and the
** name of the viewobject included in that appmodule.
**
*/
String amDefName = "package1.Package1Module";
String voMemberName = "DeptView";
/**
** Change the following to point to the datasource name
** (defined in Oracle9iAS).
** to your database.
**/
String dataSourceName = "jdbc/OracleCoreDS";
/**
** Change the following to point to the hostname where the
** appmodule is deployed i.e. the host where Oracle9iAS application
** server is running.
**/
String applicationServerHost = "localhost";
/**
** Change the following username and password
** to be used for connecting to the Oracle9iAS server.
**/
String iasUserName = "admin";
String iasUserPasswd = "welcome";
14-126
/**
** Change the following to match the name of the J2EE application
** containing the deployed appmodule session bean.
**/
String applicationName = "Workspace1_Project1_ejb";
ApplicationModule am = null;
try
{
// Setup JNDI environment for looking up
// the appmodule
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,JboContext.JBO_CONTEXT_FACTORY);
env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_EJB_IAS);
env.put(JboContext.HOST_NAME, applicationServerHost);
env.put(JboContext.SECURITY_PRINCIPAL, iasUserName);
env.put(JboContext.SECURITY_CREDENTIALS, iasUserPasswd);
env.put(JboContext.APPLICATION_PATH, applicationName);
Context ctx = new InitialContext(env);
// Lookup appmodule home

ApplicationModuleHome amHome = (ApplicationModuleHome)ctx.lookup(amDefName);
// Create an appmodule instance

am = amHome.create();
// Connect to the database using the datasource

am.getTransaction().connectToDataSource(null,
dataSourceName,
false);

ViewObject vo = am.findViewObject(voMemberName);

Row r = vo.first();
while (r != null)
{
{
}
r = vo.next();
}
}
catch (NamingException ex)
{
System.out.println("NamingException " + ex.getMessage());
ex.printStackTrace();
}
catch (ApplicationModuleCreateException ex)
14-127
{
System.out.println("Unable to create application module: " + ex.getMessage());
}
catch (JboException ex)
{
System.out.println("JboException: " + ex.getMessage());
}
catch (Exception ex)
{
System.out.println("Exception: " + ex.getMessage());
}
finally
{
if (am != null)
{
am.getTransaction().disconnect();
am.remove();
}
}
}
Related Topics

14-128
Deploying BC4J as an EJB Session Bean to
WebLogic
The BC4J deployment process involves three main steps: ensuring that the BC4J runtime
libraries are installed in BEA WebLogic, building a deployment profile, and deploying the
application using the deployment profile. The JDeveloper deployment wizards create all the
necessary code to deploy business components as an EJB session bean.
Important: Before deploying your BC4J EJB application, ensure that you've met all the
prerequisites. See BC4J Prerequisites for WebLogic Deployment. You should create a
connection to BEA WebLogic before creating the deployment profile.
To deploy BC4J as an EJB session bean on WebLogic:
1. With the BC4J project selected in the JDeveloper Navigator, right-click

<ProjectName>.jpx and choose Deploy... to display the Business Components
Deployment Wizard.
File | New.... Select Deployment Profiles in the Categorieslist and choose Business
Components EJB Session Bean Profile in the Itemslist.
3. A list of deployment profiles displays. Select EJB Session Beans from the Available list
and use the move button to shuttle it to the Selected list.
4. Click Next.
profile. This name also becomes the display name in the Navigator.
Note: The BC4J deployment profile is named with a .bcdeployfilename extension.
6. In the Deploy to list box, choose the EJB container type corresponding to the application
server to which you are deploying.
7. In the Server Connection field, choose an existing application server connection. Or, you
can create an application server connection by clicking New... to display the Connection
Wizard.
8. You can leave the Deploy check box clear for now. If you select the Deploy check box, it
creates the EJB JAR and EAR files when the wizard is complete.
9. A list of EJB types displays. Select one of more EJB types from the Available list and use
the move button to shuttle it to the Selected list. In most cases, choosing AppModule
14-129
Session Bean (BMT) would be appropriate. If you are unsure about what to choose, you
can refer to these links for more information:
a. About Business Components Service Beans
b. About Container-Managed and Bean-Managed Transactions
c. Using Client-Demarcated Transactions
10. Click Next.

11. Select the Create AppModule Configurations check box to create the bc4j.xcfg
configuration file. This file is required for client access to the BC4J application.
12. Click Data Source... to enter connection information to the data source which contains
the business data.
a. In the Data Source field, enter the JNDI name of the data source you will use to
create this BC4J deployment profile.
b. In the appropriate fields, enter the data source's user name and password to
access the data source.
c. In the Internal Data Source field, enter the JNDI name of a non-transactional data
source.
d. Click OK.
e. Click Help for more information.
13. Click OK.

14. In the Available list, select the application module(s) you want to deploy as an EJB
session bean to WebLogic. To do this, select the Application Module (for example,
PackageModule) from the Available list and move it to the Selected list.
Note: To prepare an application module for deployment, you must generate classes and
interfaces that allow a client program to access your deployed module and its service
methods. JDeveloper creates the code that gives you remote access to the application.
The generated code makes it possible to deploy an application remotely and build a
client interface without having to build any interface by hand.
15. Click Next.

The Business Components Deployment Wizard - Summarydialog displays. Review the
BC4J deployment profile settings.
16. Click Finish.

The deployment profile for this platform is created. The Business Components
deployment profile icon <ProjectNameEJB>.bcdeployappears in the Navigator below
your project.
14-130
17. To deploy the BC4J project, right-click <ProjectNameEJB>.bcdeploy and choose
Deploy.
The application files including the JAR and EAR file are deployed to the WebLogic
application server you specified earlier in Step 7.
Deployment Options
1. From the Navigator, click + to expand <ProjectNameEJB>.bcdeploy and to display

the subprofiles:
<ProjectNameCommon>.deploy:files shared between the business components and the
client
<ProjectNameEJB>.deploy: contains the business logic in the EJB session bean
2. Right-click any of these subprofile icons to perform a variety of tasks including: display
deployment profile settings, deploy to a Java Archive file, Preview, and so on.
You can also choose from the following deployment options when right-clicking
<ProjectNameEJB>.bcdeploy:
Deploy to JAR file: the J2EE EJB module is packaged as a EJB JAR file and saved to
the local directory.
Deploy to EAR file:the J2EE EJB module is packaged as an Enterprise Archive (EAR)
file and saved to the local directory.
Deploy to <Name_of_appsvr_connection>:the J2EE EJB module is packaged as a EJB
JAR. JDeveloper also generates an EAR file which contains the EJB JAR before
deploying to the selected WebLogic application server connectionyou created.
Related Topics
14-131
14-132
Rather than using the Business Components browser, you can also choose to test your BC4J
project with the following sample client code for connecting to an AppModule deployed as an
EJB session bean to BEA WebLogic 6.x:
package mypackage;
public class sampleClient

{
public sampleClient()
{
}

String _cf = "MypackageModule9iAS"; // EJB Config name
String _wcf = "MypackageModuleWLS"; //Weblogic EJB config name
//Use _wcf if you are accessing BC4J application deployed as

//as EJB session bean in weblogic

Row r = vo.first();
while (r != null)
{
{
}
r = vo.next();
14-133
}
}
}
Related Topics
14-134
Deploying CORBA objects on VisiBroker involves these tasks:
● Setting Up the Classpath to Run BC4J Applications on VisiBroker

● Starting CORBA Objects on VisiBroker
● Starting a Business Components Project Using Bind Mode
● Starting a Business Components Application Using the Naming Service
Modifying Applet HTML Files for VisiBroker Deployment
● Setting Up the VisiBroker Gatekeeper

● Modifying HTML Files to Use the VisiBroker Naming Service
● Modifying HTML Files to Use VisiBroker Bind Mode
Testing CORBA Objects on VisiBroker
● Testing Business Components Deployed to VisiBroker Using Collocate Mode

● Testing Business Components to VisiBroker Using Bind Mode
● Testing Business Components Using Naming Service
● Testing with the Business Components Browser
Note: For more information about CORBA Objects on VisiBroker, see http://www.inprise.com/.
14-135
Setting Up the Classpath to Run BC4J Applications
on VisiBroker
After creating and invoking a Business Components for Java (BC4J) deployment profile, you
must set up the classpath to run the CORBA server object on VisiBroker. You must also copy a
batch file that will help you start your VisiBroker server class.
Note: Ensure that you have VisiBroker already installed before deploying to it. The location
where VisiBroker is installed becomes your target directory. For more information about
CORBA Objects on VisiBroker, see http://www.inprise.com/.
To set up the classpath to run BC4J applications on VisiBroker:
1. From your JDeveloper installation directory in

<JDEV_HOME>/<your_project_dir>/classes, select to copy the following files:
❍ <Project1>VisigenicServer.jar
❍ <Project1>VisigenicCommon.jar
❍ <Project1>VisigenicMT.jar
where <Project1> is the name of your project.
2. Copy these files to your VisiBroker target directory.

3. From your JDeveloper installation directory in <JDEV_HOME>/lib directory, select to
copy the following files:
❍ bc4jmt.jar
❍ bc4jdatum12.jar
❍ bc4jdomgnrc.jar or bc4jdomorcl.jar
■ Note: Only one of the above is required. If you are using the Oracle type
mappings and you are using Oracle JDBC (classes12.zip or

classes111.zip), use bc4jdomorcl.jar. If the application was built using
Oracle type mappings and you are connecting to non-Oracle JDBC, use
bc4jdomgnrc.jar. If you are using Java type mappings, you do not
require either of these files.
❍ bc4jct.jar
❍ bc4jmtvb.jar
❍ bc4jctvb.jar
14-136
❍ bc4jct.jar
❍ classes12.jar
❍ collections.jar
❍ ordhttp.jar
❍ ordim817.jar
❍ ordvir817.jar
❍ jndi.jar
❍ runtime12.jar
❍ xmlparserv2.jar
❍ vbjorb.jar

5. From your JDeveloper installation directory in <JDEV_HOME>/bin directory:
startCORBA.bat
Related Topics
Starting a Business Components Project Using Bind Mode
Starting a Business Components Application Using the Naming Service
14-137
Before deploying a Business Components for Java project, you must have already created a
project with business components using the Business Components Package Wizard.
The BC4J deployment process involves three main steps: copying the Business Components
archives, building a deployment profile, and deploying using the deployment profile.
To start CORBA Objects on VisiBroker:
1. Make sure that you've set up the classpath to run BC4J applications on VisiBroker.
2. With a Business Components for Java project selected in the Navigator, right-click
and choose Deploy Business Components... to display the Business Components
Deployment Wizard.
File | New... to open the New Object dialog. Select Deployment Profiles in the
Categories list and choose Business Components CORBA Server for VisiBroker profile
in the Items list.
This wizard guides you in the creation of business components deployment profile
3. Choose CORBA Server for VisiBroker from the Available list as the deployment profile
type and click the arrow to move it to the Selected list.
4. Click Next.
profile. The default name is Project1Visigenic1.bcdeploy.
Note: The CORBA Object's deployment profile should be named with a
.bcdeployfilename extension.
6. Select the Deploy check box.

7. Before you deploy your CORBA Objects, you must make server- and client-side versions
of your application module so that the application module can be invoked remotely.
This is done from the Select AppModules to Support the Selected Platforms panel by
selecting and moving the appropriate Application Modules from the Available list to the
Selected list with the move arrows.
8. Click Next.
9. You'll see a listing of the selected deployment profile(s).
Click Finishwhen you are done.
The deployment profile for the archive is created. The Business Components deployment
14-138
profile icon appears in the Navigator below your project.
10. (optional) You can right-click on any of these subprofile icons to perform a variety of
tasks including: display deployment profile settings, deploy to a Java Archive file,
Preview, and so on.
Note: For more information about CORBA Objects on VisiBroker, see http://www.inprise.com/.
Related Topics
Setting Up the Classpath to Run BC4J Applications on VisiBroker
14-139
Starting a Business Components Application Using
Bind Mode
Follow these steps to start business components applications to VisiBroker using bind mode
(default).
1. In the Navigator, right-click the VisiBroker deployment profile icon

<Projectname>Visigenic.bcdeloy and choose Deploy... to deploy your BC4J
application project.
2. Set up the classpath to run BC4J applications by copying your VisiBroker server class,
required libraries, and batch file to the VisiBroker directory.
3. Start the OSAgent by executing the following command:
<vbroker>\bin\osagent -C
where <vbroker> is your VisiBroker home directory.
4. Start the CORBA server class by executing the following command:
startCORBA <yourServerClass>
where <yourServerClass> is the name of your business components server class.
Related Topics

Modifying HTML Files to Use VisiBroker Bind Mode
Testing Business Components to VisiBroker Using Bind Mode
14-140
Starting a Business Components Application Using
the Naming Service
Follow these steps to deploy to VisiBroker if you want to use the VisiBroker Naming Service.
1. In the Navigator, right-click the VisiBroker deployment profile icon

<Projectname>Visigenic.bcdeloy and choose Deploy... to deploy your BC4J
application project.
2. Set up the classpath to run BC4J applications by copying your VisiBroker server class,
required libraries, and batch file to the VisiBroker directory.
3. Start the OSAgent by executing the following command:
<vbroker>/bin/osagent -C
where <vbroker> is your VisiBroker home directory.
4. Start the VisiBroker naming service by executing the following command:
<vbroker>/bin/nameserv <NameServerRoot>
where <NameServerRoot> is the name you want for the naming service root.
5. Start the CORBA server class by executing the following command:
startCORBA <yourServerClass> -ns <NameServerRoot>
where <yourServerClass> is the name of your business components server class.
Related Topics
Starting a Business Components Application Using the Bind Mode

Modifying HTML Files to Use the VisiBroker Naming Service
Testing Business Components Using Naming Service
14-141
Setting Up the VisiBroker Gatekeeper
You may have to use the VisiBroker Gatekeeper so that your applet can communicate to your
server objects across firewalls. If you do, you must change your applet's HTML files.
1. Start the VisiBroker Gatekeeper.

2. Copy the gatekeeper.ior file to a location under your web server's document root so
that it may be retrieved via HTTP from the applet.
Related Topics
14-142
Modifying HTML Files to Use VisiBroker Bind Mode
1. Modify the HTML file generated by the Business Components Data Page Wizard to
include the following tags used by the ORB.
For Microsoft Internet Explorer
Add the following PARAM tags:
<PARAM NAME="VBROKER.ORB.GATEKEEPER.IOR"
value="http://mywebserver/gatekeeper.ior">
<PARAM NAME="vbroker.orb.alwaysTunnel" value="true">
Note: Replace mywebserver with the hostname of the web server that is running.
For Netscape Navigator
The above parameters have to be specified in the EMBED tag
<EMBED type="application/x-java-applet;version=1.2"
java_CODE = "package3.Applet1.class"
...
pluginspage =
"http://java.sun.com/products/plugin/1.2/plugin-
install.html"
vbroker.ord.gatekeeper.ior =
"http://mywebserver/gatekeeper.ior"
vbroker.orb.alwaysTunnel = "true"
2. When viewing the applet with the Java plug-in version 1.1.2, the type parameter in the
above tag should be changed for your browser. For example, for the Netscape
Navigator:
14-143
Related Topics

Modifying HTML Files to Use the VisiBroker Naming Service
Deploying a Business Components Project to VisiBroker Using Bind Mode
14-144
Modifying HTML Files to Use the VisiBroker Naming
Service
1. Modify the HTML file generated by the Business Components Data Page Wizard to
include the following tags used by the ORB.
Add the following PARAM tags:
For Microsoft Internet Explorer

<PARAM NAME="vbroker.orb.gatekeeper.ior"
For Netscape Navigator
The above parameters must be specified in the EMBED tag:
java_CODE = "package3.Applet1.class"
...
<PARAM NAME="vbroker.orb.gatekeeper.ior"
</EMBED>
2. When viewing the applet with the Java plug-in version 1.1.2, the type parameter in the
above tag should be changed for your browser. For example, for the Netscape
Navigator:
14-145
Related Topics

Modifying HTML Files to Use the VisiBroker Bind Mode
Deploying a Business Components Project to VisiBroker Using the Naming Service
14-146
Testing with the Business Components Browser
JDeveloper provides the Business Components browser to test application modules that are
deployed remotely. You can use the browser after deploying your application module and
before adding a client application.
To test a BC4J project using the Business Components browser:
1. In the Navigator, right-click the application module you want to test and choose Test...
2. Choose the Business Component Configuration Name from the list box.
3. In the Middle-tier Server Type list, choose VisiBroker.
4. In the ORB Connection Type section, choose the mode to which you want to connect to
VisiBroker: Collocated, Binding, Naming Service.
Note: If you choose either Binding or Naming Service as the ORB Connection Type,
make sure that the VisiBroker server is already up and running.
5. Complete the remaining configuration settings.
6. Click Connect.
The Business Components Tester opens.
Related Topics
14-147
Testing Business Components to VisiBroker Using Bind Mode
1. In the Navigator, select the appropriate business components project.
2. Choose Project | Project Settings from the main menu, or right-click and choose Settings.
3. The Project Settings dialog opens with the common input paths displayed.
4. Under Development, click the Libraries or Production node, depending on what was set for the Project
Settings' Currently active configuration (Configuration node).
5. Select the desired library or libraries from the Available libraries listing and click the single shuttle button to
move them to the Selected libraries listing. To move the entire listing, click the double shuttle button.
6. Add the following libraries:
JBO VB Runtime
JBO VB Client
JBO Runtime
Your business components common library
If you need assistance adding libraries, click Help

.
7. Create a VisiBroker bind mode configuration for your business components project. For information on how to
do this, see Defining Business Component Runtime Properties in the bc4j.xcfg File for Web Applications.
8. Choose File | New ...
9. Select Class.
10. Name your class BC4J_VBBIND_Test and click OK.
11. In the Navigator, double-click your new class to open the Source view.
12. Paste the following code into your class. You'll need to replace the names in this sample to reflect the names
you've used in your your own test client.
package mypackage;
public class BC4J_VBBIND_TEST

{
public BC4J_VBBIND_Test()
{
}

String _cf = "MypackageModule"; // VisiBroker Bind Mode Config name specified in Step 7
above.
14-148

Row r = vo.first();
while (r != null)
{
{
}
r = vo.next();
}
}
}
13. Choose Run | Run <name of project>.
Related Topics

Deploying a Business Components Project to VisiBroker Using Bind Mode
14-149
Testing Business Components Deployed to VisiBroker Using
Collocate Mode
4. Under Development, click the Libraries or Production node, depending on what was set for the Project Settings'
Currently active configuration (Configuration node).
5. Select the desired library or libraries from the Available libraries listing and click the single shuttle button to move
them to the Selected libraries listing. To move the entire listing, click the double shuttle button.
JBO 8i Runtime
JBO 8i Client
If you need assistance adding libraries, click Help.

7. Create a VisiBroker collocate mode configuration for your business components project. For information on how to
9. Select Class.
10. Name your class BC4J_VBcolocate_Test and click OK.
12. Paste the following code into your class. You'll need to replace the names in this sample to reflect the names you've
used in your your own test client.
package mypackage;
public class BC4J_VBcolocate_Test

{
public BC4J_VBcolocate_Test()
{
}

String _cf = "MypackageModule"; // VisiBroker Collocate Mode Config name specfied in step 7
above.

14-150
Row r = vo.first();
while (r != null)
{
{
}
r = vo.next();
}
}
}
Related Topics

14-151
Testing Business Components Using Naming Service
4. Under Development, click the Libraries or Production node, depending on what was set for the Project Settings'
Currently active configuration (Configuration node).
5. Select the desired library or libraries from the Available libraries listing and click the single shuttle button to move
them to the Selected libraries listing. To move the entire listing, click the double shuttle button.
JBO VB Runtime
JBO VB Client
JBO Runtime
If you need assistance adding libraries, click Help.

7. Create a VisiBroker naming mode configuration for your business components project. For information on how to
9. Select Class.
10. Name your class BC4J_VBREMOTE_Test and click OK.
12. Paste the following code into your class. You'll need to replace the names in this sample to reflect the names
you've used in your your own test client.
package mypackage;
public class BC4J_VBREMOTE_Test

{
public BC4J_VBREMOTE_Test()
{
}

String _cf = "MypackageModule"; // VisiBroker Naming Config name specfied in step 7 above.

Row r = vo.first();
14-152
while (r != null)
{
{
}
r = vo.next();
}
}
}
Related Topics

14-153
JDeveloper provides tools that help you create and deploy Web services. Information about
Web services, and how to create them in JDeveloper, can be found in Web Services.
JDeveloper allows you to create Web services that can be deployed:
● as J2EE Web Services to OC4J. JDeveloper allows you to deploy J2EE Web Services
with a single mouse click. This is by far the simplest way to deploy your Web service. For
more information, go to Deploying J2EE Web Services to OC4J.
● Web services to:
❍ Oracle9iAS Release 2 SOAP Servers. Refer to Deploying Web Services to an
Oracle9i Release 2 SOAP Server.

❍ Apache 2.2 SOAP Servers. Refer to Deploying Web Services to an Apache SOAP
Server.
To experience how easy it can be to create and deploy Web services in JDeveloper, refer to
the tutorial Creating and Using Web Services, which takes you through creating and deploying
a J2EE Web service on OC4J, and creating and deploying a Web service based on the same
Java class to the Oracle9i SOAP Server.
Related Topics
Web Services
14-154
Deploying J2EE Web Services to OC4J
You can deploy a J2EE Web service to Oracle9iAS Containers for J2EE (OC4J) with a single
mouse click. This includes J2EE Web services based on a simple Java class and Web services
based on the remote interface of a stateless EJBs.
When you used the Web Service Publishing Wizard to create the files for your J2EE Web
service, you specified a connection to the OC4J instance on which the service is to be
deployed, and the wizard automatically created all the files that you need, including a Web
Archive (WAR) deployment profile named WebServices.deploy.
The WebServices.deploy file is created at the project level, and if you create more than one
Web service in the same project, it is updated with the new files. To examine the contents of
WebServices.deploy, double-click it in the Navigator to display the WAR Deployment Profile
Settings. Choose the WEB-INF/classes node from the left panel to display a listing of the
.java and .wsdl files for the Web services in the project in the right panel.
To deploy a J2EE Web service:
● With WebServices.deploy selected in the Navigator, right-click and choose Deploy to

<Name_of_server_connection>. Choose the OC4J connection that you specified when
you created the Web service from the list of available connections.
For more information about creating a J2EE Web service, refer to Creating a J2EE Web
Service.
Related Topics
Web Services
14-155
Deploying a Web service to an Oracle9i Release 2
SOAP Server
You can quickly and simply deploy a Web service generated from a simple Java class or a
Java class generated by JDeveloper's Business Components for Java (BC4J) framework as a
JAR file to an Oracle9i Release 2 SOAP Server.
You may need to refer to the Oracle9iAS documentation or ask your Application Server
administrator for assistance.
To deploy a simple Web service:
1. With a project selected in the Navigator, choose File | New...

2. Select Deployment Profiles in the Categories list and Simple Archive in the Items list.
3. Click OK.
4. Specify a location for the archive's deployment profile and click Save.
5. The Simple Archive Deployment Profile Settings dialog is displayed. You can accept the
defaults. Click OK and the deployment profile is saved to the location you specified with
a .deploy filename extension.
6. Select the deployment profile in the Navigator, right-click, and choose Deploy to.
7. The Deploy to Java Archive (JAR) File dialog is displayed.
8. You can save the deployment profile to your local machine and then copy it to the correct
location on the SOAP server, or you can copy it directly to
<JDeveloper_home>/soap/webapps/soap/soap/WEB-INF/lib. This
automatically places it in the classpath, and the SOAP server does not have to be
restarted.
9. The JAR file is saved to the location you specified. If necessary, copy the file to the
<JDeveloper_home>/soap/webapps/soap/soap/WEB-INF/lib on the SOAP
server. This has to be performed outside of JDeveloper.
Now that you have created your JAR file and deployed it to the correct location, you need to
register it to ensure that the SOAP server can recognize the file. See Registering a Web
service With a Soap Server.
For more information about creating and deploying a simple JAR file, refer to Deploying a
Simple Archive to Your File System.
14-156
Related Topics
Ways to Deploy Web services

Web services
14-157
Deploying a Web Service to an Apache SOAP
Server
You can deploy a Web service generated from a simple Java class or a Java class generated
by JDeveloper's Business Components for Java (BC4J) framework as a JAR file to an Apache
2.2 SOAP Server.
You may need to refer to the Apache documentation or ask your Application Server
To deploy a simple Web service:
1. With a project selected in the Navigator, choose File | New

2. Choose Deployment Profiles in the Categories list and Simple Archive in the Items list.
3. Click OK.
4. Specify a location and name for the archive's deployment profile and click Save.
5. The Simple Archive Deployment Profile Settings dialog is displayed. You can accept the
defaults. Click OK and the deployment profile is saved to the location you specified with
a .deploy filename extension.
6. Select the deployment profile in the Navigator, right-click and choose Deploy to.
7. The Deploy to Java Archive (JAR) File dialog is displayed. You can save the JAR file it to
your local machine and then copy it to the correct location on the SOAP server, or if you
have a drive mapped to the SOAP server you can save it to a location there.
8. If you did not save to JAR file to the SOAP server, copy it to the correct location. This
must be performed outside of JDeveloper.
To add the JAR to the classpath:
1. Stop the Apache SOAP Server.

2. Add the path of the JAR file to the SOAP server's classpath.
3. Restart the SOAP Server.
Now that you have created your JAR file and deployed it to the correct location, you need to
register it to ensure that the SOAP server can recognize the file. See Registering a Web
Service With a Soap Server.
14-158
For more information about creating and deploying a simple JAR file, refer to Deploying a
Simple Archive to Your File System.
Related Topics

Web Services
14-159
About Deploying an EJB Web Service to an Oracle9i
SOAP Server
JDeveloper lets you create a Web service based on the remote interface of a stateless EJB and
deploy it to OC4J, which contains an Oracle9iAS Release 2 SOAP server.
Note: This section describes deploying a Web service based on the remote interface of a
stateless EJB to an Oracle9i SOAP Server. Deploying a J2EE Web service based on the
remote interface of a stateless EJB is a much simpler procedure. For more information, see
Deploying J2EE Web Services to OC4J.
There are a number of tasks you must perform to deploy a Web service based on an EJB to an
Oracle9i SOAP Server:
1. Before deploying to a SOAP Server for the first time, the EJB providers must be
registered on the server. See Registering the EJB Providers with OC4J.
2. Once the providers have been registered on the server, you can deploy the EJB Module
(EJB JAR) to OC4J. See Creating and Deploying a J2EE EJB Module (EJB JAR) to
OC4J.
3. When the EJB module has been deployed, you can deploy the Web service as a J2EE
EJB Module (EJB JAR file). See Deploying an EJB Web Service.
4. You must register the Web service. See Registering a Web Service With a Soap Server.
For general information about creating Web services, refer to Web Services. For information
about creating a Web service based on an EJB, see Web Services.
Related Topics
Web Services
14-160
Registering the EJB Providers with OC4J
Before you can deploy a Web service based on an EJB for the first time, you must register the providers for the EJB Web service types that are supported:
● Stateless session Enterprise JavaBeans
● Stateful session Enterprise JavaBeans
● Entity Enterprise JavaBeans
These instructions apply to the embedded OC4J server in Oracle9i JDeveloper or a standalone OC4J instance. To register the providers on Oracle9i Application Server, use the following instructions as examples, and refer
to the Oracle9iAS documentation for specific information.
Throughout this topic, <JDeveloper_home> refers to the location where JDeveloper is installed.
To register the providers:
1. If necessary, install OC4J, or if it is running, stop it according to the instructions in Installing, Starting, and Stopping OC4J.
2. Modify the following JDeveloper file, <JDeveloper_home>/soap/webapps/soap/soap/WEB-INF/soap.xml, to include the following lines:
<osc:providerManager>
<osc:option name="autoDeploy" value="true" />
</osc:providerManager>
3. You have to create three XML files that contain provider information for stateless EJBs, stateful EJBs, and entity EJBs. For each of the following, copy the code into a text editor, change <hostname.domain> to the
domain qualified hostname for your machine, and save as instructed:
Save the following as <JDeveloper_home>/j2ee/home/statelessejb-provider.xml
<isd:provider xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/provider"
id="stateless-ejb-provider"
class="oracle.soap.providers.ejbprov.StatelessEJBProvider">
<isd:option key="SecurityPrincipal" value="admin"/>
<isd:option key="SecurityCredential" value="welcome"/>
<isd:option key="ContextProviderURL" value="ormi://<hostname.domain>"/>
<isd:option key="FullContextFactoryName"
value="com.evermind.server.rmi.RMIInitialContextFactory"/>
</isd:provider>
Save the following as <JDeveloper_home>/j2ee/home/statefulejb-provider.xml:
id="stateful-ejb-provider"
class="oracle.soap.providers.ejbprov.StatefulEJBProvider">
</isd:provider>
Save the following as <JDeveloper_home>/j2ee/home/entityejb-provider.xml:
id="entity-ejb-provider"
class="oracle.soap.providers.ejbprov.EntityEJBProvider">
14-161
</isd:provider>
4. Cut and paste the following command into a text editor (it is all on one line), and replace <JDeveloper_home> with the appropriate path:
Java -cp
<JDeveloper_home>/lib/xmlparserv2.jar;<JDeveloper_home>/soap/lib/soap.jar;<JDeveloper_home>/j2ee/home/lib/http_client.jar;<JDeveloper_home>/j2ee/home/lib/javax-
ssl-1_2.jar;<JDeveloper_home>/j2ee/home/lib/jssl-1_2.jar;<JDeveloper_home>/j2ee/home/activation.jar;<JDeveloper_home>/j2ee/home/mail.jar
oracle.soap.client.ProviderManagerClient
Copy the edited command and paste it into the command prompt. The current usage details of the provider manager are displayed.
5. Run the same command with parameters to register the EJB providers. At the command prompt, run the command in step 4 three times, each time followed by one of:
http://localhost:8888/soap/servlet/soaprouter deploy <JDeveloper_home>\j2ee\home\statelessejb-

provider.xml
http://localhost:8888/soap/servlet/soaprouter deploy <JDeveloper_home>\j2ee\home\statefulejb-
provider.xml
http://localhost:8888/soap/servlet/soaprouter deploy <JDeveloper_home>\j2ee\home\entityejb-
provider.xml
6. Check that the providers are registered using the list command. At the command line, enter the command in step 3 followed by:
http://localhost:8888/soap/servlet/soaprouter list
7. Start OC4J following the instructions in Installing, Starting, and Stopping OC4J.
Now that you have the EJB providers registered at OC4J's SOAP server, you can create Web services based on an EJB by invoking the Web Services Publishing Wizard, and entering the EJB remote interface as the class
to publish.
Related Topics
Deploying a J2EE EJB Module as a Web service

Registering the EJB Providers with OC4J
Installing, Starting, and Stopping OC4J
Deploying an EJB Web service Module
14-162
Deploying an EJB Web Service
Before you can deploy a Web service based on an Enterprise JavaBeans for the first time, you
must first register the Web service providers on the SOAP server. See Registering the EJB
Providers with OC4J.
Once you have created a Web service from the remote interface of a stateless EJB, you deploy
it as a J2EE EJB Module (EJB JAR file).
You may need to refer to the Oracle9iAS documentation, or ask your Application Server
To deploy an EJB Web service:

2. Choose Deployment Profiles in the Categories list and EJB JAR file - J2EE EJB Module
in the Items list.
3. Click OK.
6. The J2EE EJB Module Deployment Profile Settings panel appears. You can accept the
defaults. Click OK.
7. The newly created EJB deployment profile icon appears in the Navigator below your
project.
7. Select and right click the <ejb_name> deployment profile icon and choose one of the
following deployment options:
deploying to an OC4J connection which you created earlier. For more information,
see Creating a Connection to Oracle9iAS Containers for J2EE (OC4J). Refer to
the "Oracle9iAS Containers for J2EE User's Guide" Part Number A95880-01
provided with the Oracle9iAS documentation library for information on the
14-163
Now that you have deployed your EJB Web service to the SOAP server, you need to register it
to ensure that the SOAP server can recognize the file. See Registering a Web service With a
Soap Server.
For more information about creating and deploying an EJB Jar file, refer to Creating and
Deploying a J2EE EJB Module (EJB JAR) to OC4J.
Related Topics

Web Services
14-164
Using SQL in Java Programs
● Using SQL in Java Programs
● Embedding SQL in Java Programs

❍ About SQL in Java Programs
❍ About Oracle JDBC drivers

❍ About SQLJ versus JDBC
❍ Embedding SQL in Java Programs with SQLJ
■ Creating a SQLJ File
■ Compiling SQLJ Files

■ Using Named SQLJ Connection Contexts
■ Declaring a SQLJ Connection Context Class
■ Creating a Connection Context Object
■ Debugging SQLJ Files

■ Setting SQLJ Translator Options
■ Using SQLJ Connection Options
❍ Embedding SQL in Java Programs with JDBC

■ Choosing a JDBC Driver
■ Installing a Non-Default JDBC Driver

■ Modifying the JDeveloper Environment for Non-Default JDBC Drivers
■ Modifying a Project to Use a Non-Default JDBC Driver
■ Coding a JDBC Connection

■ Specifying a JDBC Connection
● Accessing Oracle Objects and PL/SQL Packages using Java

❍ About JPublisher
■ About Object Types and JPublisher
■ About PL/SQL Packages and JPublisher

■ About Java Mapping Options
■ About Mapping Built-In Types
15-1
■ About Mapping LOB Types
■ About Mapping Numeric Types
■ About Mapping User-Defined Types
■ About JPublisher Output

■ About Properties Files
■ About JPublisher Limitations
❍ Generating Java Source Code for Oracle Objects and PL/SQL Packages
❍ Enhancing JPublisher-Generated Classes
■ Extending JPublisher-Generated Classes
❍ Setting JPublisher Options

■ Generating Classes for Packages and Wrapper Methods for Methods
■ Omitting the Schema Name from Generated Names

■ Setting the Package Name for Generated Classes
● Improving Application Performance with Java Stored Procedures

❍ About Java Stored Procedures
❍ Creating Java Stored Procedures

❍ Deploying Java Stored Procedures
■ What JDeveloper Does when You Deploy a Java Stored Procedure
❍ Testing Stored Procedures

■ Testing Stored Procedures Deployed in Packages
■ Testing Stored Procedures Deployed Separately
❍ Invoking a Java Stored Procedure

■ Invoking a Java Stored Procedure using SQL
■ Invoking a Java Stored Procedure using JDBC

■ Invoking a Java Stored Procedure using SQLJ
■ Invoking a Java Stored Procedure using PL/SQL
❍ Browsing Java Stored Procedures

❍ Removing Java Stored Procedures
15-2
15-3
JDeveloper supports features allow you to write and execute Java programs that access the
Oracle9i database:
● Embed SQL statements in Java programs using JDBC and SQLJ, to allow your Java
application to access the database.
● Manipulate database objects and PL/SQL packages directly in Java, by using JPublisher
to map them to Java classes.
● Store and execute database-intensive Java methods in the database itself, as Java
stored procedures.
Related topics
Browsing the Database
15-4
Embedding SQL in Java Programs
JDeveloper supports two mechanisms for embedding SQL in Java programs:
● SQLJ: If you are developing a purely static application, that is, you know the PL/SQL
tables and columns involved at compile time, you can use SQLJ.
SQLJ allows you to code at a higher level than JDBC, by embedding SQL statements
directly in your Java code. The SQLJ precompiler that is integrated into JDeveloper
translates the SQL into Java plus JDBC code for you. SQLJ with JDeveloper lets you
write and debug applications much faster than you can using just JDBC.
● JDBC: If you require fine-grained control over database access, or if you are developing
an application that requires precise information about database (or instance) metadata,
you can code your application entirely in Java using the JDBC API.
You can mix JDBC calls with SQLJ statements in your program. One way to do this is through
connection context sharing.
Related documentation
See Advanced Language Features in the Oracle9i SQLJ Developer's Guide and Reference at
the Oracle Technology Network (OTN) website.
Related topics
About SQL
About Oracle JDBC drivers
About SQLJ versus JDBC
15-5
About SQL in Java Programs
SQLJ is a standard way to embed static SQL statements in Java programs. The standard is
being developed by a number of software vendors, including IBM, Tandem, Sybase, and Sun
Microsystems, along with Oracle. SQLJ applications are portable and can communicate with
databases from multiple vendors using standard JDBC drivers.
JDBC provides Java programs with low-level access to databases.
SQLJ provides a way to develop applications both on the client side and on the middle-tier that
access databases using Java. Developing in SQLJ is fast and efficient, and JDeveloper
completely supports SQLJ development. You can create or include SQLJ files in your
JDeveloper projects. When you compile a project that contains SQLJ source files, JDeveloper
automatically calls the SQLJ translator, or precompiler. The translator produces completely
standard Java source code, with calls to JDBC methods to provide the database support.
JDeveloper then compiles the Java that the SQLJ translator generates.
See Oracle9i SQLJ Developer's Guide and Reference at the Oracle Technology Network
(OTN) website.
Related topics

15-6
Oracle JDBC drivers can be grouped into two main categories with the following attributes:
● Java-based drivers (thin client / Type 4 driver)
❍ implemented entirely in Java

❍ highly portable
❍ downloadable from the server system to a web browser
❍ connect using the TCP/IP protocol
❍ only option for applets (due to security restrictions)
● OCI-based drivers (Type 2 driver)
❍ implemented using native method libraries (OCI DLLs)

❍ OCI libraries must be available on the client system
❍ cannot be downloaded to a browser
❍ can connect using any Net8 protocol
❍ high performance
The following figure illustrates how JDBC components and the driver run in the same memory
space as an applet.
The following figure illustrates how the Oracle JDBC OCI drivers run in a separate memory
15-7
space from your Java application. These JDBC drivers make OCI calls to a separately loaded
file.
Note: Don't confuse the terms JDBC and JDBC drivers. All Java applications, no matter how
they are developed or where they execute, ultimately use the JDBC-level drivers to connect to
Oracle. However, coding using the pure JDBC API is low-level development, akin to using the
Oracle Call Interface (OCI) to develop a database application. Like the OCI, the JDBC API
provides a very powerful, but also very code-intensive, way of developing an application.
Related topics

About SQL
Choosing a JDBC driver
15-8
How does SQLJ compare to JDBC? Here are some of the advantages that SQLJ offers over
coding directly in JDBC:
● SQLJ programs require fewer lines of code than JDBC programs. They are shorter, and
hence easier to debug.
● SQLJ can perform syntactic and semantic checking on the code, using database
connections at compile time.
● SQLJ provides strong type-checking of query results and other return parameters, while
JDBC values are passed to and from SQL without having been checked at compile time.
● SQLJ provides a simplified way of processing SQL statements. Instead of having to write
separate method calls to bind each input parameter and retrieve each select list item,
you can write one SQL statement that uses Java host variables. SQLJ takes care of the
binding for you.
However, JDBC provides finer-grained control over the execution of SQL statements and offers
true dynamic SQL capability. If your application requires dynamic capability (discovery of
database or instance metadata at runtime), then you should use JDBC.
Related topics

Embedding SQL in Java Programs with SQLJ
Embedding SQL in Java Programs with JDBC
15-9
SQLJ is an industry standard for defining precompiled SQL code in Java programs.
Embedding SQL in Java programs with SQLJ involves the following tasks:
● Creating new SQLJ files.

● Compiling SQLJ files.
● Using Named SQLJ Connection Contexts
● Debugging SQLJ files.
● Setting SQLJ translator options.
● Using SQLJ Connection Options
(OTN) website.
Related topics

About SQL
15-10
Creating a SQLJ File
To create a new SQLJ (.sqlj) file and add it to the current project, perform these steps:
1. Choose File | New from the JDeveloper menu bar to open the New gallery.
2. Select Objects in the Categories list.
3. Select SQLJ Class in the Items list.
4. Click OK
A skeleton SQ LJ class is opened for editing, and is added to the current project.
Related topics
15-11
Compiling SQLJ Files
SQLJ also provides syntactic as well as semantic checking of your SQL code. SQLJ will do
syntax and type checking on the SQL statements, testing the compatibility of Java and SQL
expressions at compile time. As a compile time option, you also can specify a connection to a
database server, and have SQLJ check the semantics of your SQL statements against the
database schemas specified by connection contexts.
Before compiling a project's SQLJ (.sqlj) source files, set the project's SQLJ compilation
options. To open the SQLJ compiler options for the current project, choose Project | Project
Settings to open the Project Settings dialog, and navigate to Configurations | Development |
Compiler | SQLJ.
To compile a .sqlj source file, right-click it, and choose Make from its context menu.
Related topics
15-12
Using Named SQLJ Connection Contexts
A SQLJ executable statement can designate a connection context object that specifies the
database connection where the SQL operation in that clause will execute. If the SQLJ
statement omits the connection context clause, then the default connection context is used.
To use a named SQLJ connection context:
● Declare a context class.

● Create a context object.
Named connection contexts are not required: SQLJ statements that omit the connection
context name use the default connection context.
Related topics

About SQLJ
15-13
Declaring a SQLJ Connection Context Class
A connection context is an object of a connection context class, which you define using a SQLJ
connection declaration.
The following statement declares the context class MyConnectionContext.
#sql context MyConnectionContext;
Context classes extend sqlj.runtime.ref.ConnectionContextImpl and implement

sqlj.runtime.ConnectionContext.
Related topics
15-14
Creating a Connection Context Object
Before it can be used in an SQLJ statement, a declared connection context must be created.
The following statement creates an instance thisCtx for the connection context class
MyConnectionContext:
MyConnectionContext thisCtx = new MyConnectionContext

(myPath, myUID, myPasswd, autocommit)
Related topics
15-15
Debugging SQLJ Files
You debug SQLJ code by debugging the SQLJ source directly, not the generated Java code.
SQLJ is debugged in JDeveloper in the same manner as other source code.
See Performance and Debugging in the Oracle9i SQLJ Developer's Guide and Reference at
Related topics

15-16
Setting SQLJ Translator Options
To configure the SQLJ compiler for the current project, open the Project Settings dialog by
choosing Project | Project Settings, and navigate to Configurations | Development | Compiler |
SQLJ. For more information, click Help.
Related topics
15-17
Using SQLJ Connection Options
These options specify the database connection for online checking. All of these options (except
for driver) may be tagged with a ConnectionContext type:
-option@ConnectionContextType=value
This permits the use of separate exemplar schemas for each of the connection contexts.
If you omit the connection context type, when specifying one of these options, the value will be
used for any SQL statements that use the default connection context. If no option value is given
at a specific ConnectionContextType, then the option value for the default connection context is
used.
-user
The user option specifies the username for connecting to a database in order to perform
semantic analysis of the SQL expressions embedded in a SQLJ program. It contains the
username, for example:
-user=scott
The user command line option may include a connection context type. For example:
-user@Ctx1=Scott
Whenever a username is required for the connection to a database context Ctx1, SQLJ uses
the user option that was tagged with Ctx1. If it can not find one, SQLJ issues a message and
looks for an untagged user option to use instead.
Specifying a user value indicates to SQLJ that online checking is to be performed. If you do not
specify the user option, SQLJ does not connect to the database for semantic analysis. There is
no default value for the user option.
If you have turned on online checking by default (by specifying, for example, -user=Scott),
then in order to disable online checking for a particular connection context type Ctx2, you must
explicitly specify an empty user name:
-user@Ctx2=
15-18
-password
The password option specifies a password for the user. The password will be requested
interactively if it is not supplied. This option can be tagged with a connection context type. The
two forms are:
-password=tiger
-password@Ctx1=tiger
-url
This sub-option specifies a JDBC URL for establishing a database connection. The default
value is jdbc:oracle:oci7:@. It can also be tagged with a connection context type:
-url=jdbc:oracle:oci8:@
-url@Ctx1=jdbc:oracle:thin:@<local_host>:1521:orcl
-driver
This option specifies a list of JDBC drivers that should be registered in order to interpret JDBC
connection URLs for online analysis. The default is oracle.jdbc.driver.OracleDriver.
Example:
-driver=sun.jdbc.odbc.JdbcOdbcDriver,oracle.jdbc.driver.OracleDriver
Related topics

15-19
JDBC provides Java programs with low-level access to databases.
The following topics describe aspects of JDBC:
● Choosing a JDBC driver
● Installing a Non-Default JDBC Driver
● Coding a JDBC Connection
● Specifying a JDBC Connection
(OTN) website.
Related topics

About SQL
15-20
Choosing a JDBC Driver
JDBC uses a driver manager to support different drivers, so that you can connect to multiple database
servers. To connect your database application to a data server, you must have available the appropriate
JDBC driver. JDeveloper provides the Oracle 8.1.7: thin and OCI JDBC drivers. OCI for Oracle 8.1.7 is
the default driver. If you wish you may install a non-default JDBC driver.
These considerations may impact your choice of which JDBC driver to use for your application or applet:
● If you are developing an applet, you must use the JDBC thin driver. OCI-based driver classes
cannot be invoked from an applet, because they call native methods, written in C (which violates
the applet security model).
Note 1: The JDBC thin drivers use a subset of the Oracle Net8 protocol, written entirely in Java,
and connect using the TCP/IP protocol. So any data servers that you will be connecting to must
also support Net8 over TCP/IP.
Note 2: There are other restrictions on applets besides the JDBC driver choice. See Browser
Security and JDK Version Considerations at the Oracle Technology Network (OTN) website.
● If you desire maximum portability, you should choose the thin driver. You can connect to either an
Oracle8 or an Oracle7 data server, from either an application or an applet, using the thin driver.
Depending on your choice of driver, some special configuration may be required:
● If you choose to use the OCI driver, you must install the client-side OCI files that correspond to the
version of the OCI driver you will use. These client-side files are available with the server
distribution. For example, if you decide to use the Oracle 8.1.7 OCI driver, you must install the OCI
client-side files that come with the 8.1.7 server distribution. The OCI client-side files must match
the version of the OCI driver you are using, not the version of the database to which you will
connect.
● If you are using the Oracle JDBC/OCI or Oracle Lite JDBC Driver with JDeveloper (JDK 1.2/1.3)
add the
%ORACLE_HOME%/bin directory to java.library.path and sun.boot.library.path in
bin/jdeveloper.ini. They should look like this:
[Java_2]
JDK=java version "JDK1.2.2_JDeveloper"
Java2VM=OJVM
JLP=-Djava.library.path=.;JAVA_ROOT\bin;JAVA_ROOT\jre\bin;C:\ORANT\BIN
SLP=-Dsun.boot.library.path=.;JAVA_ROOT\bin;JAVA_ROOT\jre\bin;C:\ORANT\BIN
15-21
Where JAVA_ROOT is the path to your installed Oracle Home.
● If you are executing applications which use the JNI to call native libraries (DLL files) under
JDeveloper with
JDK 1.2/1.3 it is necessary to edit your project properties. Add to the Java VM Parameters,
under the
Run/Debug tab the following setting:
-Djava.library.path=Path where DLL files are located".
See Requirements and Compatibilities for Oracle JDBC Drivers in the Oracle9i JDBC Developer's Guide
and Reference at the Oracle Technology Network (OTN) website.
Related topics
15-22
Installing a Non-Default JDBC Driver
JDeveloper ships with Oracle JDBC drivers. In certain situations, you may wish to use different
JDBC drivers, for example, to connect to a non-Oracle datasource or to connect to a different
version of Oracle.
To install a non-default JDBC driver:
● Modify your JDeveloper environment.

● Modify each project that will use the alternate driver.
Related topics

Choosing a JDBC driver
15-23
Modifying the JDeveloper Environment for Non-
Default JDBC Drivers
Before you can modify your projects to use a different JDBC driver, you must first modify the
JDeveloper programming environment by performing these steps:
1. Exit from JDeveloper.

2. Open the jdev.conf file in a text editor. This file is located in the JDeveloper bin
directory.
3. Edit JDeveloper's bin/jdev.conf file to add the driver's .zip or .jar archive file.
Use the same format that is used for other included archives.
4. Save and close the file.
Related topics

Modifying a Project to Use a Non-Default JDBC Driver
15-24
Modifying a Project to Use a Non-Default JDBC
Driver
If your JDeveloper programming environment as been modified to allow the use of a non-
default JDBC driver, you can modify the current project to use the new driver by performing
these steps:
1. With the project node selected, choose Project | Project Settings to open the Project
Settings dialog.
2. Navigate to Configurations | Development | Libraries.
3. Create a new library by clicking New. Click Help in the New Library dialog for
instructions.
4. Return to the Libraries project settings page, and in the Available Libraries list, select the
new library, and transfer it to the Selected Libraries list:
5. If necessary, order the list of selected libraries so that the library you have just added
appears before other driver libraries, or libraries that pull in other driver libraries. These
include:
❍ Oracle JDBC
❍ Enterprise Java Beans
If necessary, select the library you added and drag it up to the top of the list.
6. Click OK to save your changes and close the dialog.
Related topics

Modifying the JDeveloper Environment for Non-Default JDBC Drivers
Connection Requirements for Oracle's Type 2 JDBC Drivers (OCI)
15-25
Coding a JDBC Connection
If you are coding using pure JDBC, the following steps are required to make a connection:
1. Import the JDBC classes using the statement
import java.sql.*;
This statement is required for all JDBC programming.
2. Register the Oracle JDBC drivers with the Driver Manager using the statement
DriverManager.registerDriver
(new oracle.jdbc.driver.OracleDriver());
3. Get a connection to a data server using the statement calling one of the
getConnection methods:
Connection conn = DriverManager.getConnection(parameters...);
There are three driver manager getConnection methods, differing in the number and
types of their parameters.
Related topics
15-26
Specifying a JDBC Connection
The driver manager method getConnection has three variants, differing in the number and
types of their parameters.
getConnection (String conn)
The conn parameter is a string of the form
"jdbc:oracle:drivertype:user/password@database"
The drivertype component is one of:
❍ oci8
❍ oci7
❍ thin.
The database component is optional if there is a default database associated

with the installation. If you specify it, it must be one of the following:
● A Net8 name-value pair. For more information, see the Net8 Administrator
documentation.
● For OCI drivers, an entry in the TNSNAMES.ORA file.
● For thin drivers, a string of the form
host_name:port_number:sid
getConnection (String URL, String userid, String passwd)
The conn parameter is a string of the form
"jdbc:oracle:drivertype
or, if you specify the database explicitly,
15-27
"jdbc:oracle:drivertype:@database"
The drivertype and database fields are defined as above.
getConnection (String URL, Properties info)
This variant gathers the connection's parameters from a Properties object. For
example:
java.util.Properties info = new java.util.Properties();

info.addProperty ("user", "scott");
info.addProperty ("password","tiger");
getConnection ("jdbc:oracle:oci8:", info);
Oracle JDBC drivers support other properties as well. The following table lists all
of these properties.
Name Short name Type Description Equivalent to

user (none) String The user name for logging into (none)
the database
password (none) String The password name for (none)
logging into the database
database server String The connect string for the (none)
database
defaultRowPrefetch prefetch Integer The default row prefetch setDefaultRowPrefetch
remarksReporting remarks Boolean True if getTables and setRemarksReporting
getColumns should report
TABLE_REMARKS
Related topics

Coding a JDBC connection
15-28
Accessing Oracle Objects and PL/SQL Packages
using Java
Use JPublisher to access Oracle objects and PL/SQL packages from your Java programs.
JPublisher lets you specify and customize the mapping of Oracle object types, reference types, and
collection types to Java classes in a strongly typed paradigm.
Also, SQLJ programmers who want to call stored procedures declared in PL/SQL packages can
use JPublisher to generate SQLJ wrapper classes for the packages. The SQLJ wrapper classes let
you invoke the PL/SQL stored procedures, and pass and return values from them, directly from
your SQLJ program.
To access Oracle objects and PL/SQL packages using Java:
1. Create the desired object datatypes (Oracle objects) and PL/SQL packages in the database.
It is recommended that any custom classes or interfaces you might use in the Oracle9i
server implement the oracle.sql.CustomDatum interface.
2. Use JPublisher to generate source code — .java and .sqlj files — that represents the
Oracle objects, PL/SQL packages, user-defined types, and REF types.
3. Import these classes into your application code.
4. Use the methods in the generated classes to access and manipulate the Oracle Objects and
their attributes.
5. Compile all classes (the JPublisher-generated code and your code). The SQLJ compiler
compiles the .sqlj files, and the Java or SQLJ compiler compiles the .java files.
6. Run your compiled application.
This process is illustrated in the following figure:
15-29
Related topics

About JPublisher
Generating Java Source Code for Oracle Objects and PL/SQL Packages
15-30
Enhancing JPublisher-Generated Classes
Setting JPublisher Parameters
Browsing the Database Through JDBC Connections
15-31
About JPublisher
JPublisher increases your productivity by letting you access Oracle objects and PL/SQL
packages from your Java programs. JPublisher lets you specify and customize the mapping of
Oracle object types, reference types, and collection types (VARRAYs or nested tables) to Java
classes in a strongly typed paradigm.
SQLJ programmers who want to call stored procedures declared in PL/SQL packages can use
JPublisher to generate SQLJ wrapper classes for the packages. The SQLJ wrapper classes let
you invoke the PL/SQL stored procedures, and pass and return values from them, directly from
your SQLJ program.
The following topics describe aspects of JPublisher:
● Object Types and JPublisher

● PL/SQL Packages and JPublisher
● About Java Mapping Options
● JPublisher Output
● Properties Files
● JPublisher Limitations
See Oracle9i JPublisher User's Guide at the Oracle Technology Network (OTN) website.
Related topics
Accessing Oracle Objects and PL/SQL Packages using Java
15-32
About Object Types and JPublisher
JPublisher allows your Java language applications to use user-defined object types in an
Oracle9i server. These objects can be user-defined objects, VARRAYs, nested tables, index-by
tables, or REFs to object types. If you intend to have your Java-language application access
object data, then it must represent the data in a Java format. JPublisher helps you do this by
creating the mapping between object types and Java classes, and between object attribute
types and their corresponding Java types.
The mapping is determined by:
● The selected Java mapping option, and

● The object's datatype category.
Additionally, JPublisher generates get and set accessor methods for each of the object’s
attributes, and optionally generates a wrapper method for each of the object’s stored
procedures. A wrapper method is a method that invokes a stored procedure that executes in
the database. Wrapper methods generated by JPublisher are always instance methods even
when the original object methods are static.
The following table summarizes the types of Java classes that JPublisher generates for objects.
SQL type Java class mapping
user-defined object type Java class with accessor methods to get and set each attribute of the object, and
optional wrapper methods to call the object's stored procedures.
VARRAY, Java classes that can get and set the following:
nested table,
index-by table
● The entire array
● A subset of the array
● An individual element of the array
REF to an object type Java class to get and set the object to which the REF refers.
Classes generated by JPublisher implement either the oracle.sql.CustomDatum interface

or the java.sql.SQLData interface. Either interface makes it possible to transfer object type
instances between the database and your Java program. It is recommended that you use the
15-33
oracle.sql.CustomDatum interface.
Related topics
About JPublisher
About JPublisher Output
15-34
About PL/SQL Packages and JPublisher
You might want to call stored procedures in a PL/SQL package from your Java application. The
stored procedure can be implemented in PL/SQL, or it can be a Java method that has been
published to PL/SQL. Java arguments and functions are passed to and returned from the
stored procedure.
To help you do this, you can direct JPublisher to create a class containing a wrapper method
for each subprogram in the package. Like object methods, the wrapper methods generated for
each subprogram are always instance methods even when the original method is static. The
wrapper methods that JPublisher generates provide a convenient way to invoke PL/SQL stored
procedures from Java code or to invoke a Java stored procedure from a client Java program.
JPublisher lets you generate Java wrappers by selecting an individual package, or by selecting
the PL/SQL Packages node to select all of the packages in the schema. If you call PL/SQL
code that includes subprograms at the top-level, JPublisher generates a single class containing
a wrapper method for each top-level subprogram.
PL/SQL Functions
For PL/SQL functions, whether you generate Java for a single PL/SQL function or multiple
functions, JPublisher generates a single class. For a single function, the class contains a single
wrapper method for the function. For multiple functions, the class contains a wrapper method
for each function.
PL/SQL Procedures
For PL/SQL procedures, whether you generate Java for a single PL/SQL procedure or multiple
procedures, JPublisher generates a single class. For a single procedure, the class contains a
single wrapper method for the procedure. For multiple procedures, the class contains a
wrapper method for each procedure.
Related topics
About JPublisher
15-35
About Java Mapping Options
The mapping options you select for datatype categories determine the set of type mappings
that JPublisher uses to translate object types and PL/SQL packages to Java classes:
● For object types, JPublisher applies the mappings to the object's attributes and to the
arguments and results of any methods included with the object. The mappings control
the types that the generated accessor methods should support, that is, what types the
get methods should return and the set methods should require.
● For PL/SQL packages, JPublisher applies the mappings to the arguments and results of
the methods.
● For a collection type (that is, nested tables and VARRAYs), JPublisher applies the
mappings to the element type of the collection.
● For user-defined types (usertypes category) JPublisher generates CustomDatum
classes or SQLData classes and generates code for collection and REF types.
You may select from the following mapping options:
● Oracle Mapping represents data in PL/SQL format.

● JDBC Mapping represents simple data types as Java primitive types.
● Object JDBC Mapping represents simple data types as Java wrapper classes.
● BigDecimal Mapping uses a common class to represent all numeric types.
See Details of Datatype Mapping in the Oracle9i JPublisher User's Guide at the Oracle
Technology Network (OTN) website.
Related topics
About Object Types and JPublisher

About Mapping Built-In Types builtintypes)
About Mapping LOB Types (lobtypes)
About Mapping Numeric Types (numbertypes)
15-36
About Mapping User-Defined Types (usertypes)
15-37
About Mapping Built-In Types (builtintypes)
Syntax: jpub.builtintypes={jdbc|oracle}
The builtintypes parameter (and its JPublisher Wizard equivalent Built-in Types) controls
type mappings for all the built-in database types except the LOB and BFILE types (controlled
by the lobtypes parameter) and the different numeric types (controlled by the numbertypes
parameter). The following table lists the database types affected by the builtintypes
parameter, and shows their Java type mappings for builtintypes=oracle and for
builtintypes=jdbc (the default).
PL/SQL Datatype Oracle Mapping Class JDBC Mapping Class

CHAR, CHARACTER, LONG, STRING, VARCHAR, oracle.sql.CHAR java.lang.String
VARCHAR2
RAW, LONG RAW oracle.sql.RAW byte[ ]
DATE oracle.sql.DATE java.sql.Timestamp
Related topics
15-38
About Mapping LOB Types (lobtypes)
Syntax: lobtypes={jdbc|oracle}
The lobtypes parameter (and its JPublisher Wizard equivalent LOB Types) controls type
mappings for the LOB types. The following table shows how these types are mapped for
lobtypes=oracle (the default) and for lobtypes=jdbc.
PL/SQL Datatype Oracle Mapping Class JDBC Mapping Class

CLOB oracle.sql.CLOB java.sql.CLOB
BLOB oracle.sql.BLOB java.sql.BLOB
The BFILE type does not appear in this table, because it has only one mapping. It is always
mapped to oracle.sql.BFILE, because there is no java.sql.BFILE class.
The java.sql.CLOB and java.sql.BLOB classes are new in JDK 1.2. If you use JDK 1.1,
you should not select lobtypes=jdbc.
Related topics
15-39
About Mapping Numeric Types (numbertypes)
Syntax: jpub.numbertypes={jdbc|objectjdbc|bigdecimal|oracle}
The numbertypes parameter (and its JPublisher Wizard equivalent Number Types) controls
type mappings for numeric PL/SQL types. Four choices are available:
● The jdbc mapping maps most numeric database types to Java primitive types such as
int and float, and maps DECIMAL and NUMBER to java.math.BigDecimal.
● The objectjdbc mapping (the default) maps most numeric database types to Java
wrapper classes such as java.lang.Integer and java.lang.Float, and maps
DECIMAL and NUMBER to java.math.BigDecimal.
● The bigdecimal mapping maps all numeric database types to
java.math.BigDecimal.
● The oracle mapping maps all numeric database types to oracle.sql.NUMBER.
The following table lists the PL/SQL types affected by the numbertypes option, and shows
their Java type mappings for numbertypes=jdbc and numbertypes=objectjdbc (the
default).
PL/SQL Datatype JDBC Mapping Class Object JDBC Mapping Class

BINARY_INTEGER, INT, INTEGER, NATURAL, int java.lang.Integer
NATURALN, PLS_INTEGER, POSITIVE,
POSITIVEN, SIGNTYPE
SMALLINT short java.lang.Integer
REAL float java.lang.Float
DOUBLE PRECISION, FLOAT double java.lang.Double
DEC, DECIMAL, NUMBER, NUMERIC java.math.BigDecimal java.math.BigDecimal
Related topics
15-40
15-41
About Mapping User-Defined Types (usertypes)
Syntax: jpub.usertypes={oracle|jdbc}
The usertypes parameter (and its JPublisher Wizard equivalent User Types) controls
whether JPublisher generates CustomDatum classes or SQLData classes for user-defined
types:
● When usertypes=oracle (the default), JPublisher generates CustomDatum classes

for object, collection, and REF types.
● When usertypes=jdbc, JPublisher generates SQLData classes for object types.
JPublisher does not generate anything for collection or REF types. Use
java.sql.Array for all collection types, and java.sql.Ref for all REF types.
Related topics
15-42
About JPublisher Output
JPublisher generates a Java class for each object type that it translates. For each object type,
JPublisher generates a type.java file (or a type.sqlj file if wrapper methods were
requested) for the class code and a typeRef.java file for the code for the REF class of the
Java type. For example, if you define an EMPLOYEE PL/SQL object type, JPublisher
generates an employee.java file and an employeeRef.java file.
For each collection type (nested table or VARRAY) it translates, JPublisher generates a
type.java file. For nested tables, the generated class has methods to get and set the nested
table as an entire array and to get and set individual elements of the table. JPublisher
translates collection types when generating CustomDatum classes but not when generating
SQLData classes. JPublisher does not generate a typeRef.java file for nested tables or
VARRAYs. This is because PL/SQL does not allow a REF to be made to these types.
For PL/SQL packages, JPublisher generates classes containing wrapper methods as .sqlj
files. JPublisher also generates method wrappers in your class that invoke the associated
package methods executing in the server. This is specified by the Include Methods option.
Note: Since version 8.1.6, the wrapper methods that JPublisher generates to invoke stored
procedures are in SQLJ only. Classes generated by JPublisher that contain wrapper methods
must be compiled by SQLJ.
Related topics
About JPublisher
Generating Java Code for Oracle Objects and PL/SQL Packages
15-43
About Properties Files
A properties file is an optional text file where you can specify frequently used parameters or
parameters which you cannot specify in the JPublisher Wizard. Note that if you need only the
default output of JPublisher, then you do not need a properties file.
The properties file is designated in the JPublisher wizard.
In a properties file, you enter one (and only one) parameter and its associated value on each
line. Each parameter name must be preceded with the prefix "jpub." and you cannot use any
white space within a line. You can enter any parameter except the props parameter in the
properties file. JPublisher processes the parameters, in order, from the top of the list to the
bottom. If you specify a parameter more than once, JPublisher uses the last encountered value.
A properties file might contain the following:
jpub.case=lower
jpub.package=package1
jpub.numbertypes=jdbc
jpub.lobtypes=jdbc
jpub.builtintypes=jdbc
jpub.usertypes=jdbc
jpub.omit_schema_names
jpub.methods=true
jpub.input=mySchema.txt
jpub.sql=employee:oracleEmployee
Related topics
Setting JPublisher Parameters

Generating Source Code for Oracle Objects and PL/SQL Packages
15-44
About JPublisher Limitations
For information on this topic see JPublisher Limitations in the Oracle9i JPublisher User's Guide
at the Oracle Technology Network (OTN) website.
Related topics
About JPublisher
15-45
Generating Java Source Code for Oracle Objects
and PL/SQL Packages
To generate Java classes for an object type or package, right-click an object type or package in
JDeveloper's Navigator pane. You can also right-click a folder, such as the Object Types folder
or the PL/SQL Packages folder, to generate Java classes for all of the objects or packages it
contains.
Choose Generate Java from the menu to open the JPublisher Wizard. Click Help for
instruction on using the wizard.
The generated classes are added to JDeveloper's Navigator pane for the Project and Package
you specified.
Related topics
15-46
You might want to enhance the functionality of a custom Java class generated by JPublisher by
adding methods and transient fields to it.
Ways to enhance JPublisher-generated classes
● Extend the class. That is, treat the JPublisher-generated class as a superclass, write a
subclass to extend its functionality, and then map the object type to the subclass.
● Write a new class that delegates the functionality provided by the JPublisher-generated
class to a field whose type is the generated class.
● Add methods to the class. This is not recommended if you anticipate running JPublisher
at some future time to regenerate the class. If you regenerate a class that you have
modified in this way, your changes (that is, the methods you have added) will be
overwritten. Even if you direct JPublisher output to a separate file, you will still need to
merge your changes into the file.
Related topics

15-47
Extending JPublisher-Generated Classes
The Declaration Name and Use Name fields in the JPublisher Wizard give you the flexibility of
extending generated classes. In the Declaration Name field, enter the name of the class that
you want JPublisher to generate from the given database object. In the Use Name field, enter
the name of the class that your Java program will use to represent the database object.
When publishing an object type where Use Name is different from Declaration Name,
JPublisher creates a declaration_name.sqlj file and a use_nameRef.java file, where
use_name represents the object type in your Java program.
JPublisher expects that you have written the class use_name, which extends
declaration_name. If you do not provide this class, then the use_nameRef.java file will not
compile.
For example, suppose you want JPublisher to generate the class JAddress from the PL/SQL
object type ADDRESS. You have also written a class, MyAddress, to represent ADDRESS
objects, where MyAddress either extends the functionality provided by JAddress or has a
JAddress field.
Under this scenario, select ADDRESS in the Database Browser and right-click Generate Java. In
the JPublisher Wizard, enter JAddress in the Declaration Name field and MyAddress in the
Use Name field. JPublisher will generate the custom Java class JAddress, and map the
ADDRESS object to the MyAddress class—not to the JAddress class. JPublisher will also
produce a reference class for MyAddress, not JAddress.
This is how JPublisher will alter the code it generates:
● JPublisher will generate the REF class MyAddressRef rather than JAddressRef.
● JPublisher will use the MyAddress class, instead of the JAddress class, to represent
attributes whose database type is ADDRESS. This situation will occur in classes
generated by JPublisher, or in classes written by the user.
● JPublisher will use the MyAddress class, instead of the JAddress class to represent
VARRAY and nested table elements whose database type is ADDRESS.
● JPublisher will use the MyAddress factory, instead of the JAddress factory, when the
CustomDatumFactory interface is used to construct Java objects whose database type
is ADDRESS. This situation will occur both in classes generated by JPublisher, and in
classes written by the user.
15-48
The class that you create (for example, MyAddress.java) must have the following features:
● The class must have a no-argument constructor. The easiest way to construct a properly
initialized object is to invoke the constructor of the superclass, either explicitly or
implicitly.
● The class must implement the CustomDatum interface. The simplest way to do this is to
inherit the toDatum() method from the superclass.
● You must also implement the CustomDatumFactory interface, either in the same class
or in a different one. For example, you could have a class Employee that implements
CustomDatum and a class EmployeeFactory that implements
CustomDatumFactory.
Related topics

15-49
Setting JPublisher Options
JPublisher options can be set for these types of PL/SQL subprograms in your schema:
● Functions
● Package Bodies
● Packages
● Procedures
To set JPublisher options for PL/SQL subprograms in a schema, select the folder for the
subprogram type, right-click, and choose Generate Java to launch the JPublisher wizard. Click
Help for further instructions.
These JPublisher options can be set from within JDeveloper:
● methods
● omit_schema_names
● package
See JPublisher Options in the Oracle9i JPublisher User's Guide at the Oracle Technology
Network (OTN) website.
Related topics
15-50
Generating Classes for Packages and Wrapper
Methods for Methods
Set the JPublisher methods option in the JPublisher wizard by checking the Include Methods
box.
The value of the methods option determines whether JPublisher generates classes for PL/SQL
packages and wrapper methods for methods in packages and object types.
If selected, JPublisher generates PL/SQL classes and methods. This is default behavior.
If not selected, JPublisher does not generate PL/SQL classes and methods.
Related topics
15-51
Omitting the Schema Name from Generated Names
Set the JPublisher omit_schema_names option in the JPublisher wizard by checking the Omit
Schema Names box.
The value of the omit_schema_names option determines whether certain object type and
PL/SQL wrapper names generated by JPublisher include the schema name. If an object type or
wrapper name generated by JPublisher does not include the schema name, the type or
wrapper is looked up in the schema associated with the current connection when the code
generated by JPublisher is executed. This makes it possible for you to use classes generated
by JPublisher with a connection other than the one used when JPublisher was invoked.
However, the type or package must be declared identically in the two schemas.
If selected, an object type or wrapper name generated by JPublisher is qualified with a schema
name only if:
● You declare the object type or wrapper in a schema other than the one to which
JPublisher is connected.
OR
● You declare the object type or wrapper with a schema name in the properties file or
INPUT file.
That is, an object type or wrapper from another schema requires a schema name to identify it,
and the use of a schema name with the type or package in the properties file or INPUT file
overrides the omit_schema_names option.
If not selected, every object type or wrapper name generated by JPublisher is qualified with a
schema name. This is default behavior.
Related topics
15-52
Setting the Package Name for Generated Classes
Set the JPublisher package option in the JPublisher wizard by providing a name in the
Package field.
The package option specifies the name of the Java package JPublisher generates. The name
of the package appears in a package declaration in each Java file. The directory structure also
reflects the package name. An explicit name in the INPUT file, after the sql option, overrides
the value given to the package option.
Related topics
15-53
Improving Application Performance with Java
Stored Procedures
A Java stored procedure is a Java method that resides and runs in a database. Stored
procedures can help improve the performance of database applications because they are
efficient: they are stored in the RDBMS in executable form, and run in the RDBMS (rather than
the client) memory space.
Use JDeveloper to write methods in Java for new stored procedures and deploy them to the
Oracle9i server. When you deploy a Java class to Oracle9i, you can select the methods that
you want to publish to PL/SQL for use as stored procedures. Methods can be deployed
together in a package or separately.
These topics describe aspects of using Java stored procedures:
1. Create stored procedures

2. Deploy stored procedures
3. Test stored procedures
4. Invoke stored procedures
5. Browse stored procedures
6. Delete stored procedures
See Oracle9i Java Stored Procedures Developer's Guide at the Oracle Technology Network
(OTN) website.
Related topics
About Java Stored Procedures

15-54
A stored procedure is a program that resides and runs in a database. Application developers
can use stored procedures to help improve the performance of a database application.
Procedure calls are quick and efficient because a stored procedure is compiled once and
stored in an executable form. Because a stored procedure runs in the RDBMS memory space,
complex functions run faster than a routine run by a client. You can also use stored procedures
to group PL/SQL statements so that they are executed in a single call. This reduces network
traffic and improves round-trip response times. By designing applications around a common set
of stored procedures, you can avoid redundant coding and increase your productivity.
A Java stored procedure contains Java public static methods that are published to PL/SQL and
stored in an Oracle database for general use. To publish Java methods, you write call
specifications, which map Java method names, parameter types, and return types to their
PL/SQL counterparts. This allows a Java stored procedure to be executed from an application
as if it were a PL/SQL stored procedure. When called by client applications, a Java stored
procedure can accept arguments, reference Java classes, and return Java result values.
Any Java class can be deployed to Oracle9i and the conforming methods of the class can be
published to PL/SQL as stored procedures. These Java stored procedures can then be
executed from an application as if they were PL/SQL stored procedures. Java stored
procedures can be an entry point for your application into other (Java and non-Java)
procedures deployed to Oracle9i.
Deploying and publishing Java stored procedures to Oracle9i generates call specs that act as
PL/SQL wrappers for each of the methods selected for publishing. These wrappers can be
called by PL/SQL queries from any enterprise application that uses PL/SQL to access data in
Oracle9i.
Related topics
Improving Performance with Java Stored Procedures

15-55
Creating Java Stored Procedures
Create Java stored procedures by first developing business application logic in a Java class
file. Declare methods that are to become stored procedures as public static.
Use the code editor in JDeveloper to add and edit business logic in the Java class. During
deployment to Oracle9i, all public static methods included in the class file are available to be
published to PL/SQL as stored procedures. You can choose which public static methods in the
class to be published to PL/SQL.
There are different JDeveloper Java stored procedure creation scenarios:
● Use an existing Java class and make any necessary edits to the public static methods in
the class that will be deployed to Oracle9i. The existing class could include public static
methods used for validation or database triggers. The methods in the class might also be
in local use by several applications. These methods could be deployed to Oracle9i and
used by multiple applications from the database. The deployed methods could also
supplement existing PL/SQL stored procedures and functions.
● Create a new class with methods designed for publishing as stored procedures. Use the
code editor in JDeveloper to create the public static methods that will be exposed as
stored procedures. Write in industry-standard Java and use the original Java class for
other application deployments. In Oracle9i, this programming could supplement existing
PL/SQL stored procedures.
For example, assume the following Java package Welcome was created with the public class
Greeting and the public static method Hello().
package Welcome;
public class Greeting {
public static String Hello() {
return "Hello World!";
}
}
When this package, Welcome, is deployed to Oracle9i and the Hello() method is published
there, the call spec for the package as viewed in the JDeveloper Database Browser looks like
this:
15-56
PACKAGE WELCOME AS
FUNCTION HELLO RETURN VARCHAR2
AS LANGUAGE JAVA
NAME 'Welcome.Greeting.Hello() return java.lang.String'
END WELCOME;
Related topics

Deploying Java Stored Procedures
15-57
Create a deployment profile for Java stored procedures, then deploy the classes and,
optionally, any public static methods in JDeveloper using the settings in the profile.
Deploying to the database uses the information provided in the Deployment Profile Wizard and
two Oracle9i utilities:
● loadjava loads the Java class containing the stored procedures to Oracle9i.
● publish generates the PL/SQL call spec wrappers for the loaded public static methods.
Publishing enables the Java methods to be called as PL/SQL functions or procedures.
Related topics

What JDeveloper Does when You Deploy a Java Stored Procedure
Loading and Publishing Java Stored Procedures in the Oracle9i Database
15-58
What JDeveloper Does when You Deploy a Java
Stored Procedure
The following figure illustrates the loading and publishing components of stored procedure
deployment.
To deploy stored procedures to Oracle9i, first use the Deployment Profile Wizard to create a
complete deployment profile that identifies all of the deployment information. Deployment
profiles are created and stored for later use in a Deployment folder within a project. When
multiple profiles are created for an object type, the profile names are incremented (for example
15-59
Profile1, Profile2, etc.). In the project navigator and the filesystem, deployment profiles are
saved in the Deployment folder in the form Profile#.prf.
By default, public static methods selected for deployment as Java stored procedures are
published to Oracle9i in a package that is named after the JDeveloper project. By editing the
deployment profile or creating multiple deployment profiles you can publish the same method to
multiple packages. You can also choose to publish methods without a package as multiple top-
level functions or procedures.
The deployment process uses the loadjava utility to load the Java class(es) into Oracle8i.
Additionally, deployment creates call specs that act as PL/SQL wrappers for the Java public
static methods in the classes deployed. PL/SQL applications call the Java method through its
call spec.
Related topics
15-60
Testing Stored Procedures
You can test stored procedures you have deployed to Oracle9i by running an application that
executes those procedures or by running any SQL client tool. These SQL client tools can be
invoked from within JDeveloper:
● SQL Worksheet
● SQL*Plus
All testing and running of applications must include a connection to the database that accesses
the username space into which the Java Stored Procedures are deployed.
Test stored procedures depending on how they are deployed:
● In packages
● Separately
Related topics
15-61
Testing Stored Procedures Deployed in Packages
For stored procedures deployed in packages, access the stored procedure by the package
name and/or the stored procedure name set during deployment. The package name may be
the default name taken from the project or another name entered during deployment. The
stored procedure name may be the default name taken from the method name or a name
chosen for the stored procedure during deployment. Stored Procedures may also be deployed
without packages.
For example, assume the following public static method hello()--from the Java package
Welcome and the public class Greeting--was deployed in a package Openings.
package Welcome;
public class Greeting {
public static String Hello() {
return "Hello World!";
}
}
You could execute a PL/SQL query to the deployed stored procedure that executes the public
static method deployed there and returns the result. To invoke SQL*Plus from within
JDeveloper, right-click on a connection or select it from the Tools menu.
With a working connection to the database, your SQL*Plus client could execute the following:
select Openings.Hello() from dual;

Openings.Hello()
yielding
Hello World!
Note: The reference to the stored procedure call spec uses package.method syntax; the
name of the class from which the method originated is not part of the call.
Related topics
15-62
Testing Stored Procedures Deployed Separately
15-63
Testing Stored Procedures Deployed Separately
For stored procedures deployed separately (not in packages), access the stored procedure by
the stored procedure name set during deployment. The stored procedure name may be the
default name taken from the method name or a name chosen for the stored procedure during
deployment. Refer to Selecting Methods and Deployment Type for more information about
stored procedure naming.
For example, for a public static method hello() that was deployed as hello from a class
greeting and package welcome, you could execute a PL/SQL query to the deployed stored
procedure that returns the result.
Assume the above hello() method as the example method, but this time assume it was
deployed without a package.
With a working connection to the database, your SQL*Plus client could execute the following:
select Openings.Hello() from dual;

Openings.Hello()
yielding
Hello World!
Related topics

Testing Stored Procedures Deployed in Packages
15-64
Invoking a Java Stored Procedure
The SQL CALL statement lets you call Java stored procedures, and may be invoked in the
following ways:
● Using SQL
● Using JDBC
● Using SQLJ
● Using PL/SQL
See Calling Stored Procedures in the Oracle9i Java Stored Procedures Developer's Guide at
Related topics
15-65
Invoking a Java Stored Procedure using SQL
In SQL*Plus, you can execute the CALL statement interactively to invoke a Java stored
procedure, using the syntax:
CALL [schema_name.][{package_name | object_type_name}][@dblink_name]

{ procedure_name ([param[, param]...])
| function_name ([param[, param]...]) INTO :host_variable};
where param stands for the following syntax:
{literal | :host_variable}
Host variables (that is, variables declared in a host environment) must be prefixed with a colon.
The following examples show that a host variable
cannot appear twice in the same CALL statement, and that a parameterless subprogram must
be called with an empty parameter list:
CALL swap(:x, :x); -- illegal, duplicate host variables

CALL balance() INTO :current_balance; -- () required
Related topics
15-66
Invoking a Java Stored Procedure using JDBC
Java stored procedures invoked from JDBC must be encapsulated in CallableStatement
objects.
To invoke a Java stored procedure using JDBC:
1. Create a callable statement object.

1. Declare a callable statement object. For example:
private CallableStatement checkIn;
2. Initialize the callable statement object by calling prepareCall on the connection

with a SQL CALL statement for the stored procedure. For example:
checkIn = connection.prepareCall(
"{call NPL.CHECKIN(?, ?, ?)}");
Note that the number of parameters in the stored procedure is represented by the
number placeholders in the SQL call.
3. Register the callable statement object's output parameters. Call

registerOutParameter for each output parameter, identifying it by position,
and declaring its type. For example, if the second parameter is an SQL INTEGER
(which maps to a Java int), and the third is a SQL VARCHAR ( which maps to a
Java String), then:
newCustomer.registerOutParameter(2, Types.INTEGER);
newCustomer.registerOutParameter(3, Types.VARCHAR);
● Execute the callable statement object.
1. Provide the callable statement object's input parameters by calling a set method,
identifying the parameter by position, and assigning it a value. For example, if the first
parameter is an int input parameter:
checkIn.setInt(1, bookID);
15-67
2. Execute the callable statement object. For example:
checkIn.execute();
3. Extract the callable statement object's output parameters. Call a get method for each
output parameter, identifying the parameter by position. The get methods return values
of corresponding Java types. For example:
int daysLate = checkIn.getInt(2);

String title = checkIn.getString(3);
Related topics
15-68
Invoking a Java Stored Procedure using SQLJ
1. Declare and initialize input and in-out variables. For example, if the first parameter is an
int input parameter:
int bookID = scanID();
2. Declare output variables. For example:
int daysLate;
String title;
3. Invoke the stored procedure in a SQLJ statement. In the statement identify the
parameters by name, and designate them as :in, :out, or :inout. For example:
#sql { call NPL.CHECKIN (:in bookID, :out daysLate, :out title)}
Return values will be assigned to output and inout variables.
Related topics
15-69
Invoking a Java Stored Procedure using PL/SQL
Use a CALL statement in the trigger body clause of a PL/SQL statement to invoke a stored
procedure, and pass arguments to it.
The CALL statement's arguments can be:
● Literal values.
● SQL expressions, but not bind variables.
● Column references, qualified by correlation names.
Correlation names are prefixes to column references. Use these names to qualify whether the
reference applies to the existing column value of the row being processed by the trigger or the
value being written by the triggering event:
● OLD refers to the the value of the column prior to the triggering operation.
● NEW refers to the value being assigned to the column by the triggering operation. It is
possible for the trigger body to redefine this value before the triggering operation occurs.
An example of a complete trigger definition:
CREATE TRIGGER check_salary

BEFORE UPDATE OF salary ON employee
CALL salaryCheck(:new.job, :old.salary, :new.salary, :old.employeeID)
Related topics
15-70
Browsing Java Stored Procedures
The call specifications (the PL/SQL wrappers) for Java stored procedure packages and
methods deployed to a database schema can be inspected through an Oracle 9i connection.
Only published Java stored procedures appear as PL/SQL blocks, and only public static
methods in Java classes can be published to PL/SQL when deployed. Java classes can be
deployed without being published, in which case they are not seen in the PL/SQL nodes.
Depending on how Java stored procedures were published, they appear in one of the following
folders under a schema.
● Packages include call specs for Java stored procedures deployed in packages.
● Functions include call specs for Java stored procedures deployed as functions (that
return a value).
● Procedures include call specs for Java stored procedures deployed as procedures
(that do not return a value).
To view a Java stored procedure's call specification, find its node in the schema's hierarchy,
and double-click it. A window will open to display it.
Related topics

15-71
Removing Java Stored Procedures
If you have write permission or are connected as SYS, you can drop a stored procedure from a
database through a JDBC connection.
Depending on how Java stored procedures were published, they appear in one of the following
folders under a schema.
● Packages include call specs for Java stored procedures deployed in packages.
● Functions include call specs for Java stored procedures deployed as functions (that
return a value).
● Procedures include call specs for Java stored procedures deployed as procedures
(that do not return a value).
To drop a stored procedure:
1. In the Navigator, find the right-click the object's node.

2. In the context menu choose Drop.
Related topics
15-72
● Browsing the Database
● Browsing Schemas through JDBC Connections

❍ Creating Database Users
❍ Dropping Database Users

❍ Browsing PL/SQL Subprograms
■ Editing PL/SQL Subprograms
■ Creating New PL/SQL Subprograms

■ Compling PL/SQL Subprograms
❍ Inspecting Tables, Views, and Synonyms

❍ Browsing Sequences
❍ Browsing Deployed Java Classes
❍ Dropping Schema Objects
● Using the SQL Worksheet

● Launching SQL*Plus
❍ Launching SQL*Plus from a Connection Node
❍ Launching SQL*Plus from a PL/SQL File
16-1
JDeveloper provides these options for inspecting and editing objects in the database:
● Browsing Schemas through JDBC Connections

● Using the SQL Worksheet
● Launching SQL*Plus
Related topics
16-2
Browsing Schemas through JDBC Connections
Databases can be browsed through JDBC connections, which are incorporated into the Oracle
and Oracle9i connection types. JDBC connections permit access PL/SQL objects and blocks
and the Java classes that implement those objects. Any database can be browsed, however
only Oracle9i databases permit access to the full range of database objects. When browsing a
third-party database, only generic JDBC objects — tables, views, and synonyms—are visible.
To browse a connection find its node in the Navigator, under the Connections | Database node,
and expand it to show the database's schemas. By default, the connection only allows the
schema of the user identified in the connection to be browsed. Other schemas can be browsed
as well, if the user has the required priveleges.
Expanding a schema will show the folders that represent its object types, and expanding an
object type will show its objects. Select an object to open a view to display its content.
Depending on the type of the object, its structure may also be displayed in the structure pane.
Use the JDBC database browser to:
● Create database users

● Dropping database users
● Browse PL/SQL subprograms
● Browse tables, views, and synonyms
● Browse sequences
● Browse deployed Java classes
● Drop schema objects
Related topics

16-3
Creating Database Users
You can create new database users through a JDBC connection, provided you have
administrator privileges.
To create a new database user:
1. In the Navigation pane, right-click the node of the connection for which you wish to
create a new user, and select New from the context menu to open the New gallery.
2. Choose Database Objects | Database User to open the New Database User dialog.
Related topics
16-4
Browsing PL/SQL Subprograms
Schema objects of the following types are PL/SQL subprograms:
● Functions
● Package Bodies
● Packages
● Procedures
Through the schema you can:
● Edit PL/SQL subprograms

● Create new PL/SQL subprograms
● Compile and save PL/SQL subprograms
● Generate Java source code
Related topics
16-5
Editing PL/SQL Subprograms
PL/SQL objects in the database can be edited through JDBC connections. To edit an object,
find its node under the connection's node, and open editor for an object by either double-
clicking its node, or by right clicking its node and choosing Code Editor from the context menu.
Related topics

Creating PL/SQL Subprograms
Compiling PL/SQL Subprograms
16-6
Creating New PL/SQL Subprograms
New PL/SQL objects of the following types can be created in the database through a JDBC
connection:
● Functions
● Package Bodies
● Packages
● Procedures
To create a new PL/SQL object:
1. Right-click on the node for the schema that will contain the object, and choose New
PL/SQL Subprogram from the context menu.
2. In the New PL/SQL Subprogram dialog, enter an Object Name for the subprogram, and
and choose the Object Type from the dropdown list.
3. Click OK. A skeleton definition will be created and opened in the PL/SQL editor.
Related topics

16-7
To compile a PL/SQL subprogram:
1. Open the subprogram in the PL/SQL editor, and edit the text as desired.
2. Right-click on the subprogram, and choose Make from the context menu. This saves and
compiles the code by sending the source to the database as a CREATE OR REPLACE
FUNCTION statement.
Invoking Make causes the subprogram to be modified in the database, regardless of the
success of the compilation. Any previous definition of the subprogram will be lost.
Related topics

Creating PL/SQL Subprograms
16-8
Inspecting Tables, Views, and Synonyms
Expand a schema's Table and View nodes to see the nodes for their defined objects. To view
an object, either double-click its node, or right click its node and choose Table Viewer from the
context menu. A table viewer will open, and the structure explorer will display a navigable
representation of the tree's columns and indices.
A synonym can be viewed only if it refers to a table.
The Table Viewer has two tabs:
● The Data tab shows the objects content in tabular form.

● The Structure tab shows a table describing the properties of the object's columns. For
each column the following information is shown:
PK contains a checkmark if this attribute is the table's primary key and an X otherwise
Name the attribute's variable name
Type the attribute's SQL type
Size the attribute's length or precision (total number of significant digits)
Scale for numeric types, the attribute's scale (number of digits to the right of the decimal point)
Allow Nulls contains a checkmark if the attribute may be null (unset) and an X otherwise
Related topics
16-9
Browsing Sequences
Expand a schema's Sequence node to see the nodes for the defined sequences. To view a
sequence, either double-click its node, or right click its node and choose Sequence Viewer from
the context menu.
The Sequence Viewer displays a table showing the following information for the sequence:
Minimum Value The smallest value the sequence can produce

Maximum Value The largest value the sequence can produce
Increment By The increment by which the sequence increases (decreases if negative)
Cycle Displays a checkmark if the sequence cycles back to its minimum value after generating its
maximum value (or vice versa); displays an X if the sequence halts
Ordered Displays a checkmark if the sequence is guaranteed to generate numbers in the order of
request; displays an X otherwise
Cache Size How many sequence numbers are read into the cache at once
Last Value The last value the sequence has produced
Related topics
16-10
Browsing Deployed Java Classes
The Java Classes folder under a schema contains the compiled Java .class files, deployed
Java source, and other Java resources such as XML files. Double-click on a node to display its
contents.
If you select a resource file or one containing source code, the browser's Information pane
displays the file.
When a Java .class file is opened the browser invokes the API Decompiler to generate the
source stubs of the class. The class view shows:
● The class's package

● An approximation of the class's import block
● The class's declaration
● The class's data members
● The declarations (but not the implementations) of the class's methods
The exact import block and the implementations of the methods cannot be reconstructed from
the compiled code.
Related topics
16-11
Dropping Schema Objects
To drop an object from a schema:
1. Right-click the object's node and choose Drop.

2. In the Drop Confirmation dialog click Yes to delete the object, or No to leave the schema
unchanged.
The SQL worksheet can be used to drop objects and users.
The Oracle9i command-line utility dropjava can also be used to drop Java sources, binaries,
and resources from a schema.
Related topics

Using the SQL Worksheet
16-12
Using the SQL Worksheet
Use the SQL Worksheet to enter SQL statements, execute them, and inspect their execution
plans.
To open the SQL viewer right-click on a connection node an choose SQL Viewer from the
context menu. The SQL Viewer has two panes; SQL statements are entered into the upper
pane, and when executed the result is displayed in the lower pane.
Use the SQL Worksheet to:
● Execute SQL statements. Enter a statement into the upper pane and click the Execute
button. The query results will be displayed in the Results pane.
● View a SQL statement's execution plan. Enter a statement into the upper pane and click
the Explain button. To get the execution plan, you need to have access to a tale
which stores he information for viewing. If the plan table does not yet exist, a dialog box
will open to ask if it should be created. Click OK. The lower part of the SQL Worksheet
will display the execution plan. On the left side the levels of the plan are displayed in
outline form. Select a level to see its details on the right side.
If you have more than one SQL statement in the SQL Worksheet, highlight a statement to
select it before clicking Execute or Explain.
See the ">Oracle9i SQL Reference at the Oracle Technology Network (OTN) website at
http://download-west.oracle.com/otndoc/oracle9i/901_doc/server.901/a90125/toc.htm.
Related topics
16-13
Launching SQL*Plus
JDeveloper launches SQL*Plus by invoking an external application, the SQL*Plus Executable.
Before launching SQL*Plus you must provide the path to this application. Choose Tools |
Preferences | SQL*Plus, and click Help for for further instructions.
SQL*Plus may be launched in either of these ways:
● From a connection node

● From a SQL (.sql) file
Related topics

16-14
Launching SQL*Plus from a Connection Node
In the System Navigator pane, right-click on a connection node in the Connections folder, and
select SQL*Plus.
The executable specified on the Tools | Preferences | SQL*Plus page will be used to make the
connection. If no executable has been specified the SQL*Plus item will be disabled.
Related topics
Launching SQL*Plus
Launching SQL*Plus from a SQL File
16-15
Launching SQL*Plus from a SQL File
A SQL*Plus connection can be established through a SQL (.sql) node, providing one or more
connection nodes already exist.
In the JDeveloper Navigator pane, right-click on a SQL file. Select Invoke SQL*Plus. and then
select a connection in the submenu. The default executable will be used, if one has previously
been selected; otherwise the SQL*Plus dialog will open.
Related topics
Launching SQL*Plus
Launching SQL*Plus from a Connection Node
16-16
Using Source Control Support
● Using Source Control Support
● Using Oracle9i SCM Support

❍ Oracle9i SCM Glossary
❍ Oracle9i SCM - Best Use Recommendations

❍ Oracle9i SCM Essentials
■ About Workareas
■ About Workarea Rules

■ About Branching
■ About Configurations
■ About Oracle9i SCM Repositories
■ About Security and Access Rights
■ About Synchronization
❍ Setting Up JDeveloper to Use Oracle9i SCM

■ Configuring JDeveloper to Use Oracle9i SCM
■ Creating an Oracle9i SCM Connection

■ Creating a New Workarea
■ Selecting a Workarea
■ Editing Workarea Rules
■ Deleting an Oracle9i SCM Connection
■ Disconnecting from an Oracle9i SCM Repository
❍ Branching with Oracle9i SCM

■ Beginning a Private Branch in Oracle9i SCM
■ Ending a Private Branch in Oracle9i SCM

■ Comparing Files in Oracle9i SCM
■ Merging File Versions in Oracle9i SCM
■ Canceling a Private Branch in Oracle9i SCM
❍ Managing Files in Oracle9i SCM
17-1
■ Adding a File to Oracle9i SCM
■ Checking In a File to Oracle9i SCM
■ Checking Out a File from Oracle9i SCM
■ Undoing an Oracle9i SCM Checkout
■ Listing Oracle9i SCM Checkouts
■ Mapping Oracle9i SCM Repository Folders to File System Directories
■ Comparing Files in Oracle9i SCM
■ Merging File Versions in Oracle9i SCM
■ Displaying the Version History of an Oracle9i SCM File
■ Displaying the Event History of an Oracle9i SCM File
● Using Rational ClearCase With JDeveloper

❍ Configuring JDeveloper to Use Rational ClearCase
❍ Adding a File to ClearCase

❍ Removing a File from ClearCase
❍ Checking In a File to ClearCase
❍ Checking Out a File From ClearCase
❍ Undoing a ClearCase Checkout
❍ Listing ClearCase Checkouts
❍ Comparing Files Checked In to ClearCase
❍ Displaying the History of a ClearCase File
❍ Displaying the Status of a ClearCase File
● Using Concurrent Versions System (CVS) With JDeveloper

❍ Configuring JDeveloper to Use CVS
❍ Importing a JDeveloper Project Into CVS

❍ Checking Out a CVS Project
❍ Adding a File to CVS
❍ Removing a File from CVS
❍ Updating a File in CVS
❍ Committing a File to CVS
17-2
❍ Comparing Files In CVS
❍ Displaying the Log for a CVS File
❍ Displaying the Status of a CVS File
● Using Your Own Source Control System

❍ Writing a Source Control Addin for JDeveloper
❍ More on Source Control Addin Utilities
17-3
Using Source Control Support
Source control is the process of maintaining multiple versions of software development objects
and is the most basic requirement for a software configuration management system.
JDeveloper supports the following source control technologies: Oracle9i Software Configuration
Manager (SCM), Rational ClearCase and Concurrent Versions System (CVS).
Important: Oracle9i SCM Connections can only be created if the Active Source Control Addin has
been defined as Oracle9i Software Configuration Manager in the Source Control section of the Tools
| Preferences dialog.
The following topics describe how to use these supported source control technologies with
JDeveloper.
● Using Oracle9i SCM Support
● Using Rational ClearCase Support
● Using Concurrent Versions System (CVS) Support
You can also use your own source control technologies with JDeveloper by writing a source control
addin. For more information, see Using Your Own Source Control System With JDeveloper.
17-4
Using Oracle9i SCM Support
JDeveloper support for Oracle9i Software Configuration Manager (SCM), formerly known as
Oracle Repository, brings the power of source control systems to JDeveloper users. Versioning
operations and tools can be invoked directly from the menu bar in the JDeveloper IDE, and
through context menu operations in the Navigator pane. Enabling source control from within the
JDeveloper IDE, as opposed to using non-integrated external tools, enables a more productive
interaction because:
● There is less context switching between development tools and versioning tools.
● The source control service is tuned to the requirements of Internet development projects
involving Java, JSP, DDL, and other source, executable, and documentation files. Either
single files or whole projects can be checked in and checked out.
Important: Oracle9i SCM Connections can only be created if the Active Source Control Addin has
been defined as Oracle9i SCM in the Source Control section of the Tools | Preferences dialog, by
choosing File | Source Control | Enable.
By integrating the Software Configuration Manager with JDeveloper, powerful source control
features are added to the IDE. You have the ability to:
● Invoke versioning tools and utilities such as the Version History Viewer and the Compare
Tool, and Merge Tool from within JDeveloper.
● Perform fine-grained, file-level configurations (such as patches, and so on) for the Java
files.
● Work on files while disconnected from the repository.
Note: JDeveloper does not support connecting to and working against shared workareas, only
connecting to and working against private workareas. This ensures that no unintentional loss of data
occurs where one developer overwrites others developer's work. JDeveloper does, however, support
shared workareas for coordination purposes only: a shared workarea can be used as the basis for
defining one or more private workareas. The shared workarea enables a configuration to be
produced that can be shared by many developers in their private workarea definitions, enabling
effective team based development.
Oracle9i SCM repositories used by Oracle9i JDeveloper can only be installed and configured
using Oracle9i SCM client tools installed on Windows machines. For more information on
Oracle9i SCM, please refer the online documentation for that product, or refer to
17-5
http://otn.oracle.com.
17-6
Oracle9i SCM Glossary
ABCDFHLMNOPRSUVW
access rights
Access rights govern what operations users can perform on specific objects in the
repository. Access rights can be granted on workareas, containers and
configurations.
Note that an access right to a container in a workarea is effective only if the user
has the same access right to the workarea.
ancestor version
A version of the object from which the current object version has evolved, that is,
an object version that occurs earlier in the history of the object than the current
version.
branch
A sequence of object versions that has its starting point at a particular version in
an existing branch, but that evolves independently from the existing branch.
Branches are identified using branch labels.
Branching enables users to develop multiple versions of a product simultaneously

using the same set of source files.
A version tree always has a MAIN branch, and may also have sub-branches.
branch label
17-7
A unique name for a branch that should identify the purpose of the branch
check in
To create a new version of a checked-out versioned object, or to add a non-

versioned object to the version control system. While an object is checked in it is
write protected, and therefore cannot be modified.
check out
To make a versioned object available for updating. Checked-out objects are visible
in a user's workarea, and may be locked so that other users cannot update them
until they are checked back in.
common ancestor version
An object version that is an ancestor of more than one other object version. If two
versions share an ancestor version, that version is common to them both.
Typically, the object version from which development follows more than one
branch is a common ancestor for all the object versions on all the branches from
that point onwards. The root version is a common ancestor to all subsequent
versions.
compare
To compare two object versions to identify the differences between them. A

compare operation compares two versions: a base object version and a
contributor object version. The base object version is the version with which the
contributor object version is compared. For example, if you choose to select
version 1.1 of an object and compare it with its previous version 1.0, version 1.1 is
the contributor and version 1.0 is the base. If an object is checked out, the
checked-out version details are included in the compare operation.
You can compare different versions of one object or versions of different objects of
the same type. Compare operations can be performed on the contents of a
container and a configuration as well as on individual object versions.
17-8
configuration
A user-defined collection of specific repository object versions, usually related in

some way. A configuration typically represents a specific release of a particular
product or component of a product.
A specific object version that is included in a configuration is said to be a member

of that configuration. In any particular configuration there can be only one version
of each included object.
container
A logical subdivision of the repository that provides a convenient method for users
to organize and access repository objects, similar to directories in a file system.
Different types of container are supported:
● folders are available with any installation of the repository

● packages and projects are available only with JDeveloper (release 3.2
onwards)
delta
A chunk of information containing the differences between two file versions.
download
To copy data from the repository to a client file system.
delete
1. To remove a non-versioned object.

2. To remove the container membership of a checked-in object version, in other
words, to remove a particular object from a particular version of its container.
17-9
Compare with force delete.
file mapping
See folder mapping.
folder
A type of container for storing repository objects.
folder mapping
The association of a container in the repository with a logical path in a file system.
This association enables synchronization operations to take place.
hijacked file
A file for which the file system copy has been changed (through alteration of the
read-only attribute), while the repository copy is checked in and therefore remains
unchanged.
To resolve hijacked files you can choose to download the repository copy
(effectively canceling the changes that have been made to the file system copy),
check out the repository copy (enabling you to upload the file system copy or
download the repository copy), compare the two copies or view the version history
of the file.
LATEST
17-10
The full (baseline) version of a file in a delta-set, representing the most recent file
version.
lock
Checking out an object version with a lock permits other users to check out a
version of that object unlocked, but prevents them from either locking it or from
checking it back in to the same branch until the lock is removed.
Compare with strict locking.
merge
To combine changes that have occurred independently in two versions of the

same object. A merge is typically required when development has taken place on
a branch and the changes need to be incorporated back onto the main line of
development.
The merge operation combines two different object versions into another, different
object version. The merge operation takes two contributor object versions (target
and source), compares them to a base version, and uses internal rules to create
the result based on changes found in all three versions.
When merging from the JDeveloper interface, the merge operation uses the
common ancestor of the source and target as the base.
When merging from the repository Command Line Tool, the user can specify
which object version is to be used as the base, and it need not be a common
ancestor.
meta data
Data that describes data. In the context of Oracle9i Software Configuration

Manager (formerly known as Oracle Repository), descriptive information about a
database or application, for example, the fact that values for a particular column in
a table must be numeric data of a particular length.
metamodel
17-11
The structure, within a repository, in which metadata is stored
non-versioned
The preferred term for describing a repository object that has not been added to
version control.
object
Objects in the repository can be of two main types:
● repository objects
● files and file systems
object version
See version.
parallel development
The process of maintaining multiple versions of the same objects. This is achieved
by working on branches.
policy
A repository-wide option that controls certain aspects of the repository behavior.
17-12
For example, the automatic version labeling policy determines whether the
repository automatically assigns a version label on checkin, or whether the user is
able to specify a label of their choice.
private workarea
A workarea that can be accessed only by the user who created it. See also
workarea.
privilege
A bit value representing yes or no which allows (authorizes) an operation to take

place. The type of operation determines the type/name of the privilege.
See also repository privilege.
purge
To remove from the repository some or all versions of a repository object. Purging
a version of an object also removes that part of its version history. Compare with
force purge.
refresh
To reapply the rules that determine which objects, and which versions of those
objects, are visible in a workarea.
repository
A central, online, multi-user storage area for objects.
Repository Administration Utility
The Repository Administration Utility enables the build manager or repository

administrator to install and manage a repository environment. This person is
normally the repository owner.
17-13
For more details on setting up the repository owner’s account, see the
documentation for the Oracle Repository.
You can use the Repository Administration Utility to:
● Install a new repository for this product

● Check system details and requirements using the Check Requirements
Utility; for example, the system privileges a repository owner requires
● Check the status of repository objects and take appropriate action using the
Object Status Utility; for example, for recompiling repository objects
● Delete all the repository objects belonging to the repository owner
● Delete all the database objects belonging to the repository owner, including
all the repository objects
● Back up the contents of a repository
● Restore a repository from a backup
● Maintain users' access to the repository
● Grant or revoke repository privileges to users
● Edit or extend the repository structure using the user extensibility features
repository object
Structured data. An individual item of meta data that forms a building block for
repository operations, for example, application development. In this case, a table
definition could be a repository object that stores details of a table used by the
application under development.
Repository Object Navigator
The Repository Object Navigator is a versatile tool for creating and maintaining
repository objects and should be used only by the build manager or the repository
administrator.
The on-line help which accompanies the Repository Object Navigator describes
the tasks that you can perform with the Repository Object Navigator:
● Administrative - these tasks include creating, editing and deleting

workareas, containers and configurations, and setting repository-wide
policies.
17-14
● Maintenance - these tasks include creating, editing and deleting repository
objects, and performing file upload, download and synchronization between
the repository and a file system.
● Access control - these tasks include granting and revoking access by other
repository users to workareas, containers and configurations.
● Version control - these tasks include checking repository objects in or out,
viewing the version history of an object, and comparing and merging object
versions.
The privileges to perform some of these tasks must be granted through the
Repository Administration Utility.
If the Oracle9i SCM Repository Object Navigator (RON) is used to download or

synchronize files to the file system, JDeveloper does not recognize the
downloaded files are repository files. This is because mapping information stored
by the RON is not available to JDeveloper.
root version
The first (top) version of an object in a version tree.
rule
A selection criterion for a version of a repository object. Rules are instrumental in

determining the contents of a workarea or configuration.
software configuration management
The process of controlling the evolution of an item of software by:
● maintaining the actual components of a product

● recording the history of the components as well as of the whole product
● providing a stable working context for changing the product
● supporting the manufacture of the product from its components
● coordinating concurrent changes
17-15
Version control is an essential part of software configuration management.
strict locking
If a strict locking policy is applied in the repository, every checkout is automatically

set to locked. Because two or more users cannot apply locking to object versions
on the same branch, a strict locking policy prevents concurrent development of
object versions on the same branch.
structured data
An individual item of meta data that forms a building block for repository
operations, for example, application development. In Oracle9i Software
Configuration Manager (formerly known as Oracle Repository), repository objects
are structured data.
Compare with unstructured data.
synchronization
Synchronization can either upload or download files and folders between the
repository and the file system. The objective of synchronization is to keep the file
system files and repository files up to date with respect to each other.
system folder
A special folder created at installation time and belonging to the repository owner.
It contains standard required items, for example, development language elements
that can be included in application systems and modules.
The system folder can be copied and included in workareas via rules but it cannot
be deleted, it cannot have subfolders, and its contents cannot be altered.
system privilege
See repository privilege.
17-16
unstructured data
All types of files and file systems, text documents, Java files, SQL scripts, images.
Compare with structured data.
upload
To copy data from a client file system to the repository.
version
A snapshot of the content of an object at a certain point in its development.
version control
The process of managing and tracking changes made to repository objects.
Version Event Viewer
A tool that enables you to view details of all the events that have occurred for an
object that is under version control.
version history
A record of the changes made to a versioned repository object over a period of

time.
Version History Viewer
A tool that displays the version history of an object in the graphical form of a
version tree.
version label
A string that uniquely identifies a version of an object. Version labels are useful for
identifying specific versions of objects with a meaningful textual description,
instead of using a version number.
17-17
W
workarea
A specific view of the repository through which the user can create repository
objects, and delete or edit those objects to which he or she has access. If you are
using version control, only one version of a particular object is visible in a
workarea.
The contents of a workarea are defined by a workarea specification containing a

list of predefined rules and configurations.
Note: JDeveloper does not support connecting to and working against shared
workareas, only connecting to and working against private workareas. This ensures
that no unintentional loss of data occurs where one developer overwrites others
developer's work. JDeveloper does, however, support shared workareas for
coordination purposes only: a shared workarea can be used as the basis for defining
one or more private workareas. The shared workarea enables a configuration to be
produced that can be shared by many developers in their private workarea definitions,
enabling effective team based development.
17-18
Oracle9i SCM - Best Use Recommendations
Oracle9i Software Configuration Manager (SCM), formerly known as Oracle Repository, offers
a wide variety of processes and options. Rather than attempt to describe all of these, this topic
describes several "best use" recommendations. They do not represent the only way of working,
but should be interpreted as a basic starting point for using the software configuration
management features of Oracle9i SCM in medium- and large-scale development environments:
● Use automatic branching
The automatic branching policy ensures that branch labels can be assigned as a default
checkin branch; all subsequent checkins in the selected workarea will check in to the
new default branch. By default, the automatic branching policy is turned off. The
repository owner can turn on this policy from the Options menu of the Repository
Administration Utility.
● Work on private branches and merge changes into a common branch
Ensures code integrity by allowing changes to be made in isolation. Merging changes

back on to common branch using Oracle9i SCM tools.
● Use private workareas
Ensures that accidental overwrites of files in workareas are avoided.
● Use the automatic version labeling policy
Automatic version labeling allows the repository to assign version labels. When the
repository assigns version labels, no two versions of the same object will share the
same version label. This avoids conflicts in resolving versions in the repository.
Typically, the automatic version labeling policy is set by the repository owner or
administrator when the repository is set up.
● Use strict locking if you are not working on a private branch to avoid simultaneous
updates
Strict locking keeps other developers from checking out a file while you are working on it.
This is especially useful if you are working on the integration branch. If you are working
on the integration branch and strict locking policy is not applied then other developers
17-19
could check out a file while you are working on it. This could lead to complex merge
situation when you try to check the file back in. Typically, the strict locking policy is set by
the repository owner or administrator when the repository is set up.
17-20
Oracle9i SCM Essentials
The following topics describe the main concepts of Oracle9i SCM.
● Workareas
● Workarea Rules
● Branching
● Configurations
● Oracle9i SCM Repositories
● Security and Access Rights
● Synchronization
Related Topics:
Setting Up JDeveloper to Use Oracle9i SCM
Branching with Oracle9i SCM
Managing Files in Oracle9i SCM
17-21
About Workareas
Oracle9i Software Configuration Manager (formerly known as Oracle Repository) can support
large numbers of concurrent users. An individual user may not want to see a list of every object
in the repository. In addition, some kind of mechanism is needed to ensure that one user does
not interfere with another user's work. Software Configuration Manager solves both these
problems by allowing you to create individual workareas—specific views of the repository
through which you can work on your own objects. In this way, you can avoid seeing objects
belonging to other users, and you need not be concerned that your changes might be
overwritten by someone else.
The following illustration shows a conceptual view of a a user's workarea. The workarea
provides a specific view of a subset of objects within the repository that the user wants to work
with. The workarea can be defined to exclude objects that the user does not need.
As an example, assume that version control has been activated and User A wants to work on
some of the repository objects that he or she owns. User A checks these objects out, locking
them at the same time. Other users can still check out and update these objects, provided they
can access them. However, they cannot check them back in to the same branch until the lock is
released. User A then works on the objects and, having finished, checks them back in. This
releases the lock, allowing other users to check in their versions. However, it will then be
necessary to merge their versions with User A's versions to enable checkin.
It is possible to check out and update an object without locking it, allowing other users to check
out the same object and possibly update it as well. In this situation, the first user to check the
updated object back in is allowed to do so, while updates from other users must be merged
with the original updates. It is also possible to set a repository option to lock every object when
it is checked out. This option, known as a strict locking policy , prevents any other user from
checking out the object until the first user checks it back in.
JDeveloper provides a Workarea Wizard to guide you through the steps of creating workareas.
17-22
When you create a workarea, it is initially a private workarea, meaning that only you can access
it. Note that the repository owner must have assigned you the Workareas repository privilege
before you can create workareas.
Note: JDeveloper does not support connecting to and working against shared workareas, only
connecting to and working against private workareas. This ensures that no unintentional loss of data
occurs where one developer overwrites others developer's work. JDeveloper does, however, support
shared workareas for coordination purposes only: a shared workarea can be used as the basis for
defining one or more private workareas. The shared workarea enables a configuration to be
produced that can be shared by many developers in their private workarea definitions, enabling
effective team based development.
When you create a workarea, you are its owner. You can subsequently transfer ownership to
another user.
It is possible to choose exactly which repository objects or object versions you want to see in a
particular workarea. Options are available that enable you to include or exclude specific objects
or versions, for example.
If you are using version control, only one version of a particular object is visible in a workarea.
However, you can change the version that is visible in the workarea you are currently using.
At least one workarea must be available to you before you can do any work in the repository.
You can either create a workarea yourself, or use a workarea that has been made available to
you. In a workarea, you must create at least one container before you can create other
repository objects. Any versioned container or object can be included in (that is, visible from)
more than one workarea. However, a non-versioned container or object cannot be visible from
more than one workarea.
You make objects visible in a workarea by defining a workarea specification consisting of a set
of rules, which define the precise versions of objects that are to be visible in the workarea. For
example, you can specify that the workarea is always to include the latest version of objects on
a particular branch, or the latest version between two dates, and so on. In addition, you can
include configurations - predefined sets of object versions - in your workarea specification.
You can create a workarea from a specification file containing rules, configurations or both.
Specification files have the default extension .CWS.
When you refresh a workarea, the workarea contents are redisplayed according to the current
workarea specification. As a result, objects may be added to, updated in, or removed from, the
set of objects visible in the workarea. Refreshing a workarea also resolves potential version
conflicts for objects in the workarea.
17-23
The following illustration shows the effect of refreshing a workarea whose specification includes
two potentially conflicting configurations:
In this example, which assumes the use of version control, version 1.1 of object A is included in
workarea WA1, together with the other objects. Version 1.2 of object A is excluded because its
configuration, config2, is lower down the list than config1, which contains version 1.1 of the
object.
You can set up a workarea to work with a specific development branch. To do so, you specify a
default checkin branch to ensure that all versioned objects updated via that workarea are
assigned to the same branch on checkin. For this feature to be effective, the automatic
branching policy must be active.
17-24
About Workarea Rules
A workarea or configuration is defined by specifying one or more rules. These rules define which
repository object versions are to be included in, or excluded from, the workarea or configuration
to which the rules apply.
When you create or modify a workarea or configuration, you use the Workarea Wizard to specify
the rules you want to use. From the wizard you can:
● Define the rules directly on one of the pages of the wizard
● Identify a specification file or template file containing the rules you want to use
In either case, the available rules for specifying a workarea or configuration are as follows. Click
a rule name to see the format to use when including the rule in a specification or template file.
Rule Effect
EXCLUDE_FOLDER Excludes all specified containers
EXCLUDE_OBJECT Excludes all specified objects
FOLDER_LATEST_BEFORE Includes the latest versions of all objects in the specified container that were
checked in before the specified date
FOLDER_LATEST_BETWEEN Includes the latest versions of all objects in the specified container that were
checked in between the specified dates
FOLDER_LATEST_CONTENTS Includes the latest versions of all objects in the specified container on the
specified branch
INCLUDE_CONFIG Includes all the object versions defined by a configuration
INCLUDE_FOLDER Includes the latest versions of all objects in the specified container
INCLUDE_OBJECT Includes the latest version of the specified object
LATEST Includes the latest versions of all objects on the specified branch
LATEST_BEFORE Includes the latest versions of all objects on the specified branch that were
checked in before the specified date
LATEST_BETWEEN Includes the latest versions of all objects on the specified branch that were
checked in between the specified dates
LATEST_CONFIG_CONTENTS Includes the latest versions of all the objects in the specified configuration
EXCLUDE_FOLDER repository rule
Excludes all specified container versions.

17-25
EXCLUDE_FOLDER(folder-path=container-element-type)
Examples
The following excludes version 1.2.1.1 of folder reports:
EXCLUDE_FOLDER(reports{1.2.1.1}=Folder)
The following excludes the version of folder fix(reports) that is on branch fix06 and
has sequence number 4 on that branch:
EXCLUDE_FOLDER(fix^(reports^){fix06;4}=Folder)
EXCLUDE_OBJECT repository rule
Excludes all the specified object versions.
EXCLUDE_OBJECT(object-path=element-type)
Examples
The following excludes version 1.1 of the domain LIST OF THINGS in version 1.2.1.1
of folder reports:
EXCLUDE_OBJECT(reports{1.2.1.1}/LIST OF THINGS{1.1}=Domain)
The following excludes the object MASTER TABLE that has the version sequence 6 on the
MAIN branch that is in the latest version of the MAIN branch of folder reports:
EXCLUDE_OBJECT(reports{MAIN;LATEST}/MASTER TABLE{MAIN;6}=Table
Definition)
FOLDER_LATEST_BEFORE repository rule
The FOLDER_LATEST_BEFORE repository rule includes the latest versions of all objects in
the specified container that were checked in before the specified date.
FOLDER_LATEST_BEFORE(folder-path=container-element-type,before-date)
Examples
17-26
FOLDER_LATEST_BEFORE(wa-specs{1.0.1.0}=Folder,19-APR-2000)
FOLDER_LATEST_BEFORE(reports{1.2.1.1}=Folder,19-APR-00 08:00:00)
FOLDER_LATEST_BETWEEN repository rule
The FOLDER_LATEST_BETWEEN repository rule includes the latest versions of all objects
in the specified container that were checked in between the specified dates.
FOLDER_LATEST_BETWEEN(folder-path=container-element-type,start-date,end-date)
Example
The following includes the only or the latest versions of all objects in folder WA-
specs{1.0.1.0} between the given dates:
FOLDER_LATEST_BETWEEN(WA-specs{1.0.1.0}=Folder,19-APR-2000,30-APR-
2000)
FOLDER_LATEST_CONTENTS repository rule
The FOLDER_LATEST_CONTENTS repository rule includes the latest versions of all objects
in the specified container on the specified branch.
FOLDER_LATEST_CONTENTS(folder-path=container-element-type,branch-label)
Example
The following includes the latest versions of objects in folder reports{1.2.1.1} on

branch fix06:
FOLDER_LATEST_CONTENTS(reports{1.2.1.1}=Folder,fix06)
INCLUDE_CONFIG
INCLUDE_CONFIG, while not strictly a repository rule, has a similar format to repository
rules. It is used to include a configuration, that is, to include all the object versions defined
by a configuration.
INCLUDE_CONFIG(configuration-path)
Example
17-27
The following includes all the object versions defined by the configuration version
services_internal{1.0}.
INCLUDE_CONFIG(services_internal{1.0})
INCLUDE_FOLDER repository rule
The INCLUDE_FOLDER repository rule includes the latest versions of all objects in the
specified container.
INCLUDE_FOLDER(folder-path=container-element-type)
Example
The following includes the latest versions of all objects in the version of folder reports
that has sequence number 5 on the MAIN branch:
INCLUDE_FOLDER(reports{MAIN;5}=Folder)
INCLUDE_OBJECT repository rule
The INCLUDE_OBJECT repository rule includes the latest or the specified version of the
specified object.
INCLUDE_OBJECT(object-path=element-type)
Example
The following includes version 1.0 of the Domain element LIST OF THINGS in the folder
reports version 1.2.1.1:
INCLUDE_OBJECT(reports{1.2.1.1}/LIST OF THINGS{1.0}=Domain)
LATEST repository rule
The LATEST repository rule includes the latest versions of all objects on the specified
branch.
LATEST(branch-label)
17-28
Example
The following includes the latest versions of objects on branch fix06:
LATEST(fix06)
LATEST_BEFORE repository rule
The LATEST_BEFORE repository rule includes the latest versions of all objects on the
specified branch that were checked in before the specified date.
LATEST_BEFORE(branch-label,before-date)
Example
LATEST_BEFORE(fix06,19-APR-2000)
LATEST_BETWEEN repository rule
The LATEST_BETWEEN repository rule includes the latest versions of all objects on the
specified branch that were checked in between the specified dates.
LATEST_BETWEEN(branch-label,start-date,end-date)
Example
LATEST_BETWEEN(FIX06,19-APR-2000,30-APR-2000)
LATEST_CONFIG_CONTENTS repository rule
The LATEST_CONFIG_CONTENTS repository rule includes the latest versions of all the
objects defined by the specified configuration.
LATEST_CONFIG_CONTENTS(configuration-path=Configuration,branch-label)
Example
The following includes the latest version on branch fix06 of all the objects defined by
configuration version fix_config{MAIN;LATEST}:
LATEST_CONFIG_CONTENTS(fix_config{MAIN;LATEST}=Configuration,fix06)
17-29
17-30
About Branching
Branches are sequences of object versions that have their starting point at a particular version
in an existing branch, but evolve independently. All the versions together create a version tree.
A version tree always has a MAIN branch, and may also have sub-branches. Branching
enables you to develop multiple versions of a product simultaneously (parallel development)
using the same set of source files.
When you check in an object for the first time, it is always added to the default MAIN branch. If
the repository policy specifies an alternative branch to check in to for the first time, two versions
are created, one on MAIN and the other on the specified alternative branch.
Branches can be created for specific tasks such as:
● Fixing bugs in a current release

● Making a start on the next release while simultaneously maintaining a component as part
of a current release
● Maintaining different variants of the component (for example, to reflect different
implementations, ports to different platforms, or interfacing with different window
systems)
● Carrying out experimental development, which may eventually be abandoned or merged
into the primary development
● Allowing two developers to concurrently make changes to a component and, therefore,
enable serial updates to a component
All of the changes made to the source files on the branches can be merged back into a single
branch. (About) This is known as the "integration branch". Typically, the MAIN and the
integration branch are one in the same; all of the work done on the various branches are
merged back to MAIN. However, it is possible to choose an alternate branch for merges.
The following illustration shows a version tree for an object. This can be viewed using the
Version History Viewer.
17-31
By default, the versioning system uses an automatic branching policy. When the automatic
branching policy is enabled, if a default checkin branch is set for a workarea, all checked-out
objects for the workarea will check in to that branch. This feature is useful for isolating changes,
for example, you may want to set up a workarea to isolate all the changes for a specific task, so
ensuring that specific development branches are not populated with new object versions at
critical periods in development, for example, during a build.
The implications of enabling or disabling automatic branching depend on a variety of factors as

follows:
Automatic branching enabled Automatic branching disabled
17-32
No default checkin branch set for The version is checked in at the tip The version is checked in at the tip
the workarea of the current branch (the branch of the current branch (the branch
from which it was checked out). from which it was checked out).
The default checkin branch is the The version is checked in at the tip The version is checked in at the tip
same as the current branch of the current branch (the branch of the current branch (the branch
from which it was checked out). from which it was checked out).
The default checkin branch is If the version does not already exist The version is checked in at the tip
different from the current> on the default branch, the version is of the current branch (the branch
checked in as the root of the new from which it was checked out).
branch. If the object already exists
on the default checkin branch, the
object will need to be merged. This
involves checking in the latest
version to the current branch,
checking out the existing object
from the default branch and
merging from the checked-in latest
version to the checked-out existing
object on the default branch. The
latest version can then be checked
in on the default branch.
This is the first checkin for the The version is checked in to the The version is checked in to the
object MAIN branch, and a copy created MAIN branch.
on the default checkin branch.
When the automatic branching policy is enabled, you can change the default checkin branch for
a workarea; when the automatic branching policy is disabled, you cannot change the default
checkin branch.
The automatic branching policy can be set only by a user with the Set Policy system privilege.
17-33
About Configurations
A configuration is a collection of repository object versions, usually related in some way that is
significant to an application. Any set of specific object versions can be recorded as a
configuration, rather like the striping or labeling features of some configuration management
systems.
Usually a configuration represents all the object versions that represent a checkpoint in
development or component of an application, for example, all the object versions that make up
a Payroll application, or a screen form used in that application.
For example, when the development of individual objects reaches the stage where you can
build a particular application, you need to specify exactly which version of each object is to be
used for the build. The same applies when assembling a set of objects to be used for a test or
included in a production release or a patch release - the configuration defines which versions of
which objects are to be used.
When you create a configuration, you are its owner. You can subsequently transfer ownership
to another user.
Configuration Members
A specific object version that is included in a configuration is said to be a member of that

configuration. Note that only those objects to which you have select access rights can be added
to a configuration that you create.
Configuration members can be added or removed as and when required. However, only
versioned or checked-in objects can be included in a configuration. Each configuration is a
repository object in itself, and can therefore be placed under version control. Note that, if a
configuration is under version control, only one version of the configuration can be checked out
at a time.
17-34
About Oracle9i SCM Repositories
Oracle9i SCM (formerly known as Oracle Repository) consists of a store, and a set of
management tools, for all the data of an enterprise. The features of Oracle9i SCM allow a
carefully managed approach to the consolidation and sharing of data across the enterprise.
For example, you can:
● Organize objects in the repository by using containers (folders)
● Create and store your files in file systems that can be stored in the repository itself
● Keep the local file system in synch with the repository by using synchronization
● Define specific views of the repository that let you see and work with only the objects you
need with workareas
● Define a collection of repository object versions that are related to an application or

development project in the form of a configuration
● Define which repository object versions are to be included in, or excluded from, the
workarea or configuration with repository rules
● Set repository-wide options that control certain aspects of version control, file naming
(case sensitivity), and object dependencies with policies
● Control access the repository, its contents, and the audit properties of individual objects
by granting access rights
● Perform a wide variety of repository tasks, including bulk operations, using the command-
line interface
● Return information from repository objects, such as folders, and create and manage
system elements such as workareas and versioning operations by using PL/SQL
packages in the repository API
● Write queries against the repository

17-35
17-36
About Security and Access Rights
Repository security is provided at the following levels:
● Repository access control
● Repository contents access control
● Event auditing and monitoring
Control of Access to the Repository
Access to the entire repository is controlled through the standard Oracle database access
control features. Anyone wishing to use the repository must already have an account on the
database where the repository resides. Only a user with database administrator (DBA)
privileges can create user accounts on the database.
At the time the repository is installed, only the repository owner can access the repository. The
repository owner can subsequently authorize other existing database users to access the
repository.
Control of Access to Repository Contents
It is possible to control a number of general security features on an individual user basis. The
repository owner can assign each user a number of repository privileges. These privileges
specify, for example, whether a particular user is allowed to create or delete workareas,
containers or configurations. Other repository privileges specify whether a user can perform
certain repository operations (such as setting policies or purging objects), or whether that user
can use the various software tools that are supplied with Oracle9i Software Configuration
Manager (formerly known as Oracle Repository).
Access to a particular workarea, container or configuration is controlled by the user who owns
that item. The user who creates a workarea, container or configuration is initially its owner. That
user can grant or revoke access rights (for example, update or delete) for that item to or from
themselves or another user. However, the owner of an item always retains administrate and
select access rights to it.
A particular role with the name PUBLIC is predefined for use with access rights. Granting or
revoking access rights on a workarea, container or configuration to or from PUBLIC enables
17-37
you to grant or revoke those access rights to or from every repository user in a single operation.
The owner of a workarea, container or configuration can transfer ownership of that item to
another repository user.
A user may have access rights for a container. However, if that user does not also have access
rights to a workarea in which that container is visible, the user will not be able to perform
operations corresponding to those access rights on objects in the container.
17-38
About Synchronization
An upload operation copies a file from the file system to the repository. If you edit the file, your
changes are made to the file system copy. Oracle9i Software Configuration Manager (formerly
known as Oracle Repository) provides a synchronization mechanism to enable you to keep the
different copies up to date with respect to each other.
The Software Configuration Manager allows you to perform a workarea refresh and one-way
(download) synchronization by using the File | Source Control | Download Latest Versions
command.
Notes
If you are working on a private branch and choose to download latest versions, you should be
aware that the isolation of your workarea will be compromised. Files merged into the integration
branch by other developers may appear in your workarea after the download is complete.
However, if you have checked out any files in your workarea, these will take precedence over
new versions on the integration branch. No merging will be required until you end your private
branch.
If the Oracle9i SCM Repository Object Navigator (RON) is used to synchronize files to the file
system, JDeveloper does not recognize the downloaded files are repository files. This is
because mapping information stored by the RON is not available to JDeveloper. Therefore you
should only synchronize files in JDeveloper using the method described above.
17-39
Before you can use Oracle9i SCM with JDeveloper you must set Oracle9i Software
Configuration Manager as the Active Source Control Addin. For more information on this, see
Configuring JDeveloper to Use Oracle9i SCM.
The following topics describe how to set up JDeveloper to use Oracle9i SCM.
● Configuring JDeveloper to Use Oracle9i SCM
● Creating an Oracle9i SCM Connection
● Creating a New Workarea
● Selecting a Workarea
● Deleting an Oracle9i SCM Connection
● Disconnecting from an Oracle9i SCM Repository
Related Topics
Branching With Oracle9i SCM
Managing Files and Folders With Oracle9i SCM
17-40
Configuring JDeveloper to Use Oracle9i SCM
JDeveloper can be configured to use Oracle9i SCM as its source control mechanism. Oracle9i
SCM connections cannot be created in the Navigator pane until JDeveloper has been
configured to use this source control system.
To configure JDeveloper to use Oracle9i SCM:
1. Choose Tools | Preferences, then select Source Control from the left pane of the
Preferences dialog.
OR
Choose File | Source Control | Enable.
2. Select 'Oracle9i SCM' from the Active Plugin dropdown list.
3. If you want to automatically convert end of line characters for files involved in Oracle9i
SCM operations, check Perform end of line character translation on text files, then select
the translation you require:
❍ Windows to UNIX
❍ UNIX to Windows
4. If you want to automatically save any unsaved changes when you perform a source
control operation, check Save Open Files for SCM Operations.
5. Click OK.
Related Topics
Connecting to an Oracle9i SCM Repository
17-41
Creating an Oracle9i SCM Connection
If you already have a connection to the required Oracle9i SCM repository, you can restore that
connection by choosing File | Source Control | Connect, then selecting the connection and
clicking Connect.
The Source Control message window has a status area that displays the current source control
connection and workarea. Also, the suffix (SCM) will be added to the name of the selected
workarea in the Navigator pane. The suffix indicates that the workarea and its contents are now
available for source control operations.
Note: Before you can create a connection to an Oracle9i SCM repository, you must first ensure that
the Active Source Control Addin preference is set to 'Oracle9i SCM'.
To create a connection to an Oracle9i SCM repository:
1. Right-click the Oracle9i SCM node under the Connections node in the Navigator pane,
then choose New Connection.
OR
Choose File | New, then select Oracle9i SCM from the Connections category, then click
OK.
OR
Right-click the Connections node in the Navigator pane, then choose New Oracle9i SCM
Connection.
3. Enter the display name for the connection. This is the name that will be displayed under
the Connections | Oracle9i SCM node in the Navigator pane.
4. Click Next.
5. Enter the username and password for the connection, then click Next.
Note: To save the password for the Oracle9i SCM connection, select the Remember
Password checkbox. These passwords are not encrypted when they is saved. If security
is an issue at your site, you might not want to use this option.
17-42
6. Enter the hostname, JDBC port and SID for the connection, then click Next.
7. Click Test Connection to test the Oracle9i SCM connection is functioning correctly.
8. Click Next to display a summary of the Oracle9i SCM connection details.
9. Click Finish.
Related Topics
17-43
Creating a New Workarea
You can create new workareas on an Oracle9i SCM repository using JDeveloper.
Notes:
● To create a new workarea in Oracle9i SCM you must have create workarea privileges on
the Oracle9i SCM repository.
● JDeveloper does not support connecting to and working against shared workareas, only
connecting to and working against private workareas. This ensures that no unintentional
loss of data occurs where one developer overwrites others developer's work. JDeveloper
does, however, support shared workareas for coordination purposes only: a shared
workarea can be used as the basis for defining one or more private workareas. The
shared workarea enables a configuration to be produced that can be shared by many
developers in their private workarea definitions, enabling effective team based
development.
To create a new workarea:
1. Choose File | Source Control | Create Workarea.
OR
Right-click the Workareas node under the Oracle9i SCM connection on which you want
to create a new Workarea, then choose New Workarea.
If you are not currently connected to an Oracle9i SCM repository, you will be prompted to
either connect to an existing connection, or create a new connection.
3. Enter the name of the new workarea. The workarea name must be unique in the selected
repository.
4. Enter a description for the workarea, then click Next.
5. Select the source of the files for the workarea:
❍ latest files on a branch. Click Browse to choose an existing branch.
17-44
❍ files specified by a workarea specification file
Related Topics:
About Workareas
17-45
Selecting a Workarea
You can select which workarea on an Oracle9i SCM repository you want to use.
To connect to a workarea for source control:
1. Choose File | Source Control | Connect from the JDeveloper menu bar to select an
existing connection or create a new connection. The Connect to Repository dialog
opens.
2. If you choose an existing connection in the dialog, the Workareas for connection_name
dialog opens.
3. Select the name of the workarea to which you want to connect and click OK.
Related Topics
Creating a New Workarea
17-46
Editing Workarea Rules
You can edit the existing rules for a workarea, or add new workarea rules for a workarea.
Note: The order in which the rules are listed in this dialog is the order of precedence in which the
rules are processed. You can change the order of the rules using the reordering buttons.
To edit a workarea's rules:
1. Right-click the workarea, the rules for which you want to edit, from those displayed in the
Navigator pane.
2. Choose Edit.
3. To edit an existing workarea rule, select the rule that you want to edit, then click Edit.
OR
To add a new workarea rule, click Add.
OR
To import an existing workarea specification, click Import.
OR
To remove an existing workarea rule, select the rule that you want to remove and click
Remove.
For more information on workarea rules, see About Workarea Rules.
17-47
Deleting an Oracle9i SCM Connection
If you no longer need a connection to an Oracle9i SCM repository, you can delete the
connection from JDeveloper.
To delete an Oracle9i SCM connection:
1. Right-click the Oracle9i SCM connection you want to remove.
2. Choose Delete Connection.
Related Topics
Disconnecting from an Oracle9i SCM Repository
17-48
Disconnecting from an Oracle9i SCM Repository
If you have finished with a connection to an Oracle9i SCM you can close the connection without
removing it from JDeveloper.
To disconnect from an Oracle9i SCM repository:
1. Right-click the Oracle9i SCM connection that you want to close.
2. Choose Close Connection.
Note: When you next try to access the close connection JDeveloper will reconnect to the
Oracle9i SCM repository using the stored details.
Related Topics
Deleting an Oracle9i SCM Connection
17-49
Branches are sequences of object versions that have their starting point at a particular version
in an existing branch, but evolve independently. All the versions together create a version tree.
A version tree always has a MAIN branch, and may also have sub-branches. Branching
enables you to develop multiple versions of a product simultaneously, which is also known as
parallel development. Parallel development is useful for:
● Allowing developers to work on atomic tasks (private branches) independently from the
main branch, then merge their tasks back to the main branch when they have been
completed.
● Allowing multiple versions of a product to be developed independently, for example, the
main release ad a bug fix release.
For example:
17-50
The following topics describe how to work with branches on Oracle9i SCM.
● Beginning a Private Branch in Oracle9i SCM
● Ending a Private Branch in Oracle9i SCM
● Comparing Files in Oracle9i SCM
● Merging File Versions in Oracle9i SCM
● Canceling a Private Branch in Oracle9i SCM
17-51
Related Topics
Setting up JDeveloper to Use Oracle9i SCM
Managing Files and Folders in Oracle9i SCM
About Branching
17-52
Beginning a Private Branch in Oracle9i SCM
Branches can be used to develop code discreetly from the main development source so that
systems, sub-systems, bugs or tasks can be developed and tested without impacting the main
source control tree.
Before beginning a private branch, you should first ensure that there are currently no files or
folders checked out on the integration branch from which you want to create a private branch.
For more information on listing which files you currently have checked out, see Listing All
Oracle9i SCM Checkouts.
Note: To begin a private branch you must first have a connection to an Oracle9i SCM repository.
For more information on creating a connection to an Oracle9i SCM repository, see Connecting to an
Oracle9i SCM Repository.
To create a private branch:
1. Choose File | Source Control | Begin Private Branch.
If you have any files or folders currently checked out from the active workarea you will be
advised to check them in before continuing. This ensures that changes you have made
to files checked out from the integration branch will be available on the integration branch
for other users.
2. Enter the name and description for the branch.
3. Click OK.
The workarea rules for the workarea to which you are currently connected are
automatically updated to use the private branch.
Note: While working on a private branch, the name of the current branch is displayed at the bottom
of the SCM message log window.
Related Topics:
17-53
About Branching
17-54
Ending a Private Branch in Oracle9i SCM
When work has been completed on a private branch, and all the changes have been checked
in on that branch, it can be ended and merged back on to the integration branch. Your changes
will then be available to other users on the integration branch.
To end a private branch:
1. Choose File | Source Control | End Private Branch.
If you have any files or folders currently checked out from the selected workarea you will
be advised to check them in before continuing. Files that have not been checked in won't
be merged back to the integration branch when you end the private branch.
2. JDeveloper will attempt to merge all your changed files automatically. Any files that
cannot be merged automatically can be merged manually using the Oracle9i SCM Merge
Tool.
3. Files that have been merged will still be checked out. Check that the files have been
merged correctly, then check them in either from the Merge Results pane, or from the
Navigator pane.
Related Topics
Creating a Private Branch in Oracle9i SCM
Canceling a Private Branch in Oracle9i SCM
Listing All Oracle9i SCM Checkouts
About the Merge Window
17-55
Comparing Files in Oracle9i SCM
Versions of files that have been added to Oracle9i SCM can be compared with either the
current, checked out, version of the file, or other checked-in versions.
To compare file versions from the Navigator pane:
1. Right-click the file you want to compare with a previous version, then choose Source
Control | Compare Previous.
OR
Choose File | Source Control | Compare Previous.
The differences between the two versions of the file are highlighted in the Oracle9i SCM
Compare Tool.
To compare file versions from the Oracle9i SCM Version History Viewer:
1. Right-click the node you want to compare with a previous version, then choose View
Version History.
OR
Choose File | Source Control | View Version History.
2. Right-click the node for the version of the file that you want to compare with another
version.
3. Choose Compare With Previous to compare the selected version of the file with the
previous version.
OR
Right-click the node for the version you want to compare with another version, choose
Mark, then right-click the version with which you want to compare and choose Compare
With Mark.
17-56
Related Topics
Merging File Versions in Oracle9i SCM
17-57
Before you can merge file versions in Oracle9i SCM, all the files that are to be merged must be
checked in. If you want to merge file versions back to the integration branch you should end
your private branch. For more information on ending your private branch, see Ending a Private
Branch in Oracle9i SCM.
Merging file versions is commonly used to:
● 'Merge up', where you refresh file versions on your private branch from the integration
branch.
● 'Merge across', where you refresh file versions on your private branch from another
developer's private branch during a limited collaboration project. This allows you have
other developer's changes before they've ended their private branches.
To merge file versions in Oracle9i SCM:
1. Choose File | Source Control | Merge File Versions.
3. Select the source for the merge. You can select a branch, a workarea or a configuration.
4. Click Next.
5. Select the target workarea, then click Next.
6. Review the settings on the Summary page, then click Finish
7. JDeveloper will attempt to automatically merge all the changed files from the source to
the target. Any files that cannot be merged automatically can be merged manually using
the Oracle9i SCM Merge Tool.
8. Files that have been merged will still be checked out. Check that the files have been
merged correctly, then check them in from the Navigator pane or, if the files are not on
the file system, using the Repository Object Navigator on an Oracle9i SCM client.
17-58
Related Topics
Comparing Files in Oracle9i SCM
About the Merge Window
17-59
Canceling a Private Branch in Oracle9i SCM
If you want to stop working on your private branch without having to merge your changes back
up to the integration branch, you can cancel your private branch.
Important: In JDeveloper, you cannot directly resume a private branch which has been canceled.
However, the branch, and all the changes on it, are retained in the repository, and you can edit your
workarea rules to see the contents of the canceled branch. For more information on workarea rules,
see About Workarea Rules.
Note: You cannot cancel a private branch on which you have files checked out.
To cancel a private branch:
● Choose File | Source Control | Cancel Private Branch.
Your workarea rules are returned to what they were before the private branch was
created.
Note: You can still merge any files that were checked in to your private branch using the Merge File
Versions Wizard and selecting the private branch label as the source for the merge. For more
information, see Merging File Versions in Oracle9i SCM.
Related Topics
17-60
Managing Files in Oracle9i SCM
You can see the status of a file or other item in the Navigator pane that is under Oracle9i SCM
source control because the icon is overlaid with one of the following status markers:
Status
Meaning
Marker
The file is checked in and must be checked out before it can be
modified.
The file is checked out and can be modified.
The following topics describe how to work with files in Oracle9i SCM.
● Adding a File to Oracle9i SCM
● Checking In a File to Oracle9i SCM
● Checking Out a File from Oracle9i SCM
● Undoing an Oracle9i SCM Checkout
● Listing Oracle9i SCM Checkouts
● Mapping Oracle9i SCM Repository Folders to File System Directories
● Comparing Files in Oracle9i SCM
● Merging File Versions in Oracle9i SCM
● Displaying the Version History of an Oracle9i SCM File
● Displaying the Event History of an Oracle9i SCM File
17-61
Related Topics
Branching With Oracle9i SCM
17-62
Adding a File to Oracle9i SCM
Files that are not already in Oracle9i SCM can be added to source control using JDeveloper.
To add a file to Oracle9i SCM:
1. Right-click the file you want to add to source control from those listed in the Navigator
pane, then choose Source Control | Add.
OR
Select the file you want to add to source control from those listed in the Navigator pane,
then choose File | Source Control | Add.
A candidate list of files to be added to source control are displayed in the Add Files to
Oracle9i SCM dialog. You can remove files from the candidate list by selecting the files
you want to remove, then clicking Remove. If you have removed a file from the candidate
list, but want to re-add it, click Add then select the previously deleted file you want to re-
add to the candidate list.
2. Enter comments for the initial addition of the file to source control.
3. To check out the file after it has been added to source control, select Check out after
adding.
4. Click OK.
Related Topics
Checking In a File to Oracle9i SCM
Checking Out a File from Oracle9i SCM
17-63
Files that have been checked out of Oracle9i SCM can be checked back in using JDeveloper.
A file that is currently checked in to source control display a check icon in the Navigator pane.
Notes:
● If you are working on an integration branch, you may need to merge your file when you
check it in as a version of the file on a private branch may have been merged back onto
the integration branch before you check in.
● If a file type is not in the Oracle9i SCM registry it is treated as a binary file when it is
checked it, and consequently it cannot be compared with previous versions. To add a file
type to the Oracle9i SCM registry, the administrator of the Oracle9i SCM repository must
choose File | Utilities | Edit File Registry in the Repository Object Navigator then add a
new rule with the missing file type extension. For example, to recognize the .uix file type,
the extension must be set to %.uix and %.UIX, set the Rule to 'Text' and set the
Platform to 'All'.
To check in a file to Oracle9i SCM:
1. Select the currently checked-out file, or files, you want to check out of Oracle9i SCM
from those listed in the Navigator pane, then choose File | Source Control | Check In.
OR
Right-click the currently checked-out file, or files, you want to check out or Oracle9i SCM
from those listed in the Navigator pane, then choose Source Control | Check In.
A candidate list of files to be checked in are displayed in the Check In Files to Oracle9i
SCM dialog. You can remove files from the candidate list by selecting files, then clicking
Remove. If you have removed a file from the candidate list, but want to re-add it, click
Add then select the previously deleted file you want to re-add to the candidate list.
2. Enter comments for the checkin.
3. To use the file's checkout comments, select Use checkout comments.
OR
17-64
To enter new checkin comments, deselect Use checkout comments, then enter the
comments in the Checkin comments area.
4. To automatically check out the file after the checking, select Check out after checkin.
5. To check the file in regardless of whether it has been changed, select Check in even is
identical.
6. Click OK.
Related Topics
Check Out a File from Oracle9i SCM
17-65
Checking Out a File from Oracle9i SCM
Files that have been checked in to Oracle9i SCM can be checked back out using JDeveloper.
To check out a file from Oracle9i SCM:
1. Select the currently checked-in file, or files, you want to check out of Oracle9i SCM from
those listed in the Navigator pane, then choose File | Source Control | Check Out.
OR
Right-click the currently checked-in file, or files, you want to check out or Oracle9i SCM
from those listed in the Navigator pane, then choose Source Control | Check Out.
A candidate list of files to be checked out are displayed in the Check Out Files Oracle9i
SCM dialog. You can remove files from the candidate list by selecting the files you want
to remove, then clicking Remove. If you have removed a file from the candidate list, but
want to re-add it, click Add then select the previously deleted file you want to re-add to
the candidate list.
2. Enter comments for the checkout.
3. To lock the file when it is checked out, select Check out with lock. While a file is checked
out with a lock, no-one else can check this file out on this branch.
4. Click OK.
Related Topics
17-66
Undoing an Oracle9i SCM Checkout
If you have checked out a file, or files, that you don't want to change, you can undo the
checkout on those files.
To undo a file checkout from Oracle9i SCM:
1. Select the currently checked-out file, or files, you want to check out of Oracle9i SCM
from those listed in the Navigator pane, then choose File | Source Control | Undo
Checkout.
A candidate list of files to be added to source control are displayed in the Undo Checkout
dialog. You can remove files from the candidate list by selecting the files you want to
remove, then clicking Remove. If you have removed a file from the candidate list, but
want to re-add it, click Add then select the previously deleted file you want to re-add to
the candidate list.
2. Click OK.
Related Topics
17-67
Listing Oracle9i SCM Checkouts
You can list which files are currently checked out of Oracle9i SCM. From the list of checked out
files you can choose to check files in, or undo file checkouts.
To list all the files checked out of Oracle9i SCM:
1. Choose File | Source Control | List Checkouts.
2. Select the List Checkouts options you require on the List Oracle9i SCM Checkouts, then
click OK.
The checkouts are displayed in the List Checkouts pane.
Related Topics:
Checking Out a File to Oracle9i SCM
17-68
Mapping Oracle9i SCM Repository Folders to File
System Directories
Folder mapping associates a folder in a private workarea with a directory in any file system to
which you have access. The directory becomes the target of the repository folder. When you
subsequently select a folder from which to download, or a directory from which to upload, the
associated destination is selected by default.
Note: Only root folders can be mapped. You cannot map a subfolder.
A file system mapping provides a default specification for upload and download operations. In
addition, a file system mapping is required before you can synchronize that file system with the
repository.
Creating Folder Mappings Using JDeveloper
When you select files, a project, or any node which has contents in JDeveloper's Navigation
pane and choose Source Control | Add from the right mouse or menu bar, JDeveloper looks to
see if it can find a predefined mapping between the file's containing directory, and a repository
folder. If it cannot find a mapping, JDeveloper will attempt to create one automatically.
The folder mapping dialog can be invoked by selecting the active workarea in the Navigator
pane and choosing File | Source Control | Folder Mappings.
Related Topics
17-69
Displaying the Version History of an Oracle9i SCM
File
You can view a graphical representation of the version history of a file using the Version History
Viewer.
Because the Version History Viewer can work independently of any workarea context, it can
display all versions of a single element that is under version control. The object version
selected by the context workarea is marked with an arrow on the version tree.
To display the version history of a file in Oracle9i SCM:
● Select the file, the version history of which you want to display, then choose File | Source
Control | View Version History.
OR
● Right-click the file, the version history of which you want to display, then choose Source
Control | View Version History.
17-70
Displaying the Event History of an Oracle9i SCM
File
You can view a list of the events in the history of a file using the Version Event Viewer.
Because the Version Event Viewer can work independently of any workarea context, it can
display all version events of a single element that is under version control.
To display the event history of a file in Oracle9i SCM:
● Select the file, the event history of which you want to display, then choose File | Source
Control | View Event History.
OR
● Right-click the file, the event history of which you want to display, then choose Source
Control | View Event History.
Related Topics
Displaying the Version History of an Oracle9i SCM File
17-71
Using Rational ClearCase With JDeveloper
JDeveloper allows you to use the source control features of Rational ClearCase release 4.0
onwards. JDeveloper works seamlessly with ClearCase so that once you have it configured you
can add files to source control, and check them in and out from the Navigator pane.
You can see the status of a file or other item in the Navigator pane that is under ClearCase
source control because the icon is overlaid with one of the following status markers:
Status
Meaning
Marker
The file is checked in and must be checked out before it can be
modified.
The file is checked out and can be modified.
The following topics describe how to configure and use to use ClearCase:
Configuring JDeveloper to Use Rational ClearCase
Adding a File to ClearCase
Removing a File from ClearCase
Checking In a File to ClearCase
Checking Out a File from ClearCase
Undoing a ClearCase Checkout
Listing ClearCase Checkouts
Comparing Files Checked In to ClearCase
Displaying the History of a ClearCase File
Displaying the Description of a ClearCase File
For more information about Rational ClearCase, refer to your ClearCase documentation, or see
17-72
the Rational website, http://www.rational.com.
17-73
Configuring JDeveloper to Use Rational ClearCase
In order to use ClearCase with JDeveloper you must have ClearCase 4.0 or greater client
installed on the same machine as JDeveloper.
To configure JDeveloper to use Clearcase:
1. In JDeveloper choose Tools | Preferences to display the Preferences dialog, and select
Source Control in the left pane.
2. In the Source Control preferences page, select Rational ClearCase 4.0 from the Active
Plugin list. The fields for defining ClearCase options are enabled.
3. Select the File Comparison Style for file comparison reports. If you select Side by Side,
the Column Width of Report field is enabled.
4. Enter a value for Maximum History Entries.
5. Leave View All User Events if you want to view events for all users. Uncheck this if you
only want to see your event history.
6. Make sure that Save changes before performing source control operations is checked.
7. When you click OK, JDeveloper locates the installed ClearCase client, and displays
connection information in the log window.
Now that you have configured JDeveloper to work with ClearCase, you can access files and
folders that already exist in a mounted ClearCase view. New files and folders must be created
in or copied to your ClearCase view.
To add new files to ClearCase, see Adding a File to ClearCase.
Related Topics
17-74
Adding a File to ClearCase
To work in ClearCase, you have to store your workspaces, projects and files on your
ClearCase view, and before new projects and files are under ClearCase source control, you
have to explicitly add them to ClearCase.
The comment pane in the Add to ClearCase dialog allows you to build up comments for
different groups of files. The comments you type apply to the files you have selected. For
example, you can select all the files and type a global comment. Next, select a smaller number
of files. The first comment is displayed and you can add to it. Then you can select just a single
file in this group and add another comment specific to that file.
To add one or more files to ClearCase:
1. Select the project or file in the navigator, and choose File | Source Control | Add. The
Add to ClearCase dialog is displayed listing the items you have selected.
2. You can add all the listed files to ClearCase by clicking OK, or you can first remove some
of them from the list. To remove a file from the list, select it and click Remove. The file is
greyed out. If you have removed a file from the list in error, you can add it again by
selecting it and clicking Add.
3. If you want to continue working on the files, leave Keep Files Checked Out selected. If
you deselect it, the files are checked in and you must check them out when you want to
work on them.
4. When you click OK the files in the list are added to ClearCase source control. You may
see one or more messages asking whether you should add folders to ClearCase. You
should click Yes.
Related Topics
17-75
Removing a File From ClearCase
You can remove a file from ClearCase if you no longer need it. The files are removed from the
current version of the directory which contains them.
To remove a file from ClearCase:
1. With the file or files selected in the navigator, choose File | Source Control | Remove.
The Remove from ClearCase dialog is displayed with the files listed.
2. You can remove all the listed files from ClearCase by clicking OK, or you can first
remove some of them from the list. To remove a file from the list, select it and click
Remove. The file is greyed out. If you have removed a file from the list in error, you can
add it again by selecting it and clicking Add.
3. When you click OK, the files are removed from the current version of directory, and you
will no longer be able to work with them.
Related Topics
17-76
Checking In a File to ClearCase
When you have finished working on a file, you should check it into ClearCase.
The comment pane in the Check In to ClearCase dialog allows you to build up comments for
file in this group and append a specific comment.
To check in one or more files:
1. Select the files in the navigator, and choose Source Control | Check In from the context
menu. The Check In to ClearCase dialog is displayed listing the items you have selected.
2. You can check in all the listed files to ClearCase by clicking OK, or you can first remove
some of them from the list. To remove a file from the list, select it and click Remove. The
file is greyed out. If you have removed a file from the list in error, you can add it again by
3. Type in comments for this check in in the right pane.
4. If you want the files checked in even though they are identical to the previous ClearCase
versions, leave Force Check In Where Files Are Identical selected. If you deselect this
option, the file may remain checked out, depending on how ClearCase handles files of
that type. If the file remains checked out, you can use the Undo checkout command to
return the file to its previous checked in state.
5. When you click OK the files in the list are checked in to ClearCase source control.
Related Topics
17-77
Checking Out a File From ClearCase
To work on a file, you must check it out from ClearCase.
The comment pane in the Check In to ClearCase dialog allows you to build up comments for
file in this group and append a specific comment.
To check out one or more files:
1. Select the files in the navigator, and choose Source Control | Check In from the context
menu. The Check Out from ClearCase dialog is displayed listing the items you have
selected.
2. You can check out all the listed files from ClearCase by clicking OK, or you can first
remove some of them from the list. To remove a file from the list, select it and click
Remove. The file is greyed out. If you have removed a file from the list in error, you can
add it again by selecting it and clicking Add.
3. Type in comments for this check out in the right pane.
4. When you click OK the files in the list are checked out from ClearCase source control
and you can work on them.
Related Topics
17-78
Undoing a ClearCase Checkout
If you have checked out a file but not made any changes to it, or if you want to discard the
changes you have made, you can undo the last check out of that file.
Warning: you may lose you work if you use this on a file that you have changed since it was
checked out.
To undo checkout for one or more files:
1. Select the files in the navigator, and choose Source Control | Undo Checkout from the
context menu. The Undo Clearcase Checkout dialog is displayed listing the items you
have selected.
2. You can undo checkout for all the listed files by clicking OK, or you can first remove
some of them from the list. To remove a file from the list, select it and click Remove. The
file is greyed out. If you have removed a file from the list in error, you can add it again by
3. When you click OK the last checkout from ClearCase for these files is undone, and any
changes are lost.
Related Topics
17-79
Listing ClearCase Checkouts
You may want to see all the files that you have checked out from ClearCase, for example to
see which files need to be checked in before performing another action.
To list ClearCase checkouts:
1. Choose File | Source Control | List Checkouts. The ClearCase List Checkouts dialog is
displayed.
2. Browse to the top level folder in the ClearCase view from which you want to search for
checked out files and folders.
3. To only list files that you have checked out, leave List My Checkouts Only selected,
otherwise you will see files checked out by everyone.
4. If you want to search for checked out files only in this folder, deselect Include Subfolder
Checkouts.
5. When you click OK the the List Checkouts pane is displayed in JDeveloper. There may
be a delay of a few seconds when the search is over a large number of files and folders.
Then the files currently checked out are displayed. You can check in a file, undo a check
out from the context menu of an item in the List Checkouts pane.
6. You can refresh the list by choosing Refresh clicking .
Related Topics
17-80
Comparing Files Checked In to ClearCase
Use this to compare versions of files that are under ClearCase source control. You can
compare a file with:
● Its immediate predecessor

● Any of the file's previous revisions
● Any other file on your filesystem
The format of the ClearCase report of the comparison is set in Source Control Preferences
page, which is under Tools | Preferences.
To compare a file with its immediate predecessor:
1. With the file selected in the navigator, choose Source Control | Compare with Previous
Version.
2. If there are no differences, a message is displayed. Otherwise a ClearCase report of the
differences is displayed.
To compare a file with another revision:
1. With the file selected in the navigator, choose Source Control | Compare.
2. Ensure that Predecessor File Revision is checked.
3. Previous versions of the file are listed in the Compare ClearCase File dialog. Select the
one you want to compare to.
To compare a file with a file outside ClearCase source control:
2. Check Other Locally Accessible File.
3. Browse to the file you want to compare to.
17-81
Related Topics
17-82
Displaying the History of a ClearCase File
Use this to display the history of a file that is under ClearCase source control.
To display the history:
1. With the file selected in the navigator, choose Source Control | View Version History
2. The History for ClearCase File dialog is displayed. The history contains fields describing
ClearCase actions, and user comments relating to the changes. To see the full text of a
comment, click on it.
Related Topics
17-83
Displaying the Description of a ClearCase File
Use this to display the description of a project or a file that is under ClearCase source control.
To display the description:
1. With the file selected in the navigator, choose Source Control | View Description from
the context menu.
2. The Description of ClearCase File dialog displays information about the file. To see the
full text of a comment, click on it.
Related Topics
17-84
Using Concurrent Versions System (CVS) With
JDeveloper
JDeveloper allows you to use the source control features of Concurrent Versions Support
(CVS) version 1.10 onwards. JDeveloper works seamlessly with CVS so that once you have
configured it you can check out files and commit changes from JDeveloper's Navigator pane.
To configure JDeveloper to work with CVS you first enter some connection information. Once
you can connect to the CVS repository you then import your work into the CVS repository to
place the files under source control. Then, before you can work on them, you have to check
them out. This copies them to a location on your local file system. Finally, you import them into
a JDeveloper project so that you can see the files in the Navigator pane.
Any changes you make are to the local copies of your files, and these changes are only
updated to the CVS repository when you perform a commit. It also means that, for example,
when you create a new file and add it to CVS, the file is not yet under source control. Only
when you commit that file is the CVS repository updated.
You can see the status of a file or other item in the Navigator pane that is under CVS source
control because the icon is overlaid with one of the following status markers:
Status
Meaning
Marker
The file has been added to your local CVS files.
There were conflicts when the file was updated from the CVS
repository. In this case you have to manually edit the file to resolve
all the points of conflict.
The file has been removed from the your local CVS files.
The file is out of synch with the CVS repository due to local or
remote changes.
The file system file is up to date with the CVS file.
This may occur if a file has been removed from the CVS repository
using the CVS command line.
CVS Modules and JDeveloper Projects
CVS organizes files in the context of a module. This is not directly analogous to a JDeveloper
project, because a JDeveloper project is a logical container for files that can reside in any
directory and a project can also contain configuration data, whereas a CVS module is just a
17-85
structured collection of files in the same directory.
When you import a JDeveloper project into CVS it is important that all the files are in the same
directory structure, otherwise when you check out the project into JDeveloper you will find that
files that were in another location are not present.
Getting started with CVS
The following topics describe how to configure JDeveloper to use CVS:
Configuring JDeveloper to Use CVS
Importing a JDeveloper Project into CVS
Checking Out a CVS Project
The following topics show you how to work with files and folders in CVS:
Adding a File to CVS
Removing a File from CVS
Updating a File in CVS
Committing a File to CVS
Comparing Files in CVS
Displaying the Log for a CVS File
Displaying the Status of a CVS File
Additional information for CVS administrators
The CVS administrator has to configure the CVS repository for the automatic handling of binary
files produced by JDeveloper, such as image file formats.
Where other file types are updated CVS attempts to merge them. If you do not want this occur,
you must change the configuration of the CVS repository.
17-86
For more information about CVS, refer to the CVS documentation, or see their website,
http://www.cvshome.org.
17-87
Configuring JDeveloper to Use CVS
In order to use CVS with JDeveloper you must have the following:
● CVS client installed on the same machine as JDeveloper.

● The location of the CVS executable must in in your path.
To configure JDeveloper to use CVS:
1. In JDeveloper choose Tools | Preferences to display the Preferences dialog, and select
Source Control in the left pane.
2. In the Source Control preferences page, select Concurrent Versions Systems (CVS) 1.10
from the Active Plugin list. The fields for defining your connection to the CVS repository
are enabled.
3. Select the access method to your CVS repository from Access Method:
Select Local when the repository is on the local machine. In this case, you
do not enter a User Name and Server Location.
Select External (rsh) when you have a remote shell configured to access a
remote repository as if it was on the local machine.
Select Password Server when the CVS Repository is on a remote machine

which requires password authentication.
4. In User Name, enter your user name on the CVS repository server.
5. In Server Location, enter the domain qualified hostname for the CVS repository server.
6. In Repository, enter the path, relative to the root directory on the server, to the CVS
repository.
7. The CVSRoot is composed from the entries you have made, and you cannot change it.
8. Make sure that Save changes before performing source control operations is checked.
When you click OK, JDeveloper locates the installed CVS client, and displays the first
command run and version information in the log window.
9. Log into to CVS by choosing File | Source Control | Log In and enter your password in
the dialog that is displayed.
17-88
The next task you have to perform is to import your work into the CVS repository, and then
copy the source controlled files back to JDeveloper. See Importing a JDeveloper Project Into
CVS.
Having Problems?
If JDeveloper fails to find the CVS client on your machine, an error message is displayed.
Check that you have a CVS client installed, and that the folder containing the CVS executable
appears in your path.
If you are accessing a CVS server through a firewall, you can only connect to it if the firewall
allows TCP/IP communication on the CVS port. If there is an authentication failure when you
log in, try using the CVS command line to connect. If this fails the connection may be being
blocked by the firewall, and you should contact your network administrator.
Related Topics
Using Concurrent Versions System (CVS) With JDeveloper
17-89
Importing a JDeveloper Project Into CVS
Before you can start using your project with CVS, you have to import your project into the CVS
repository. This copies all your folders and files to the CVS repository and places them under
source control.
In JDeveloper you work in the context of a project which is displayed in the navigator. A project
can contain files that can reside in any directory. In CVS your work is stored in the context of a
module, which is simply a structured collection of files. It is therefore important that the files in
your JDeveloper project are present in the same directory structure before you import the
project into CVS
To import a JDeveloper project into CVS:
1. If you have not already done so, log into to CVS by choosing File | Source Control | Log
In.
2. Select the project you want to import into source control in the navigator. Choose File |
Source Control | Import Project. The Import Project into CVS dialog is displayed.
3. The Module Source displays the directory where the project you are importing is
currently stored.
4. The Module Name defaults to the name of the project, although you can change this.
5. The Vendor Tag and the Release Tag are used by some organizations for their own
purposes, in which case you should use the values supplied by your CVS administrator.
Otherwise you can leave the default values.
6. You can leave the Action Comments as the default, or enter some comments which
describe the module or the project. These comments apply to all root versions of the files
in this project.
When you click OK, the contents of the folder in Module Source are copied to the CVS
repository and stored as a module.
Before you can check out any files to work on them you have to copy them back to your
machine so that you work on them locally. See Checking Out a CVS Project. It is good practice
to work on the checked out files in a new workspace, so you may want to remove the
workspace from which you imported the files into CVS The files and folders will still be present
on your machine, but they will not be displayed in the navigator.
To remove the workspace from the navigator:
17-90
● Select the workspace in the navigator, and click .
Related Topics
17-91
Checking Out a CVS Project
This is one of the configuration tasks you perform to place files and folders under CVS source
control. You perform this task once, after importing your project into the CVS repository.
When you check out a CVS project, the files are copied from the CVS repository to a new
location on your local machine. Then you add the files to your project so that they are visible in
the Navigator pane where you can work on them.
To check out a project from CVS:
1. If you need to, log into to CVS by choosing File | Source Control | Log In.
2. Create a new workspace by selecting the Workspaces node at the top of the navigator,
and selecting New Workspace from the context menu. Enter a name for the workspace,
and deselect Add a New Empty Project.
3. In the navigator, select the new workspace, and choose File | Source Control | Check
Out Project. The Check Out Project from CVS dialog is displayed.
4. To check out into the the same folder as the workspace, leave Use Workspace Location
for Checkout selected. To specify a new folder deselect it.
5. In Module Name enter the name of the CVS module that you want to check out. Modules
that JDeveloper is aware of are listed here, so if you are checking out a project that you
imported into CVS, the module name will be displayed here, otherwise you have to type
in the module name.
6. If you have deselected Use Workspace Location for Checkout, click Browse and browse
to the correct location and enter the name of a new folder.
Note: you cannot check out to an existing folder therefore you must type in the name for
a new folder that will be created for the files.
7. When you click OK the project and its files are copied to the location you have specified.
To see them listed in the navigator you have to add the project to the workspace. With
the workspace selected in the navigator click and select the project.
If you find that there are files missing after you check out a CVS project, it is possible that they
were not in the same directory as the other files when you imported the JDeveloper project. In
this case you should add them to the CVS project as if they were new files. See Adding a File
to CVS.
17-92
You can now work with the files in this project. To see the source control commands available
for the project and its contents, select Source Control from the context menu. These are
described in:
Comparing Files in CVS
You can also remove a file from CVS source control. See Removing a File from CVS.
Related Topics
17-93
Before you can add a file to CVS, you must have already put your project under CVS source
control. This is described in Configuring JDeveloper to Use CVS.
When you create a new file, for example a new class, it has to be added to source control
before you can use the other CVS operations on it. The file is added to source control locally,
and the CVS repository is not updated. A file in this state can be identified in the Navigator
pane by the icon , and from its context menu because the source control options Update and
Commit are available.
To add new files in a project to CVS:
1. With the project selected in the navigator, choose Source Control | Add from the context
menu. JDeveloper finds all the files that are candidates for adding to CVS, and they are
listed in the Add to CVS dialog.
2. You can add all the listed files to CVS by clicking OK, or you can first remove some of
them from the list. To remove a file from the list, select it and click Remove. The file is
3. When you click OK the files in the list are copied to the relevant module in the CVS
repository.
To add one file to CVS:
1. Select the file in the navigator and choose Source Control | Add. The Add to CVS dialog
is displayed with the file listed.
2. When you click OK the file is copied to the relevant module in the CVS repository.
This file will be added to the CVS repository when the next commit is performed.
Related Topics
17-94
Removing a File from CVS
When you remove a file from CVS it is removed from your local disk, and it is removed from the
CVS repository at the same time. It is the equivalent of using Remove from IDE on a file not
under source control.
Warning: this deletes the file locally and fromthe CVS repository when you click OK.
To remove a file from CVS:
1. Select one or more files to be delected in the navigator, and choose File | Source
Control | Remove.
2. The Erase from Disk dialog is displayed with the files listed. You can check and uncheck
the files, and those checked are removed from your local disk when you select Erase
Selected.
This file will be removed from the CVS repository when the next commit is performed.
Related Topics
Using Concurrent Versioning System (CVS) With JDeveloper
17-95
The CVS update operation attempts to merge the modifications with the local files. It does not
overwrite local files with those from the CVS repository.
You can perform this on just a single file, or in the context of a project in which case JDeveloper
determines which files have changed since they were last committed and displays them as a
list.
To update a project from the CVS repository:
1. With the project selected in the navigator, choose Source Control | Update from the
context menu. JDeveloper finds all the files that are candidates for updating from the
CVS repository, and they are listed in the Update from CVS dialog.
2. You can update all the files by clicking OK, or you can first remove some from the list. To
remove a file from the list to be added to CVS, select it and click Remove. The file is
3. When you click OK the local copies of the files in the list are merged with the versions
from the CVS repository.
To update a file from the CVS repository:
1. Select the file in the navigator and choose Source Control | Update. The Update from
CVS dialog is displayed with the file listed.
2. When you click OK the local copy of the file is with that from the CVS repository.
Related Topics
17-96
Use this to update the CVS repository with the latest version of the files you have been working
on, and to add any new files or remove any unwanted files that have been selected for this
action.
You can perform this on just a single file, or in the context of a project in which case JDeveloper
determines which files have changed since they were last committed and displays them as a
list.
The comment pane in the Commit to CVS dialog allows you to build up comments for different
groups of files. The comments you type apply to the files you have selected. For example, you
can select all the files and type a global comment. Next, select a smaller number of files. The
first comment is displayed and you can add to it. Then you can select just a single file in this
group and append a specific comment.
To commit the changed files in a project:
1. With the project selected in the navigator, choose Source Control | Commit from the
context menu. JDeveloper finds all the files that are candidates for committing to the
CVS repository, and they are listed in the Commit from CVS dialog.
2. You can commit all the files by clicking OK, or you can first remove some from the list. To
remove a file from the list to be added to CVS, select it and click Remove. The file is
3. Enter a comment in the right pane.
4. When you click OK the listed files in the CVS repository are updated.
To commit a single file:
1. Select the file in the navigator and choose Source Control | Commit. The Commit to
CVS dialog is displayed with the file listed.
2. Enter a comment in the right pane.
3. When you click OK the file in the CVS repository is updated.
Related Topics
17-97
17-98
Comparing Files In CVS
Use this to compare versions of files that are under CVS source control. You can compare a file
with its immediate predecessor, or you can compare with any of the file's previous revisions.
To compare a file with its immediate predecessor:
1. With the file selected in the navigator, choose Source Control | Compare with Previous
Version.
2. If there are no differences, a message is displayed. Otherwise a CVS report of the
To compare a file with another revision:
2. Previous versions of the file are listed in the Compare CVS File dialog. Select the one
you want to compare it to.
3. If there are no differences, a message is displayed. Otherwise a CVS report of the
Related Topics
17-99
Use this to display the log of a file that is under CVS source control.
To display the log:
1. With the file selected in the navigator, choose Source Control | View File Log from the
context menu.
2. The Log for CVS File dialog is displayed. The log contains fields describing CVS actions,
file line differences after committing, and user comments relating to the changes. To see
the full text of a comment, click on it.
Related Topics
17-100
Use this to display the status of a project or a file that is under CVS source control.
To display the status:
1. With the file selected in the navigator, choose Source Control | View Status from the
context menu.
2. The Status of CVS File dialog displays information about the file. Possible statuses are:
● Changed locally - the file has been locally modified since it was copied from the
repository.
● Changed in repository - the file has been modified by another user since it was copied
from the repository.
● Locally removed - the file will be removed during the next commit.
● Locally added - the file will be added during the next commit.
● Up-to-date - the file is up-to-date with the latest CVS repository revision.
● File has conflicts - these may have resulted from a file update or commit action. If
necessary, consult your CVS administrator for assistance.
● Needs merge or needs patch - the file externally, for example, by another user.
Related Topics
Using Concurrent Versioning System (CVS) With JDeveloper
17-101
Using Your Own Source Control System
Although Oracle9i Software Configuration Manager (SCM), Rational ClearCase and Concurrent
Versions System (CVS) are supported by JDeveloper, the source control system you use may
not be one of them. In this case you can write an addin for JDeveloper to support your source
control system.
The following topics describe how to write your source control addin for JDeveloper.
● Writing a Source Control Addin for JDeveloper
● More on the Source Control Addin Utilities
The reference documentation required to write a source control addin for JDeveloper is
included in the JDeveloper distribution, as jdev/doc/jdev-scm-doc.zip. To view the
reference, unzip it, and open its overview-summary.html file in a web browser.
Related Topics
Extending JDeveloper Using the Addin API
17-102
Writing a Source Control Addin for JDeveloper
To write an source control addin for JDeveloper, you must:
● implement oracle.ide.scm.SCMClient
● specialize the adapter subclasses of oracle.ide.scm.SCMOperation for every source
control command you need to execute.
Implementing oracle.ide.scm.SCMClient
The most important task when writing a source control addin is create your own implementation
of SCMClient. You must implement ALL the methods on this interface to create a source
control addin.
Note: SCMClient fully extends JDeveloper's Addin API.
SCMClients must do the following:
● Register with the source control addin framework using SCMRegistry.

● Provide an SCMCheckoutList, if you want to use the List Checkouts window.
● Return the SCMOperationSet for the categorized set of operations you want your
SCMClient to use.
● Define the SCMPropertyCustomizer for the client. This allows the source control addin
user to edit source control client preferences.
● Return the current version system status of an SCMFile.
Specializing adapters in the oracle.ide.scm.op package
Once you have implemented oracle.ide.scm.SCMClient, you must specialize the adapter
subclasses of oracle.ide.scm.SCMOperation to define the behavior of your source control
addin.
The adapters provided are:
● SCMSingleFileOperation
● SCMMultiFileOperation
● SCMNoFileOperation
17-103
● SCMToggleOperation
Note: To use the standard file confirmation dialog, you must implement
SCMDialogSpecification.
Using oracle.ide.scm.SCMFile
You can use the SCMFile interface to perform operations on file system elements that are
under source control. For example, retrieving a file's current source control status or converting
to java.net.URL and java.io.File types.
More Information
For more information on the API provided for writing your own source control addin, refer to the
Javadoc for the oracle.ide.scm package, and below.
For more information on extending JDeveloper using the Addin API, see Extending JDeveloper
Using the Addin API.
Related Topics
More on the Source Control Addin Utilities
17-104
More on Source Control Addin Utilities
Two categories of utilities are provided by the Source Control Addin API: general and
environmental.
General Utilities (oracle.ide.scm.util)
The general utilities provided are as follows:
Utility Description
SCMOperatingSystem Queries the operating system of the client machine.

SCMShellRunner Runs a shell command, providing an SCMProcess for capturing the
output.
SCMVersionFileStatus Defines a collection of standard file states for source control.
Note: Other classes are in the oracle.ide.scm.util package, but only those that are most
useful to your implementation of a source control addin are discussed here.
Environmental Utilities (oracle.ide.scm.env)
The environmental utilities provided are as follows:
Utility Description
SCMAssert Provides exception and assertion handling.

SCMListCheckouts Controls the list checkouts window
SCMOperationRuntime Provides a mechanism for performing your source control operations
programmatically.
SCMProperties Retrieves the properties for your implemented SCMClient.
SCMStatusOverlays Allows updates to overlay icons for source control elements in the
Navigator pane.
SCMUtilitySet Contains a selection of utilities to enhance your SCMClient.
17-105
Related Topics:
Writing a Source Control Addin for JDeveloper
17-106
Web Services
● Web Services
● What are Web Services?

❍ J2EE and Oracle SOAP Based Web Services
❍ What is WSDL?
■ Creating a WSDL Document
■ Editing a WSDL document

■ Supported Types
❍ What is SOAP?
❍ What is the Deployment Descriptor?
● Getting Started with Web Services

❍ Configuring JDeveloper to Generate Web Service Stubs
❍ Configuring SOAP Server Connections

■ Defining SOAP Server Connections
■ Editing a SOAP Server Connection

■ Refreshing a SOAP Server Connection
■ Deleting a SOAP Server Connection
■ Registering a Web Service with a SOAP Server
■ Unregistering a Web Service from a SOAP Server
● Developing a Web Service

❍ Creating a J2EE Web Service
❍ Creating a SOAP Web Service

❍ Editing a Web Service
❍ Creating More Complex Web Services
■ Publishing BC4J Application Modules as Web Services
■ Creating Web Services with Custom Bean Parameters in the Method

Signatures
18-1
● Using a Web Service
❍ Generating a Web Service Stub
❍ Regenerating Your Generated Stub Files

❍ Generating a Web Service Skeleton
18-2
Web Services Using JDeveloper
Web services consist of a set of messaging protocols and programming standards that expose
business functions over the internet using open standards. A Web service is a discrete,
reusable software component that is accessed programmatically over the internet and to return
a response.
JDeveloper provides powerful tools that allow you to quickly develop Web services that can be
deployed as:
● J2EE Web services that are deployed to Oracle9iAS Containers for J2EE (OC4J).
JDeveloper supports developing and deploying services based on the evolving Web
services standard which will be included in the next release of J2EE (J2EE 1.4).
● Web services that are deployed to an Apache SOAP (Oracle SOAP) server.
JDeveloper provides powerful tools for quickly developing Web services. It provides features
that allow you to create Web services, or to create stubs to call existing Web services. For
example:
● If you have a method in a Java class that you want to publish as a Web service, you can
use the Web service Publishing Wizard to create the deployment information and WSDL
document for you. Deployment is very easy, and in a short time your Web service is
available for use.
● Web service Publishing Wizard can also create a Web service based on:
❍ the remote interface of an Enterprise JavaBean (stateful and stateless session
beans, and entity beans).

❍ a Business Components for Java (BC4J) framework, or BC4J wrapped as a EJB
session bean.
● To use an existing Web service in an application, all you need to know is the URL of the
WSDL, which contains all the information about the Web service, the parameters used
and the location. You enter the WSDL URL in the Web service Stub/Skeleton Wizard
which generates a stub with the appropriate method signatures. You can then use this as
an interface to call the Web service in your application.
For the more expert user, JDeveloper can:
● Create server-side skeleton code based on an existing Web service that you can use to
develop a new implementation.
18-3
● Creates an outline WSDL document to save you time in writing a WSDL document. The
Tag Insight feature in the XML Editor, similar to the Code Editor's Code Insight feature,
helps you to write error-free code.
If you want to practice creating Web services using JDeveloper, there is a tutorial that takes
you through to process of creating and deploying a J2EE Web service, and creating and
deploying the same service as a Web service on a SOAP server. See Creating and Using a
Web Service, which is in the Tutorials book of the online help.
Additional information about Web services can be found in the Web services Developer's Guide
(Part No. A95453-01), which is part of the Oracle9i Application Server Release 2
documentation set. It can also be found at the Oracle Technology Network (OTN), on
//otn.oracle.com/products/jdev/.
Related topics
What are Web Services?
Getting Started with Web Services
Developing a Web Service
Using a Web Service
18-4
What are Web Services?
Examples of Web services are:
● A service that could tell a user information such as which bookstores are within five
blocks of a given address.
● A service provided by a shipping company that returns information on the delivery status
of a parcel.
A useful way to think of a Web service is as a discrete reusable software component that can
be incorporated into an application. The assembled software components of a Web service
application are loosely coupled, the dependencies between components are manageable and it
is possible to flexibly reconfigure Web service applications.
A Web service performs a single, well-defined task. Its interface describes the inputs and
outputs of the service, so the user knows what to expect from the service. The Web service is
designed for interaction with other software, and unlike a Web site, or a a desktop application a
Web service provides no direct user interface.
Web services make use of existing Internet infrastructure, and piggyback on existing and
ubiquitous transport protocols, such as HTTP.
Using an emerging groups of standards, organizations are able to make software available as a
service over the internet. When you use a Web service in your application, you do not need to
know the software that it is written in, or much about it at all. The standards are:
● WSDL (Web services Description Language)

● J2EE Web services, which will be included in the next version of J2EE (J2EE 1.4
● UDDI (Universal Description, Discovery and Integration)
● SOAP (Simple Object Access Protocol)
and they build upon the existing XML and HTTP protocols.
Each Web service has a WSDL document which contains all the information you need in order
to use the service: the location of the service, its name, and information about the method that
the Web service exposes.
For information about the standards that Web services are built on, refer to:
18-5
What is WSDL?
What is SOAP?
Related Topics
Web Services
18-6
J2EE and Oracle SOAP Based Web services
JDeveloper supports the development of Web services for two different environments. This
book in the online help contains information about creating both types of Web service, and
information about deploying them can be found in the Packaging and Deploying book in this
online help.
J2EE Web Services
J2EE based Web services which run on Oracle9iAS Containers for J2EE (OC4J) are packaged
and deployed in the same way as other OC4J applications.
● You have to define an application server connection to OC4J before creating the Web
service.
● Then you invoke the Web Service Publishing Wizard and allow it to generate all the files
needed for your Web service, including the deployment profile and web.xml file. Refer
to Creating a J2EE Web Service.
● Deployment is then just a single mouse click, and it is described in Deploying J2EE Web
Services to OC4J in the Packaging and Deploying book.
Web Services for SOAP Servers
Creating a Web service for deployment on a SOAP server is also a straightforward process.
● You have to define a connection to the SOAP server before creating the Web service.
● Then you invoke the Web Service Publishing Wizard and allow it to generate the files
needed for your Web service. Refer to Creating a SOAP Web Service.
● You have to manually create a deployment profile, and then you deploy the the service to
the SOAP server. This is described in Deploying a Web service to an Oracle9i Release 2
SOAP Server and Deploying a Web Service to an Apache SOAP Server in the
Packaging and Deploying book.
● Finally, you register the Web service with the SOAP server.
Related Topics
18-7
Using Web services
18-8
What is WSDL?
The Web services Description Language (WSDL) is an XML language used to describe the syntax of Web service
interfaces and their locations.
When you use the Web service Publishing Wizard to produce your web service, the WSDL document is automatically
generated. Alternatively, if you want to create your own WSDL document JDeveloper can create an outline WSDL
document for you to work on.
You do not need to be able to write your own WSDL document in order to create a web service using JDeveloper, but if
you do the remainder of this topic gives you additional information about WSDL documents that will help you.
Javadoc Comments in WSDL Documents
The WSDL document that defines your web service may contain XML <documentation> tags. These can occur at both
the service and operation level. These are generated as class level Javadoc comments (for service level comments) or
method level Javadoc comments (for operation level comments).
Using Tag Insight
If you have created an outline WSDL document, or if you are an expert user, you can edit the WSDL document in the XML
Editor. This gives you the advantage of Tag Insight, which displays a list of available tags when you type "<" and pause for
a second or two.
Example of a WSDL Document
The example below is a WSDL document generated by JDeveloper for a simple service which returns the current date
and time as a string.
<?xml version = '1.0'?>



<definitions
name="DateTimeService"
targetNamespace="http://www.myorg.com/jdeveloper/generated/datetimepackage/DateTimeService"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://www.myorg.com/jdeveloper/generated/datetimepackage/DateTimeService"
xmlns:ns1="http://www.myorg.com/jdeveloper/generated/datetimepackage/DateTimeService/schema">
<types>
<schema
targetNamespace="http://www.myorg.com/jdeveloper/generated/datetimepackage/DateTimeService/schema"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"/>
</types>
<message name="getDateResponse">
<part name="return" type="xsd:string"/>
</message>
<portType name="DateTimeServicePortType">
<operation name="getDate">
<output message="tns:getDateResponse" name="getDateResponse"/>
18-9
</operation>
</portType>
<binding name="DateTimeServiceBinding" type="tns:DateTimeServicePortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="getDate">
<soap:operation soapAction="" style="rpc"/>
<output>
<soap:body use="encoded"
namespace="urn:datetimepackage.DateTimeService"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</output>
</operation>
</binding>
<service name="DateTimeService">
<port name="DateTimeServicePort" binding="tns:DateTimeServiceBinding">
<soap:address location="http://138.3.17.99/soap/servlet/soaprouter"/>
</port>
</service>
</definitions>
Structure of an WSDL DSocument
The WSDL specification describes it as "...an XML grammar for describing network services as collections of
communication endpoints capable of exchanging messages." The diagram below illustrates the elements that are present
in a WSDL document in terms of this, and indicates their relationships.
18-10
WSDL Document Elements
A WSDL document has a definitions element that contains the other five elements, types, message, portType, binding and
service. The following sections describe the features of the generated client code.
WSDL supports the XML Schemas specification (XSD) as its type system.
definitions
Contains the definition of one or more services. JDeveloper generates the following attribute declarations for
this section:
name is optional.
targetNamespace is the logical namespace for information about this service. WSDL
documents can import other WSDL documents, and setting targetNamespace to a unique value
ensures that the namespaces do not clash.
xmlns is the default namespace of the WSDL document, and it is set to

http://schemas.xmlsoap.org/wsdl/. All the WSDL elements, such as <definitions>, <types>
and <message> reside in this namespace.
xmlns:xsd and xmlns:soap are standard namespace definitions that are used for specifying
SOAP-specific information as well as data types.
xmlns:tns stands for this namespace.
xmlns:ns1 is set to the value of the schema targetNamespace, in the <types> section.
Notice that the default of http://tempuri.org in namespaces to ensure that the namespaces are unique.
types
Provides information about any complex data types used in the WSDL document. When simple types are
used the document does not need to have a types section.
message
An abstract definition of the data being communicated. In the example, the message contains just one part,
response, which is of type string, where string is defined by the XML Schema.
operation
An abstract description of the action supported by the service.
portType
An abstract set of operations supported by one or more endpoints.
binding
Describes how the operation is invoked by specifying concrete protocol and data format specifications for the
18-11
operations and messages.
port
Specifies a single endpoint as an address for the binding, thus defining a single communication endpoint.
service
Specifies the port address(es) of the binding. The service is a collection of network endpoints or ports.
Related Topics
Creating a WSDL Document
Web Services
18-12
Creating a WSDL Document
When you create a Web service using the Web service Publishing Wizard, the WSDL
document is automatically created for you, however there may be times when you want to
create a WSDL document directly. This topic describes how to do that.
JDeveloper can create an outline WSDL document for you which contains the Definitions and
Types elements. The WSDL outline document is displayed in the XML Editor in JDeveloper,
and you can use JDeveloper's Tag Insight feature to assist you; when you type <, pause for a
second or two, and a list of available elements is displayed. Double-click on the one you want
to use.
To create a WSDL document:
1. In the Navigator pane, select the project where you want the WSDL document to be and
choose File | New.
2. In the New Gallery select Web services in Categories and WSDL Document in Items.
The New WSDL Document dialog is displayed.
3. Enter a name for the document, a directory where the document is stored and the
targetNamespace to be used in the document. If you leave the targetNamespace as the
default, a warning message is displayed when you click OK, and you must remember to
change the targetNamespace in the WSDL document before using it.
4. The WSDL document is displayed in the XML Editor for you to work on.
Related Topics
What is WSDL?
Using Web services
18-13
Editing a WSDL Document
If you have generated your Web service using the Web service Publishing Wizard, you should
not edit the WSDL document directly. Instead, you should edit the Web service deployment
container (the node on the navigator which contains the WSDL document and the deployment
descriptor file). This reopens the Web service Publishing Wizard and you can change details on
the three pages. See Editing a Web service.
If you have created an outline WSDL document, or if you are an expert user, you can edit the
WSDL document in the XML Editor. This gives you the advantage of Tag Insight, which
displays a list of available tags when you type "<" and pause for a second or two.
To edit a WSDL document:
1. Select the WSDL document in the Navigator pane. Right click and choose Edit from the
context menu.
2. The WSDL document is opened in the XML Editor.
Related Topics
What is WSDL?
Using Web services
18-14
Supported Types
WSDL types in JDeveloper are defined by XML Schema. This topic lists the supported types in
JDeveloper.
JDeveloper supports primitive XML Schema types and arrays of primitive XML Schema types.
The following table lists the supported XML Schema types and the Java types they map to:
XML Schema type Java type

string java.lang.String
boolean java.lang.Boolean
decimal java.lang.Double
float java.lang.Float
double java.lang.Double
headers="xml"dateTime java.util.Date
time java.util.Date
date java.util.GregorianCalendar
base64Binary java.lang.Byte[]
normalizedString java.lang.String
integer java.lang.Integer
long java.lang.Long
int java.lang.Integer
short java.lang.Short
byte java.lang.Byte
Limitations
Mapping char and char[]
The Java types char and char[] are mapped by the JDeveloper's Web service generator to
String, therefore they exist in the generated WSDL documents and Web service stubs as
Strings. However the server does not make an equivalent mapping, and will return an error
reporting that the requested method could not be found. To avoid this problem, you can write a
wrapper class to convert char[] to String, or write a serializer for char and char[], and register it.
Type Mapping by Hand
When a type described by the WSDL document cannot be understood by the Web services
18-15
Stub/Skeleton generator, an UnknownType placeholder is generated. This will intentionally not
compile. In addition, the generated stub class will contain some comments near the top of the
file. To resolve this, you should do the type mapping by hand. You can write your own SOAP
serializer/deserializer, which takes the Java type and converts it into a SOAP representation
using SOAP encoding rules. You need to describe serializer/deserializer for each Java type in
the Web Service Deployment Descriptor.
There is an example that may help you in Chapter 9 of the Web services Developer's Guide
(Part No. A95453-01), which is part of the Oracle9i Application Server Release 2
documentation set. It can also be found at the Oracle Technology Network (OTN), on
//otn.oracle.com/products/jdev/.
Related Topics
What is WSDL?
SWeb Services
18-16
What is SOAP?
The Simple Object Access Protocol (SOAP) is an a lightweight XML based protocol. It
combines SOAP based requests and responses with transport protocols, for example HTTP, so
that an application can use a service that has been made available as a Web service across
the Internet. JDeveloper hides this complexity from you, and allows you to create and use Web
services without needing to know much about how SOAP works.
How SOAP Works
The SOAP specification provides a standard way to encode requests and responses. It
describes the structure and data types of message payloads using XML Schema.
The way that SOAP is used for the message and response of a web service is:
● The SOAP client uses an XML document that conforms to the SOAP specification and
which contains a request for the service.
● The SOAP client sends the document to a SOAP server, and the SOAP servlet running
on the server handles the document using, for example, HTTP or HTTPS.
● The Web service receives the SOAP message, and dispatches the message as a
service invocation to the application providing the requested service.
● A response from the service is returned to the SOAP server, again using the SOAP
protocol, and this message is returned to the originating SOAP client.
If you would like to find out more about SOAP, you can read the SOAP specification at
http://www.w3c.org/TR/SOAP.
For more information about XML Schema, refer to http://www.w3.org/XML/Schema.
Related Topics
Web Services
18-17
18-18
What is the Deployment Descriptor?
The deployment descriptor is an XML document that is created when you use the Web Service Publishing Wizard
to generate a Web service for deployment on a SOAP server. It contains information about the Web services you
are deploying, and defines the following information:
● The service ID
● The service provider type, in this case Java
● The available methods
The name of the file is <class_name.dd>.
JDeveloper generates a different deployment descriptor file for the Oracle SOAP Server and the Apache SOAP
Server. Examples of deployment descriptors for the same Web service generated by JDeveloper for each of the
SOAP servers are shown below.
This example shows a deployment descriptor file for the Oracle SOAP Server.
<?xml version = '1.0'?>




<isd:service
id="urn:datetimepackage.DateTimeService"
type="rpc"
xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/service">
<isd:provider
id="java-provider"
methods="getDate"
scope="Request">
<isd:java class="datetimepackage.DateTimeService" static="false"/>
</isd:provider>
<isd:faultListener
class="org.apache.soap.server.DOMFaultListener"/>
</isd:service></isd:service>
The isd:service id element shows the URI identifier (prefixed by urn:) for the Web service, the isd:java
class element identifies the Java class that implements the Web service and indicates whether methods on the
class should be invoked statically, and the isd:provider element shows the methods available from this Web
service.
Related topics
Web Services
18-19
18-20
Getting Started with Web Services
Before creating a Web service, or using the Web Service Stub/Skeleton Wizard to use a Web
service, you may have to set the proxy in JDeveloper so that you can connect through the
firewall. See Configuring JDeveloper to Generate Web Service Stubs.
If you are generating J2EE Web services, you must first define a connection to OC4J. For more
information, refer to Creating a Connection to Oracle9iAS Containers for J2EE (OC4J).
If you are generating Web services for deployment on SOAP servers, you should first define a
connection to your SOAP server. For more information, refer to Configuring SOAP Server
Connections.
Related Topics
Web Services
18-21
Configuring JDeveloper to Generate Web Service
Stubs
If your organization uses a firewall, and you are going to use a (WSDL) document that is
outside your organization's firewall, you first have to set the proxy server host name in
JDeveloper. This allows JDeveloper to connect to the external Web service description
document for the information it needs to generate the stub class.
To set the Proxy Server Host Name:
1. Select Tools | Preferences from the JDeveloper main menu.

2. In the Preferences dialog, select the Proxy Server node.
3. In the Proxy Server Preferences page, select Use proxy server.
4. In Proxy server host name, enter the name of the proxy server. This may be the same
proxy server name you use in your browser to access the internet through the firewall. If
you are not sure of the proxy server host name or port number to use, you should
contact your network administrator.
5. In Proxy server port number, enter the port number for the proxy server.
6. Click OK. The values you entered here will be used by the Web services Stub/Skeleton
Wizard when you specify an external Web service description.
Related Topics
Web Services
18-22
Note: You only use these connections for deploying Web services that have been created for
deployment on a SOAP server. J2EE Web services are deployed to an application server
across an Application Server connection. For more information, refer to Creating a Connection
to Oracle9iAS Containers for J2EE (OC4J).
You can create and manage your SOAP server connections using the SOAP Server
Connection Wizard, and JDeveloper automatically detects which of the SOAP server types the
connection is to. If the SOAP Server sits behind a Web server which requires basic HTTP
authentication, you can specify the username and password and these will be used to connect
successfully.
SOAP server connections are stored under the SOAP Server node, which is under the
Connections node in the Navigator pane. When you register a Web service with a SOAP
server, that service is listed under that server's node in the Navigator pane.
By right clicking a SOAP Server connection you can select the following options from the
context menu:
New
This displays the SOAP Server Connection Wizard so that you can add a new
connection.
Edit
You can change the connection and authentication details, and test the
connection.
Refresh Connection
This connects to the SOAP Server and refreshes the list of services registered on
that service so that, for example, a service registered by another user will be
displayed in the Navigator pane.
Delete Connection
This deletes the connection to the SOAP Server. However any services deployed
and registered on that server are not affected, and should you delete a connection
in error you can recreate it and registered services will be displayed under that
18-23
connection node.
The file system location for the SOAP connection information is

<JDeveloper_home>\jdev\home\soapconn.xml, where <JDeveloper_home> is the
location where JDeveloper was installed.
Related Topics
Defining SOAP Server Connections
Editing a SOAP Server Connection
Refreshing a SOAP Server Connection
Deleting a SOAP Server Connection
Web Services
18-24
Defining SOAP Server Connections
You create SOAP server connections using the SOAP Server Connection Wizard.
To create a new SOAP server connection:
1. In the Navigator pane, expand the Connections node and select the SOAP Server node.
2. Right click and choose New Connection from the context menu. The SOAP Server
Connection Wizard is displayed.
4. On the Connection Details page, enter a name for the connection and a SOAP Servlet
URL for the connection. For information about the format of the URL, click Help on the
dialog. Click Next.
5. On the Test page, click Test Connection. JDeveloper checks the connection using the
information you provided. If the test succeeds, a success message appears in the status
text area. If the test does not succeed, an error appears.
6. When the test succeeds, click Finish. The SOAP Server Connection Wizard closes, and
the new SOAP connection name appears under the Connections, SOAP Server node in
the Navigator pane.
Having Problems?
If the connection fails, try the following:
● Check that the SOAP server is running by by entering the SOAP servlet URL in a
browser. If you can see a message from the SOAP server then the server is running, and
the fault is elsewhere.
● Check that the URL, and username and password you entered for the connection are
correct.
If the connection still fails, contact your application server administrator for assistance.
Related Topics
18-25
Web Services
18-26
Editing a SOAP Server Connection
You can edit an existing SOAP server connection in JDeveloper, for example to change the
name of the connection, to correct an incorrect SOAP Servlet URL, or to test that the
connection works.
To edit a SOAP server connection:
1. In the Navigator pane, expand the Connections node, then the SOAP Server node, and
select the connection you want to edit.
2. Right click and choose Edit from the context menu. The SOAP Server Connection
Wizard is displayed.
3. To change the name of the connection or the SOAP Servlet URL, make your changes on
the Connection Details page.
4. To change the authentication details, choose the Authentication tab, and make your
changes.
5. To test the connection (recommended if you have changed the SOAP Servlet URL),
choose the Test tab and click Test. The results of the test are displayed on the screen.
Related Topics
Web Services
18-27
Refreshing a SOAP Server Connection
You can refresh a SOAP server connection to update the list of Web services on that server in
the Navigator pane.
To refresh a SOAP server connection:
1. In the Navigator pane, expand the Connections node, then the SOAP Server node, and
select the connection you want to refresh.
2. Right click and select Refresh Connection from the context menu.
Related Topics
Web Services
18-28
Deleting a SOAP Server Connection
If you no longer use a SOAP server connection, you can delete it from JDeveloper.
To delete a SOAP server connection:
1. In the Navigator pane, expand the Connections node, then expand the SOAP Server
node.
2. Select connection you want to delete, right click and choose Delete Connection from the
context menu.
3. A message is displayed asking whether you want to delete the connection. Click Yes.
Related Topics
Web Services
18-29
Registering a Web service With a Soap Server
JDeveloper creates Web services that can be deployed to:
● Oracle9iAS Release 2 SOAP server

● Apache 2.2 SOAP server
The procedure for registering the service is different for Oracle SOAP servers and Apache
SOAP Servers, and only that for an Oracle SOAP server is described here. You should consult
the Apache SOAP server documentation for information on registering a Web service on an
Apache SOAP server.
Registration only makes the SOAP server aware of the service, and you must deploy the Web
service before registering it. See Deploying a Web service.
To register a Web service with an Oracle SOAP Server:
1. Select the deployment container for the Web service in the Navigator pane. This is the
node that contains the WSDL document and the deployment descriptor file.
2. Choose Register with from the context menu and select the SOAP server that you
selected when you used the Web service Publishing Wizard.
If you need to create a new SOAP server connection to the SOAP server choose New
Connection which starts the SOAP Server Connection Wizard.
3. The Web service is now displayed in the Navigator pane under the node for that SOAP
server (under Connections).
Now that you have created and deployed your Web service, you should test it. You can do this
by using the Web Service Stub/Skeleton Wizard to create a stub to the service, then writing a
Java class to use the stub and return something from the service.
Related Topics
Developing a Web service
18-30
Web Services
18-31
Unregistering a Web service from a SOAP Server
If you no longer want a Web service to be listed for a SOAP server, you can unregister it.
The procedure for unregistering the service is different for Oracle SOAP servers and Apache
SOAP Servers, and only that for an Oracle SOAP server is described here. You should consult
the Apache SOAP server documentation for information on unregistering a Web service from
an Apache SOAP server.
To unregister a Web service with an Oracle SOAP Server:
1. Expand the node for the SOAP server in the Navigator pane, and select the Web service
you want to unregister.
2. Right click and select Unregister.
Related Topics
Developing a Web Service
Web Services
18-32
Developing Web Services
The Web Service Publishing Wizard generates the files that allow you to expose one or more
methods as Web services from:
● Simple Java classes

● The remote interface of an Enterprise JavaBean (stateless and stateful session beans,
and entity beans).
You can create them as J2EE Web services, which are deployed to OC4J, or as Web services
for deployment to SOAP servers.
In the Web Service Publishing Wizard you select the appropriate Java class and the type of
server on which you are going to deploy the service. Next you enter select the available
methods to expose as a Web service. Finally you enter file locations for the WSDL document
and other generated deployment files, and specify a targetNamespace which uniquely identifies
the Web service.
Once the Web service has been generated you make it available by deploying it. For more
information, refer to Ways to Deploy Web Services.
For information about creating J2EE Web services, refer to Creating a J2EE Web Service.
For information about creating Web service for deployment to SOAP servers, refer to Creating
a SOAP Web Service.
Related Topics
Web Services
18-33
Creating a J2EE Web Service
JDeveloper's Web Service Publishing wizard makes it easy to generate and publish a J2EE
Web service. You can create a J2EE Web service from:
● a simple Java class

● an Enterprise JavaBean (stateless and stateful session beans, and entity beans). You
must use the remote interface of the EJB.
● a BC4J module wrappered as a stateless EJB.
When you are developing J2EE Web services for deployment to different servers, you have to
create each in a different project. This is because the deployment profile and web.xml files are
specific to the application server connection you select, and they exist at project level.
Note: In step 3 of the Web services Publishing Wizard, you have to select the application
server to which you will deploy the service, therefore you shouldcreate the connection before
continuing.
To create a J2EE Web service:
1. With the project containing your Java class or EJB selected in the JDeveloper Navigator,
edit the project settings to set an appropriate context root name. This name will appear in
the URL of anyone needing to access your service.
Right click on the project, and choose Project Settings from the context menu. Select
J2EE in the left pane. J2EE Web Context Root is one of the fields on the right. Click Help
2. With the project still selected in the JDeveloper Navigator, choose File | New. In the New
Gallery, choose Web Services in the Categories pane and Web Service in the Items
pane. The Web Service Publishing Wizard is displayed.
3. If the Welcome page is displayed read the summary on it, then click Next.
4. Click Browse to select the Java class or the remote interface of a stateless EJB
containing the method that you want to publish.
5. A default URI is displayed. You can use the default, or change it to a different URI.
6. In Deployment Platform, leave the default of Oracle J2EE Web service. Click Next.
7. The methods available to publish as Web services are listed. If you have used the
@webmethod Javadoc comment to identify the methods in the Java class, they will
already be selected.
18-34
8. Some methods may be shown grayed out. In this case the Why Not? button is enabled.
If you select one of the grayed out methods and click Why Not? a message box is
displayed explaining why the method is not suitable for publishing as a Web service.
9. By default, the Web service will be stateless, that is, information is not held by the
application between calls. If you want information to be maintained across a session,
check Stateful.
10. When you have selected the method or methods you want to publish, click Next.
11. The wizard displays defaults for the WSDL Document URL. You can accept it, or
overwrite it with your own location.
12. The Deployment Description File URL is a read-only field which displays the location of
the web.xml file.
13. From the drop-down list, select the Application Service Endpoint. This is the application
server connection you defined earlier.
14. Either accept the default Web Server Port No or enter a different one.
15. The read-only Web Service Endpoint is made up of:
❍ the URL of the application server
❍ the context root. For more information about context roots, refer to refer to
❍ the Web service name you entered on the first page of the wizard
16. The wizard displays a targetNamespace which is made up of:

❍ http://tempuri.org
❍ generated
❍ the name of the package
❍ the name of the Java class
While you are developing your Web service and testing it you can use the default,
but before you publish it you must replace it with a targetNamespace that is
universally unique. For example, you could replace http://tempuri.org with your
organization's internet domain name. The targetNamespace does not have to
point to an actual Web address.
17. When you click Finish, JDeveloper generates:

❍ WSDL document for the Web service, which is displayed in the Navigator pane
under the deployment descriptor node
❍ web.xml. When there is an existing web.xml file for the project it is added to.
18-35
❍ WAR deployment profile called WebService.deploy
❍ when you select only some of the available methods, an interface is generated for
the methods you have selected. It has the same name as your original Java class,
prefixed by I.
Now that you have generated the deployment information for your J2EE Web service, the final
step is to deploy the files to OC4J. This is the same as deploying any other J2EE Web
Application. Refer to Deploying J2EE Web Services to OC4J in the Packaging and Deploying
book in the online help.
Related Topics
Web Services
18-36
Creating a SOAP Web Service
JDeveloper's Web Service Publishing wizard makes it easy to generate and publish a SOAP
Web service. You can create a Web service from:
a simple Java class

● an Enterprise JavaBean (stateless and stateful session beans, and entity beans). You
must use the remote interface of the EJB
● a BC4J module wrappered as a stateless EJB
Note: You should create a connection to your SOAP server before proceeding.
To create a Web service:
1. With the project containing your Java class or EJB selected in the JDeveloper Navigator,
choose File | New. In the New Gallery, select Web Services in the Categories pane and
Web Service in the Items pane. The Web Service Publishing Wizard is displayed.
2. If the Welcome page is displayed read the summary on it, then click Next.
3. Click Browse to select the Java class or remote interface containing the method that you
want to publish.
4. A default URI is displayed. You can use the default, or change it to a different URI.
5. In Deployment Platform, select the SOAP server on which you will deploy your Web
service. Click Next.
6. The methods available to publish as Web services are listed. If you have used the
@webmethod Javadoc comment to identify the methods in the Java class, they will
already be selected.
7. Some methods may be shown grayed out. In this case the Why Not? button is enabled.
If you select one of the grayed out methods and click Why Not? a message box is
displayed explaining why the method is not suitable for publishing as a Web service.
8. Check Show Superclass Methods to show the available methods on superclasses of the
current class.
9. Check Invoke Methods Statically if you want to ensure that the methods you publish are
invoked statically.
10. When you have selected the method or methods you want to publish, click Next.
11. The wizard displays defaults for the WSDL Document URL and the Deployment
Description File URL. You can accept these, or overwrite them with your own locations.
18-37
12. From the drop-down list, select the Web Service Endpoint. This is a list of the SOAP
server connections you have defined. If you want to define a new SOAP server
connection, click New to invoke the SOAP Server Connection Wizard.
13. The wizard displays a targetNamespace which is made up of:
❍ http://tempuri.org
❍ generated
❍ the name of the package
❍ the name of the Java class
While you are developing your Web service and testing it you can use the default, but
before you publish it you must replace it with a targetNamespace that is universally
unique. For example, you could replace http://tempuri.org with your organization's
internet domain name. The targetNamespace does not have to point to an actual Web
address.
14. When you click Finish, JDeveloper generates:

❍ a WSDL document that describes your Web service and gives its location.
❍ a Deployment Descriptor file that is used for deployment.
These files are displayed in the Navigator pane under the deployment descriptor
node.
Now that you have created the deployment information for your Web service, the next stage is
to deploy the files you have generated. The information about deploying a Web service is
contained in the Packaging and Deploying book in the JDeveloper's Help contents list.
After you have deployed the service, you must register the Web service so that it is available
for use.
Related Topics
Registering a Web service
18-38
Web Services
18-39
Editing a Web Service
You can edit a Web service that you have created in JDeveloper, for example, to change the
exposed method or a file location.
Note: when you edit a Web service the previously generated files are overwritten, and any
changes you have made will be lost. If you have already deployed the Web service and you
edit it, you must redeploy it.
To edit a Web service:
1. In the Navigator pane, select the Web service container (the node containing the WSDL
document and deployment descriptor).
2. Right click and choose Edit from the context menu. The Web Service Publishing Wizard
is displayed.
3. To change the class, the URI identifier for the service or the deployment platform, make
your changes on the Web service Class, URI and Deployment Platform page.
4. To change the method to expose or one of the related options, choose the Exposed
Methods tab, and make your changes.
5. To change one or more of the file locations, or to change the targetNamespace, choose
the File Locations tab.
Related Topics
Web Services
18-40
Creating More Complex Web Services
This section is aimed at Java developers who are experienced at using JDeveloper. It contains
topics that describe how to use JDeveloper, along with some hand-coding, to create more
complex types of Web services.
Publishing BC4J Application Modules as Web Services
Creating Web Services with Custom Bean Parameters in the Method Signatures
18-41
Publishing BC4J Application Modules as Web Services
After exporting custom methods of your BC4J application module, you can publish those methods as a Web service using one
of these two techniques:
● Generate a Web service class for your application module, then publish it as a simple Java class using the Web Service
Publishing Wizard.
● Deploy a Stateless EJB Session Bean for your application module, then publish its remote interface using the Web
Service Publishing Wizard.
The first technique is the simplest. The second technique is best if your service needs to interact with other EJB session beans
as part of its implementation.
Generating a Web Service Class for Your Application Module
After creating your application module and exporting at least one of its custom methods using the Application Module Editor's
Client Methods tab, you can select the Generate Web Service Class option from the context menu for the application module
in question. The Web service class allows you to publish a stateless, BC4J-based Web service using the BC4J application
module pooling facilities, running in local mode, or using any of the other deployment modes supported by BC4J.
Selecting this option adds a class <YourAppModuleName>WS.java to your project. You can then publish this Web service
class using the Web Service Publishing Wizard.
Note: since the Web service class is generated code, if you modify the set of exported client methods on your application
module, you need to regenerate the Web service class by selecting Generate Web Service Class again.
Before using the WebServices.deploy profile to deploy your class, edit its settings and click on the WEB-INF/classes node.
Make sure all of the BC4J project's files are included in the list, including *.java, *.xml, *.jpx, and bc4j.xcfg. A quick
way to do this is to select the entire project for inclusion, if that is appropriate.
If it is applicable, you can further optimize the stateless use of the BC4J application module pool for Web services by
considering either or both of the following BC4J properties which you can set for your configuration using the Properties tab of
the Configurations wizard. To edit your configuration, right click on your application module in the Navigator, and choose
Configurations from the context menu. The two properties of interest are:
❍ jbo.ampool.dynamicjdbccredentials = false
The default is true, which allows each user to dynamically provide new username/password credentials
for each use of the application module.
If you know your application module will always use the same username, you can optimize the use of the
application module by setting this property to false.
❍ jbo.ampool.resetnontransactionalstate = false
This setting controls whether non-transactional resources like cached JDBC prepared statements are
thrown away when the application module is checked back into the pool. The default is true since
JDeveloper 3.2 had this behavior and since sharing the non-transactional application module state (e.g.
VO where clauses, view criteria, etc.) should be done consciously.
By setting this property to false prepared statements can be shared across uses of the pooled
application module, avoiding the JDBC overhead of recreating and reparsing them.
18-42
To use your configuration property settings at runtime, make sure that the name of the configuration passed to the
Configuration.createRootApplicationModule() method is the same as the name of the configuration where you
set the properties.
Deploying a Stateless EJB Session Bean for your application module
You can change a stateful service session bean to stateless, then publish its remote interface using the Web Service
Publishing Wizard.
By default, when you publish a BC4J application module as a Service Session Bean, the BC4J design time wizard code-
generates a bean implementation class that is a stateful session bean. Since OC4J only supports stateless EJB Web services
in this release, if you want to publish your application module-based session bean as a Web service, you need to change your
BC4J-based service session bean to be stateless.
Alternatively, you can use the technique described below to create a BC4J Web service class "wrapper" that uses the BC4J
application module pool in local mode. To accomplish this, follow the steps outlined in below.
Your generated bean implementation class will have a method like:
public void ejbCreate() throws java.rmi.RemoteException, javax.ejb.CreateException

{
createApplicationModule("mypkg.MypkgModule");
}
and one or more method implementations for the exported methods that appear on the session bean's remote interface. For
example, you might see one or more methods like this:
public String someExposedMethod(int x) throws java.rmi.RemoteException

{
try
{
return getMypkgModule().someExposedMethod(x);
}
catch(oracle.jbo.JboException ex)
{
// Convert JboException to service exception below
// Business methods shouldn't throw RuntimeException
throw ex;
}
}
To turn this stateful BC4J-based session bean into a stateless session bean:
1. Comment out the createApplicationModule() call from the ejbCreate(), leaving an method that looks
like this:
public void ejbCreate() throws java.rmi.RemoteException, javax.ejb.CreateException

{
// To make stateless, comment this line out
// createApplicationModule("mypkg.MypkgModule");
}
2. For each method in the bean that implements a method on the Session Bean's remote interface (i.e. one for each
18-43
exported method in your application module), perform the following four steps to augment the existing method
body:
■ Copy/paste the createApplicationModule("mypkg.MyModule") line from above, and put it first,

just inside the try.
If you want to pass environment settings that you have set as part of a BC4J configuration, you can
optionally pass the desired configuration name as the second parameter to this method.
■ Add a line to connect the application module to a datasource.
■ Add a catch block to handle the javax.ejb.CreateException
■ Add a finally block that contains a call to removeApplicationModule()
So, for example, the someExposedMethod() above would end up looking like this:
// NOTE: Need to add imports for javax.ejb.CreateException and java.rmi.RemoteException

public String someExposedMethod(int x) throws java.rmi.RemoteException
{
try
{
// (Step 1) Add this line -- Create the application module
createApplicationModule("mypkg.MypkgModule");
// (Step 2) Add this line -- Connect the appmodule to a datasource using the
// ejb-location name of the datasource from the data-sources.xml file
getApplicationModule().getTransaction().connectToDataSource(null,"jdbc/OracleDS",false);
return getMypkgModule().someExposedMethod(x);
}
// (Step 3) Add this catch block
catch(CreateException ex)
{
throw new RemoteException("Create error", ex);
}
catch(oracle.jbo.JboException ex)
{
// Convert JboException to service exception below
// Business methods shouldn't throw RuntimeException
throw ex;
}
// (Step 4) Add this finally block to remove the appmodule
finally {
// Add this line -- Remove the application module
removeApplicationModule();
}
}
Lastly, you need to edit the EJB Session Bean properties to change the setting from Stateful to Stateless. The simplest way to
do this is to select your Session Bean in the Navigator and choose EJB Class Editor from the context menu. Then, on the
EJB/Session tab of the editor, set Session Type to Stateless.
Related Topics
18-44
Web Services
18-45
Creating Web Services with Custom Bean
Parameters in the Method Signatures
In this release of JDeveloper the Web Service Publishing Wizard does not support publishing
methods whose return type, or any of whose arguments, is of a custom Java Bean type.
However the OC4J Web Services container does support Java Bean return values and
argument types.
This topic describes how to use the Web Services Publishing Wizard and built-in J2EE
deployment features, along with some hand-coding, to create a Web service based on a class
with Java Bean return value and/or arguments.
Once the Web service has been deployed, you produce the client stub for this service by using
a browser to locate the deployed Web service files you need.
The class CustomerService.java (shown below) is used to illustrate this procedure.
// Simple customer service with Bean-valued properties - for example only

package mypkg;
public class CustomerService
{
private static Hashtable customers = new Hashtable();
public void setContact(String custName, Contact c) {
Customer cust = (Customer)customers.get(custName);
if (cust != null) cust.setContact(c);
}
public Contact getContact(String custName) {
if (cust != null) return cust.getContact();
else return null;
}
public void addOrUpdateCustomer(Customer c) {
if (c != null) {
Customer customer = (Customer)customers.get(c.getName());
if (customer == null) {
customer = new Customer();
customer.setName(c.getName());
customers.put(c.getName(),customer);
}
customer.setBalance(c.getBalance());
}
}
18-46
public Customer getCustomer(String custName) {
if (cust != null) return cust;
else return null;
}
}
This class references the Java Bean parameters mypkg.Customer that represents a
customer type, and mypkg.Contact that represents the main contact for a customer.
Publishing the Web Service
You have to make sure that the class containing the method you want to publish as a Web
service contains a method which the Web Service Publishing Wizard can recognize. If
necessary, you must add a dummy method to your implementation class.
Once the JDeveloper has generated the files needed for deployment, you can edit the Java
files to remove the dummy method (if you used one) and add JavaBean method signatures to
both the original Java class and the generated Java interface.
Finally, you deploy the Web service using JDeveloper's built-in J2EE deployment features.
To generate and deploy the Web service:
1. Edit the project settings to set an appropriate context root name. This name will appear
in the URL of anyone needing to access your service.
Right click on the project, and choose Project Settings from the context menu. Select
J2EE in the left pane. J2EE Web Context Root is one of the fields on the right. Click Help
2. f the class does not have any methods that do not use Java Bean types, like the example
class CustomerService, then temporarily add a dummy method:
// Dummy Method, will be removed later

public int foo() { return 0; }
3. Use the Web Service Publishing Wizard to create a Web service based on the
mypkg.CustomerService class. Make sure that the Deployment Platform you select
is Oracle J2EE Web Services.
All of the methods with JavaBean parameters will be disabled, but select one of the
enabled methods like foo() that you just added, and complete the wizard. The following
18-47
artifacts are generated:
❍ CustomerService.wsdl
❍ ICustomerService.java, the Web service interface
❍ web.xml, which contains appropriate entries needed to deploy the Web service
❍ WebServices.deploy. This is the deployment profile
4. Edit the WebServices.deploy settings by selecting it in the navigator and choosing

Settings from the context menu.
With the General category selected in the editor, examine the Enterprise Application
Name to make sure that it is appropriate.
Select the WEB-INF/classes node, and uncheck the CustomerService.wsdl
document. This means that it will not be included in the WebServices.war file.
Because it is not included, the OC4J Web Services container will generate the WSDL
document on the fly the first time the service is accessed. While it doesn't allow you to do
any hand-customization of the WSDL file within JDeveloper, this workaround allows you
to complete the task you have set out to accomplish.
5. Now remove the dummy method (if you created one) from your Java class and the
generated interface, in the example these are the CustomerService.java
implementation file and the ICustomerService.java interface.
6. Add method signatures to the interface corresponding to all of the methods from
implementation file that you want to publish. In the example, you would add the methods
to the ICustomerService.java interface that correspond to the methods in
CustomerService.java, so that the interface ends up looking like:
public interface ICustomerService

{
public void setContact(String custName, Contact c);
public Contact getContact(String custName);
public void addOrUpdateCustomer(Customer c);
public Customer getCustomer(String custName);
}
7. Build the project, then deploy it by right clicking on WebServices.deploy in the

Navigator and selecting Deploy to from the context menu.
After Deployment
When you add methods to the implementation class, remember to add the equivalent method
18-48
signature to the corresponding interface file to keep the two in synch. Similarly, if you remove
methods from the implementation class, remove them from the corresponding Web service
interface file too.
If you have already deployed your Web service, and subsequently make changes to the
interface, remember to redeploy the Web service.
Getting the WSDL Service Description and Client-Side Stub JAR
A deployed Web service has the following files on the server:
● WSDL service description. In this case, the WSDL document is created the first time the
service is accessed.
● Client-side stub JAR (class files)
● Client-side stub source
To obtain the WSDL document for the service you have published, paste this URL into a
browser :
http://host:port/<context_root>/<web_service_name>?WSDL
In this release of JDeveloper, you cannot use the Web Service Stub/Skeleton Wizard to
produce the client-side proxy stubs for a service with JavaBean parameters. Instead , you can
get the client stubs from the server where the service resides by pasting this URL into a
browser:
http://host:port/<context_root>/<web_service_name>?PROXY_JAR
After saving the retrieved JAR file to disk, you can define a new library in your current project
that points to it to begin using the proxy stub classes. Alternatively you can browse this URL to
retrieve a JAR file with the source code for the client stubs:
http://host:port/<context_root>/<web_service_name>?PROXY_SOURCE
After saving the retrieved JAR file, you can add this source code to your JDeveloper project to
compile and use.
18-49
Related Topics
Web Services
18-50
Using a Web Service
JDeveloper makes it easy to use a Web service in your application. The steps you perform are:
● In the Web Service Stub/Skeleton Wizard, enter the URL of the WSDL document, either
from a source on your local file system, or from a directory of Web services available on
the internet. The wizard connects to the WSDL document and identifies the Web service
or services available. See What is WSDL?
● From a list of the available methods available, select the ones you want to use.
● The wizard generates a Java class which contains the stub to the Web service in a
SOAP wrapper class. The code uses the Oracle SOAP API, which is compliant with the
Apache SOAP API. This means that the generated stub can be used with both Oracle
and Apache SOAP implementations.
● In your application, you can then call the methods in the generated class which are stubs
for the Web service.
The Web Service Stub/Skeleton Wizard allows you to:
● Generate a Java stub for calling a Web service. You enter the WSDL document for the
Web service. The wizard generates the stub, and you then use the stub in your
application to use the method exposed in the Web service.
● Generate a Java skeleton interface for implementing a Web service. The skeleton is
based on the Web service identified by the WSDL document you enter in the wizard, and
it allows you to quickly start creating a new Web service based on an existing one.
● List the WSDL document in the Navigator pane. This does not import the WSDL
document into the project. Rather, it makes it available in the navigator so that you can
connect to it and examine it by double-clicking the node in the Navigator pane.
From time to time you may want to regenerate your Java stub files, for example, if the WSDL
web service description has been updated. For more information, refer to Regenerating
Generated Stub Files.
Related Topics
Generating a Web service Stub or Skeleton
18-51
Web Services
18-52
Generating a Web Service Stub
JDeveloper allows you to generate a Web service stub to use a Web service. Once you have
generated the stub using the Web Service Stub/Skeleton Wizard, you can call the methods
(which are proxies to the Web service) in your application.
To generate a Web service stub:
1. In the Navigator pane, select the project you want to use.

2. Right click to select New from the context menu.
3. In the New Gallery, select Web Services in the Categories pane, and Web Service
Stub/Skeleton from the Items pane.
4. When you click OK, the Web Service Stub/Skeleton Wizard is displayed.
6. In the Select Web Service Description page, enter the filename or URL of the Web
service description (WSDL) document. The WSDL document can be:
❍ A file on the file system
❍ The URL of a Web service description on an external site.
Note: If you are using an external Web service description document, make sure that you
have set the proxy server host name for JDeveloper. For more information, refer to
Configuring JDeveloper to Generate Web Service Stubs.
7. Select the generation options you want:

❍ Generate Client-Side Stubs generates a stub for each method you select on the
next page.
❍ Generate Basic HTTP Authentication Code adds code for HTTP authentication to
the stub or stubs.
❍ Import WSDL URL Into Project makes the WSDL document available as a node in
the Navigator pane so that you can work entirely within JDeveloper.
8. When you click Next there may be short pause while JDeveloper retrieves the file or
connects to the external site to get information about the Web services available.
9. The Web services available are displayed in the Select Web Services to Use page.
When you have selected more than one Web service, a separate Java stub will be
generated for each Web service marked with a tick. By default they are all selected for
generation so deselect any you do not want.
18-53
10. The name of the Web service currently highlighted is displayed in the read-only Service
Name field.
11. (Optional) The default package for this project is displayed in the Package field. If you
want to generate the Web service stub for the currently selected Web service to another
package, type the new package name here.
12. (Optional) The default name for the Web service stub is displayed in the Class name. If
you want to generate the stub with a different name, type the new class name here.
13. Click Finish. The wizard generates a new stub or for each Web service, and they are
listed in the Navigator pane and displayed in the Code Editor.
Related topics
Web Services
18-54
Regenerating Generated Stub Files
From time to time you may want to regenerate your generated stub files, for example, if the
WSDL document has been updated.
Warning: When you do this, JDeveloper generates the stub file again, and you will lose any
changes that you have made to it since it was last generated. However we do not recommend that
you make any changes to a generated stub file.
To regenerate a stub file:
1. In the Navigator pane, select the stub file you want to regenerate.
2. Right click and select Regenerate the Web Service Stub/Skeleton from the context
menu. The file is automatically regenerated, and any changes you have made to it since
it was last generated are lost.
Related topics
Web Services
18-55
Generating a Web Service Skeleton
JDeveloper allows you to generate a Server-side skeleton to develop a new Web service based
on an existing one. It creates a Java class with the outline code to get you started.
To generate a Web service skeleton:
1. In the Navigator pane, select the project you want to use.

2. Right click to select New from the context menu.
3. In the New Gallery, select Web Services in the Categories pane, and Web Service
Stub/Skeleton from the Items pane.
4. When you click OK, the Web Service Stub/Skeleton Wizard is displayed.
6. In the Select Web Service Description page, enter the filename or URL of the Web
service description (WSDL) document. The WSDL document can be:
❍ A file on the file system
❍ The URL of a Web service description on an external site.
Note: If you are using an external Web service description document, make sure that you
have set the proxy server host name for JDeveloper. For more information, refer to
Configuring JDeveloper to Generate Web service Stubs.
7. Select Generate Server-Side Skeletons to generate a server-side skeleton class for each
method you select.
8. Optionally you can select Import WSDL URL Into Project, which makes the WSDL
document available as a node in the Navigator pane so that you can work entirely within
JDeveloper.
9. When you click Next there may be short pause while JDeveloper retrieves the file or
connects to the external site to get information about the Web services available.
10. The Web services available are displayed in the Select Web Services to Use page.
When you have selected more than one Web service, a separate Java skeleton will be
generated for each Web service marked with a tick. By default they are all selected for
generation so deselect any you do not want.
11. The name of the Web service currently highlighted is displayed in the read-only Service
Name field.
12. (Optional) The default package for this project is displayed in the Package field. If you
18-56
want to generate the Web service skeleton for the currently selected Web service to
another package, type the new package name here.
13. (Optional) The default name for the Web service skeleton is displayed in the Class
name. If you want to generate the skeleton with a different name, type the new class
name here.
14. Click Finish. The wizard generates a new skeleton for each Web service, and they are
listed in the Navigator pane and displayed in the Code Editor.
Related topics
Web Services
18-57
Using WebDAV Support
● Using WebDAV Support
● Creating a WebDAV Connection

● Accessing a WebDAV-Enabled Server Via a Proxy Server
● Modifying a WebDAV Connection
● Refreshing a WebDAV Connection
● Deleting a WebDAV Connection
● Managing Files and Folders on a WebDAV Connection
❍ Creating a New WebDAV Folder
❍ Uploading to a WebDAV Connection

❍ Downloading from a WebDAV Connection
❍ Using a Workspace Stored on a WebDAV Connection
❍ Using a Project Stored on a WebDAV Connection
❍ Using Files Stored on a WebDAV Connection
❍ Locking and Unlocking Files on a WebDAV Connection
■ Locking a File on a WebDAV Connection
■ Unlocking a File on a WebDAV Connection

■ Listing All Locked Files on a WebDAV Connection
19-1
Using WebDAV Support
WebDAV connections in JDeveloper allow you to work with files hosted on WebDAV servers in
the same way as you would work with files on the local file system.
Important: Before using WebDAV Connections in Oracle9i JDeveloper, you must first install the
WebDAV addin from the Oracle Technology Network website. For more information, refer to the
Installing Oracle9i JDeveloper guide for your operating system.
What is WebDAV?
Web-based Distributed Authoring and Versioning, or WebDAV, is an extension to HTTP which

allows users to collaboratively edit and manage files on WebDAV-enables servers.
Files located on WebDAV servers, accessed using WebDAV connections in JDeveloper, can
be edited and built in the same way as files stored on the local file system or LAN.
As WebDAV clients provide access using HTTP, files can be accessed through firewalls
(configured to support WebDAV extensions) that prevent ftp file transfer.
JDeveloper completely supports the current WebDAV 1.0 standard, which does not support
versioning. The file locking feature of WebDAV is supported, allowing files and folders to be
protected against change where development projects involve multiple distributed users.
As a WebDAV client, JDeveloper can connect directly to any Oracle Internet File System,
allowing you to cut,copy and paste content, edit content in place, and publish it directly from the
database.
WebDAV Server Requirements
To use JDeveloper as a WebDAV client, the WebDAV server must be one of the following:
● Oracle Internet File System 8.1.7 (or above)
● Apache 1.3.19 (or above)
Note: If the Apache server is version 1.x, the mod_dav module must also be installed.
● A server that conforms to the WebDAV 1.0 standard
19-2
Note: If you access the Internet through a firewall, it must be configured to process the extended
HTTP commands used by WebDAV.
More Information on WebDAV
If you'd like to find out more about WebDAV, refer to:
● http://www.webdav.org
● http://www.apache.org/docs-2.0/mod/mod_dav.html
Related Topics
Creating a WebDAV Connection
Accessing a WebDAV-Enabled Server Via a Proxy Server
19-3
WebDAV connections created in JDeveloper allow you manage files and folders as part of a
JDeveloper project.
Note: The same URL cannot be used for more than one WebDAV connection on the same
JDeveloper client.
To create a WebDAV connection in JDeveloper:
1. Click File | New | Connections .
OR
Open the Connections node in the Navigator pane, then right-click the WebDAV node
and choose New Connection.
2. Click Next.
3. Enter a display name for the new WebDAV connection.
4. Enter the URL of the WebDAV-enabled server you want to use. The URL of the server
should also include a port number, if one is required. If no port number is entered, a
default of 80 is used.
Note: If you do not enter a protocol prefix for the URL, a default of http:// will be
added automatically.
5. If authentication is required for this WebDAV connection, select the Authentication

Required checkbox, then click Next.
6. If you checked the Authentication Required checkbox, enter the Username and
Password for the WebDAV connection and enter your email address to be used as
identification when locking files in a WebDAV folder, then click Next.
Note: To save the password for the WebDAV connection, check the Remember
Password checkbox. These passwords are not encrypted when they is saved. If security
is an issue at your site, you might not want to use this option.
19-4
7. Click Test Connection to test the WebDAV connection is functioning correctly.
8. Click Next to display a summary of the WebDAV connection details.
9. Click Finish.
Related Topics
About WebDAV Connections
Deleting a WebDAV Connection
Accessing a WebDAV-Enabled Server Via a Proxy Server
19-5
Accessing a WebDAV-Enabled Server Via a Proxy
Server
If you access the internet via a proxy server you need to configure JDeveloper before
accessing WebDAV-enabled servers on the internet.
To access a WebDAV-enabled server via a proxy server:
1. Check with your network administrator to ensure that your proxy server is WebDAV-
enabled.
2. In JDeveloper choose Tools | Preferences, click Proxy Server in the left pane of the
Preferences dialog box, then deselect the 'Use proxy server' checkbox.
3. If the WebDAV-enabled server you want to access is inside your firewall and you do not
need to go through your proxy server to access it, add the name of the WebDAV server
to your default web browser's proxy exceptions list. This is normally set on the browser's
preferences/setting page with the other proxy settings.
For Netscape browsers:
1. Choose Edit | Preferences.

2. Choose Advanced | Proxies.
3. Choose View next to 'Manual proxy configuration'. The Manual Proxy
Configuration dialog box will appear.
4. In the Exceptions section there is a text field titled 'Do not use proxy servers for
domains beginning with:'. Add the WebDAV server or servers here.
For Internet Explorer browsers:
1. Choose Tools | Internet Options.
2. Click the Connections tab.
3. Click LAN Settings in the 'Local Area Network (LAN) settings' section.
19-6
4. Select Use a proxy server if not already selected.
5. Click Advanced in the 'Proxy server' section.
6. In the 'Exceptions' section there is a text field titled 'Do not user proxy server
for addresses beginning with:'. Add the WebDAV server or servers here.
19-7
Modifying a WebDAV Connection
WebDAV connections defined in JDeveloper can be edited after they have been created.
To edit a WebDAV connection:
1. Right-click the WebDAV connection you want to edit from those listed under the
Connections node in the Navigator pane.
2. Choose Edit.
3. Change the details of the WebDAV connection.
4. Click OK.
Related Topics
Refreshing a WebDAV Connection in JDeveloper
Deleting a WebDAV Connection in JDeveloper
19-8
Refreshing a WebDAV Connection
To ensure that the list of files and folders listed under the Connections | WebDAV node in the
Navigator pane accurately reflects the current contents of those WebDAV folders, you can
manually refresh the display of a WebDAV connection.
Note: Refreshing a WebDAV folder will automatically refresh all the files and folders beneath it on
the WebDAV connection.
To refresh the entire contents of a WebDAV connection:
1. Right-click the WebDAV connection you want to refresh from those listed in the
Navigator pane.
2. Choose Refresh.
To refresh a specific folder on a WebDAV connection:
1. Right-click the folder you want to refresh from those listed under the appropriate
WebDAV connection in the Navigator pane.
2. Choose Refresh.
Related Topics
Managing Files and Folders on a WebDAV Connection
19-9
Deleting a WebDAV Connection
Removing a WebDAV connection from JDeveloper does not affect any of the files or folders on
the WebDAV server itself.
To delete a WebDAV connection:
1. Right-click the WebDAV connection you want to delete from those listed under the
Connections | WebDAV node in the Navigator pane.
2. Choose Delete Connection.
Related Topics
Refreshing a WebDAV Connection
19-10
Managing Files and Folders on a WebDAV
Connection
Files can be uploaded to, and downloaded from, a WebDAV-enabled server using a WebDAV
connection in JDeveloper.
Files accessed using a WebDAV Connection can be built in the same way as files on the local
file system. If a file relies on others to build, it will have to be added to a project which can
provide the required build environment.
The following topics describe how to use files and folders stored on WebDAV Connections.
● Creating a New WebDAV Folder
● Uploading to a WebDAV Connection
● Downloading from a WebDAV Connection
● Using a Workspace Stored on a WebDAV Connection
● Using a Project Stored on a WebDAV Connection
● Using Files Stored on a WebDAV Connection
Related Topics
Using WebDAV Connections in JDeveloper
19-11
Creating a New WebDAV Folder
WebDAV folders can be created on WebDAV connections defined in JDeveloper.
To create a new WebDAV folder:
1. Right-click the WebDAV connection, or WebDAV folder under which you want to create a
new WebDAV folder.
2. Choose New Folder.
3. Enter the name for the new WebDAV folder.
4. Click OK.
Related Topics
Uploading to a WebDAV Connection
19-12
Files and folders can be uploaded to WebDAV connections defined in JDeveloper. Uploading
creates a copy of the files or folders in the WebDAV folder, leaving the original files and folders
on the file system.
To upload to a WebDAV connection:
1. Click the file or folder you want to upload, from those listed under the Workspaces node
in the Navigator pane, then choose File | WebDAV | Upload.
OR
Right-click the file in the Navigator pane that you want to upload to a WebDAV
Connection, then choose WebDAV | Upload.
Note: Selecting a project, package or other container for upload to a WebDAV

connection will also select all files and folders in that container. You can choose not to
upload specific files and folders by removing them from the candidate list in the Upload
to WebDAV Connection Wizard.
A list of candidate files is displayed. Files can be removed from the candidate list by
selecting them and clicking Remove, or re-added by selecting the removed file and
clicking Add.
2. Click Next.
3. Select the location on a WebDAV connection to which you want to upload the candidate
files.
4. If you want to overwrite existing versions of the files at the specified location on the
WebDAV connection, select the Overwrite existing file(s) and folder(s) checkbox.
5. Click Finish.
Related Topics
19-13
Downloading from a WebDAV Connection
19-14
Files and folders can be downloaded from a WebDAV connection to the local file system or
LAN. Downloading creates a copy of the files and folders on the local file system, leaving the
original files and folders on the WebDAV server.
To download a file or folder from a WebDAV connection:
1. Click the file or folder you want to download from those listed under the Connections |
WebDAV node in the Navigator pane, then choose File | WebDAV | Download.
OR
Right-click the file or folder that you want to download from those listed under the
Connections | WebDAV node in the Navigator pane, then choose Download.
Note: Selecting a WebDAV folder for download from a WebDAV connection will also
select all the files and folders it contains. You can choose not to download specific files
and folders by removing them from the candidate list in the Download to File System
Folder Wizard.
A list of candidate files is displayed. Files can be removed from the candidate list by
selecting them and clicking Remove, or re-added by selecting the removed file and
clicking Add.
2. Click Next.
3. Select the target file system directory to which you want to download the candidate files.
4. If you want to overwrite any files with same name in the target directory, select the
Overwrite existing file(s) and folder(s) checkbox.
5. Click Finish.
Related Topics
19-15
Using a Workspace on a WebDAV Connection
JDeveloper workspace files (.jws) stored on a WebDAV connection can be used in JDeveloper
by adding them to the Workspaces node in the Navigator pane.
To use a workspace on a WebDAV connection:
1. Right-click the workspace file that you want to add to JDeveloper from those listed under
the appropriate WebDAV connection in the Navigator pane.
2. Choose Add to Workspaces.
The workspace file on the WebDAV connection is now linked to the Workspaces node in
the Navigator pane, from where you can add projects and files to the workspace.
Any projects and files that exist in the workspace are displayed under the workspace in
the Navigator pane.
Note: Adding a workspace file from a WebDAV connection to the Workspaces node
does not copy the workspace (.jws) file to the local file system, but creates a link to the
workspace which can be used by JDeveloper to manage the projects in that workspace.
Related Topics
Using a Project Stored on a WebDAV Connection
Using a File Stored on a WebDAV Connection
19-16
JDeveloper project files (.jpr) stored on a WebDAV connection can be used in JDeveloper by
adding them to a workspace in the Navigator pane.
To link a project on a WebDAV connection to a workspace:
1. Select the workspace, under the Workspaces node in the Navigator pane, to which you
want to add a project from a WebDAV connection.
Note: This ensures that the current workspace is the one to which you intended to add
the project.
2. Right-click the project file that you want to add to the workspace from those listed under
the appropriate WebDAV connection in the Navigator pane.
3. Choose Add to Workspace.
Note: Adding a project file from a WebDAV connection to a workspace does not copy the
project (.jpr) file to appropriate workspace directory, but creates a link to the project
which can be used by the workspace to set and retrieve project properties and
information.
Related Topics
Using a Workspace Stored on a WebDAV Connection
Using a File Stored on a WebDAV Connection
19-17
Using Files Stored on a WebDAV Connection
Files, such as Java source files, stored on a WebDAV connection can be used in JDeveloper
by adding them to a project in the Navigator pane.
To link a file on a WebDAV connection to a project:
1. Select the project, under the Workspaces node of the Navigator pane, to which you want
to add a file from the WebDAV connection.
Note: This ensures that the current project is the one to which you intended to add the
file.
2. Right-click the file that you want to add to the project from those listed under the
appropriate WebDAV connection in the Navigator pane..
3. Choose Add to Project.
Note: Adding a file from a WebDAV connection to a project does not copy it to
appropriate project directory, but creates a link to the file so that it can be used by the
project.
Related Topics
Download from a WebDAV Connection
Using a Workspace Stored on a WebDAV Connection
19-18
Locking and Unlocking Files on a WebDAV
Connection
Files on WebDAV connections can be locked to prevent other users of that WebDAV server
from changing them.
The following topics describe how to lock and unlock files stored on WebDAV connections.
● Locking a File on a WebDAV Connection
● Unlocking a File on a WebDAV Connection
● Listing All Files Locked on a WebDAV Connection
19-19
Locking a File on a WebDAV Connection
Files can be locked on a WebDAV connection. Locking files on a WebDAV connection will
prevent anyone using another connection to that WebDAV server from changing that file.
To lock a file on a WebDAV connection:
1. Right-click the file you want to lock from those listed in the WebDAV connection's node in
the Navigator pane, then choose Lock.
OR
Select the file you want to lock from those listed in the WebDAV connection's node in the
Navigator pane, then choose File | WebDAV | Lock.
2. The file or folder is locked on the WebDAV server. The email address entered when the
WebDAV connection was created is used to identify who locked the file.
A list of the files that you are about to lock is displayed in the Lock Files dialog.
3. Click OK to lock the listed files.
Files that are now locked are display the locked icon in the Navigator pane.
Related Topics
Listing All Files Locked on a WebDAV Connection
Unlocking a File on a WebDAV Connection
19-20
Files that are locked on a WebDAV connection cannot be modified by any other WebDAV
connection.
To unlock a file from the Navigator pane:
● Right-click the locked file you want to unlock from those listed in the WebDAV
connection's node in the Navigator pane, then choose Unlock.
OR
● Select the locked file you want to unlock from those listed in the WebDAV connection's
node in the Navigator pane, then choose File | WebDAV | Unlock.
To unlock a file from the List Locks pane:
1. Select the file that you want to unlock, from those listed in the List Locks pane, then
choose File | WebDAV | Unlock.
A list of the files that you are about to unlock is displayed in the Unlock Files dialog.
2. Click OK to unlock the listed files.
Files that were previously locked that are now unlocked are display the unlocked icon
in the Navigator pane.
Related Topics
19-21
You can list all the files that are locked by you, or anyone else, on a WebDAV connection.
To list which files are locked on a WebDAV connection:
1. Select the WebDAV connection, for which you want to list locked files, from those listed
under the Connections node in the Navigator pane.
2. Choose File | WebDAV | List Locks.
3. Enter the URL at which you want to start searching for locked files on the WebDAV
connection.
4. Specify other options for listing locked files:
❍ Select List Only My Locked Files to only list files locked by you on the WebDAV
connection.
❍ Select Include Subfolders to search all folders beneath the URL specified in the
Search URL field.
5. Click OK.
The list of locked files is displayed in the List Locks pane.
Note: To refresh this list of locked files at any time, click the Refresh icon.
Related Topics
19-22
● Extending JDeveloper Using the Addin API
● A Sample Extension
❍ An Example of an Extension
❍ Understanding the Hello X Wizard
● Inside the JDeveloper IDE

❍ IDE Initialization
❍ IDE Structure
❍ IDE Behavior
❍ The Ide Class
● Creating a Wizard
❍ Setting Up a Wizard Project
❍ Implementing the Wizard Interface

❍ Adding a Wizard to the Gallery
❍ Adding a Wizard to the Tools Menu
● Defining a Document Type

❍ Implementing the Addin Interface
❍ Mapping URL Extensions to Node Classes

❍ About Documents in JDeveloper
❍ About URLs
❍ About Recognizers and Document Types
● Creating an Editor
❍ Implementing the EditorAddin Interface
❍ Defining an Editor
❍ Implementing a Controller
❍ About Data Objects in JDeveloper
❍ About Notifications
20-1
● Creating an Explorer
❍ Registering an Explorer
❍ Creating a Structure Explorer Element Model

❍ Updating the Structure Explorer
● Defining a Command
❍ Invoking an Addin from a Main Window Menu
❍ Invoking an Addin from a Context Menu

❍ Implementing a Command
❍ Defining an Action
❍ About IDE Action Processing
■ About Contexts
■ About Actions
■ About Commands
■ About Controllers
■ About Updating Ide Actions
■ About Handling Ide Actions
● About Other Extension Types

❍ About Views
❍ About UI Proxies
❍ About Property Editors
❍ About Java Code Generators
● Installing an Extension
● Debugging an Extension
20-2
Extensions are the means by which JDeveloper can be extended and customized to enhance
its capabilities. Oracle partners and other developers can use extensions to incorporate
additional tools into JDeveloper and add new functionality to their working environments.
Extensions are loaded into JDeveloper and integrated with IDE. Extensions are an essential
capability of JDeveloper: many standard JDeveloper features are extensions of the JDeveloper
kernel.
Extensions are classified according to the way they are installed. Most extension are addins,
which are installed when JDeveloper is launched. Installation of extensions of most of the other
types is deferred until they are needed.
These are the common extension types and functions:
● Wizards perform modal tasks, such as creating documents or other data objects from
user-supplied parameters.
● Custom nodes define new document types, and associate them with appropriate
explorers, editors, and compilers.
● Editors are views through which a particular type of document can be viewed and
modified. Designers are editors that are graphical, rather than text-based.
● Explorers display a hierarchical representation of a document or object, such as the
structure of classes and members in a Java file or the elements of an XML file. Explorers
are mainly used to aid navigation in views.
● Commands perform some atomic, non-modal task, such as an edit operation on a
document. Commands are invoked through menu items, toolbar icons, or keyboard
shortcuts.
● Dockable views are views that can either float independently or be docked to the IDE's
main window.
● Builders compile or translate source files of a specific language.
● Runners evaluate or execute programs.
This user's guide documents the JDeveloper Extensions API; the classes and interfaces of the
IDE that are used when integrating extensions.
Contents
20-3
● A Sample Extension
● Inside the JDeveloper IDE
● Creating a Wizard
● Defining a Document Type
● Creating an Editor
● Creating an Explorer
● Defining a Command
● About Other Extension Types
● Installing an Extension
● Debugging an Extension
Reference documentation
The Java classes and methods described in this user's guide are defined in the JDeveloper
Addin API.
Other documentation
Other documentation about the JDeveloper Addin API, sample applications, and updates to this
documentation, will be posted on JDeveloper's http://otn.oracle.com/products/jdev/content.html"
Oracle Technology Network (OTN) website.
20-4
A Sample Extension
Extensions are compiled Java components that are loaded and integrated with Developer after
it is launched, so that they can programmatically access the IDE. Use extensions to customize
the JDeveloper environment and augment its functionality.
The Addin API exposes the classes and methods of the IDE that are related to extensions.
Extensions can use these classes to, for example, access the IDE state, add controls to the
IDE, generate and intercept events, interact with the user, define new document types, and
install new views and compilers for various document types.
The Hello X sample extension is a wizard that creates a Java class from parameters provided
by the user. The following topics describe the Hello X Wizard, and will give you an introduction
to JDeveloper extensions:
● Running the Hello X Wizard

● Understanding the Hello X Wizard
Sample projects
The HelloX sample project is available at JDeveloper's Oracle Technology Network (OTN)
website at http://otn.oracle.com/products/jdev/content.html.
Related topics
Debugging an Extension
Installing an Extension
20-5
Running the Hello X Wizard
This sample project demonstrates a JDeveloper wizard that can be invoked to create a simple Java program.
One installed, this wizard can be invoked from either the Tools menu or the Samples page of the New gallery.
When invoked, the wizard opens a Hello X Wizard dialog, which requests a 'addressee' string. When a string,
such as "World" or "Larry", is entered, a simple one-class program is created from it. The provided string
becomes part of the class name and part of the text output by the program.
This sample consists of the following files:
Filename File contents

HelloX.java The implementation of the wizard.
HelloX.jpr The project that contains the source file.
HelloX.jsw The workspace that contains the project.
HelloX.gif The icon displayed in the Tools menu.
addins-user.properties A sample addins installation file.
ProjectInfo.html Instructions.
In these instructions "jdev" stands for your JDeveloper installation's root directory.
HelloX and other sample projects are available at JDeveloper's Oracle Technology Network (OTN) website at
http://otn.oracle.com/products/jdev/content.html.
Perform these steps to build and using the Hello X Wizard:
1. Building Hello X
2. Installing Hello X
3. Using Hello X
Building Hello X
Follow these steps to open and compile the project in JDeveloper:
1. In the JDeveloper directory navigate to samples/oracle/addin/hellox.

2. Open the workspace (.jws) file.
3. Expand it to see the project (.jpr) and source files.
4. Compile the source files. Right-click the project node and choose Build.
The log window should report that the project has compiled without errors or warnings. The class files
20-6
produced will be saved under JDeveloper's samples/classes directory.
Installing Hello X
Extensions must be installed in JDeveloper before they can be used. Follow these steps to install this wizard:
1. Add the example's files to JDeveloper's class path. Edit JDeveloper's bin/jdev.conf file to add the
line
AddJavaLibFile ../samples/classes
This entry will cause the Addin Manager to search the samples/classes folder for the project's
compiled classes.
2. Perform one or both of the following installations:

1. Install the example in the Tools menu. Copy the
jdev/samples/oracle/addin/hellox/addins-user.properties file to the
jdev/system directory. (If this file already exists, save the original and restore it when finished
with this example.)
2. Install the example in the New gallery. Copy these lines into jdev/lib/gallery.xml, just
preceding the last </list> tag:
<Item class="oracle.ide.gallery.GalleryFolder">
<list class="java.util.ArrayList">
<Item class="oracle.ide.gallery.GalleryElement">
<name>Class</name>
<wizardClass>samples.oracle.addin.hellox.HelloX</wizardClass>
<wizardParameters/>
</Item>
</list>
<name>Samples</name>
</Item>
Using Hello X
To use the wizard:
1. In the Navigator create a new workspace and a new empty project. Select the project node.
2. Invoke the wizard in either of the following ways, depending on how you installed it:
❍ From the Tools menu: choose Tools | Hello X, or
❍ Form the New gallery: choose File | New and then select Samples | Hello X.
3. The Hello X Wizard's dialog will open. Enter a name and click OK. A node will be created for the class in
the selected project, and the class will be opened for editing.
20-7
4. Right-click the node or the file, and choose Run. The program will compile and run, printing its output in
the log window.
Related topics
A Sample Extension
Understanding the Hello X Wizard
20-8
Understanding the Hello X Wizard
The Hello X sample extension is a wizard that creates a Java class that is customized by a user-
provided string. For example, when the string is "World" the following class is created:
public class HelloWorld

{
{
System.out.println("Hello, World!");
}
}
The Hello X sample is included in your JDeveloper installation, in

samples/oracle/addin/hellox.
The Hello X wizard consists of one Java class, HelloX, which implements the Wizard and
Addin interfaces. As an addin, HelloX can be loaded when JDeveloper is launched and be
invoked from a menu. As a wizard, HelloX can be loaded and invoked when and if it is needed,
from the New Gallery.
● Loading HelloX as a Wizard

● Loading HelloX as an Addin
● Invoking HelloX
● Generating the Java Class
Loading HelloX as a Wizard
A characteristic of wizards is that they are not loaded until they are needed. A wizard invoked
through the gallery is loaded when its gallery page is opened.
The structure of the gallery is described by a JDeveloper file, lib/gallery.xml. To install

Hello X as a gallery object, add an entry for it to the gallery file:
<name>Hello X</name>
<wizardClass>samples.oracle.extensions.hellox.HelloX</wizardClass>
20-9
<wizardParameters/>
</Item>
This entry gives the name that will appear in the gallery, and names the class that implements
the Wizard interface. When the gallery is opened the Gallery Manager parses the gallery
description, and when a gallery element is to be displayed, the manager attempts to load it. If
the class exists, and implements Wizard, the manager will load the class and call its default
constructor to create and initialize an instance. The instance will persist until JDeveloper is
exited, handling all invocation requests.
Loading HelloX as an Addin
Addins are loaded when JDeveloper is launched. Any extension that is invoked from the menu
or toolbar must be installed as an addin — otherwise, the addin's menu item or icon will not
appear.
User-installed addins are loaded if they are named in system/addins-user.properties, in

an entry such as:
Addin0=samples.oracle.addin.hellox.HelloX
This entry names the class implements the Addin interface, and specifies its place (first, in this
example) in the sequence in which addins are loaded. When JDeveloper is launched addins-
user.properties is read, and all the named addins are loaded, instantiated, and initialized.
The instances will persist until JDeveloper is exited.
Invoking the Wizard
When the wizard's gallery page or menu is opened, before the wizard is actually selected, the
Wizard Manager will call the wizard's getIcon method to obtain its graphic and call
isAvailable to determine if the icon and name should be displayed as selectable, or not. In
Hello X's case, the generated class file must be added to an existing project, so the current
context — the currently selected object — must be a project node:
"frags/hellox_isavailable.frag">[hellox_isavailable.frag]
When the user selects the wizard's item the Wizard Manager calls its invoke method. As a
typical wizard, Hello X opens a modal dialog to obtain user input — the string greetee — and
passes it to the method that will create the class and its node.
20-10
"frags/hellox_invoke.frag">[hellox_invoke.frag]
Generating the Java Class
Hello X is a code generation wizard: it creates a file, content for the file, and a node to represent
the file in JDeveloper.
To construct the node a URL is created from the class name, which is a concatenation of
"World" and the greetee parameter supplied by the user, and the project's URL: the class file
will be created in the project's directory.
"frags/hellox_createnode.frag">[hellox_createnode.frag]
The content of the class file is Java code, which is created using JOT (Java Object Tool). JOT
classes represent Java's syntactic elements, such as classes, methods, parameters, and
expressions.
"frags/hellox_createcontent.frag">[hellox_createcontent.frag]
Sample projects
The code examples cited here are taken from the HelloX sample project. It and other extension
examples are available at JDeveloper's http://otn.oracle.com/products/jdev/content.html">Oracle
Related topics
A Sample Extension
Running the Hello X Wizard
20-11
Inside the JDeveloper IDE
JDeveloper's IDE (integrated development environment) are accessed through the static
methods of the Ide Class. Extensions to JDeveloper are integrated by accessing data objects
and services through these components, which are exposed in the Addin API.
These topics describe aspects of the IDE object:
● IDE Structure
● IDE Initialization
● IDE Behavior
● The Ide Class Definition
Related topics
20-12
IDE Initialization
When JDeveloper is launched its components are initialized through the extension mechanism,
which loads addins and integrates their functionality.
Three sets of addins are installed when JDeveloper is launched:
● Core Features — addins that initialize IDE components, and in doing so define the
general functionality of JDeveloper. Core features provide the basic user interface and
the managers with which the other features are registered. Core feature addins are
loaded from the list in bin/addins-core.properties.
● Standard Features — addins defining the specific functionality of JDeveloper. Standard
features define the file types, editors, translators, and other functionality required for
developing database applications in Java. Standard feature addins are loaded from the
list in bin/addins.properties.
● User Features — addins that augment and customize JDeveloper. User feature addins
are loaded from the list in system/addins-user.properties.
Other extension types, such as wizards, are not installed until needed. JDeveloper can also be
augmented and customized by user features installed by these extension types.
Related topics

IDE Structure
IDE Behavior
The Ide Class Definition
20-13
IDE Structure
The IDE object provides access to JDeveloper's major components. These are:
● Extension Managers
● Core Features
● Execution Components
● Action Processing
● IDE State
Extension Managers
Extension classes are accessible through extension managers.
These extension managers are components of the IDE:
● Addin Manager — the manager for extensions loaded at startup.

● Wizard Manager — the manager for invokable extensions.
Core Features
The core features of IDE are bundled as the Feature Manager, and are installed as a unit by
the first extension loaded.
JDeveloper's core features are:
● Main Window — the content area and the frame that surrounds it. The frame displays the
fixed UI components: the Tool Bar and Menu Bar at the top and Status Bar at the bottom.
Views — which are managed by the other core features — float in the content area, or
are docked to the frame.
● Editor Manager — the manager for document views. Editors are registered with the
Editor Manager to associate them with specific document types.
● Explorer Manager — the manager for structure explorers. Explorers are registered with
Explorer Manager to associate them with specific document types.
● Navigator Manager — the manager for the system navigator and transient navigators
20-14
opened on nodes.
● Inspector Manager — the manager for property inspector views.
● Palette Manager — the manager for palette views.
● Log Manager — the manager for log pages.
● Dock Station — the manager for the content area. Dockable factories, which are
extensions that create new dockable views, must be registered with the Dock Station.
Implement a dockable factory if you wish to augment the IDE with a new feature.
● Layouts — the manager for user-created layouts of the Main Window content area.
● Print Manager — the printing interface.
Execution Components
The IDE contains these components related to application execution:
● Compiler — the build system. This component controls compilation, but the nature of the
compilation depends on the implementation of the compile method in document
classes.
● Runner — manages running applications. This component is the registry for starter
factories, which produce starters for processes. Runner addin extensions install starter
factories. The standard starter factories are Runner, Debug, Profile, and CodeCoach.
Action Processing
The IDE is ultimately responsible for handling user-generated actions. These components of
the IDE are involved in that process:
● Root Controllers — the controllers that define default behavior for actions. Subordinate
controllers handle specific actions and defer others to their supervisor. The IDE itself is
the root controller for all actions defined in the default items in the Menu Bar and Tool
Bar. Additional root controllers can be provided for custom actions.
● The Command Processor — the component that executes commands, and manages
data-objects undo stacks. Controllers react to actions by create commands, which are
passed to the Command Processor.
IDE State
20-15
The IDE is the repository for various parameters, such as:
● IDE Properties — the state of the user interface. These properties are written to and read
from system files, so that they can persist from session to session.
● IDE Preferences — the user settings accessed through the Tools menu. Preferences
define the defaults that are used for various operations.
Related topics

IDE Initialization
IDE Behavior
20-16
IDE Behavior
The function of the IDE is to present a document to the user so that it can be viewed, edited,
and perhaps executed. In general this capability involves three interacting components:
● A data object that represents the document.

● A view that displays the state of the data object.
● A controller associated with the view that translates user-interface actions into
commands that act on the data object.
The JDeveloper IDE is extensible — all of these capabilities can augmented by extensions. For
example:
● A custom node is an extension that registers a class as the representation of a new

document type, so that documents of that type can be represented by data objects, and
be associated with navigator nodes, viewers, editors, and other services.
● A gallery wizard is an extension that creates a data object of a particular type, according
to user-supplied parameters.
● An explorer is an extension that displays a schematic view — usually a tree — of the
content of documents of a given type. Explorers are associated with editors, and act as
navigation aids for them.
● An editor is an extension consisting of a view and a controller. The view displays the
content of a data object, and the controller handles editing operations and other events.
An editor may be associated with one document type or many. Conversely, a document
type may be viewable through more that one editor.
● A tool is an extension that defines a new functionality that may be applied to objects of
one or more types, and installs it in the menu bar or toolbar.
Related topics

IDE Initialization
IDE Structure
20-17
The Ide Class
The JDeveloper IDE is represented by the singleton instance of the Ide class. The IDE class
has methods that provide the following capabilities:
● Accessing The IDE's Subcomponents

● Accessing Data Objects
● Handling Actions
● Reacting to Events
● Accessing Environment Information
● Adapting the IDE for Other Products
Accessing IDE Subcomponents
The Ide instance is the backbone of JDeveloper: the objects that represent the essential parts
of JDeveloper are components of the Ide instance.
The IDE Instance
This method returns the Ide instance:
getInstance
The Main Window
This method returns the Main Window, which represents the IDE's graphical display:
getMainWindow
Some of the Main Window's components can be obtained directly from the Ide, by calling these
methods:
getMenubar
getToolbar
20-18
getStatusBar
getLogWindow
IDE Feature Managers
Managers oversee the behavior of extendable components. New features are integrated into
JDeveloper by registering them with appropriate managers, which make the new features
available to the user. For example, an editor is registered with the Editor Manager, which adds
it to the View | Display With menu, and then enables it when a node of an compatible type is
selected.
JDeveloper's essential set of managers are collected together in the Feature Manager, which is
returned by this method:
getFeatures
Most of these features can be obtained directly from the Ide, by calling these methods:
getEditorManager
getPaletteManager
getExplorerManager
getInspectorManager
getNavigatorManager
getLogManager
getPrintManager
getDockStation
Extension Managers
These methods return the managers responsible for loading and integrating extensions:
getWizardManager
getAddinManager
Execution Components
20-19
These methods return the components that oversee the compilation and invocation of Java
applications within JDeveloper:
getCompiler
getRunner
Wait Cursor
If an action will cause a noticeable delay the Wait Cursor should be activated to alert the user.
Use this method to obtain the Wait Cursor.
getWaitCursor
Help System
This method accesses the component that manages context-sensitive help.
getHelpSystem
Accessing Data Objects
Documents and other data objects are presented to the user primarily by nodes in the System
Navigator. Data objects can be accessed programmatically through the IDE.
The System Navigator
The trees in the System Navigator are accessible from the Ide. Nodes representing documents
can be obtained by traversing these trees. The IdeSystem instance, representing the true root
node ( which is not displayed) can be obtained by calling this methods:
getSystem
These methods return children of the IdeSystem instance, which appear in the System
Navigator as the apparent root nodes:
getWorkspaces
20-20
getMiscellaneousFolder
Workspaces and Projects
These methods the current context's workspace and project nodes to be set an retrieved
programmatically:
getActiveWorkspace
setActiveWorkspace
getActiveProject
setActiveProject
getDefaultProject
getDefaultWorkspace
activateProjectInWorkspace
Miscellaneous Folder
Documents that are opened outside the context of the active project are added to the
Miscellaneous Folder, a top-level node in the System Navigator. Use this method to
programmatically add objects to the folder:
addToMiscellaneousFolder
Handling Actions
Actions, which are triggered by the user through the user interface, are handled by controllers,
which are associated with views. The IDE is the controller associated with the Main Window,
and is ultimately responsible for all handling all actions.
Command Processing
This method returns the Command Processor, which is used by controllers to execute
commands:
getCmdProcessor
20-21
The following methods are used to obtain commands that are already defined, or to define new
ones:
newCmd
newSysCmd
cmdName
getCmdID
Root Controllers
Root controllers are ultimately responsible for interpreting commands. The IDE is itself a root
controller; controllers that are not subordinate to it should be designated as root controllers.
These methods manage the set of root controllers:
getRootControllers
addRootController
removeRootController
Context-Sensitive Actions
Most newly-defined actions are associated with views and their controllers. Those that are not
must be registered with the IDE by calling this method:
addContextSensitiveAction
Controller Methods
The IDE is the original root controller, and thus implements Controller, which requires these
methods:
supervisor
update
handleEvent
checkCommands
20-22
Reacting to Events
The IDE reports its high-level events to the standard components and extensions that need to
react to them.
View Events
The IDE is a listener for events involving its subwindows, and thus implements
ActiveViewListener and ViewSelectionListener, which require these methods:
activeViewChanged
viewSelectionChanged
IDE Events
Components that need to react to IDE events should be registered as IDE listeners. These
methods manage the listener registry:
addIdeListener
removeIdeListener
JDeveloper Status
This method returns the status of the current JDeveloper session:
isQuitting
Accessing Environment Information
The parameters that govern the appearance and behavior of the IDE are recorded in various
files in the bin and system directories, which are read when JDeveloper starts. These
parameters are accessible programmatically.
IDE Properties
The parameters that define the IDE's state are contained in the system/ide.properties
file. This file is read when JDeveloper starts, and then written when JDeveloper shuts down
20-23
normally. Use these methods to obtain property values, and set them programmatically:
getIdeProperties
getProperty
setProperty
getIdePropertiesFilename
IDE Preferences
The IDE settings that are accessible to the user through the Tools | Preferences menu item are
read originally from the system/settings.xml file. Use this method to obtain the root of the
Preferences tree:
getSettings
This method is an alternate accessor to one of the children of the Preferences tree:
getEnvironOptions
Layouts
The definitions of layouts are accessible to the user on the Layouts page of the IDE
Preferences, and in files in the system directory having the .layout extension. Use these
methods to access and set layouts programmatically:
getLayouts
getActiveLayout
JDeveloper's Directories
These methods return the pathnames of some of JDeveloper's directories.
getBinDirectory
getHomeDirectory
getLibDirectory
20-24
getUserHomeDirectory
getSystemDirectory
getWorkDirectory
JDeveloper's Version Information
These methods return information that describe the current version of JDeveloper:
getProgramName
getVersion
getVersionInfo
Adapting the IDE for Other Products
These methods are needed only by extensions that radically modify JDeveloper's 'look and
feel', or adapt the IDE to support products other than JDeveloper:
Look and Feel
These methods access the objects that define the IDE's appearance and behavior:
getIdeUIManager
getKeyStrokeContextRegistry
getIdeInputMap
getIdeActionMap
getMacros
Essential Features
These methods attach product-specific features to the IDE:
setFeatures
setRunner
setCompiler
20-25
setHelpSystem
History Lists
The IDE maintains a list of files that have been opened. Call this method to obtain it
programmatically:
getFileOpenHistory
Use this method to create custom history lists:
loadHistoryList
IDE Operation
These methods control the startup and shutdown of the IDE:
startup
quit
preTerminate
terminate
Related topics

IDE Initialization
IDE Structure
IDE Behavior
20-26
Creating a Wizard
A wizard is an extension that is invoked to perform some task. A typical wizard is invoked
through the UI to open a user interface consisting of one or a sequence of dialog boxes, in
which the user specifies task parameters. A typical task is the creation of a document or other
data object. Specialized invocation mechanisms are provided for wizards that are installed in
the gallery or the Tools menu. In these cases the Wizard Manager manages the invocation
details.
A wizard project usually has three main components:
● A wizard class. This class deals will the wizard's appearance in the user interface, and
with its invocation. This class may implement Wizard directly, but JDeveloper's wizards
are extensions of BaliWizard. Extend BaliWizard if your wizard is to have JDeveloper's
look and feel. A wizard that is to be invoked from the Tools menu must also implement
Addin. BaliWizard implements both Wizard and Addin.
● A modal dialog. The dialog interacts with the user to collect data required for the function
of the wizard. If your wizard is a BaliWizard, implement BaliWizardPanel. Otherwise, use
Swing components to create the dialog.
● A data object. The wizard applies the data collected by the dialog to create or modify a
data object. If your wizard is a BaliWizard, implement BaliWizardState to represent the
data object. If the data object is a Java class or interface, use the classes and methods
of the Java Object Tool (JOT) to parse and assemble Java code.
HelloX is a sample wizard that creates a simple Java class. HelloX implements Wizard
directly, and uses a javax.swing.JDialog as its user interface.
The following topics describe aspects of creating a new BaliWizard:
● Setting up a Wizard Project

● Implementing the Wizard Interface
● Adding a Wizard to the Gallery
● Adding a Wizard to the Tools Menu
Sample projects
20-27
HelloX and other sample extension projects are available at JDeveloper's Oracle Technology
Network (OTN) website at http://otn.oracle.com/products/jdev/content.html.
Related topics
20-28
Setting Up a Wizard Project
To create and initialize a JDeveloper wizard project:

2. In the project create a Java class; a class that either extends
oracle.jdeveloper.wizard.common.BaliWizard, or directly implements
oracle.Ide.addin.Wizard and oracle.Ide.addin.Addin. The class should be
public and have a default constructor, but not a main method.
3. In the Project Settings for Libraries select these libraries:
JDeveloper Addin API

Oracle JEWT
4. In the Project Settings for Runner:

1. Set Default Run Target to name the Java class created above.
2. Set the Run Directory to jdev/myhome or some other directory that will serve as
your user home for debugging.
Related topics
Creating a Wizard
20-29
Implementing the Wizard Interface
Extensions that are to be invoked from the user interface to perform some modal task should
implement the Wizard interface. This interface provides for the extension's installation, and
integrates it with JDeveloper's user interface.
The Wizard interface can be implemented directly, or indirectly by extending the BaliWizard
abstract class.
To Implement the Wizard interface:
● Define the constructor

● Define the invoke method
● Define the getMenuSpecification method
● Define the isAvailable method
● Define the getIcon method
● Define the getName method
● Define the toString method
Defining the constructor
A wizard's constructor is invoked only once, when the wizard is loaded. The constructor should
be lightweight, meaning that it should not create and hold object references. Defer such
operations to the initialize method.
Defining the invoke method
This method embodies the wizard's functionality. Wizards generally open a dialog to obtain
parameters from the user, and then use those parameters to create or modify a document or
other data object.
A wizard that extends BaliWizard need not implement this method, but must define the
buildPanel and buildState methods.
This method is called when the wizard's UI element is selected by the user through the gallery
or Tools menu. The context parameter identifies the currently selected objects that the wizard
20-30
might affect. The params parameter is empty when the wizard is called from Tools menu, and
contains the value set of the wizard's wizardParameters tag from the gallery.xml file.
"frags/hellox_invoke.frag">[hellox_invoke.frag]
Defining the getMenuSpecification method
This method is called to determine the appearance of the wizard's item in the Tools menu,
when it is to be displayed. If the wizard is not installed in the Tools menu this method should
return null.
"frags/hellox_getMenuSpecification.frag">[hellox_getMenuSpecification.frag]
Defining the isAvailable method
This method is called to determine if the wizard's gallery icon or Tools menu item should be
enabled or disabled, given the current context. For example, a wizard that operates on project
nodes must only be enabled only when the current node is a project node.
"frags/hellox_isAvailable.frag">[hellox_isAvailable.frag]
Defining the getIcon method
This method is called to obtain the wizard's gallery icon. If the wizard is does not require an
icon this method should return null.
"frags/hellox_getIcon.frag">[hellox_getIcon.frag]
Defining the getName method
This method provides a human-readable name for the Wizard. The content of the string is left
to the programmer's discretion.
Defining the toString method
This method provides a human-readable description of the Wizard. The content of the string is
left to the programmer's description, but is often the same as the value of getName.
20-31
Sample projects
The code examples cited here are taken from the HelloX sample project. It and other extension
examples are available at JDeveloper's http://otn.oracle.com/products/jdev/content.html" Oracle
Related topics
Creating a Wizard
20-32
Adding a Wizard to the Gallery
Wizards can be installed in the gallery by listing them in JDeveloper's lib/gallery.xml file.
All of the details of wizard registration and event processing are handled by the Wizard
Manager.
If the wizard is to be invoked only from the gallery the constructor for the wizard class is not
called until the user first opens its gallery page. The constructor for the wizard class may be
empty.
The gallery's manager reads gallery.xml when the gallery is first opened, and constructs
the gallery's pages and items from it.
To add a wizard to the gallery:
● Add the wizard to JDeveloper's class path

● List the wizard in the configuration file
Related topics
Creating a Wizard
20-33
Adding a Wizard to the Tools Menu
The Wizard Manager provides special support for wizards that are installed in the Tools menu.
The Wizard Manager takes care of the details of adding the menu item and handling the user's
selection of it.
Wizards can also be installed elsewhere in the user interface, such as other menu, context
menus, or the tool bar, but in these cases a command must be defined, and installed and
handled explicitly.
To install a wizard in the Tools menu, modify the class that implements Wizard to implement
Addin, as well, so that it can be loaded when JDeveloper is launched.
The wizard must also be registered with the Wizard Manager. This should be performed in the
initialize method, which is part of the Addin specification:
"frags/hellox_intialize.frag">[hellox_initialize.frag]
Define the wizard's getMenuSpecification method to return a valid MenuSpec object. (This
method may return null if the wizard is invoked only from the gallery.) For example:
"frags/hellox_getMenuSpecification.frag">[hellox_getMenuSpecification.frag]
Install the extension by editing configuration files.
Sample projects
The code examples cited here are taken from the HelloX sample project. It and other
extension examples are available at JDeveloper's
http://otn.oracle.com/products/jdev/content.html" Oracle Technology Network (OTN) website.
Related topics
Creating a Wizard
Implementing the Addin Interface
Implementing the Wizard Interface
20-34
20-35
Defining a Document Type
A recognizer addin is an extension used by the Node Factory to recognize document types and
create instances of them. When a document is opened in the IDE, its type determines the icon
that will represent it in the Navigator pane, the viewers that are available to it in its context
menu and the View menu, the parser that will render it for browsing in the Structure pane, and
so on.
JDeveloper provides recognizers for workspace, project, Java, HTML, XML, and other basic
document types. If you wish to extend JDeveloper to work with other document types, you can
map an extension type to a node class in the URLRecognizer, or you can create and register
your own recognizer.
The following topics describe aspects of recognizer addins:
● Implementing the Addin Interface

● Mapping URL Extensions to Node Classes
● About Documents in JDeveloper
● About URLs
● About Recognizers and Document Types
Related topics
Creating an Editor
Creating an Explorer
20-36
Most extensions should implement the Addin interface. This interface provides for the
extensions installation at the time of JDeveloper's startup.
To implement the Addin interface:

● Define the initialize method
● Define the canShutdown and shutdown methods
● Define the version and ideVersion methods
This method is called by the Addin Manager during JDeveloper's startup, provided that the
addin class is registered in the bin/addins-user.properties file.
Defer initialization tasks to the intialize method.
Defining the initialize method
This method is called by the Addin Manager after the instance has been created. The tasks that
should be performed at initialization are:
● creation of UI elements and controllers

● registration with managers
Other tasks, such as the creation of data structures that will not be needed until and if the addin
is invoked, should be deferred, so that JDeveloper's startup is not unnecessarily delayed.
Defining the canShutdown and shutdown methods
When JDeveloper shuts down the Addin Manager calls these methods for each addin.
The canShutdown method is called first to allow the addin to alert the user that it has some
unfinished business, such a running process or unsaved data. Use this method to give the user
20-37
an opportunity to cancel the shutdown process, and return the user's choice to the Addin
Manager.
If all of the addin's canShutdown methods return true, the Addin Manager then calls their
shutdown methods. Use it to release any non-java resources acquired by this addin, such as
file handles and database connections.
Defining the ideVersion and version methods
Define the version method, if desired, to provide a version number for the addin. JDeveloper
ignores this method.
Define the ideVersion method to return the version number of the JDeveloper IDE release
for which the addin was implemented. The Addin Manager calls this method during startup and
uses the returned value to discover and reject incompatible addins. Addins implemented for
Oracle 9i JDeveloper should return 5.0.
Related topics

Invoking an Addin from a Main Window Menu
Invoking an Addin from a Context Menu
20-38
Mapping URL Extensions to Node Classes
Node classes represent document types that are distinguished by their file extensions. These
node classes must be registered with the URLRecognizer. The essential registration task is the
association of the document name with the node class.
Registration operations, which associate a file extension with an implementation of the Node
interface, should be performed in the addin class' initialize method.
"frags/recognizeraddin_initialize.frag">recognizeraddin_initialize.frag
Sample projects
The code example cited here is taken from the PropFile sample project. It and other extension
Related topics
Implementing a Recognizer Addin
20-39
About Documents in JDeveloper
When a document, or other resource accessed through a URL, is opened in the IDE, its type
determines the label, icon, and tooltip, that will represent it in its navigator pane, the viewers
that are available to it in its context menu, the parser that will render it for browsing in the
Structure pane, and other services. A document's type is usually distinguished by the extension
part of its URL, or by the root element in some XML files.
A document in JDeveloper is ususlly presented to the user in three ways:
● As a node in a navigator pane. Each document type is represented by its own node
class. A document type is known to JDeveloper if the mapping from the document type to
the node class is registered with a recognizer. An opened document is represented by an
instance of the class. The document type determines the services, such as viewers and
compilers, that are available in the node's context menu, or are enabled elsewhere in the
IDE when the node is selected.
● As editable content in a view. A node's context menu shows a list of the designer and
editor views — that can be used to see or modify the document's content. A view
appears on this list if it is registered for the node's type with the IDE's editor manager or
designer manager. A document type can be viewable through many views, and a view
may be registered for many document types.
● As an explorer tree in a structure pane. An explorer tree displays the skeletal structure of
the document's content, and can be used to navigate in he associated view. When the
user selects a view for a document, an explorer is found that is compatible with both the
document type and the viewer, if such a viewer has been registered with the explorer
manager. The document is then parsed to construct the tree.
JDeveloper provides node classes, views, explorers and other services for many common
types. If custom document types, or alternative views or explorers for known types are needed,
they can be incorporated as extensions:
Related topics

Creating an Editor
About Data Objects in JDeveloper
20-40
20-41
About URLs
URLs (Uniform Resource Locators) are represented in JDeveloper by instances of the
Java.net.URL class. However, JDeveloper supplies custom protocol handlers to support
requirements of the IDE: to insure that URLs will work correctly in JDeveloper, use URLFactory
methods to create all URLs.
Other protocols can be incorporated as extensions. Operations on file systems are provided by
the static methods of the URLFileSystem class. For the predefined protocols this class
delegates to the URLFileSystemHelper class. To add a custom protocol, extend the
URLFileSystemHelper class to define the behavior of the protocol's file system, and register
this new class with URLFileSystem.
Related topics
20-42
About Recognizers and Document Types
Document instances are created whenever a file is opened or created in JDeveloper. The
particular class of document object created depends on the type of the file. The Node Factory
can be extended by adding custom recognizers.
When a file is opened or created, the IDE passes the URL to the Node Factory. The Node
Factory delegates node creation to its recognizers, which are instances of Recognizer. The
Node Factory has a list of registered recognizers: the first recognizer in the list that recognizes
the URL creates a node for it. JDeveloper has two predefined recognizers:
● The URL recognizer (the singleton instance of URLRecognizer) maps file extensions to
node classes. Extensions can cause JDeveloper to recognize custom file types by
defining a Node class for for that file type, and registering the file type and node class
with the URL recognizer. Whenever a URL having that extension is passed to the
NodeFactory findOrCreate static method, an instance of the custom node class will
be returned.
● The XML recognizer (the singleton instance of XMLRecognizer) also maps file
extensions to node classes, but in addition allows root elements to be mapped to node
classes. Extensions can register custom node classes using either mapping. The XML
recognizer will first check if the file extension is known, and if it is not, will read enough of
the file to find the root element. If either the file extension or root element are recognized
a instance of an appropriate node class will be returned.
The Node Factory caches all nodes it creates. The findOrCreate static method returns a
second reference to an existing node, if a node for the given URL already exists, and creates a
new node if not.
The Node Factory's functionality is provided by static methods of the NodeFactory class.
Related topics
20-43
Creating an Editor
An editor is a view that displays an object for the user to modify. Editors usually display text; a
designer is a non-textual editor.
Editors are opened for a document through its node's context menu or the View | Display With
submenu. The editors available for a document are those registered for the document's type
with the IDE's Editor Manager. Editors are usually used in conjunction with structure explorers,
but this is not required.
The following topics describe aspects of creating an editor extension:
● Implementing the EditorAddin Interface

● Defining an Editor Class
● Implementing a Controller Class
● About Data Objects in JDeveloper
● About Notifications
Related topics
20-44
Implementing the EditorAddin Interface
Editor extensions should implement the EditorAddin interface. This interface integrates the
extension with the Editor Manager, and provides for the extensions installation at the time of
JDeveloper's startup.
To implement the EditorAddin interface:

● Define the initialize method
● Define the getEditorClass method
● Define the isDefault method
● Define the getMenuSpecification method
● Define the other methods require by the Addin interface.
This method is called by the Addin Manager during JDeveloper's startup, provided that the
addin class is registered in the bin/addins-user.properties file.
Defer initialization tasks to the initialize method.
Defining the initialize method
This method is called by the Addin Manager after the instance has been created. Register the
editor with the Editor Manager here.
Editors must be registered with the IDE's EditorManager. A registration associates an editor
with one or more node classes. When the user attempts to open an editor for a node, through
either its context menu or the View | Display With menu, only editors that are registered for that
node's class are enabled:
"frags/editoraddin_initialize.frag">editoraddin_initialize.frag
Defining the getEditorClass method
20-45
This method names the class, an implementation of Editor, that acts as the editable view.
"frags/editoraddin_getEditorClass.frag">editoraddin_getEditorClass.frag
Defining the isDefault method
A node class can have a default editor; when the user double-clicks on the node it is opened in
the default editor. To declare an editor to be the default for it's registered node types,
implement this method to return true:
"frags/editoraddin_isDefault.frag">editoraddin_isDefault.frag
If more that one editor is declared to be the default for a given node type, the addin loaded last
overrides the others. User addins (those listed in system\addins-user.properties) are
loaded after JDeveloper addins (listed in bin\addins.properties), and in each file addins
are loaded by number in ascending order.
Defining the getMenuSpecification method
The Editor Manager adds the menu specification for the editor addin to two menus:
● The Display With submenu of the View menubar menu. This menu display all editors, but
only those applicable in the current context are enabled.
● The context menu for nodes lists the editors that are applicable to that node, if any.
The menu specification describes the appearance of the editors menu item. For example:
"frags/editoraddin_getMenuSpecification.frag">editoraddin_getMenuSpecification.frag
Sample projects
Related topics
20-46
Defining an Editor Class
Implementing a Controller Class
20-47
Defining an Editor Class
An editor is a view that displays an object for the user to modify.
An editor class implements the Editor interface, and may do so by extending AbstractEditor.
The editor class is instantiated whenever a node of a type registered for the editor is opened for
viewing.
An editor is associated with these other components:
● The Editor Manager, a component of the IDE, which selects an editor class and
instantiates it when the user opens a node.
● An EditorAddin serves as the go-between the editor and the Editor Manager. When
JDeveloper starts the addin registers the editor class.
● An object representing the data being edited, usually an implementation of Document.
● An editor component, an implementation of javax.swing.JEditorPane, which
performs the actual modification of the data.
● A Controller that interprets user interface editing commands and invokes editor
component methods.
● An Explorer that displays the structure of the data object. The explorer responds to user
actions by calling editor methods.
An editor class must:
● Create instances
● Initialize instances
● Access the Controller
● Respond to explorer events
● Respond to editor component events
● Generate update messages
Instantiating the editor
The Editor Manager instantiates an editor class when the user opens a node in the Navigator.
20-48
The Editor Manager calls the default constructor, so no context-specific parameters are
available to it:
"frags/editor_constructor.frag">editor_constructor.frag
Initializing the editor
The Editor Manager initializes a editor instance by calling its setContext method. This
method should extract the document to be edited from the context, and initialize the editor
component.
"frags/editor_setContext.frag">editor_setContext.frag
Accessing the Controller
The editor has an associated controller instance that intercepts and interprets user events. The
IDE calls the editor's getController method to acquire the controller, which should create
the controller when first called:
"frags/editor_getController.frag">editor_getController.frag
Responding to explorer events
An explorer view of a data object provides a means of navigating in a document in an editor:

when the user selects an element in the explorer, the explorer instructs the editor to display the
corresponding part of the data.
If the editor is intended to be integrated with an explorer is must provide one or more 'goto'
methods. (This capability is not required by the Editor interface.) This example is a methods
that causes the editor's cursor to move to a specified line of a text file:
"frags/editor_setCaretPosition.frag">editor_setCaretPosition.frag
Responding to editor component events
The editor component, as an implementation of JEditorPane, generates action events when

its data changes. The editor should implement an interface such as java.awt.KeyListener, and
during initialization should call the editor component's addKeyListener method to register
itself to receive the events. This example of the KeyListener method keyTtypes triggers a
20-49
method that will alert other IDE objects, such as the recognizer, of the change.
"frags/editor_keyTyped.frag">editor_keyTyped.frag
Generating update messages
When the data object's state changes other IDE components — such as the document's
explorer — must be informed. This is accomplished through the notification mechanism. The
editor creates an UpdateMessage instance and broadcasts it to the document's observers:
"frags/editor_keyTyped.frag">editor_keyTyped.frag
Sample projects
The code examples cited here are taken from the PropFile sample project. It and other
Related topics
Creating an Editor
Implementing the EditorAddin Interface
Implementing a Controller Class
About Notifications
20-50
Implementing a Controller
If your extension implements a view class it should also implement a controller class to handle
the view's events. You can implement the controller by extending BaseController, or by directly
implementing the Controller interface.
To implement a controller class provide definitions for the following members:
● Defining the Constructor

● Defining the supervisor Method
● Defining the handleEvent Method
● Defining the checkCommands Method
● Defining the update Method
● Define Command Constants
Defining the Constructor
Define either a unary or a nullary constructor:
● Define a unary constructor if the controller class can have multiple instances. This is the
case for controllers for editors.
"frags/editorcontroller_constructor.frag">[editorcontroller_constructor.frag]
Generally a view will create its controller. When the view class allows multiple
instances the controller's constructor should take the calling view instance as its
argument.
● Define a nullary constructor in some cases when the controller and view are singleton
instances.
"frags/controller_nullary_constructor.frag">[controller_nullary_constructor.frag]
Some extensions, such as the component palette, have a single instance that may
or may not be used in a JDeveloper session. In such a case the creation of the
20-51
view can be delayed until the user request it. It is then created by its controller,
through a menu item or toolbar icon installed for this purpose. This constructor
should throw an exception if an attempt is made to create an additional instance.
Defining the supervisor Method
Implement supervisor to return a controller that will handle events your extension chooses
as a default. The BaseController definition, which is adequate for most extensions, returns the
Ide object.
"frags/controller_supervisor.frag">[controller_supervisor.frag]
Defining the handleEvent Method
The handleEventmethod is essentially a switch statement which handles actions referring to

selected commands, and defers the rest to its supervisor. Define this method to handle
commands defined for the extension, and others that the extension must override. The
BaseController definition defers all commands.
"frags/controller_handleevent.frag">[controller_handleevent.frag]
An event may be handled directly by calling methods that act on the data. Alternatively, an
event may be handled indirectly by creating a command object and invoking it through the
command processor. Some cases where the latter option is preferable are:
● The event has an applicable default behavior. If the action's command class is
compatable with the data then there is no need to re-implement the command. For
example, Ide.SAVE_CMD is the default command class for the 'Save' action, and is
defined for any data class that implements the Document interface.
● The event is to be undoable. The command processor manages undo stacks.
● The event interacts with the system or is otherwise computationally intensive. The
command process invokes commands in their own threads.
Defining the checkCommands Method
The checkCommands method causes selected actions to be updated. Define this method to
call update on actions defined for this extension. Do not update actions defined for a
supervisor: these are the responsibility of the supervisor's checkCommands method, which
20-52
should be invoked as this method first action. Call the update method defined for the passed
activeController, so that future extensions can extend yours and override its actions. The
BaseController definition invokes its supervisor, but has no other effect.
"frags/editorcontroller_checkcommands.frag">[controller_checkcommands.frag]
Defining the update Method
The update method is essentially a switch statement which enables and disables selected
actions, and defers the rest to its supervisor. Define this method for actions defined for the
extension, and others that the extension must override. The BaseController definition defers all
actions.
"frags/controller_update.frag">[controller_update.frag]
Define Command Constants
Define the commands required by your extension by giving them command IDs. The
Ide.newCmd static method assigns unique command IDs.
"frags/controller_command_def.frag">[controller_command_def.frag]
Sample projects
The code examples cited here are taken from the ContextInfo sample project. It and other
Related topics
Creating an Editor
Defining a Command
About IDE Action Processing
Implementing a Command
Defining an Action
20-53
Data objects represent the documents and other data that the user manipulates in JDeveloper.
Data objects should implement JDeveloper's framework data model, so that the data can be
accessed through explorers. The framework model presents data organized into hierarchical
trees. The interfaces that define the framework are:
● Element. A data item in an explorer tree.

● Folder. Elements that can contain other elements, including other folders.
● Node. Elements that are associated with documents.
● Container. Nodes that can contain other nodes, including other containers.
Data objects in JDeveloper are either persistent or transient.
● Persistent objects generally represent files. They are created when a file is opened or
created in JDeveloper, and can be saved and subsequently reopened. Persistent objects
implement the Node or Container or interfaces, usually by extending DefaultNode or
DefaultContainer. Nodes represent documents such as .java and .html files;
workspace (.jws) and project (.jpr) files are examples of containers. The NodeFactory
creates instance of nodes and containers. Persistent objects are displayed in navigator
panes.
● Transient objects generally represent data derived from persistent data, such as a
document's parse tree. Transient objects are potentially regenerated whenever their
underlying data changes. Transient objects implement the Element or Folder interfaces.
Data objects representing XML elements are examples of folders and elements.
Transient objects are displayed in structure explorers.
Related topics

Creating an Editor
20-54
About Notifications
Notifications are a mechanism for transmitting state change messages from data objects to
other views, such as explorers. A transmission has three components:
● The sender, an instance of a class that implements Subject. The sender sends update
message to all recipients by calling their update methods.
● The recipient, an instance of a class that implements Observer. The recipient registers to
receive messages by calling the sender's attach method.
● A message, an instance of UpdateMessage. A message contains an ID indicating the
nature of the sender's state change and lists of the objects involved in the change.
Notifications are based on the Observer Update Message pattern. In designs using this pattern,
the subject (sender) can consists of a number of objects. A state change in such a design can
be complex, involving multiple objects, and can be characterized by the contents of a
message's four lists:
● object creations (add),

● old object deletions (remove), and
● and current object modifications (modify); and
● the locations where these occur (container).
Related topics

Creating an Editor
20-55
Creating a Explorer
A structure explorer displays the organization of a document, usually as a tree.
A structure explorer is closely associated with a document view, such as an editor or designer:
when an editor or designer is given focus, its explorer is shown in the structure window. An
explorer is essentially an index or table of contents for the document: the user uses the
explorer to move about in the content displayed in the document view. The hierarchy of the
document is displayed in the structure pane, and is updated as the document is edited.
JDeveloper provides explorers for various common document types, and allows custom
explorers to be installed and registered with the Explorer Manager. When a document is
opened in JDeveloper the Explorer Manager provides an appropriate explorer for it, which then
parses the document and displays the resulting structure.
An explorer addin has the following components:
● A class that performs the registration. This class implements Addin A single instance of
this class is created by the addin manager when JDeveloper is launched, and that
instance performs the registration. The addin class need have no other purpose.
● A class that provides the explorer's user interface. This class is is a specialized viewer.
When the document's structure is to be represented by a tree most of the required
functionality can be provided by extending TreeExplorer or one of its subclasses. This
class handles mouse clicks on elements, tracks changes in the editor, and invokes the
parser to rebuild the tree when necessary.
● One or more classes that represent the elements representing the structure of the
document. The structure is composed of instances of these classes, which implement
Element. Elements are associated with specific locations in the content of the document,
and when selected, scroll the viewer too that location.
● A parser that generates a structure of elements from the document. The parser reduces
the document to a hierarchy of elements which map to viewer coordinates.
The following topics describe aspects of creating an explorer extension:
● Registering and Initializing a Structure Explorer

● Creating a Structure Explorer Element Model
● Updating A Structure Explorer
20-56
Related topics
Creating an Editor
20-57
Registering and Initializing a Structure Explorer
Explorers must be registered with the IDE's ExplorerManager. A registration associates an
explorer with a node class, or with a node/viewer pair.
When the user selects a viewer for a node, the IDE sends a request to the explorer for the
explorer that best satisfies that node and viewer. The resulting viewer will be one registered for
precisely that node and viewer, or else one registered for the node alone. In no such
registrations have been made, the explorer manager will try to find a viewer that is registered
for a node class that converts to the requested node class.
Registration operations should be performed in an addin class' initialize method.
"frags/exploreraddin_initialize.frag">[exploreraddin_initialize.frag]
Sample projects
Related topics
Creating a Structure Explorer Addin

Creating a Structure Explorer Element Model
Updating A Structure Explorer
20-58
The explorer's element model should be generated whenever the explorer is to be refreshed,
which occurs when the associated viewer is given focus or when the viewer's content is
modified.
An element model should implement the AbstractExplorer interface.
The model's re-creation is the responsibility of the explorer's annotate method. This method
is invoked when the explorer is to be refreshed. To re-create the model pass the viewer's
document to the explorer's parser, and return the resulting element model as the value of
annotate.
Related topics

Registering an Explorer
20-59
A structure explorer should be notified whenever whenever the content of the of the assocated
editor or designer is modified, so that it can update its state. Use the notification mechanism to
transmit information about changes in the viewer to the explorer. The structure explorer should
implement Observer, providing an update method, and register with the object representing
the viewer's document.
Related topics

Registering an Explorer
20-60
Defining a Command
An extension that adds a user-interface element such as menu item or toolbar icon, or
customized an existing element for a new purpose, should encapsulate the functionality in a
command extension.
The following topics describe aspects of command addins:
● Invoking an Addin from a Main Window Menu

● Invoking an Addin from a Context Menu
● Implementing a Command
● Implementing a Controller
● Defining an Action
● About IDE Action Processing
Related topics
20-61
To allow an addin to be invoked from a main window menu, add a menu item for it to one of the
main window menus. The item can be added to any menu, however, if the extension is to be
invoked from the Tools menu, it should be installed as a wizard, rather than (or in addition to)
being installed as an addin: the Wizard Manager takes care of the details of adding and
handling menu item in the Tools menu.
The IDE menus are represent by a singleton instance of Menubar, which can be accessed
using the IDE's getMenubar method.
Extensions can add menus, submenus, and menu items to the IDE menus. Extensions that are
invoked, such as wizards, add their own items to menus when they are installed. Alternatively,
extensions can define their own behavior for standard menu items. For example, effect of the
items in the Edit menu depend on the editor in use.
Menu items are associated with IdeAction objects.
When the state of the IDE changes the enabled/disabled status of all menu items are reset as
dictated by the active view's controller. When the user then selects a menu item or enters a
keyboard shortcut for an item, the command named by the item's action is executed under the
current context.
To define a menu item, provide these components:
● A command ID representing the command that is to be executed when the menu item is
selected.
● An action that is associated with the command ID, and acts as the link between user
actions and the controller.
● A controller responsible for enabling and disabling the menu item and handling its
events, and ultimately invokes the feature installed by the addin.
● The menu item, which serves as the link between user actions and the controller.
Call the menu bar's createMenuItem method to create the menu item. The menu bar is a
component of the IDE.
"frags/msa_createMenuItem.frag">[msa_createMenuItem .frag]
Menus are static members of the Main Window. Call a menu's add method to add a menu item.
20-62
The following example adds a menu item to the Edit menu.
"frags/msa_addMenuItem.frag"> [msa_addMenuItem.frag]
Menu items should be immediately available when JDeveloper is launched, so create and
install them in the addin's initialize method.
Sample projects
Related topics
Defining a Command
Invoking an Addin from a Context Menu
20-63
Invoking an Extension from a Context Menu
Some views, such as the Navigator window and the Code Editor window have context menus
that pop-up when the user right-clicks in the window. Extensions can add items to context
menus.
User interface elements that are represented by objects of any class that implements
ContextMenuListener may have a context menu. Context menus can be used almost anywhere
in JDeveloper: most of the user interface's elements ultimately either implement this class, or
are subcomponents of implementors.
When the user right-clicks the context menu is reconstructed. Selected context menu listeners
— those associated with the subject of the right-click — are polled, and given the opportunity to
contribute items or submenus to the context menu. For example, when a node representing a
document is right-clicked, editors and designers that are registered as viewers for that
document's type are allowed to add their menu items to the context menu.
A context menu listener is polled through these methods:
● poppingUp, called when the context menu is being constructed. The listener should
contribute its menu items at this time.
● poppingDown, called when the context menu is dismissed.
● handleDefaultAction, called on double-clicks, in which case exactly one of the
polled listeners should return true, indicating that the action associated with its menu
item should be invoked.
To allow an extension to be invoked from a context menu, add a menu listener to the view's
context menu. The menu listener will be given an opportunity to install the menu item when the
context menu is recreated, which occurs whenever it pops-up.
To define a context menu item, provide these components:
● A command ID representing the command that is to be executed when the menu item is
selected.
● An action that is associated with the command ID, and acts as the link between user
actions and the controller.
● A controller responsible for enabling and disabling the menu item and handling its
events, and ultimately invokes the feature installed by the addin.
20-64
● A context menu listener, which provides a listener instance for each context menu to
which the item can be added. The various views each manage their own context menus.
The following example adds a listener to the navigator window's context menu.
"frags/msa_createCtxMenuListeners.frag">[msa_createCtxMenuListeners.frag]
The context menu listener should be added when the addin is loaded, so this task should be
performed in the addin's initialize method. The creation of the controller and action can be
deferred until the context menu is opened; the first time it calls the listener's method.
Sample projects
The code example cited here is taken from the ContextInfo sample project. It and other
Related topics
Defining a Command
20-65
If your extension adds a menu item or toolbar icon you should implement its functionality as a
command.
You can implement the command by extending AbstractCommand, in which case all methods
except doit and the constructor may use the provided defaults. Otherwise, implement the
Command interface.
An extension that defines specialized behavior for an existing control should use the action and
command class already provided for it, rather than define a custom action or implement a
custom command class. Fields defined in the Ide class give the class names and IDs of the
IDE's standard commands.
Implementing a Command class for an extension involves these tasks:
● Defining the Constructor

● Defining the doit Method
● Defining the undo Method
● Defining other Methods
Defining the Constructor
The constructor is invoked by the command processor.
"frags/command_constructor.frag">[command_constructor.frag]
The constructor can call one of the constructors defined for its supertype, AbstractCommand:
AbstractCommand(int cmdId)
AbstractCommand(int cmdid, int type)
AbstractCommand(int cmdid, int type, String name)
cmdid is a command ID, which should be defined in the extension's controller class.
type is one of the following:
20-66
● NO_CHANGE. These commands cannot be undone because they do not modify their
subject's structure, and are discarded after they are invoked. This is the default value.
● NORMAL. These commands can be undone. They are pushed onto the document's undo
stack after they are invoked. If this option is selected, the command must provide an
undo method.
● NO_UNDO. These commands irreversibly modify their subject's state. They are discarded
after they are invoked, and the undo stack is flushed.
name is an optional identifier for the command. If not specified it defaults to the empty string.
Defining the doit Method
"frags/command_doit.frag">[command_doit.frag]
This method generally has three tasks:
● If the command is undoable, and is to be undone by restoring a the data to a

checkpointed state, then checkpoint the data, and save it using the setData method. If
the command is not undoable, or is undoable through an inverse operation, this task is
not needed.
● Modify the data.
● Notify observers that the modification has taken place.
Return OK if the command is successful, or CANCEL or some other non-zero value if not.
Defining the undo Method
This method must be defined only if the constructor specifies that the controller is of the
NORMAL type:
This method generally has two tasks:
● Undo the doit methods effect by restoring a checkpointed state with the value obtained
from the getData method, or by performing the inverse of the doit method's operation.
● Notify observers that the modification has taken place.
20-67
Return OK if the command is successful, or CANCEL or some other non-zero value if not. The
default implementation returns CANCEL and has no side-effects.
Defining Other Methods
These methods' default implementations can be overridden, if desired:
● The getId method returns the command ID passed to the constructor.

● The getType method returns the "command type" constant passed to the constructor, or
NO_CHANGE if this argument was not given.
● The getName method returns the name string passed to the constructor, or the empty
string if this argument was not given.
● The getAffectedDocuments method returns null by default.
● The setContext and getContext methods respectively write and read a protected
Context variable. The default value is null.
● The setData and getData methods respectively write and read a private Object
variable. The default value is null.
Sample projects
Related topics
Defining a Command
Defining an Action
20-68
Defining an Action
An extension that implements new command classes should define actions to contain them. An
action serves as the link between a menu item, or other user-interface control, and the
command that is executed when the menu item is selected. Actions are instances of IdeAction.
An extension that defines specialized behavior for an existing UI element should use the action
already provided for it, rather than define a custom action. Fields defined in the Ide class give
the class names and IDs of the standard commands. For example, any editor that provides a
'save' operation should use the predefined Ide.SAVE_CMD and Ide.CUT_SAVE_ID values
and the action that is associated with them.
Actions are typically defined as fields of the Addin class that installs the menu items or toolbar
icons they are associated with. Create and configure actions as part of the extension's
initialization.
The following topics describe aspects of defining an action:
● Obtaining an Action
● Setting Action Values
● Extending an Action's Controller
● Extending an Action's Command Class
Obtaining an Action
Actions are cached by command ID. If an action already exists for the command you require,
you should generally use it instead of creating a new one.
Do not use the IdeAction contstructors to create actions. Instead, use the following static
methods to retrieve a cached action or create a new one:
● The find method returns an action that contains the given command id, if one has
already been cached.
● The various get methods return the action matching the given command id, if such an
action has been cached, but the properties of this action may or may not match the
parameters given. If no action is found for the command ID a new action is created from
the given parameters, cached, and returned.
20-69
● The create methods create and return a new action without caching it. A action
obtained from create will not be available to subsequently loaded extensions.
Setting Action Values
An action may have various properties, such as those that determine appearance, which are
accessed through string keys by the putValue and getValue methods. Some of the
properties are set when an action is created by a create or get static method. Keys
recognized by the IDE are defined in the ToggleAction superclass.
Extending an Action's Controller
An action that is independent of a view, such as 'open', must specify a controller to update the
action and handle its events. An action that is invoked in the context of a view need not have an
action controller.
The behavior of a command, for all IDE features that use that command, can be extended to
perform some custom operation by replacing the controller of the command's action, or by
giving the action a controller if it did not already have one. However, care must be taken to
avoid disrupting default behavior.
To replace an existing controller:
1. Implement the new controller class by extending the old.

2. Override the new controller's supervisor method to return the old controller instance,
so that any commands not extended by the new controller will be updated and handled
as before.
3. In the new controller's handling of the command that is to be extended, perform the
custom operation, and then invoke the old controller's handleEvent method for the
command, so that the original behavior will be preserved.
To add a controller to an action that does not have one:
1. Implement a new controller class.

2. Override the controller's supervisor method to return the controller of the active view,
if any, or else the Ide object. When the new controller declines update or handle a
command it should delegate to the supervisor, so that the commands will be handled as
before.
20-70
3. In the new controller's handling of the command that is to be extended, perform the
custom operation, and then invoke the supervisor's handleEvent method for the
command, so that the original behavior will be preserved.
Use the getController and setController methods ot access an action's controller.
Extending an Action's Command Class
The getCommand method returns the name of the action's command class. The setCommand
method can be used to replace it. However, doing so replaces it globally, affecting all IDE
features that handle the action. To avoid unwanted side effects, replace an original command
class only with a class that extends it.
Related topics
Defining a Command
20-71
The Ide class defines a set of standard command IDs, which are each associated with a unique
action, which in turn are associated with UI elements. Command IDs simply name an operation,
such as "cut" or "save"; the interpretation of a command ID depends on structure of the data
being manipulated.
The general process of transforming user-interface events into state changes has these main
steps:
1. The user triggers an action by choosing a UI element, such as a menu item or toolbar
icon, or by entering a keyboard shortcut.
2. The action and the current context are passed to a controller associated with either the
action or the active view.
3. The controller creates a command, an instance of the command class named by the
action.
4. The command is passed to the IDE's command processor.
5. If the command is undoable the command processor saves it in an undo stack obtained
from the context.
6. The command processor executes the command.
The general sequence above applies to undoable state-change events: the event and its
inverse are embodied in the command object. When and event is not reversable the controller
can perform the state change directly in step 3, and steps 4-6 are not needed.
When practical, new extensions should adopt the actions that are predefined in the Ide class.
An extension that overrides predefined commands or introduces new ones should provide its
own controller. An extension that overrides commands should use preexisting commands and
the actions that contain them: the view's controller updates and handles preexisting actions by
creating, initializing, and executing instances of preexisting command classes. Extensions that
introduce new commands require custom actions and commands.
The following topics describe aspects of event handling in greater detail:
● About Contexts
● About IDE Actions
20-72
● About Commands
● About Controllers
● About Updating IDE Actions
● About Handling IDE Actions
Related topics
Defining a Command
Defining an Action
20-73
About Contexts
A Context object is a record of the state of the IDE. The information a context record can
contain includes:
● The active view, and through it the active context

● The node currently selected in a navigator.
● The element currently selected in an explorer.
● The document associated with the selected item
● The project associated with the selected item
● The workspace associated with the selected item
Whenever focus changes a context is created by calling the active view's getContext
method. It is passed to the active controller's checkCommands method to initiate the process of
updating (enabling and disabling) IDE actions.
When an action is executed the current context is passed to the handleEvent method of a
controller. The controller creates an IDE command, and incorporates the context in it. The
context may be discarded immediately after the command is executed, or it may persist with
the command in an undo stack and be eventually used to restore the document to a previous
state.
The current context can be obtained by calling
getLastActiveView().getContext()
on the main window.
Related topics
About IDE Events

About IDE Actions
About Commands
About Controllers
20-74
About Updating IDE Actions
About Handling IDE Actions
20-75
About IDE Actions
Invokable user interface elements such as menu items and toolbar icons are associated with
actions, which are IdeAction instances. An action serves as a link between a UI element and a
command class: the effect of selecting a menu item is to create an instance of the command
class, as dictated by the current context, and execute it.
The IdeAction class maintains a cache of actions. The actions of the default UI elements can
be obtained from the cache, and adopted or extended by new extensions. An extension that
implements new commands can define new actions for them, and add the new actions to the
cache. An extension's UI elements are created during startup, when the extension is initialized.
Each UI element incorporates an action; either a new action defined by the extension, or an
preexisting action obtained from the cache.
Actions have the following principal responsibilities and properties:
● UI element appearance. Most of the properties that define a UI element's apperance,

such as its label string, icon, and shortcut string, are set when the action is created.
● UI element enabled status. An action is either enabled or disabled. This property is set
whenever the context changes.
● UI element invocation. When a UI element is selected by the user its action's
actionPerformed method is called. This method calls a controller's handleEvent
method, passing itself and the current context. The controller is either action's own
controller, if any, or else the controller belonging to the active view.
● Action controller. Actions associated with UI elements that are not context sensitive, such
as New and Open, have their own controllers.
● Command class. Actions with a default behavior name the class, an implementation of
Command, that provides the behavior.
Related topics
About IDE Events

About Contexts
About Commands
About Controllers
20-76
20-77
About Commands
Commands encapsulate the functionality of an extension. The methods that actually modify
data structures are the doit and undo methods of a Command class. User interface events
cause commands to be created and passed to the command processor, which executes the
command and may also preserve it in an undo stack.
Command IDs identify generic operations, such as "save", "cut"", or "run". Each menu item,
toolbar icon, and keyboard shortcut is associated with an IdeAction instance, which contains a
command ID. The IDE defines the command IDs associated with the standard menu items. An
extension that adds a new menu item or toolbar icon must implement a new Command class
for it, and register it by calling the Ide class' newCmd method to obtain a new command ID.
Commands are created by the command processor's createCommand method, which takes
the name of a command class and a context. This method is called by a controller when a user
action resolves to a command ID known to the controller. For example, an HTML editor
extension will implement a command class that performs text insertions. The editor's controller,
when it receives the Ide.PASTE_CMD_ID command ID, will create an instance of that
command class and pass it references to the clipboard and document's text buffer.
Command classes define two principal methods:
● doit. This method performs the requested operation. It is called when the command
processor is invoked for the command, and may be called following an undo to perform a
'redo'.
● undo. This method performs the inverse of the requested operation.
Undo-ablility is represented by a command's "type", which is one of these values:
● NO_CHANGE. These commands cannot be undone because they do not modify their
subject's structure. They are discarded after they are invoked.
● NORMAL. These commands can be undone. They are pushed onto the document's undo
stack after they are invoked.
● NO_UNDO. These commands irreversibly modify their subject's state. They are discarded
after they are invoked, and the undo stack is flushed.
The command processor is the singleton instance of the CommandProcessor class. The
20-78
command processor invokes commands' doit and undo methods when appropriate, and
manages the undo and redo command stacks for extensions that require that capability.
Related topics
About IDE Events

About Contexts
About IDE Actions
About Controllers
20-79
About Controllers
Controllers interpret user-generated events, translating them into executable commands that
modify the IDE's state. The user chooses a menu item (or toolbar icon, or enters a keyboard
shortcut) which triggers its action (an IdeAction instance). Other events, such as text entry or
mouse and keyboard events, bypass controllers.
Controllers are instances of classes that implement Controller.
The handling of an event depends on the current context, which is a record of the current state
of the IDE. The context and identifies the active view and its controller. When the context
changes the active controller is responsible for selectively updating actions to enable and
disable their menu items.
Controllers can play two roles with respect to event handling:
● View controllers are associated with views, such as editors, and manage events that
occur when the controller's view is the active view, applying them to the views data.
● Action controllers are associated with actions that can be triggered even when they are
not related to the subject of the current view.
The singleton object of the Ide class is a view controller. It's view is the MainWindow object.
Controllers have two main responsibilities:
● When the focus changes they update relevant actions by enabling or disabling them. The
active view's controller has primary responsibility for updating actions, but may defer to
other controllers.
● When an event occurs they handle the action associated with the event. Event handling
is the responsibility of the action controller, if one exists, or the active view's controller.
Controllers are organized into a hierarchy: every controller (except the root controller, which is
the Ide object itself) has a supervisor. A controller will determine how some actions are to be
updated or handled, and defer others to its supervisor. The ultimate supervisor is the Ide object.
Related topics
20-80
About IDE Events
About Contexts
About IDE Actions
About Commands
20-81
When the focus changes the controller belonging to the active view is given the opportunity to
update actions (instances of IdeAction, which are associated with menu and toolbar items and
keyboard shortcuts). The controller updates relevant actions by enabling or disabling them.
The action updating process occurs often, and can be involved: it should be carefully
implemented to avoid intensive computation and duplication.
The process has two parts:
● The relevant actions are selected. This responsibility is shared by the active controller
and its chain of supervisors, ending with the Wizard object itself.
The process begins when the active controller's checkCommands method is called. This
method should invoke checkCommands for its supervisor, and then call update for
actions defined for the controller, if any. Thus, the active controller and all its supervisors,
including the Ide object, select actions to update. The arguments passed to
checkCommands are the current context and the active controller. The active controller
is passed so that all update calls can be made to its update method: this gives the
active controller the opportunity to override a supervisor.
● The selected actions are updated. The active controller is given the first opportunity to
update and action, but may defer to its supervisors. The Ide object is the updater of last
resort.
The actions are passed to the active controller's update method, which is essentially a switch
statement on the action's command ID. If the update method is defined for a given action's
command ID, it should update that action by calling its setEnabled method, and then return
true. Otherwise, the action should be passed to the supervisor, which in turn can update it or
defer to its own supervisor.
Related topics
About IDE Events

About Contexts
20-82
About IDE Actions
About Commands
About Controllers
20-83
After a user event occurs a controller handles the action (an instance of IdeAction) associated
with the event by invoking a command. The action's own controller will be used, if it has one,
otherwise it will be active view's controller. The selected controller may either handle the action
or defer to its supervisors. The Ide object is the handler of last resort.
The actions is passed to the active controller's handleEvent method, which is essentially a
switch statement on the action's command ID. If a handleEvent method is defined for a given
action's command ID, it should construct or select a Command instance, pass it to the invoke
method of the CommandProcessor, and then return true. Otherwise, the action should be
passed to the supervisor, which in turn can handle it or defer to its own supervisor.
Related topics
About IDE Events

About Contexts
About IDE Actions
About Commands
About Controllers
20-84
About Other Extension Types
Various IDE components manage extensions. Each loads, installs, and initializes extensions of
its particular type. To be loaded and recognized by an extension manager, an extension must:
● Implement the required interface. This interface specifies the methods that an extension
manager will call to initialize, install, and invoke the extension.
● Be registered with a manager. The manager invokes the extension.
● Be listed in an appropriate JDeveloper file. Each extension type is associated with a
particular file, which the manager reads to obtain the class names of its extensions.
● Have its class files in a directory or archive known to JDeveloper.
Addins are the most general types of extensions. All extensions that are installed as addins
must implement the Addin interface and be listed in JDeveloper's system/addins-
user.properties file, or some other such file.. All addins are loaded and initialized when
JDeveloper is launched. Depending on their function, extensions must register with various
managers, such as the Explorer Manager or Editor Manager.
Other extension types are loaded and registered through specialized mechanisms. Loading is
not necessarily performed when JDeveloper is launched: instead, loading may be deferred until
the extension is needed.
The following topics briefly describe some extension types that not discussed in detail in this
documentation:
● Dockable views are views that can either float independently or be docked to the IDE's
main window.
● Runners evaluate or execute programs.
● Proxy classes are used to render and manipulate instances of UI classes which can not
be directly rendered or manipulated in the UI Editor.
● Property editors are display and manipulate data in JDeveloper's Property Inspector.
● Java code generators define the way code-builder dialogs generate code for Java
classes.
Related topics
20-85
20-86
About Views
Views are non-modal graphical user interfaces. The IDE's main window is a view, the singleton
instance of MainWindow. Other views are direct or indirect subordinates of the main window. A
view is associated with a controller that handles the user's interaction with the view.
A view displays a data object to the user. A data object can have multiple views. For example,
an HTML document might have an explorer view, one or more WYSIWYG editor views, and
one or more source editor views.
Views communicate changes in their state through the listener
Most views needed by extensions are of one of these common types.
● Editors
● Explorers
● Logs
● Palettes
● Dockable Views.
These views can be implemented by extending one of the AbstractView or DockableWindow

subclasses.
Related topics
About Extensions
20-87
About UI Proxies
UI proxy classes are used to render and manipulate instances of user interface classes which, for
whatever reason, can not or should not be directly rendered or manipulated at design-time by the UI
Editor. UI proxy classes serve as stand-ins for the classes that cannot be rendered. Some cases where
proxies are useful or required are:
● The UI class is an abstract class and thus cannot be instantiated for 'live' representation in the UI
Editor.
● The UI class is a heavyweight (that is, AWT-based) control and thus does not work well within the
lightweight UI Editor.
● The class has runtime behavior (such as data access) which should not be enabled during design
time.
The UI proxy implemented for a class must support the exact API of the class (in addition to any other
members): otherwise it may cause exceptions to be thrown by the UI Editor and the Property Inspector as
the user attempts to manipulate 'live' instances of the proxy. A java.beans.BeanInfo class should also
be provided for the proxy class which exposes only the API of the original UI class, or a subset of its API.
The names of BeanInfo classes must be of the form ProxyBeanInfo, where Proxy is the name of a proxy
class.
If you wish to use custom controls in the UI Editor you may need to provide proxy classes for them. It is
recommenced that any class used as a proxy for a visual control should descend directly or indirectly from
javax.swing.JComponent, because the UI Editor itself is a lightweight (Swing) implementation.
Proxy classes are loaded when JDeveloper is launched. Proxies must be listed in JDeveloper's
bin/addins.properties file, in entries of the form
jdeveloper.concreteProxy.UI_class=proxy_class
where UI_class is the fully-qualified name of a datatype class that requires a proxy, and proxy_class
is the fully-qualified name of the proxy class that will represent it at design-time. For example, the
following entry will load a proxy for the heavyweight class java.awt.Button:
jdeveloper.concreteProxy.java.awt.Button=oracle.jdeveloper.uieditor.proxy.Button
Related topics
About Extensions
20-88
20-89
Property editor classes (implementations of java.beans.PropertyEditor) are used to display and
manipulate data in JDeveloper's Property Inspector.
Property editor classes are loaded when the Property Inspector is first opened. They must be listed in
JDeveloper's bin/addins.properties file, in entries of the form
jdeveloper.propertyeditor.datatype_class=property_editor_class
where datatype_class is the fully-qualified pathname of a datatype class, and

property_editor_class is the fully-qualified pathname of its property editor class. For example, the
following entries will load property editors for int and java.awt.Color:
jdeveloper.propertyeditor.int=borland.jbuilder.cmt.editors.I_Editor
jdeveloper.propertyeditor.java.awt.Color=borland.jbuilder.cmt.editors.ColorEditor
Related topics
About Extensions
20-90
About Java Code Generators
Java code generators define the way code-builder dialogs, such as New Class and New Frame, generate code for Java
classes. When, in the dialog's 'Extends' box, the user selects a base class that matches a code generator, the code generator
specifies the content of the dialog's 'Optional Attributes' box, and then generates code based on the selected attributes.
Code generator classes are loaded when requested by a dialog. They must be listed in JDeveloper's
bin/addins.properties file, in entries of the form
jdeveloper.builder_type.generator.base_class=generator_class
where builder_type is a class-builder class, base_class is the class that is to be extended by the newly-generated class,
and generator_class is the code-generator class that is to be loaded. All of these classes must be identified by fully-
qualified pathnames. For example, the entry
jdeveloper.frame.generator.javax.swing.JFrame=oracle.jdeveloper.builder.ui.frame.JFrameGenerator
causes the New Frame dialog to offer javax.swing.JFrame as one of its 'Extends' options, and if it is selected, to use
JFrameGenerator to collect optional arguments and generate the code for the new class. A generator named in an entry
with a wildcard ('*') for the base-class field is the default generator; to be used for all base classes that do not have an
explicitly defined generator.
Related topics
About Extensions
20-91
Extensions deployed as .jar files may be installed simply by depositing the .jar file in the
jdev/lib/ext directory (where jdev is your JDeveloper root directory), and restarting
JDeveloper.
Otherwise, various configuration files must be edited to make the extension known to
JDeveloper. Install an extension in JDeveloper by editing configuration files as required:
1. Add the extension's directory to JDeveloper's class path

2. List the extension in the appropriate JDeveloper configuration file
Adding a directory to JDeveloper's class path
The directory or archive containing the extensions class files must be named in the
jdev/bin/jdev.conf file, in entries such as
AddJavaLibFile ../mywork/classes
AddJavaLibFile ../mywork/hellox.jar
Edit jdev/bin/jdev.conf file to add entries for your class directories and archives.
Listing an extension in a configuration file
Extension classes must be named in an appropriate JDeveloper file. These files are read by the
IDE components that load the extensions. The file an extension is listed in depends on
extension class that installs the extension. Some extensions will be listed in more than one
configuration file.
Some extension are listed in system directory files. Each JDeveloper user home directory has
its own system directory. Addins listed in a particular system directory are installed only in
invocations of JDeveloper launched from that system directory. Other extensions are listed in
files in other JDeveloper subdirectories, and are available in all JDeveloper invocations.
If you are installing a finished extension for use, install it in your default user home; typically
jdev/system. If you are installing an addin for debugging, install it in the user home created
for debugging.
20-92
To install an extensions, perform one or more of the following tasks:
● List an addin
● List a gallery wizard
● List a toolbar button
● List a keyboard accelerator context
Listing an addin
Extensions that implement the oracle.ide.addin.Addin interface can be listed in the

addins-user.properties in a JDeveloper system directory.
To list an addin:
1. In you user home directory open system/addins-user.properties for editing. If it

does not exist, create it to have the following content:
#
# User addins
#
AddinCount=0
2. Add an entry for your Addin class. The file contains a sequence of entries of the form
AddinN=class_name
where N is an integer integer indicating when in the sequence the addin is to be loaded,
and class_name is the fully-qualified name of a class that implements the Addin
interface. For example, the entry
causes HelloX to be loaded third.
20-93
3. Increment the file's AddinCount property. This value must be greater than the highest-
numbered addin entry. The Addin Manager will scan the file for addin properties, in
numerical order from zero to AddinCount - 1, and will attempt to load and initialize
those it finds. New addins should be added to the end of the sequence, and the order of
the other addins should not be disturbed.
Listing a gallery wizard
Extensions that implement the oracle.ide.addin.Wizard interface can be listed in

JDeveloper's lib/gallery.xml file. This file describes the structure of the pages and items
that comprise the gallery, using XML syntax:
● The root element represents the gallery contains a list of elements representing gallery
pages. The tag of the root element is <Gallery
class="oracle.ide.gallery.RootGalleryFolder">.
● A gallery page item contains a list of elements representing gallery elements. The tag of
a page element is <Item class="oracle.ide.gallery.GalleryFolder">.
● A gallery element item provides a wizard's display name and fully-qualified class path. An
example of a gallery element is:
<name>Wizard Name</name>
<wizardClass>fully.qualified.wizard.Classname</wizardClass>
<wizardParameters/>
</Item>
To list a wizard in the gallery:
1. Open jdev/lib/gallery.xml for editing, where jdev is your JDeveloper installation

directory.
2. Find the element represent the page on which your wizard is to appear.
3. Copy the example Item element above into the file into that page's list of gallery
elements.
4. Edit the item's name element to show your wizard's display name.
5. Edit the item's wizardParameter element to show your wizard's classpath.
20-94
Listing a toolbar button
Extensions that implement the oracle.ide.keyboard.AbstractCommand interface can be

listed in the ide.properties file in a JDeveloper system directory to define selectable main
window toolbar elements.
To list a toolbar button:
1. Open the ide.properties for editing..
2. Find the section titled Addins Toolbar items.
3. Add an entry for your AbstractCommand class. The file contains a sequence of entries of
the form
MainWindow.Addin.Toolbar.itemN=class_name
where N is an integer integer indicating when in the sequence the item is to be loaded,
and class_name is the fully-qualified name of a class that implements the
AbstractCommand interface. For example, the entry
MainWindow.Addin.Toolbar.item3=RunProjectCommand
causes RunProjectCommand to be loaded fourth.
4. Increment the file's MainWindow.Addin.Toolbar.count property. This value must

be greater than the highest-numbered toolbar entry. The Addin Manager will scan the file
for toolbar properties, in numerical order from zero to AddinCount - 1, and will
attempt to load and initialize those it finds. New addins should be added to the end of the
sequence, and the order of the other addins should not be disturbed.
Listing a keyboard accelerator context
20-95
Extensions that implement the oracle.ide.keyboard.XMLKeyStrokeContext interface
can be listed in the keyboard descriptor (.kdf) files in a JDeveloper system directory. The
files describe alternative accelerator bindings. The extension should be listed in each file, but
need not describe the same bindings in each file.
Descriptor files have an XML syntax. Each file contains a single preset element containing
several context elements. Context elements consist of a number of map elements, which
name IDE commands that apply to the context. Some map elements associate accelerator
keys with their commands. An example of a context element having three map elements is:
<context name="oracle.jdevimpl.runner.run.JRunnerGlobalKeys">
<map action="ViewRunManager" scope="global">
</map>
<map action="RunProjectCommand" scope="global">
<accel>F11</accel>
</map>
<map action="RunSelectionCommand" scope="global">
</map>
</context>
To list a keyboard accelerator context in a descriptor file:
1. Open the descriptor file for editing.

2. Find the end of the file's preset element.
3. Create a new context element. (Insert it immediately before the </preset> tag.)
4. Edit the element's name attribute to the fully-qualified classname of your extension.
5. Add map elements to the body of the context element. In each, name a command in
the action attribute, and optionally name an accelerator key in the accel element.
Related topics
20-96
20-97
Debugging JDeveloper extensions is similar to debugging other Java programs, and uses the
same tools and techniques. However, debugging is complicated by the fact that an extension is
integrated into the JDeveloper IDE, so the debugger must debug a second invocation of
JDeveloper. The original invocation is the debugger process, and oversees the execution of the
debuggee process, which includes the extension.
Before an extension can be debugged, it must be successfully built with debugging information
and be installed in JDeveloper by listing it in one or more configuration files. Before you debug
the extension for the first time you must prepare the extension for debugging.
To debug a extension project, once it has been prepared, set breakpoints and choose Debug |
Debug. The debuggee JDeveloper process will start. Interact with your extension in the
debuggee process, and interact with the debugging tools in the debugger process.
To prepare an extension for debugging:
1. Configure a project for debugging

2. Add the extension's directory to JDeveloper's class path
3. Create a home directory for the debuggee process
4. List the extension in the appropriate JDeveloper configuration file
Configuring a project for debugging
Configure the project for debugging in the Project Settings dialog. To open the dialog, choose
Project | Project Settings. You may accept the defaults for most settings, but make or verify the
following settings.
To configure a project for debugging:
1. On the Configurations page set the Currently Active Configuration to Production.

2. On the Configurations | Production | Paths page set the Output Directory to specify the
depository for generated class files; for example, mywork/classes in your JDeveloper
directory.
3. On the Configurations | Production | Libraries page move JDeveloper Addin API
and any other needed libraries to the Selected Libraries list.
20-98
4. On the Configurations | Production | Runner page:
1. Set the Default Run Target to name the file containing your project's extension
class. This is a class that implements Addin, Wizard, or some other extension
interface.
2. Set the Run Directory to be specify the location of the user home directory; for
example, myhome in your JDeveloper directory.
Adding a directory to JDeveloper's class path
The root directory of the extension's class path, which must match the Output Directory given
in your project's project settings on the Configurations | Production | Paths page, must be
specified in JDeveloper's jdev/bin/jdev.conf file, in an entry such as
AddJavaLibFile ../mywork/classes
This entry tells JDeveloper to search the mywork/classes directory in the JDeveloper
installation for the class files it wishes to load.
Creating a home directory for the debuggee process
The debuggee process must run from its own user home directory, so that it does not interfere
with the debugger process. A debuggee process, once created, may be used to debug any
number of extensions.
The user home directory, if it does not already exist, will be created in the Run Directory given
in your project's project settings on the Configurations | Production | Runner page.
To create a user home directory:
1. Launch the debugger. Select your project, right-click, and choose Debug.
2. A dialog will open with the query, "The user home located under directory ... does not
exist. Would you like to create it now?" Click Yes.
3. A second JDeveloper instance will start. Close it. Note that a system directory has been
created in your run directory. This is the debuggee process' user home.
4. In the newly created user home directory create a text file named addins-
user.properties, having the following content:
20-99
#
# User addins
#
AddinCount=0
Listing an extension in a configuration file
Extension classes must be named in an appropriate JDeveloper system file. These files are
read by the IDE components that load the extensions.
Listing addins
List addins in a addins-user.properties in a user home directory. When you are

debugging an addin, this is the debuggee user home directory created above. When you are
installing a completed addin, this is the system subdirectory in your JDeveloper directory.
To list an addin:
1. Add an entry for its Addin class. The file contains a sequence of entries of the form
AddinN=class_name
where N is an integer integer indicating when in the sequence the addin is to be loaded,
and class_name is the fully-qualified name of a class that implements the Addin
interface. For example, the entry
causes HelloX to be loaded third.
2. Increment the file's AddinCount property. This value must be greater than the highest-
numbered addin entry. The Addin Manager will scan the file for addin properties, in
numerical order from zero to AddinCount - 1, and will attempt to load and initialize
those it finds. New addins should be added to the end of the sequence, and the order of
the other addins should not be disturbed.
20-100
Listing other extensions
Wizards and other extensions that are loaded on demand must me cataloged in other
configuration files. See the documentation on the specific extension type for more information.
Related topics
20-101
Getting Started Reference
● Add JavaBeans Dialog
● Add Library Dialog
● Add URL Dialog
● Archive Viewer
● Browse Symbol Dialog
● Class and Package Browser
● Class Editor - Events Page
● Class Editor - Fields Page
● Class Editor - General Page
● Class Editor - Methods Page
● Classes and Packages to Include or Exclude
● Code Editor
● Component Palette
● Configure Component Palette Dialog
● Confirm Library Deletion
● Connection Wizard - Authentication Page
● Connection Wizard - Connection Page
● Connection Wizard - Connection Page#jdbc
● Connection Wizard - Connection Page#jdbc-odbc
● Connection Wizard - Connection Page#lite
● Connection Wizard - Connection Page#otherjdbc
● Connection Wizard - Finish Page
● Connection Wizard - Test Page
● Connection Wizard - Type Page
● Connection Wizard - Welcome Page
● Directory Options Dialog
● Document Bar
21-1
● Edit Class, Source, or Doc Path Dialog
● Edit Library Dialog
● Export Connection Descriptors Dialog
● Field Settings Dialog
● Find Text / Replace Text Dialog
● Generate Javadoc Dialog
● Go to Line Number Dialog
● HTML Converter Could Not Run
● HTML Converter Does Not Exist
● HTML Root Directory Does Not Exist
● Image Viewer
● Implement Interface Dialog
● Import Connection Descriptors Dialog
● Import Set Dialog
● Invalid Class Name
● Load Preset Dialog
● Log Window
● Method Settings Dialog
● Move Classes Dialog
● New Application Project Wizard - Finish Page
● New Application Project Wizard - Libraries Page
● New Application Project Wizard - Location Page
● New Application Project Wizard - Paths Page
● New Application Project Wizard - Welcome Page
● New Class Dialog
● New Configuration Dialog
● New Gallery
● New Gallery - Beans Category
● New Gallery - Beans Category#bean
21-2
● New Gallery - Beans Category#beaninfo
● New Gallery - Beans Category#customizer
● New Gallery - Beans Category#ejb
● New Gallery - Beans Category#eventset
● New Gallery - Beans Category#formspjc
● New Gallery - Beans Category#propertyeditor
● New Gallery - Connections Category
● New Gallery - Connections Category#applicationserverconnection
● New Gallery - Connections Category#databaseconnection
● New Gallery - Connections Category#scmconnection
● New Gallery - Connections Category#soapserverconnection
● New Gallery - Connections Category#webdavconnection
● New Gallery - Projects Category
● New Gallery - Projects Category#applicationproject
● New Gallery - Projects Category#bcproject
● New Gallery - Projects Category#emptyproject
● New Gallery - Projects Category#remotedebugproject
● New Gallery - Projects Category#sourceproject
● New Gallery - Projects Category#warproject
● New Gallery - Projects Category#webmoduleproject
● New Gallery - Projects Category#workspace
● New JDK Dialog
● New Layout Dialog
● New Library Dialog
● New Palette Page Dialog
● New Project Dialog
● New Project from Existing Source - Add Source Files and Directories Page
● New Project from Existing Source - Finish Page
● New Project from Existing Source - Location Page
21-3
● New Project from Existing Source - Run Settings Page
● New Project from Existing Source - Source Paths Page
● New Project from Existing Source - Welcome Page
● New Project from WAR File - Location Page
● New Project from WAR File - WAR Location Page
● New Project from WAR File Wizard - Finish Page
● New Workspace Dialog
● Open or Create a File and "Add to" Dialogs
● Override Methods Dialog
● Preferences Dialog - Accelerators Page
● Preferences Dialog - Code Insight Page
● Preferences Dialog - Code Style Page
● Preferences Dialog - Code Templates Page
● Preferences Dialog - Display Page
● Preferences Dialog - Documentation Page
● Preferences Dialog - Editor Page
● Preferences Dialog - Environment Page
● Preferences Dialog - Fonts Page
● Preferences Dialog - Layouts Page
● Preferences Dialog - Syntax Colors Page
● Preferences Dialog - Undo Behavior Page
● Project Settings Dialog - Common Page
● Project Settings Dialog - Configurations Page
● Project Settings Dialog - Development Page
● Project Settings Dialog - Input Paths Page
● Project Settings Dialog - Libraries Page
● Project Settings Dialog - Paths Page
● Property Inspector
● Rename Class Dialog
21-4
● Rename Configuration Dialog
● Rename Layout Dialog
● Save As and Rename Dialog
● Save Scheme Dialog
● Search Files Dialog
● Select Directories and Files Dialog
● Select Directories and Files Dialog
● Structure Window
● System Navigator
● UI Editor
● UI Editor, with menu focus
● Windows Dialog
21-5
Add JavaBeans Dialog
Use the JavaBeans dialog to add JavaBeans to the Component Palette.
Library
Select the library which contains the components you wish to install.
Component
Displays the components for the library selected above. Select the component grouping
(by class) to be installed.
Filter
All classes
Select to display all classes, whether they are JavaBeans or not.
JavaBeans with BeanInfo only
Select to display only those classes which have accompanying BeanInfo classes.
JavaBeans in jar manifest only
Select to display only those classes which are JavaBeans, as defined in a
manifest .jar file.
Icon
Noneditable. Displays the name and location of the icon file associated with your
selection in the Component list box above. Initially, this will be the default icon for the
selected tag.
Use Default
Click to accept the default icon for this component.
Select Image
Click to browse for an icon other than the default to use for this component. When you
return to this dialog, the path for the icon you have selected appears in the Icon field
above.
Related topics
About JavaBeans
21-6
Add Library Dialog
Use the Add Library dialog to select a library from which to add components to the Component
Palette.
To use the dialog, select a library and then click OK.
Related topics
About Libraries
21-7
Add URL Dialog
Use the Add URL dialog to add a URL to the doc path for a library.
Enter a new URL

Enter the URL to be added.
21-8
Archive Viewer
Use the Archive Viewer to view .jar, .zip, .war, and .ear files. You can view the content of
an archived file by double-clicking it.
21-9
Browse Symbol Dialog
Use the Browse Symbol dialog to locate the source code for a given type.
Name
Enter the name of a class or interface to browse. The source file for the class or interface
is displayed in the Code Editor.
Sources can be displayed only for classes present in the project's source path.
Related topics
About Project Paths

About Libraries
Project Settings Dialog - Input Paths Page
Project Settings Dialog - Libraries Page
21-10
Class and Package Browser
Depending upon your context, you may see the Class Browser, the Package Browser, or a
browser combining the two.
The browser displays a tree of all of the classes and packages, as appropriate, available from
the current context, which may mean items in your classpath, in your source path, or both.
Depending upon context, you may be able to select multiple items.
Related topics
About Packages
21-11
Class Editor - Events Page
Use the Events page of the Class Editor to make your class an event source for event sets you
select or to register your class's interest in events generated by other components.
New Event Set

Click when your class needs to fire custom events that are not supported by AWT or
JFC. The New Event Set dialog appears, which you use to define the individual events of
your custom event set. When you complete this dialog, the new files are generated, a
listener is created, and the event set is added to a custom events grouping of each list.
The New Event Set dialog is also available from the New Gallery.
Import Event Set
Click when your class needs to fire previously defined events that are not supported by
AWT or JFC. The Import Event Set dialog appears, which you use to locate the event-
listener class that describes the events of the desired event set. When you complete this
dialog, the event set is added to a custom events grouping of each list.
Fire these types of events
Select the event sets that you want instances of your class to be able to fire. The editor
generates the fireEventName(SelectionNameEvent e) method in your class for
each event set you select, as well as the
addselectionNameListener(selectionNameListener l) and
removeselectionNameListener(selectionNameListener l) methods.
Listen for these events
Select the event sets that you want instances of your class to be able to listen for. The
editor generates the implementsselectionListener clause and generates stubs
for each event in the event set you selected.
Related topics

21-12
Class Editor - Fields Page
Use the Fields page of the Class Editor to add, modify, or delete fields from your class
definition.
Declared Fields
Each field displays with its name, scope, and type listed. To view all of a field's settings,
select it and click the Edit button to open the Field Settings dialog.
Click to add a new field to your class. The Field Settings dialog appears, from which you
can define or edit field settings.
Click to remove the currently highlighted field description from the Declared Fields list.
When the confirmation dialog appears, click OK to delete the field and its associated
code from your class definition.
Click to view and edit the currently highlighted field description. The Field Settings dialog
appears, from which you can define or edit field settings.
Show Inherited Fields
Select to view the list of fields your class inherits from its ancestors. The Fields page
does not allow you to edit inherited fields.
21-13
Class Editor - General Page
Use the General page of the Class Editor to provide JDeveloper with explicit information about
a JavaBean. The designer adds a BeanInfo class to your project that is a subclass of
SimpleBeanInfo.
This option does not allow you to create a class that implements your own custom BeanInfo
interface. You may want to do this, for example, when your company supplies a standard interface
for this purpose. In this case, you should use the New BeanInfo dialog that you select from the
Beans category of the New Gallery.
Class Data
Displays the name, package, and superclass for the class that the editor has been
opened on.
Generate BeanInfo
Click to add an automatically generated BeanInfo class to your project.
Create a BeanInfo for your bean when you want to supply custom property editors that
will provide explicit information about a bean to JDeveloper, rather than having
JDeveloper derive the information through automatic introspection.
Create a BeanInfo for your bean when you do not want to:
❍ Give the user of your JavaBean access to every property or event at design time
❍ Use the JavaBeans design and naming conventions for new or existing classes
Related topics
21-14
Class Editor - Methods Page
Use the Methods page of the Class Editor to add, modify, or delete methods from your class
definition.
Declared Methods
The list of methods that your class defines is displayed here. Each method displays with
its primary settings listed. To view all of a method's settings, select it and click the Edit
button to open the Method Settings dialog.
Click to add a new method to your class. The Method Settings dialog appears,
from which you can define or edit method settings.
Click to remove the currently highlighted method description from the Declared
Methods list. When the confirmation dialog appears, click OK to delete the method
and its associated code from your class definition.
Click to view and edit the currently highlighted method description. The Method
Settings dialog appears, from which you can define or edit method settings.
Show Inherited Methods
Select to view the list of methods your class inherits from its ancestors. The
Methods page does not allow you to edit inherited methods.
Related topics

21-15
Classes and Packages to Include or Exclude
Use this dialog to manage which classes and packages are included in or excluded from your
classes.
Add
Click to open the Class and Package Browser, from which you select the classes and
packages to be added.
Remove
Click to remove the currently selected item in the list.
21-16
Code Editor
The Code Editor displays text files of any type, such as language source and header files.
Double-clicking a node in the Navigator opens or brings the default editor to the foreground.
When a file is open in the Code Editor, its corresponding elements are displayed hierarchically
in the Structure window. Double-clicking a node in the Structure window takes you immediately
to that location in the open Code Editor.
To locate the node in the Navigator that corresponds to the file you are currently working on,
from the main menu choose Search | Locate in Navigator. Or, as always, use the keyboard
shortcut. (In the default keymap, Alt-Home.)
Right-click anywhere within this editor to bring up a context-sensitive menu of commands. The
menu commands available depend on the type of file you are editing.
Working in the Code Editor
Insert mode for the editor is controlled by the Insert key on the keyboard. The default is insert
mode. Press Insert to toggle between insert and replace mode.
Searching Incrementally
To search incrementally either forwards or backwards, from the main menu choose Search |
Incremental Search Forward or Search | Incremental Search Backward. In the dialog that
appears, begin typing. As you type, the cursor jumps to the next instance of that particular letter
combination, either forward or backward. The search does not support wildcards.
Scrolling with the Wheel Mouse
If you are using a wheel mouse, you have two additional scroll options. Hold down the shift key
to scroll one line at a time. Hold down the control key to scroll an entire page at a time. The
default scroll length is three lines.
Using Code Insight
You can use Code Insight to speed up the process of writing code. Code Insight has two
varieties: completion insight and parameter insight. You can enable or disable each
independently and set the delay in seconds for each to appear when the cursor is paused at an
appropriate insertion point.
21-17
To invoke completion insight, pause after typing the period separator or, in the default keymap,
press Ctrl-Space. To invoke parameter insight, pause after typing an open (the left) parenthesis
or, in the default keymap, press Ctrl-Shift-Space. If you change your keymapping, these
keyboard accelerators may change.
To change Code Insight settings or to view or change accelerators, from the main menu
choose Tools | Preferences to open the Preferences dialog and then navigate to the
appropriate page.
Using Code Completion Templates
You can also use code completion templates to speed up the process of writing code. Code
completion templates consist of a set of letters (the shortcut) used to evoke the template, the
template code itself, and any imports associated with that code. You can edit existing
templates, should you wish, or create your own.
To invoke a code completion template, type the shortcut associated with the template and then,
with the cursor positioned at the end of the shortcut, press Ctrl-Enter. If you change your
keymapping, this keyboard accelerator may change.
To edit or create code templates or to view or change accelerators, from the main menu
choose Tools | Preferences to open the Preferences dialog and then navigate to the
appropriate page.
Related topics

The Structure Window
The Property Inspector
About Code Insight

About Browse Symbol
21-18
Component Palette
The Component Palette displays the visual components of the JDeveloper component library.
These packages of related components are displayed individually, either in an icon view or a
list view.
Select the palette toolset you wish to work with from the dropdown list. The toolset display
changes to reflect the current UI focus.
To toggle between views, right-click and choose Icon View or List View.
Use the Component Palette to:
● Add components to your user interface

● Add JSP tags to a JSP
● Add elements to a UML diagram
● Add XSQL tags to an XSQL page
To customize the Component Palette, choose Tools | Configure Palette or with the focus in the
Palette, right-click and choose Properties.
Note that when an element in either the icon or list view is depressed, this component is
selected. To drop an instance of this component into the editor, simply click within it.
Pinning a Component
To drop multiple instances of a given component in an editor, hold the Shift key down when you
select the component from the Palette. A new instance of the component now appears
whenever you click within the editor. To turn the selection off, click the Pointer tool. The Pointer
tool is common to all toolsets, and appears at the beginning of the component listing for each.
Related topics
21-19
Configure Component Palette Dialog
Use the Configure Component Palette dialog to configure the Component Palette.
Page Type
Select Java or JSP pages to limit the display to one or the other, or select All to display
both page types at once.
Pages
Noneditable. Displays a listing of the pages currently contained on the Component
Palette, based on the selection you have made in the Page Type field above.
Components
Displays a listing of the components for the page currently selected in the Pages list box.
New Page
Click to add a new page to the Palette.
Delete Page
Click to remove the page currently selected in the Pages list box from the Palette.
Add Component
Click to add a JavaBeans or JSP component to the selected Palette page.
Remove Component
Click to remove the component currently selected in the Components list box.
21-20
Confirm Library Deletion
Deleting a library is irreversible. The deleted library will no longer be available to any projects
within JDeveloper.
If the library being deleted is a user library, and the library name matches an existing system
library as well, the previously hidden system library will be restored. Any project using the
library name will now refer to the system library instead of the user library.
Related topics
About Libraries
21-21
Connection Wizard - Authentication Page
Use the Authentication page of the Connection Wizard to define authentication measures either
for a database or an application server connection.
Username
Enter the username to be authorized for access to the database or application server.
Password
Enter the password to be associated with the specified username. An asterisk (*)
appears for each character you type in this field.
Role
If applicable, enter a role. This must be a specific database role, such as SYSDBA, as
defined in the database. For more information on roles, refer to Oracle9i documentation.
This field is optional.
Deploy Password
Select to include the password for this connection with the archives deployed for it, in
plain text, in the runtime version of the connection.xml file. Deselect to require the
user to supply a password when connecting. By default, this option is deselected.
Typically, you would select this option for development testing purposes only, as it
enables you to connect more quickly, and then deselect it again before you deploy your
final application.
Warning: Once you have finished development and testing of your application, be sure to
deselect this option. Because the password is stored in unencrypted text, it could pose a
security breach in your final product.
Related topics
About Connections
21-22
Connection Wizard - Connection Page
Use the Connection page of the Connection Wizard to define the information necessary for the
connection type selected on the Type page. For a database connection, the following types are
available:
● Oracle (JDBC)
● JDBC-ODBC bridge
● Oracle Lite
● Third-party JDBC driver
Oracle (JDBC)
Driver
Select a JDBC driver from the dropdown menu.
thin
Use this type 4 driver when creating Java applets, or when you need a pure Java
environment. As a type 4 driver, it is written entirely in Java. The thin driver can be
used to connect to Oracle9i, Oracle8i, or Oracle8 databases with TCP/IP network
protocols.
This driver is included in the default Oracle JDBC library for all projects. The library
is named Oracle JDBC and it includes both the Thin JDBC and JDBC-OCI8 driver
library components.
oci8
Use this type 2 driver when creating a Java application that runs against an Oracle
server. As a type 2 driver, it is a mix of Java and native code. This is a thick driver
optimized for the Oracle9i database. This driver handles any database protocol
(TCP, IPX, BEQ, and so on). It is recommended for applications which are run
from the machine they are stored on. It can also be used against an Oracle7
database.
This driver requires client software installation. The project must also include the
correct version of the driver in a library and include no other Oracle JDBC library.
This driver is included in the default Oracle JDBC library for all projects. The library
is named Oracle JDBC and it includes both the Thin JDBC and JDBC-OCI8 driver
21-23
library components. For all OCI and type 2 JDBC drivers, see JDeveloper's
Connection Requirements for Oracle's Type 2 Drivers (OCI).
Host Name
Enter a value to identify the machine running the Oracle server. Use an IP address or a
host name that can be resolved by TCP/IP, for example, myserver. Default value:
localhost.
JDBC Port
Enter a value to identify the TCP/IP port. Default value: 1521.
SID
Enter a value for the unique system identifier (SID) of an Oracle database instance.
Default value: ORCL.
Enter Custom JDBC URL
Select to enter a custom URL to bypass the information on this page and provide
connection information directly to the driver. If you are using TNS or a naming service
with the OCI driver, you will need to employ this option.
Use a URL with a format similar to:
jdbc:oracle:oci8:<USERNAME/PASSWORD>@(DESCRIPTION=
(ADDRESS=(PROTOCOL=<PROTOCOL>
(PORT=<PORT>)
(HOST=<HOSTID>))
(CONNECT_DATA=(SID=<SID>))))
Note that if you are using TNS names, you must have ORACLE_HOME in your PATH
environment variable for JDeveloper to find your TNSNAMES.ora file.
JDBC-ODBC Bridge
Use this type 1 driver to connect with standard, ODBC-compliant drivers. Refer to your ODBC
vendor's documentation for connection requirements.
Datasource Name
Enter the name defined using the Microsoft ODBC driver manager.
21-24
Extra Parameters
Enter any additional parameters as required by the driver.
Oracle Lite
Use this type 1 driver when creating a Java application that runs against an Oracle Lite
database.
This driver requires installation of Oracle8i Lite 4.0 or higher. Projects using the driver must
include <ORACLE_HOME\lite\classes\olite.jar> in a library. For more information,
refer to the documentation for Oracle Lite.
Datasource Name
Enter the name defined using the ODBC driver manager of your Oracle Lite datasource.
Extra Parameters
Enter any additional parameters as required by the driver.
Third-party JDBC Driver
Use this option for other vendors' JDBC-compliant drivers not listed in the dropdown menu. In
addition to the information in the fields on this page, projects connecting through the third-party
JDBC driver option must include that driver's .zip or .jar file in in a JDeveloper library. For
additional information on connection settings for the driver, refer to the driver vendor's
documentation. For type 2 JDBC drivers, see JDeveloper's Connection Requirements for
Oracle Type 2 Drivers (OCI).
Java Class Name

Ener a fully qualified name for the driver you're using. The Java class name uses Java
syntax and corresponds to the vendor's packaging of the driver.
oracle.jdbc.driver.OracleDriver is the Oracle JDBC driver. Other vendors may
package their drivers in the form vendor.jdbc.product.driver. For more
information, refer to the documentation for the specific JDBC driver.
URL
Enter any additional parameters as required by the driver. Refer to the driver vendor's
datasource URL documentation for syntax information. The default format is
jdbc:vendor:type@vendor_URL. For example (assuming an Oracle datasource):
21-25
jdbc:oracle:thin@hostname:port:sid
Related topics
About Connections
21-26
Connection Wizard - Finish Page
The Finish page finalizes your new database or application server connection, directing you to
the Navigator, where the new connection node now appears.
21-27
Connection Wizard - Test Page
Use the Test page of the Connection Wizard to test the database or application server
connection defined in the Type, Authentication, and Connection pages of the wizard.
Test Connection
Click to test the connection.
Status
Displays the status for the connection being tested. Any errors will be displayed here. In
case of a connection failure, return to earlier wizard pages to correct entries.
Related topics
About Connections
21-28
Connection Wizard - Type Page
Use the Type page of the Connection Wizard to define the connection type either for a
database or an application server connection.
Connection Name
Enter a name for the connection. The connection name must be a valid Java identifier.
Additionally, as the name and connection are global across your JDeveloper installation,
choose an appropriate and unique name.
Connection Type
Select a connection type from the dropdown list. The type selected here determines the
fields displayed on the Connection page. The types displayed here are a reflection of
whether you have entered this wizard through a database connection or an application
server connection node.
Related topics
About Connections
21-29
Connection Wizard - Welcome Page
Use the Connection Wizard to establish a new database or a new application server
connection. This wizard is reentrant, so you can also use it subsequently to edit existing
connections.
The Welcome page introduces you to the wizard. Deselect the checkbox to disable this page
when next you open the wizard to create a new connection.
Related topics
About Connections
21-30
Directory Options Dialog
Use the Directory Options dialog to define how the directory you have selected will be imported.
Directory
Noneditable. Reflects the directory selected in the directory or file chooser.
Recurse Subdirectories
Select to include all subdirectories when importing the directory selected above.
Add Files Matching Pattern
Enter a value or select from the dropdown list to further refine your import. Only files with
the extension indicated here will be imported, in the base directory or throughout
subdirectories, depending upon your selection for recursion.
Note that you can type in a filename filter or wildcards, if you wish, as well as an
extension type. Entering base*.java, for example, imports all those files beginning with
base and ending in .java.
21-31
Document Bar
The document bar displays the files you have opened explicitly in editor windows (for example
directly from the Navigator or through the Open dialog), as well as any files called by those
editors as you work, for example, by debugging or browsing symbols. Explicit documents
display with numbers assigned to them which reflect the order in which you originally opened
them, from 1 to 9. Access additional documents opened by clicking the double-arrow button in
the far right of the bar. Implicit documents are not automatically assigned numbers.
Explicit documents retain the numbering automatically assigned to them until you close them or
until you reassign them with a new number. Existing documents do not renumber when one or
more in a sequence have been closed. Given the document sequence 1 through 5, for
example, closing the document numbered 4 does not result in any change in the numbering for
1, 2, 3, or 5. The next document you explicitly open, however, takes the first available number,
which in this case is 4. You can also renumber documents whenever you like, or assign
numbers to implicit documents. Once you have done so, they are treated as explicit windows.
The usefulness of the document bar is in the ease with which it enables you to move between
and manipulate editor windows. It is for this reason that the documents in the bar remember the
number assigned to them, only taking a new number if you redefine one for them.
To toggle quickly through explicit documents, press Alt-#, where # is the number assigned the
document you wish to make active.
To reassign the number of an explicit document, or to assign a number to an implicit document,

select the document name in the bar and press Alt-Shift-#, where # is the number to be
assigned to the document.
To view all documents, both implicit or explicit, in alphabetical order, click on the double-arrow
button in the far right of the bar. Selecting a document in this list makes it active.
To close any document individually, whether explicit or implicit, right-click on the document
name in the bar and choose Close Editor.
To close all implicit windows at once, click on the double-arrow button in the far right of the bar
and choose Close Implicit. Alternately, you can choose Window | Close Implicit or use the
accelerator Ctrl-Shift-F4.
To close all editor windows at once, choose Window | Close All Editors.
21-32
Related topics

21-33
Edit Path Dialog
Use the Edit Path dialog to edit the paths used to locate resources, including classpaths,
additional classpaths, Java source paths, source paths, doc paths, and model paths.
The dialog displays the path entries that are currently defined for the context. You can change
the order of the paths in the list by selecting the path and using the up and down shuttle
buttons. The order in which the paths appear in the dialog signifies the order in which the
folders are searched.
Add Entry
Click to open a selection dialog, from which you select a path to add.
Remove
Click to remove the currently selected entry from the list. Removing entries from paths
can affect the way that JDeveloper locates resources.
Add URL
Optionally available in some dialogs. Click to add an arbitrary URL to be used as part of
the path. The URL will be searched as one of the path entries.
Related topics
About Project Paths

21-34
Edit Library Dialog
Use the Edit Library dialog to edit an existing library.
Library Name
Noneditable. Displays the name of the library to be edited.
Location
Noneditable. Displays the location of the library.
Class Path
Displays the classpath associated with that library. When this library is added to the
project, the entries here automatically become part of the project's classpath.
Source Path
Displays the source path associated with that library. When this library is added to the
project, the entries here automatically become part of the project's source path.
Doc Path
Displays the doc path associated with that library. When this library is added to the
project, the entries here automatically become part of the project's doc path.
Related topics
About Libraries
21-35
Export Connection Descriptors Dialog
Use the Export Connection Descriptors dialog to export connection descriptors from your
JDeveloper installation. Connection descriptors are global for your installation. Export
connections for other users to add to their installations.
File Name
Click Browse to bring up the Select File to Export dialog. In that dialog, select the file to
contain the connection descriptor(s) that you want to export, or type in a new filename.
Then click Save.
Connection descriptors are saved to xml files. The recommended file extension is .xml.
Connections
Contains a list of available connections. Select the connection descriptor(s) to export and
click OK. Select multiple connections by control-clicking or shift-clicking. The selected
connections are exported to the file.
Related topics
About Connections
21-36
Field Settings Dialog
Use the Fields Settings dialog to create and edit the fields of your class definition. You can also
use the dialog to create JavaBeans-compliant accessor methods for your fields or modify the
fields in an Enterprise JavaBean (EJB).
Field name
Enter the name of the field.
Field type
Select a type from the dropdown list or click Browse to locate an existing type in your
project's current path settings.
Modifiers
Specify the field's scope and additional modifiers.
Scope
Select the appropriate scope for the field. Default indicates that you are giving the field
package-level access. Normally you declare fields private and provide public accessor
methods to read and write their values.
final
Select to indicate a field which, after its original initialization, remains constant.
transient
Select to indicate a field which will not be serializable.
static
Select to indicate a field which will be shared across all instances of a class.
volatile
Select to indicate a field which will not use the synchronized mechanism, but which may
still be modified by concurrent threads.
Accessors
Select to add new accessor methods or to overwrite your class's existing getter and
setter methods for reading and writing field values. Use this option when you want to
define accessor methods that conform to the JavaBeans conventions for accessing
fields.
The Class Editor will:
❍ Overwrite the getter or setter you select with the new implementation only when
21-37
the original accessor method follows the JavaBeans convention
❍ Leave the original accessor method intact when it does not follow the JavaBeans
convention
If you deselect either the get() or set() checkboxes, the editor will remove the getter or setter
implementation from your class without adding a replacement accessor for the deselected
option. Deselect these options only when you want to delete particular accessor methods
from your class definition.
Create get() method

Select to add a method for reading the field value to your class.
Create set() method
Select to add a method for writing the field value to your class. When you specify a setter
for the class's field, you must also indicate how the potential field-value change should
be viewed by the users of the class.
You can specify:
■ A bound field to fire an event when the field is changed at runtime
This field type has a setter with a firePropertyChange() call. Components

can then register as event listeners to react to those changes.
■ A constrained field to fire a vetoable change event
Registered listeners can react to the change, verify the new value, and reject the
change if it doesn't meet the test criteria. Constrained fields are a more complex
form of bound fields: they have a setter with both a fireVetoableChange() call
and a firePropertyChange() call.
■ An unbound field when you do not want the outside world to react to the changed
field value
This simple field type is neither bound nor constrained: it has a standard method
for setting the field.
OK
21-38
Click to dismiss the Field Settings dialog, update the Declared Fields list on the Fields
page of the Class Editor with your field settings, insert the field declarations into your
class, and (optionally) insert accessors into your class. A dialog box warns you that the
editor will overwrite your field's accessor methods when:
❍ Your class defines getter and setter methods that conform to the JavaBeans
convention
and
❍ You selected Accessors
and
❍ You selected either get( ) or set( )
21-39
Find Text / Replace Text Dialog
Use the Find Text dialog to specify text to search for in the Code Editor, and the Replace Text
dialog to both search and replace.
Text to Search For

Enter a search string.
Replace With
Select to enable replacement and enter the string to replace the searched item with. The
Replace Text dialog appears with this item selected.
Options
Specifies the search criteria for this search.
Match Case
Select to perform a case-sensitive search.
Search from Beginning
Select to search the open file from its beginning.
Highlight All Occurrences
Select to highlight all occurrences of the search string in the file.
Wrap Around
Select to search from the cursor position past the end (if searching forward) or the
beginning (if searching backward) of the file, back to the cursor, covering the
entire contents of the file once.
Regular Expressions
Select to treat the text in the Search Text field as a regular expression.
Direction
Specifies in which direction you want to search, starting from the current cursor position.
Forward
Select to search from the current position to the end of the file. Forward is the
default Direction setting.
Backward
Select to search from the current position to the beginning of the file.
Scope
Determines how much of the file is searched.
21-40
Single
Select to replace a single occurrence of the search string only.
Prompted
Select to bring up a confirmation dialog which prompts you, for each occurrence of
the search string, whether it should be replaced or not.
Global
Select to search the entire file, in the direction specified by the Direction setting,
and replace to replace all occurrences without further prompting. Global is the
default scope setting.
Related topics
Regular Expressions
21-41
Generate Javadoc Dialog
Use the Generate Javadoc dialog to generate Javadoc for your projects.
Source package root

Select a package name from the dropdown list or click Browse to select the package root
with the Package Browser. The Javadoc for this package and all its subpackages will be
generated.
Destination path
Click Browse to select the directory for the generated Javadoc.
Additional parameters
Set any additional parameters for Javadoc. For a complete list of Javadoc options, see
Javadoc - the Java API Documentation Generator. In addition, you can specify JVM
options by placing a -J before the parameter. For example, to set the heap size to
128MB (-mx128m), add -J-mx128m to the parameter list.
Scope to document
Select which methods to run Javadoc on.
Generate
Select which optional Javadoc pieces to generate.
Hierarchy tree
Select to include the class/interface hierarchy from the generated docs. The
hierarchy is produced by default.
Index file
Select to include the index from the generated docs. The index is produced by
default.
Navigation bar
Select to generate the navigation bar, header and footer, otherwise found at the
top and bottom of the generated pages. Has no affect on the "bottom" option.
Deselect when you are interested only in the content and have no need for
navigation, such as when converting the files to PostScript or PDF for print only.
Tags
Select which optional tags to generate.
@deprecated
Select to generate documentation for the deprecated API. Deselect to suppress
the generation of documentation for any deprecated API, which is useful when you
21-42
are writing code and so do not want to be distracted by the deprecated code.
@version
Select to include the @version text in the generated docs. This text is omitted by
default.
@author
Select to include the @author text in the generated docs.
Related topics
Javadoc - the Java API Documentation Generator
21-43
Go to Line Number Dialog
Use the Go to Line Number dialog to go directly to a line of source code in the file you are
editing.
Line Number
Enter the line number you want to go to in the file open in the Code Editor.
The current line number is displayed when this dialog first opens.
21-44
HTML Converter Could Not Run
An unknown error prevented the HTML Converter from running. Possible causes include an
incorrectly installed HTML Converter jar file or incorrect permissions on the HTML root
directory.
21-45
HTML Converter Does Not Exist
The J2SE used by the current project does not have the HTML Converter installed. Please
download the appropriate HTML Converter for this version of the J2SE from Sun and install it
under the lib directory of the J2SE root directory as htmlconverter.jar.
21-46
HTML Root Directory Does Not Exist
The HTML Converter utility converts applet tags in HTML files located under the HTML Root
Directory of the current project. If this directory does not exist, the HTML converter cannot run.
21-47
Image Viewer
Use the Image Viewer to view .gif, .jpg, and .png files.
If the image is larger than the display area (in either dimension), then the image can be
scrolled. A status bar at the bottom of the viewer shows the width and height of the image.
21-48
Implement Interface Dialog
Use the Implement Interface dialog to add interface implementation to a class or to make an
existing interface extend other interfaces. When you exit the dialog, the interface or interfaces
are added to the implements clause of the selected class. The default implementations of any
methods defined by the interface are also added.
Class
Select the class you want to implement the interface for. This dropdown list contains all
top-level classes defined in the selected file. It does not include any inner classes.
Available Interfaces
The available interfaces are listed here. Click the icons in the left column to expand or
collapse the list of inherited interfaces. To choose an interface or interfaces, select as
many as you like (by holding down the Shift or Control key) and then click OK.
21-49
Import Connection Descriptors Dialog
Use the Import Connection Descriptors dialog to add connection descriptors to your JDeveloper
installation. Connection descriptors are global for your installation. Import connections from
other user's installations, or from other files created by exporting connections, to add those
connections to your installation.
File Name
Click Browse to display the Select File to Import dialog. In this dialog, select the file
containing the connection descriptor(s) that you want to import, and click Open.
Connection descriptors are saved to xml files. The recommended file extension is .xml.
You can import connections from previous versions of JDeveloper by importing

connections from IDEConnnections.properties in the earlier installation. You can
import connections from other versions of JDeveloper 9i by importing connections from
IDEConnnections.xml.
Connections
Contains a list of the available connections specified in the File Name field above. Select
the connection descriptor(s) to import and click OK. Select multiple connections by
control-clicking or shift-clicking. The selected connections are imported to your
installation.
Related topics
About Connections
21-50
Import Event Set Dialog
Use the Import Event Set dialog to locate and import an existing event set from your project's
classpath. You do this when the event set you want to register with your class does not already
appear on the Events page of the Class Editor.
Fully qualified EventListener class

Enter the name of the event listener class associated with the event set to be imported,
listing its package as well as its classname. You can also browse the package in your
classpath to locate the event-listener class.
The class you import must:
❍ Exist on your classpath

❍ Be a valid event-listener class
❍ Not already appear in the Events page of the Class Editor
After adding the new event set, you must select it on the Events page to add the
accompanying event-listener interface to your class.
Related topics

21-51
Invalid Classname
The classname you have entered is invalid. Review the conventions for naming Java classes, if
necessary. When assigning a classname in the New Class dialog, you need not append the
.java extension.
21-52
Load Preset Dialog
Use the Load Preset dialog to select preset keymappings.
Load Preset
Displays the available preset keymappings for you to select from.
Related topics
Classic Keymapping
Default Keymapping
Emacs Keymapping
21-53
Log Window
The Log window displays tabbed windows for specific feedback from the IDE, the Compiler, the
Runner, the Debugger, CodeCoach, and the Profiler. Additionally, the Compiler and
CodeCoach both report error messages that you can double-click to navigate directly to the
correct line in the source file referenced.
To clear the contents of the Log window, right-click either on the tab or within the window itself
and choose Clear.
To close the Log window, right-click either on the tab or within the window itself and choose
Close.
21-54
Method Settings Dialog
Use the Method Settings dialog to create and edit the methods of your class definition.
Method tab
Method name
Enter the name of the method.
Return type
Select a type from the dropdown list or click Browse to locate an existing type in your
project's current path settings.
Modifiers
Specify the method's scope and additional modifiers.
Parameters tab
Specify the method's individual parameters, including its name and datatype.
Click to add a new parameter to your method. Click in the Type and Name fields to
specify the datatype and parameter name.
Click to delete the currently highlighted parameter from your method settings.
or
Highlight a parameter definition and click the up or down arrows to change the sequence
in which the parameters appear in the method signature.
Throws tab
Specify any exceptions that your method throws.
Click to add a new exception to your method. Click in the Type field to specify a fully
qualified exception name.
21-55
Click to delete the currently highlighted exception from your method settings.
or
Highlight an exception definition and click the up or down arrows to change the sequence
in which the exception appears in the method signature.
OK
Click to dismiss the Method Settings dialog, update the Declared Methods list on the
Methods page of the Class Editor with your method settings, and insert the method
declarations into your class.
21-56
Move Classes Dialog
Use the Move Classes dialog to move selected Java classes into the same package. Files on
the current project's source path that are dependent on the selected classes are also updated.
Enter the new, fully-qualified, package name for the selected files.
21-57
New Application Project Wizard - Finish Page
Use the Finish page of the New Application Project Wizard to finalize and create your new
project.
When you exit the wizard, the new project will appear in the Navigator.
Related topics
21-58
New Application Project Wizard - Libraries Page
Use the Libraries page of the New Application Project Wizard to define libraries for your new
project.
J2SE Version
The J2SE used by your project. Select an existing J2SE from the dropdown list or click
Define to create a new one.
Available Libraries
Displays the libraries that are defined within JDeveloper, but not currently referenced by
the project. Use the shuttle buttons to the right to move libraries from this listing into the
Selected Libraries listing.
Selected Libraries
Displays the libraries currently referenced by the project. Use the shuttle buttons (to the
left) to move libraries from the Available Libraries listing into this listing. Use the reorder
buttons (to the right) to arrange the order of the libraries, which determines the order in
which JDeveloper locates resources. Libraries listed in red are currently referenced by
the project, but not defined within JDeveloper.
New
Click to create a new library and add it to the Selected Libraries listing.
Edit
Highlight a library in either the Available Libraries or Selected Libraries listings and click
to edit that library. If the library to be edited appears in red, the library will be created.
Delete
to delete that library.
Classpath
Displays the classpath for the library currently selected in either the Available Libraries
or Selected Libraries listings.
Related topics
About Libraries
About J2SEs
21-59
New Application Project Wizard - Location Page
Use the Location page of the New Application Project Wizard to name your project and define
its directory.
Directory Name
Enter a new directory name for the project or click Browse to select an existing one. By
default, the directory is placed in the work directory within the user home.
File Name
Enter a filename for your project, maintaining the .jpr file extension. By default, the
generic name Project is simply incremented. The name you supply here will identify
the project for you in the Navigator.
Related topics
About Projects
21-60
New Application Project Wizard - Paths Page
Use the Paths page of the New Application Project Wizard to define the paths for your new
project.
Default Package
The default package for this project. To change the default value, enter a new package
name.
Java Source Path
The path or paths to the Java source code (.java files) contained in your project. By
default, this is the src directory under the project file's directory. To change the default,
enter a new value or click Browse to display the Edit Project Source Path dialog, which
you can use to modify paths in, or add paths to, your list of root directories.
Output Directory
The directory where compiled .class files will be placed. To change the default, enter a
new value or click Browse to select an existing directory.
Related topics
About Projects
About Project Paths
21-61
New Application Project Wizard - Welcome Page
Use the New Application Project Wizard to create a new project containing an application.
when next you open the wizard.
Related topics
About Projects
21-62
New Class Dialog
Use the New Class dialog to create a Java class.
Name
Enter a name for your class. The name you enter here will become the filename for the
class.
Package
Displays the name of the package your class belongs to. Accept the default, enter a new
name, or click Browse to select a package in your existing class or source path.
Extends
Displays the name of the class that this class extends. By default, all Java classes
extend java.lang.Object. To select a different superclass from your existing class or
source path, click Browse.
Optional Attributes
Public
Select to make the class public. Classes that are not public can only be accessed from
within their own package.
Generate Default Constructor
Select to generate a simple constructor. A constructor is a method that is called when an
object of this class is instantiated with the new operator.
Generate Main Method
Select to generate a main method. To be runnable, a class must have this method.
Related topics
About Packages
21-63
New Configuration Dialog
Use the New Configuration dialog to create a new configuration. Once you create a new
configuration, it becomes the active configuration.
If you have arrived at this dialog from the Project Settings dialog, the new configuration applies
only to that project. If you have arrived at this dialog from the Default Project Settings dialog,
the new configuration applies to all subsequently created projects.
Name
Enter a unique name for the new configuration. Configuration names are case sensitive,
so Debug and debug would be perceived as two distinct names. Note that if you use a
lengthy name, the tree control will display with a horizontal scrollbar.
Copy from another configuration
Select to clone an already existing configuration. Deselect to create one from scratch.
When you deselect this option, you must provide an output directory for the newly
created configuration.
21-64
New Gallery
The New Gallery is the launching point for everything you need to create and work with projects
in JDeveloper. Use the New Gallery to create objects of any sort, from applications or classes
to JSPs and UML diagrams, and to set up and maintain your connections.
To use the New Gallery, select a category in the lefthand pane and double-click the new object
you wish to create in the righthand pane. Depending upon the object type, a new instance of it
appears in the Navigator under the appropriate node or a dialog or wizard opens in which you
will further define object attributes.
By category, here's what appears in the Gallery:
● Projects
● Objects
● Web objects
● Enterprise JavaBeans
● Beans
● Web services
● Database objects
● Connections
● Deployment profiles
● Business components
● BC4J JSP
● UIX JSP
● JClient objects
● UIX XML
● UML diagrams
Related topics

21-65
21-66
New Gallery - Beans Category
From the Beans category in the New Gallery you create new beans and the objects needed to
maintain those beans. All the objects in this category are available from any project node or its
children in the Navigator.
Bean
Opens the New Bean dialog, in which you assign a name and a package to your bean
and define the class it extends.
BeanInfo
Opens the New BeanInfo dialog, in which you create a BeanInfo for an associated bean.
In the dialog, you point the BeanInfo to the appropriate bean and tell it which package it
resides in and which class it extends. BeanInfo classes supersede the introspection that
an IDE automatically undertakes to publish bean properties to users of your bean.
Customizer
Opens the New Customizer dialog, in which you define a customizer for an associated
bean. In the dialog, you assign the customizer a name and a package and define which
class it extends. Customizers enable component designers to more easily edit complex
bean properties.
Event Set
Opens the Event Set dialog, in which you assemble the events for the new event set. In
the dialog, you name the event set, generate its associated event object and listener,
and define the events to be included in the set. Custom event sets are useful when your
beans need to fire events not supported by AWT and JFC event sets.
Oracle Forms Pluggable Java Component
Opens the New Oracle Forms Pluggable Java Component dialog, in which you specify
the UI components that you want to customize for use with Oracle Forms. In the dialog,
you choose which of the Forms UI components you want to customize and in which
package it should reside. You can choose from the standard Forms UI components or
you can access the Java Swing classes. JDeveloper generates the skeleton code for
you. All you have to do is add your own custom code to the file, describing the
functionality you want, and include the file to your Forms codebase.
Property Editor
Opens the Property Editor dialog, in which you define a property editor. In the dialog, you
name the editor, define its type, and provide a list of the property values that it supports.
Property Editors are useful when you want to provide a standard way for component
designers to update and display the property values of a specific property type. For more
complex beans, consider supplying a customizer instead.
21-67
Enterprise JavaBean
Launches the Enterprise JavaBean Wizard. Complete the wizard to add a customized
EJB .java file to your project. Use the Code Editor to develop your EJB class.
Related topics
About JavaBeans
About Introspecting a Bean
About Customizers
21-68
New Gallery - Connections Category
From the Connections category in the New Gallery you create new connections to use in
JDeveloper. Database, Application Server, Oracle9i SCM, and WebDAV Connections are
available from any node in the Navigator. SOAP Server Connections are available from any
project node or its children in the Navigator.
Application Server Connection

Launches the Connection Wizard, in which you create a new application server
connection. Oracle9i JDeveloper supports deployment of your J2EE applications to these
application servers: Oracle9iAS Containers for J2EE (OC4J) and BEA WebLogic 6.x.
Database Connection
Launches the Connection Wizard, in which, from this selection, you create a connection
to a database. To define a database connection you must enter a display name,
connection type, authentication details, and location details for the database.
SOAP Server Connection
Launches the SOAP Server Connection Wizard, in which you create a connection to
either an Oracle9iAS SOAP server or an Apache V2.x SOAP server. This connection can
then be used to browse the registered services on that SOAP server and to
register/unregister additional services.
Oracle9i SCM Connection
Launches the Oracle9i SCM Connection Wizard, in which you create a connection to an
Oracle9i SCM repository, on which you can then perform source control operations.
Oracle9i SCM connections can only be created if the Active Source Control Addin has
been set to "Oracle9i SCM" on the Source Control page of JDeveloper's Preferences
dialog.
WebDAV Connection
Launches the WebDAV Connection Wizard, in which you create a connection to a
WebDAV-enabled server. WebDAV connections can only be created in JDeveloper if the
WebDAV addin has been installed. For more information on downloading this addin,
refer to the "Enabling WebDAV Support in JDeveloper" section of the Installing Oracle9i
JDeveloper document for your operating system.
Related topics
About Connections
21-69
Specifying Connection Information to Oracle9iAS
Specifying Connection Information to BEA WebLogic
Using Oracle9i Software Configuration Manager (SCM) With JDeveloper
Using WebDAV Support in JDeveloper
21-70
New Gallery - Projects Category
From the Projects category in the New Gallery you create new workspaces and projects.
You can create a new workspace from any node, or any file contained within a node, in the
Navigator. The new workspace is automatically added to the Workspaces node.
You can create new projects from any workspace or project node, or from any of the file nodes
governed by a project. The new project becomes the child of a selected workspace node. It
becomes the sibling of a project either whose node or contained files are selected.
Workspace
Opens the New Workspace dialog, in which you define a directory and workspace
(.jws) filename for a new workspace. You can also choose to create this workspace
with a new empty project automatically added.
Empty Project
Opens the New Project dialog, in which you define a directory and project (.jpr)
filename for a new empty project. Define project attributes using the Project Settings
dialog.
Project from Existing Source
Launches the New Project from Existing Source Wizard, with which you import your
source files and fully define project attributes for the new project. The wizard is not
reentrant. To alter project attributes later, use the Project Settings dialog.
Project with Web Module
Launches the New Project from Web Module Wizard, with which you locate the
document root directory to import your existing source files and fully defined project
attributes for the new project. In JDeveloper the default document root is the
public.html folder in the projects directory of a workspace. The wizard is not
reentrant. To alter project attributes later, use the Project Settings dialog.
Project from Existing WAR
Launches the New Project from WAR File Wizard, with which you locate a Web Module
Archive (WAR) file to import your existing source files and fully defined project attributes
for the new project. The wizard is not reentrant. To alter project attributes later, use the
Project Settings dialog.
Application Project
Launches the New Application Project Wizard, with which you define the project
attributes necessary to create a new application. When you exit the wizard, the New
21-71
Application Dialog is invoked.
Project Configured for Remote Debugging and Profiling
Launches the Remote Debugging and Profiling Project Wizard, which guides you in the
creation of a new project for remote debugging and profiling. This wizard is intended for
those users who want to use the remote debugging and profiling features in Oracle9i
JDeveloper but who don't want to build or run their projects from within JDeveloper.
Project with Business Components
Launches a wizard that helps you create a new business components project. You need
a business components project if you want to use Business Components for Java to
produce n-tiered applications.
Related topics
About Workspaces
About Projects
21-72
New J2SE Dialog
Use the New J2SE dialog to define a new J2SE. This J2SE definition will then be available to
all projects opened within JDeveloper.
J2SE Name
Enter a unique name for the J2SE. The name is used only an an identifier. Select its
location from the dropdown list to the right.
Location
Select a location for the library from the dropdown list.
J2SE Executable
Enter the executable associated with the installed J2SE or browse for its location. For
more information, consult your J2SE documentation. When this value is entered, the
following three fields automatically display the default values for the paths associated
with the executable.
Class Path
Displays the classpath associated with the J2SE executable. Click Edit to add additional
entries. It is not recommended that you remove entries.
Source Path
Displays the source path associated with the J2SE executable. Click Edit to add
additional entries. It is not recommended that you remove entries.
Doc Path
Displays the doc path associated with the J2SE executable. Click Edit to add additional
entries. It is not recommended that you remove entries.
Related topics
About J2SEs
21-73
New Layout Dialog
Use the New Layout dialog to assign a name to a new layout design.
Layout Name
Enter a descriptive name for the new custom layout.
21-74
New Library Dialog
Use the New Library dialog to create a new library, or named collection of paths. Any library
that you create here will be available to all projects.
Library Name
Enter a name for your new library. Choose a name that reflects the nature of its contents.
Location
Select a location for the library from the dropdown list.
Class Path
Enter the classpath for the new library. When this library is added to the project, the
entries here automatically become part of the project's classpath.
Source Path
Enter the source path for the new library. When this library is added to the project, the
entries here automatically become part of the project's source path.
Doc Path
Enter the doc path for the new library. When this library is added to the project, the
entries here automatically become part of the project's doc path.
Related topics
About Libraries
21-75
New Palette Page Dialog
Use the New Palette Page dialog to add a new page to the Component Palette.
Page Name
Enter a name for the new Palette page.
Page Type
Select the page type from the dropdown list. The Component Palette is sensitive to
context and will display only those pages which are relevant to the file types currently
active in the Code Editor.
21-76
New Project Dialog
Use the New Project dialog to create a new empty project within the currently selected
workspace. The newly created project inherits the default project properties.
Directory Name
By default, the directory that JDeveloper creates to store your projects appears. To store
the files outside of JDeveloper's directory structure, or to redefine what the project
directory is called, enter your changes. To navigate to a location rather than typing it,
click Browse.
File Name
By default, the project filename that JDeveloper creates appears. To rename this file,
enter your changes. Do not change the .jpr extension.
Related topics

Setting Project Properties for Individual Projects
21-77
New Project from Existing Source Wizard - Add
Source Files and Directories Page
Use the Add Source page of the New Project from Existing Source Wizard to locate your
source files and to define a directory for compiled files.
Files to Add to Project

Displays the files to be added, once you have selected them. Click Add Files to locate
source files and then return to this dialog. You can further refine your file list here by
deleting files.
Add
Click to browse for existing source files and to list those files in this dialog. You can add
as many files as you want, using the button multiple times, to put together a list from as
many locations as you would like.
Remove
Click to remove selected files in the Files to Add to Project listing.
Related topics
About Projects
21-78
New Project from Existing Source Wizard - Finish
Page
Use the Finish page of the New Project from Existing Source Wizard to finalize and create your
new project.
When you exit the wizard, the new project will appear in the Navigator.
Related topics
21-79
New Project from Existing Source Wizard - Location
Page
Use the Location page of the New Project from Existing Source Wizard to name your project
and define its directory.
Directory Name
File Name
Related topics
About Projects
21-80
New Project from Existing Source Wizard - Run
Settings Page
Use the Run Settings page of the New Project from Existing Source Wizard to specify how your
project will run.
Set Classpath Directly

Select this option and then either type in the classpath as you would on the command
line or click Browse to retrieve it. Select this option to work with a classpath as you would
when writing an application outside an IDE.
Create Library for Classpath
Noneditable. Displays the name of the library created after you click Create Library and
complete the New Library dialog. Select this option to work with libraries (named
collections of classpaths, source paths, and documentation paths for a project) rather
than editing the classpath directly. When a library is added to a project, the classpath
defined in the library is added to the classpath for the project when you run your code
from JDeveloper.
Create Library
Click to open the New Library dialog, in which you create a new library for a project.
Default Run Target
The dropdown list contains all the files in your project which may be possible run targets.
A run target can be a Java application, a Java servlet, a Java Server Page (JSP), an
HTML file, an XSQL file, a UIX file, or a JDeveloper-related file addin. Choose the default
run target for this project from the dropdown list, or click Browse to locate a run target
outside of your project. The default run target does not have to be a file contained in the
project. For example, you may be working in a workspace with multiple projects, where
each project is just part of a large program. You may set the default run target for each of
the projects to be a specific Java class which is contained in only one of the projects.
Attempt to Run Active File Before Default
By default, the Runner runs the project's specified default run target, which is also set in
this panel.
If this option is selected, then the Runner attempts to run the current node in the active
view. For example, if the Navigator is active, the Runner will run the selected node in the
Navigator. Likewise, if the Code Editor is active, the Runner will run the current file in the
Code Editor. If the file is not runnable, the Runner attempts to run the project's specified
default run target.
21-81
Related topics
About Project
About Libraries
21-82
New Project from Existing Source Wizard - Source
Paths Page
Use the Source Paths page of the New Project from Existing Source Wizard to locate your
source files and to define a directory for compiled files.
Output Directory
The directory where compiled .class files for the project will be placed. Your source
files can reside in multiple locations, but all compiled files will be placed in one directory.
Note that the value of this field becomes the first element of the project classpath.
Accept the default value, enter a new value, or click Browse to select a location from the
directories available to your JDeveloper environment.
HTML Root
The path to the directory where all your HTML or HTML-based files will be stored. This
directory should contain everything that needs to be accessible to the design time web
server. If left blank, this field's value is assumed to be the public.html directory in the
project directory.
Enter a value or click Browse to select a location from the directories available to your
JDeveloper environment.
Related topics
About Projects
21-83
New Project from Existing Source Wizard -
Welcome Page
Use the New Project from Existing Source Wizard to create a new project composed entirely of
source files you import into it. To add source files to an existing project, use either the Open or
Create a File dialog or the Add to Project dialog.
when next you open the wizard.
Related topics
About Projects
21-84
New Project from WAR File Wizard - Location Page
Use the Location page of the New Project from WAR File Wizard to name your project and
define its directory.
Directory Name
File Name
Related topics
About Projects
21-85
New Project from WAR File Wizard - WAR Location
Page
Use the WAR Location page of the New Project from WAR File Wizard to specify the WAR file
and its root directory.
Specify a WAR File to Create Project From

Enter the directory name for the WAR or click Browse to locate it.
Specify the Root Directory for the Web Module
Enter the document root of your web module or click Browse to locate it.
Related topics
About Projects
21-86
New Project from WAR File Wizard - Finish Page
Use the Finish page of the New Project from WAR File Wizard to finalize and create your new
project.
When you exit the wizard, the new project with existing files from the specified WAR will appear
in the Navigator.
Related topics
21-87
New Workspace Dialog
Use the New Workspace dialog to create a new workspace node within JDeveloper.
Directory Name
By default, the directory that JDeveloper creates to store your projects appears. To store
the files outside of JDeveloper's directory structure, or to redefine what the workspace
directory is called, enter your changes. To navigate to a location rather than typing it,
click Browse.
File Name
By default, the workspace filename that JDeveloper creates appears. To rename this file,
enter your changes. Do not change the .jws extension.
Add a New Empty Project
Select to automatically add a new empty project to your workspace. The New Project
dialog will appear when you exit this dialog.
Open in New Navigator
Select to open this workspace in a new custom navigator, with the new workspace as the
root node.
Related topics
21-88
Open or Create a File Dialog
Add Files or Directories to Workspaces Dialog
Add Files or Directories to Workspace Dialog
Add Files or Directories to Project Dialog
Use the Open or Create a File dialog to add existing files to a JDeveloper project, while
maintaining their original file structure. You can also use the Open or Create a File dialog to
bring files into the JDeveloper IDE without adding them to a project, simply for the convenience
of having them handy to browse while you work.
The three "Add to" dialogs function the same, consistent with the context of the focus in the
Navigator or the Code Editor. Use these dialogs to add:
● A .jws file to the top-level Workspaces node

● A .jpr file to an individual workspace node
● Individual files or the contents of an entire directory, while maintaining the original file
structure
The only distinction between the Open or Create a File dialog and the "Add to" dialogs is the
Add to project checkbox, which appears in the Open or Create a File dialog when a project
node or any of its children were first selected in the Navigator. In the Open or Create a File
dialog you are given a choice: to open files outside the project, or to add files to a project.
Navigating the Open or "Add to" dialogs
To use any of these dialogs, navigate through the directory tree using the dropdown listing at
the top and the display area just below. These dialogs are sensitive to context. When you first
invoke one, it will open to the directory in which the node currently selected in the Navigator (or
the active navigator) resides. If the focus is instead on a file open in the Code Editor, the dialog
will open to the directory in which that file resides.
Browsing vs. Opening or Adding Directories
Double-click a directory to open it in the display and continue browsing. Select a directory and
click Open to open or add it within whatever context you are working. Double-click a file to
dismiss the dialog and open or add the file.
21-89
Selecting Directory Contents
If you select a directory, the Directory Options dialog appears in which you can define specific
file types to be opened or added, if you wish, and choose whether or not to recurse
subdirectories.
Selecting Archive Files
Archive files are displayed twice: once as a virtual directory and again as a file. When you
select the directory to be opened or added, the Directory Options dialog appears. When you
select the file, the archive file is brought into your context intact. You can display its contents in
the archive viewer.
Dialog Controls
Location
Noneditable. Displays the current directory path, based upon the node selected in the
currently active navigator or the file active in the Code Editor. Contents of the directory
appear in the display below. Navigate directories by selecting from the dropdown list in
this field or by clicking in the display of directory contents.
Click to jump to the location of the .jpr file for the currently selected project.
Click to jump to the location of the .jws file for the currently selected workspace.
Click to jump to JDeveloper's home location.

File name
Enter a name to narrow your search or click through the directory tree instead.
File type
Describes the type of file to be displayed. Select the appropriate type from the dropdown
list.
Add to project <project name>
Appears only in the Open or Create a File dialog, once a project or any of its children
21-90
have been selected.
Select to add the files indicated in the dialog to the current project. Deselect to open
those files for browsing, but not to add them to a project. Opened files are grouped under
a new node named Miscellaneous Files, which appears as the last node in the
Navigator.
Note that if .jws or .jpr files are selected, they are automatically added to either the
top-level Workspaces node (for the .jws file) or the currently selected workspace node
(for the .jpr file), whether or not the Add to project checkbox is selected.
Related topics
About Workspaces
About Projects
21-91
Override Methods Dialog
Use the Override Methods dialog to override inherited methods for a given class.
Class
Select the class for which you want to override methods. This dropdown list contains all
top-level classes defined in the selected file. It does not include any inner classes.
Inherited methods
The superclass hierarchy and the inherited methods from each superclass appear here.
To choose a method or methods, select as many as you like and then click OK.
21-92
Preferences Dialog - Accelerators Page
Use the Accelerators page of the Preferences dialog to fine-tune your selected keymapping.
Begin by selecting a preset keymapping. Then make any changes to those accelerators that
you would like to further customize the keymap for your own use.
Category
Select an area of JDeveloper from the dropdown list. The listing under Actions changes
in response to this selection.
Actions
Displays the actions available in the area of JDeveloper selected in Category. To view
the assignment for
Accelerators
Displays the currently defined accelerator or accelerators for the action selected under
Actions.
New Accelerator
The field in which you define your own custom accelerators or discover the current
assignment of an accelerator.
To investigate the possibility of adding a new accelerator, select the action in the Actions
list that you wish to define the accelerator for and then enter the new accelerator. To
enter the accelerator, press the appropriate keys on the keyboard. If this proposed
accelerator is already assigned to another action, that action will be displayed in the field
just below.
If you would like to assign this accelerator you have just entered to the action selected,
click Add. You can assign this accelerator to the selected action even if it is already
defined for another action. If you reassign it, however, its previous assignment is
removed. When added, the new accelerator will appear in the Accelerators listing above.
No other unrelated accelerators in the keymap are affected by the individual accelerators
you customize. The only time a previously existing accelerator is affected is if you
reassign an accelerator to a new action. The previous action will be left without an
accelerator, unless you in turn assign a new accelerator to it.
To discover whether an accelerator is defined within the keymap currently in effect (and if
it is defined, to which command), select All in the Category list and About in the Actions
list and then enter the accelerator. If it is assigned in the current keymap, the command it
is assigned to will appear in the Currently Assigned To field.
21-93
Currently Assigned To
Displays the action, if any, currently assigned to the accelerator entered in New
Accelerator.
Remove
Click to remove the accelerator selected in the Accelerators listing.
Add
Click to add the new accelerator to the Accelerators listing for the selected action.
Load Preset
Click to select a base keymapping, which you can then refine, if you wish, in this dialog.
If you reload a preset keymap, any changes you have made are no longer in effect.
Related topics
Classic Keymapping
Default Keymapping
Emacs Keymapping
21-94
Preferences Dialog - Code Insight Page
Use the Code Insight page of the Preferences dialog to configure Code Insight.
JDeveloper's Code Insight assists you with logical completion while you are coding. Currently,
Code Insight is available for Java, HTML, JSP, and for schema-based XML. Java Code Insight
helps the user to type class or member names (completion insight) or to type function
parameters (parameter insight).
Enable Auto-Popup for Completion Insight

Select to enable completion insight. Slide the bar below to set the delay (in seconds)
before the auto-popup insight window appears.
Different languages have different auto-triggers for completion insight. Java uses a
period (.) and HTML and XML use the right-angle bracket (<). When you type the
appropriate auto-trigger character, Code Insight will automatically bring up the
completion insight window after the specified delay as long as you have not performed
any subsequent edits or navigations in the editor.
When this option is deselected, you can still prompt completion insight to appear by
pressing Ctrl-Space (Alt-Space in the Emacs keymap).
Enable Auto-Popup for Parameter Insight

Select to enable parameter insight. Slide the bar below to set the delay (in seconds)
before the insight window appears.
Different languages have different trigger characters. Java uses a period (.) and HTML
and XML use a space. When you type the trigger, parameter assistance is displayed as
a tooltip.
When this option is deselected, you can force parameter insight to appear by pressing
Ctrl-Shift-Space (Alt-Shift-Space in the Emacs keymap).
Related topics
The Code Editor

About Code Insight
21-95
Preferences Dialog - Code Style Page
Use the Code Style page to set preferences for standard code fragments that the JDeveloper
IDE creates for you using wizards or when interacting with visual editors such as the UI Editor.
Event Handling
Anonymous Inner Classes
Select to use anonymous inner classes, rather than a standard adapter, for the
event methods that JDeveloper generates for you.
Standard Adapter
Select to use a standard adapter, rather than anonymous inner classes, for the
event methods that JDeveloper generates for you.
Match Existing Code
Select to match whichever event style is already in place.
Brace Style
Same Line
Select to use the code style that places opening braces on the same line as the
governing code.
Next Line
Select to use the code style that places opening braces on the line following the
governing code.
Example
Noneditable. Displays sample code reflecting your choices for event handling and brace
style.
Default Member Scope
Select the scope to apply to new data members created from the Palette.
Use Beans.instantiate
Select this option to use the Beans.instantiate method, rather than a direct call to
the JavaBean class, when you add a JavaBeans component to your UI. You can use this
method to instantiate all of your JavaBeans components, but it is especially useful if you
are using JavaBean serialization in your programs.
21-96
Preferences Dialog - Code Templates Page
Use the Code Templates page of the Preferences Dialog to edit existing code templates for the
Code Editor or to define your own.
Add
Click to add a new template to the listing. The cursor jumps into the current listing at the
end, in preparation for your adding a new template.
Delete
Click to delete the currently selected template.
Shortcut
Displays the keyword associated with a given template and potential imports, defined
below. You can add new shortcuts, as well as edit existing ones.
Once you return to the Code Editor, to use code completion you will type the shortcut
and then press the accelerator defined (in the default keymap, Ctrl-Enter) to evoke the
template code and any associated imports.
Description
Displays an identifying description for the shortcut selected at left.
Code
Displays the template code associated with the shortcut selected above. Enter code for
new shortcuts, or edit the existing code for previously defined shortcuts.
Before saving a template, be sure to place the cursor at the logical insertion point for the
code in question. This cursor position is remembered in the template and so becomes
part of how you will use that template.
Imports
Displays the imports associated with template. Enter the appropriate imports for any
newly defined template code. When the template is invoked, these imports are
automatically added to the source, unless they already appear.
21-97
Preferences Dialog - Display Page
Use the Display page of the Preferences dialog to set the general display features for the Code
Editor.
Right Margin Settings

Show Visible Right Margin
Select to render the right margin (gray line) visible in the Code Editor. The visible
right margin generally is used to keep lines short, so that they can print more
easily without having lines wrap or be truncated.
Right Margin Column
Enter a setting to determine at which column the right margin, when visible,
displays.
Show Line Numbers

Select to display line numbers in the line gutter to the left of the code in the Code Editor.
21-98
Preferences Dialog - Documentation Page
Use the Documentation page of the Preferences dialog to determine whether JDeveloper uses
local or hosted documentation.
Use Local Documentation

Select this option to use JDeveloper documentation from your file system. Local
documentation is the fastest, but it requires you to maintain local documents on your
system.
Use Hosted Documentation
Select this option to use JDeveloper documentation hosted by Oracle. This
documentation will be updated regularly, and if you use it, you will not need to maintain
documentation on your drive (you can delete the jdeveloper/doc directory on your
system). However, it takes some time to start up hosted documentation for the first time
in each JDeveloper session.
Warning: Using hosted documentation with a 56K connection or slower is not

recommended.
21-99
Preferences Dialog - Editor Page
The Editor page of the Preferences dialog, and all the pages it governs, direct the behavior of
the Code Editor. Some options control its editing behavior. Others affect the font or colors it
employs to display document content.
Use the Editor page of the Preferences dialog to define general tab and navigation settings for
the Code Editor.
Tab Settings
Tab Size
Enter a tab size or accept the default (2). The tab size determines the number of
columns (spaces) that a tab character occupies. It also determines the number of
spaces that are added when Use spaces for Tabs is selected on this page and
you press the Tab key. The tab size is the same size used by a block indent or
block outdent operation.
Use Spaces for Tabs
Select to specify that space characters, rather than tab characters, be used for tab
settings when you press the Tab key.
Auto-Indent New Lines
Select to direct the editor to autoindent a new line when you press Enter at the
end of a line. The new line will automatically be indented at the same initial
indentation as the line preceding it.
Perform Block Indent or Outdent for Selections
Select to direct the editor to perform a block indent or block outdent on a selection
when your press Tab or shift-Tab respectively. With this option selected, when you
press Tab on a selected block of text, the entire block will be indented to the
current tab size. Shift-Tab on the same block would outdent it, as a block, to the
current tab size.
Miscellaneous Settings
Use Smart Home
Select to contextualize the cursor's understanding of home (the beginning of the
line).
With this setting selected, pressing Home positions the cursor at the start of the
line after any leading spaces or tabs. Pressing Home again repositions the cursor
at the start of the line before any leading spaces or tabs. Continuing to press
21-100
Home toggles the cursor between these two locations.
With this setting deselected, pressing Home simply places the cursor at the start of
the line.
Use Smart End

Select to contextualize the cursor's understanding of end of line.
The behavior is analogous to that for smart home, except that the cursor responds
to the End key, and its behavior regarding the end of the line and any trailing
spaces is altered.
Use Jump Scrolling for Keyboard Navigation

Select to implement jump scrolling, which involves behavior of the keyboard arrow
keys.
With this setting selected, when you navigate offscreen using the keyboard arrow
keys, the editor view will "jump" to recenter the cursor location in the middle of the
editor view.
With this setting deselected, the editor view will scroll the editor view the minimum
amount to bring the cursor back into view.
Use Line Start for Next or Previous Word Operations Boundary

Select to define the beginning of the line as the boundary for all next or previous
word operations.
For example, with this setting selected, if you navigate forward using next word
(generally Ctrl-Right), the editor will include the beginning of a line as a word
boundary to stop at.
Use Line End for Next or Previous Word Operations Boundary
Select to define the end of the line as the boundary for all next or previous word
operations.
21-101
Preferences Dialog - Environment Page
Use the Environment page of the Preferences dialog to set JDeveloper's default display
options.
Show Splash Screen at Startup

Select to enable the display of the splash screen when you start JDeveloper.
Save Before Compile
Select to enable automatic save of your files whenever you compile.
Automatically Reload Externally Modified Files
Select to instruct JDeveloper to check for externally modified files whenever you switch
from another application back to JDeveloper. You may find this option particularly useful
if you are using an external code editor. With both the automatic reload and the silently
reload options enabled, JDeveloper remains synchronized with any changes made in the
external editor.
With the automatic reload option disabled:
❍ The advantage is that you eliminate any risk of overwriting changes that you make
in JDeveloper with changes made external to JDeveloper.
❍ The disadvantage is that, by contrast, any changes you make in JDeveloper have
the potential for overwriting externally applied changes.
With the automatic reload option enabled:
❍ The advantage is that files modified outside of JDeveloper are kept in sync with
JDeveloper's buffer.
❍ The disadvantage is that this synchronization can overwrite work you have done in
JDeveloper if both an external change and a change within JDeveloper were
made before the automatic reload behavior was triggered.
Silently Reload When Buffer Is Unmodified

Select or deselect to modify the automatic reload option accordingly.
Deselect to instruct JDeveloper, before it automatically reloads, to prompt you with

a complete list of externally modified files.
21-102
Select to instruct JDeveloper, before it automatically reloads, to prompt you with a
list of externally modified files that omits those files not modified within JDeveloper
since last being saved. Selecting this option is tantamount to indicating "Yes to all"
for the unmodified buffers. When a file has been both modified externally and
modified within JDeveloper, however, you will always be prompted.
Undo Level
Enter a number that determines the number of undo operations JDeveloper will
remember.
Look and Feel
Select a look and feel from the dropdown list. The new look and feel will be reflected in
the IDE once you restart JDeveloper.
Related topics
Customizing the IDE
21-103
Preferences Dialog - Fonts Page
Use the Fonts page of the Preferences dialog to set the fonts for the Code Editor.
Font Name
Select the name of the font from the dropdown list. By default, JDeveloper will show all
system fonts here. To limit the selection to fixed-width fonts, select the Display Only
Fixed-Width Fonts checkbox below.
Font Size
Select the font size.
Sample Text
Type in sample text for display in the field below.
Sample text in selected font and size
Noneditable. The text you typed in above appears here in the font style and size you
selected.
Display Only Fixed-Width Fonts
Select to limit the fonts available in this dialog page to fixed-width fonts. If you select this
checkbox, the first time you do, JDeveloper will run a check on your system fonts to
detect which ones are fixed-width fonts. Once it has finished, the selections available
under Font Name will change accordingly.
This system check is required only once. Subsequently, if you deselect or select this
checkbox, the fonts displayed under Font Name toggle between all fonts and fixed-width
fonts.
21-104
Preferences Dialog - Layouts Page
Use the Layouts page of the Preferences dialog either to manage the layouts provided with
JDeveloper or with specific addins or to customize your own.
Before you can alter a layout for an editor in Design mode, that editor must be open and have
focus.
Use Editor's Preferred Layout

Select to request that editors in Design mode override any layout settings that may
already be current in favor of their own preferred settings, where those settings exist. An
editor (such as the Code Editor) that does not have a preferred layout opens in the
generic Design mode. Deselect to request that editors respect whatever layout you are
already working in when you open them.
When this checkbox is selected, in other words, each new editor that you open has the
potential for declaring its own layout, and the work area alters accordingly. When it is
deselected, no change will appear in your work area, no matter how many different types
of editors you open. This option pertains only to editors in Design mode.
Once you select this option, the checkbox below becomes available to you.
Use Active Layout As Current Editor Preferred Layout

Only available when the checkbox above is selected. Select this option to redefine the
preferred layout for the editor which currently has focus. Do not select this option if you
wish the editor instead to use its originally provided preferred layout.
If you select and then later deselect this option, the last layout activated is remembered
but not called when the editor is opened.
Available Layouts
Displays the layouts currently defined for Design and Debug modes. In Design mode,
layouts can be associated with editors, each editor potentially having its own active
layout. In Debug mode, you can define as many layouts as you like, but only one can be
active at a time.
New
Click to create a new layout. You will design that layout when you return to JDeveloper. If
you subsequently make changes to the layout (moving a window, for instance) while
working, those changes are remembered as being a feature of the layout design.
21-105
Activate
Click to activate the layout selected in Available layouts. In Design mode, an activated
layout is the layout an individual editor will use as its preferred layout. To enable the
activated layout for the current editor, you must select both checkboxes at the top of the
page. In Debug mode, an activated layout is the layout currently defined for any work to
be done in this mode.
Currently activated layouts appear in bold. When the selection rests on an activated
layout, the Activate button is disabled.
The active layout is distinct from whichever current layout you may be using. The current
layout appears in reverse highlighting.
Rename
Click to rename the selected custom layout. You cannot rename JDeveloper's default
layouts.
Delete
Click to delete the selected custom layout. Deletion is immediate. To "undo" a deletion,
click Cancel rather than OK to dismiss the dialog. You cannot delete JDeveloper's default
layouts.
Related topics
About Layouts
21-106
Preferences Dialog - Syntax Colors Page
Use the Syntax Colors page of the Preferences dialog to control the colors and font style used
by the Code Editor.
Category
Select a language category of JDeveloper from the dropdown list. The listing under
Available Styles changes in response to this selection.
Available Styles
Select the element you wish to modify from the list of styles available for the selected
language category. Then use the other controls on the page to configure how the
selected style is displayed.
Note that the style Default plain text is special. It is the root of all styles, and controls the
background color used by the editor. If you change the background color of this style, the
background color used by the editor will be changed as well.
Style Sample
Type in sample text (or accept the default) to view the currently defined font style and
foreground and background colors.
Font Style
Select a font style to be applied to the element style currently selected in the Available
Styles list. Select Use default to instruct the editor to select a default appropriate for the
style. Selecting this option for the Java keyword style, for instance, means that the editor
will apply the font style currently defined for Default keyword, which you can also
customize.
Foreground
Select Use Default to use the default color displayed to the right or select Specify Color
and select the color by clicking on the color button to the right. The selected color is
shown in the color panel.
Background
Select Use Default to use the default color displayed to the right or select Specify Color
and select the color by clicking on the color button to the right. The selected color is
shown in the color panel.
Editor Sample
Noneditable. Displays sample text based on the language category selected and on the
current settings for all styles.
21-107
Scheme
A scheme is a collection of all the settings for all available styles saved under an
identifying name. To activate a scheme for the Code Editor, select it from this dropdown
list. The list contains all the initial schemes bundled with JDeveloper and any custom
schemes that you create. All initial schemes are editable. To make changes to any
previously existing scheme, select it first. To create a new scheme based upon an
existing scheme, select it first. You will always start with some scheme selected, even if it
is just Default.
As soon as you begin making changes to settings on this page, the current selection in
the Scheme listing goes blank, indicating that you have modified an existing scheme and
that those settings are not currently saved under a particular scheme. Likewise, if you
delete a scheme, the current selection in this listing goes blank, indicating that the
settings that once constituted the recently deleted scheme are not currently saved as a
scheme.
Save As
Click to save all the changes you have made, to the settings for any style, under a new
or already existing scheme name. To create a new scheme, assign a new name. To edit
an existing scheme, assign the same name. Once you have dismissed the name dialog,
a newly defined scheme appears immediately in the Scheme listing. A newly edited
scheme reflects its changes.
All the changes you have made, from the first change until the moment you click Save
As, are reflected in the new or edited scheme.
Delete
Click to delete the currently selected scheme in the Scheme listing. Deletion is
immediate.
OK
Click to accept the new or edited settings, or to switch between schemes. Whatever style
setting is currently selected in the Scheme listing will now be applied to all open Code
Editor windows.
21-108
Preferences Dialog - Undo Behavior Page
Use the Undo Behavior page of the Preferences dialog to set the undo behavior for the Code
Editor.
Consecutive Edits of the Same Type to Combine into One Undo

Use the slide bar to set the number of consecutive edits of a given type that will be
considered one undo action.
The definition of an edit "of the same type" is precise: typing (inserting) a character in
insert mode and typing (replacing) a character in replace mode are considered to be two
different edit types. JDeveloper's undo behavior only allows merges for the same edit
type.
The number you set here is applied in this fashion. With the merge count set to 10 in this
field and Combine Typed Insert Edits in Insert Mode selected, if you type 7 characters in
a row, choosing Edit | Undo will undo all 7 characters. If you type 12 characters in a row,
however, choosing Edit | Undo the first time will undo 2 characters, and choosing it again
will undo the 10 characters before it.
Combine Typed Insert Edits in Insert Mode

Select to allow merges of typed inserts (normal typing in insert mode.)
Combine Typed Replace Edits in Overwrite Mode
Select to allow merges of typed replaces (normal typing in replace/overwrite mode).
Combine Delete Next Character Edits
Select to allow merges of delete next character edits performed with the Delete key.
Combine Delete Previous Character Edits
Select to allow merges of delete previous character edits performed with the Backspace
key.
Allow Navigation-Only Changes to Be Undoable
Select to allow changes involving navigation only with the keyboard or mouse to be
undone.
Consecutive Navigations to Combine into One Undo
Use the slide bar to set the number of consecutive navigations of a given type that will be
considered one undo action.
21-109
Project Settings Dialog - Common Page
Related topics
Links here
21-110
Project Settings Dialog - Configurations Page
Use the Configurations page of the Project Settings dialog to manage configurations. You can
set the active configuration and create, delete, or rename configurations from this page.
From the Project Settings dialog, you will be setting properties for an individual project. From the
Default Project Settings dialog, you will be setting properties for all subsequently created projects.
Active Configuration
Select the configuration to make active from the dropdown list. The currently active
configuration is displayed in this list and appears in bold in the tree view to the left. When
a configuration is active, its settings will be used when you compile, build,
run or debug.
New
Click to add a new configuration. When you create a new configuration, it becomes the
active configuration.
Delete
Click to delete the selected configuration. When you delete a configuration, the next
configuration in the list becomes the active configuration.
JDeveloper requires at least one configuration. If only one configuration exists, this
button is disabled.
Rename
Click to rename the selected configuration. When you rename a configuration, it
becomes the active configuration.
21-111
Project Settings Dialog - Development Page
Related topics
Links here
21-112
Project Settings Dialog - Input Paths Page
Use the Input Paths page of the Project Settings dialog to define the source directory paths for
a project or projects.
Default Package
The default value that's used for the package name when you create new objects. Select
from the dropdown list or enter a new value.
Java Source Path
The path or paths to the Java source code (.java files) in your project. By default, this is
the src directory in the project directory. Click Edit to display the Edit Project Source
Path dialog, which you can use to modify paths in, or add paths to, your list of root
directories. In the Default Project Settings dialog, this is the root source for all
subsequent projects created for that package.
You can specify multiple source paths, as you will typically when creating a project that
references existing source files stored in various locations, but when you create a new
file for the project, JDeveloper uses the first entry in the source path to determine where
to store the file.
HTML Root Directory

The path to the directory where all your HTML or HTML-based files will be stored. This
directory should contain everything that needs to be accessible to the design time web
server. By default, this is the public.html directory in the project directory.
Enter a value or click Browse to navigate the directories available to your JDeveloper
environment and select an output directory.
Related topics
About Project Paths

About Packages
21-113
Project Settings Dialog - Libraries Page
Use the Libraries page of the Project Settings dialog to define libraries for a project or projects.
J2SE Version
The J2SE used by your project. Select an existing J2SE from the dropdown list or click
Define to create a new one.
Available Libraries
Selected libraries listing.
Selected Libraries
left) to move libraries from the Available libraries listing into this listing. Use the reorder
New
Click to create a new library and add it to the Selected libraries listing.
Edit
Highlight a library in either the Available libraries or Selected libraries listings and click
Delete
Highlight a library in either the Available libraries or Selected libraries listings and click
Classpath
Displays the classpath for the library currently selected in either the Available libraries or
Selected libraries listings.
Related topics
21-114
About Libraries
About J2SEs
21-115
Project Settings Dialog - Paths Page
Use the Paths page of the Project Settings dialog to set the classpath-related paths.
Output Directory
The directory where compiled files will be placed. To change the default, enter a new
value or click Browse to select an existing directory.
Additional Classpath
Enter any additional locations of compiled classes.
Related topics
About Project Paths
21-116
Property Inspector
The Property Inspector displays the properties of the selection of the active view, if it
participates in property inspection. For example, if JButton is selected in the UI Editor and the
UI Editor is active, JButton's properties display in the Property Inspector. For a project
selected in the Navigator, the Inspector displays the project properties.
The name of the selected object appears in the title bar of the Inspector, and its properties
appear in the main area of the Inspector, in a table, one property per row. Each row contains
the display name for the property and its current value. Descriptive text for the property appears
in the status area at the bottom of the Inspector, if the status area is shown.
The Property Inspector can display (where all three apply) three tabbed pages: Properties,
Events, Customizer. If multiple objects are selected, only the Properties page pertains.
When you activate a row in the Inspector's table, in order to edit the property's value, the
property editor for that property is swapped into the cell. If a fixed set of values applies, they
appear here in a dropdown list. If the value is a String, the text area is directly editable. If a
custom property editor is defined for this type, an ellipses button appears. Clicking the ellipses
button brings up a dialog that will display the custom editor.
When you write your own property editors for properties, you have the opportunity to control
what the Inspector will display. If your property editor supports tags, the Property Inspector
displays those tags in a dropdown list as the fixed set of values. If the property editor does not
support tags, the Property Inspector will query your editor to see whether it supports a custom
property editor. If neither are supported, a text area will be displayed for the user to type directly
into.
Related topics
About Bean Properties
21-117
Rename Class Dialog
Use the Rename Class dialog to move or rename the selected Java class. Files on the current
project's source path that are dependent on the moved or renamed class are also updated.
Enter the new name, and package, for the selected class.
If you do not supply a package name, the class is renamed so that it is not contained in a
package. That is, the class now exists without a package statement.
21-118
Rename Configuration Dialog
Use the Rename Configuration dialog to rename an existing configuration. Once you rename a
configuration, it becomes the active configuration.
If you have arrived at this dialog from the Project Settings dialog, the new configuration name
applies only to that project. If you have arrived at this dialog from the Default Project Settings
dialog, the new configuration name applies to all subsequently created projects.
Name
Enter a new name for the configuration. The name must be unique. Configuration names
are case sensitive, so Debug and debug would be perceived as two distinct names.
Note that if you use a lengthy name, the tree control will display with a horizontal
scrollbar.
21-119
Rename Layout Dialog
Use the Rename Layout dialog to assign a new name to a currently existing custom layout
design. You cannot rename the default layouts.
Layout Name
Enter a new name for the custom layout.
21-120
Save As and Rename Dialogs
Use the Save As and Rename dialogs to save the container workspace (.jws) or project
(.jpr) files, or any of the files within a project, to a new location or with a new filename, or
both. Rename always replaces the target file. Save As replaces container files, but duplicates
source files.
To change a file's location, enter the new pathway into the File name field or click through the
directory tree in the lefthand pane. To change a file's filename, make the changes directly in the
File name field.

File name
When the dialog is first opened, displays the current filename. The current location is
shown in the directory tree in the lefthand pane above this field.
File type
list.
21-121
Save Scheme Dialog
Use the Save Scheme dialog to assign, or to confirm, a name for a scheme.
Save These Style Settings Under Scheme Name

Enter the name of a new or an existing scheme. If creating a new scheme, enter a new
name. If editing an existing scheme, reenter the original scheme name. When creating
new schemes, choose names that will immediately suggest their settings to you.
21-122
Search Files Dialog
Use the Search Files dialog to search files anywhere on your system, by file type, for a specific
text string or regular expression.
Note that during this search, .zip and .jar files are understood as being containers for other
files. When a .zip or .jar file is encountered, each file within the container is searched, as
indicated by the file types specified in the search.
Search Text
Enter the text to search for.
Generally, the last text string search is remembered in this field, and text searches
previous to that appear in the dropdown history. If you invoke the search dialog from
within the Code Editor, however, with a word selected in the editor, what displays in this
search field is that word.
Auto-Fill Text from Word Under Active Code Editor Cursor

Select to auto-fill the Search Text field based upon the currently selected word in the
active editor.
File Type(s)
Select the appropriate file type or types from the dropdown list. Examples of such file
types are *.java, *.jsp, *.txt, and so on.
Search Path(s)
Enter a search path or paths. The last path searched is remembered in this field, and
path searches previous to that appear in the dropdown history. To enter multiple paths,
use semicolons to separate individual entries. For example,
d:\src;d:\java\src.jar;d:\common\src\AllMySrc.zip
Use Active Project Source Path by Default
Select to search the source path for the project as defined in the project settings, rather
than entering a search path in the field above.
Search Options
Specifies the search criteria for this search.
Match Case
Select to perform a case-sensitive search.
Match Whole Word Only
21-123
Select to match complete words only.
Regular Expressions
Select to treat the text in the Search Text field as a regular expression.
Search in Subdirectories
Select to recursively search into all files of all paths specified in the Search Path(s)
field.
Related topics
Regular Expressions
21-124
Select Directories Dialog
There are several specific selection dialogs throughout JDeveloper. Use this dialog to select
whichever directory is appropriate. To navigate directories, enter a directory name directly or
click through the directory tree. Double-click a directory to open it in the display and continue
browsing. Select a directory and click Select to add it within whatever context you are working.
When you first invoke the dialog, it will open to the directory based upon your current context.
Location
Noneditable. Displays the current directory path, based upon the field information in the
current wizard or dialog. Contents of the directory appear in the display below. Navigate
directories by selecting from the dropdown list in this field or by clicking in the display of
directory contents.
Directory name
If you wish, enter a directory name to narrow down your search. The directory tree
responds to your input.
21-125
Select Directories or Files Dialog
There are several specific selection dialogs throughout JDeveloper. Use this dialog to select
whatever directory or files are appropriate for your context. To navigate directories, enter a
directory or file name directly or click through the directory tree.
When you first invoke the dialog, it will open to the directory based upon your current context.
Browsing vs. Adding Directories
Double-click a directory to open it in the display and continue browsing. Select a directory and
click Open to add it within whatever context you are working. Double-click a file to dismiss the
dialog and add the file.
Selecting Directory Contents
When you select a directory to be added where the context calls for files, the Directory Options
dialog appears in which you can define specific file types to be added, if you wish, and choose
whether or not to recurse subdirectories.
Selecting Archive Files
Archive files are displayed twice: once as a virtual directory and again as a file. When you
select the directory to be added, the Directory Options dialog appears. When you select the file,
the archive file is brought into your context intact. You can display its contents in the archive
viewer.
Dialog Controls
Location
Noneditable. Displays the current directory path, based upon the field information in the
current wizard or dialog. Contents of the directory appear in the display below. Navigate
directories by selecting from the dropdown list in this field or by clicking in the display of
directory contents.
21-126

File name
Optionally, enter a name to narrow your search.
File type
list.
21-127
Structure Window
The Structure window displays the structure of the document of the active view. Views that
participate in providing structure are the Navigator, the editors, and viewers. For example,
when a document is open in the Code Editor and the Code Editor is the active view, the
Structure window displays the code structure of the document. Likewise, when a document is
open in the UI Editor and the UI Editor is the active view, the Structure window displays the GUI
structure of the document. And when a node in the Navigator is selected, the structure provided
(if any) is the same as that which would be displayed if the node were opened in its default
editor.
You can navigate in the editor by navigating in the Structure window. For example, you can
navigate to the definition of a method by double-clicking on the node for it in the Structure
window.
Related topics

The Code Editor
The UI Editor
21-128
System Navigator
By default, the System Navigator opens docked to the left of the main work area of JDeveloper.
The System Navigator displays all of your workspaces and projects, as well as all database,
application server, SOAP server, and repository connections. Single-click leaf nodes within
project (.jpr) files to display their structure hierarchically in the Structure window below the
default position of the System Navigator. Double-click the leaf nodes to open them in their
default editor in the central area of JDeveloper, or to bring that default editor (if already open)
into focus.
Right-click on a node within the System Navigator to bring up a context-sensitive menu of

commands. The menu commands available depend on the node selected. You can open nodes
in their default editors, as well as other editors common to that node type, using the context
menu.
Opening a New Navigator
You can open a new Navigator window for certain containers (and their children), making the
selected element the root object of the new Navigator, by choosing View | Display in New
Navigator or by clicking the Display in New Navigator toolbar icon in the toolbar at the top of
the Navigator window. The new custom navigator appears with a tab naming its root node. The
System Navigator now appears with a tab labeled System. To close a custom navigator, right-
click on its tab and choose Close.
If the menu option and icon are grayed out, you cannot create a new navigator with this node
as a starting point. You can undock and redock navigators wherever you would like. The
windows are also resizeable.
Working in the Navigator
You cannot rename files directly in the Navigator, as it interprets typing as implementing a
search. To rename files, use the Rename and Save As options on the File menu. Note that
Rename always replaces the target file. Save As replaces container files, but duplicates source
files.
Searching Incrementally
To search incrementally, put the focus in the Navigator and begin typing. As you type, the
cursor jumps to the next instance of that particular letter combination, either up or down,
21-129
depending upon where the next instance is. If the search locates the same combination both
above and below, it prefers the forward search, moving down the list.
If the letter combination you type is matched by the current cursor location, the cursor will not
move until you type a distinguishing letter, not matched by the current location. This search
supports wildcards.
Scrolling with the Wheel Mouse
If you are using a wheel mouse, you have two additional scroll options. Hold down the shift key
to scroll one line at a time. Hold down the control key to scroll an entire page at a time. The
default scroll length is three lines.
Icons in the Navigator
At the top of the Navigator, the following icons appear. Each icon also has a menu equivalent.
Add to Workspaces, a particular workspace, or a particular project.
Click to add a new workspace to the Workspaces node, a new project to a particular
workspace, or new items to a particular project, depending upon the node type selected.
An "Add to" dialog appears with which you can select the appropriate directories or files.
Not enabled outside these three node types.
Remove from IDE.
Click to remove the selected file or node from the IDE. Removal is immediate. The files
are not deleted, but no longer appear within your workspace or project folder. There is no
undo for this action. Not enabled for default root nodes.
Project Settings.
Click to open the Project Settings dialog for the selected project. Enabled only on
individual project nodes or their children.
21-130
Display in New Navigator.
Click to open the selected node in a new custom navigator. The new navigator appears
with a tab naming its root node. The System Navigator now appears with a tab labeled
System. Not enabled for default root nodes.
Show Categories.
Click to display the files in the selected project by file type, rather than as a flat list of all
files organized alphabetically. Click again to return to the default flat list. Enabled only on,
21-131
or within, project nodes.
Once your project is displayed by category, you can choose to display individual project
source nodes in the following ways, based upon source type. All four category display
types are available to Java source nodes.
File List.
Click to reorganize the selected file type node by file list. The files under the
selected source node now appear in a flat alphabetical listing.
Package Tree.
Click to reorganize the selected file type node by package tree. The files under the
selected source node now reflect their package hierarchy.
Package List.
Click to reorganize the selected file type node by package list. The files under the
selected source node are grouped by package, and the packages are listed
alphabetically. Package list is the default view for Java source files.
Directory Tree.
Click to reorganize the selected file type node by directory tree. The files under the
selected source node now reflect their directory hierarchy. This view is virtually the
same as that of the package tree, but directory information additionally appears.
Show All Files.
Available within selected category display types. Click to display all the files in the
directory or package, not simply those in the project.
21-132
Related topics

About Workspaces
About Projects
21-133
UI Editor
The UI Editor displays the visual components of a user interface in design mode.
When a UI Editor is open, its corresponding elements are displayed hierarchically in the
Structure window. If the Property Inspector is open, selecting elements in either the Structure
window or the UI Editor changes the selection in the Inspector as well.
The UI Editor displays a GUI hierarchy. If these are menu items, the hierarchy is displayed in
one fashion; if these are nonmenu items, it is displayed in another. The mode of presentation
differs, as the sort of editing that you are engaged in differs.
To open a hierarchy initially in the UI Editor, you have only to select a node in the Navigator
and then right-click and choose UI Editor, or use the View menu. What displays in the editor is
the entire GUI hierarchy for the this node. The method of display depends upon whether this
hierarchy consists of menu or nonmenu items.
When the node is selected in the Navigator, its GUI structure also displays in the Structure
window. All nonmenu GUI items for this object appear under a node labeled UI. Any menu
items appear under a node labeled Menu. Any non-GUI items appear under a node labeled
Other. Once you have opened the UI Editor for an object in the Navigator, to switch between
the display of nonmenu GUI elements and menu elements you have only to click on a node
below these UI or Menu nodes in the Structure window.
Because the display in the UI Editor is rooted in the GUI hierarchy, when you click on a node
(for all GUI objects) in the Structure window what loads into the editor is the visual
representation of the root node and all its descendants: the entire hierarchy opens, regardless
of which node in the hierarchy you selected. What displays in the editor reflects the complete
GUI hierarchy; the specific element selected in the display reflects the specific node selected in
the window. Selections in the Structure window and the UI Editor are kept in synch.
If you have an orphan node in the Structure window, that node and its descendants comprise
the entire hierarchy, with the orphan being the root of the hierarchy. The UI display will reflect
this. If you had a control, for instance, that was not parented, and you selected the node for that
control, the control and any descendants would now appear in the editor, without a container.
Any changes you make to that control, however, will result in generated code.
Right-click anywhere within the UI Editor to bring up a context-sensitive menu of commands.

The context menus differ, depending upon whether you are editing nonmenu or menu items,
and the commands available within the context menu depend on the selected object.
21-134
Related topics

The Component Palette
21-135
UI Editor, with menu focus
The UI Editor displays the visual components of a user interface in design mode.
When a UI Editor is open, its corresponding elements are displayed hierarchically in the
Structure window. If the Property Inspector is open, selecting elements in either the Structure
window or the UI Editor changes the selection in the Inspector as well.
The UI Editor displays a GUI hierarchy. If these are menu items, the hierarchy is displayed in
one fashion; if these are nonmenu items, it is displayed in another. The mode of presentation
differs, as the sort of editing that you are engaged in differs.
To open a hierarchy initially in the UI Editor, you have only to select a node in the Navigator
and then right-click and choose UI Editor, or use the View menu. What displays in the editor is
the entire GUI hierarchy for the this node. The method of display depends upon whether this
hierarchy consists of menu or nonmenu items.
When the node is selected in the Navigator, its GUI structure also displays in the Structure
window. All nonmenu GUI items for this object appear under a node labeled UI. Any menu
items appear under a node labeled Menu. Any non-GUI items appear under a node labeled
Other. Once you have opened the UI Editor for an object in the Navigator, to switch between
the display of nonmenu GUI elements and menu elements you have only to click on a node
below these UI or Menu nodes in the Structure window.
Because the display in the UI Editor is rooted in the GUI hierarchy, when you click on a node
(for all GUI objects) in the Structure window what loads into the editor is the visual
representation of the root node and all its descendants: the entire hierarchy opens, regardless
of which node in the hierarchy you selected. What displays in the editor reflects the complete
GUI hierarchy; the specific element selected in the display reflects the specific node selected in
the window. Selections in the Structure window and the UI Editor are kept in synch.
If you have an orphan node in the Structure window, that node and its descendants comprise
the entire hierarchy, with the orphan being the root of the hierarchy. The UI display will reflect
this. If you had a control, for instance, that was not parented, and you selected the node for that
control, the control and any descendants would now appear in the editor, without a container.
Any changes you make to that control, however, will result in generated code.
Right-click anywhere within the UI Editor to bring up a context-sensitive menu of commands.

The context menus differ, depending upon whether you are editing nonmenu or menu items,
and the commands available within the context menu depend on the selected object.
21-136
Related topics

The Component Palette
21-137
Windows Dialog
Use the Windows dialog to activate or to close windows in your working area within
JDeveloper. This is particularly useful when your work area is crowded with many windows.
Windows
Displays an alphabetical list of the windows currently open. To move quickly through the
list, begin typing the window name to be selected. At the first unique identifying letters,
the cursor jumps to that name. To activate a window, select it and click Activate. To
activate a window and dismiss the dialog, press Enter.
Activate
Click to activate the selected window. Activation is immediate.
Close
Click to close the selected window or windows. Closure is immediate.
21-138
JClient Reference
● Accelerator Keystroke Property Editor
● Border Property Editor
● BoundedRange Model Property Editor
● Color Property Editor
● Constraints Property Editor
● Event Handler Stub Dialog
● Font Property Editor
● JClient Action Model Property Editor
● JClient Attribute List Model Property Editor
● JClient Attribute Model Property Editor
● JClient Boolean Model Property Editor
● JClient Data Model Definition Wizard - Welcome
● JClient Data Model Definition Wizard - Client Data Model Name
● JClient Data Model Definition Wizard - Application Module Selection
● JClient Data Model Definition Wizard - Finish
● JClient Empty Frame Wizard - Welcome
● JClient Empty Frame Wizard - Data Model
● JClient Empty Frame Wizard - File Name
● JClient Empty Frame Wizard - Finish
● JClient Empty Panel Wizard - Welcome
● JClient Empty Panel Wizard - Data Model
● JClient Empty Panel Wizard - File Names
● JClient Empty Panel Wizard - Finish
● JClient Enumeration Model Property Editor
● JClient Form Wizard - Welcome
● JClient Form Wizard - Form Type
● JClient Form Wizard - Form Layout
22-1
● JClient Form Wizard - Data Model
● JClient Form Wizard - Panel View
● JClient Form Wizard - Single Table Attribute Selection
● JClient Form Wizard - Master Attribute Selection
● JClient Form Wizard - Detail Attribute Selection
● JClient Form Wizard - File Names
● JClient Form Wizard - Finish
● JClient Graph Wizard - Welcome
● JClient Graph Wizard - Graph Type
● JClient Graph Wizard - Data Model
● JClient Graph Wizard - View Selection
● JClient Graph Wizard - Graph Details
● JClient Graph Wizard - Finish
● JClient Java Web Start Wizard - Welcome
● JClient Java Web Start Wizard - Data Model
● JClient Java Web Start Wizard - Properties
● JClient Java Web Start Wizard - Finish
● JClient LOV Model Property Editor
● JClient Navigation Model Property Editor
● JClient Node Model Property Editor
● JClient Panel Wizard - Welcome
● JClient Panel Wizard - Template Selection
● JClient Panel Wizard - Data Model
● JClient Panel Wizard - Panel View
● JClient Panel Wizard - Attribute Selection
● JClient Panel Wizard - File Names
● JClient Panel Wizard - Finish
● JClient View Object Model Property Editor
● New Gallery - Application Object
22-2
● New Gallery - Dialog Object
● New Gallery - Frame Object
● New Gallery - JClient Objects Category
● New Gallery - Panel Object
22-3
Accelerator Keystroke Property Editor
Use this dialog to set the keystrokes for the menu item's accelerator.
Modifiers
Select the keystroke modifier:
SHIFT_MASK
When you want to require pressing the Shift key as part of the keystroke.
CTRL_MASK
When you want to require pressing the Ctrl key as part of the keystroke.
META_MASK
When you want to require pressing the Meta key as part of the keystroke.
ALT_MASK
When you want to require pressing the Alt key as part of the keystroke.
Keys
Select the key combination. Use Ctrl-click to select more than one key from the list.
On key release
Select to activate the accelerator when the user completes the keystroke.
22-4
Border Property Editor
Use the this dialog to change border for the selected control.
BeveledBorder
Displays a border with a 3-D effect that gives the entire control the appearance of being
raised or lowered. You can select:
Raised
When you want to give the control a slightly raised appearance.
Lowered
When you want to give the control a slighly lowered appearance.
EmptyBorder
Pads the control with empty space within the layout area that the control occupies. You
can enter the number of pixels you want to pad around the control on each side. The
layout manager preserves the relative positions of the surrounding controls; therefore,
padding can affect the position of the surrounding controls as well.
EtchedBorder
Displays a border with a 3-D effect that appears the same around the entire control. You
can select:
Raised
When you want to give the etched border a slightly raised appearance.
Lowered
When you want to give the etched border a slightly lowered appearance.
LineBorder
Displays a border with the color you select.
Thickness
Specifies the thickness of the border in pixels.
Standard colors
Provides a list of predefined color settings. Select a color from the dropdown list
and view the result in the Selected Color panel.
Custom color settings (RGB)
The following color settings are displayed when the RGB (Red/Blue/Green) button
is selected. To set values, use the slider bars or enter a number.
Red
22-5
The red component of the color.
Green
The green component of the color.
Blue
The blue component of the color.
Custom Color Settings (HSB)

The following color settings are displayed when the HSB
(Hue/Saturation/Brightness) button is selected. To set values, use the slider bars
or enter a number.
Hue
The actual color in the color spectrum.
Saturation
The amount of color. Low saturation results in pastels, high saturation in
more vibrant colors.
Brightness
The lightness or darkness of the color. No brightness is black; full
brightness is white.
Selected Color
The selected color is displayed in this area.
TitledBorder
Displays an etched-style border with the label you supply.
22-6
BoundedRange Model Property Editor
Use this dialog to set the display range for the control.
Minimum
Enter the value for the minimum value in the scrollable range. This is the value that
defines start point for the range.
Value
Enter the initial value. This is the value that defines the position of the thumb.
Extent
Enter the value by which the thumb increments.
Maximum
Enter the value for the maximum in the scrollable range. This is the value that defines
end point for the range.
22-7
Color Property Editor
Use this dialog to change a component's background and foreground colors.
Standard colors
Provides a list of predefined color settings. Select a color from the dropdown list and
view the result in the Selected Color panel.
Custom color settings (RGB)
The following color settings are displayed when the RGB (Red/Blue/Green) button is
selected. To set values, use the slider bars or enter a number.
Red
The red component of the color.
Green
The green component of the color.
Blue
The blue component of the color.
Custom Color Settings (HSB)

The following color settings are displayed when the HSB (Hue/Saturation/Brightness)
button is selected. To set values, use the slider bars or enter a number.
Hue
The actual color in the color spectrum.
Saturation
The amount of color. Low saturation results in pastels, high saturation in more
vibrant colors.
Brightness
The lightness or darkness of the color. No brightness is black; full brightness is
white.
Selected Color
The selected color is displayed in this area.
22-8
Constraints Property Editor
When you use the UI Editor to create a GridBagLayout container, JDeveloper automatically
instantiates a GridBagConstraints2 object for each component you add to the container. It uses
default constraint values, and/or values calculated for existing components during conversion
from another layout (like XYLayout) to GridBagLayout. Use the Constraints property editor
allows to edit these constraints.
You can access the Constraints property editor two ways in JDeveloper:
● The component's constraints property in the Inspector

● The Constraints menu item on the component's right-click popup menu
Each constraint in the property editor directly corresponds to a constraint from the
GridBagConstraints2.class as specified in the following section.
Grid Position
X and Y
Use the Grid Position constraints X (gridx) and Y (gridy) to specify the grid cell
location for the upper left corner of the component. This constraint value is an
integer representing the cell number in a column or row. For example, gridx=0 is
the first column on the left, and gridy=0 is the first row at the top. Therefore, a
component with the constraints gridx=0 and gridy=0 is placed in the first cell of the
grid (top left).
There is an additional constraint value that can be used for gridx and gridy called
RELATIVE (the default value). RELATIVE specifies that the component be placed
relative to the previous component as follows:
■ When used with gridx, it specifies that this component be placed

immediately to the right of the last component added just before this one.
■ When used with gridy, it specifies that this component be placed
immediately below the last component added just before this one.
To specify a RELATIVE value for Grid Position X or Y in the Constraints property

editor, enter -1.
22-9
Width and Height
Use the Grid Position constraints Width (gridwidth) and Height (gridheight) to
specify the number of cells in a row (gridwidth) or column (gridheight) the
component uses. This constraint value is an integer representing the number of
cells in a column or row, not the number of pixels.
There are two additional constraint values that can be used for gridwidth and
gridheight: RELATIVE and REMAINDER.
RELATIVE specifies that this component is the next to last one in the row
(gridwidth) or column (gridheight). A component using RELATIVE takes all the
remaining cells except the last one. For example, in a row of six columns, if the
component starts in the third column, a gridwidth of RELATIVE will make it take up
columns three, four, and five.
REMAINDER specifies that this component is the last one in the row (gridwidth) or
column (gridheight).
■ To specify a RELATIVE value for Grid Position Width or Height in the

Constraints property editor, enter -1.
■ To specify a REMAINDER value for Grid Position Width or Height in the
Constraints property editor, enter 0.
External Insets
Use External Insets (insets) to specify (in pixels) the minimum amount of external space
(padding) between the component and the edges of its display area. You can specify a
value for each edge of the component separately: top, left, bottom, and right.
Size Padding
Size Padding specifies the internal padding for a component (the amount of space
around the component inside the cell). Use Width (ipadx) and Height (ipady) to specify
(in pixels) the amount of space to add to the minimum size of the component for internal
padding.
The width of the component will be at least its minimum width plus ipadx in pixels. (In
spite of the fact that the Javadoc comments say ipadx*2, the actual code only adds it
once.) Similarly, the height of the component will be at least the minimum height plus
22-10
ipady pixels.
Example:
When added to a component that is 30 pixels wide and 20 pixels high:
❍ If Width= 4, the component will be 34 pixels wide.

❍ If Height= 2, the component will be 22 pixels high.
Width
Width (ipadx) specifies the number of pixels to add to the minimum width of the
component.
Height
Height (ipady) specifies the number of pixels to add to the minimum height of the
component.
Weight
Use the Weight constraints to specify how to distribute the extra space vertically
(weightx) and horizontally (weighty) when the container is resized. Weight determines
what share of extra space each component gets when the container is enlarged beyond
its default size.
For example, if you have three components with weights of 0.0, 0.3, and 0.2 respectively,
when the container is enlarged, none of the extra space will go to the first component,
3/5 of it will go the second component, and 2/5 of it will go to the third.
Note: If all the components have weights of zero in a single direction, the components will
clump together in the center of the container for that dimension and won't expand beyond
their preferred size. GridBagLayout puts any extra space between its grid of cells and the
edges of the container.
Weight values are of type double and are specified numerically in the range 0.0 to 1.0
inclusive. Zero means the component should not receive any of the extra space, and 1.0
means the component gets a full share of the space.
X
The Weight constraint X (weightx) is the vertical weight distribution for a
22-11
component. The weight of a row is calculated to be the maximum weightx of all the
components in the row.
Y
The Weight constraint Y (weighty) is the horizontal weight distribution for a
component. The weight of a column is calculated to be the maximum weighty of all
the components in the column.
Anchor
When the component is smaller than its display area, use the anchor constraint to tell the
layout manager where to place the component within the area. anchor only affects the
component within its own display area, depending on the fill constraint for the
component.
For example, if the fill constraint value for a component is BOTH (fill the display area
both horizontally and vertically), the anchor constraint has no effect because the
component takes up the entire available area. For the anchor constraint to have an
effect, set the fill constraint value to NONE, HORIZONTAL, or VERTICAL.
The values for anchor are as follows:
NW (NORTHWEST) N (NORTH) NE (NORTHEAST)

W (WEST) C (CENTER) E (EAST)
SW (SOUTHWEST) S (SOUTH) SE (SOUTHEAST)
Fill
When the component's display area is larger than the component's requested size, use
the fill constraint to tell the layout manager if the component needs to be resized, and if
so, how. As with the anchor constraint, the fill constraint only affects the component
within its own display area. fill tells the layout manager to expand the component to fill
the whole area it has been given.
The values for fill are as follows:
None Don't change the size of the component.

Horizontal Only resize the component to fill the area horizontally.
Vertical Only resize the component to fill the area vertically.
Both Resize the component both horizontally and vertically to fill the area completely.
22-12
Related topics
GridBagLayout
22-13
Event Handler Stub Dialog
Use this dialog to change the default name for the method to be called from the event handler
stub. The dialog inserts the event handler stub in your class file with the method name you
specify.
Private void
Shows the method signature. Enter the desired method name. The default name is
formed from the name of the component the event is registered on and the event name
itself.
Sample handler
Displays the event handler stub as it will appear in your class file.
22-14
Font Property Editor
Use this dialog to change the font for displayed text.
Name
The names of available fonts.
Size
Changes the font's point size.
Bold
Bolds the font.
Italic
Italicizes the font.
Sample Text Box
Displays a sample of the selected font.
22-15
JClient Action Model Property Editor
Use this dialog to bind a JClient action model to your control. Select the view object and the
action you want the control to initiate on the rows of the view object.
Select a view
Select an available view object from the list to bind the control. The list of available view
objects is determined by the containing panel's data model.
Choose the action
In the case of JScrollBar, JSlider, and JProgressBar controls, you can also set the
attribute display range.
Next
Select to move to the next row in the view object's range.
Previous
Select to move to the previous row in the view object's range.
First
Select to move to the first row in the view object's range.
Last
Select to move to the last row in the view object's range.
Reset
Select to reset data from the view object cache on all rows.
Remove current row
Select to delete the current row.
Insert new row
Select to insert a row.
Execute
Select to execute the view object query to get the latest data from the database.
Commit
Select to commit the view object changes to the database.
Rollback
Select to rollback the view object changes. No data will be sent to the database.
22-16
Related topics

Setting an Action Binding Control
22-17
JClient Attribute List Model Property Editor
Use this dialog to bind a JClient attribute list model to your table control. Select the view object
and the attributes that you want the table to display. You can also change the order in which
the table displays the bound attributes.
Select a View
Select an available view object from the list to bind the table control. The list of available
view objects is determined by the containing panel's data model.
Available Attributes
Lists all of the attributes in the selected view object that are available for display. The list
of available view objects is determined by the containing panel's data model.
Selected Attributes
Lists all of the attributes from the view object selected to be displayed by the table
control. Four buttons allow you to move attributes between the Available and Selected
lists.
Button Description
Click to move the attribute selected in the Available
Attributes list to the Selected Attributes list.
Click to move all attributes in the Available Attributes
list to the Selected Attributes list.
Click to move the attribute selected in the Selected
Attributes list to the Available Attributes list.
Click to move all attributes in the Selected Attributes
list to the Available Attributes list.
Up and Down Arrows
Click to reposition the selected attribute in the Selected Attributes list.
22-18
Click to reposition the selected attribute in the
Selected Attributes list. This affects the order in which
the table displays the attributes: top to bottom in the
list positions column attributes from left to right in the
table.
Related topics

Setting an Attribute List Binding Control
22-19
JClient Attribute Model Property Editor
Use this dialog to bind a JClient attribute model to your control. Select the view object and the
attribute on which you want the control to operate.
Choose a View
Choose an Attribute
Lists all of the attributes in the selected view object that are available for display. Select
the attribute you want to bind to the control.
Properties for JScrollBar, JSlider, and JProgressBar Only

In the case of JScrollBar, JSlider, and JProgressBar controls, you can also set the
attribute display range.
Minimum
Enter the value for the minimum value in the scrollable range. This is the value
that defines start point for the range.
Maximum
Enter the value for the maximum in the scrollable range. This is the value that
defines end point for the range.
Extent
Enter the value by which the scrollbar or slider thumb increments. Each increment
(or tick mark) corresponds to a possible value the user can choose for the
attribute. Not applicable to the JProgressBar.
In the case of the scrollbar and slider, attribute values are calculated by adding the
control's Minimum value to the product of the Extend value and index of the
selected tick mark. For example, if the Minimum value is 20, the Extent value is
10, and the user has selected the 3rd tick mark in the scrollbar or slider, then the
attribute value would be 20 + (10 x 3) = 50.
Related topics
22-20
Setting an Attribute Binding Control
22-21
JClient Boolean Model Property Editor
Use this dialog to bind a JClient boolean model to your control. The boolean model determines
the value to return when the user changes your control's selection state. Use this dialog to
select the view object and the attribute on which you want the control to operate. You must
know what values the bound attribute takes in order to supply meaningful selection state
values.
Select a View
Select an Attribute
the attribute you want to bind to control.
True Value
Enter a meaningful attribute value to return for the true state. This is the value the model
will use to update the attribute when the user makes the control appear selected.
False Value
Enter a meaningful attribute value to return for the false state. This is the value the model
will use to update the attribute when the user makes the control appear unselected.
Related topics

Setting a Boolean Binding Control
22-22
JClient Data Model Wizard - Welcome
Use the JClient Data Model Wizard to quickly create a new client data model definition for use
with JClient applications.
The client data model definition the wizard creates relies on an existing Business Components
project to specify an application module. Refer to the documentation if your workspace does
not yet contain a Business Components project.
The JClient Data Model Wizard:
● Uses the current application workspace to display a list of available application modules
● Adds a client data model definition to a .cpx file that appears in the JClient project
● The client data model definition specifies the name of the application module you select
Display this page next time

Clear this checkbox to skip the Welcome page when you use the JClient Data Model
Wizard.
Related topics

22-23
Client Data Model Name
Use this page to specify the name of the data model.
Client Data Model Name

The name you supply will appear in the JClient project configuration (.cpx) file.
Related topics

22-24
Application Module
Use this page to select the location of your Business Components application module.
Business Components for Java lets you develop multi-tier data forms that separate your
application's business logic from the user interface's functionality.
The wizard will add the data model definition to the JClient project configuration (.cpx) file.

Select an available Business Components project from the dropdown list.
Application Module
Displays available application modules. If the Business Components data model contains
nested application modules, choose the one that defines the desired view object and
their relationships.
Selected application's model
Examine the structure of the application module selection to ensure it includes desired
master-detail relationships in the data model.
Configuration
Displays available deployment configurations defined in the Business Components
project configuration (.xcfg) file. Choose the desired JClient configuration to reference
the JClient data model definition from the Business Components project. If no
deployment configuration has been defined, the default choice will be a local
configuration used to run JClient within JDeveloper.
Related topics

22-25
JClient Data Model Definition Wizard - Finish
Use this page to review information you have entered about your data model.
When you click Finish, the wizard will update your JClient project configuration file (.cpx) with
the data model definition you named.
Click Finish to generate the data model definition.
Related topics

22-26
JClient Empty Frame Wizard - Welcome
Use the JClient Empty Frame Wizard to create a Java client frame with JClient-specific code.
The frame the wizard generates will contain JClient-specific application bootstrap code. The
bootstrap code creates a JUApplication object that defines an application module connection
and creates the frame instance using a constructor with the JUApplication object.
The frame is empty because it contains no code to create data browsing panels. You can use
the JClient Panel Wizard to create the data browsing panels that you add to the generated
frame.
The JClient Empty Frame Wizard:
● Walks you through the steps of creating a Java frame

● Generates the Java source code required to implement the empty frame with JClient
code that creates an application module session

Clear this checkbox to skip the Welcome page when you use the JClient Empty Frame
Wizard.
22-27
Data Definition
Use this page to choose a data model that your JClient project defines. The data model you
choose defines the context for Business Component datasources. This context appears in the
empty frame as JClient-specific code.
Select the Data Model

Select an available data model from the dropdown list. Click New to define additional
data models that you can choose from.
Select an AppModule
<root> refers to the application module referenced by the data model selection. This
dropdown menu is disabled unless the selected data model references an application
module that is itself a nested application module. In that case, you will be presented with
a list of application modules from which to choose. The list will include the nested
application module (identified by the <root> selection) and the container application
modules. Choose the application module that defines the desired view object. You can
see the available view objects and their relationships in the Selected Data Model area.
Selected Data Model
Examine the structure of the data model selection to ensure you have selected the
desired application module. In a JUPanel that your empty frame creates, you will
eventually bind controls to specific view objects from the displayed list.
Related topics

22-28
File Name
Use this page to name the package and empty frame. The wizard will add the package and file
with the supplied names to your JClient project.
Package Name
Enter a name for the package.
Frame Name
Enter the name of the java class that defines the empty frame.
Generate a login dialog
Select to add an extensible login dialog to your project. The wizard checks to see
whether the class JCLoginDialog exists in your project; it will not overwrite an existing
login dialog with same name. The sample code in this generated class file is provided so
that you can customize the login dialog to provide your own login parameters in addition
to user name and password.
Note: JClient forms will use the generated login dialog (JCLoginDialog) when present in your
project. If you do not want to use the generated login dialog to run your JClient project, select
the Deploy Password option in the Connection Wizard and remove the generated file from
your project.
22-29
JClient Empty Frame Wizard - Finish
Use this page to review information you have entered about your frame.
Click Finish to generate the frame.
22-30
JClient Empty Panel Wizard - Welcome
Use the JClient Empty Panel Wizard to create a Java client panel with JClient-specific code.
The panel the wizard generates extends the JFC JPanel class, which in turn implements a
JUPanel interface provided by JClient. The generated panel class contains a method that
implements the JUPanel interface getPanelBinding() to return a panel binding definition for the
panel. A panel with a panel binding definition can be embedded in another container, such as a
JFrame or JPanel.
The panel is empty because it contains no code to bind controls to BC4J datasources. You can
use the JClient Model Editors for individual controls to add control bindings to the panel.
The JClient Empty Panel Wizard:
● Walks you through the steps of creating a Java panel

● Generates the Java source code required to implement the empty panel with JClient
code that creates a panel binding

Clear this checkbox to skip the Welcome page when you use the JClient Empty Panel
Wizard.
Related topics
About JClient Data Panels

Binding JClient Panels to a JUApplication Object
22-31
Data Definition
choose defines the context for Business Component datasources that you can create in the
empty panel.

Select an AppModule
Selected Data Model
desired application module. In the empty JUPanel, you will bind controls to specific view
objects from the displayed list.
Related topics

22-32
File Names
Use this page to name the package and empty panel. The wizard will add the package and file
with the supplied names to your JClient project.
Package Name
Panel Name
Enter the name of the java class that defines the form's empty panel.
Generate a Frame the Runs the Panel
Select when you want to create a runnable frame that contains the panel.
Related topics

22-33
JClient Empty Panel Wizard - Finish
Use this page to review information you have entered about your panel.
Click Finish to generate the empty panel and optional runnable frame.
Related topics

22-34
JClient Enumeration Model Property Editor
Use this dialog to bind a JClient enumeration model to your control. Select the view object and
the attribute on which you want the control to operate then specify a set of values from which
the user may select. You must know what values the bound attribute takes in order to supply
meaningful choices.
Select a View
Select an Attribute
the attribute you want to bind to the control.
Provide a set of values
Enter the values you want the control to display. Several buttons allow you to add and
remove values from the list. You can also use the up and down arrow buttons to change
the display order of the values you enter.
Button Description
Click to add and enter the desired value that you want
the control to display.
Click to remove the selected value from the list.
Click to reposition the selected value in the values list.

This affects the order in which the control displays the
values.
Related topics

Setting an Enumeration Binding Control
22-35
JClient Form Wizard - Welcome
Use the JClient Form Wizard to create a Java client application or applet class that accesses
data from either a single table or two tables joined in a master-detail relationship. The table
relationships are predefined by view objects in the Business Components application module
that you specify.
The JClient Form Wizard:
● Walks you through the steps of creating a Java application or applet class
● Generates the default look and feel of the form's user interface
● Generates the Java source code required to implement the form
● Saves connection information the form will use to connect to the Business Components
application module

Clear this checkbox to skip the Welcome page when you use the JClient Form Wizard.
Related topics
About JClient Data Forms

Creating a Single Table JClient Form
Creating a Master-Detail JClient Form
22-36
Form Types
Use this page to select the kind of form you want to create and how the form should be
implemented.
Single Table
Select to create a form that displays data from a single business component view object.
The view object represent a table in the database.
Master-Detail
Select to create a form that displays data based on a master-detail relationship between
two business component view objects. This assumes you have an application module
whose view objects define this type of relationship. The view objects represent tables in
the database.
Frame
Select to build the form as a top-level window.
When you choose this option, the wizard generates a frame class (for example,
FrameMyView.java) that contains JClient application bootstrap code. The bootstrap code
creates a JUApplication object that defines an application module connection and
creates the frame instance using a constructor with the JUApplication object.
Applet
Select to build the form as an applet that can be displayed in a web browser or Java Web
Start.
When you choose this option, the wizard generates an applet class (for example,
AppletMyView.java), which extends the JFC JApplet class. However, the wizard does not
generate an applet HTML file, which is required to define the applet that will appear in a
Java-enabled browser. If you wish to generate an applet class for your JClient
application, you can either create the HTML file yourself, or you can use Java Web Start
to run the applet. For information on Java Web Start, see the JClient documentation.
Related topics

22-37
22-38
Form Layout
Use this page to select the layout and label position to be applied to your form. The wizard
displays an example of the layout in a screen capture next to your selection.
If your form is a master-detail form, you can choose one layout type for the master and another
type for the detail.
Select a Template
Single Columns (Labels Above)
Positions the labels above the fields.
Single Columns (Labels Left)
Positions the labels to the left of the fields.
Table
Displays attribute data in rows in a grid control. Labels will appear above the fields.
Number of Columns
If you choose vertical layout, by default the data form aligns the fields it uses to display
view object attributes in a single column. If you want to arrange the fields in multiple
columns to display across your data form, you can change the number of columns. You
can display up to ten columns of attributes in your data form.
Related topics

22-39
Data Model
choose defines the context for Business Component datasources you want your form to use.

Select an AppModule
Selected Data Model
Examine the structure of the data model selection to ensure it includes the desired view
objects and master-detail relationships (if applicable). You will choose the view object (or
view objects in the case of a master-detail form) to serve as your form's datasource in
the next wizard step.
Related topics

22-40
Panel View
Use this page to select the Business Components view object that defines the set of attributes
you want your form to use. This page displays master-detail view objects only if you indicated a
master-detail type form on the first page of this wizard and the data model you chose on the
previous page contains those relationships. Go back to the previous page if you want to change
the list of available view objects.
Select a view object

Select the view object that represents the table in the query. The view object you select
is the datasource for the panel; it defines the set of attributes that you can choose to
display.
The contents of these lists are based on the view objects included in your application
module's data model.
Show hidden attributes

Lets you handle the Form Type control hint setting for attributes of the selected view
object. The business components developer can set control hint properties for attributes
of a view object. If the Form Type property of an attribute is set to Detail (default), this
checkbox is ignored. If the Form Type property is set to Summary, then this checkbox
lets you select attributes that would otherwise be hidden for use in the generated form:
❍ When selected, attributes with Form Type property set to Summary will not appear
in the Selected Attributes list on the next page of this wizard, but these attributes
will appear in the Available Attributes list.
❍ When unselected, attributes with Form Type property set to Summary will not be
available for selection on the next page of this wizard (they will be hidden).
Related topics

22-41
Attribute Selection
Use this page to select the attributes from the view object that you want to include in your form.
If you indicated a master-detail type form on the first page of this wizard and the data model
you chose contains those relationships, these attributes will define either your master or your
detail form.
This field lists all of the attributes in the view object that are available to be displayed on
a form.
An asterisk (*) in front of a attribute indicates that the attribute represents the primary key
and will be used by the query, whether or not it is displayed on the form.
The numbers listed after each attribute define attribute information such as, the number
of characters in a text item, or the scale and precision of a numeric item.
Selected Attributes
This field lists all of the attributes from the master table selected to be displayed on the
form. Four buttons allow you to move attributes between the Available and Selected lists.
Button Description
Up and Down Arrows
22-42
the attributes are displayed in the generated form.
Related topics

22-43
Attribute Selection
Use this page to select the master attributes you want to include on your form.
This field lists all of the attributes in the master view object that are available to be
displayed on a form.
Selected Attributes
Button Description
Up and Down Arrows

Related topics
22-44
22-45
Attribute Selection
Use this page to select the detail attributes you want to include on your form.
This field lists all of the attributes in the detail view object that are available to be
displayed on a form.
Selected Attributes
This field lists all of the attributes from the detail table selected to be displayed on the
Button Description
Up and Down Arrows

Related topics
22-46
22-47
File Names
Use this page to supply the package, class, and panel names you want your form to use. The
wizard will add the package and files with the supplied names to your JClient project.
Package name
Frame name
Enter a name for the Java class that defines the top-level window.
Layout panel name
Enter the name of the Java class that defines the form's layout panel.
Master panel name
Enter the name of the Java class that defines the form's master panel.
Generate a login dialog
Select to add an extensible login dialog to your project. The wizard checks to see
whether the class JCLoginDialog exists in your project; it will not overwrite an existing
login dialog with same name. The sample code in this generated class file is provided so
that you can customize the login dialog to provide your own login parameters in addition
to user name and password.
Note: JClient forms will use the generated login dialog (JCLoginDialog) when present in your
project. If you do not want to use the generated login dialog to run your JClient project, select
the Deploy Password option in the Connection Wizard and remove the generated file from
your project.
Related topics

22-48
JClient Form Wizard - Finish
Use this page to review information you have entered about your form.
Click Finish to generate the form.
Related topics
About Using JClient Data Panels
22-49
JClient Graph Wizard - Welcome
Use the JClient Graph Wizard to quickly create a data panel that contains a customized graph
control for use with JClient applications.
The graph data panel the wizard creates relies on an existing Business Components project to
specify an application module. Refer to the documentation if your workspace does not yet
contain a Business Components project.

Clear this checkbox to skip the Welcome page when you use the JClient Graph Wizard.
Related topics
About JClient Graph Panel

22-50
Graph Type
Use this page to select the type of graph you want to generate. The wizard displays a short
description of the selected graph.
Graph Type
Choose the category of the graph from the dropdown menu.
List of Graphs
Select the specific graph type from the list.
Related topics

22-51
Data Definition
Use this page to choose the data model that contains the view object you want your graph to
use.

Select an AppModule
Selected Data Model
object.
Related topics

22-52
View Selection
Use the View Selection page to specify whether you want the graph to use a single view object
or a master with a series of detail view objects. A graph based on a master detail is two or more
related graphs, which might plot, for example, a set of stocks; whereas, a single table graph
would plot only a single stock.
Single Table
Select if you want to draw a single graph based on one view object.
Master Detail
Select if you want to draw multiple graphs based on a series of related view object. This
produces a series of graphs based on master-detail view objects.
Views
If you selected the single table option, select the view object that contains the attributes
to plot.
If you selected the master detail option, select the view object that is the master for the
detail series.
View Accessor
This area is disabled unless you select the master detail option. Select the view object
accessor that links the detail view objects.
Class Name
Enter the name of the class for the graph panel.
Related topics

22-53
Select Columns
Use this page to specify which attribute you want to used to display the graph.
Series Label
The field supplies the label for the graph itself. If you selected a single table graph, you
can type the label. If you selected a multiple table graph, then you must select the
attribute to use to display the label for each graph in the series.
Group Label
Select the attribute to use to display the label for your graph's groups.
Column
Select the attribute to use to display the datapoints of the graph columns.
X axis
Select the attribute to display the datapoints of the graph's X axis.
Y axis
This value may not be used by your graph selection. Select the attribute to use to display
the datapoints of the graph's Y axis.
Label
This value may not be used by your graph selection. Select the attribute to use to display
the graph's label.
High
Select the attribute to display the datapoints of the stock's high values.
Low
Select the attribute to display the datapoints of the stock's low values.
Close
This value may not be used by your graph selection. Select the attribute to display the
datapoints of the stock's close values.
Volume
This value may not be used by your graph selection. Select the attribute to display the
datapoints of the stock's volume values.
22-54
Related topics

22-55
JClient Graph Wizard - Finish
Use this page to review information you have entered for your graph.
Click Finish to generate the graph data panel.
Related topics

22-56
JClient Java Web Start Wizard - Welcome
Use the JClient Java Web Start Wizard to create a JNLP file that you can use with your JClient
project to run and deploy JClient applications. Java Web Start is an application deployment
software developed by Sun Microsystem's that lets you maintain JClient applications on the
web server, while users download and run on their client machines.
The JNLP file the wizard creates relies on an existing Business Components project to specify
an application module and connection information. Refer to the documentation if your
workspace does not yet contain a Business Components project.

Clear this checkbox to skip the Welcome page when you use the JClient Java Web Start
Wizard.
Related topics

Creating a Web Start JNLP Definition for JClient Applications
22-57
Data Model
Use this page to choose the data model definition that contains the application module and
connection information you want the Java Web Start JNLP file to use.
Select the data model

Select an available data model definition from the dropdown list. Click New to define
additional data models that you can choose from.
Select an AppModule
modules. Choose the application module that defines the desired connection
configuration (specified in the bc4j.xcfg file). You can see the available view objects and
their relationships in the Selected Data Model area.
Selected Data Model
desired application module.
Related topics

22-58
Properties
Use this page to specify properties of the JNLP file that determine how your JClient application
should be run by Java Web Start.
Generate Application Description

Select if you want to run your JClient application from a main class. Your application
must define a class with a main() method.
Generate Applet Description
Select when you want to run your JClient application as an applet. You application must
define an applet class, but no HTML file is required.
Main Class
Select the class that you want to use to run your application from the dropdown menu.
The class should contain the main() method when you want to run as an application or it
should be the applet class when you want to run as an applet.
Title
Enter the title of your application to document the JNLP file.
Description
Enter the description of your application to document the JNLP file.
Vendor
Enter the name of your application to document the JNLP file.
JNLP generated dynamically - JSP
Select when you want to create a JavaServer Page (JSP) page to dynamically generate
the JNLP file. The JNLP file will not appear in your project. It is recommended that you
choose JNLP generated dynamically - JSP in order to dynamically generate the JNLP
definition from a generated JSP page that the user conveniently runs from their web
browser.
Static JNLP
Select when you want to generate the JNLP file and add it to your project.
Related topics
22-59
Creating a Web Start JNLP Definition for JClient Applications
22-60
JClient Java Web Start Wizard - Finish
Use this page to view the files that will be added to your project. These files let you deploy your
JClient application from a web server and run the application locally with Java Web Start.
Click Finish to generate the files required to deploy your JClient to the web server.
Related topics

22-61
JClient LOV Model Property Editor
Use this dialog to bind a JClient LOV (list of values) model to your control:
1. Use the Define the LOV tab to select the view objects for the LOV control and its target
view object. You will also bind attributes that will allow you to update the target view
object from the LOV-bound control.
2. Use the Select the LOV Attributes you want to display tab to choose the attributes to
display in the LOV-bound control and to determine the order in which they appear.
Define the LOV

Use to specify the binding between the attributes of the LOV view object bound to your
control and the view object that will be the target for updates. In each case, the list of
available view objects is determined by the containing panel's data model.
The LOV View Object
Select the view object from the list that you want to bind to your control. Choose
the view object appropriate for the panel you are laying out: view objects that are
constrained by a master view object may appear in the list with a number if they
have not been renamed (for example, CustomersView1), whereas master view
objects with default names appear unnumbered (for example, CustomersView).
The Target View Object

Select the view object that contains the attributes to be updated from user
selections in the LOV-bound control.
Define the LOV/Target View Object Binding
Displays a table with a list of LOV binding attributes you define. You specify the
specific attribute to update in the target view object for a particular attribute in the
LOV view object. The Add button lets you define a new binding in view object
binding table.
LOV Attributes
Displays the attributes from the LOV view object. Choose the attribute from
the dropdown menu that you want to specify as the source value.
Target Attributes
Displays the attributes from the target view object. Choose the attribute from
the dropdown that you want to update as the target value.
Remove
Click to remove an existing LOV/target attribute binding definition that you
select from the view object binding table.
22-62
Add
Click to insert another row in the view object binding table. You can choose
to bind multiple attributes through a single LOV by clicking Add.
Select the LOV Attributes You Want to Display

Use to select the attributes you want the LOV-bound control to display. You can also
reorder the list of attributes.
Lists all of the attributes in the selected view object that are available for display.
Selected Attributes
Lists all of the attributes from the view object selected to be displayed in the LOV-
bound control. Four buttons allow you to move attributes between the Available
and Selected lists.
Button Description
Click to move the attribute selected in the
Available Attributes list to the Selected
Attributes list.
Click to move all attributes in the Available
Click to move the attribute selected in the
Selected Attributes list to the Available
Attributes list.
Click to move all attributes in the Selected
Up and Down Arrows
22-63
Selected Attributes list. This affects the order
in which the attributes are displayed in the
LOV: top to bottom in the list positions view
object attributes from left to right in the JList
control or top to bottom in the JComboBox
control.
Related topics

Setting an LOV Binding Control
22-64
JClient Navigation Model Property Editor
Use this dialog to bind a JClient navigation model to your control. Select the view object on
which you want the control to navigate its rows. In the case of the JComboBox and the JList
controls, you typically select a single attribute for display in the navigation list, but you can also
choose to display multiple attributes.
Select a View
Select an available view object from the list to bind the control. The view object you
select determines the rows to display for navigation. The list of available view objects is
determined by the containing panel's data model.
Not used with the JUNavigationBar control. Lists all of the attributes in the selected view
object that are available for display by the JComboBox or JList control.
Selected Attributes
Not used with the JUNavigationBar control. Lists all of the attributes from the selected
view object to be displayed in the JComboBox or JList control. Four buttons allow you to
move attributes between the Available and Selected lists.
Button Description
Up and Down Arrows

the attributes are displayed in the control.
22-65
Related topics

Setting a Navigation Binding Control
22-66
JClient Tree Node Model Property Editor
Use this dialog to bind a JClient node model to your tree control that you can use to let users
navigate through the rows of the bound view object:
1. Use the Edit rule tab to select the view object and attributes you want to display as a
hierarchical list of nodes in the tree control. If you want the tree to display branches from
the parent nodes, you must also select an accessor to traverse the hierarchy.
2. Use the Show rules tab to determine the display order of the hierarchical list. The order
of the rules is important: the node model will populate the tree control starting from the
top of the rules list and continuing until it reaches the last rule or until it encounters a rule
whose accessor cannot find a target attribute.
Note: Typically when you work with the JClient node model your client data model must contain:
● A starting or root view object that you will use as the control binding target.
● One or more viewlink accessors from that root view object and other view objects. The
node model editor will display an allowable set of viewlink accessors for that node to
drilldown into the next level of the tree.
Edit rule
Use to define the rules that specify how to populate each level in the tree hierarchy.
Select a view
Select the view object that contains the attribute you want to use to define a node-
populating rule. The view object you choose determines the list of attributes you
can select and the list of accessors you select from to drilldown into the next level
of the tree. The list of available view objects is determined by the containing
panel's data model. If you select Defines the root for the current rule definition,
then this list displays view usage names as they appear in the application module
data model: choose a view usage, which is an instance of a view object, to define
the top-most rule. After you define the root-node rule, this field displays view
definitions for the entire package: choose a view definition, which is a reference to
a view object that contains the desired attribute and accessor.
Select a display attribute
Select the attribute that you want the rule to use to populate the nodes at a level of
the tree. The node level is determined by the sequence of the rules as they appear
in the Rules Tab.
Polymorphic restriction
22-67
Optionally, you can define a node-populating rule for an attribute whose value you
want to make a discriminator. The rule will be polymorphic because you can define
as many node-populating rules as desired for the same attribute, as long as each
rule specifies a unique discriminator value. The tree control will display a separate
branch for each polymorphic rule, with the node equal to the discriminator value of
the attribute.
Define a polymorphic definition (attribute/value)
Choose the attribute that you want to use for the polymorphic rule. This is
usually the same attribute as the attribute you selected for the view object.
Then enter the discriminator value for the selected attribute in the field
below. Currently, it is not possible to specify a range for discriminator
values; only equality discriminators are allowed. The value you enter must
be a valid attribute value.
Select an accessor
Select the accessor (defined by the data model) that specifies the link to the next
level in the tree's hierarchy. You must define another rule to display the data on
the child branch.
Defines the root
Determines whether the node level you are defining will be the first node in the
hierarchy. Only one node definition can be a root node. Unselect the checkbox if
the current node definition should not display as the root node. When selected,
Select a view list displays view usage names and not view object definition names:
this allows you to pick a view usage for the topmost rule and the node model
editor will determine the view definition to use for the root node.
Add new rule
Click to save the current tree node definition and start a new one.
Show rules
Use to reorder the rules that specify how to populate the nodes of the tree. If you want
two level in the hierarchy, you need two rules: one to define the parent node and one to
define its child branch. Each rule tells you the name of the view object, the name of the
attribute to display for the current level (can be a root node), and the accessor to use to
drilldown to the next level (not present when the rule defines leaf or terminal nodes
appears as <none> instead).
Delete Button
Click to delete the selected node-definition rule in the Rules list.

Up and Down Arrows
22-68
Click to reposition the selected attribute in the Rules list.
Click to reposition the selected node definition

rule in the Rules list. This affects the order in
which the attributes are displayed in the tree:
top to bottom in the list positions column
attributes as hierarchical levels (branches) in
the tree. The rule that defines the root node
should appear first in the list.
Related topics

Setting a Node Binding Control
22-69
JClient Panel Wizard - Welcome
Use the JClient Panel Wizard to create a Java client panel that accesses data from single
tables. The tables are predefined by view objects in the Business Components application
module that you specify.
The JClient Panel Wizard:
● Walks you through the steps of creating a Java panel

● Generates the default look and feel of the form's user interface
● Generates the Java source code required to implement the form
● Saves connection information the form will use to connect to the Business Components
application module

Clear this checkbox to skip the Welcome page when you use the JClient Panel Wizard.
Related topics

22-70
Template Selection
Use this page to select the layout and label position to be applied to your form. The wizard
displays an example of the layout in a screen capture next to your selection.
Select a Template
Single Columns (Labels Above)
Positions the labels above the fields.
Single Columns (Labels Left)
Positions the labels to the left of the fields.
Table
Displays attribute data in rows in a grid control. Labels will appear above the fields.
Number of Columns
If you choose vertical layout, by default the data form aligns all the attributes in a single
column. You can specify up to ten columns for attributes the data form displays.
Related topics

22-71
Data Model
choose defines the context for Business Component datasource you want your panel to use.

Select an AppModule
Selected Data Model
object. You will choose the view object to serve as your panel's datasource in the next
wizard step.
Related topics

22-72
Panel View
Use this page to select the Business Components view object that defines the set of attributes
you want your panel to use. Go back to the previous page if you want to change the list of
available view objects.
Select a View Object

Select the view object that represents the table in the query. The view object you select
is the datasource for the panel; it defines the set of attributes that you can choose to
display.
The contents of these lists are based on the view objects included in your application
module's data model.
Show hidden attributes

Lets you handle the Form Type control hint setting for attributes of the selected view
object. The business components developer can set control hint properties for attributes
of a view object. If the Form Type property of an attribute is set to Detail (default), this
checkbox is ignored. If the Form Type property is set to Summary, then this checkbox
lets you select attributes that would otherwise be hidden for use in the generated form:
❍ When selected, attributes with Form Type property set to Summary will not appear
in the Selected Attributes list on the next page of this wizard, but these attributes
will appear in the Available Attributes list.
❍ When unselected, attributes with Form Type property set to Summary will not
available for selection on the next page of this wizard (they will be hidden).
Related topics

22-73
Attribute Selection
Use this page to select the attributes you want to include on your form.
This field lists all of the attributes in the view object that are available to be displayed on
a form.
An asterisk (*) in front of a attribute indicates that the attribute represents the primary key
and will be used by the query, whether or not it is displayed on the form.
The numbers listed after each attribute define attribute information such as, the number
of characters in a text item, or the scale and precision of a numeric item.
Selected Attributes
Button Description
Up and Down Arrows

22-74
Related topics

22-75
File Names
Use this page to name the package and panel of your form.
Package Name
Panel Name
Enter the name of the java class that defines the form's panel.
Related topics

22-76
JClient Panel Wizard - Finish
Use this page to review information you have entered about your form.
Click Finish to generate the form.
Related topics

22-77
JClient View Object Model Property Editor
Use this dialog to specify a view object data binding for your control. Select the view object on
which you want the control to operate. In the case of the scrollable controls, you can also
decide whether or not to use an estimated row count obtained from the view object.
Select the View

Use Estimated Rowcount
Not available on all controls. Select to use the row count from the view object cache. This
option appears selected by default because when unselected (thereby forcing the actual
rowcount) it may trigger an additional query. This option is available for these controls:
❍ JProgressBar: determines whether the progress bar indicator is proportional to the
number of rows displayed out of the full range of the view object. Select if you
want to set the indicator size based on the full view object row count.
❍ JSlider: determines whether the size of the slider thumb is proportional to the
number of rows displayed out of the full range of the view object. Select if you
want to set the thumb size based on the full view object row count
❍ JScrollBar: determines whether the size of the scrollbar thumb is proportional to
the number of rows displayed out of the full range of the view object. Select if you
want to set the thumb size based on the full view object row count.
Not applicable in the case of JUNavigationBar and JUStatusBar controls.
Related topics

Setting a View Binding Control
22-78
New Application
Use this dialog to create a new runnable application class and optionally create a frame class
that you can layout with UI controls. The generated class contains a main() method.
Name
Displays the default name assigned to the application class. To rename it, click the field
and enter a new name.
Package
Displays the default name assigned to the package. Enter the desired package name to
which the application class will belong or click Browse to open the package browser and
select another package.
Extends
Displays the name of the class that this application class extends. By default, all Java
classes extend java.lang.Object. To select a different superclass from your existing class
or source path click Browse.
Optional Attributes
Add Default Frame
Select to add a default frame to your application.
New Empty Frame
Select to run the New Frame dialog after you have finished filling out this
dialog. This option is only available if you select Add Default Frame.
Existing Frame
Select and enter the fully qualified classname of an existing frame into the
adjacent field to use a previously created frame with the application. This
option is only available if you select Add a default frame.
Center Frame On Screen
Select to center the application on the screen at runtime. This option is only
available if you select Add Default Frame.
Do Not Add Default Frame

Select if you do not want a frame associated with your application. You would use
this option if you were, for example, creating a server-side application with no user
interface.
22-79
New Dialog
Use this dialog to create a dialog box.
Name
This field displays the default name assigned to the class. Enter the desired class name.
Package
This field displays the default name assigned to the package. Enter the desired package
name to which the dialog class will belong or click Browse to open the package browser
and select another package.
Extends
Displays the class on which the dialog will be based. To use your own base class, click
Browse. This action opens the package browser allowing you to select a specific base
dialog class.
22-80
New Frame
Use this dialog to create a Swing-style frame that you can layout using UI controls. If you want
to create a databound frame for use with Business Components, see JClient objects.
Name
Package
name to which the frame class will belong or click Browse to open the package browser
Extends
Displays the class on which the frame will be based. To use your own base class, click
frame class.
Optional Attributes
Title
The title of a frame. This style frame can optionally serve as a parent window in an
MDI-style application.
Menu Bar
Creates a menu bar with the commands File | Exit and Help | About
Tool Bar
Creates a tool bar with Open, Save, and Help buttons.
Status Bar
Creates a status bar where you can provide process information to your user.
About Box
Creates an About Box for your project, where you can provide version and author
information and display an image (usually the application icon).
22-81
New Gallery - JClient Objects Category
From the JClient Objects category in the New gallery you can quickly create JClient forms-type
applications and panels to create databound Java clients. All of the options in this category
launch wizards. To use these wizards, you must have an existing Business Components for
Java (BC4J) project that describes the client's data model. Refer to the documentation if your
workspace does not yet contain a business components project.
JClient Form
Launches the JClient Form Wizard. This wizard helps you quickly create several different
types of JClient forms to build databound Java applications. You can specify single table
forms or master-detail related forms. Complete the wizard to add a customized JClient
application to your project. You will be able to run the application from the generated
frame.java file without changes.
JClient Panel
Launches the JClient Panel Wizard. This wizard helps you create a .java file for a
databound JClient panel. You specify the view object and attributes you want the panel
to display from your business components project. Use the Code Editor to add the new
JClient panel to an existing runnable frame in your JClient project.
JClient Empty Panel

Launches the JClient Empty Panel Wizard. This wizard adds a skeleton .java file for an
empty JClient panel to your project. The generated panel contains JClient-specific code
to generate a JClient panel binding. It contains no databound controls. Use the
JDeveloper UI Editor to layout the panel with databound controls that you select from the
Swing panel of the Component Palette.
JClient Empty Frame
Launches the JClient Empty Frame Wizard. This wizard adds a skeleton .java file for a
JClient frame to your project. The generated frame contains JClient-specific application
bootstrap code that defines an application module connection. The frame does not
create JClient panels. Use the JDeveloper Code Editor to set JClient panels that you
want the frame to layout and the code to make the frame runnable.
JClient Graph
Launches the JClient Graph Wizard. This wizard adds a panel.java file to your project
that contains a graph component. Use this wizard to select the type of graph and specify
the graph's datasource from a business components project.
JClient Java Web Start
Launches the JClient Java Web Start Wizard. This wizard adds several versions of a
22-82
Java Web Start .jnlp file to your project. It also creates deployment profiles for the client
and business component libraries. Use this wizard to create a JNLP file and WAR files
that you can use with your JClient project to run and deploy JClient applications. Java
Web Start is an application deployment software developed by Sun Microsystems that
lets you maintain JClient applications on the web server, while users download and run
on their client machines.
JClient Data Model
Launches the JClient Data Model Wizard. This wizard adds a JClient project
configuration (.cpx) file to your project with a client data model definition you create. The
client data model specifies the Business Component application module context for
JClient forms. The other JClient wizards let you invoke the JClient Data Model Wizard so
that you may create a new client data model definition.
Related topics

About the Frame or Applet Class in JClient
About Data Panels in JClient
22-83
New Panel
Use this dialog to create a panel.
Name
Package
name to which the panel class will belong or click Browse to open the package browser
Extends
Displays the class on which the panel will be based. To use your own base class, click
panel class.
22-84
Web Application Reference
● BC4J Web Application Wizard - Welcome
● BC4J Web Application Wizard - Web Site Information
● BC4J Web Application Wizard - Business Application
● BC4J Web Application Wizard - View Form
● BC4J Web Application Wizard - View Links
● BC4J Web Application Wizard - Finish
● Configuration Manager Dialog
● Configuration Manager - Application Module Tab
● Configuration Manager - Properties Tab
● Data Tags Wizard Pages - ApplicationModule
● Data Tags Wizard Pages - DataSource
● Data Page Wizards - Welcome
● Data Page Wizards - Business Application
● Data Page Wizards - Finish
● New Gallery - BC4J JSP Category
● New Gallery - Objects Category
● New JSP Dialog
● New Project from Web Module Wizard - Welcome
● New Project from Web Module Wizard - Web Module Location
● New Project from Web Module Wizard - Web Module Document Root
● New Project from Web Module Wizard - Finish
● New Web Bean Dialog
● Preferences - Web Browser
● Servlet Wizard - Welcome
● Servlet Wizard - Servlet Details
● Servlet Wizard - Servlet Parameters
● Servlet Wizard - Mapping Details
23-1
● Servlet Wizard - Finish
● Web Application 2.2 Deployment Descriptor - Standard DD
● Web Application 2.2 Deployment Descriptor - Servlets
● Web Application 2.2 Deployment Descriptor - Servlet Settings - General
● Web Application 2.2 Deployment Descriptor - Servlet Settings - Init Params
● Web Application 2.2 Deployment Descriptor - Servlet Settings - Define Parameter
● Web Application 2.2 Deployment Descriptor - Servlet Settings - Security Roles
● Web Application 2.2 Deployment Descriptors - Servlet Mappings
● Web Application 2.2 Deployment Descriptor - Create Servlet Mapping
● Web Application 2.2 Deployment Descriptor - Context Init
● Web Application 2.2 Deployment Descriptor - Define Parameter
● Web Application 2.2 Deployment Descriptor - MIME Mappings
● Web Application 2.2 Deployment Descriptor - Create MIME Mapping
● Web Application 2.2 Deployment Descriptor - Tag Libraries
● Web Application 2.2 Deployment Descriptor - Declare Tag Library
● Web Application 2.2 Deployment Descriptor - Login
● Web Application 2.2 Deployment Descriptor - Resource Refs
● Web Application 2.2 Deployment Descriptor - Create Resource Reference
● Web Application 2.2 Deployment Descriptor - Preview
● Web Application 2.2 Deployment Descriptor - Create Security Role
● Web Bean Editor - Properties
● Web Bean Editor - Web Bean Class
● Web Bean Editor - Add Property
● Web Bean Editor - Edit Properties
● Web Object Manager Dialog
● Web Object Manager - Add Web Bean
● Web Object Manager - New Class from Web Bean
23-2
Business Components JSP Application Wizard -
Welcome
Use the Business Components JSP Application Wizard to create a Business Components JSP
application consisting of a set of JavaServer Pages (JSPs) that connect to an Oracle Business
Components application module.
To create a JSP application, you must:
● Provide information about your JSP application and its web site.
● Provide information about the Business Components application module you want your
JSP application to use.
● Select the view objects you want your JSP pages to use.
● Select the page templates you want to use to generate the JSP pages.
The Welcome page is informational only and may be skipped.

Clear this checkbox to skip the Welcome page next time you use the Business
Components JSP Web Application Wizard.
Related topics

23-3
Web Site Information
Use the Web Site Information page to name your Business Components JSP application,
specify the directory in which to place its files, and provide a description of it for informational
purposes.
Web application name

Enter the name of the JSP application you are creating.
Project server root
Displays the document root directory of your web server. This field is read-only. To
change the document root directory, you must edit the properties of the project
containing this JSP application. To do this, find the project within the Navigator, right-
click it, and choose Properties from the pop-up menu.
Document root
Enter the name of the directory to contain your JSP application files. The application
directory goes under your Project HTML Root, so you should not enter a full path with the
name, just the path relative to the Project HTML Root. JDeveloper creates the
application directory if it doesn't exist (and any non-existent directories in the relative
path as well).
War file name
Enter the name for the web application archive file (.war) you want the wizard to
generate. If you do not supply a name a default will be provided.
Application description
Enter a description of your JSP application. Note, the tab key does not change focus
when your cursor appears in this field. To change the focus using the keyboard, press
the Ctrl-Tab keys or click in any other field and press the Tab key.
23-4
Business Application
Use the Business Application Information page to generate a JSP application for a specific
application module and deployment configuration.

Optionally select a project containing a Business Components application module. If your
workspace contains many projects, the Application Module list can take a long time to
populate. Selecting a project can speed up that process.
Application Module
Select an application module. The application module selected must include one or more
view objects. JDeveloper uses the application module name and package to derive the
JSP application property file name.
objects. You will choose the view object to serve as the JSP application's datasource in
the next wizard step.
Configuration
Displays the deployment configurations available for the selected application module.
From the dropdown menu, choose the configuration that your want your JSP to use to
connect to the deployed application module. You can view configuration parameters by
right-clicking the application module in the Business Components project and choosing
Configurations.
23-5
View Form
Use the View Form page to select which view objects you want to generate JavaServer Pages
(JSP) pages for and which JSP forms are generated for each view object selected.
By default, JSP pages for all views are generated, including all four JSP forms for each view
object. These JSPs are built using JDeveloper's data tags.
View Objects
Select the view object for which you want to modify JSP form generation settings. The
page displays the current JSP form generation settings for the selected view object. To
see the settings for another view object, make another selection in the View Objects list.
Form Options
Unselect the form options to modify the JSP form generation settings. If you do not
change the default settings, all four JSP forms will be generated. You must unselect the
checkbox for a particular form if you do not want to generate it in the JSP page.
Generate page
Selected by default. Generates JSP pages for the selected view object. Unselect
to prevent a JSP page and all forms from being generated.
Query form
Selected by default. Generates a JSP query form for the selected view
object. Unselect to prevent the query form from being generated.
Browse form
Selected by default. Generates a JSP browse form for the selected view
object. Unselect to prevent the browse form from being generated.
Edit form
Selected by default. Generates a JSP edit form for the selected view object.
Unselect to prevent the edit form from being generated.
File Name
Enter the desired base name for your generated JSP pages. For certain form types, the
wizard will generate multiple JSP pages like EmpView_Query.jsp and
EmpView_QuerySubmit.jsp, where EmpView is the base name. By default, the wizard
will use the value of the FILE_NAME property on the View Object. If this property is not
defined, the view name specified when the view object was created is used.
23-6
View Links
Use the View Links page to generate JSP pages that use single tables or master-details tables.
The application module you selected in a previous page contains user-defined view links that
you may or may not want your generated JSP pages to use. If you want to generate master-
detail JSP pages, you must select at least one view link.
View Link
Select the view link for which you want to modify the JSP page generation setting. The
page displays the current JSP form generation settings for the selected view link. To see
the settings for another view link, make another selection in the View Link list.
Form Options
Generate page
Selected by default. Generates a JSP page for the selected view link. Unselect to
prevent a JSP page from being generated.
File Name
Enter the desired base name for your generated view link JSP pages.
23-7
Business Components JSP Application Wizard -
Finish
Use the Finish page to complete the creation of your new Business Components web
application by clicking Finish.
23-8
Configuration Manager
The Configuration Manager lets you manage configuration information for any application
module in your Business Components project. The editor generates a .xcfg file that contains
one or more configurations. You use the Configuration Manager to create or edit individual
configurations by selecting:
● Server deployment mode for the application module
● Connection name from a list of existing connections created in the Connection Manager.
You can choose to use either a JDBC URL (default for Local mode) or a JDBC
DataSource. If deploying web applications or BC4J applications as EJB session beans to
Oracle9iAS Containers for J2EE (OC4J), all data sources are defined in the data-
sources.xml file. If you choose to use a JDBC DataSource connection, you must
specify a Datasource Name that matches the <location> value in the
x:\<ORACLE_HOME>\j2ee\config\data-sources.xml file.
● Application module usage properties
The configurations defined by the .xcfg file allows Business Component clients (currently,
business component-enabled JSP pages) to interact with specific, deployed application
modules.
Names
Displays the list of existing configurations defined by the.xcfg file. Select a configuration
from the list to create, edit, delete, or copy a configuration.
Property
Displays the properties associated with the configuration you select in the Names
list.
Value
Displays the value of each property for the configuration you select in the Names
list.
New
Displays the Configuration Editor to enable you to create and save a new configuration to
23-9
the .xcfg file for the application module you selected in the Navigation pane.
Copy
Copies the configuration you select in the Names list. You can the click Edit to modify
the copy in the Configuration Editor.
Edit
Displays the Configuration Editor with the information for configuration you select in the
Names list. You can modify the name or settings, and then save your changes.
Delete
Deletes the configuration you select in the Names list from the .xcfg file.
Note: If you delete an existing configuration, references to the deleted configuration by client
applications will need to be replaced with a new configuration.
23-10
Configuration Manager — Configuration Application
Module Tab
You display this page for the Business Component Browser - Connect dialog or the Business
Component Configuration dialog (when you right-click the application module in your Business
Components project and choose either Test or Configurations from the popup menu).
● If you displayed the Business Component Browser-Connect dialog, you use this page to
select an already defined configuration, connection, and application module to display its
view objects in the Business Component Browser.
● If you displayed the Business Component Browser Configuration dialog, you use this
page to create a new configuration by specifying its name, connection information, and
application module. Clients of deployed business components will use the configuration
to specify a data source location.
Configuration Name
The Business Components Configuration dialog displays the name of the configuration
that will appear in the bc4j.xcfg file. If you change the name of an existing configuration,
make sure that all references to the configuration by client applications are also changed.
In the Business Components Browser - Connect dialog, you choose a previously defined
configuration or if one has not yet been defined, use JDeveloper's default configuration.
To create a configuration to display in the Business Components Browser - Connect
dialog, right-click the application module in the Business Components project and
choose Configurations...
Middle Tier Server Type
Choose the server type from the dropdown menu and provide the required server
information:
Local
Select Local (web module) if the Business Components application module's
business logic resides on the same machine as the client application.
Visibroker
Select Visibroker when you want to deploy the Business Components to Inprise
23-11
VisiBroker.
This deployment type provides the following three ORB Connection Type options:
■ Use Collocated to connect locally

■ Use Naming Service to connect using a naming service (do this by setting
the connection name and naming service root)
■ Use Binding to connect by providing an address for the middle tier
Note: If you are connecting using the Bind mode, see Starting a Business
Components Application Using Bind Mode. If you are connecting using the
naming service, see Starting a Business Components Application Using the
Naming Service.
Oracle9i EJB
Select when you deploy the application module to Oracle9iAS. You will need to
choose the OC4J Application Server and Application Name.
WebLogic EJB
Select when the application module resides on a BEA WebLogic 6.x server. You
will need to set the Application Server and JNDI path.
Note: For application servers to be populated in the dropdown list, you must have
already created your OC4J and WebLogic application server connections.
JDBC Connnection
You can choose to connect to a JDBC URL or a JDBC DataSource.
JDBC URL
Displays the JDBC URL for the connection as defined in the Connection Manager
for your BC4J project. JDeveloper displays connections that the workspace
defines in the Connections directory in the Navigator. Choose a previously defined
JDBC connection from the dropdown menu. This option is displayed only if you
choose Local, Visibroker, or WebLogic from the Middle Tier Server Type menu.
JDBC DataSource
Enter the JNDI name of the data source you will use in the following form:
jdbc/OracleCoreDS
where jdbc/OracleCoreDS must match the <location> value in the
23-12
x:\<ORACLE_HOME>\j2ee\config\data-sources.xml file. For EJBs,
this is the Data Source name you have specified to use in the Business
Components Deployment Wizard to build the BC4J project. For local or web
modules, make sure that you also edit the data-sources.xml file to include the
JDBC data source name you specify here. See About OC4J Data Sources for
more information.
Username
Optionally, enter the database user name to access the data source. The
value entered in this field takes precedence over the user name specified in
the data source file.
Password
Optionally, enter the database password to access the data source. The
value entered in this field takes precedence over the value in the data
source file. In the example below, tiger is the password.
Note: If no username or password for the data source is specified, you must enter
a valid username and password here to access the database.
23-13
Configuration Manager — Properties Tab
Use the Configuration Properties page to specify the settings for individual application module
configurations.
Configuration Name
Displays the name of the configuration that will appear in the .xcfg file. If you change the
name of an existing configuration, references to the configuration by client applications
will also need to be changed.
Property Name
Displays the names of the properties associated with the configuration.
Note: Click a property name to see a description of the property in the editor.
Value
Enter the values for the corresponding properties of the configuration into the Value
column. Some of the properties may have default values.
RELEASE_MODE
The mode that determines the state of the application module instance servicing the
HTTP requests. Type the value: Stateful, Stateless, or Reserved depending on how you
want to handle the state of the application module.
❍ Stateful preserves the application module instance's state in the database
between page-processing requests. This permits the application to maintain a

user's data without involving a single application module instance for long periods
of time.
Note: Stateful mode provides failover support for the HTTP session and is the
preferred choice when the application module uses a standard JDBC connection.
❍ Stateless does not preserve the state of the application module instance between
page-processing requests. The instance is immediately released when a JSP
page terminates.
Note:Select this option when you expect many users to access your JSP
application simultaneously. The stateless option allows more users to access a
JSP application simultaneously at the cost of requiring the user to reconnect to a
new application module instance every time a JSP page is invoked (or re-invoked).
❍ Reserved allocates the application module instance for the duration of the browser
23-14
session. The instance is released only at the end of the session. This mode is
provided primarily for compatibility with certain application module definitions.
Failover is not supported in this mode.
Note: Reserved mode is primarily useful when the application module requires a non-
standard JDBC connection definition. Failover is not supported in this mode.
Add
Inserts an empty property field in the list. Use to create new properties.
Remove
Lets you remove properties that you added to the list.
23-15
ApplicationModule
Use this page to specify the application module usage for the <jbo:ApplicationModule> data
tag. You will select a specific application module and deployment configuration.

Optionally, select a project containing a Business Components application module. If
your workspace contains many projects, the Application Module list can take a long time
to populate. Selecting a project can speed up that process.
Application Module
view objects. The application module name will appear as the id attribute for the
ApplicationModule data tag.
objects. You will choose the view object to serve as a datasource when you insert a
<jbo:DataSource> data tag into your JSP file.
Configuration
connect to the deployed application module. The configuration name will appear as the
config attribute for the ApplicationModule data tag. You can view configuration
parameters by right-clicking the application module in the Business Components project
and choosing Configurations.
Related topics

Defining Business Component Runtime Properties in the bc4j.xcfg File
23-16
DataSource
Use this page to specify the view object for your <jbo:DataSource> data tag. The view object
you select is contained by a specific application module that you have already defined for your
JSP file through the <jbo:ApplicationModule> data tag.
Application Id
Select the id of an existing application module defined by the <jbo:ApplicationModule>
data tag of your current JSP file. The application module you select must include one or
more view objects.
View Object
Select the view object that you want to specify for your DataSource data tag. The view
object name will appear as the view object attribute for the DataSource data tag.
Related topics
23-17
Data Page Wizard — Welcome
Use the Data Page Wizard to create a new page to insert into your existing JSP application that
connect to a Business Components application module. You can choose from these JSP page
templates:
Browse Form
Use this page template to browse records from a data source represented by a view
object. A Browse Form consists of a single JSP page named viewobject_Browse.jsp
where viewobject is the name of the view object for which the Browse Form was
generated.
Browse and Edit Form
Use this page template to browse and edit records from a data source represented by a
view object. A Browse and Edit Form consists of three JSP pages named
viewobject_Edit.jsp, viewobject_SubmitEdit.jsp and viewobject_BrowseEdit.jsp where
viewobject is the name of the view object for which the forms were generated.
Query Form
Use this page template to define a query to a data source represented by a view object.
A query form consists of two JSP pages named viewobject_Query.jsp and
viewobject_QuerySubmit.jsp where viewobject is the name of the view object for which
the query form was generated. The viewobject_Query.jsp simply renders a standard
HTML form with text input fields, which correlate with the view object's attributes. The
form has it's ACTION set to viewobject_QuerySubmit.jsp. The
viewobject_QuerySubmit.jsp performs the following functions:
❍ Processes the incoming HTML parameters
❍ Sets the Where clause based on the parameter values
❍ Issues a query via the RowsetIterate tag and renders all the rows which
correspond to the Where clause
Note: The processing code in viewobject_QuerySubmit.jsp is provided as a basic example of

how to process HTML form parameters and set Where clauses using the data tags.
Advanced parameter parsing will require additional coding enhancements to the generated
viewobject_QuerySubmit.jsp page.
23-18
To create a JSP page with this wizard, you must:
● Select the view object you want your JSP page to use.


Clear this checkbox to skip the Welcome page next time you use the Data Page Wizard.
Related topics

Generating a JSP Application Based on BC4J View Objects
23-19
Use the Business Application Information page to create a JSP data page for a specific
application module, view object, and deployment configuration.

Application Module
Open the application module that contains the view object you want. Select the view
object. You can select a view object from any application module associated with a
Business Components project that is in the same workspace as the JSP project in which
you are inserting the web page.
Configuration
connect to the deployed application module. You can view configuration parameters by
right-clicking the application module in the Business Components project and choosing
Configurations
23-20
Data Page - Finish
Use the Finish page to complete the insertion of the JSP page by clicking Finish.
23-21
New Gallery - BC4J JSP Category
From the BC4J JSP category in the New Gallery you can quickly create JSP pages based on
BC4J page templates for web application clients. All of the options in this category launch
wizards.
To use these wizards, you must have an existing Business Components for Java (BC4J)
project that describes the client's data model. Refer to the documentation if your workspace
does not yet contain a business components project.
Business Components JSP Application

Launches the Business Components JSP Application Wizard. This wizard helps you
quickly create several different types of JSP forms to build databound web applications.
You can generate query, edit, and browse forms for any view object that your business
components project defines. Complete the wizard to add a JSP web application to your
project. You will be able to run the application from the generated .jsp files without
changes.
Browse Form
Launches the Data Page Wizard for a browse form. This wizard helps you create a JSP
page to browse records from a datasource represented by a view object. A Browse Form
consists of a single JSP page named viewobject_Browse.jsp where viewobject is the
name of the view object for which the Browse Form was generated. You can run the
Browse.jsp in JDeveloper.
Browse & Edit Form

Launches the Data Page Wizard for a browse and edit form. This wizard helps you
create JSP pages to browse and edit records from a datasource represented by a view
object. A Browse and Edit Form consists of several pages with the following names,
where viewobject is the name of the view object for which the forms are generated:
❍ A single JSP page named viewobject_BrowseEdit.jsp. You can run this form in
JDeveloper.
❍ Two JSP pages named viewobject_Edit.jsp and viewobject_SubmitEditForm.jsp.
The BrowseEdit.jsp invokes these pages.
Query Form
Launches the Data Page Wizard for a query form. This wizard helps you create a JSP
page to view queried records from a datasource represented by a view object. A Query
Form consists of a single JSP page named viewobject_QueryView.jsp where viewobject
is the name of the view object for which the Query View Form was generated. You can
23-22
run the QueryView.jsp in JDeveloper.
Related topics

23-23
New Gallery - Objects Category
From the Objects category in the New Gallery you create new files for application, class, dialog,
frame, IDL, panel, SQL, and SQLJ class.
Application
Opens the New Application dialog. Complete the dialog to add a skeleton
application.java file and optional frame.java file to your project. Use the Code Editor to
develop your application class.
Class
Opens the New Class dialog. Complete the dialog to add a customized class.java file to
your project. The skeleton code for your new class can include a main() method and a
default public constructor, depending on the options you select. Use the Code Editor to
develop your class.
Dialog
Launches the New Dialog dialog. Complete the dialog to add the skeleton dialog.java file
to your project. Use the Code Editor to develop your dialog class.
Frame
Opens the New Frame dialog. Complete the dialog to add a customized frame.java file to
your project. The skeleton code for your new frame can contain a menu bar, toolbar,
status bar, and about box depending on the options you select. Use the Code Editor to
develop your frame class and the UI Editor to layout panels for the frame.
IDL File
Adds an empty IDL file to your project named untitled#.idl, which opens in the Code
Editor. Once the file appears in your project, you can rename the file by choosing File |
Rename. Use the Code Editor to modify the IDL file.
Panel
Opens the New Panel dialog. Complete the panel to add a skeleton panel.java file to
your project. Use the Code Editor to develop your panel class.
SQL File
Adds an empty SQL file to your project named untitled#.sql, which opens in the Code
Editor. Once the file appears in your project, you can rename the file by choosing File |
Rename. Use the Code Editor to modify the SQL file.
SQLJ Class
Opens the New SQLJ Class dialog. Complete the dialog to add a customized class.java
file to your project. The skeleton code for your new class can include a main() method
and a default public constructor, depending on the options you select. Use the Code
23-24
Editor to develop your class.
Related topics
About Containers
23-25
New JSP
Use this dialog to provide the name and location of the new JSP page to add to your project.
Name of JSP
The name of the .jsp file that you want to save to your project.
Directory
The full path name of the directory where you want to save the .jsp file. If you don't want
to use the default public.html folder in your project's directory, click Browse button to
locate another directory. Saving your web application files to the public.html folder allows
you to work easily with the deployment profiles generated by JDeveloper.
23-26
New Project with Web Module Wizard - Welcome
Using the New Project with Web Module Wizard, you can create a project in JDeveloper that
contains the directory structure of an J2EE web module. The New Project with Web Module
Wizard:
● Lets you specify the document root of the web module.

● Specify a project name to add to the JDeveloper mywork folder
In JDeveloper the default document root is the public.html folder in the projects directory of a
workspace. The wizard is not reentrant. To alter project attributes later, use the Project
Settings.

Clear the checkbox to skip the Welcome page when you use the wizard.
23-27
Location
Use the Location page to name your project and define its directory.
Directory Name
Enter a new directory name for the project or browse to select an existing one. By
Project File Name
generic name Project is simply incremented. The name you supply here will identify the
project for you in the Navigator.
23-28
Document Root
Use the Document Root page to specify the location of the document root for your web module.
JDeveloper will create a new project in the mywork directory.
Root Directory
Enter the full path name for the document root or browse to select an existing one.
23-29
New Project from Web Module Wizard - Finish
Click Finish to create the project and close the wizard.
23-30
New Web Bean
Use this dialog to provide the information to define the web bean class.
Note: If you have an existing web bean file with a syntax error and you attempt to overwrite it using
the same package and class name, JDeveloper will not permit you to save the file. In this case, you
will receive a parse error unless you web bean is a well-formed class.
Package Name
Enter the name of the package to contain your web bean. If the package doesn't exist, it
is created.
Class Name for new Web Bean
Enter the class name of your new web bean.
Add Data Source Support
Select to generate a web bean class that supports connection to OC4J data sources.
This results in your web bean extending the class
oracle.jdeveloper.html.DataWebBeanImpl rather than the class
oracle.jdeveloper.html.WebBeanImpl.
Description
Enter a description of your new web bean.
23-31
Preferences - Web Browser
Use this panel to specify the web browser for the web server JDeveloper will use when you run
web applications. This setting is project-specific: it applies to the current project that contains
your web application (JSP pages and servlets).
Browser command line

Enter the full path name of the browser executable file to run your web application. If you
do not specify a browser, the web server will use your machine's default browser to run
the web application.
23-32
HTTP Servlet Wizard - Welcome
Using the HTTP Servlet Wizard, you can create HTTP servlets that can return any MIME type
to the requesting client, including images, XML, and HTML. The HTTP Servlet wizard:
● Walks you through the steps of creating an HTTP servlet.

● Generates the Java source code and skeleton HTTP servlet methods for the servlet.
By default, this wizard creates a servlet that dynamically generates HTML content (MIME type:
text/html). You can change to another MIME type by passing the type to the
ServletReponse.setContentType method in the servlet's Java file.

Clear the check box to skip the Welcome page when you use the Servlet wizard.
23-33
Servlet Details
Use this page to provide information about the your servlet class.
Package
Enter a name for the package. For example: MyPackage
Class
Enter a name for the servlet class. For example: MyHTTPServlet
Generate Content Type
Choose the MIME type for the servlet-generated content. By default, the HTTP Servlet
Wizard creates a servlet that dynamically generates HTML content (MIME type:
text/html). The wizard adds the setContentType method in the servlet's Java file with the
selected type to set.
Generate Header Comments
Select if you want the HTTP Servlet Wizard to comment the servlet class.
Single Thread Model
If one of the servlet's do methods cannot be implemented in a thread-safe manner, the
servlet can declare that it implements the javax.servlet.SingleThreadModel interface.
Select this checkbox to guarantee that the do methods are not called concurrently. The
SingleThreadModel interface does not contain any methods but simply acts as a flag
which indicates that the Servlet is not thread-safe.
Implement Methods
Select those methods for which you want to generate skeleton code in your servlet class.
doGet() method
Select to generate a doGet method, which handles GET and conditional GET and
HEAD requests.
doPost() method
Select to generate a doPost method, which handles POST requests.
doPut() method
Select to generate a doPut method, which handles PUT requests.
doDelete() method
Select to generate a doDelete method, which handles DELETE requests.
23-34
Servlet Parameters
Use the Servlet Parameters page to enter the parameters to be passed to the servlet. The
wizard will generate the code needed for the servlet to read the parameter values at runtime.
Click New to open a new parameter entry line. Click Remove to remove an existing parameter.
During runtime, you can pass the parameters and values in the URL from a browser or HTML
form, or in a name=value pair within the <servlet> tag of an SHTML file. For example:
http://serverHostName:port/servlet/MyHTTPServlet?Greeting=Hello
You can also pass in additional parameters and get them programmatically by calling the
method ServletRequest.getParameter within your servlet's Java code.
Name
Enter the servlet parameter name.
Type
Select the servlet parameter type.
Variable
Enter the parameter variable name.
Description
Enter description of the servlet parameter.
Default
Enter a default parameter value.
23-35
Mapping Details
Use the Mapping Details page to provide mapping information about the your servlet class.
Specify a name and mapping for the servlet

Select to enter the mapping details.
Mapping Details
Name
Enter a name for the servlet. For example: myservlet
URL Pattern
Enter a URL for the servlet class. For example: /myservlet
23-36
Servlet Wizard - Finish
Click Finish to create the servlet and close the wizard.
23-37
Web Application 2.2 Deployment Descriptor -
Standard DD
Use this panel to specify general information about the deployment descriptor file you use this
dialog to create. The web.xml file generated by this wizard describes how files contained by
your application's web archive (.war) file are used by the runtime web server and web browser
to implement your web-based application.
You configure your web application's deployment descriptor to manage your web application
resources at runtime. In addition to general descriptor information, you should use this page to
set the session timeout for your web application.
Display Name
Optional, enter the name that you want to display in JDeveloper's message window
when use JDeveloper to deploy your application. The display name may also be used by
other graphical configuration tools. Corresponds to the <display-name> tag in the
web.xml file.
Description
Optional, enter a description of your web application. This provides useful documentation
for the web application descriptor file you use this dialog to create. Corresponds to the
<description> tag in the web.xml file.
Specify Session Timeout (in minutes)
Optional, enter an integer value of minutes of inactivity are required before you want to
force your web application's sessions to expire. Corresponds to the <session-timeout>
tag of the <session-config> subelement. Note, this value can be overridden for individual
sessions by means of the setMaxInactiveInterval() method of the
javax.servlet.http.HttpSession interface.
You can also refer to the following references for assistance:

23-38
23-39
Servlets
Use this panel to configure the deployment descriptor details for individual servlet files in your
current project.
Details
Click to edit the deployment descriptor settings for an individual servlet that you select
from the list.
23-40
Servlet Settings - General
Use this panel to define declarative data for your servlet. You can optionally specify the
sequence by which the web server will initialize your servlets upon startup.
Display Name
Optional. Enter a short name intended to be displayed by a GUI tool. This field
corresponds to the <display-name> subelement.
Description
Optional. Enter the text description of the servlet. This field corresponds to the
<description> subelement.
Load this Servlet When the Web Application is Started
Optional. Select this option when you want to specify the servlet initialization order the
web server will follow when it starts up. The optional contents of this element must be a
positive integer that indicates the order in which the servlet should be loaded. Servlets
you assign a lower integer value will be loaded before ones with a higher integer value.
This field corresponds to the <load-on-startup> subelement.
Positive Integer Specifying Load Order
If no value is specified, or if the value specified is not a postive integer, the web server
can load the servlet in any sequence.

23-41
Servlet Settings - Init Params
Use this panel to configure initialization parameters for a specific servlet or JSP in your
application.
The subelement <init-param> is not a required element of the web.xml deployment descriptor
definition.
Servlet/JSP Initialization Parameters

Displays the list of intialization parameters you have configured for specific servlet and
JSP files.
Add
Click to configure a new initialization parameter for your servlet or JSP.
Delete
Click to remove an existing initialization parameter that you select from the
parameter definition table.
Name
Enter the name of the initialization parameter that you want to add. Corresponds to the
<param-name> tag of the <init-param> subelement.
Value
Enter the value of the initialization parameter. Corresponds to the <param-value> tag of
the <init-param> subelement.
Description
Optional, enter a description of the initialization parameter. Corresponds to the
<description> tag of the <init-param> subelement.

23-42
23-43
Define Parameter
Use this dialog to configure a new initialization parameter for your servlet.
Servlet/JSP Initialization Parameters

Displays the list of intialization parameters you have configured for specific servlet and
JSP files.
Add
Click to configure a new initialization parameter for your servlet or JSP.
Delete
Name
Enter the name of the initialization parameter that you want to add. Corresponds to the
<param-name> tag of the <init-param> subelement.
Value
Enter the value of the initialization parameter. Corresponds to the <param-value> tag of
the <init-param> subelement.
Description
<description> tag of the <init-param> subelement.

23-44
Servlet Settings - Security Roles
Use this panel to link a security role name defined by the subelement <security-role> to an
alternative role name that appears in your servlet's application code. This reference lets you
configure the servlet at deployment without needing to change application code.
The subelement <security-role-ref> is not a required element of the web.xml deployment

descriptor definition.
Security Role Links

Displays the list of security roles that you have associated with an alternative security
role name.
Add
Click to define a new security role link for your web application.
Delete
Click to remove an existing link definition from the Security Role Links list.
Role Name
Required, enter the name of the security role that appears in your servlet code that you
want to associate with an alternative name. This field corresponds to the <role-name>
tag of the <security-role-ref> subelement.
Role Link
Required, enter the name of the security role that you want to link to as the alternative
name. This field corresponds to the <role-link> tag of the <security-role-ref> subelement.
The name you enter must be defined by the <role-name> tag in the <security-role>
subelement of the generated web.xml file. To view existing security role names, select
the Security node from the tree on the left of this dialog.
Description
Optionally, enter the text description of the security role that you want to associate with
an alternative security role name. This field corresponds to the <description> tag of the
<security-role-ref> subelement.

23-45
23-46
Web Application 2.2 Deployment Descriptors -
Servlet Mappings
Use this panel to redirect specific URL patterns to a servlet or JSP file. It is possible that
different URL patterns may converge on the same servlet class or JSP file, but with different
<init-param> declarations.
Note: Because the <servlet> tag can indicate a <jsp-file>, the <servlet-mapping> subelement is also
capable of redirecting URL patterns to a JSP page.
The subelement <servlet-mapping> is not a required element of the web.xml deployment

Servlet Mappings
Displays the mappings between servlets and a URL pattern in your web application.
Add
Click to configure a new servlet mapping definition for your web application.
Delete
Click to remove an existing mapping definition from from the Servlet Mappings list.
URL Pattern
Required, enter the URL you want to map to a particular servlet for your web application.
The portion of the URL after the http://host:port + webappname is compared to the
pattern you supply. If the pattern matches, then the servlet mapped in this element will
be called. The URL must follow the rules specified in Section 10 of the Servlet 2.2
Specification. This field corresponds to the <servlet-mapping> tag of the <servlet-
mapping> subelement.
Servlet Name
Required, enter the document name of the servlet that you want to map through the URL
specified in the URL Pattern field. This field corresponds to the <servlet-name> tag of the
<servlet-mapping> subelement.

23-47
23-48
Create Servlet Mapping
Use this dialog to specify a new mapping between a URL pattern and a servlet class or JSP file
in your web application.
Servlet Mappings
Displays the mappings between servlets and a URL pattern in your web application.
Add
Click to configure a new servlet mapping definition for your web application.
Delete
Click to remove an existing mapping definition from from the Servlet Mappings list.
URL Pattern
Required. Enter the URL you want to map to a particular servlet for your web application.
The portion of the URL after the http://host:port + webappname is compared to the
pattern you supply. If the pattern matches, then the servlet mapped in this element will
be called. The URL must follow the rules specified in Section 10 of the Servlet 2.2
Specification. This field corresponds to the <servlet-mapping> tag of the <servlet-
mapping> subelement.
Servlet Name
Required. Enter the document name of the servlet that you want to map through the URL
specified in the URL Pattern field. This field corresponds to the <servlet-name> tag of the
<servlet-mapping> subelement.

23-49
Context Init
Use this panel to configure initialization parameters for your web application. Parameters you
configure will be run in the ServletContext object associated with the application. Within your
application's JSP pages, this ServletContext object is available via the application implicit
object. Because this object is accessible from all of a web application's servlets and JSP pages,
it provides a convenient mechanism for specifying configuration data that is applicable across
multiple application resources.
The subelement <context-param> is not a required element of the web.xml deployment

Web Application Context Initialization Parameters

Displays the list of web application intialization parameters you have configured.
Add
Click to configure a new initialization parameter for your web application.
Delete
Name
Required, enter the name of the initialization parameter that you want to add.
Corresponds to the <param-name> tag of the <context-param> subelement.
Value
Required, enter the value of the initialization parameter. Corresponds to the <param-
value> tag of the <context-param> subelement.
Description
<description> tag of the <context-param> subelement.

23-50
23-51
Define Parameter
Use this dialog to configure a new initialization parameter for your web application.
Name
Required, enter the name of the initialization parameter that you want to add.
Corresponds to the <param-name> tag of the <context-param> subelement.
Value
Required, enter the value of the initialization parameter. Corresponds to the <param-
value> tag of the <context-param> subelement.
Description
<description> tag of the <context-param> subelement.

23-52
Web Application 2.2 Deployment Descriptor - MIME
Mappings
Use this panel to configure valid document types for your web application. In addition to the
standard HTML and JSP document types, you may want to configure your web application to
use other types of information. You add the document's MIME type to this panel to inform the
web server which MIME types are associated with specific file name extensions in your web
application. The web browser that runs your web application can then examine the MIME type
returned by the server for a given request and determine how to handle the data contained in
the response.
The subelement <mime-mapping> is not a required element of the web.xml deployment

MIME Mappings
Displays the list of web application MIME types that you have associated with particular
document file name extensions, including the default html and txt types.
Add
Click to configure a new MIME-type mapping definition for your web application.
Delete
Click to remove an existing mapping definition that you select from the MIME
mappings list.
Extension
Required, enter the file name extension of the document type you want to map to a
particular MIME type for your web application. For example, pdf. This field corresponds
to the <extension> tag of the <mime-mapping> subelement.
MIME Type
Required, enter the document MIME type that you want to map to the specified file name
extension. For example, application/pdf for Adobe's Portable Document Format. This
field corresponds to the <mime-type> tag of the <mime-mapping> subelement. Note, the
official registry of Internet MIME types is managed by the Internet Assigned Numbers
Authority (IANA) and is available from their website at http://www.iana.org.

23-53
23-54
Create MIME Mapping
Use this dialog to configure a new document type for your web application.
Extension
Required, enter the file name extension of the document type you want to map to a
particular MIME type for your web application. For example, pdf. This field corresponds
to the <extension> tag of the <mime-mapping> subelement.
MIME Type
Required, enter the document MIME type that you want to map to the specified file name
extension. For example, application/pdf for Adobe's Portable Document Format. This
field corresponds to the& <mime-type> tag of the <mime-mapping> subelement. Note,
the official registry of Internet MIME types is managed by the Internet Assigned Numbers
Authority (IANA) and is available from their website at http://www.iana.org.

23-55
Web Application 2.2 Deployment Descriptor - Tag
Libraries
Use this panel to specify the location of a JSP Tag Library Descriptor file (TLD) though a URI
pattern you supply. Although you can specify a TLD in your JSP that is relative to the WEB-INF
directory, you can alternatively use the <taglib> deployment descriptor subelement to configure
the TLD when deploying your web application. You can use a separate <taglib> subelement for
each TLD file you want to deploy with your web application.
The subelement <taglib> is not a required element of the web.xml deployment descriptor
definition.
Tag Libraries
Displays the list of tag library TLD files for which you have specified a location.
Add
Click to specify the location for a new TLD for your web application.
Delete
Click to remove an existing TLD location definition that you select from the Tag
Libraries list.
Taglib URI
Required. Enter the URI for the location of a tag library descriptor (TLD) file used by your
web application. This should be the same URI string that appears in the <%@taglib%>
directive of your JSP pages. However, if the <%@taglib%> directive of your JSP pages
is a relative URI for a TLD file, this subelement is not required in the web.xml definition
and should be left empty. This field corresponds to the <taglib-uri> tag of the <taglib>
subelement.
Taglib Location
Required. Enter the file name of the TLD file or the name of a taglib Jar file that has a
META-INF/taglib.tld file in it. The location of the file name you supply is relative to the
WEB-INF directory; to make it relative to the root of the web application, start your entry
with a "/". It is a good idea to store the TLD file under the WEB-INF directory so it is not
publicly available over an HTTP request. This field corresponds to the <taglib-location>
tag of the <taglib> subelement.

23-56
23-57
Declare Tag Library
Use this dialog to define a new association between a JSP Tag Library Descriptor file (TLD)
and its URI pattern.
Taglib URI
Required. Enter the URI for the location of a tag library descriptor (TLD) file used by your
web application. This should be the same URI string that appears in the <%@taglib%>
directive of your JSP pages. However, if the <%@taglib%> directive of your JSP pages
is a relative URI for a TLD file, this subelement is not required in the web.xml definition
and should be left empty. This field corresponds to the <taglib-uri> tag of the <taglib>
subelement.
Taglib Location
Required. Enter the file name of the TLD file or the name of a taglib Jar file that has a
META-INF/taglib.tld file in it. The location of the file name you supply is relative to the
WEB-INF directory; to make it relative to the root of the web application, start your entry
with a "/". It is a good idea to store the TLD file under the WEB-INF directory so it is not
publicly available over an HTTP request. This field corresponds to the <taglib-location>
tag of the <taglib> subelement.

23-58
Web Application 2.2 Deployment Descriptor - Login
Use this panel to specify how login authentication is to be handled for your web application
users.
This selection you make in this panel corresponds to the <auth-method> tag of the <login-
config> subelement. The subelement <login-config> and the tag <auth-method> are not
required elements of the web.xml deployment descriptor definition.
Web Application Login Authentication

None
Select when no authentication is desired.
HTTP Basic Authentication (RFC 2617)
Select to specify browser authentication.
HTTP Digest Authentication (RFC 2617)
Select to specify digest authentication.
Form-based Authentication
Select to specify user-written HTML form for authentication. In this case, you must
supply a login page (an HTML page, JSP page, or HTTP servlet) used to
authenticate the user. The page must return an HTML page containing a FORM
that conforms to a specific naming convention. This is done through the <form-
login-config> tag in the <login-config> subelement of the generated web.xml file.
HTTPS Client Authentication (Public Key Certificate)
Select to specify client-side authentication.

23-59
Resource Refs
Use this panel to define reference lookup names for external resources in your web application.
This allows you to use the deployment descriptor definition to map the names that appear in
your Java code with the JNDI names of the resources. Using the reference names in your
application code permits you to easily change your application resources without changing the
lookups in your application code. The web server maps the resource names in the deployment
descriptor to the actual location of the resource at deployment time.
The subelement <resource-ref> is not a required element of the web.xml deployment descriptor
definition.
Resource References
Displays the list of resources that you have associated with a particular resource named
by your Java code.
Add
Click to define a new resource reference for your web application.
Delete
Click to remove an existing resource reference definition from the Resource
References list.
Name
Required, enter the name of the actual JNDI resource name as bound to the JNDI tree.
This field corresponds to the <res-ref-name> tag of the <resource-ref> subelement.
Resource Type
Required, enter the Java type of the resource you want to reference. You must supply
the full package name of the Java type. This field corresponds to the <res-type> tag of
the <resource-ref> subelement.
Authentication
Required, select the type of authentication used for the resource. This field corresponds
to the <res-auth> tag of the <resource-ref> subelement.
Servlet
Select when the servlet component code will perform resource sign on
programmatically.
Container
Select when the web server container uses the security context that you specify
23-60
within the <login-config> subelement of the generated web.xml file.
Description
Optionally, enter the text description of the resource reference that you have defined.
This field corresponds to the <description> tag of the <resource-ref> subelement.

23-61
Create Resource Reference
Use this dialog to define a new reference lookup name for an external resource in your web
application.
Name
Required, enter the name of the actual JNDI resource name as bound to the JNDI tree.
This field corresponds to the <res-ref-name> tag of the <resource-ref> subelement.
Resource Type
Required, enter the Java type of the resource you want to reference. You must supply
the full package name of the Java type. This field corresponds to the <res-type> tag of
the <resource-ref> subelement.
Authentication
Required, select the type of authentication used for the resource. This field corresponds
to the <res-auth> tag of the <resource-ref> subelement.
Servlet
Select when the servlet component code will perform resource sign on
programmatically.
Container
Select when the web server container uses the security context that you specify
within the <login-config> subelement of the generated web.xml file.
Description
Optionally, enter the text description of the resource reference that you have defined.
This field corresponds to the <description> tag of the <resource-ref> subelement.

23-62
Preview
Use this panel to preview the deployment descriptor definition that you specified using the
panels of the Web Application 2.2 Deployment Descriptor Dialog. You can edit deployment
descriptor and preview it as many times as desired before saving the definition to the web.xml
file generated by this dialog. See the individual panels for a description of each tag that
appears in the web.xml deployment descriptor.

23-63
Create Security Role
Use this dialog to define a new security role link.
Role Name
Required, enter the name of the security role that appears in your servlet code that you
want to associate with an alternative name. This field corresponds to the <role-name>
tag of the <security-role-ref> subelement.
Role Link
Required, enter the name of the security role that you want to link to as the alternative
name. This field corresponds to the <role-link> tag of the <security-role-ref> subelement.
The name you enter must be defined by the <role-name> tag in the <security-role>
subelement of the generated web.xml file. To view existing security role names, select
the Security node from the tree on the left of this dialog.
Description
Optionally, enter the text description of the security role that you want to associate with
an alternative security role name. This field corresponds to the <description> tag of the
<security-role-ref> subelement.

23-64
Web Bean Editor - Properties
Use this tab to expose a custom web bean's properties. The tab displays a list of those
properties already exposed. Select a property from this list before clicking Edit or Remove.
Add
Click to expose an attribute of the web bean.
Remove
Click to conceal an attribute of the web bean from the Component Palette.
Edit
Click to edit the attributes of the selected property.
23-65
Web Bean Editor - Class Information
Use this tab to change general information about a custom web bean.
Web Bean Name

Enter the name of your web bean, to be used by the Web Object Manager and
Component Palette.
Class Name
Enter the package and class that implements your web bean. Alternately, click Browse to
browse for a package and class to implement your web bean.
Description
Enter a description for your web bean.
23-66
Add Property
Use this editor to define additional web bean properties based on an existing web bean's class
information.
Select attribute to be added

Select an attribute from the list of currently unexposed web bean attributes.
23-67
Edit Properties
Use this dialog to edit the attributes of a selected property.
Name
Enter the name of property to edit.
Requires a value
Click to specify that the attribute expects a value.
Needs to be quoted
Click if the value must be enclosed in quotation marks.
Default value
Enter a default value for the property.
User must select from the following options
Click to specify the list of legal values when a limited selection list is desired. Enter the
space delimited options in the text area.
23-68
Web Object Manager
Use the Web Object Manager to register web beans with JDeveloper's Component Palette.
Edit
Click to change the name or edit the registered properties of the selected web bean.
Register
Click to register a new web bean with JDeveloper to display in the Component Palette.
❍ Web Bean - non-databound web beans
❍ Data Web Bean- databound web beans that work with a Business Components
project to interact with the database
De-Register
Click to de-register the selected web bean. This action removes the class from the
Component Palette.
SubClass
Click to create and register a new web bean by extending the selected one.
23-69
Add Web Bean
Use this dialog to register a web bean with the Component Palette. This allows you to use the
wizard to add the web bean to a JSP page.
Web Bean Name

Enter a name for your web bean, to be used by the Web Object Manager and
Component Palette.
Class Name
Enter the package and class for your web bean. Click Browse to find the web bean's
class rather than entering information in the Class Name field.
Description
Enter a description of your web bean.
23-70
New Class from Web Bean
Use this dialog to create a new web bean by subclassing and existing web bean.
Note: If you have an existing web bean file with a syntax error and you attempt to subclass it as
another web bean, JDeveloper will not permit you to save the file. In this case, you will receive a
parse error in JDeveloper unless you web bean is a well-formed class.
Base Class
This field displays the class from which the new web bean will inherit.
Class Name
Enter a name for your new web bean class.
Web Bean Name
Enter a registered name for your new web bean.
Package
Enter the package for your new web bean. Click the Browse button to browse for a
package rather than entering one into the Package field.
Description
Enter a description for your new web bean.
23-71
JSP Tag Reference
● Chart Web Bean
● Declaration JSP Tag
● EditCurrentRecord Web Bean
● EditForm Web Bean
● Expression JSP Tag
● FindForm Web Bean
● getProperty JSP Tag
● Hidden Comment JSP Tag
● Include Directive JSP Tag
● Include JSP Tag
● jbo:AnchorMedia
● jbo:ApplicationModule
● jbo:AttributeIterate
● jbo:Commit
● jbo:CreateViewObject
● jbo:Criteria
● jbo:CriteriaRow
● jbo:DataEdit
● jbo:DataHandler
● jbo:DataNavigate
● jbo:DataQuery
● jbo:DataRecord
● jbo:DataScroller
● jbo:DataSource
● jbo:DataSourceRef
● jbo:DataTable
● jbo:DataTransaction
24-1
● jbo:DataWebBean
● jbo:EmbedAudio
● jbo:EmbedImage
● jbo:EmbedVideo
● jbo:ExecuteSQL
● jbo:FileUploadForm
● jbo:FormEvent
● jbo:InputDate
● jbo:InputHidden
● jbo:InputPassword
● jbo:InputRender
● jbo:InputSelect
● jbo:InputSelectGroup
● jbo:InputSelectLOV
● jbo:InputText
● jbo:InputTextArea
● jbo:MediaUrl
● jbo:OnEvent
● jbo:PostChanges
● jbo:RefreshDataSource
● jbo:ReleasePageResources
● jbo:RenderValue
● jbo:Rollback
● jbo:Row
● jbo:RowsetIterate
● jbo:RowsetNavigate
● jbo:SetAttribute
● jbo:SetDomainRenderer
● jbo:SetFieldRenderer
24-2
● jbo:SetHtmlAttribute
● jbo:ShowCriteria
● jbo:ShowDefinition
● jbo:ShowHint
● jbo:ShowValue
● jbo:UrlEvent
● jbo:ViewCriteria
● jbo:ViewCriteriaIterate
● jbo:WebBean
● JSP Forward JSP Tag
● NavigatorBar Web Bean
● Output Comment JSP Tag
● Page Directive JSP Tag
● plugin JSP Tag
● RowSetBrowser Web Bean
● RowSetNavigator Web Bean
● Scriptlet JSP Tag
● setProperty JSP Tag
● TableControl Web Bean
● Tag Library Directive JSP Tag
● Toolbar Web Bean
● useBean JSP Tag
● ViewCurrentRecord Web Bean
● XMLDataGenerator Web Bean
24-3
Chart Web Bean
Class Name: Chart
Package: oracle.jdeveloper.jsp.wb
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\ChartRenderer.java
Extends: DataWebBeanImpl
Implements: WebBean
Description
Provides methods to dynamically generate a chart .gif image and render it to the output stream
of a JavaServer Page response. The Chart web bean relies on the Chart Render web bean to
instantiate the chart based these choices in the Chart Wizard:
● A Business Components View Object

● Chart attributes selections
Associating a View Object with the Chart
You must choose a view object that queries the columns that you want to use to render the
chart. The Chart Wizard inserts this method to associate the Chart with your view object
selection:
myChart.initialize(application, session, request, response, out,

"d2ePackage_d2eModule.MyDeptView");
Selecting a Chart Type
The Chart Wizard allows you to insert charts into your JSP output. Selecting the appropriate
chart for the data you want to display is made simple with the Chart Type step of the wizard.
Once you have filled in all the choices for the chart you selected, the wizard inserts the code to
build your chart into your source file, as in the following example:
<jsp:useBean class="oracle.jbo.html.databeans.ChartRenderer" id="d2e" scope="request" >
24-4
<%
d2e.setReleaseApplicationResources(false);
d2e.initialize(application,session, request,response,out,"d2e_d2eMod.ViewEmp");
d2e.setCommonScriptName("/webapp/jsp/chart_common.jsp");
d2e.getChart().setGraphType(d2e.BUBBLE_CHART);
//....
d2e.setSeriesLabelColumnName("Job");
d2e.setDisplayAttributes("Empno,Sal,Comm");
//....
d2e.getChart().setY1AxisSide(1);
//....
d2e.getChart().setTitleString("Dept to Emp");
d2e.getChart().setSubtitleString("Employee");
d2e.getChart().setFootnoteString("");
d2e.setImageWidth(500);
d2e.setImageHeight(350);
//....
d2e.render();
%>
</jsp:useBean>
You can select from various types of chart, each with a number of options. See JSP Element
Charts for the different chart types available. You may select one of these chart types from the
Chart Type dropdown menu:
● Pie Chart
● 3-D Charts
● Area Charts
● Bar Charts
● Hi/Lo Charts
● Line Charts
● Scatter Charts
● Special Charts
Selecting Chart Attributes
Once you have selected your chart, fill in the data elements or select the attributes required for
that chart on the subsequent pages of the Chart Wizard. Refer to each chart type in the above
list for details.
24-5
All charts require that you provide a title and other data. See Generic Chart Options for further
details.
Refer to the Javadoc for additional methods that you can use to set visual attributes.
24-6
Declaration JSP Tag
Declares a variable or method valid in the page scripting language. For complete details about
the tag, see the JavaServer Pages Developer's Guide from Sun Microsystems.
Note: You can view the tag descriptions online at http://java.sun.com/products/jsp/tags/tags.html.
24-7
EditCurrentRecord Web Bean
Class Name: EditCurrentRecord
Package: oracle.jbo.html.databeans
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\EditCurrentRecord.java
Description
Use to edit the current record of a view object's rowset.
Note: Starting in JDeveloper 3.2, the behavior of the createNewRow() method has changed. It now
removes field renderers when the new row gets created. If you set field renderers before creating a
new row in application code developed prior to 3.2 release, you need to move createNewRow() prior
to your assignment of the field renderers.
You can control the height and width of the row used to display the attribute by:
● Setting the control hints Display Height and Display Width for the attribute that you set
on the entity object or view object.
OR
● Adding a useEditField() method call to produce a single-line height control before

rendering the control:
ed1.useEditField("attr");
ed1.getFieldRenderer("attr").setPromptText("attr");
24-8
EditForm Web Bean
Class Name: EditForm
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jdeveloper\jsp\wb\EditForm.java
Extends: HTMLForm
Implements: WebBean
Description
Provides methods to dynamically generate an HTML form and render it to the output stream of
a JSP response.
It is instantiated by the EditCurrentRecord web bean.
24-9
Expression JSP Tag
Contains an expression valid in the page scripting language. For complete details about the
tag, see the JavaServer Pages Developer's Guide from Sun Microsystems.
24-10
FindForm Web Bean
Class Name: FindForm
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\FindForm.java
Description
Use to find those records that match given search criteria from a view object's rowset.
24-11
getProperty JSP Tag
Gets the value of a Bean property so that you can display it in a result page. For complete
details about the tag, see the JavaServer Pages Developer's Guide from Sun Microsystems.
24-12
Page Comment JSP Tag
Documents the JSP page but is not sent to the client. For complete details about the tag, see
the JavaServer Pages Developer's Guide from Sun Microsystems.
24-13
Include Directive JSP Tag
Includes a file of text or code in the JSP source file. For complete details about the tag, see the
JavaServer Pages Developer's Guide from Sun Microsystems.
24-14
include JSP Tag
Includes either a static or dynamic file in a JSP file. For complete details about the tag, see the
24-15
<jbo:AnchorMedia>
Inserts an HTML Anchor to refer to the multimedia content stored as an interMedia object in the Oracle database.
JSP Syntax
<jbo:AnchorMedia
datasource="datasourceInstanceName"
mediaattr="mediaAttributeName"
[[ rowkey="rowKeyString" ] | [ whereclause="whereClause" ]]
[ retrievepath="customRetrievePath" ]
>
body content
</jbo:AnchorMedia>
Description
The <jbo:AnchorMedia> data tag lets you embed an HTML Anchor tag for an interMedia object in your JSP page. When you
invoke the JSP page in the browser, you will see a URL link in place of the Anchor tag. After you click the URL link, the
multimedia content (image, audio, or video) will be delivered from the database to your browser.
This tag can be nested inside <jbo:Row> or <jbo:RowsetIterate> data tags. If the tag appears inside one of these two tags, it
uses the row defined by these tags and ignores rowkey and whereclause attributes. Otherwise, the tag uses rowkey or
whereclause attributes to locate the row. The rowkey has precedence to whereclause. If neither attribute is specified, the tag
tries to use the current row in the datasource object. You can use the <jbo:RowsetNavigate> data tag to change the current row
in the datasource object.
The [mediaFetchingURL] has the following format:
[retrievepath]?appModId=[appModId]&rowSetName=[rowSetName]&contentCol=[mediaAttributeName]&rowKey=[rowKeyString]
By default, the [retrievepath] is a pre-supplied JSP page called ordPlayMedia.jsp. You can write your own media delivery
component and provide a custom retrieve path when such requirement arises.
Attributes
● datasource—the datasource id that you want to use to access the interMedia objects. You create the datasource using
the <jbo:DataSource> data tag.
● mediaattr—the name of the specific view object attribute (in the datasource) that contains the interMedia objects.
● rowkey—optional, the text encoding of the row identifier that is used to uniquely identify a row.
● whereclause—optional, the where clause of a query that uniquely locates a row.
● retrievepath—optional, the custom retrieval path for the media content delivery component. The default value is
ordPlayMedia.jsp.
Example 1:
<jbo:AnchorMedia datasource="ds" mediaattr="Picture" whereclause="id = 15" >My birthday party.</jbo:AnchorMedia>
24-16
HTML Output
<A HREF="[mediaFetchingURL]">My birthday party.</A>
Example 2:
<jbo:RowsetIterate datasource="ds" action="First" >

<jbo:AnchorMedia datasource="ds" mediaattr="Picture" />
HTML Output
<A HREF="[mediaFetchingURL]"></A>
...
Example 3:
<jbo:RowsetNavigate datasource="ds" action="First" />

<jbo:AnchorMedia datasource="ds" mediaattr="Picture" />
HTML Output
24-17
<jbo: ApplicationModule>
Creates an application module instance to service the HTTP requests.
JSP Syntax
<jbo:ApplicationModule
id="appModuleInstanceName"
[ configname="businessComponentsPackageName.appModuleName.configName" ] | [ definition="data model
definition" ]
[ lock="true | false" ]
[ waittimeout="time in ms. | 60000" ]
[ releasemode="Stateful | Stateless | Reserved" ]
[ username="jdbc_connection_username" ] | [ iiop_username="iiop_connection_username" ]
[ password="jdbc_connection_password" ] | [ iiop_password="iiop_connection_password" ]
/>
Description
The <jbo:ApplicationModule> tag provides a runtime connection to a Business Components application module
instance. Rather than specify the connection information in the ApplicationModule tag, you select a named
configuration from a list of possible configurations that a developer created for the Business Components
project.
The JSP pages access business components through instances of the application module. You can decide how
application module instances are allocated during the JSP session, whether their state is preserved, and
whether there is failover support from the database. The default application module pooling implementation in
the Business Components for Java framework supports three modes: stateful, stateless, and reserved.
Stateless is the default mode for all JSP pages, unless you change it. In a JSP application you can control the
manner in which a databound JSP page releases its application module instance at two levels:
● At the level of the entire JSP application by setting the RELEASE_MODE property in the configuration
you create for an application module
● At the level of individual JSP pages by setting the ApplicationModule data tag
Note: The mode you specify for the ApplicationModule data tag, overrides the JSP application release mode at the
level of individual JSP pages.
During page processing, the HTTP requests for a page share a limited pool of instances of each application
module. In a stateless JSP application, access to a specific instance of the application module is maintained
only for the duration of the page requests. Then, when the ApplicationModule data tag with Stateless option is
processed, the application module instance must be released back to the pool of instances of that application
module.
If you allow the default stateless option for individual JSP pages or the entire JSP application, the data tags do
not necessarily access the same application module instance each time a new page is invoked during a specific
HTTP session and, therefore, cannot depend on a view object's rowset remaining the same from one invocation
24-18
to the next. This behavior is desirable when your JSP pages work independently from one another, and do not
represent a single task that requires state to be maintained. Permitting the majority of your JSP pages to release
the application module instance statelessly reduces the overhead that managing application module state
entails and ensures that your JSP application will operate at the highest level of performance possible.
When you select the Stateful option for the ApplicationModule data tag, the data tags of a JSP application also
do not access the same application module instance each time they are invoked. However, unlike stateless JSP
pages, Business Components for Java saves the application module state to the database when the application
module is released, and allows a view object's rowset to remain the same from one invocation to the next.
Stateful mode is the preferred choice when:
● You want to preserve information across a series of JSP pages that users interact with to complete a
single task
● You want to preserve changes submitted by the user from one page to the next
In stateful mode, Business Components for Java provides failover support from the database, and permits the
application module pool to be used efficiently. The application module pool manager manages the application
state including the current position and all dynamic application information that needs to be passed from one
JSP page to the next. Stateful mode is useful whether or not the user submits changes to the data: it is easier
and more efficient to let Business Components for Java manage restoring queries to the previous HTTP request
than performing these tasks programmatically using the Business Components for Java API.
Important: If you permit users to modify data in stateful or reserved mode, you must use the Commit data tag to
submit the changes to the database.
When you select the Reserved option for the ApplicationModule data tag, once a data tag has connected to an
application module, all subsequent connections to that application module from any data tag during the same
HTTP session involve the same instance of the application module. This holds true whether a subsequent
connection is from another JSP page or from a new invocation of the same JSP page. This mode is similar to
the stateful application, but it does not provide failover support, nor does it permit application modules to be
recycled. Reserved mode is provided primarily for compatibility with application modules when non-standard
JDBC connections have been defined.
See also: oracle.jbo.common.ampool.SessionCookie
Attributes
● id—the name of the instance of the data application. The name you assign must be unique within a page.
This can be any legal Java identifier. Within a scriptlet, you may use the id as a scriptable variable of type
oracle.jbo.common.ampool.SessionCookie.
● configname—optional, the name of the configuration that defines the application module connection. You
can view configuration parameters by right-clicking the application module in the Business Components
project and choosing Configurations. You should omit this attribute and set the definition attribute instead
if you prefer to use an existing client data model definition.
● definition—optional, the name of the data model definition that appears in a client configuration file (.cpx).
Each definition specifies an application module name and the configuration name that defines the
24-19
application module connection information. You create data model definitions by running the JClient Data
Model Wizard. You can view the wizard by selecting JClient Objects in the New Gallery. If you do not
specify a data model definition, you should omit this attribute and use the configname attribute instead to
define the application module connection information.
● lock—optional, specifies whether to acquire a session lock for the application module shared by JSP
pages. The default is false. If you set lock to true, you should be careful to release the lock after it is done
using the application module resource. Application thread starvation may occur if the lock is held
indefinitely.
● waittimeout—optional, determines the period of time in milliseconds that the thread running your JSP
page will wait when another thread is holding the lock associated with the session cookie that references
the application module. The default is 60000 milliseconds. If the tread does not release the session
cookie before the timeout, then calling thread will terminate. In BC4J JSP pages, the session cookie
references the application module used to connect to business components.
● releasemode—optional, the mode that determines the state of the application module instance servicing
the HTTP requests. Choose the value Stateful, Stateless, or Reserved depending on how you want to
handle the state of the application module for HTTP requests from the JSP page. Stateful is the default
value.
Stateless does not preserve the state of the application module instance between page-processing
requests. The instance is immediately released when a JSP page terminates. Select this option for
individual pages that do not benefit from failover support or do not comprise a set of JSP pages that work
together.
Stateful preserves the application module instance's state in the database or file (as specified by the
application module property passivationtype) between page-processing requests. This permits the
application to maintain user's data without involving a single application module instance for long periods
of time. Stateful mode provides failover support for the HTTP session and is the preferred choice when
the application module uses a standard JDBC connection. It is also recommended for individual JSP
pages that user interact with to complete a specific task.
Reserved the application module instance is not released for the duration of the HTTP session. This
mode is similar to the stateful application, but it does not provide failover support, nor does it permit
application modules to be recycled. Reserved mode is useful in an intranet type environment. In this
mode, the user is expected to click either the Commit button or Rollback button in the process JSP page.
username—optional, a valid user name for the application module. When user name is defined in the
JDBC connection named by the configuration, you do not need to use this attribute.
● password—optional, a valid password for the application module. When password is defined in the JDBC
connection named by the configuration, you do not need to use this attribute.
● iiop_username—optional, a valid user name for the application module. When user name is defined in
the IIOP connection named by the configuration you need to use this attribute.
24-20
● iiop_password—optional, a valid password for the application module. When password is defined in the
IIOP connection named by the configuration or the JSP application properties file, you need to use this
attribute.
Example
This example shows that you can use scriptable variables with the BC4J data tags to access their
implementation classes in the oracle.jbo.* package. Here, the scriplet uses the am variable to get a reference to
the application module object and call the getName() method from the
oracle.jbo.common.ampool.SessionCookie API.

<%@ page import="oracle.jbo.*" %>
<jbo:ApplicationModule id="am" configname="mypackage.MypackageModule.MypackageModuleLocal"

<% ApplicationModule appMod = am.useApplicationModule(); %>
Application Module name = <%=appMod.getName()%>
Related topics

24-21
<jbo:AttributeIterate>
Iterates through the datasource attribute definition.
JSP Syntax
<jbo:AttributeIterate
id="AttributeDefInstanceName"
[ displayattributes="List of attribute names" ]
[ hideattributes="List of attribute names" ]
[ queryableonly="true | false" ]
>
[JSP_tags]
Description
The <jbo:AttributeIterate> data tag lets you create an iterator to step through each attribute in the specified
datasource. You can use the AttributeIterate data tag to work with:
● Attribute definition metadata on the datasource

● Attribute values for a specific row
● Attribute criteria for a specific criteria row
Within the body of the <jbo:AttributeIterate> data tag you can perform some action on the iterated attribute
before proceeding to the next attribute. For example, you can:
● Use a ShowDefinition or a ShowHint data tag to display attribute metadata

● Use the Input data tags or the RenderValue data tag to edit and display attribute data
● Use the Criteria or the ShowCriteria data tag to edit and display criteria value
When you want to iterate over the attributes of a specific row or criteria row, the <jbo:AttributeIterate> data
tag gets the row to work on through the context of the JSP page. In this case, you must use the
<jbo:AttributeIterate> data tag inside the body of a <jbo:Row>, <jbo:RowsetIterate>, or <jbo:CriteriaRow>
data tag. Each of these data tags will retrieve a row for the <jbo:AttributeIterate> data tag to process.
See also: oracle.jbo.AttributeDef
Attributes
● id—the name of the instance of the attribute iterator created by the AttributeIterate tag. The name you
assign must be unique within a page. This can be any legal Java identifier. Within a scriptlet, you may
use the id as a scriptable variable of type oracle.jbo.AttributeDef.
24-22
● datasource—the datasource id, as defined in the <jbo:dataSource> data tag. This attribute is optional
when inside the tag body of an RowsetIterate, Row, or CriteriaRow data tag.
● displayattributes—optional, a list of attributes separated by commas. Only the attributes in list will be
iterated. Use when you want to iterate through a subset of datasource attributes; otherwise, omit this
attribute to iterate through all attributes.
● hideattributes—optional, a list of attributes separated by commas. Attributes in list will not be iterated,
while all others will be. Use when you want to iterate through a subset of datasource attributes;
otherwise, omit this attribute to iterate through all attributes.
● queriableonly—optional, specifies whether the iterator will ignore attributes that do not have the BC4J
attribute definition queriable enabled. Queriable attributes are those that are allowed to have a filter
condition for the WHERE clause; whereas, non-queriable attributes are not to be used in constructing
the WHERE clause of SQL statements. The default is false, which uses all attributes in the datasource,
whether they are queriable or not. If you want to iterate over only queriable attributes, set to true.
Examples
The example below constructs a table using data tags and HTML code. The AttributeIterate data tag iterates
through the bound datasource attributes.
<jbo:Row id="rowCur" datasource="dsShow" rowkey="<%=rowParam%>" action="<%=rowAction%>">

<table class="clsViewCurrentRecord" cellspacing="1" cellpadding="3">
<jbo:AttributeIterate id="def" datasource="dsShow">
<td title="<jbo:ShowHint hintname='TOOLTIP'/>"><jbo:ShowHint
hintname="LABEL">##Column</jbo:ShowHint></td>
<td title="<jbo:ShowHint hintname='TOOLTIP'/>"
class="clsFieldValue"><jbo:RenderValue datasource="dsShow">##Cell</jbo:RenderValue></td>
</tr>
</table>
</jbo:Row>
24-23
<jbo:Commit>
Applies changes you make on all datasource instances defined by the application module to
the database.
JSP Syntax
<jbo:Commit
appid="appModuleInstance"
/>
Description
Until you commit changes from the datasource cache, the changes will be accessible only to
the data application specified. Once commited to the database, the changes cannot be rolled
back.
The Commit tag performs the same action whether you operate on the datasource cache or
directly on the database. Therefore, you can issue a commit:
● When you modify the data of the rows of the datasource cache
● When you modify the database through a ExecuteSQL data tag
Attributes
● appid—the application module id you specified with the ApplicationModule data tag.
Example

<jbo:ApplicationModule id="OnlineOrdersModule"
configname="OnlineOrders.OnlineOrdersModule.LocalConfig"
<jbo:DataSource id="ds1" appid="OnlineOrdersModule"

viewobject="CustomerView" >
</jbo:DataSource>
<jbo:Row id="newRow" datasource="ds1" action="Create" >

24-24
<jbo:SetAttribute dataitem="Id" value="101" />
<jbo:SetAttribute dataitem="Lastname" value="tiger" />
<jbo:SetAttribute dataitem="Firstname" value="tiger" />
<jbo:SetAttribute dataitem="Address.Street" value="101 Main st" />
<jbo:SetAttribute dataitem="Address.City" value="Redwood city" />
</jbo:Row>
</BODY>
</HTML>
<jbo:Commit appid="OnlineOrdersModule" />
24-25
<jbo:CreateViewObject>
Creates an instance of a dynamic view object from a Business Components application module
you specify.
JSP Syntax
<jbo:CreateViewObject
appid="appModuleInstanceName"
name="viewObjectName"
[ rangesize="number of rows displayed | -1 | 1" ]
>
SQL_SELECT
Description
The <jbo:CreateViewObject> data tag lets you define a SQL SELECT statement in the body of
the tag. Typically, you generate the statement from user input. For example, you might want to
display a LOV-selection list by binding to a dynamic view object that you create based on the
user's input.
You work with the dynamic view object instance, you must create a datasource based on it
using the <jbo:DataSource> data tag. The DataSource data tag lets you define an id for the
dynamic view object that you pass to other data tags which can act on rowsets and attributes,
such as the RowsetIterate or ShowValue tags. To generate the rowset, the CreateViewObject
tag must include a SQL SELECT statement in its body:
<jbo: CreateViewObject >

SQL Select goes here
</jbo: CreateViewObject >
Then, you can display data from the result set using <jbo:RowsetIterate> and <jbo:ShowValue>
data tags as shown in the example below.
Note: You must use uppercase for any dataitems that refer to a dynamic view object's attribute
names. The CreateViewObject data tag queries the database directly and therefore bypasses the
usual Business Components attribute alias names and column names in database tables are always
represented in uppercase.
See also: oracle.jbo.ViewObject
24-26
Attributes
● appid—the data application id you specified with the ApplicationModule data tag.
● name—the name of the dynamic view object. The name identifies the view object from
which instances are created. This parameter does not create a named datasource; you
must pass the name to the viewobject parameter of the DataSource tag to create the
datasource for the dynamic view object.
Note: If this name collides with an existing view object, then the existing view object is
removed. This can be useful if you want to replace one view object currently in use with
another.
● rangesize—optional, the number of rows in a range to fetch from the datasource. This is
useful when you do not want to work with an entire rowset. A range effectively defines a
window you can use to access a subset of the rows in the datasource. Ranges are useful
when the rowset is large and you do not want to bring all of the rows to the client, or
when you want to display a certain number of rows on the page. By default, the range
size is set to 1. The value -1 fetches all rows.
● SQL_SELECT—defines the view object query through a SQL SELECT statement you
provide and generates the rowset upon which your JSP acts. Typically, you will generate
this statement from user input. The names in your query are dicated by the database
tables and columns and therefore must be supplied in uppercase.
Tip: If you do not yet know how to construct the query, type something into this field and
refine your SQL statement in the generated data tag.
Example
This example creates a dynamic view object based on a query against the CUSTOMERS table.
The page displays the view object attribute: PHONE_NUMBER. The value of the dataitem
(PHONE_NUMBER) for <jbo:ShowValue> is the same as the column name because the
attribute names for dynamic view objects are dicated by the database column names (rather
than attribute alias names which would be defined for a persistent view object in the Business
Components project).

<%@ page contentType="text/html;charset=windows-1252"%>
<HTML>
24-27
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html;
charset=windows-1252">
<TITLE>
Hello World
</TITLE>
</HEAD>
<BODY>
<jbo:ApplicationModule id="MypackageModule"
configname="mypackage.MypackageModule.MypackageModuleLocal"
releasemode="Stateful" />
<jbo:CreateViewObject appid="MypackageModule" name="MyNewViewObject" >

select * from CUSTOMERS
<jbo:DataSource appid="MypackageModule" id="ds1"

viewobject="MyNewViewObject" />
<jbo:RowsetNavigate datasource="ds1" action="First" />
<jbo:RowsetIterate datasource="ds1" >
<jbo:ShowValue datasource="ds1" dataitem="PHONE_NUMBERS" ></jbo:ShowValue>
</BODY>
</HTML>
@ <jbo:ReleasePageResources />
24-28
<jbo:Criteria>
Specifies a WHERE clause value for a view row criteria.
JSP Syntax
<jbo:Criteria
dataitem="attributeName"
value="criteriaValue"
/>
Description
The <jbo:Criteria> data tag creates a new criteria object for the view row criteria instance. An
individual row criteria defines a view object's WHERE clause, where one row criteria contains criteria
for the individual attributes. You use the criteria objects to assemble an arbitrary SQL statement. The
criteria data tags provide a more structured way of creating a SQL query WHERE clause, than
working with the whereclause attribute in the <jbo:Datasource> data tag.
The view criteria provides the context for the contained row criteria and individual criteria. To provide
this context, you must specify the datasource and view criteria instance id on the ViewCriteria data
tag. For this reason, Criteria data tags must appear inside the body of a CriteriaRow tag which
appears inside a ViewCriteria tag, where the actual datasource is specified.
When your JSP page executes, the WHERE clause formed by the row criteria object joins all criteria
statements together in an AND'ed fashion. Thus, in order for a datasource value to be returned as a
search result, it must satisfy each criteria value your CriteriaRow tag defines.
See also: oracle.jbo.ViewCriteriaRow
Attributes
● dataitem—the name of the specific view criteria attribute that contains the data to search. The
name must match a corresponding dataitem name in the datasource specified in the
ViewCriteria tag.
● value—the string used to perform the search. The value must be a valid SQL WHERE clause
statement that must include the desired comparison operator.
Examples
The example below adds a view criteria. The Criteria data tag obtains the criteria value to perform
the search from a JSP edit form when the user clicks the Search or Add Criteria buttons. The JSP
24-29
page with the OnEvent data tag handles the generated event and receives the criteria value.
<jbo:OnEvent list="Search, Add Criteria" >

<% String rowParam = params.getParameter("nRows");
int nRows = 0;
if (rowParam != null)
{
try { nRows = Integer.parseInt(rowParam); }
catch (Exception ex) { }
}
%>
<% for (int index=0; index < nRows; index++)

{ %>
<jbo:CriteriaRow id="row<%=index%>" >
<jbo:AttributeIterate id="attrvc" datasource="ds" queriableonly="true">
<% String item = attrvc.getName();
String value = params.getParameter("row" + index + "_" + item); %>
<jbo:Criteria dataitem="<%=item%>" value="<%=value%>" />
</jbo:CriteriaRow>
<% } %>
</jbo:ViewCriteria>
</jbo:OnEvent>
24-30
<jbo:CriteriaRow>
Specifies a WHERE clause structure and execution options for a view criteria.
JSP Syntax
<jbo:CriteriaRow
id="criteriaRowId"
[ index="number rowIndex | -1" ]
[ uppercolumns="true | false" ]
[ clearall="true | false" ]
>
<Criteria . . . />
</jbo:CriteriaRow>
Description
The <jbo:CriteriaRow> data tag creates a new row criteria object for the view criteria instance. An
individual row criteria defines a view object's WHERE clause, where one row criteria contains criteria
for the individual attributes. You use the criteria objects to assemble a dynamic SQL statement.
While the whereclause attribute in the <jbo:Datasource> data tag provides a simple way to add a
WHERE clause to a datasource, the criteria data tags provide a more structured and dynamic way of
creating a SQL query WHERE clause.
The view criteria provides the context for the contained row criteria and individual criteria. To provide
this context, you must specify the datasource and view criteria instance id on the ViewCriteria data
tag. For this reason, CriteriaRow and Criteria data tags must appear inside the body of a ViewCriteria
tag, where the actual datasource is specified.
When your JSP page executes, the WHERE clause constructed for each row criteria object is
executed against the datasource in an OR'ed fashion. Thus, in order for a datasource value to be
returned as a search result against multiple row criteria, it need only satisfy one of the CriteriaRow
data tag definitions. In addition, each row criteria can contain multiple Criteria definitions, which will
execute the criteria object in an AND'ed fashion. Thus, you can use the structure of CriteriaRow and
Criteria definitions to build a complex, structured, and dynamic WHERE clause against your
datasource.
You can specify whether the row criteria in your JSP page should:
● Append to the criteria values to the previous row criteria. This is the default.
OR
24-31
● Always contain new criteria values.
Unless you create a ViewCriteria tag with its action attribute set to New, row criteria you create are
always appended and the resulting WHERE clause is OR'ed with the view criteria's previous row
criteria definitions. Therefore, if you want to allow users to reexecute the same row criteria with
different criteria values, you must identify the row criteria to update through its index, using the index
attribute. When you specify the index of the row criteria, the dataitems of its individual criteria will be
updated according to these rules:
● Matching criteria dataitems will be overwritten by the new criteria value.

● The values of criteria dataitems which you do not explicitly overwrite will remain unchanged in
the row criteria.
● The value of each criteria dataitem will be cleared if you define the row criteria with the
CriteriaRow tag clearall attribute set to True.
Attributes
● id—the name of the instance of the row criteria created by the CriteriaRow tag. The name you
assign must be unique within a page. This can be any legal Java identifier.
● index—optional, the position of the row criteria you want to modify in the containing view
criteria. The index of row criteria is 0-based: thus, the first row in the view criteria has an index
of 0. If you do not specify an index value, the default value -1 specifies all row criteria.
● uppercolumns—optional, specifies whether the values of dataitems defined by the contained
criteria will be converted to uppercase. The default is false, which allows for case-sensitive
searches. Enter true when you want to perform case-insensitive searches.
● clearall—optional, specifies whether the values of dataitem will be cleared. The default is
false. Enter True when you want to modify an existing row criteria so that the values of
previous criteria dataitems do not persist in the view criteria to be executed. You must specify
a row criteria index when you set clearall to true.
Examples
The example below adds a view criteria to a new criteria row. The Criteria data tag obtains the
criteria value to perform the search from a JSP edit form when the user clicks the Search or Add
Criteria buttons. The JSP page with the OnEvent data tag handles the generated event and receives
the criteria value.

24-32
int nRows = 0;
{
}
%>
<jbo:ViewCriteria id="vc" datasource="ds" action="new">
{ %>
</jbo:CriteriaRow>
<% } %>
</jbo:ViewCriteria>
</jbo:OnEvent>
The example below clears a criteria row on a view criteria. The CriteriaRow data tag uses the index
of an input parameter submitted by a JSP edit form when the user clicks the Delete Criteria button.
The JSP page with the OnEvent data tag handles the generated event and clears the criteria row.
<jbo:OnEvent name="Del Criteria" >

<% String remove = params.getParameter("index"); %>
<jbo:ViewCriteria id="vc" datasource="ds" action="append">
<jbo:CriteriaRow id="row<%=remove%>" index="<%=remove%>" clearall="true" />
</jbo:ViewCriteria>
</jbo:OnEvent>
24-33
<jbo:DataEdit>
Inserts an edit form for a single record into your page and generates an edit submit event.
JSP Syntax
<jbo:DataEdit
datasource="datasourceId"
[ targetURL="event-handling page | the JSP with the component" ]
[ relativeUrlPath="component's JSP page | DataEditComponent.jsp" ]
/>
Description
Use the <jbo:DataEdit> component tag when you want to display an HTML form used to edit a specify
record in the datasource. The form can display:
● A new record that the user inserts

● An existing record that the user updates
The DataEdit component has two methods of obtaining a row to edit:
● It can use the row currency. This is the position of the current row in the datasource to which it is
bound.
● Testing the rowkey input parameter submitted by the form of your JSP page. The rowkey is a special
attribute on the datasource which uniquely identifies each row.
You can use the DataNavigate component to change row currency on the datasource and reflect this
change in the DataEdit component. Both components should be bound to the same datasource.
If you choose not to use the row currency method and prefer to obtain a specific row, then it is your
responsibility to pass a rowkey to the edit form. You can use a DataTable component for this purpose. If you
use the DataTable component with the editTargetURL attribute set to the name of your edit form JSP page,
the DataEdit component obtains the rowkey from the DataTable component. Alternatively, you can explicitly
pass the rowkey yourself through an input parameter your form names:
<td class="tablecell">
<a href="<%=editTargetParam%>?RowKey=<jbo:ShowValue datasource='dsBrowse'
dataitem="RowKey"/>&originURL=<%=originURLParam%>">Edit</a>
</td>
Typically, you provide a separate JSP page that allows the user to view the changes before deciding
whether to continue or return to the edit form. This page is known as the submit JSP page and is identified in
24-34
the targetURL attribute. If you prefer to perform the editing and processing in a same JSP page, your JSP
page must be able to handle the submit event.
Attributes
● datasource—the datasource id, as defined in the <jbo:DataSource> data tag.
The datasource you specify must not use the view object in forward-only mode. The default setting for
<jbo:DataSource> data tag's forwardonly attribute is false. If the forwardonly attribute is set to true,
JSP pages that use Data Component tags will throw a runtime error.
● targetURL—optional, the name of the JSP page you want to use to process the submit event. If a JSP
page target is not supplied, the actions are submitted back to the page that contains the DataEdit
component for processing.
● relativeUrlPath—optional, the location of the JSP file that implements the component tag. The default
references the JDeveloper-provided file DataEditComponent.jsp. You can supply the name of a
component implementation .jsp file that you want to create in order to customize the component
behavior. You can also edit the name to reference an existing component implementation.jsp file that
you have already customized.
If the file you want to create or reference appears in a subdirectory of your project directory site (in
your mywork folder), then you must supply a relative path. For example, you could create the custom
component implementation file MyDataEditComponent.jsp in a subdirectory in the site folder called
components; then the value of relativeUrlPath would be /components/MyDataEditComponent.jsp.
Examples
The example below displays an edit form for the datasource to which it is bound and submits the edited
values to a separate JSP page for processing. In this example, the edit target for the DataEdit is an JSP edit
form. The location of the DataEdit component's JSP page (generated when you insert the tag into the JSP
page) is at the same level as the project JSP pages.
<jbo:ApplicationModule id="am" configname="package1.Package1Module.Package1ModuleLocal"

releasemode="Reserved" />
<jbo:DataSource id="ds" appid="am" viewobject="DeptView" />
DeptView Edit Form

<jbo:DataEdit datasource="ds" targetURL="DeptView_SubmitEdit.jsp" />
Related topics
24-35
24-36
<jbo:DataHandler>
Inserts a component that handles JSP business component-specific events.
JSP Syntax
<jbo:DataHandler
[ relativeUrlPath="component's JSP page | DataHandlerComponent.jsp" ]
/>
Description
The <jbo:DataHandler> component lets you handle JSP business component-specific events, such as: next,
previous, and delete. The DataHandler component uses the <jbo:OnEvent> data tag to handle each event.
When you want to provide automatic handling of business component events, insert the DataHandler
component tag at the top of the JSP page that receives the event. You can handle the generated event either in
the same page that you insert the DataHandler component or in a unique target page.
Attributes
● appid—the application module id, as defined in the <jbo:ApplicationModule> data tag.

references the JDeveloper-provided file DataHandlerComponent.jsp. You can supply the name of a
component implementation .jsp file that you want to create in order to customize the component behavior.
You can also edit the name to reference an existing component implementation.jsp file that you have
already customized.
If the file you want to create or reference appears in a subdirectory of your project directory site (in your
mywork folder), then you must supply a relative path. For example, you could create the custom
component implementation file MyDataHandlerComponent.jsp in a subdirectory in the site folder called
components; then the value of relativeUrlPath would be /components/MyDataHandlerComponent.jsp.
Examples
The example below handles events on the application module session to which it is bound. In this example, the
target for the DataHandler is the JSP with the component.

<jbo:DataSource id="LocationsView" appid="am" viewobject="LocationsView"/>
<jbo:DataHandler appid="am" />
Related topics
24-37

24-38
<jbo:DataNavigate>
Inserts a rowset navigation bar into your page and handles row navigation events.
JSP Syntax
<jbo:DataNavigate
[ relativeUrlPath="component's JSP page | DataNavigateComponent.jsp" ]
/>
Description
Use the <jbo:DataNavigate> component tag when you want to be able to change the position of the current
row on the datasource to which it is bound. Changing the row currency permits users to navigate through the
datasource one record at a time. You can use the DataNavigate component, for example, to change the row
currency and reflect this change in a DataEdit component or DataRecord component. The components you
use to display the current row should be bound to the same datasource as the DataNavigate component.
The navigation bar rendered by the DataNavigate component displays First, Next, Previous, and Last action
links. The user can change the row position by clicking one of the action links. Depending on the position of
the current row, the DataNavigate component can handle these row navigation actions:
● First—changes the row currency to the first row in the datasource

● Next—changes the row currency to the next row in the datasource
● Previous—changes the row currency to the previous row in the datasource
● Last—changes the row currency to the last row in the datasource
Note: If the position of the current row is the last or first row in the datasource when the navigation bar
is rendered, then some of the action links will appear disabled.
When the JSP page with DataNavigate component executes the first time during a session, a row currency
might not exist for the datasource. Therefore, it is necessary to explicitly set the row currency before
rendering the navigation bar. You should use this scriplet code in any JSP page that has a DataNavigate
component to set row currency:
<% if (ViewObjectName.getRowSet().getCurrentRow() == null)

{ %>
<jbo:RowsetNavigate datasource="myDatasource" action="First"/>
<% } %>
Typically, you use the same JSP page to display the navigation bar, handle the row navigation event, and
display the records. In this case, you need not specify a targetURL value. Navigation and display in the
24-39
same JSP page is possible because the DataNavigate component performs two operations:
● First, it executes the row navigation action by handling the navigation event.
● Second, it renders the navigation bar with the appropriate action links.
However, if you prefer to navigate and display in separate JSP pages, you can supply the name of the
display page in the targetURL attribute.
Attributes
The datasource you specify must not use the view object in forward-only mode. The default setting for
<jbo:DataSource> data tag's forwardonly attribute is false. If the forwardonly attribute is set to true,
JSP pages that use Data Component tags will throw a runtime error.
● targetURL—optional, the name of the JSP page you want to use to process the row navigation event.
If a JSP page target is not supplied, the actions are submitted back to the page that contains the
DataNavigate component for processing.
references the JDeveloper-provided file DataNavigateComponent.jsp. You can supply the name of a
component implementation .jsp file that you want to create in order to customize the component
behavior. You can also edit the name to reference an existing component implementation.jsp file that
you have already customized.
If the file you want to create or reference appears in a subdirectory of your project directory site (in
your mywork folder), then you must supply a relative path. For example, you could create the custom
component implementation file MyDataNavigateComponent.jsp in a subdirectory in the site folder
called components; then the value of relativeUrlPath would be
/components/MyDataNavigateComponent.jsp.
Examples
The example below displays a navigation bar for the datasource to which it is bound. In this example, the
target for the DataNavigate is the JSP with the component. The location of the DataNavigate component's
JSP page (generated when you insert the tag into the JSP page) is at the same level as the project JSP
pages. The scriplet code is necessary to set the row currency of the datasource when the current row is null;
otherwise, the DataNavigate component will not be initialized.
<jbo:ApplicationModule id="am" configname="package1.Package1Module.Package1ModuleLocal"

<jbo:DataSource id="myDS" appid="am" viewobject="DeptView"/>
<% if (myDS.getRowSet().getCurrentRow() == null)
{ %>
<jbo:RowsetNavigate datasource="myDS" action="First"/>
24-40
<% } %>
<jbo:DataNavigate datasource="myDS" />
Related topics

24-41
<jbo:DataQuery>
Inserts a query form to edit and process view criteria on a bound datasource.
JSP Syntax
<jbo:DataQuery
[ relativeUrlPath="component's JSP page | DataQueryComponent.jsp" ]
/>
Description
Use the <jbo:DataQuery> component tag when you want to provide users with the ability to
enter queries for a specific datasource. The DataQuery component lets users specify view
criteria on any of the attributes of the datasource to which it bound. The user executes a query
using the DataQuery component by:
1. Entering values in the view criteria field for the attributes they want to match. The entered
value must include the appropriate comparison symbol (>, <, =). All values in the same
view criteria are AND'ed together.
2. Optionally, click Add Criteria to specify a new view criteria that is automatically OR'ed to
any preceeding view criteria.
3. Click Search in the query form to display the results in a DataTable component
automatically rendered by the DataQuery component.
Typically, you use the same JSP page to display the query form, handle the query event, and
display the query results records. In this case, you need not specify a targetUrl value. Query
and display in the same JSP page is possible because the DataQuery component performs two
operations:
● First, it renders an empty query form with buttons that let the user add new criteria to the
search or clear all.
● Second, it executes the query. If matching records are found, then it renders a DataTable
component to display the results.
However, if you prefer to query and display results in separate JSP pages, you can supply the
24-42
name of the results page in the targetURL attribute.
Note: The number of records that the DataTable component can display is determined by the
rangeSize attribute on the datasource being queried.
Attributes
The datasource you specify must not use the view object in forward-only mode. The
default setting for <jbo:DataSource> data tag's forwardonly attribute is false. If the
forwardonly attribute is set to true, JSP pages that use Data Component tags will throw a
runtime error.
● targetURL—optional, the name of the JSP page you want to use to process the query. If
a JSP page target is not supplied, the query results are submitted back to the page that
contains the DataQuery component for display.
● relativeUrlPath—optional, the location of the JSP file that implements the component
tag. The default references the JDeveloper-provided file DataQueryComponent.jsp. You
can supply the name of a component implementation .jsp file that you want to create in
order to customize the component behavior. You can also edit the name to reference an
existing component implementation.jsp file that you have already customized.
If the file you want to create or reference appears in a subdirectory of your project
directory site (in your mywork folder), then you must supply a relative path. For example,
you could create the custom component implementation file
MyDataQueryComponent.jsp in a subdirectory in the site folder called components; then
the value of relativeUrlPath would be /components/MyDataQueryComponent.jsp.
Examples
In this example, the target for the DataQuery is the JSP with the component.
<jbo:DataQuery datasource="LocationsView" />
Related topics
24-43

24-44
<jbo:DataRecord>
Inserts a component that displays a single record bound to a datasource.
JSP Syntax
<jbo:DataRecord
[ relativeUrlPath="component's JSP page | DataRecordComponent.jsp"]
/>
Description
Use the <jbo:DataRecord> component tag when you want to display a single record from the
datasource to which it is bound.
The DataRecord component has two methods of obtaining a row to display:
● It can use the row currency. This is the position of the current row in the datasource to which
it is bound.
● It can use the rowkey input parameter submitted by the form of your JSP page. The rowkey is
a unique identifier for each row.
You can use the DataNavigate component to change row currency on the datasource and reflect
this change in the DataRecord component. Both components should be bound to the same
datasource.
If you choose not to use the row currency method and prefer to obtain a specific row, then it is your
responsibility to pass a rowkey to the display form. In this case, you must explicitly pass the rowkey
yourself through an input parameter your form names:
<a href="<%=displayTargetParam%>?RowKey=<jbo:ShowValue datasource='dsBrowse'
dataitem='RowKey'/>&originURL=<%=originURLParam%>">Display</a>
</td>
OR, using the convenience data tag <jbo:UrlEvent>:
<a href="<jbo:UrlEvent datasource="dsBrowse" addRowKey="true">
24-45
</td>
Attributes
The datasource you specify must not use the view object in forward-only mode. The default
setting for <jbo:DataSource> data tag's forwardonly attribute is false. If the forwardonly
attribute is set to true, JSP pages that use Data Component tags will throw a runtime error.
● relativeUrlPath—optional, the location of the JSP file that implements the component tag.
The default references the JDeveloper-provided file DataRecordComponent.jsp. You can
supply the name of a component implementation .jsp file that you want to create in order to
customize the component behavior. You can also edit the name to reference an existing
component implementation.jsp file that you have already customized.
If the file you want to create or reference appears in a subdirectory of your project directory
site (in your mywork folder), then you must supply a relative path. For example, you could
create the custom component implementation file MyDataRecordComponent.jsp in a
subdirectory in the site folder called components; then the value of relativeUrlPath would be
/components/MyDataRecordComponent.jsp.
Examples
The example below displays a single record for the datasource to which it is bound. In this example,
the location of the DataRecord component's JSP page (generated when you insert the tag into the
JSP page) is at the same level as the project JSP pages.
<jbo:DataRecord datasource="LocationsView" />
Related topics

24-46
<jbo:DataScroller>
Inserts a component that scrolls records in sets controlled by the bound datasource's range
size.
JSP Syntax
<jbo:DataScroller
[ relativeUrlPath="component's JSP page | DataScrollerComponent.jsp" ]
/>
Description
Use the <jbo:DataScroller> component tag when you want to be able to change the position of
the viewable range on the datasource to which it is bound. Changing the range position permits
users to navigate through the datasource multiple records at a time. Typically you use the
DataScroller component with a DataTable component to display the current range. The
DataScroller component and the DataTable component you together should be bound to the
same datasource.
The number of records the DataScroller component scrolls is controlled by the view object's
range size. In your JSP pages, you can control the size of this range by setting the rangeSize
attribute for the <jbo:DataSource> data tag. For example, if you specify a rangeSize of 10, then
the DataScroller component will move the current range position on the datasource ten records
at a time. If you do not set the rangeSize for the datasource to which the DataScroller
component is bound, then the DataScroller component will scroll a single record at a time.
The scroller rendered by the DataScroller component displays the index of the first row and the
last row of the current range; it also displays the count of the entire viewable range. The user
can change the range position by clicking the scroller's Next and Previous action links.
Depending on the position of the range, the DataScroller component can handle these range
navigation actions:
● NextSet—moves the viewable range to the first row after the previous range position
● PreviousSet—moves the viewable range to the rows located just before the previous
range position
Note: If the range position is already on the last or first set when the scroller is rendered, then
the Next or Previous action link will appear disabled.
24-47
Typically, you use the same JSP page to display the data scroller, handle the navigation event,
and display the records. In this case, you need not specify a targetURL value. Navigation and
display in the same JSP page is possible because the DataScroller component performs two
operations:
● First, it executes the range navigation action by handling the navigation event.
● Second, it renders the data scroller with the appropriate action links.
If you prefer to navigate and display in separate JSP pages, you can supply the name of the
display page in the targetURL attribute.
Usage Notes
When you add a DataScroller component to a JSP page, the application module should be
released in either Stateful or Reserved mode, but not Stateless mode. Using either Stateful or
Reserved mode ensures the next time the JSP page executes (immediately after the user
triggers a data scroller navigation event), the position of the range will be preserved.
The datasource you specify for the DataScroller must not use the view object in forward-only
mode. The default setting for <jbo:DataSource> data tag's forwardonly attribute is false. If the
forwardonly attribute is set to true, JSP pages that use Data Component tags will throw a
runtime error.
Attributes

● targetURL—optional, the name of the JSP page you want to use to process the range
navigation event. If a JSP page target is not supplied, the actions are submitted back to
the page that contains the DataScroller component for processing.
● relativeUrlPath—optional, the location of the JSP file that implements the component
tag. The default references the JDeveloper-provided file DataScrollerComponent.jsp.
You can supply the name of a component implementation .jsp file that you want to create
in order to customize the component behavior. You can also edit the name to reference
an existing component implementation.jsp file that you have already customized.
If the file you want to create or reference appears in a subdirectory of your project
directory site (in your mywork folder), then you must supply a relative path. For example,
you could create the custom component implementation file
24-48
MyDataScrollerComponent.jsp in a subdirectory in the site folder called components;
then the value of relativeUrlPath would be /components/MyDataScrollerComponent.jsp.
Examples
The example below displays a scroll bar for the datasource to which it is bound. In this
example, the target for the DataScroller is the JSP with the component. The location of the
DataScroller component's JSP page (generated when you insert the tag into the JSP page) is
at the same level as the project JSP pages.
<jbo:DataScroller datasource="LocationsView" />
Related topics

24-49
<jbo:DataSource>
Creates a datasource instance based on a view object that:
● Already exists in a Business Components application module you specify

● You create dynamically, using the CreateViewObject data tag
JSP Syntax
<jbo:DataSource
id="dataSourceInstanceName"
appid="appModuleInstanceName"
viewobject="viewObjectName"
[ whereclause="filterString" ]
[ orderbyclause="orderbyString" ]
[ rangesize="number of rows displayed | -1 | 1" ]
[ forwardonly="true | false" ]
/>
Description
The DataSource tag gives you a handle to the datasource instance that you can pass to other
data tags that act on rowsets and attributes, such as the RowsetIterate or ShowValue tags.
See also: oracle.jbo.ViewObject
Attributes
● id—the name of the instance of the datasource created by the DataSource tag. The
name you assign must be unique within a page. This can be any legal Java identifier.
Within a scriptlet, you may use the id as a scriptable variable of type
oracle.jbo.html.DataSource.
● viewobject—the full name of the view object you want to use as it appears in your
Business Components project. You can specify an existing view object defined by the
application module or a view object you created using the CreateViewObject data tag. If
the view object is contained in a nested application module, you must specify the view
24-50
object name with the application module name: appmodNested.viewobjectName.
● whereclause—optional, sets the WHERE clause on the view object to limit the rowset.
This is a standard SQL clause.
Note: The name of the columns you supply for the WHERE clause cannot be database
column names: You must use the name defined by the ColumnNameForQuery property of
the view object's attribute definition. See the <jbo:ShowDefinition> data tag to obtain the
ColumnNameForQuery value.
● orderbyclause—optional, set the ORDERBY clause on the view object to specify how to
order the rows. This is a standard SQL clause.
Note: The name of the columns you supply for the ORDERBY clause cannot be database
column names: You must use the name defined by the ColumnNameForQuery property of
the view object's attribute definition. See the <jbo:ShowDefinition> data tag to obtain the
ColumnNameForQuery value.
You can order rows in ascending or descending order using:
❍ Expression -- order rows based on their value for expression
For example, the following statement shows how to select all the sales
representatives' records from the Employee view object and order the results by
commission in descending order.
ORDER BY comm DESC
❍ Position -- order rows based on their value for the expression in this position on
the select list. Sorting by position is useful when an expression is long. Rather
than duplicating the entire expression from the select list, you can specify its
position.
For example, the following statement shows how to select employees from the
Employee view object and order them first by department (in ascending order) and
then by salary (in descending order) using ordinal positioning.
ORDER BY 2 ASC, 3 DESC
● rangesize—optional, the number of rows in a range to fetch from the view object. This is
24-51
useful when you do not want to work with an entire rowset. A range effectively defines a
window you can use to access a subset of the rows in the datasource. Ranges are useful
when the rowset is large and you do not want to bring all of the rows to the client, or
when you want to display a certain number of rows on the page. By default, the range
size is set to a range of a single row (the value 1). The value -1 fetches all rows.
● forwardonly—optional, specifies whether the rows will be accessed sequentially by the

view object. The default is false, which allows users to change data in the view object.
When set to true, forward-only mode prevents a row preceeding the current row from
being designated as the new current row. You may set to true, to obtain faster retrieval of
rows, when you want to perform a quick iteration of the rows. Forward-only mode is not
suitable when you permit users to edit row data or navigate rows (such as when using a
DataScroller component).
Note: JSP pages that use BC4J Data Component tags will throw a runtime error when
forward-only mode is enabled for the datasource. You must leave forwardonly set to false
(default) when you add a BC4J Data Component tag to your JSP page.
Example
<jbo:DataSource id="category_vo" appid="OnlineOrdersModule" viewobject="CategoryView" />
<jbo:DataSource
id="customer_vo1" appid="OnlineOrdersModule"
whereclause="<%= wc %>"
viewobject="CustomerView" />
Here's a more complete example.

<jbo:DataSource id="ds1" appid="OnlineOrdersModule" whereclause="id > 206"

rangesize="20" viewobject="CustomerView" />

<jbo:ShowValue datasource="ds1" dataitem="Id" ></jbo:ShowValue>
<jbo:ShowValue datasource="ds1" dataitem="Firstname" ></jbo:ShowValue>
<jbo:ShowValue datasource="ds1" dataitem="Lastname" ></jbo:ShowValue>
24-52
</BODY>
</HTML>
24-53
<jbo:DataSourceRef>
Creates a datasource variable based on a datasource instance.
JSP Syntax
<jbo:DataSourceRef
id="dataSourceVariableName"
reference="dataSourceInstanceName"
/>
Description
The <jbo:DataSourceRef> tag lets you create a datasource variable of type

oracle.jbo.html.Datasource. You can use the tag to reference a datasource in your JSP pages.
It is necessary to use a datasource reference when you want to use an <jsp:include> tag to
include another JSP page that needs to access the datasource. For example, the BC4J
Component tags use the datasource variable created by the DataSourceRef tag to reference
the datasource of the page that created the datasource instance.
Attributes
● id—the name of the datasource variable this tag creates. The name you assign must be
unique within a page. This can be any legal Java identifier.
● reference—the name of the instance of the datasource created by the DataSource tag.
Examples
This example creates a datasource reference using an input parameter.
<%
RequestParameters params = HtmlServices.getRequestParameters(pageContext);
String dsParam = params.getParameter("datasource");
%>
<jbo:DataSourceRef id="dsQuery" reference="<%=dsParam%>"/>
24-54
<jbo:DataTable>
Inserts a component that displays a table bound to a datasource and optionally links to an edit form.
JSP Syntax
<jbo:DataTable
[ editTargetURL="event-handling page | the JSP with the component" ]
[ relativeUrlPath="component's JSP page | DataTableComponent.jsp" ]
/>
Description
Use the <jbo:DataTable> component tag when you want to display multiple records from the
datasource to which it is bound. An example of the DataTable component is used to display records
from the detail datasource in a master-detail type JSP page. In this situation, the user navigates
through the individual records displayed by the master form in order to view multiple records in the
detail form.
The number of records the DataTable component displays is controlled by the view object's range
size. In your JSP pages, you can control the size of this range by setting the rangeSize attribute for
the <jbo:DataSource> data tag. You set a numeric value for this attribute to limit the number of
records the user can view in the DataTable component at one time. For example, if you specify a
rangeSize of 10, then the DataTable component will display ten records from the datasource at a
time. In this case, you can add a DataScroller component to your JSP page to change the position
of the range. The DataScroller component permits the user to scroll through the records by sets (in
our example, with a rangeSize of 10, users would scroll ten records at a time). If you do not set the
rangeSize for the datasource to which the DataTable component is bound, then the DataTable
component will display a single record.
Note: If you don't use a DataScroller component with the DataTable component, the records displayed
by the DataTable component will be determined by the current state of the datasource range.
You can also use the DataTable component to display records that you want the user to be able to
edit. You use the editTargetURL attribute to supply the name of the JSP page that you want to
handle the row editing action. The DataTable component you configure to edit rows displays links
for these two operations:
● Delete the row—the DataTable component handles the row action

● Edit the row—an Edit JSP page you specify handles the row action
24-55
When you use the DataTable component with the options to edit and delete records, the DataTable
component passes a rowkey input parameter to the edit JSP page for to identify the specific row.
The following sample shows how the form containing the DataTable component obtains the rowkey
and submits it to the processing page:
<a HREF example here /a>
Attributes
The datasource you specify must not use the view object in forward-only mode. The default
setting for <jbo:DataSource> data tag's forwardonly attribute is false. If the forwardonly
attribute is set to true, JSP pages that use Data Component tags will throw a runtime error.
● editTargetURL—optional, the name of the JSP page you want to use to edit the records of
the DataTable component. If you do not supply a JSP page target, then the DataTable
component displays records without the option to edit or delete them.
● relativeUrlPath—optional, the location of the JSP file that implements the component tag.
The default references the JDeveloper-provided file DataTableComponent.jsp. You can
supply the name of a component implementation .jsp file that you want to create in order to
customize the component behavior. You can also edit the name to reference an existing
component implementation.jsp file that you have already customized.
If the file you want to create or reference appears in a subdirectory of your project directory
site (in your mywork folder), then you must supply a relative path. For example, you could
create the custom component implementation file MyDataTableComponent.jsp in a
subdirectory in the site folder called components; then the value of relativeUrlPath would be
/components/MyDataTableComponent.jsp.
Examples
The example below displays a table for the datasource to which it is bound. In this example, the edit
target for the DataTable is an JSP edit form. The location of the DataTable component's JSP page
(generated when you insert the tag into the JSP page) is at the same level as the project JSP
pages.
LocationsView Table with Edit Link

<jbo:DataTable datasource="LocationsView" edittarget="LocationsView_Edit.jsp" />
24-56
Related topics

24-57
<jbo:DataTransaction>
Inserts a component that renders user selectable links to commit or rollback database transactions.
JSP Syntax
<jbo:DataTransaction
[ relativeUrlPath="component's JSP page | DataTransactionComponent.jsp" ]
/>
Description
The <jbo:DataTransaction> component inserts links in the JSP page that users may select to commit or roll
back changes made on the datasource. The state of the links rendered by the page reflects the current state of
the datasource: links will be greyed out and not selectable when the data is unchanged or the user has already
committed all datasource changes to the database.
The DataTransaction component relies on the <jbo:Commit> and <jbo:Rollback> data tags to handle the user's
link selection. You can insert the DataTransaction component tag inside the JSP page that contains the edit
form. You can handle the database transaction in the same page that you insert the DataTransaction
component tag or in a unique target page.
Attributes
● appid—the application module id, as defined in the <jbo:ApplicationModule> data tag.

● targetURL—optional, the name of the JSP page you want to use to process the users commit or rollback
selection. If a JSP page target is not supplied, the actions are submitted back to the page that contains
the DataTransaction component for processing.
references the JDeveloper-provided file DataTransactionComponent.jsp. You can supply the name of a
component implementation .jsp file that you want to create in order to customize the component behavior.
You can also edit the name to reference an existing component implementation.jsp file that you have
already customized.
If the file you want to create or reference appears in a subdirectory of your project directory site (in your
mywork folder), then you must supply a relative path. For example, you could create the custom
component implementation file MyDataTransactionComponent.jsp in a subdirectory in the site folder
called components; then the value of relativeUrlPath would be
/components/MyDataTransactionComponent.jsp.
Examples
The example below handles database transactions on the application module session to which it is bound. In
this example, the target for the DataTransaction is the JSP with the component.
24-58
<jbo:DataSource id="LocationsView" appid="am" viewobject="LocationsView"/>
<jbo:DataTransaction appid="am" />
Related topics

24-59
<jbo:DataWebBean>
A tag to use a data web bean in your JSP.
JSP Syntax
<jbo:DataWebBean
id="dataWebBeanInstanceName"
wbclass="webbeanclassname"
/>
Description
The <jbo:DataWebBean> tag is useful when you want to:
● Reuse custom web beans in a data tag application

● Migrate an older style web beans-based JSP applications to a JSP application using only data
tags
Although users may continue to develop new applications with <jsp:useBean> in data tag-style JSP
applications, we do not recommend using the data web bean and web bean classes provided in the
oracle.jbo.html.databeans and oracle.jbo.html.webbeans packages for this purpose; instead, we
recommend developing new applications entirely with the BC4J data tags and component tags.
To migrate a web bean-style application developed in JDeveloper version 3.2 or earlier to a data tag-
style application, you must:
1. Add tags to define an application module and datasource in your JSP file.
2. Replace the <jsp:usebean> tag with the appropriate <jbo:DataWebBean> or <jbo:WebBean>
tag.
3. Remove the initialize() method (now done by datasource tag).
4. Remove the setReleasePageResources() method (now done by ApplicationModule tag).
5. Prefix the set property methods with a scriptable variable instance of the web bean (obtained
from the data tag's id="" attribute).
6. Leave the render() method, but move it outside the data tag.
Example
In a web bean-style application, you need to refer to the JavaDoc to call methods on the bean instance.
For example, the <jsp:useBean> tag with a EditCurrentRecord web bean might look like this:
24-60
<jsp:useBean class="oracle.jbo.html.databeans.EditCurrentRecord"
id="efDetail" scope="request" >
<%
efDetail.setUseRoundedCorners(true);
efDetail.setSubmitText("Save Changes");
efDetail.setDeleteText("Delete Record");
efDetail.setShowRecordNumbers(true);
efDetail.setMaximumFieldWidth(40);
efDetail.setMaximumFieldHeight(0);
efDetail.setReleaseApplicationResources(true);
efDetail.initialize(application,session, request,response,out,
"package3_Package3Module.EmpView");
efDetail.render();
%>
</jsp:useBean>
In this example, you use the <jbo:DataWebBean> tag to replace the old <jsp:useBean> tag:
<jbo:ApplicationModule configname="myconfig" id="myappmod" releasemode="stateful"/>

<jbo:DataSource id="myds" appid="myappmod" viewobject="myvo" />
<jbo:DataWebBean id="efDetail" datasource="myds"
wbclass="oracle.jbo.html.databeans.EditCurrentRecord" >
<%
%>
</jbo:DataWebBean>
<%
efDetail.render();
%>
...additional page content...
</jbo:ReleasePageResources />
Attributes
● id—the name of the instance of the data web bean. The name you assign must be unique within
a page. This can be any legal Java identifier. Within a scriptlet, you use the id as a scriptable
variable of type oracle.jbo.html.databeans.classname, where classname is the name of the web
bean.
● wbclass—the fully qualified name of the web bean class. For example,
oracle.jbo.html.databeans.EditCurrentRecord.
24-61
24-62
<jbo:EmbedAudio>
Inserts an HTML block that is composed of <Object> and nested <Embed> tags. This HTML block renders media content
stored as an interMedia object in the Oracle database.
JSP Syntax
<jbo:EmbedAudio
[ width="pluginWidth" ]
[ height="pluginHeight" ]
[[ alt="alternateText" ] | [ altattr="alternateAttributeName" ]]
[ title="advisoryTitle" ]
[ helperapp="WindowsMediaPlayer | QuickTimePlayer | RealMediaPlayer" ]
[ showcontrols="showControls" ]
[ autoplay="autoStart" ]
[ loop="loopPlay" ]
[ standby="standbyText" ]
/>
Description
The <jbo:EmbedAudio> data tag lets you embed a helper application, such as an ActiveX control or a plug-in, in your browser to
play media content stored as an interMedia object in the database. You can specify which helper application you want to use,
the height and width of the helper application, as well as other attributes.
Currently, there are only three helper applications that the <jbo:EmbedAudio> data tag supports:
● Windows Media Player

● QuickTime player
● RealMedia Player
The generated HTML code is a <OBJECT></OBJECT> block with nested <EMBED> tags. The JSP page that uses
<jbo:EmbedAudio> data tag works correctly in Microsoft Internet Explorer, but sometimes fails in Netscape Navigator. This is
due to Netscape's lack of support for <OBJECT> tag and the limitation of <EMBED> tag. Because the Netscape browser
doesn't fully support <OBJECT> tag, it usually ignores the <OBJECT> tag and uses the nested <EMBED> tag. A known
limitation of <EMBED> tag is that there is no way to specify the exact plug-in to use. The invocation of the plug-in purely
depends on the association of plug-ins and MIME types in the Netscape browser.
24-63
Attributes
ordPlayMedia.jsp.
● width—optional, the width of the helper application. The default is 300.
● height—optional, the height of the helper application. The default is 200.
● alt—optional, the alternate text if the browser does not support the renderring of the media content. This attribute should
not be used if altattr attribute is specified.
● altattr—optional, the name of the attribute that contains the alternate text. This attribute should not be used if alt attribute
is specified.
● title—optional, the advisory title.
● helperapp—optional, the name of the supported browser helper applications: WindowsMediaPlayer, QuickTimePlayer,
and RealMediaPlayer. If this attribute is not specified or specified with an unknown string, the default helper application
WindowsMediaPlayer will be used.
● showcontrols—optional, whether to display the control components of the helper applicaiton. Valid values are true and
false. The default is true.
● autoplay—optional, whether to auto start the renderring of the media content. Valid values are true and false. The default
is true.
● loop—optional, whether to loop the renderring of the media content. Valid values are true and false. The default is false.
● standby—optional, the standby message when the data is loading.
Example 1:
<jbo:EmbedAudio datasource="ds" mediaattr="Clip" whereclause="id = 5" />
HTML Output
24-64
<OBJECT CLASSID="clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95" HEIGHT="200" WIDTH="300"
CODEBASE="http://activex.microsoft.com/activex/controls/mplayer/en/nsmp2inf.cab#Version=5,1,52,701" >
<PARAM NAME="FileName" VALUE="[mediaFetchingURL]">
<PARAM NAME="AutoStart" VALUE="true">
<PARAM NAME="ShowControls" VALUE="true">
<EMBED SRC="[mediaFetchingURL]" HEIGHT="200" WIDTH="300"

PLUGINSPAGE="http://www.microsoft.com/isapi/redir.dll?prd=windows&sbp=mediaplayer&ar=Media&sba=Plugin&"
AutoStart="true" ShowControls="true" >
</EMBED>
</OBJECT>
Example 2:

<jbo:EmbedAudio datasource="ds" mediaattr="Clip" helperapp="QuickTimePlayer" autoplay="false" alt="My favorite song." />
HTML Output
<OBJECT CLASSID="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B" HEIGHT="200" WIDTH="300"

CODEBASE="http://www.apple.com/qtactivex/qtplugin.cab" >
<PARAM NAME="SRC" VALUE="[mediaFetchingURL]">
<PARAM NAME="HEIGHT" VALUE="200">
<PARAM NAME="WIDTH" VALUE="300">
<PARAM NAME="AUTOPLAY" VALUE="false">
<PARAM NAME="CONTROLLER" VALUE="true">
<PARAM NAME="LOOP" VALUE="false">
<EMBED SRC="[mediaFetchingURL]" TYPE="video/quicktime" HEIGHT="200" WIDTH="300" AUTOPLAY="false"

CONTROLLER="true" LOOP="false" PLUGINSPAGE="http://www.apple.com/quicktime/download/" >
</EMBED>
<NOEMBED>My favorate song.</NOEMBED>
</OBJECT>
24-65
<jbo:EmbedImage>
Inserts an HTML IMG tag that displays the image content stored as an interMedia object in the Oracle database.
JSP Syntax
<jbo:EmbedImage
[ width="imageWidth" ]
[ height="imageHeight" ]
[ border="borderPixel" ]
[ align="alignOption" ]
[ longdesc="longDescription" ]
/>
Description
The <jbo:EmbedImage> data tag lets you embed an HTML IMG tag to display image content stored as an interMedia object in
the database.
Attributes
ordPlayMedia.jsp.
● width—optional, the width of the displayed image. If this attribute is not specified, <jbo:EmbedImage> data tag tries to
use the actual width parsed by interMedia from the image content. If the image can not be parsed by interMedia, the
24-66
width attribute is not set.
● height—optional, the height of the displayed image. If this attribute is not specified, <jbo:EmbedImage> data tag tries to
use the actual height parsed by interMedia from the image content. If the image can not be parsed by interMedia, the
height attribute is not set.
● border—optional, the border pixel number. This has the same usage as "BORDER" attribute in an HTML IMG tag.
● align—optional, the align option. This has the same usage as the ALIGN attribute in an HTML IMG tag.
● alt—optional, the alternate text for the image. This attribute should not be used if the altattr attribute is specified.
● altattr—optional, the name of the attribute that contains the alternate text. This attribute should not be used if alt attribute
is specified.
● longdesc—optional, long description of the image. This has the same usage as the LONGDESC attribute in an HTML
IMG tag.
Example 1:
<jbo:EmbedImage datasource="ds" mediaattr="Pic" whereclause="id = 2" alt="family reunion picture" />
HTML Output
<IMG SRC="[mediaFetchingURL]" ALT="family reunion picture" WIDTH="400" HEIGHT="350">
Example 2:

<jbo:EmbedImage datasource="ds" mediaattr="Pic" altattr="Description" border="2" width="200" height="200" />
HTML Output
<IMG SRC="[mediaFetchingURL]" ALT="[description text]" BORDER="2" WIDTH="200" HEIGHT="200">
24-67
<jbo:EmbedVideo>
Inserts an HTML block that is composed of <Object> and nested <Embed> tags. This HTML block renders video content stored
as an interMedia object in the Oracle database.
JSP Syntax
<jbo:EmbedVideo
[ width="pluginWidth" ]
[ height="pluginHeight" ]
[ title="advisoryTitle" ]
[ helperapp="WindowsMediaPlayer | QuickTimePlayer | RealMediaPlayer" ]
[ showcontrols="showControls" ]
[ autoplay="autoStart" ]
[ loop="loopPlay" ]
[ standby="standbyText" ]
/>
Description
The <jbo:EmbedVideo> data tag lets you embed a helper application, such as an ActiveX control or a plug-in, in your browser to
play media content stored as an interMedia object in the database. You can specify which helper application you want to use,
the height and width of the helper application, and many other attributes.
Currently, there are only three helper applications that the <jbo:EmbedVideo> data tag supports:
● Windows Media Player

● QuickTime playe
● RealMedia Player
The generated HTML code is a <OBJECT></OBJECT> block with nested <EMBED> tags. The JSP page that uses
<jbo:EmbedVideo> tag works correctly in Microsoft Internet Explorer, but sometimes fails in Netscape Navigator. This is due to
Netscape's lack of support for <OBJECT> tag and the limitation of <EMBED> tag. Because Netscape browser doesn't fully
support <OBJECT> tag, it usually ignores the <OBJECT> tag and uses the nested <EMBED> tag. A known limitation of
<EMBED> tag is that there is no way to specify the exact plug-in to use. The invocation of the plug-in purely depends on the
association of plug-ins and MIME types in the Netscape browser.
24-68
Attributes
ordPlayMedia.jsp.
● width—optional, the width of the helper application. The default is 300.
● height—optional, the height of the helper application. The default is 200.
● alt—optional, the alternate text if the browser does not support the renderring of the media content. This attribute should
not be used if altattr attribute is specified.
● altattr—optional, the name of the attribute that contains the alternate text. This attribute should not be used if the alt
attribute is specified.
● title—optional, the advisory title.
● helperapp—optional, the name of the supported browser helper applications: WindowsMediaPlayer, QuickTimePlayer,
and RealMediaPlayer. If this attribute is not specified or specified with an unknown string, the default helper application
WindowsMediaPlayer will be used.
● showcontrols—optional, whether to display the control components of the helper applicaiton. Valid values are true and
false. The default is true.
● autoplay—optional, whether to auto start the renderring of the media content. Valid values are true and false. The default
is true.
● loop—optional, whether to loop the renderring of the media content. Valid values are true and false. The default is false.
● standby—optional, the standby message when the data is loading.
Example 1:
<jbo:EmbedVideo datasource="ds" mediaattr="Movie" whereclause="id = 2" title="playing movie" />
HTML Output
24-69
<OBJECT CLASSID="clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95" HEIGHT="200" WIDTH="300" TITLE="playing
movie" CODEBASE="http://activex.microsoft.com/activex/controls/mplayer/en/nsmp2inf.cab#Version=5,1,52,701" >
<PARAM NAME="FileName" VALUE="[mediaFetchingURL]">
<PARAM NAME="AutoStart" VALUE="true">
<PARAM NAME="ShowControls" VALUE="true">
<EMBED SRC="[mediaFetchingURL]" HEIGHT="200" WIDTH="300"

PLUGINSPAGE="http://www.microsoft.com/isapi/redir.dll?prd=windows&sbp=mediaplayer&ar=Media&sba=Plugin&"
AutoStart="true" ShowControls="true" >
</EMBED>
</OBJECT>
Example 2:

<jbo:EmbedVideo datasource="ds" mediaattr="Movie" helperapp="RealMediaPlayer" altattr="Description" />
HTML Output
<OBJECT CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA" HEIGHT="200" WIDTH="300" >

<PARAM NAME="SRC" VALUE="[mediaFetchingURL]">
<PARAM NAME="AUTOSTART" VALUE="true">
<PARAM NAME="CONTROLS" VALUE="ImageWindow,ControlPanel">
<EMBED SRC="[mediaFetchingURL]" TYPE="audio/x-pn-realaudio-plugin" HEIGHT="200" WIDTH="300" AUTOSTART="true"

CONTROLS="ImageWindow,ControlPanel" PLUGINSPAGE="http://www.real.com/player/" >
</EMBED>
<NOEMBED>[description text]</NOEMBED>
</OBJECT>
24-70
<jbo:ExecuteSQL>
Executes a SQL statement via the data application connection defined by the
ApplicationModule data tag.
JSP Syntax
<jbo:ExecuteSQL
appid="appModuleInstance">
Query_Statement
<jbo:ExecuteSQL/>
Description
The ExecuteSQL tag does not generate a data cache and, therefore, cannot execute a
SELECT statement. Use the tag when you want to perform an operation directly on the
database.
If you want to generate a rowset, use the CreateViewObject data tag. It accepts a SELECT
statement to generate a dynamic view object.
Attributes
Example
<jbo:ExecuteSQL appid="OnlineOrdersModule" >update emp set sal = sal +

1</jbo:ExecuteSQL>
24-71
<jbo:FileUploadForm>
Inserts an HTML FORM to upload files from the browser to the web server.
JSP Syntax
<jbo:FileUploadForm action="actionHandlerName">
form content
</jbo:FileUploadForm>
Description
The <jbo:FileUploadForm> data tag lets you create an HTML FORM to upload a media file from
the browser to the web server. Then your FORM action handler could continue loading the
media content to the database.
The generated HTML FORM has a 'ENCTYPE="multipart/form-data"' attribute. Inside the form,
you must include at least two INPUT elements:
● <INPUT TYPE="FILE" ...>

● <INPUT TYPE="SUBMIT"...>
The first INPUT element generates a file browse button to let you pick a file for upload. The
second INPUT element generates the submit button to fire the action. After you hit the submit
button, the content of the file is sent to the web server in an HTTP POST request using the
multipart/form-data encoding. The JSP page handleUpload.jsp will be invoked to handle the
HTTP request.
Attributes
● action—the name of the action handler that handles the HTTP POST request.
Example:
<jbo:FileUploadForm action="handleUpload.jsp">
Id: <INPUT TYPE="TEXT" NAME="Id"><br>
Description: <INPUT TYPE="TEXT" NAME="Desc"><br>
24-72
Photo: <INPUT TYPE="FILE" NAME="Photo"><br>
<INPUT TYPE="SUBMIT" TEXT="SUBMIT">
</jbo:FileUploadForm>
HTML Output:
<FORM ACTION="handleUpload.jsp" METHOD="POST" ENCTYPE="multipart/form-data">

Id: <INPUT TYPE="TEXT" NAME="Id"><br>
Description: <INPUT TYPE="TEXT" NAME="Desc"><br>
Photo: <INPUT TYPE="FILE" NAME="Photo"><br>
<INPUT TYPE="SUBMIT" TEXT="SUBMIT">
</FORM>
24-73
<jbo:FormEvent>
Adds a JSP event to the request object of the submitting page's HTML FORM element.
JSP Syntax
<jbo:FormEvent
event="eventName"
[ datasource="datasourceName" ] | [ viewobject="viewobjectName" ]
[ addrowkey='true'| 'false']
/>
Description
The <jbo:FormEvent> data tag lets you submit special request parameters with your JSP page to identify a JSP
event. Events you submit can be:
● User-defined events that your application handles as required.

● Predefined business component events that are handled by the various Data Components (such as the
DataScrollerComponent or DataRecordComponent).
You use the FormEvent data tag inside the HTML FORM element of your JSP page. The JSP page constructs
two request parameters from the attribute values you supply in the FormEvent data tag:
jboEvent="eventname"
jboEventVo="viewobjectname"
where the name of the view object is optional. The event you submit with the request parameters will apply to
the view object of the target JSP page and will be handled by the body of a corresponding <jbo:OnEvent> data
tag in that page. If you omit the view object name in the FormEvent attributes, then the event will apply to any
view object in the target JSP page's datasource. If you want the event to apply to a specific view object, you
can:
● Use the datasource attribute to supply the id of the datasource which contains the view object.
OR
● Use the viewobject attribute to supply the view object name.
Note: The target JSP page must contain the <jbo:OnEvent> data tag to handle the incoming event. See the
<jbo:OnEvent> data tag for details about handling events.
Inside the HTML FORM element, these two are equivalent:
<jbo:FormEvent event="Commit" event="myViewObject">
24-74
and
<input name="jboEvent" type="hidden" value="Commit" />

<input name="jboEventVo" type="hidden" value="myViewObject" />
The target JSP page will handle the two special event parameters from the request object of the submitting JSP
page. If the value of these FORM parameters matches the identifiers in the <jbo:OnEvent> data tag, then the
body of the OnEvent data tag will be executed in the target page. See the <jbo:OnEvent> data tag for details.
Attributes
● event—the event name identifier that you want to submit with the HTML FORM. Predefined JSP business
components events that the Data Components handle include:
❍ firstset, nextset, previousset, lastset to navigate to the next set of rows in a rowset.
❍ first, next, previous, last to navigate to the next row in a rowset.

❍ Update, Delete, Commit, Rollback to complete a database transaction.
● datasource—optional, the id of the datasource that contains the view object on which you want to apply
the event. You create the datasource using the DataSource data tag. You can omit this attribute if you
choose to name the view object in the viewobject attribute or you want the event to apply to any view
object in the target JSP page.
● viewobject—optional, the full name of the view object on which you want to apply the event. You must
supply the name as it appears in your Business Components project. You can omit this attribute if you
choose to name the datasource in the datasource attribute or you want the event to apply to any view
Note: You can specify an existing view object defined by the application module or a view object you created
using the CreateViewObject data tag. If the view object is contained in a nested application module, you must
specify the view object name with the application module name: appmodNested.viewobjectName.
● addrowkey—optional, set to true when you want to submit a row key to identify the current row in the
submitting page's datasource. You would use this when the body of the <jbo:OnEvent> data tag in the
target JSP page needs to perform an action on a specific row.
Example
This example generates a business components "Update" event using the datasource and the row key as
additional information.

<jbo:DataSource id="ds" appid="am" viewobject="EmpView" />

<form name="test" action="formSubmit.jsp" method="post">
Name: <jbo:InputText datasource="ds" dataitem="Ename" />
24-75
<jbo:FormEvent event="Update" datasource="ds" addrowkey="true" />
<input type="submit" value="Update">
</form>
24-76
<jbo:InputDate>
Inserts a date input form element into your page.
JSP Syntax
<jbo:InputDate
[ dataitem="attributeName" ]
formname="HTMLFormName"
[ readonly="true | false" ]
/>
Description
The user selects the date value from a calendar bean which displays on a separate JSP page.
If the business components developer has defined BC4J Control Hints for the dataitem (attribute), then the
InputDate data tag will use BC4J Control Hints formatting hints to format the output of the attribute value.
Note: When using Netscape Navigator as your browser, you must insert the tag inside the HTML <form> </form> tags
to render the data correctly.
Attributes
● datasource—the datasource id that represents the table which the user's date selection will update. You
create the datasource using the DataSource data tag.
● dataitem—the name of the specific view object attribute (in the datasource) that contains the data to
update from the date selection. Not required when inside the body of an AttributeIterate tag.
● formname—the name of the HTML form tag where the <jbo:InputDate> tag is located.
● readonly—optional, the default prevents users from altering the value of the view object attribute. If you
want to make the attribute value editable, set to true. Also, depending on the browser, the default
prevents users from editing the date displayed in the input field.
Note: This attribute sets the HTML readonly attribute for the HTML FORM INPUT element and behaves
differently in Netscape Navigator and Microsoft Internet Explorer: Netscape lets users modify the value inside
the edit window. Note that the attribute value is still readonly, meaning that the value of the view object attribute
will not be altered. If a readonly field that prevents editing a value is desired, use the <jbo:SetFieldRenderer>
data tag to map the view object attribute to the field renderer call ReadonlyField.
Example

24-77

Name: <jbo:InputText datasource="ds" dataitem="Ename" /><br>
Hire Date: <jbo:InputDate datasource="ds" dataitem="Hiredate" formname="test" />
</form>
Related topics

24-78
<jbo:InputHidden>
Inserts an input form field element that is not visible on the page.
JSP Syntax
<jbo:InputHidden
/>
Description
The hidden input element is useful when you need to pass a value that is not obtained from the
user. For example, you might want to process a particular row (obtained from the rowkey
attribute) that you obtain from a datasource you identify.
Note: When using Netscape Navigator as your browser, you must insert the tag inside the HTML
<form> </form> tags to render the data correctly.
Attributes
● datasource—the datasource id that represents the table which contains the value you
want to submit for processing. You create the datasource using the DataSource data tag.
● dataitem—the name of the specific view object attribute (in the datasource) that contains
the data to submit for processing. Not required when inside the body of an
AttributeIterate tag.
Example
<jbo:InputHidden datasource="Orders" dataitem="Id" />
24-79
<jbo:InputPassword>
Inserts a input form element into your page.
JSP Syntax
<jbo:InputPassword
[ cols="numberCharactersDisplayed | attribute length " ]
[ maxlength="numberOfCharactersToEnter | unlimited" ]
/>
Description
The password the user types is obsured with asterisks.
Attributes
● datasource—the datasource id that represents the table which the user's password
value will update. You create the datasource using the DataSource data tag.
● dataitem—the name of the specific view object attribute (in the datasource) that contains
the data to update from the password value. Not required when inside the body of an
AttributeIterate tag
● cols—optional, the character width of the password-input field. If not specified, the width
will be equal to the length of the attribute.
● maxlength—optional, the maximum number of characters the user can enter into the
password-input field. If not specified, the maximum is unlimited.
Example
User Password:<jbo:InputPassword datasource="Orders" dataitem="Id" cols="10" />
24-80
<jbo:InputRender>
Inserts an input form element that allows user to edit data of all types, including complex object types.
JSP Syntax
<jbo:InputRender
[ formname="HTMLFormName" ]
/>
Description
Input form uses a field render specific to the object type. Additionally, if the business components developer
has defined BC4J Control Hints for the dataitem (attribute), then the InputRender data tag will use BC4J
Control Hints to decide which control to render at runtime.
Note: When using Netscape Navigator as your browser, you must insert the tag inside the HTML <form> </form>
tags to render the data correctly.
Attributes
● datasource—the datasource id that represents the table which the user's value will update. You create
the datasource using the <jbo:DataSource> data tag.
● dataitem—the name of the specific view object attribute (in the datasource) that contains the data to
update from the user's value. Not required when inside the body of an AttributeIterate tag.
● formname—the name of the HTML form tag where the <jbo:InputRender> data tag is located. This is
used when the field renderer is LOV or Date.
Example
This example iterates through all the attributes fo the current record, displays the attribute name, then renders
an input field with the current value.

<jbo:ApplicationModule id="am"configname="mypackage.MypackageModule.MypackageModuleLocal"

<table>
<%-- Iterate through all the attributes of the current record --%>
<jbo:AttributeIterate id="def" datasource="ds">
24-81
<tr>
<%-- Display attribute name --%>
<td align="right"><jbo:ShowHint hintname="LABEL" /></td>
<%-- Display input field with current value --%>
<td><jbo:InputRender formname="test" /></td>
</tr>
</table>
</form>
Related topics

About Multimedia Content in BC4J JSP Pages

Rendering Multimedia Content in BC4J JSP Pages
24-82
<jbo:InputSelect>
Inserts a combobox that is either a single-selection list or multiple-selection list form element
into your page.
JSP Syntax
<jbo:InputSelect
[ multiple="true | false" ]
displaydatasource="datasourceInstanceName"
displaydataitem="attributeName"
displayvaluedataitem="attributeName"
/>
Description
The <jbo:InputSelect> data tag requires two datasources: one to display selection values from
the database and one to update values in the database. Furthermore, the attribute you use to
display the value need not be the same attribute you use to update the database. For example,
if you want to update a customer orders table from a product list table that your single-selection
list displays, the display attribute might be the product_description, while the data attribute
(used to update the customer orders table) might be the product_id.
The input renderer converts all values to a String for storage in the database.
If the business components developer has defined BC4J Control Hints for the dataitem
(attribute), then the InputSelect data tag will use BC4J Control Hints formatting hints to format
the output of the attribute value.
Attributes
● multiple—optional, determines whether or not multiple selections will be allowed from

the combobox list. Type true if you want to insert a multiple-selection list; otherwise, the
default value false specifies a single-selection list.
Note: Whether you choose a multiple-selection list or a single-selection list, the dataitem
24-83
attribute to be updated always receives a single value. In the case of a multiple-selection list,
the value is a comma-delimited list of data attribute values formed by the user's selections.
● datasource—the datasource id that represents the table which the user's selection will
update. You create the datasource using the DataSource data tag.
Note: When using this data tag, you must use an unconstrained (non-dependent) view object
as the datasource. Otherwise, the data tag will not be able to generate a complete query:
when the default query is run for a dependent view object, it is always constrained by a
master view object and if there is no master view object or datasource instantiated, it will
throw an exception. The preferred method of defining a datasource for the InputSelect data
tag is to use an unconstrained view object. To obtain an unconstrained view object usage,
you can simply select one from the Edit Application Module View Usage Wizard. Another way
to obtain an unconstrained view usage (Object) is to dynamically create one using the
CreateViewObject data tag.
● dataitem—the name of the specific view object attribute (in datasource) that contains the
data to update from the selection. Not required when inside the body of a AttributeIterate
tag.
● displaydatasource—the datasource id that represents the table which the selection list
will display. You create the datasource using the DataSource data tag.
● displaydataitem—the name of the specific view object attribute (in displaydatasource)

that contains the data to display in the selection list.
● displayvaluedataitem—the name of the specific view object attribute (in

displaydatasource) that contains the data whose selected value will be used to update
the attribute in the table identified by the dataitem and datasource. This data attribute
you specify need not be the same as the display attribute if you want to return a value
different from the one you display.
Example
Customer Name:<jbo:InputSelect multiple="true" datasource="Orders" dataitem="Id"

displaydatasource="customers" displaydataitem="Lastname" displayvaluedataitem="Id" />
Customer Name:<jbo:InputSelect datasource="Orders" dataitem="CustomerId"

displaydatasource="customers" displaydataitem="Id" displayvaluedataitem="Lastname" />
24-84
Related topics

24-85
<jbo:InputSelectGroup>
Inserts a radio button group or a checkbox group form element into your page.
JSP Syntax
[ multiple= true | false ]
displaydatasource="datasourceId"
/>
Description
Use the radio button group when you want to limit the user to a single selection. Use the
checkbox group bean when you want to permit users to make multiple selections.
The tag requires two datasources: one to display selection choices from the database and one
to update values in the database. Furthermore, the attribute you use to display the choices
need not be the same attribute you use to update the database.
For example, if you want to update a customer profile table from a survey table that your radio
button group displays, the display attribute might be the product_rating, while the data attribute
(used to update the customer profile table) might be the product__rating_id.
(attribute), then the InputSelectGroup data tag will use BC4J Control Hints formatting hints to
format the output of the attribute value.
Attributes
● multiple—optional, determines whether or not multiple selections will be allowed. Type

true if you want to insert a checkbox group; otherwise, the default value false specifies a
24-86
radio button group.
Note: Whether you insert a radio button group or a checkbox group, the dataitem attribute to
be updated always receives a single value. In the case of a checkbox group that permits
multiple selections, the value is a comma-delimited list of dataattribute values formed by the
user's selections.
throw an exception. The preferred method of defining a datasource for the InputSelectGroup
data tag is to use an unconstrained view object. To obtain an unconstrained view object
usage, you can simply select one from the Edit Application Module View Usage Wizard.
Another way to obtain an unconstrained view usage (Object) is to dynamically create one
using the CreateViewObject data tag.
data to update from the user's selection. Not required when inside the body of a
AttributeIterate tag.
● displaydatasource—the datasource id that represents the table which the radio button or
checkbox group will display. You create the datasource using the DataSource data tag.
● displaydataitem—the name of the specific view object attribute (in displaydatasource)

that contains the data to display as selection choices for the radio button or checkbox
group. The attribute name represents a column in a table.

displaydatasource) that contains the data whose selected value will be used to update
the attribute in the table identified by the dataitem and datasource. This may or may not
be the same as the displayattribute.
Example
Customer Name:<jbo:InputSelectGroup multiple="true" datasource="Orders" dataitem="Id"

displaydatasource="customers" displaydataitem="Email" displayvaluedataitem="Id" />
24-87
Customer Name:<jbo:InputSelectGroup datasource="Orders" dataitem="Id"
displaydatasource="customers" displaydataitem="Email" displayvaluedataitem="Id" />
Related topics

24-88
<jbo:InputSelectLOV>
Inserts an input form element that accepts a single value into the page.
JSP Syntax
<jbo:InputSelectLOV
displaydatasource="datasourceId"
formname="HTMLFormName"
/>
Description
The user selects the value from a LOV list which displays on a separate JSP page. The LOV
selection list page also displays a search field that lets the user limit the selection choices
displayed by the LOV list by entering a value that matches the display attributes of the LOV.
Note: Unlike the InputSelect data tag, which displays a list from a single attribute you specify, you
can specify a set of attributes to display in the LOV that the InputSelectLOV data tag creates. This
allows the LOV to display multiple columns and gives the user more information upon which to base
their selection.
The InputSelectLOV tag requires two datasources: one to display selection choices from the
database and one to update values in the database. Because the LOV selection list typically
displays data from more than one attribute, you must choose a single attribute to use for
updating the database. For example, if you want to update a customer orders table from a
product list table that your LOV selection list displays, the display attributes might include
product_id, product_description, and product_quantity, while the specific data attribute (used to
update the customer orders table) might be product_id.
(attribute), then the InputSelectLOV data tag will use BC4J Control Hints formatting hints to
24-89
Attributes
throw an exception. The preferred method of defining a datasource for the InputSelectLOV
data tag is to use an unconstrained view object. To obtain an unconstrained view object
usage, you can simply select one from the Edit Application Module View Usage Wizard.
Another way to obtain an unconstrained view usage (Object) is to dynamically create one
using the CreateViewObject data tag.
data to update from the LOV selection. The attribute name represents a column in a
table. Not required when inside the body of a AttributeIterate tag.
● displaydatasource—the datasource id that represents the table which the LOV selection
list will display. You create the datasource using the DataSource data tag.
● displaydataitem—the name of the one or more view object attributes (in

displaydatasource) that contain the data to display in the LOV selection list. Type a
single attribute name if you want to display a LOV with a single column; otherwise, type a
comma-delimited list of attribute names to display a multi-column LOV. For example,
type "AttributeName1,AttributeName2,AttributeName3" to display an LOV with three
columns defined by the three display attributes.

displaydatasource) whose selected value will be used to update the attribute in the table
identified by the dataitem and datasource. The value of the dataattribute also appears in
input field after the user makes a selection.
Tip: You should include the data attribute you specify in the displaydataitem parameter list in
order to make it visible to the user. Otherwise, the user might wonder why the value entered
in the input field for their selection does not match data displayed in the LOV selection list.
● formname—the name of the HTML form tag where the <jbo:InputSelectLOV> tag is
24-90
located.
Example
<jbo:InputSelectLOV datasource="Orders" dataitem="Contactname"

displaydatasource="customers" displaydataitem="Lastname"
displayvaluedataitem="Id" formname="form1" />
Related topics

24-91
<jbo:InputText>
Inserts a text-input field form element into your page.
JSP Syntax
<jbo:InputText
[ cols="numberCharactersDisplayed | attribute length" ]
[ maxlength="numberOfCharactersToEnter | unlimited" ]
/>
Description
The input render converts all values to a String for storage in the database.
(attribute), then the InputText data tag will use BC4J Control Hints formatting hints to
Attributes
● datasource—the datasource id that you want to use to update the database. You create
the datasource using the DataSource data tag.
● dataitem—the name of the specific view object attribute (in the datasource) that you want
to update from your page. Not required when inside the body of an AttributeIterate tag.
● cols—optional, the character width of the text-input field. If not specified, the width will be
equal to the length of the attribute.
● maxlength—optional, the maximum number of characters the user can enter into the
input field. If not specified, the maximum is unlimited.
24-92
● readonly—optional, the default prevents users from altering the value of the view object
attribute. If you want to make the attribute value editable, set to true. Also, depending on
the browser, the default prevents users from editing text displayed in the text-input field.
Note: This attribute sets the HTML readonly attribute for the HTML FORM INPUT element
and behaves differently in Netscape Navigator and Microsoft Internet Explorer: Netscape lets
users modify the value inside the edit window. Note that the attribute value is still readonly,
meaning that the value of the view object attribute will not be altered. If a readonly field that
prevents editing a value is desired, use the <jbo:SetFieldRenderer> data tag to map the view
object attribute to the field renderer call ReadonlyField.
Example
Order Id:<jbo:InputText datasource="Orders" dataitem="Id" />
Related topics

24-93
<jbo:InputTextArea>
Inserts a multi-line text-input form element into your page.
JSP Syntax
<jbo:InputTextArea
[ dataitem="attributename" ]
[ rows="numberLinesDisplayed | 10" ]
[ cols="numberCharactersDisplayed | attribute length" ]
/>
Description
The input render converts all values to a String for storage in the database.
(attribute), then the InputTextArea data tag will use BC4J Control Hints formatting hints to
Attributes
● datasource—the datasource id that you want to use to update the database. You create
to update from your page. Not required when inside the body of an AttributeIterate tag.
● rows—optional, the number of rows you want to display. If not specified, the
InputTextArea will display 10 rows by default.
● cols—optional, the character width of the text-input field. If not specified, the width will be
equal to the length of the attribute.
24-94
● readonly—optional, the default prevents users from altering the value of the view object
attribute. If you want to make the attribute value editable, set to true. Also, depending on
the browser, the default prevents users from editing text displayed in the text-input field.
Note: This attribute sets the HTML readonly attribute for the HTML FORM INPUT element
and behaves differently in Netscape Navigator and Microsoft Internet Explorer: Netscape lets
users modify the value inside the edit window. Note that the attribute value is still readonly,
meaning that the value of the view object attribute will not be altered. If a readonly field that
prevents editing a value is desired, use the <jbo:SetFieldRenderer> data tag to map the view
object attribute to the field renderer call ReadonlyField.
Example
Order Information:<jbo:InputTextArea datasource="Orders" dataitem="Desc" />
Order Information:<jbo:InputTextArea datasource="Orders" dataitem="Desc"

cols="20" rows="5" />
Related topics

24-95
<jbo:MediaUrl>
Supplies a URL string that retrieves the multimedia content stored as an interMedia object in the Oracle database.
JSP Syntax
<jbo:MediaUrl
id="uniqueIdName"
[[ rowkey="RowKeyString" ] | [ whereclause="WhereClause" ]]
[ retrievepath="CustomRetrievePath" ]
>
body content
</jbo:MediaUrl>
Description
The <jbo:MediaUrl> data tag helps you to write highly custom HTML tags to render multimedia content stored in interMedia. The
<jbo:MediaUrl> data tag's "id" attribute introduces a scripting variable that is an OrdURLBuilder object and in scope of the body
of the <jbo:MediaUrl> data tag. The scripting variable builds the media fetching URL for custom HTML tags. A sample usage is
to use the scripting variable to build a URL for the HTML <IMG> tag's "SRC" attribute. The scripting variable also provides some
utility methods, such as getHeight() and getWidth(), to help populate other custom HTML tag attributes.
By default, the [retrievepath] is a pre-supplied JSP page, ordPlayMedia.jsp. You can write your own media delivery component
and provide a custom retrieve path when such requirement arises.
Attributes
● id—the name of the instance of the URL builder created by the <jbo:MediaUrl> tag. The name you assign must be unique
within a page. This can be any legal Java identifier. Within a scriptlet, you may use the id as a scriptable variable of type
OrdURLBuilder.
24-96
ordPlayMedia.jsp.
Example 1:
<jbo:MediaUrl id="urlBuilder" datasource="ds" mediaattr="Photo" whereclause="id = 15" >

<IMG SRC="<%= urlBuilder.getOrdDomainURL() %>" ALT="vacation photo.">
</jbo:MediaUrl>
HTML Output
<IMG SRC="[mediaFetchingURL]" ALT="vacation photo.">
Example 2:
<jbo:RowsetIterate datasource="ds">
<jbo:MediaUrl id="builder" datasource="ds" mediaattr="Image" >
<IMG SRC="<%= builder.getOrdDomainURL() %>"
<% if(builder.getWidth()>0 && builder.getHeight()>0) { %>
HEIGHT="<%= builder.getHeight() %>"
WIDTH="<%= builder.getWidth() %>"
<% } %>
ALT="my cat">
</jbo:MediaUrl>
HTML Output
<IMG SRC="[mediaFetchingURL]" HEIGHT="[nn]" WIDTH="[nn]" ALT="my cat">

24-97
<jbo:OnEvent>
Handles a JSP event submitted by the <jbo:UrlEvent> or <jbo:FormEvent> data tags.
JSP Syntax
<jbo:OnEvent
[ name="[eventName | * ]" ] | [ list="listofEventName" ]
[ datasource="datasourceName" ] | [ viewobject="viewobjectName" ]>
[JSP_tags]
</jbo:OnEvent>
Description
The <jbo:OnEvent> data tag lets you handle events identified by the jboEvent URL parameters
of the submitting JSP page. The OnEvent data tag functions like a conditional statement
because your JSP page executes the body of the tag only if the OnEvent tag condition is true.
To test the OnEvent condition, your JSP page will compare the values of the OnEvent
attributes against the values of the request parameters generated by a <jbo:UrlEvent> data tag
or a <jbo:FormEvent> data tag.
When the OnEvent condition is true, the matching datasource and event name provide a
context for the action attribute of any BC4J data tags you list in the body of the OnEvent data
tag. For example, you can submit any of these predefined business component events to
trigger an action in the body of the OnEvent data tag using the recognized event:
● firstset, nextset, previousset, lastset to navigate to the next set of rows in a rowset.
● first, next, previous, last to navigate to the next row in a rowset.
● Update, Delete, Insert to perform an action on a row.
You generate event request parameters using these data tags:
● Executing the <jbo:FormEvent> tag in the submitting pages. See the <jbo:FormEvent>
data tag for details.
● Executing the <jbo:UrlEvent> tag in the submitting pages. See the <jbo:UrlEvent> data
tag for details.
Attributes
24-98
● name—optional, an event name identifier that you want to compare to FORM request
parameters or URL parameters. You can force the body of the OnEvent data tag to
execute for any event parameter by entering an asterisk "*" as the value of the name
attribute. If you prefer to match a list of identifiers, omit this attribute and use the list
attribute instead.
● list—optional, a list of event name identifiers that you want to compare to FORM request
parameters or URL parameters. If you prefer to match a single identifier, omit this
attribute and use the name attribute instead.
Note: If you do not specify any event identifier in either the name attribute or the list attribute,
the body of the OnEvent data tag will be executed for any JSP event submitted. This has the
same effect as entering an asterisk (*) as the value of the name attribute.
● datasource—optional, the id of the datasource that contains the view object on which
you want to apply the event. You create the datasource using the DataSource data tag.
You can omit this attribute if you choose to name the view object in the viewobject
attribute or you want the body of the OnEvent data tag to execute for any view object.
● viewobject—optional, the full name of the view object on which you want to apply the
event. You must supply the name as it appears in your Business Components project.
You can omit this attribute if you choose to name the datasource in the datasource
attribute or you want the body of the OnEvent data tag to execute for any view object.
Note: You can specify an existing view object defined by the application module or a view
object you created using the CreateViewObject data tag. If the view object is contained in a
nested application module, you must specify the view object name with the application
module name: appmodNested.viewobjectName.
Examples
These examples submit the jboEvent URL parameter with an anchored link:
<a href="<targetJSP.jsp>?jboEvent=Create">New</a>
As an alternative, you can use the eventName on a specific view object:
<% String voName = dsNav.getViewObjectName(); %>

<a href="<targetJSP.jsp>?jboEvent=<%voName>%.Last">Last</a>
In the first example, the value of the jboEvent parameter is formed without the view object
name, in that case, the event will apply to any view object in the JSP page's datasource. In the
24-99
second example, the event is targeted to a specific view object in the JSP page's datasource
24-100
<jbo:PostChanges>
Posts changes on all datasource instances defined by the application module to the database.
JSP Syntax
<jbo:PostChanges
/>
Description
You use the PostChanges tag to synchronize changes to the datasource cache with the
database. Issuing the post after modifying a datasource cache:
● Executes any DML-defined database triggers, which may be necessary to accept the
data in the database
● Ensures that your datasource has acquired any database locks, which would otherwise
prevent the changes from being entered into the database
● Causes the datasource to pickup default values
For example, you need to post changes after you set an attribute value or delete a row. The
post, coupled with the changes on the datasource, first initiates DML-defined database triggers
on the database. After the DML operations are completed and the datasource has acquired the
locks, you can then either roll back the change or commit it to the database.
Attributes
Example
<jbo:PostChanges appid="OnlineOrdersModule" />
24-101
<jbo:RefreshDataSource>
Refreshes the datasource data.
JSP Syntax
<jbo:RefreshDataSource
/>
Description
It is necessary to refresh a datasource when you want to be able to display data from the
database after:
● A post operation
● A commit operation
The refresh causes the datasource to reexecute its query to obtain that data.
See also: oracle.jbo.Session
Attributes
● datasource—the datasource id that you want to refresh from the database. You create
Example

<jbo:DataSource id="ds1" appid="OnlineOrdersModule" viewobject="CustomerView"

whereclause="id > 206" rangesize="20" ></jbo:DataSource>
<jbo:RefreshDataSource datasource="ds1" />
24-102
<jbo:ShowValue datasource="ds1" dataitem="Id" ></jbo:ShowValue>
<jbo:ShowValue datasource="ds1" dataitem="Firstname" ></jbo:ShowValue>
<jbo:ShowValue datasource="ds1" dataitem="Lastname" ></jbo:ShowValue>
</BODY>
</HTML>
24-103
<jbo:ReleasePageResources>
Provides a marker for the JSP page that triggers the release of the application module
instance. This tag must appear at the end of a BC4J databound JSP page.
JSP Syntax
<jbo:ReleasePageResources
[ releasemode="Stateful | Stateless | Reserved" ]
/>
Note: The appid and releasemode attributes are provided for backwards compatibility. Use the
releasemode attribute of the <jbo:ApplicationModule> data tag to set the application module release
mode on your JSP page instead.
Description
The <jbo:ReleasePageResources> tag provides a marker for the JSP page that triggers the
release of the application module instance. The release mode for the application module is
determined:
● At the level of the JSP page in the ApplicationModule tag

● At the application level, in the application module definition of the Business Component
configuration file (bc4j.xcfg).
You release the application module after your JSP page has executed all BC4J data tags. For
this reason, the ReleasePageResources tag must be the last databound BC4J data tag in your
page. Do not remove the ReleasePageResources tag or place any BC4J data tags after the
ReleasePageResources tag.
Attributes
● releasemode—provided for backward compatibility. See <jbo:ApplicationModule> to set

the application module release mode on your JSP page instead.
● appid—provided for backward compatibility. See <jbo:ApplicationModule> instead.
Example
24-104
Related topics

24-105
<jbo:RenderValue>
Displays data in an appropriate format for HTML. Like special data types, such as images,
audio, or video, using a field render specific to the data object type.
JSP Syntax
<jbo:RenderValue
/>
Description
Because the <jbo:RenderValue> data tag relies on a field render to display information, it
differs from the <jbo:ShowValue> data tag, which merely echos or represents the value as
String, Date or Numeric data type. Unlike the ShowValue data tag, RenderValue will parse the
output for special characters, such as '>', '<' or '&', and will formatted them to be visible by
replacing them with their HTML equivalents: > <, and &.
The RenderValue data tag is primarily of use when you need to display rendered data of a
complex object type into your page such as a video or image file. In that case, the renderer for
the object may display a URL for the file. The RenderValue data tag generates the necessary
HTML for the object the dataitem represents.
Additionally, if the business components developer has defined BC4J Control Hints for the
dataitem (attribute), then the RenderValue data tag will use BC4J Control Hints to decide which
control to render at runtime.
When displaying data using the RenderValue tag, you should preview your page to ensure the
form is formatted properly.
Attributes
Enter the values for the corresponding properties of the RenderValue data tag into the Value
column. You cannot proceed to the next page until you have entered all values.
● datasource—the datasource id that you want to use to display data in your page. You
create the datasource using the Datasource data tag.
● dataitem—the name of the specific view object attribute that contains the data to display
24-106
in your page. Not required when inside the body of a AttributeIterate tag.
Example
<jbo:RenderValue datasource="dvo" dataitem="Image" />
Related topics


24-107
<jbo:Rollback>
Rolls back changes to the datasource so they are not entered into the database.
JSP Syntax
<jbo:Rollback
/>
Description
You can use the Rollback data tag after you post changes to the database, but before you have
commited them. For example, after you post a new attribute value you can roll back the change
on the datasource cache before accepting new input from the user.
The Rollback tag performs the same action whether you operate on the datasource cache or
directly on the database. Therefore, you can issue a roll back:
● When you modify the data of the rows of the datasource cache
● When you modify the database through a ExecuteSQL data tag
Attributes
Example
<jbo:RollBack appid="OnlineOrdersModule" />
24-108
<jbo:Row>
Retrieve a row instance and perform an operation on the row.
JSP Syntax
<jbo:Row
id="rowInstanceName"
[ action="Active | Create | Current | Delete | Find | Get | Lock | Update" ]
[ rowkeyparam="HTTP parameter name"] | [ rowkey="rowPointer" ] >
</>
Description
The <jbo:Row> data tag lets you perform row retrieval and row action operations on a row instance.
Row retrieval operations include:
● Active retrieves the row currently being iterated through a <jbo:RowsetIterator> data tag
● Find retrieves a row from a URL parameter on the request object, will change row currency
● Get retrieves a row from a URL parameter on the request object, but will not change row currency
Before you can perform a row operation you must locate a specific row. You can use the Row tag to locate a
row on the datasource under these scenarios:
● When you want to work with a row between two JSP pages, you can use the Find or Get actions
● When you want to work with a row on the same JSP page, you can use the Active or Current actions
Row operations the Row tag lets you perform include:
● Current sets the row pointer to the current row in the specified datasource
● Create inserts a new row in the specified datasource and positions the row pointer on the new row
● Delete deletes the current row in the specified datasource
● Lock ensures that the row data you view or change in the specified datasource is not changed by other
users until you are finished with the data
● Update changes the value of an attribute you set (using the URL parameter from a form) in the specified
datasource
See also: oracle.jbo.Row
Attributes
24-109
● id—the name of the instance of the Row tag. The name you assign must be unique within a page. This
can be any legal Java identifier. Within a scriptlet, you may use the id as a scriptable variable of type
oracle.jbo.Row.
● datasource—the datasource id whose rows you want to perform an action on. You create the
datasource using the <jbo:DataSource> data tag.
● action—the row operation to perform. Type the value: Active, Create, Current, Find, Get, Update,
Delete, Lock depending on the action you want to perform on the datasource.
Active retrieves the row that is currently being iterated within the body of a <jbo:RowsetIterator> data
tag. This action will not change the row currency.
Create inserts a new row in the specified datasource and positions the row pointer on the new row.
Current sets the row pointer to the current row in the specified datasource.
Delete deletes the current row in the specified datasource.
Find retrieves a row from a URL parameter on the request object. Unlike Get, this action will change row
currency after retrieving the row.
Get retrieves a row from a URL parameter on the request object. Unlike Find, this action will not change
row currency after retrieving the row.
Lock ensures that the row data you view or change in the specified datasource is not changed by other
Update changes the value of an attribute you set (using the URL parameter from a form) in the specified
datasource.
Tip: You can also set the action parameter at runtime by using an expression such as <%=rowop%>. You
would pass the action value to the Row tag from another portion of your page.
● rowkeyparam—optional, the name of an HTTP parameter that specifies the location of the row instance
in the datasource. If you do not specify a row instance using the rowkey parameter by passing a HTTP
request parameter, the Row tag uses the current-row pointer on the datasource.
Tip: You can obtain the name of the current row for the data item by using the ShowValue tag with the
dataitem set to the special attribute value RowKey. <jbo:ShowValue datasource='ds1'
dataitem='RowKey'></jbo:ShowValue>.
● rowkey—optional, a string representing a RowKey to access a row. You would need to use
request.getParam("RowKey") to get the string value. The rowkeyparam attribute provides a more direct
approach to obtaining the RowKey.
24-110
Example
This example shows how to use the Row tag to display a detail rowset for a master row that the user selects in
a separate JSP page. In this case, the row-selection page generates HREF anchors that the user clicks to
invoke the detail page.
In the following code, the HREF in the master table passes in a RowKeyValue HTTP parameter (the name of
this parameter is application-specific), which you obtain by setting the dataitem on the ShowValue tag to the
special attribute value "RowKey":
<jbo:ApplicationModule id="MyPackageModule"
configname="myPackage.MyPackageModule.MyPackageModuleLocal"
<jbo:DataSource id="dsMaster" appid="MyPackageModule" viewobject="DeptView">

</jbo:DataSource>
<table border="1">
<jbo:RowsetIterate datasource="dsMaster" >
<TR>
<TD><a href="detail.jsp?RowKeyValue=<jbo:ShowValue datasource='dsMaster'
dataitem='RowKey'/>">See this
record</a>
</TD>
<TD>Department Name:</TD>
<TD><jbo:ShowValue datasource="dsMaster" dataitem="Dname">
</jbo:ShowValue>
</TD>
</TR>
</table>
In the receiving page, the Row tag Find action will locate the row the user clicked based on the name of an
HTTP parameter that contains the row key value you pass. The Find action sets the row currency of the master
datasource and allows you to display the detail rowset.
Note: If you use the application module in Stateful release mode (default), then you need to refresh the datasource
prior to seeking the row using the row key. You can refresh the datasource by using:
Here is the syntax of the receiving page, which displays the detail view for the row that had been passed using
the previously defined RowKeyValue HTTP parameter (be sure the name of this parameter matches on your
submit and receive JSP pages):
<jbo:ApplicationModule id="MyPackageModule"
configname="myPackage.MyPackageModule.MyPackageModuleLocal"
<jbo:DataSource id="dsMaster" appid="MyPackageModule" viewobject="DeptView" >

24-111
</jbo:DataSource>

</jbo:Row>
<jbo:DataSource id="dsDetail" appid="Package17Module" viewobject="EmpView" >

</jbo:DataSource>
<h2>Employees for Department: <jbo:ShowValue datasource="dsMaster" dataitem="Dname"

</jbo:ShowValue>
</h2>
<table border="1">
<jbo:RowsetIterate datasource="dsDetail" >
<TR>
<TD>Employee Name</a>
</TD>
<TD><jbo:ShowValue datasource="dsDetail" dataitem="Ename">
</jbo:ShowValue>
</TD>
</TR>
</table>
The important part of the receiving page is in the Row tag:

</jbo:Row>
The following example shows that you can also use the Row tag to perform other tasks, such as inserting a
new record in the datasource.

releasemode="Stateless"
/>
<jbo:DataSource id="ds1" appid="OnlineOrdersModule" viewobject="CustomerView" >

</jbo:DataSource>

<jbo:SetAttribute dataitem="Lastname" value="wong" />
<jbo:SetAttribute dataitem="Firstname" value="howard"/>
<jbo:SetAttribute dataitem="Address.City" value="Redwood City" />
</jbo:Row>
</BODY>
</HTML>
24-112
24-113
<jbo:RowsetIterate>
Iterates over the rows of the specified datasource.
JSP Syntax
<jbo:RowsetIterate
[ changecurrentrow="true | false" ]
[ userange="true | false" ]
>
[JSP tags in RowsetIterate body]
Description
The RowsetIterate tag iterates over the rows of the specified datasource's rowset. The rows
being iterated over are limited by the range specified on the datasource instance. The iterator
processes from the first row in the datasource rowset range to the last row in the range.
The body of the RowsetIterate tag lets you perform some action on the iterated row before
proceeding to the next row. For example, you can use the RowsetIterate tag to display rowset
data in master-detail pages. You create one iterator instance for each datasource you want to
display and use the ShowValue tag in order to extract the data from the iterated row.
Note: Tags that you place inside the body of a RowsetIterate tag can obtain their datasource
instance from the RowsetIterate's specified datasource. This allows you to write tags with fewer
attributes inside the body of the RowsetIterate tag.
The attribute changecurrentrow lets you control whether row currency changes while iterating
over the datasource rowset. When the currency of the row in your datasource changes, a side
effect of this action may result in additional queries. When the changecurrentrow attribute is
enabled, the row iterator determines whether a master-detail view link exists for the current
row, and when a link exists, a query is executed to retrieve detail rows. To avoid executing
additional queries, you should disable the changecurrentrow attribute when your JSP page
does not require the row currency to change inorder to display rowset data in master-detail
tables.
Iterators you set up with the RowsetIterate tag do not take conditions; you should set up the
business component datasource to define conditions to limit the rowset results.
24-114
See also: oracle.jbo.RowIterator
Attributes
● datasource—the datasource id that contains the rowset you want to iterate over. You
create the datasource using the DataSource data tag.
● changecurrentrow—determines whether the row currency changes as the iterator

changes position within the datasource rowset. The default is true to ensure backwards
compatibility with previous versions. However, in most cases, you will prefer to set this
attribute to false to avoid changing row currency on multiple rowsets.
● userange—determines whether the iterator uses the range specified on the datasource
rowset to determine the boundary of the rowset iterator. The default is true for backward
compatibility. If you do not want to traverse the entire rowset, set to false.
Example
This example iterates over a datasource rowset to create a table that displays links on the
Name attribute of each row.
<jbo:RowsetIterate datasource="category_vo">
<TR>
<TD colspan=3>
<a href="srch_results.jsp?cid=<jbo:ShowValue dataitem="Id" />" target="contentsframe">
<jbo:ShowValue dataitem="Name"/></a>
</TD>
</TR>
24-115
<jbo:RowsetNavigate>
Moves the currency or the viewing range of a datasource.
JSP Syntax
<jbo:RowsetNavigate
[ action="First | Next | Previous | Last | FirstSet | NextSet| PreviousSet | LastSet" ]
/>
Description
You can use the RowsetNavigate tag to change the row currency (using the rowkey attribute)
on the datasource and process it as desired.
In releases prior to Oracle9i JDeveloper, an exception was thrown for Business Component
JSP data tag applications that used the <jbo:RowsetNavigate> data tag when the user
attempted to scroll past the last record or before the first record in the rowset. Starting in
Oracle9i JDeveloper, the exception is no longer thrown for the rowset.
If you want your application to continue to notify users:
"Beginning of rowset has been reached." when the user clicks Previous on the first row.
"End of rowset has been reached." when the user clicks Next on the last row.
Then, your application needs to use these methods on the datasource object:
ds.getRowSet().hasNext() for the end of the rowset

dsNav.getRowSet().hasPrevious() for the beginning of the rowset
The above methods are preferred over comparing the number of the row in the rowset.
See also: oracle.jbo.RowIterator
Attributes
● datasource—the datasource id whose rows you want to step through. You create the
datasource using the DataSource data tag.
● action—the navigate operation to perform. Optional when placed in the body of an
24-116
OnEvent tag. Type the value: First, Next, Previous, Last depending where you want to
position the row pointer for the datasource.
First moves the row pointer to the first record in the rowset.
Next moves the row pointer to the next record in the rowset.
Previous moves the row pointer to the previous record in the rowset.
Last moves the row pointer to the last record in the rowset.
FirstSet moves the range at the beginning of the rowset.
NextSet moves the range to the next set of rows.
PreviousSet moves the range to the previous set of rows.
LastSet moves the range at the end of the rowset.
Tip: You can also set the action parameter at runtime by using an expression such as
<%=navop%>. You would pass the action value to the RowsetNavigate tag from another
portion of your page.
Example

<jbo:DataSource id="Orders" appid="OnlineOrdersModule" viewobject="OrdView" >

</jbo:DataSource>
<jbo:DataSource id="customers" appid="OnlineOrdersModule" viewobject="CustomerView" >

</jbo:DataSource>
<jbo:RowsetNavigate datasource="Orders" action="First" />
<form name="form1"> Order Id:<jbo:InputText datasource="Orders" dataitem="Id" />

Order Date:<jbo:InputDate datasource="Orders" dataitem="Orderdate" formname="form1" />
24-117
</form>
<jbo:RowsetNavigate datasource="Orders" action="Next" />

</form>
<jbo:RowsetNavigate datasource="Orders" action="Previous" />

</form>
<jbo:RowsetNavigate datasource="Orders" action="Last" />

</form>
</BODY>
</HTML>
24-118
<jbo:SetAttribute>
Updates a particular attribute in the row specified by a row instance.
JSP Syntax
<jbo:SetAttribute
dataitem="attributeName | *"
[ value="attributeValue" ]
[ usemultipartformat="Yes | No" ]
/>
Description
The value you use to update the attribute can be:
● Static, passed as a value

● Dynamic, passed from an HTTP parameter
You create a row instance with the Row data tag. The SetAttribute tag must appear inside a
row instance definition that performs an update action.
If you want to process data from a form input, using HTTP request parameters, you specify the
wildcard character (*) on the SetAttribute tag's dataitem property. When you provide the
wildcard, the SetAttribute tag will look for HTTP request parameters that match the attribute
name of the view object defined by your row instance's datasource. If it finds a match, the
SetAttribute tag will update the view object's attribute with the HTTP request parameter value.
If you want to process Intermedia datatypes in your HTTP request parameter, you will be
passing an HttpRequest object with a mime type encoded in the mulitpart/form-data format. In
this case, the SetAttribute tag requires that you set the usemultipartformat property to Yes.
Object type fields are accessed using a dot notation for the dataitem like: address.street.
Attributes
24-119
● datasource—the datasource id that contains the attribute to update. You create the
datasource using the DataSource data tag.
● dataitem—the name of the specific view object attribute (in the datasource identified by
the row instance) that contains the data to update from the value or an asterisk (*) when
you want to obtain the value from an HTTP parameter.
Note: If you use an HTTP parameter to obtain the value, you must use the asterisk (*) on the
dataitem in order to match against all attribute names. This is necessary since the value
obtained from an HTTP parameter will not be known until runtime.
● value—the data value of the attribute you want to set or blank when dataitem uses the
asterisk (*) character. If you use an HTTP parameter, using the asterisk (*) character,
you do not specify the value property.
● usemultipartformat—the default value is No. Set to Yes when you obtain the value from
an HTTP parameter and the HttpRequest object's mime type is encoded in the
"multipart/form-data" format. For example, set to Yes when you want to process
Intermedia datatypes, such as audio or video images.
Example
The following SetAttribute examples update a row attribute using both static and dynamic
values.
<jbo:Row id="row1" datasource="ds1" action="Current" >

<jbo:SetAttribute dataitem="Contactname" value="<%= first_name %>" />
<jbo:SetAttribute dataitem="Status" value="P" />
<jbo:SetAttribute dataitem="CustomerId" value="<%= cust_id %>" />
</jbo:Row>
The following SetAttribute example uses a wildcard (*) on the dataitem attribute. You must use
the wildcard when you define a form that takes HTTP request parameters to set the row
attribute value. The SetAttribute tag with a wildcard on the dataitem will update the row attribute
on the attribute whose name matches the HTTP request parameter name.
<jbo:Row id="row1" datasource="ds1" action="Current" >

<jbo:SetAttribute dataitem="*" usemultipartformat="Yes" />
</jbo:Row>
Here's another example.
24-120
<jbo:DataSource id="ds1" appid="OnlineOrdersModule" viewobject="CustomerView" >

</jbo:DataSource>

<jbo:SetAttribute dataitem="Lastname" value="tiger" />
<jbo:SetAttribute dataitem="Firstname" value="tiger" />
<jbo:SetAttribute dataitem="Address.City" value="Redwood city" />
</jbo:Row>
</BODY>
</HTML>
Related topics

24-121
<jbo:SetDomainRenderer>
Overwrites the default field renderer defined for attributes of the same domain.
JSP Syntax
<jbo:SetDomainRenderer
domain="class name of the domain"
classname="class name of the field renderer"
fieldtype="Display | Edit"
scope="Page | Request | Session | Application"
/>
Example
The example uses a TextArea field instead of a the default text field to render all fields of type String.

<%-- Use a TextArea field instead of a the default text field for all fields
of type String --%>
<jbo:SetDomainRenderer classname="oracle.jdeveloper.html.TextArea"
domain="java.lang.String" fieldtype="Edit" scope="session" />
<%-- Ename and Job are String, they use TextArea

Salary is a Number, it use the default Input Text--%>
Name: <jbo:InputRender datasource="ds" dataitem="Ename" formname="test" /><br>
Job: <jbo:InputRender datasource="ds" dataitem="Job" formname="test" /><br>
Salary: <jbo:InputRender datasource="ds" dataitem="Sal" formname="test" /><br>
</form>
Description
Use the SetDomainRenderer tag to overwrite the existing renderer for all attributes of the specified domain type.
The JSP pages of the web application rely on the domain renderer to determine how attributes of that domain
should be edited or displayed. You can control the scope of the domain renderer in your web application using
the scope attribute of the SetDomainRenderer tag. If you want to specify a renderer for specific attributes, see
the SetFieldRenderer tag for details.
Attributes
● domain—the fully qualified name of the class that defines the domain upon which you want to set the
renderer.
24-122
● classname—the fully qualified name of the class used to render attributes of the specified domain. You
will specify one class for the EditRenderer and another class for the DisplayRenderer.
● fieldtype—specifies whether the web application that displays the attribute should use the specified
domain renderer to control editing or displaying of the attribute.
● scope—specifies the duration for which the domain renderer will be used by the web application to render
attributes of the specified domain. The scope can be one of these values:
Page
The domain renderer will be limited to the duration of the active JSP page.
Request
The domain renderer will be limited to the duration of the request object.
Session
The domain renderer will be limited to the duration of the session object.
Application
The domain renderer will be in effect for the entire duration of the web application.
24-123
<jbo:SetFieldRenderer>
Overwrites the default field renderer defined for a dataitem.
JSP Syntax
<jbo:SetFieldRenderer
[ datasource="datasourceId" ]
fieldtype="Display | Edit"
classname="class name of the field renderer"
/>
Description
Use the SetFieldRenderer tag to overwrite the existing renderer of the specified attribute. The JSP page relies
on the field renderer to determine how the attribute should be edited or displayed. Once the JSP page is
executed, the field renderer for the attribute returns to the default renderer. The scope of the SetFieldRenderer
tag is limited to the JSP page; if you want to specify a renderer with a wider scope, see the SetDomainRenderer
tag for details.
Attributes
● datasource—the datasource id, as defined in the <jbo:dataSource> data tag. Not required when inside an
AttributeIterate tag body.
● dataitem—the name of the specific view object attribute (in the datasource) upon which you want to set
the field renderer.
● fieldtype—specifies whether the JSP page that displays the attribute should use the specified field
renderer to control editing or displaying of the attribute.
● classname—the fully qualified name of the class used to render the field. You will specify one class for
the EditRenderer and another class for the DisplayRenderer.
Example
This example uses a password field instead of a the default text field to render the EName data item.

<%-- Use a password field instead of a the default text field for "EName"
dataitem --%>
<jbo:SetFieldRenderer datasource="ds" classname="oracle.jdeveloper.html.PasswordField"
dataitem="EName" fieldtype="Edit" />
24-124
Name: <jbo:InputRender datasource="ds" dataitem="EName" />
</form>
24-125
<jbo:SetHtmlAttribute>
Adds a non-databound HTML attribute to a BC4J Input data tag.
JSP Syntax
<jbo:SetHtmlAttribute
name="attributeName"
[ value="attributeValue" ]
/>
Description
The <jbo:SetHtmlAttribute> data tag lets you add static HTML attributes to BC4J Input data tags. To render the
attribute you must use the <jbo:SetHtmlAttribute> data tag inside the body of one of the BC4J Input data tags
(for example, <jbo:InputRender> or <jbo:InputText>). The name-value pair you define will be rendered along
with the databound attributes of the BC4J Input tag.
Attributes
● name—the name of the attribute.

● value—the value of the attribute you want to set. This attribute should be omitted if the attribute is
readonly. The value may be supplied with JavaScript.
Example
This example specify the SIZE and the CSS CLASS attribute for the generated HTML INPUT tag.


Name:
<jbo:InputText datasource="ds" dataitem="Ename" >
<%-- Specify the SIZE and the CSS CLASS attribute for the generated HTML
INPUT tag --%>
<jbo:SetHtmlAttribute name="SIZE" value="10" />
<jbo:SetHtmlAttribute name="CLASS" value="myClass" />
</jbo:InputText>
</form>
24-126
<jbo:ShowCriteria>
Display the criteria of a dataitem in a view criteria row.
JSP Syntax
<jbo:ShowCriteria
/>
Description
The ShowCriteria tag displays search criteria values from its contextual datasource and
attribute. You provide a context for the ShowCriteria tag in your JSP page, using one of two
methods:
● Iterate over all view criteria rows of a view criteria to display all criteria
● Display specific criteria on a specified view criteria row
If you use the ViewCriteriaIterate tag to iterate over the criteria rows, you must:
● Insert a single ShowCriteria tag within the body of the AttributeIterate tag with the
queryable attribute set to true
● Omit the dataitem attribute of the ShowCriteria tag
● Insert the AttributeIterate tag inside the body of a ViewCriteriaIterate tag
The attribute iterator will step through each attribute of the current view row, while the view
criteria iterator steps through the view criteria rows contained by the specified datasource. In
this way, these tags define a context for the ShowCriteria tag that lets you display the value of
each criteria of each view criteria row. The context they provide defines the datasource and
dataitem; therefore, the dataitem attribute of the ShowCriteria tag must be omitted.
If you do not want to display all criteria in the criteria row, insert the ShowCriteria tag inside the
body of a CriteriaRow tag. In this case, you must explicitly define the context for a specific
criteria by specifying the ShowCriteria dataitem attribute.
Attributes
24-127
● dataitem—the name of the specific view criteria attribute that contains the data to search.
The name must match a corresponding dataitem name in the datasource. This attribute
is only optional if you use ShowCriteria tag in the body of a AttributeIterate tag to iterate
over all criteria rows.
Examples
The example below displays a criteria for the specified attribute.
<jbo:ShowCriteria datasource="CustomerName" />
24-128
<jbo:ShowDefinition>
Displays the metadata of the specified attribute.
JSP Syntax
<jbo:ShowDefinition
[ datasource="datasourceInstanceName" ]
definition="Name | ColumnName | ColumnNameForQuery | JavaType | SQLType | Scale |
Precision | Queriable | PrimaryKey | Mandatory | Updateable | Kind | DisplayRenderer |
EditRenderer"
/>
Description
Use the <jbo:ShowDefinition> data tag to display attribute metadata in your JSP page. Attribute
definitions are properties of a view object or entity object attribute that the business component
developer can define. This type of metadata is closely related to the way the attribute in the
business component interacts with the database. For example, if you display the Name
definition for an attribute, you will show the attribute name used internally by the business
components.
Alternatively, you can use the <jbo:ShowHints> data tag to display how the client application
should display the attribute: it would not display the internal attribute name used by the
business components, rather a Control Hint name defined by the business component
developer to represent the attribute in the JSP page.
See also: oracle.jbo.AttributeDef
Attributes
● datasource—the datasource id, as defined in the <jbo:dataSource> data tag. This

attribute is only optional when ShowDefinition appears inside the body of a Row,
RowsetIterate, or AttributeIterate data tag.
to retrieve in your page. This attribute is only optional when ShowDefinition appears
inside the body of a Row, RowsetIterate, or AttributeIterate data tag.
● definition—the name of the attribute definition property to display. Among the attribute
definition properties that you can display include:
24-129
Name
Returns the name of the database column the attribute represents.
ColumnName
Returns the name of the column to be used in a view object query statement. This
may be different from the actual database column name.
ColumnNameForQuery
Returns the index of the attribute row's definition object. This is the value you must
use when you create a view object query statement, WHERE clause, or
ORDERBY clause. You must not use the view object column name or the
database column name.
JavaType
Returns the Java class of the object stored for this attribute definition.
SQLType
Returns the JDBC type of the attribute.
Scale
Returns the scale value of the attribute when applicable. The attribute must be
numeric.
Precision
Returns the precision of a numeric or string attribute.
Queryable
Determines whether the the attribute is queriable. Queriable attributes are those
that are allowed to have a filter condition for the WHERE clause. Returns false if
the attribute is not to be used in constructing the WHERE clause of SQL
statements; otherwise, returns true.
PrimaryKey
Determines whether the attribute is a primary key attribute or part of the attributes
that constitute the primary key for a given row. Returns true if the attribute is a
primary key attribute; otherwise, returns false.
Mandatory
Determines whether the attribute does not allow null values. Returns true if the
attribute is mandatory ; otherwise, returns false.
Updateable
Determines whether the attribute can be freely modified. Returns true if the
attribute is updateable; otherwise, returns false.
Kind
24-130
Determines whether the attribute is to be displayed in the short or long form
layout. The long form acts like a detail mode. The short form is summary a form.
Returns true if the attribute uses the short form layout; otherwise, returns false.
EditRenderer
Returns the class used to edit the attribute.
DisplayRenderer
Returns the class used to display the attribute.
Example
This example iterates over the attributes of a datasource and contstructs the labels for a query
form using the attribute's name definition.
<jbo:AttributeIterate id="attr1" datasource="dsQuery" queriableonly="true">

<tr>
<td align="right"><jbo:ShowDefinition
definition="name">##Column</jbo:ShowDefinition></td>
</tr>
24-131
<jbo:ShowHint>
Displays the available Control Hint of the specified attribute.
JSP Syntax
<jbo:ShowHint
[ datasource="datasourceInstanceName" ]
hintname="LABEL | TOOLTIP | DISPLAYHINT | CONTROLTYPE | DISPLAYWIDTH |
DISPLAYHEIGHT | FORMTYPE"
/>
Note: Hint names must be in uppercase.
Description
The <jbo:ShowHint> data tag lets you display the Control Hint properties of the specified
attribute in your JSP page. A Control Hint is a property of a view object or entity object attribute
that the business component developer can define. When a Control Hint has been defined for
an attribute, the web application will use the information to render the dataitem in the client.
How it renders the Control Hint depends on whether the client supports the specific action.
For example, an attribute of a view object or entity object has a name used by the business
components. If that attribute appears in the UI of the client application, then it may also have a
Control Hint label. In most cases, you would use the ShowHint data tag to display the attribute's
Control Hint label rather than the internally used attribute name.
Note, when you use the <jbo:InputRender> or <jbo:RenderValue> data tags, or any of the
BC4J component tags (for example, <jbo:DataTable>) to display attribute values, then you do
not need to use the ShowHint tag to display Control Hints. The BC4J rendering data tags and
component tags will use available Control Hints to decide how to render the control at runtime.
See also: oracle.jbo.AttributeHints
Attributes
● datasource—the datasource id, as defined in the <jbo:dataSource> data tag. This

attribute is only optional when ShowHint appears inside the body of a Row,
RowsetIterate, or AttributeIterate data tag.
24-132
to retrieve in your page. This attribute is only optional when ShowHint appears inside the
body of a Row, RowsetIterate, or AttributeIterate data tag.
● hintname—the name of the Control Hint property to display; name must be in uppercase.
Among the Control Hints that you can display include:
LABEL
The text the control will use for its label.
TOOLTIP
A short description the control will use for its tooltip text.
DISPLAYHINT
Specifies whether or not the attribute should be displayed by the client application.
CONTROLTYPE
The control type the client UI will use to display the attribute.
DISPLAYWIDTH
The character width to be used by the control that displays the attribute.
DISPLAYHEIGHT
The number of character rows to be used by the control that displays the attribute.
FORMTYPE
Specifies whether the attribute is to be displayed in the short or long form layout.
The long form acts like a detail mode. The short form is summary a form.
Example
This example echos an attribute’s label to the page, followed by the attribute's value:
<table>
<tr>
<td><jbo:ShowHint datasource=”ds1” dataitem=”Deptno” hintName=”LABEL” /></td>
<td><jbo:ShowValue datasource=”ds1” dataitem=”Deptno” /></td>
</tr>
</table>
Related topics
24-133
24-134
<jbo:ShowValue>
Displays a data value from the datasource you specify in your page.
JSP Syntax
<jbo:ShowValue
>
Description
ShowValue tag merely represents the value as String, Date or Numeric data type. If you need
to use another data type, use the RenderValue tag, which uses field renderers to interpret the
data.
Note: The value of the dataitem attribute must match the case of the business components attribute
name.
Attributes
● datasource—the datasource id that you want to use to insert data into your page. You
create the datasource using the DataSource data tag. This attribute is only optional when
ShowValue appears inside the body of a Row, RowsetIterate, or AttributeIterate data tag.
● dataitem—the name of the specific view object attribute that contains the data to insert
into your page. If you specify an attribute, the name must match the case of the business
components attribute name in the view object. When inside the body of an
AttributeIterate tag, the dataitem will be the current attribute of the iteration. Use the
special attribute "RowKey" to display the value of the key.
Example
<a href="srch_results.jsp?cid=<jbo:ShowValue datasource="category_vo" dataitem="ID" >

</jbo:ShowValue>" </a>
24-135
<jbo:UrlEvent>
A convenience tag that constructs a URL to submit an event.
JSP Syntax
<jbo:UrlEvent
[ targeturl='targeturlName']
[ targeturlparam='paramName']
event='eventName'
[ datasource='datasourceName'] | [ viewobject='viewobjectName']
[ addrowkey='true'| 'false']
[ extraparameters='param=value'[& 'param=value'...] ]
/>
Note: You should use the single quotes with the attributes of the UrlEvent data tag to avoid syntax errors inside
another HTML tag.
Description
The <jbo:UrlEvent> data tag lets you construct a URL with special request parameters to identify a JSP event.
Events you submit can be:
● User-defined events that your application handles as required.

● Predefined business component events that are handled by the various Data Components (such as the
DataScrollerComponent or DataRecordComponent).
You use the UrlEvent data tag inside any HTML tag that takes a URL. The JSP page constructs two request
parameters from the attribute values you supply in the UrlEvent data tag:
jboEvent='eventname'
jboEventVo='viewobjectname'
where the name of the view object is optional. The event you submit with the URL will apply to the view object in
the target JSP page and will be handled by the body of a corresponding <jbo:OnEvent> data tag in that page. If
you omit the view object name in the UrlEvent attributes, then the event will apply to any view object in the
target JSP page's datasource. If you want the event to apply to a specific view object, you can:
● Use the datasource attribute to supply the id of the datasource which contains the view object.
OR
● Use the viewobject attribute to supply the view object name.
Note: The target JSP page must contain the <jbo:OnEvent> data tag to handle the incoming event. See the
<jbo:OnEvent> data tag for details about handling events.
24-136
For example, if you where to use the UrlEvent data tag inside an HREF tag, these two forms are equivalent:
<a href="<jbo:UrlEvent targeturl='mytargetpage.jsp' event='next' datasource='myDataSource'/>" >Click for next

row.</a>
and
<a href="mytargetpage.jsp?jboEvent=next&jboEventVo=myViewObject" >Click for next row.</a>
The target JSP page will handle the two special event request parameters from the submitting JSP page. If the
value of these input parameters matches the identifiers in the <jbo:OnEvent> data tag, then the body of the
OnEvent data tag will be executed in the target page. See the <jbo:OnEvent> data tag for details.
Attributes
● targeturl—optional, the URL which specifies a target JSP page that you want to handle the event. You
can omit this attribute if you obtain the event name through a request parameter (use the targeturlparam
attribute instead).
● targeturlparam—optional, the name of the request parameter which contains the target URL. The URL
specifies a target JSP page that you want to handle the event. You can omit this attribute if you choose to
specify the target URL explicitly through the targeturl attribute.
● event—the event name identifier that you want to submit with the URL. Predefined JSP business
components events that the Data Components handle include:
❍ firstset, nextset, previousset, lastset to navigate to the next set of rows in a rowset.
❍ first, next, previous, last to navigate to the next row in a rowset.

❍ Update, Delete, Insert to perform an action on a row.
● datasource—optional, the id of the datasource that contains the view object on which you want to apply
the event. You create the datasource using the DataSource data tag. You can omit this attribute if you
choose to name the view object in the viewobject attribute or you want the event to apply to any view
● viewobject—optional, the full name of the view object on which you want to apply the event. You must
supply the name as it appears in your Business Components project. You can omit this attribute if you
choose to name the datasource in the datasource attribute or you want the event to apply to any view
Note: You can specify an existing view object defined by the application module or a view object you created
using the CreateViewObject data tag. If the view object is contained in a nested application module, you must
specify the view object name with the application module name: appmodNested.viewobjectName.
● addrowkey—optional, set to true when you want to submit a row key to identify the current row in the
submitting page's datasource. You would use this when the body of the <jbo:OnEvent> data tag in the
target JSP page needs to perform an action on a specific row.
● extraparameters—optional, the value of additional parameters that you want to submit with the URL. Your
target JSP page can handle these any way your application requires.
24-137
Examples
This example displays links that generate a next and first event for the datasource specified by the UrlEvent
data tag. The OnEvent data tags handle the events.

<jbo:OnEvent datasource="ds" name="next">

<jbo:RowsetNavigate datasource="ds" action="Next" />
</jbo:OnEvent>
<jbo:OnEvent datasource="ds" name="first">

</jbo:OnEvent>
<jbo:Row id="currentRow" datasource="ds" action="current" >

Name: <jbo:RenderValue dataitem="Ename" /><br>
Employee number: <jbo:RenderValue dataitem="Empno" /><br>
</jbo:Row>
<a href="<jbo:UrlEvent datasource='ds' event='First' />">First record</a>

<a href="<jbo:UrlEvent datasource='ds' event='Next' />">Next record</a>
24-138
<jbo:ViewCriteria>
Sets a search view criteria on a specified datasource.
JSP Syntax
<jbo:ViewCriteria
id="viewCriteriaInstanceName"
[ action="New | Append" ]
>
<jbo:CriteriaRow . . . >
<jbo:Criteria . . . />
</jbo:CriteriaRow . . .>
</jbo:ViewCriteria>
Description
The <jbo:ViewCriteria> data tag creates a new view criteria object for the datasource instance. A
view criteria is a list of criteria rows for a view object's WHERE clause, where one criteria row
contains criteria for the individual attributes. You use the criteria objects to assemble a dynamic SQL
statement. While the whereclause attribute in the <jbo:Datasource> data tag provides a simple way
to add a WHERE clause to a datasource, the criteria data tags provide a more structured and
dynamic way of creating a SQL query WHERE clause.
The view criteria provides the context for the contained criteria rows and individual criteria. To
provide this context, you must specify the datasource and view criteria instance id on the
ViewCriteria data tag. For this reason, CriteriaRow and Criteria data tags must appear inside the
body of a ViewCriteria tag, where the actual datasource is specified.
When your JSP page executes, the WHERE clause constructed for each row criteria object is
executed against the datasource in an OR'ed fashion. Thus, in order for a datasource value to be
returned as a search result against multiple row criteria, it need only satisfy one of the CriteriaRow
definitions. In addition, each row criteria can contain multiple Criteria definitions, which will execute
the criteria object in an AND'ed fashion. Thus, you can use the structure of CriteriaRow and Criteria
definitions to build a complex, structured, and dynamic WHERE clause against your datasource.
You can specify whether the view criteria in your JSP page should:
● Append to the criteria values to the previous row criteria. This is the default.
OR
24-139
● Always contain new criteria values.
Unless you create a ViewCriteria tag with its action attribute set to New, row criteria you create are
always appended and the resulting WHERE clause is OR'ed with the view criteria's previous row
criteria definitions. Therefore, if you want to allow users to reexecute the same row criteria with
different criteria values, you must identify the row criteria to update through its index. See the
<jbo:CriteriaRow> data tag for details about updating indexed row criteria in a view criteria context.
Note: The ViewCriteria data tag will return an exception if the datasource already has a WHERE clause
set.
See also:
oracle.jbo.ViewCriteria
oracle.jbo.ViewObject
Attributes
● id—the name of the instance of the view criteria created by the ViewCriteria tag. The name
you assign must be unique within a page. This can be any legal Java identifier.
● datasource—the datasource id, as defined in the <jbo:dataSource> data tag.
● action—optional, specifies how view criteria will use row criteria values at runtime. The default
is Append which always joins new criteria rows with the previous criteria rows when the view
criteria is executed. If you want to create view criteria with no existing criteria row definitions,
set to New.
Examples
The example below creates a new view criteria and criteria row using the new action to add them to
the view criteria. The Criteria data tag obtains the criteria value to perform the search from a JSP edit
form when the user clicks the Search or Add Criteria buttons. The JSP page with the OnEvent data
tag handles the generated event and receives the criteria value.

int nRows = 0;
{
}
%>
<jbo:ViewCriteria id="vc" datasource="ds" action="new">
24-140
{ %>
</jbo:CriteriaRow>
<% } %>
</jbo:ViewCriteria>
</jbo:OnEvent>
The example below clears a criteria row and uses the appends action on the view criteria to reset the
criteria value. The CriteriaRow data tag uses the index of an input parameter submitted by a JSP edit
form when the user clicks the Delete Criteria button. The JSP page with the OnEvent data tag
handles the generated event and clears the criteria row.
<jbo:OnEvent name="Del Criteria" >

<% String remove = params.getParameter("index"); %>
<jbo:ViewCriteria id="vc" datasource="ds" action="append">
<jbo:CriteriaRow id="row<%=remove%>" index="<%=remove%>" clearall="true" />
</jbo:ViewCriteria>
</jbo:OnEvent>
24-141
<jbo:ViewCriteriaIterate>
Iterates through the row criteria of a view criteria.
JSP Syntax
<jbo:ViewCriteriaIterate
/>
Description
The <jbo:ViewCriteriaIterate> data tag lets you create an iterator to step through each row criteria in a view criteria.
The datasource you specify for the ViewCriteriaIterate tag contains the view criteria object to be iterated.
Use this tag when you want to display the search criteria of all view row criteria in the specified view criteria. See the
<jbo:ShowCriteria> data tag for details about displaying criteria values using the ViewCriteriaIterator tag.
Attributes
● datasource—the datasource id, as defined in the <jbo:dataSource> data tag.
Examples
The example below creates a JSP query form by iterating over a view criteria to display existing search values for
the datasource to which it is bound. new view criteria and criteria row using the new action to add them to the view
criteria.
<jbo:ViewCriteriaIterate datasource="dsQuery" ><%

<td>
<table border="0" cellspacing="1" cellpadding="1">
<jbo:AttributeIterate id="df1" datasource="dsQuery" queriableonly="true">
<tr><%
if (index == 0)
{
%> <td align="right"><jbo:ShowDefinition definition="name"/></td><%
}
%> <td><input type="text" name="row<%= index %>_<jbo:ShowDefinition definition='name'/>"
value="<jbo:ShowCriteria />" ></td>
</tr>
<tr><td colspan="2" align="right"><a href="<jbo:UrlEvent targeturlparam='targetURL'
event='Del Criteria' datasource='dsQuery' extraparameters='<%="index=" + index%>'
/>">Delete</a></td></tr>
</table>
</td>
<% index++; %>
</jbo:ViewCriteriaIterate>
24-142
<jbo:WebBean>
A tag to use a web bean in your JSP.
JSP Syntax
<jbo:WebBean
id="WebBeanInstanceName"
wbclass="webbeanClassName"
/>
Description
The <jbo:WebBean> tag is useful when you want to:
● Reuse custom web beans in a data tag application

● Migrate an older style web beans-based JSP applications to a JSP application using only data
tags
Although users may continue to develop new applications with <jsp:useBean> in data tag-style JSP
applications, we do not recommend using the data web bean and web bean classes provided in the
oracle.jbo.html.databeans and oracle.jbo.html.webbeans packages for this purpose; instead, we
recommend developing new applications entirely with the BC4J data tags and component tags.
To migrate a web bean-style application developed in JDeveloper version 3.2 or earlier to a data tag-
style application, you must:
1. Add tags to define an application module and datasource in your JSP file.
2. Replace the <jsp:usebean> tag with the appropriate <jbo:DataWebBean> or <jbo:WebBean>
tag.
3. Remove the initialize() method (now done by datasource tag).
4. Remove the setReleasePageResources() method (now done by ApplicationModuletag).
5. Prefix the set property methods with a scriptable variable instance of the web bean (obtained
from the data tag's id="" attribute).
6. Leave the render() method, but move it outside the data tag.
Example
In a web bean-style application, you need to refer to the JavaDoc to call methods on the bean instance.
For example, the <jsp:useBean> tag with a EditCurrentRecord web bean might look like this:
24-143
<jsp:useBean class="oracle.jbo.html.webbeans.EditCurrentRecord"
id="efDetail" scope="request" >
<%
efDetail.setReleaseApplicationResources(true);
efDetail.initialize(application,session, request,response,out,
"package3_Package3Module.EmpView");
efDetail.render();
%>
</jsp:useBean>
In this example, you use the <jbo:WebBean> tag to replace the old <jsp:useBean> tag:
<jbo:ApplicationModule configname="myconfig" id="myappmod" releasemode="stateful"/>

<jbo:DataSource id="myds" appid="myappmod" viewobject="myvo" />
<jbo:WebWebBean id="efDetail" datasource="myds"
wbclass="oracle.jbo.html.webbeans.EditCurrentRecord" >
<%
%>
</jbo:WebBean>
<%
efDetail.render();
%>
...additional page content...
</jbo:ReleasePageResources />
Attributes
● id—the name of the instance of the web bean. The name you assign must be unique within a
page. This can be any legal Java identifier. Within a scriptlet, you use the id as a scriptable
variable of type oracle.jbo.html.webbeans.classname, where classname is the name of the web
bean.
● wbclass—the fully qualified name of the web bean class. For example,
oracle.jbo.html.webbeans.EditCurrentRecord.
24-144
24-145
Forward JSP Tag
Forwards a client request to an HTML file, JSP file, or servlet for processing. For complete
24-146
NavigatorBar Web Bean
Class Name: NavigatorBar
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\NavigatorBar.java
Description
Provides methods to dynamically generate a database navigation toolbar and render it to the
output stream of a JavaServer Page response. This generated toolbar includes navigation
buttons that are used to change the current record of a view object's rowset to a new record.
The NavigatorBar web bean combines the functionality of the Toolbar and RowSetNavigator
web beans and, in fact, uses both of them.
The NavigatorBar web bean is typically used in a master-detail JSP page.
If you use the NavigatorBar web bean directly in your JSP (instead of using the
<jbo:DataWebBean> data tag) together with a RowsetBrowser web bean, you will need to
define the rangesize for the view object prior to using the NavigatorBar. Since the NavigatorBar
renders prior to the RowsetBrowser web bean, it is possible that the Next Record button will
appear disabled. This can occur because the NavigationBar uses different assumptions about
the range size than the RowsetBrowser: the NavigatorBar uses the default range size, while the
RowsetBrowser uses 11.
To ensure the range size is the same for both web beans:
1. Create a data web bean that simply changes the view object's range size.
2. Add this data web bean to the top of your JSP page and setup the range
size.
3. Don't call setVisibleRows() on the RowsetBrowser web bean and now both data web
beans will have matching assumptions and navigation will work as expected.
24-147
Output Comment JSP Tag
Generates a comment that is sent to the client in the viewable page source. For complete
24-148
Page Directive JSP Tag
Defines attributes that apply to an entire JSP page. For complete details about the tag, see the
24-149
plugin JSP Tag
Downloads a plugin to the client Web browser to execute an applet or Bean. For complete
24-150
RowSetBrowser Web Bean
Class Name: RowSetBrowser
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\RowSetBrowser.java
Description
Use this web bean to dynamically generate an HTML table that contains records from a view
object's rowset.
The RowSetBrowser web bean is typically used in a master-detail JSP page.
24-151
RowSetNavigator Web Bean
Class Name: RowSetNavigator
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\RowSetNavigator.java
Description
Use to change the current record of a view object's rowset to a new record.
24-152
Scriptlet JSP Tag
Contains a code fragment valid in the page scripting language. For complete details about the
24-153
setProperty JSP Tag
Sets a property value or values in a Bean. For complete details about the tag, see the
24-154
TableControl Web Bean
Class Name: TableControl
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jdeveloper\jsp\wb\TableControl.java
Extends: HTMLToolBar
Implements: WebBean
Description
Provides methods to dynamically generate an HTML table and render it to the output stream of
a JSP response.
It is instantiated by the web beans ViewCurrentRecord and RowSetBrowser.
24-155
Tag Library Directive JSP Tag
Defines a tag library and prefix for the custom tags used in the JSP page. For complete details
about the tag, see the JavaServer Pages Developer's Guide from Sun Microsystems.
24-156
Toolbar web bean
Class Name: Toolbar
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jdeveloper\jsp\wb\Toolbar.java
Extends: HTMLToolBar
Implements: WebBean
Description
Provides methods to dynamically generate an HTML toolbar and render it to the output stream
of a JavaServer Page response.
24-157
useBean JSP Tag
Locates or instantiates a Bean with a specific name and scope. For complete details about the
24-158
ViewCurrentRecord Web Bean
Class Name: ViewCurrentRecord
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\ViewCurrentRecord.java
Description
Use to display the current record of a view object's rowset.
The ViewCurrentRecord web bean is typically used in a master-detail JSP page.
24-159
XMLDataGenerator Web Bean
Class Name: XMLDataGenerator
Source: [<JDeveloper>\lib\jbohtmlsrc.zip]\jbo\html\databeans\XMLDataGenerator.java
Description
Generates XML containing the data from a view object's rowset and renders it to the output
stream of a JavaServer Pages (JSP) response.
24-160
JSP and JSP UIX General Reference
❍ HTML Viewer
❍ JSP Viewer
❍ New Gallery - UIX JSP Category
❍ New Gallery - UIX XML Category
❍ New Gallery - Web Objects Category
❍ Preferences Dialog - HTML and JSP Page
❍ Code Attributes
❍ Applet HTML File Wizard - Finish
❍ HTML File Location
❍ Applet Parameters
❍ Positioning Attributes
❍ New Applet Dialog
❍ Tag Library Descriptor - Define New Tag

❍ Define New Tag
❍ Tag Library Descriptor - Taglib Descriptor Page
❍ Tag Library Descriptor - Tags Page
❍ Add JSP Tag Library

❍ JavaServer Page Tag Libraries
❍ JavaServer Page Tag Library
❍ New JSP Tag
❍ Tag Editor
❍ JSP Tag Attribute Wizard
❍ Add New Tag Scripting Variable
❍ New Web Tag
❍ XML Editor
❍ UIX Preview
❍ Preferences Dialog - XML Page
25-1
❍ Preferences Dialog - XML Schemas Page
❍ Add Schema Dialog
❍ UIX JSP Wizard - Finish

❍ UIX JSP Wizard - View Object Selection
❍ UIX JSP Wizard - Welcome
❍ Business Application
❍ Business Components UIX Web Application Wizard - Finish
❍ View Form
❍ View Links
❍ Web Site Information
❍ Business Components JSP Web Application Wizard - Welcome
❍ UIX XML Wizard - Finish
❍ UIX XML Wizard - View Object Selection
❍ UIX XML Wizard - Welcome
❍ UIX Wizard - Choose UIT

❍ UIX Wizard - Corporate Branding
❍ UIX Wizard - File Name
❍ UIX Wizard - Finish
❍ UIX Wizard - Footer
❍ UIX Wizard - Global Buttons
❍ UIX Wizard - Name and Namespace
❍ UIX Wizard - Page Header
❍ UIX Wizard - Page Title
❍ UIX Wizard - Product Branding
❍ UIX Wizard - Page Title
❍ UIX Wizard - Tab Bar
❍ UIX Wizard - Welcome
❍ XSQL Connection Panel

❍ View Object Selection Dialog
25-2
❍ Web Start Information
❍ Java Web Start Wizard - Welcome
❍ Application Information
25-3
HTML Viewer
The HTML Viewer provides a read-only view of an HTML file as it will appear in a browser. As
you edit your HTML file, JDeveloper updates the HTML Viewer for you in real time, so you can
see how your changes and additions will appear. You cannot directly modify the HTML source
file through this viewer. To modify the source, edit the file in the Code Editor. CSS links can be
relative or absolute.
In the HTML Viewer, a toolbar displays the standard browser Home, Back, Forward, Reload,
Stop and Find icons. You can use the Tab key to traverse the toolbar and press the Space bar
to activate an icon that has focus.
When the HTML Viewer has focus, you can also press Ctrl-F to open the Find dialog. When the
Find dialog opens, the Find what field is always empty. Any text search begins at the top of the
document and proceeds downwards, with automatic wrapping and scrolling. Use the Find Next
button to continue the search in this dialog. Use the Case-sensitive option to perform a case-
sensitive search.
Related topics
25-4
JSP Viewer
The JSP Viewer provides a read-only view of a JSP file as it will appear in a browser. As you
edit your JSP file, JDeveloper updates the JSP Viewer for you in real time, so you can see how
your changes and additions will appear. You cannot directly modify the JSP source file through
this viewer. To modify the source, edit the file in the Code Editor. CSS links can be relative or
absolute.
In the JSP Viewer, a toolbar displays standard browser Home, Back, Forward, Reload, Stop
and Find icons. You can use the Tab key to traverse the toolbar and press the Space bar to
activate an icon that has focus.
When the JSP Viewer has focus, you can also press Ctrl-F to open the Find dialog. When the
Find dialog opens, the Find what field is always empty. Any text search begins at the top of the
document and proceeds downwards, with automatic wrapping and scrolling. Use the Find Next
button to continue the search in this dialog. Use the Case-sensitive option to perform a case-
sensitive search.
Related topics

25-5
New Gallery - UIX JSP Category
From the UIX JSP category in the New Gallery you create new Business Components JSP
Applications, and new UIX JSP pages. All the objects in this category are available from any
Business Components JSP Application

Opens a wizard that creates a Business Components JSP application consisting of a set
of JavaServer Pages (JSPs) that connect to an Oracle Business Component application
module.
Starter Form
Creates a single UIX JSP page with the basic UIX page and layout tags already
included. This page is not bound to a business components project.
Browse Edit Form
Launches a wizard that creates forms to browse and edit records from a data source
represented by a view object. The wizard creates three UIX JSP pages named
UixBrowseEdit.jsp, UixEdit.jsp, and UixHelp.jsp, along with additional JSP and project
pages.
Browse Form (with Hide/Show)
Launches a wizard that creates forms to browse records from a data source represented
by a view object. The wizard creates three UIX JSP pages named
UixBrowseHideShow.jsp, UixEdit.jsp, and UixHelp.jsp, along with additional JSP and
project pages. The UixBrowseHideShow.jsp page provides a means of toggling a group
of UINodes between being disclosed or undisclosed.
Related topics
About UIX
Working with JSP UIX Pages
Creating a Simple UIX JSP Page
Generating a UIX JSP Application Based on a BC4J Project
Generating a Databound UIX JSP Form
25-6
New Gallery - UIX XML Category
From the UIX XML category in the New Gallery you create new UIX XML and template pages.
All the objects in this category are available from any project node or its children in the
Navigator. Only the pages created with the BC4J Browse/Edit Pages and Business
Components UIX XML Application items are bound to a business components project when
they are created.
Empty UIX
Creates a single UIX XML page with only the basic UIX page framework included for
data providers, page layout, and event handlers.
Empty UIT
Creates a single UIX template (UIT) definition file. After customizing this file, you can
manually create pages for a UIX XML application based on this template.
UIX with header, footer and navigation
Launches a wizard that creates a new UIX XML file that includes header, footer, tab bar,
global button, and page header sections, which can be modified as needed.
Template (UIT) with header, footer and navigation
Launches a wizard that creates a new UIX template (UIT) definition file that includes
header, footer, tab bar, global button, and page header sections, which can be modified
as needed. Use this option to create a template on which to base all the pages in your
application.
UIX based on existing UIT page layout
Launches a wizard that creates a new UIX XML file based on a template (UIT) definition
file. Use this wizard to create application pages based on a template you previously
created and saved.
Business Components UIX XML Application
Opens a wizard that creates a Business Components UIX XML application consisting of
a set of UIX XML pages that connect to an Oracle Business Component application
module.
BC4J Browse/Edit Pages
Launches a wizard that creates forms to browse and edit records from a data source
represented by a view object. The wizard creates the necessary UIX XML pages, which
you can edit in the XML Editor.
25-7
Related topics
About UIX
Working with XML UIX Pages
Working with XML UIX Template Pages
25-8
New Gallery - Web Objects Category
From the Web Objects category in the New Gallery you create new applets, HTTP servlets,
web beans, HTML pages, JSP pages, tag libraries, UIX pages, XML pages, XSQL pages, XSL
stylesheets, and XML schemas. Many of the objects in this category are available from any
Applet
Opens the New Applet dialog where you can specify information required to add a
skeleton applet .java file to your project. Use the Code Editor to develop your applet
class.
Applet HTML File
Launches the Applet HTML File Wizard. Complete the wizard to create an .html file that
acts as the container for your applet. You can also create an optional deployment profile
with this wizard. Use the Code Editor to modify the HTML file.
HTML
Adds a skeleton HTML file to your project named untitled#.html, which opens in the
HTML Editor. Once the file appears in your project, you can rename the file by choosing
File | Rename. Use the HTML Editor to modify the HTML file.
HTTP Servlet
Launches the HTTP Servlet Wizard. Complete the wizard to add a customized HTTP
servlet Java file to your project. Use the Code Editor to develop your HTTP servlet class.
JSP
Adds a skeleton JSP (JavaServer Page) file to your project named untitled#.jsp, which
opens in the HTML Editor. Once the file appears in your project, you can rename the file
by choosing File | Rename. Use the HTML Editor and tags from the Component Palette
to modify the JSP file.
Tag Library
Opens the JavaServer Page Tag Library dialog where you can specify information
required to create a new JavaServer Page custom tag library (TLD). New JSP tags can
be created and added to this tag library.
Java Web Start Launcher
Launches the Java Web Start Launcher Wizard. This wizard adds a Java Web Start .jnlp
file to your project. It assumes you have already created a simple archive that you will
deploy. Use this wizard to create a JNLP file and web.xml file that you can use with your
application or applet project to run and deploy Java applications. Java Web Start is an
application deployment software developed by Sun Microsystems that lets you maintain
25-9
Java applications on the web server, while users download and run them on their client
machines.
XML
Creates an XML file with only the <?xml version="1.0" ?> line at the top. Use the XML
Editor to work with this page after you create it.
XSL
Creates a skeleton XSL file named untitled#.xsl in your project, which opens in the XML
editor. Edit the XSL file to create your own custom stylesheet. When you are finished,
specify the stylesheet name in your XSQL file to format the raw XML data.
XSQL
Creates a skeleton XSQL file named untitled#.xsql, which opens in the XML Editor. You
can type code in this editor, add tags by selecting them from the XSQL page on the
Component Palette, and modify the file by applying your own XSL stylesheet.
Web Bean
Opens the New Web Bean dialog. Complete the dialog to add a skeleton web bean Java
file to your project, which opens in the Code Editor. Use the Code Editor to develop your
web bean class.
UIX
Creates a UIX XML file with only the basic UIX page framework included for data
providers, page layout, and event handlers. Use the XML Editor to work with this page
after you create it. To create more complex UIX pages, use the items in the UIX XML
category.
XML Schema
Creates a skeleton XML schema file (with an .xsd extension) that you can use as the
basis of a new XML schema. Use the XML Editor to work with this page after you create
it. Intelligent tag insight and validation are available while you are editing XML schema
files with the XML Editor.
Related topics
About HTTP Servlets

About UIX
About XSQL Servlet Clients
About Web Beans
25-10
Preferences Dialog - HTML and JSP Page
Use the HTML and JSP page to enter your preference for tag completion when you are editing
an HTML or JSP file and inserting a new HTML or JSP tag.
End Tag Completion

Check to have JDeveloper automatically add the closing tag when you insert an opening
tag by using tag (code) insight. For example, when you enter the <body> tag, JDeveloper
automatically adds the </body> tag if you check this option.
Related topics

25-11
Code Attributes
Use the Code Attributes panel to specify the applet that should be invoked, as well as the
Codebase and Archive attributes used to locate the classes and resource needed by the
applet.
Code
Select the name of the applet class that should be executed. By default, the combo box
contains all the applets found in your project. Click Browse to select a different applet
class.
Codebase
Enter the codebase or leave it blank to use the default location. When the applet .class
file is used with this HTML page, if it will not be placed in the same directory on the web
server as the HTML page (or in the appropriate directory for the applet's package), enter
the relative path or absolute URL to the applet .class file location. This path is a single
node classpath for the deployed applet .class file.
Archive
Enter the name of the .jar file that will contain your applet. Leave the name blank if the
applet class files will be deployed as individual files.
Libraries will be deployed with Applet
Select to include the libraries needed by the applet to be deployed with it.
Libraries will be deployed separately
Select to specify that the libraries needed by the applet will not be deployed with it but
instead deployed as a separate Web Application.
Library Root
Enter the location where the libraries are deployed.
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
25-12
25-13
Applet HTML File Wizard — Finish
Use the Finish panel to optionally create a deployment profile that will contain the information
which is necessary to deploy the applet described by the new HTML file as a web application.
Click Finish to complete the wizard.
Create a deployment profile for this applet

Check to create the deployment profile now. If you do not check this option, the filed
below are disabled. You can create a deployment profile for the applet at a later time.
Profile location
Enter a path on your local machine for the deploment profile or click Browse to select a
path. The default location is th elocation inwhich you are creating the applet HTML file.
Profile name
Enter a name for your new deployment profile. The default name is applet1.deploy.
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
25-14
HTML File Location
Use the HTML File Location panel to specify the location and filename for the new applet HTML
file. You can also optionally specify an existing HTML file with an Applet tag to use as the
template for your new file.
Directory
Enter the full path for the location of the new applet HTML file or click Browse to select a
path.
Filename
Enter a name for your new HTML file class. The default filename is untitled1.html.
Use the default template
Select to base your file on JDeveloper's default template for applet HTML files and then
specify parameters to generate PARAM tags within the APPLET tags of the new file.
Use a custom template
Select to base your file on another applet HTML file you previously created with
JDeveloper. The APPLET tag in this template will be replaced with the value specified in
the wizard. The rest of the HTML code will be preserved. Enter the filename or click
Browse to select it.
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
25-15
Applet Parameters
Use the Applet Parameters panel to specify the name and string values of parameters that will
be passed to the applet. This information will generate PARAM tags within the APPLET tag of
the new HTML file. These parameters function like command line parameters in an application.
They allow you to pass information into the applet when it is launched from the HTML page.
Parameters
Lists the names and values of the parameters you have added. When you add a
parameter to this list, JDeveloper adds another parameter entry to the HTML file that it
generates.
Name
Enter the name attribute for the parameter which provides the NAME attribute in the
PARAM tag in the HTML file, and to provide the name parameter of the corresponding
getParameter() call in the Java source. Each applet parameter must have a unique
name.
Value
Enter the string value for the name parameter you entered in the Name field.
Add
Click to add a new line where you can specify the Name and Value of the parameter to
pass to the applet. In the new line, enter the Name and Value in the appropriate fields.
Click Add again to add another parameter.
Remove
Select a line in the list of parameters click Remove to delete if you do not want it to be
included.
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
25-16
Positioning Attributes
Use the Positioning Attributes panel to specify the values for the standard HTML tag attributes
that control how the applet is rendered on the page. Height, Width and Align are required
values; VSpace and HSpace are optional.
Height
Enter the number of pixels for the height of the applet. This value will be assigned to the
HEIGHT attribute in the APPLET tag.
Width
Enter the number of pixels for the width of the applet. This value will be assigned to the
WIDTH attribute in the APPLET tag.
VSpace
Enter the number of pixels for the vertical space surrounding the applet. VSpace controls
the amount of space above and below the applet. For example, if you enter a value of 20
pixels, a space 20 pixels wide will be inserted between the top and bottom edge of the
applet and any surrounding text. This value will be assigned to the VSPACE attribute of
the APPLET tag on the HTML page.
HSpace
Enter the number of pixels for the horizontal space surrounding the applet. HSpace
controls the amount of space to the left and right of the applet. For example, if you enter
a value of 20 pixels, a space 20 pixels wide will be inserted between the left and right
edge of the applet and any surrounding text. This value will be assigned to the HSPACE
attribute of the APPLET tag.
Align
Select a value to specify how the applet will be aligned on the HTML page. This value is
assigned to the ALIGN attribute in the APPLET tag.
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
25-17
25-18
New Applet Dialog
Use the New Applet dialog to create a Java applet, by specifying class and package details.
Name
Enter a name for your new applet class. The name you enter here will become the
filename for the top-level class in your applet. The default class name is Applet1.
Package
Displays the name of the package your class belongs to. Accept the default, enter a new
name, or click Browse to select a package in your existing class or source path.
Extends
Displays the name of the class that this applet extends. By default, applets extend
javax.swing.JApplet. Additional superclasses can be selected from the combo box or by
clicking Browse.
Optional Attributes
Can Run Standalone

Select to create a main() method in the applet file so it can be run for testing with or
without being called from an HTML page.
Generate Standard Methods
Select so that JDeveloper overrides the standard applet methods with skeleton methods
in your class. The standard applet methods are: show(), close(), and dispose().
Related topics
Creating an Applet
Debugging an Applet
Running an Applet
25-19
Tag Library Descriptor (JSP 1.1) - Define New Tag
Use this dialog box to specify the name, Tag class and TagExtraInfo (TEI) class of the tag you
are adding to the J2EE tag library deployment descriptor.
Name
Enter a name for the tag you are defining.
Tag class
Enter the name of the class that provides the handler for the tag you are defining.
TEI class
Enter the TagExtraInfo (TEI) class for the tag you are defining. This is an optional class
provided by the tag library author to describe additional translation-time information not
described in the TLD. This class must be used if the tag defines any scripting variables
or to provide translation-time validation of the tag attributes.
Related topics

Editing Deployment Descriptors
25-20
Define New Tag
Use this dialog box to specify the name, Tag class and TagExtraInfo (TEI) class of the tag you
are adding to the J2EE tag library deployment descriptor.
Name
Tag class
TEI class
or to provide translation-time validation of the tag attributes.
Related topics

25-21
Tag Library Descriptor (JSP 1.1) - Taglib Descriptor
Page
Use this page to add or edit information in the tag library deployment descriptor.
Taglib version
Displays the tag library version number.
JSP version
Displays the JSP version number.
Short name
Displays the preferred (short name) prefix. This may be used by authoring tools as the
preferred prefix when creating an include directive for this library.
Public URI
Displays the URI actually used by the taglib directive.
Info
Displays translation-time information associated with a taglib directive, and its underlying
TLD file. Most of the information is directly from the TLD, except for the prefix and the uri
values used in the taglib directive.
Related topics

25-22
Tag Library Descriptor (JSP 1.1) - Tags Page
Use this page to add tags to the tag library deployment descriptor, and modify or delete
previously added tags.
Tags
Displays the tags that have been added to the J2EE tag library deployment descriptor.
Add
Opens the Define New Tag dialog box where you can add a tag to the deployment
descriptor.
Delete
Removes the selected tag from the deployment descriptor.
Name
Displays the name of the selected tag. You can edit the name in this field.
Tag class
Displays the name of the class that provides the handler for the selected tag. You can
edit the class name in this field.
TEI class
Displays the TagExtraInfo (TEI) class for the selected tag. This is an optional class
or to provide translation-time validation of the tag attributes. You can edit the TEI class
name in this field.
Related topics

25-23
Add JSP Tag Library
Use this dialog to specify the custom tag library descriptor (TLD) file that you want to add to the
Component Palette in JDeveloper.
Jar File
Enter the name of the JAR or ZIP file that contains the taglib.tld file located in the meta-
inf directory.
URI
Enter the location of the TLD file. This is optional since the location of the tag library will
be added to the project's web.xml file.
Prefix
Enter a prefix to define a unique identifier for all tags in this library.
Related topics

25-24
Add Component Dialog
Use this dialog to add and remove JSP custom tag libraries. You can also add individual tags
from a tag library to the Component Palette, by expanding the tag library node in the tree,
selecting the tag name, and clicking OK.
Select a tag to add

Lists all the JSP tag libraries installed with JDeveloper and any custom tag libraries.
Expand the node to display the tags in each tag library. Select an individual tag and click
OK to add the tag to the Component Palette. Select a library and click Remove Library to
delete the library from the Component Palette.
Add Library
Opens the Add JSP Tag Library dialog where you can specify the JAR file that contains
the custom tag library descriptor (TLD) file that you want to add to the Component
Palette.
Remove Library
Deletes the selected tag library.
Icon
Displays the name and location of the icon file associated with your selection in the tree,
which will display with the tag name on the Component Palette. Initially, this will be the
default icon for the selected tag.
Use Default
Click to insert the filename and path of the default icon for this tag, if it does not display.
Select Image
Click to browse for an icon other than the default to use for this tag. When you return to
this dialog, the filename and path for the icon you have selected appears in the Icon field
above.
Related topics

25-25
25-26
JavaServer Page Tag Library
Use this dialog to create a new JavaServer Page custom tag library.
Short Name
Enter the preferred prefix, commonly called the short name. The short name will be used
by JDeveloper as the preferred prefix when creating an include directive for this library.
JSP Version
Enter the JSP version number. The default is version 1.1.
Tag Library Version
Enter the tag library version number. The default is version 1.0.
Tag Library URI
Enter the URI actually used by the taglib directive.
Tag Library Info
Enter any translation-time information associated with the taglib directive and its
underlying TLD file, or any additional descriptive information.
Related topics

25-27
New JSP Tag
Use this dialog to create a new JSP tag to add to a JavaServer Page custom tag library.
Name
Tag Class Name
Package Name
Select the name of the package for the new tag class.
Tag to Extend
Select the name of an existing tag to extend; extending a tag can reduce the number of
methods you must write for the new tag.
TEI Class Name
you provide to describe additional translation-time information not described in the TLD.
This class must be used if the tag defines any scripting variables or to provide translation-
time validation of the tag attributes.
Body Content
Select the type of body content.
Empty
Used for tags without bodies to declare that their body content is empty.
JSP
Used for body content containing custom and core tags, scripting elements, and HTML
text.
Tag Dependent
Used for all other types of body content.
Description
Enter information about the tag's use or purpose, or any additional descriptive
information.
25-28
Related topics

25-29
Tag Editor
Use this dialog to enter the values for the attributes of a tag that is part of a JSP custom tag
library. If the tag library developer added examples to the tld file, you can see the examples
when you click the Tag Info button.
Related topics
About JSP Tags

25-30
JSP Tag Attribute Wizard
Use this dialog to specify the information needed to add an attribute to a JSP tag.
Name
Enter a name for the tag attribute you are defining.
Required
Check to specify the the attribute you are defining requires a value.
Value evaluated at Request Time
Indicate when the attribute value should be evaluated by choosing one of the "Value
evaluated" options. Select to indicate that the attribute value should be evaluated at
request time (it can be a dynamic value).
Value evaluated at JSP Translation Time
Select to indicate that the attribute value should be evaluated at JSP Translation Time.
Code Generation Options
Specify the attribute value and type.
Default Attribute Value

Enter the default value of the attribute you are defining.
Type
Select the default attribute type from the list.
Attribute Value
Select the option that describes the attribute value and complete any additional fields.
Is used as Reference Id
Select if the attribute is used as a reference Id and select its scope.
Scope
If you select the Is used as Reference Id option, select the attribute scope from the list.
The scope constrains the accessibility and lifetime of the object.
Refers to tag or class
Select if the attribute refers to tag or class and select its type and scope, and enter the
variable name.
Type
25-31
If you select the Refers to tag or class option, select the default attribute type from the
list.
Variable Name
If you select the Refers to tag or class option, enter a name for the variable.
Scope
If you select the Refers to tag or class option, select the attribute scope from the list.
Is none of the above
Select if the attribute is not used as a reference Id ad does not refer to tag or class.
Related topics

25-32
Add New Tag Scripting Variable
Use this dialog to specify the information needed to add a scripting variable to a tag.
Variable Name
Enter a name for the new tag scripting variable you are defining.
How name is determined
Select the option that describes how the variable is determined: Fixed, From Attribute or
Other. If you select From Attribute, also select the attribute from the list of defined
attributes.
Variable Type
Select the variable type from the list.
Scope
Select the variable scope from the list.
New Declaration
Check to specify that the variable you are defining is a new declaration.
Related topics

25-33
New Web Tag
Use this dialog to provide the information to define the web tag class.
Package name
Enter the name of the package to contain your web tag. If the package doesn't exist, it is
created.
Class Name for new Web Tag
Enter the class name of your new web tag.
Add data source support
Select to generate a web tag class that supports connection to a data source. This
results in your web tag extending the class oracle.jdeveloper.html.DataWebTagImpl
rather than the class oracle.jdeveloper.html.WebTagImpl.
Description
Enter a description of your new web tag.
25-34
XML Editor
The XML Editor is a specialized schema-driven editor for editing XML languages including UIX,
UIT, XSQL and XSL files. The editor supports syntax highlighting, Structure Window view, and
the Property Inspector. If the XML language has a XML schema associated with it, Tag (Code)
Insight is also provided. You can add new XML schemas by registering them using the XML
Schemas panel reached by choosing Tools | Preferences.
While you are using the XML Editor:
● Tag Insight opens a list with valid tags and attributes, based on the schema. While you
are typing, you can invoke tag insight by pausing after typing the < (opening bracket) or
by pressing Ctrl Space (if you are using the default keymapping).
● If End tag completion is checked in the XML Preferences panel (choose Tools |
Preferences | Editor | XML), the end tag will be automatically inserted. If Required
Attribute Insertion is checked on this panel, the required attributes of an element will
also be inserted for you. You can invoke it for attributes by entering a space after
selecting a tag. Invoke it repeatedly for additional attributes by entering additional
spaces.
also displays any XML syntax errors found as you type and edit. You can double click on
an element, attribute, or error to edit it in the XML Editor.
Tip: Right-click on the file in the Navigator and choose Check XML Syntax to check the syntax
and display the results in the XML Syntax tab of the message window.
● The Property Inspector displays attributes of elements and tags in the file. You can edit
the values of attributes in the Property Inspector to update your file.
● If your file is a UIX file, right-click on the file in the Navigator and choose UIX Preview to
see a read-only view of the page as it will appear in a browser.
Related topics

25-35
25-36
UIX Preview
The UIX Preview window provides a read-only view of a UIX file as it will appear in a browser.
As you edit your UIX file, JDeveloper updates the UIX Preview window for you in real time, so
you can see how your changes and additions will appear.
You cannot test your links in this viewer, as all links are disabled. Right-click the file in the
Navigator and click Run to run the file and test your links in the browser.
You cannot directly modify the UIX source file through this viewer. To modify the UIX source,
edit the file in the XML Editor.
Related topics

Previewing UIX XML pages
Running UIX XML pages
25-37
Preferences Dialog - XML Page
Use the XML page to enter your preferences for features that are available while you are
editing an XML file and inserting new tags, to help you create valid and well formed XML
documents.
End Tag Completion

Check to have JDeveloper automatically add the closing tag when you insert an opening
tag by using tag (code) insight. For example, when you enter the <head> tag,
JDeveloper automatically adds the </head> tag if you check this option.
Required Attribute Insertion
Check to have JDeveloper include the required attributes for each tag you add, so that
you only have to enter the attribute values.
Smart Indentation
Check to have JDeveloper add appropriate indentations as you add tags, so that opening
tags are correctly indented and matching closing tags are correctly outdented as you are
editing.
Related topics

25-38
Preferences Dialog - XML Schemas Page
Use the XML Schemas page to view all the currently registered XML schemas, add new
schemas to support additional namespaces and elements, remove existing schemas, and
unload schemas from memory.
JDeveloper Schemas for XML Editing

Lists the names and locations of the pre-registered schemas currently available when
editing XML documents and the file extension with which each schema is associated.
User Schemas for XML Editing
Lists the names and locations of the schemas you have added since installing
JDeveloper which are available when editing XML documents, and the file extension with
which each schema is associated. Select a schema and click Remove to delete it from
this list if you no longer want to use it.
Add
Click to open the Add Schema dialog where you can specify a new schema to add to the
list of User Schemas.
Remove
Select a User schema in the Location list and click Remove to delete if you do not want it
to be used.
Clear Cache
Click to unload all currently loaded schemas from memory.
Related topics

25-39
Add Schema Dialog
Use the Add Schema dialog to add to the list of schemas available when editing XML
documents, to add support for additional namespaces and elements.
Add a Schema from the file system or a URL

Enter the name and location of the XML schema file you are adding.
Extension
Enter the file extension to register the schema for a specific file type.
Validate Schema
Check to have JDeveloper automatically validate the schema when you add it.
Related topics

25-40
UIX JSP Data Page Wizard - Finish
Use the Finish page to complete the creation of the UIX JSP page(s) by clicking Finish. You
can click Back to make necessary changes or review your selections, before completing the
wizard.
25-41
UIX JSP Data Page Wizard - Business Application
Use the Business Application page to:
● Select the application module from which you want your UIX JSP application to browse
and update data.
● Specify the configuration which contains the connection information you want to use for
the selected application module.
Select Business Project

Select Application Module
Business Components project that is in the same workspace as the UIX JSP project in
which you are inserting the web page.
Configuration
From the list, choose the configuration that your want your UIX JSP to use to connect to
Configurations.
25-42
UIX JSP Data Page Wizard - Welcome
Use the wizard to create new UIX JSP pages and to connect to a Business Component
application module. You can choose from these UIX JSP forms:
Starter Form
Use this form to create a single UIX JSP page with the basic UIX page and layout tags
already included. This page does not connect to a Business Component application
module.
Browse Edit Form
object. The wizard creates four UIX JSP pages named UixBrowseEdit.jsp, UixEdit.jsp,
UixHelp.jsp , UixHelp.jsp and other project files, which can create the foundation of your
UIX JSP application.
Browse Form (with Hide/Show)
Use this form to browse records from a data source represented by a view object. The
wizard creates four UIX JSP pages named UixBrowseHideShow.jsp, UixEdit.jsp,
UixHelp.jsp and other project files. The UixBrowseHideShow.jsp page provides a means
of toggling a group of UINodes between being disclosed or undisclosed.
To create a UIX JSP Browse or Browse Edit form with this wizard, you must:
● Select the view object you want your UIX JSP page to use.
These selections are not necessary when you create the Starter form.

Clear this check box to skip the Welcome page next time you use the UIX JSP wizard.
25-43
Use the Business Application Information page to generate a UIX XML application for a specific
application module and deployment configuration.

UIX XML application property file name.
Select Config
From the dropdown menu, choose the configuration that your want to use to connect to
Configurations.
25-44
Business Components UIX XML Web Application
Wizard - Finish
Use the Finish page to complete the creation of your new Business Components UIX XML
application by clicking Finish.
25-45
View Form
Use the View Form page to select which view objects you want to generate UIX XML pages for
and which forms are generated for each view object selected.
By default, UIX XML pages for all views are generated, including all forms for each view object.
View Objects
Select the view object for which you want to modify form generation settings. The page
displays the current UIX XML form generation settings for the selected view object. To
see the settings for another view object, make another selection in the View Objects list.
Form Options
Unselect the form options to modify the form generation settings. If you do not change
the default settings, all forms will be generated.
Generate Page
Selected by default. Generates UIX XML pages for the selected view object.
Unselect to prevent a UIX XML page and all forms from being generated.
Query Form
Selected by default. Generates a UIX XML query form for the selected view object.
Unselect to prevent the query form from being generated.
Browse Form
Selected by default. Generates a UIX XML browse form for the selected view
object. Unselect to prevent the browse form from being generated.
Edit Form
Selected by default. Generates a UIX XML edit form for the selected view object.
Unselect to prevent the edit form from being generated.
New Record Form
Selected by default. Generates a UIX XML insert form for the selected view object.
Unselect to prevent the insert form from being generated.
25-46
View Links
Use the View Links page to generate UIX XML pages that use single tables or master-details
tables. The application module you selected in a previous page contains user-defined view
links that you may or may not want your generated UIX XML pages to use. If you want to
generated master-detail UIX XML pages, you must select at least one view link.
All View Links

Enables all view links in the application module selection for use with the generated UIX
XML pages. The generated UIX XML pages will display master-detail relationships for
each view link that the application module contains.
No View Links
Disables all view links in the application module selection for use with the generated UIX
XML pages. This will prevent the generated UIX XML pages from displaying master-
detail relationships. Instead, the generated UIX XML pages will behave as single tables.
Only the Following View Links
Enables specific view links in the application module selection for use with the generated
UIX XML pages. The links you select in the View Links list will define master-detail
relationships for the generated pages.
25-47
Web Site Information
Use the Web Site Information page to name your Business Components UIX XML application,
specify the directory in which to place its files, and provide a description of it for informational
purposes.
Web Application Name

Enter the name of the UIX XML application you are creating.
Project Server Root
Displays the document root directory of your web server. This field is read-only. To
change the document root directory, you must edit the properties of the project containing
this UIX XML application. To do this, find the project within the Navigator, right-click it,
and choose Properties from the pop-up menu.
Document Root
Enter the name of the directory to contain your UIX XML application files. The application
directory goes under your Project HTML Root, so you should not enter a full path with the
name, just the path relative to the Project HTML Root. JDeveloper creates the application
directory if it doesn't exist (and any non-existent directories in the relative path as well).
War File Name
Enter the name for the web archive (.war) file you want the wizard to generate. If you do
not supply a name a default will be provided.
Application Description
Enter a description of your UIX XML application.
25-48
Business Components UIX XML Web Application
Wizard - Welcome
Use the Business Components UIX XML Web Application Wizard to create a Business
Components UIX application consisting of a set of UIX XML pages that connect to an Oracle
Business Component application module.
To create a UIX application, you must:
● Provide information about your UIX XML application and its web site.
● Provide information about the Business Component application module you want your
UIX XML application to use.
● Provide database connection information.
● Select the view objects you want your UIX XML application to use.

Clear this check box to skip the Welcome page next time you use the UIX Web
Application Wizard.
25-49
UIX XML Data Page Wizard - Finish
Use the Finish page to complete the creation of the UIX XML pages by clicking Finish. You can
click Back to make necessary changes or review your selections, before completing the wizard.
25-50
UIX XML Data Page Wizard - Business Application
Use the Business Application page to:
● Select the application module from which you want your UIX XML application to browse
and update data.
● Specify the configuration which contains the connection information you want to use for
the selected application module.

application property file name.
Business Components project that is in the same workspace as the UIX XML project in
which you are inserting the web page.
Configuration
From the list, choose the configuration that your want your UIX XML to use to connect to
Configurations.
25-51
UIX XML Data Page Wizard - Welcome
Use the wizard to create new UIX XML pages and to connect to a Business Component
application module. You can create:
Browse/Edit Pages
object. The wizard creates UIX XML pages and other project files, which can create the
foundation of your UIX XML application.
To create UIX XML Browse Edit pages with this wizard, you must:
● Select the view object you want your UIX XML pages to use.
module you want your UIX XML pages to use.

Clear this check box to skip the Welcome page next time you use the UIX XML Data
Page wizard. The Welcome page is informational only and may be skipped.
25-52
UIX Wizard - Choose UIT
Use this dialog to specify the file name of the new UIX template(UIT) file on which you are
basing the new page you are creating.
UIT File
Enter the path and name of the UIT file that you want to use as the page template.
25-53
UIX Wizard - Corporate Branding
Use this dialog to specify the Corporate Branding image and associated link for the new UIX
page(s).
Select Image
Click to select the image you want to use in the Corporate Branding section in the top left
area of the page.
URL
Enter the destination URL that will execute when the user clicks on the Corporate
Branding image specified above.
25-54
UIX Wizard - File Name
Use this dialog to specify the file name for the new UIX page or UIT file you are creating. You
cannot change the default location.
File
Enter a name for the file you are creating.
25-55
UIX Wizard - Finish
Use the Finish page to complete the creation of the UIX page or UIT file by clicking Finish. You
can click Back to make necessary changes or review your selections, before completing the
wizard.
25-56
UIX Wizard - Footer
Use this dialog to specify information about the copyright message, privacy message, and
privacy statement that will appear in the footer of the new UIX page(s).
Copyright message
Enter the text that will appear as the copyright message.
Privacy message
Enter the text that will appear as the privacy message.
Relative link to privacy statement
Enter the relative path to the file that will display the complete privacy statement.
25-57
UIX Wizard - Global Buttons
Use this dialog to specify information about the global buttons and related links for the new UIX
page(s). Global buttons are available from every page in an application and appear in the top
right of the page.
Text
Enter the text that will appear on each global button on the page.
Destination URL
Enter the destination URL that will execute when the user clicks on the global button.
Image Location
Enter the image that you want to appear on the global button.
Add Button
Click to add a new line where you can enter the Text, and Destination URL, and Image
Location.
Remove Button
Click to remove the selected global button from the list box above so it is not added to
your page.
25-58
UIX Wizard - Name and Namespace
Use this dialog to specify the local name and target namespace for the new UIX template you
are creating. An XML namespace is a collection of names that are used in XML documents as
element types and attribute names.
Local Name
Enter a name for the template that will be stored on your local machine.
Target Namespace
Enter the URI for the template element.
25-59
UIX Wizard - Page Header
Use this dialog to specify information about the page headers and related links for the new UIX
page(s). These page headers will provide a second level of navigation in your application.
Page Header Text

Enter the text that will appear on each page header.
Page Header Destination
Enter the destination URL that will execute when the user clicks on the page header.
Add Page Header
Click to add a new line where you can enter the Page Header Text and Page Header
Destination.
Remove Page Header
Click to remove the selected page headers from the list box above so it is not added to
your page.
25-60
UIX Wizard - Page Title
Use this dialog to specify the HTML page title for the new UIX page you are creating.
Title
Enter the text exactly as you would like it to appear on the top left border of the browser
window.
25-61
UIX Wizard - Product Branding
Use this dialog to specify the Product Branding image and associated link for the new UIX
page(s).
Select Image
Click to select the image you want to use in the Product Branding section in the top left
area of the page.
URL
Enter the destination URL that will execute when the user clicks on the Product Branding
image specified above.
25-62
UIX Wizard - Set Attributes
Use this dialog to specify the values of attributes for specific elements on the new UIX page
you are creating. The attributes displayed in the list are those that are included in the template.
Attribute Name
Displays an attribute in the template that must be specified for this page.
Java Type
Displays the type of value that you must enter for each attribute.
Attribute Value
Enter the value to set the attribute for this page.
25-63
UIX Wizard - Tab Bar
Use this dialog to specify information about the tab bars and related links for the new UIX
page(s).
Tab Text
Enter the text that will appear on each tab.
Tab Destination
Enter the destination URL that will execute when the user clicks on the tab.
Add Tab
Click to add a new line where you can enter the Tab Text and Tab Destination.
Remove Tab
Click to remove the selected tab from the list box above so it is not added to your page.
Please specify the selected tab index (starting from 0)
(Displays only in the UIX Wizard) Specify which tab will be in front when the page
displays by entering the associated tab number. Entering 0 causes the leftmost tab to be
in front.
Create attribute for setting selected tab
(Displays only in the UIT Wizard) Check if you want to create an attribute that will let you
specify which tab will be in front when you create pages based on the template.
25-64
UIX Wizard - Welcome
Use the wizard to create new UIX pages or templates. You can choose from these UIX XML
wizards:
UIX with header, footer and navigation

Launches the UIX Page wizard that creates a new UIX file that includes header, footer,
tab bar, global button, and page header sections, which can be modified as needed.
Template (UIT) with header, footer and navigation
Launches the UIX Template wizard that creates a new UIX template (UIT) definition file
that includes header, footer, tab bar, global button, and page header sections, which can
be modified as needed. After you create a template, you can base all the pages in your
application on it.
UIX based on existing UIT page layout
Launches the UIX Template Customizer wizard that creates a new UIX file based on a
template (UIT) definition file. Use this wizard to create application pages based on a
template you previously created and saved.
Show this page next time

Clear this check box to skip the Welcome page next time you use the UIX wizard. The
Welcome page is informational only and may be skipped.
25-65
XSQL Connection Panel
Use the Connection panel to view the database connection information that the XSQL file will
use. The information in this panel is not directly editable. Click New to enter information for a
new connection or click Edit to edit the information for an existing connection.
Connection
From the drop-down list, select the connection that you want to use. If these fields do not
contain the proper information, click New to enter information for a new connection, or
click Edit to edit an existing connection.
Username
The name of the user connecting to the database. If you want to change this value, click
Edit to open the Connection dialog box.
Driver
The class name of the JDBC driver that will be used to connect to the database. If you
want to change this value, click Edit to open the Connection dialog box.
URL
The URL for the JDBC connection. If you want to change this value, click Edit to open
the Connection dialog box.
Related topics

Adding XSQL Tags
25-66
View Object Selection Dialog
Use the View Object Selection dialog to select the view object that a web page accesses and
specify the configuration for the deployed application module.

application property file name.
Business Components project that is in the same workspace as the project in which you
are inserting the web page.
Select Configuration
From the list, choose the configuration that your want your web page to use to connect to
the application module in the Business Components project and choosing Configuration.
Related topics

Adding XSQL Tags
25-67
Web Start Information
Use this page to specify Java Web Start information to document in the JNLP file.
Title
Enter the title of your application or applet to document in the JNLP file.
Description
Enter the description of your application or applet to document in the JNLP file.
Vendor
Enter the vendor of your application or applet to document in the JNLP file.
Click Finish to generate the files required to deploy your application or applet to the web server.
Related topics

Creating a Web Start JNLP Definition for Applets and Applications
25-68
Java Web Start Wizard - Welcome
Use the Java Web Start Wizard to add a Java Web Start .jnlp file to your project. This wizard
assumes you have already created a simple archive that you will deploy. Use this wizard to
create a JNLP file and web.xml file that you can use with your application or applet project to
run and deploy Java applications. Java Web Start is an application deployment software
developed by Sun Microsystems that lets you maintain Java applications on the web server,
while users download and run them on their client machines.
Before you begin, make sure you have created your jar file and that you know in which class
the main function can be found, as you will be asked to specify this.

Clear this checkbox to skip the Welcome page when you use the Java Web Start Wizard.
Related topics

25-69
Application Information
Use this page to specify properties of the JNLP file that determine how your application or
applet should be run by Java Web Start.
Name
Enter the name of your application or applet. This is the name of the JNLP and HTML
files.
Jar File
Enter the name and location of the jar file that you want to deploy or click Browse to
select it. Although the wizard only supports one jar file, you can load multiple jar files in
the <resources> area of the jnlp file that is created. However, a best practice is to have
all your class files jarred up for ease of use.
Main Class
Enter the class that you want to use to run your application or click Browse to select it.
The class should contain the main() method when you want to run as an application or it
should be the applet class when you want to run as an applet.
Create Homepage
Check to create a default HTML page for the application or applet.
Allow Offline Usage
Check to allow users to download the jar file and run the application or applet when not
connected to the Internet.
Allow all Permissions
Check to exceed normal applet permissions when the application or applet is run. This
option requires a digital signature. Refer to the Java Web Start information from Sun
Microsystems available at http://java.sun.com/products/javawebstart/.
Related topics

25-70
UIX XML and UIX JSP Pages Reference
❍ bc4juix:table
❍ bc4juix:styledText
❍ bc4juix:navigationBar
❍ bc4juix:renderValue
❍ bc4juix:tableDetail
❍ bc4juix:addTableRow
❍ bc4juix:inputRender
❍ bc4juix:labelStyledText
❍ uix:addTableRow
❍ uix:body
❍ uix:borderLayout
❍ uix:bottom
❍ uix:breadCrumbs
❍ uix:button
❍ uix:cellFormat
❍ uix:checkBox
❍ uix:choice
❍ uix:column
❍ uix:columnFooter
❍ uix::columnHeaderStamp
❍ uix:contentFooter
❍ uix:dateField
❍ uix:document
❍ uix:end
❍ uix:fileUpload
❍ uix:flowLayout
❍ uix:footer
26-1
❍ uix:form
❍ uix:formValue
❍ uix:globalButton
❍ uix:globalButtonBar
❍ uix:globalButtons
❍ uix:globalHeader
❍ uix:header
❍ uix:hideShow
❍ uix:image
❍ uix:inlineMessage
❍ uix:innerBottom
❍ uix:innerEnd
❍ uix:innerLeft
❍ uix:innerRight
❍ uix:innerStart
❍ uix:innerTop
❍ uix:labeledFieldLayout
❍ uix:leading
❍ uix:leadingFooter
❍ uix:left
❍ uix:link
❍ uix:list
❍ uix:lovField
❍ uix:messageBox
❍ uix:messageStyledText
❍ uix:multipleSelection
❍ uix:navigationBar
❍ uix:option
❍ uix:pageButtonBar
❍ uix:pageLayout
26-2
❍ uix:radioButton
❍ uix:radioGroup
❍ uix:rawText
❍ uix:renderingContext
❍ uix:resetButton
❍ uix:right
❍ uix:rowLayout
❍ uix:separator
❍ uix:shuttle
❍ uix:sideNav
❍ uix:singleSelection
❍ uix:sortableHeader
❍ uix:spacer
❍ uix:stackLayout
❍ uix:start
❍ uix:styledText
❍ uix:styleSheet
❍ uix:submitButton
❍ uix:switcher
❍ uix:tabBar
❍ uix:table
❍ uix:tableLayout
❍ uix:tableSelection
❍ uix:textInput
❍ uix:tip
❍ uix:top
❍ uix:totalRow
❍ uix:trailing
❍ uix:trailingFooter
❍ uix:train
26-3
❍ uix:buildTree
❍ uix:case
❍ uix:cobranding
❍ uix:columnHeader
❍ uix:contentContainer
❍ uix:contents
❍ uix:copyright
❍ uix:corporateBranding
❍ uix:dataScope
❍ uix:date
❍ uix:decimal
❍ uix:largeAdvertisement
❍ uix:location
❍ uix:mediumAdvertisement
❍ uix:messagePrompt
❍ uix:onBlurValidater
❍ uix:onSubmitValidater
❍ uix:pageHeader
❍ uix:privacy
❍ uix:productBranding
❍ uix:quickSearch
❍ uix:ref
❍ uix:regExp
❍ uix:tableDetail
❍ uix:tabs
❍ uix:wml
❍ xsql:delete-request
❍ xsql:dml
❍ xsql:include-owa
26-4
❍ xsql:include-param
❍ xsql:include-request-params
❍ xsql:include-xml
❍ xsql:include-xsql
❍ xsql:insert-param
❍ xsql:insert-request
❍ xsql:query
❍ xsql:ref-cursor-function
❍ xsql:set-cookie
❍ xsql:set-page-param
❍ xsql:set-stylesheet-param
❍ xsql:update-request
❍ xsql:set-session-param
❍ View Object - Show data Tag
❍ View Object - Update data Tag
26-5
<bc4juix:Table>
Binds a table to the datasource automatically.
JSP Syntax
<bc4juix:Table
[ alternateText="string" ]
[ destination="URI" ]
[ formSubmitted="true | false" ]
[ height="numberCharactersHigh" ]
[ width="numberCharactersWide" ]
[ name="string" ]
[ nameTransformed="true | false" ]
[ proxied="true | false" ]
[ summary="string" ]
[ text="string" ]
[ value="rowNumber" ]>
JSP content
</bc4juix:Table>
Example
The example below creates a table to display data from the "ds1" datasource.
<bc4juix:Table width="100%" datasource="ds1" >

<uix:columnHeader>
<uix:styledText textBinding="Name"/>
</uix:columnHeader>
<jbo:DefinitionIterate id="dsAttributes" datasource="ds1" >

<uix:styledText textBinding="<%=dsAttributes.getName()%>" />
</jbo:DefinitionIterate>
<uix:formValue name="RowKey" valueBinding="RowKey" />
</bc4juix:Table>
Description
The <bc4juix:Table> tag is a convenience tag that initializes itself automatically from the
26-6
information in the datasource and view object.
If you need to have more control over the table properties, use the non-BC4J version of this
tag, <uix:table> and set the attributes.
Attributes
● datasource—the datasource id that you want to retrieve from the database, as defined in
the <jbo:dataSource> data tag.
● alternateText—optional, the text to display inside an empty table.
● destination—optional, the base destination for all links generated by the table.
● formSubmitted—optional, whether or not to use form submission in the links generated
by the table's navigation bars.
● height—optional, the number of characters high of the table.
● width—optional, the number of characters wide of the table.
● name—optional, the name used to identify the table in client-to-client or client-to-server
events.
● nameTransformed—optional, whether or not <bc4juix:Table> tag should provide any
name transformation when rendering data controls. Valid values are true and false. By
default, the names are transformed.
● proxied—optional, whether or not the table should include JavaScript proxy code when
rendering on the client. Valid values are true and false
● summary—optional, the summary of the table's purpose and structure for user agents
rendering to non-visual media. If this attribute is not provided, the value of the text
attribute will be used.
● text—optional, the character string that will display as the title above the table.
● value—optional, the first currently visible row in the set of data which is displayed by the
table. It defaults to 1.
26-7
<bc4juix:StyledText>
Binds styled text to the datasource automatically.
JSP Syntax
<bc4juix:StyledText
[ styleClass="CSS className" ]
[ accessKey="character" ]
[ labeledNodeId="string" ]
/>
Example
The example below displays items from the datasource to which it is bound, as styled text.
<bc4juix:StyledText datasource="Orders" dataitem="Id" />
Description
The <bc4juix:StyledText> tag is a convenience tag that initializes itself automatically from the
information in the datasource and view object.
If you need to have more control over the styled text properties, use the non-BC4J version of
this tag, <uix:StyledText> and set the attributes.
Attributes
to retrieve in your page.
● styleClass—optional, the CSS classname.
● accessKey—optional, the character used to gain quick access to the link on this
<bc4juix:StyledText> tag. This attribute is sometimes referred to as the hotkey or
mnemonic. The character specified by this attribute must exist in the text attribute of this
<bc4juix:StyledText> tag. If it does not, the user will receive no visual indication of the
26-8
existence of the accessKey. If the same access key appears in multiple locations in the
same page of output, the rendering user agent will cycle among the elements accessed
by the similar keys.
● destination—optional, the URI this text should reference. This attribute provides a
shortcut, however the same effect can be achieved by wrapping the text inside of a link.
● labeledNodeId—optional, the ID of the UINode that this styledText is acting as a label
for. When used in conjunction with the accessKey attribute, the user pressing the access
key will move keyboard focus to the UINode specified by labeledNodeId. In addition,
even when access keys are not used, using this attribute to specify the logical
relationship between a UINode and its label can improve the accessibility of your UI.
26-9
<bc4juix:NavigationBar>
Binds the navigation bar to the datasource automatically.
JSP Syntax
<bc4juix:NavigationBar
/>
Example
The example below creates a navigation bar that allows a user to navigate through records in
the datasource named "Orders".
<bc4juix:NavigationBar datasource="Orders" />
Description
The <bc4juix:NavigationBar> tag is a convenience tag that initializes itself automatically from
the information in the datasource and view object.
If you need to have more control over the navigation bar properties, use the non-BC4J version
of this tag, <uix:NavigationBar> and set the attributes.
Attributes
● datasource—optional, the datasource id that you want to retrieve from the database, as
defined in the <jbo:dataSource> data tag.
26-10
<bc4juix:RenderValue>
Displays data of special data types, such as images, audio, or video, using a field render
specific to the data object type.
JSP Syntax
<bc4juix:RenderValue
dataitem="attributename"
/>
Example
The example below displays an image from the datasource.
<bc4juix:RenderValue datasource="Orders" dataitem="Image" />
Description
The <bc4juix:RenderValue> tag is primarily of use when you need to display rendered data of a
complex object type into your page such as a video or image file. In that case, the render for
the object may display a URL for the file.
Attributes
to retrieve in your page.
26-11
<bc4juix:TableDetail>
Causes the detail column from the datasource to be displayed.
JSP Syntax
JSP content
</bc4juix:TableDetail>
Example
The example below displays the detail from the datasource:
<jbo:AttributeIterate id="dsAttributes2" datasource="ds1" >
<uix:labeledFieldLayout columns="1" width="100%">
<bc4juix:LabelStyledText datasource="ds1" dataitem="Id1" />
<bc4juix:RenderValue datasource="ds1" dataitem="Id1" />
</bc4juix:TableDetail>
Description
The <bc4juix:TableDetail> tag is a BC4J convenience tag used to stamp below every table row
that is disclosed. The tag is used inside a <bc4juix:Table> tag. Adding a detail child will
automatically cause the detail column to be displayed.
The <bc4juix:TableDetail> tag has no attributes.
26-12
<bc4juix:AddTableRow>
Renders a special TableRow which lets users add rows of data to the datasource.
JSP Syntax
<bc4juix:AddTableRow
[ text="string" ]
[ rows="numberRows" ]
[ destination="URI" ] >
JSP content
</bc4juix:AddTableRow>
Example
The example below creates a button with the label, "Create 5 New Rows." When a user clicks
the button, five rows will be added to the table.
<bc4juix:AddTableRow text="Create 5 New Rows" rows="5" />
Description
The <bc4juix:AddTableRow> tag is a convenience tag. Wen when used inside a

<bc4juix:table> tag, it causes a special TableRow to be rendered which lets users click on a
button to add one or more rows of data. To use the <bc4juix:AddTableRow> tag, set it as the
columnFooter child of the <bc4juix:table> tag.
There are two customizations you can make to the <bc4juix:AddTableRow> tag. The text of the
button can be customized. By default, the button will display a localized version of the text "Add
Another Row". However, after setting the rows property of the <bc4juix:AddTableRow> tag to a
value greater than one, the button will display the text "Add 'X' Row(s)" where 'X' is the number
of rows. If this is not satisfactory, you can change the button text altogether by setting the text
property to the desired text.
The other customization is the destination of the button when clicked. By default, the
destination will use either form submission or URL arguments, depending on which is turned on
in the parent table. If form submission is used, the <bc4juix:AddTableRow> tag will submit the
table's form with an "event" form value set to "addRows", a "source" form value set to the name
of the table, and a "size" form set to the number of rows to add. If URL argument links are
used, the same three keys and values will be sent as parameters.
26-13
If the standard destinations are not suitable, you can override the destination by setting the
destination property of the <bc4juix:AddTableRow> tag to the desired value.
Finally, in the rare cases where a table needs the ability to add rows and total columns as well,
you can use both an <bc4juix:AddTableRow> tag and <bc4juix:totalRow> tag together. To do
this, create and configure both tags, then add the <bc4juix:totalRow> tag as an indexed child of
the <bc4juix:AddTableRow> tag. Then add the <bc4juix:AddTableRow> tag as the
columnFooter child as usual.
Attributes
● text—optional, the character string that will display on the button.

● rows—optional, the number of rows to be added.
● destination—optional, the URI this button should reference.
26-14
<bc4juix:InputRender>
Renders an input field from a datasource to a page.
JSP Syntax
<bc4juix:InputRender
/>
Example
The example below displays an input field from the datasource.
<bc4juix:InputRender datasource="Orders" dataitem="Id" />
Description
The <bc4juix:InputRender> tag renders an input field from a datasource to a page, that allows
users to edit the data.
Attributes
● dataitem—optional, the name of the specific view object attribute (in the datasource) that
you want to retrieve in your page.
26-15
<uixbc4j:LabelStyledText>
Binds styled text labels to the datasource automatically.
JSP Syntax
<uixbc4j:LabelStyledText
[ labeledNodeId="string" ]
/>
Example
The example below displays items from the datasource to which it is bound, as styled text.
<uixbc4j:LabelStyledText datasource="Orders" dataitem="Id" />
Description
The <uixbc4j:LabelStyledText> tag is a convenience tag that initializes itself automatically from
the information in the datasource and view object.
Attributes
● datasource—optional, the datasource id that you want to retrieve from the database, as
defined in the <jbo:dataSource> data tag.
● dataitem—optional, the name of the specific view object attribute (in the datasource) that
you want to retrieve in your page.
<bc4juix:LabelStyledText> tag. This attribute is sometimes referred to as the hotkey or
mnemonic. The character specified by this attribute must exist in the text attribute of this
<bc4juix:LabelStyledText> tag. If it does not, the user will receive no visual indication of
the existence of the accessKey. If the same access key appears in multiple locations in
the same page of output, the rendering user agent will cycle among the elements
accessed by the similar keys.
26-16
● labeledNodeId—optional, the ID of the UINode that this LabelStyledText is acting as a
label for. When used in conjunction with the accessKey attribute, the user pressing the
access key will move keyboard focus to the UINode specified by labeledNodeId. In
addition, even when access keys are not used, using this attribute to specify the logical
relationship between a UINode and its label can improve the accessibility of your UI.
26-17
<uix:addTableRow>
Causes a special TableRow to be rendered which lets users click a button to add one or more
rows of data.
JSP Syntax
<uix:addTableRow
[ text="string" ]
[ destination="URI" ]>
JSP content
</uix:addTableRow>
Example
The example below creates a button with the label, "Create 5 New Rows." When a user clicks
the button, five rows will be added to the table.
<uix:addTableRow text="Create 5 New Rows" rows="5" />
Description
The <uix:addTableRow> tag, when when used inside a <uix:table> tag, causes a special
TableRow to be rendered which lets users click on a button to add one or more rows of data.
To use the <uix:addTableRow> tag, set it as the columnFooter child of the <uix:table> tag.
There are two customizations you can make to the <uix:addTableRow> tag. The text of the
button can be customized. By default, the button will display a localized version of the text "Add
Another Row". However, after setting the rows property of the <uix:addTableRow> tag to a
value greater than one, the button will display the text "Add 'X' Row(s)" where 'X' is the number
of rows. If this is not satisfactory, you can change the button text altogether by setting the text
property to the desired text.
in the parent table. If form submission is used, the <uix:addTableRow> tag will submit the
table's form with an "event" form value set to "addRows", a "source" form value set to the name
of the table, and a "size" form set to the number of rows to add. If URL argument links are
used, the same three keys and values will be sent as parameters.
26-18
destination property of the <uix:addTableRow> tag to the desired value.
you can use both an <uix:addTableRow> tag and <uix:totalRow> tag together. To do this,
create and configure both tags, then add the <uix:totalRow> tag as an indexed child of the
<uix:addTableRow> tag. Then add the <uix:addTableRow> tag as the columnFooter child as
usual.
Attributes

● rows—optional, the number of rows to be added.
26-19
<uix:body>
Creates the container for the body of a document.
JSP Syntax
<uix:body
[ onLoad="event handler" ]
[ onUnload="event handler" ] >
JSP content
</uix:body>
Example
The example below displays the text "Sample text in document body" within the body of the
document along with onload and onunload JavaScript event handlers.

<%@ page contentType="text/html;charset=WINDOWS-1252"%>
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=WINDOWS-1252">
<TITLE>
Hello World
</TITLE>
</HEAD>
<uix:body onLoad="alert(\"Document loaded\")" onUnload="alert(\"document unloaded\")" >
<uix:styledText text="Sample text in document body"> </uix:styledText>
</uix:body>
</HTML>
Description
The <uix:body> tag creates the container for the body of a document. This tag is required as
the root of all content and is automatically added when you create a JSP UIX page in
JDeveloper. This tag is the only method for attaching onLoad and onUnload handlers.
Attributes
● onLoad—optional, an onload JavaScript event handler.

● onUnload—optional, an onunload JavaScript event handler.
26-20
26-21
<uix:borderLayout>
Lays out all of its indexed children consecutively in its middle, and supports twelve other named
children.
JSP Syntax
<uix:borderLayout>
JSP content
</uix:borderLayout>
Example
The example below shows the syntax for the <uix:borderLayout> tag with multiple named
children.

<uix:document>
<uix:body>
<uix:borderLayout>
<uix:top><uix:styledText text="top"/></uix:top>
<uix:bottom><uix:styledText text="bottom" /></uix:bottom>
<uix:right><uix:styledText text="right"/></uix:right>
<uix:left><uix:styledText text="left"/></uix:left>
<uix:innerTop><uix:styledText text="inner top"/></uix:innerTop>
<uix:innerBottom><uix:styledText text="inner bottom"/></uix:innerBottom>
<uix:innerLeft><uix:styledText text="inner left"/></uix:innerLeft>
<uix:innerRight><uix:styledText text="inner right"/></uix:innerRight>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:borderLayout> tag is a layout tag which lays out all of its indexed children
consecutively in its middle, and supports twelve other named children: top, bottom, left, right,
start, end, innerTop, innerBottom, innerRight, innerStart, innerLeft, and innerEnd. You should
use only one of left/right or start/end tags for each of the inner and outer sides, in any one
container, but if both are used, the left/right tags are applied. The inner named children mirror
the layout of the outer named children, just inset immediately inside of the outer children.
26-22
The <uix:borderLayout> tag has no attributes.
26-23
<uix:bottom>
Specifies the border to be rendered below the indexed children and any innerBottom child.
JSP Syntax
<uix:bottom>
JSP content
</uix:bottom>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:bottom> tag specifies the border to be rendered below the indexed children and any
innerBottom child. This tag is used inside of a <uix:borderLayout> tag.
The <uix:bottom> tag has no attributes.
26-24
<uix:breadCrumbs>
Inserts a trail of links back to the site home page.
JSP Syntax
<uix:breadCrumbs
[ orientation="vertical | horizontal" ]>
JSP content
</uix:breadCrumbs>
Example
The example below displays the links back to Steps 1, 2, and 3 on the "Step 4" page.
<uix:breadCrumbs orientation="horizontal">
<uix:link text="Step 1" destination="UixBrowseEdit1.jsp" />
</uix:breadCrumbs>
Description
The <uix:breadCrumbs> tag inserts a trail of links back to the site home page. BreadCrumbs
are used on each page in hierarchical site layouts to provide links for the path back to the root
page of the hierarchy.
Attributes
● orientation—optional, whether to put links on the same line or indented and on new
lines. Valid values are horizontal and vertical. If the orientation is horizontal, successive
links will be put on the same line. If the orientation is vertical, successive links will be put
on a new line, and indented from their parents. The default value is horizontal. Vertical
BreadCrumbs should be used only when the text for the links is known to be very long
and likely to cause undesirable scrolling.
26-25
<uix:button>
Insert a button to trigger some action in response to a click.
JSP Syntax
<uix:button
[ name="buttonName" ]
text="string"
[ selected="true | false" ]
[ disabled="true | false" ]
[ longDesc="string" ]
[ onBlur="event handler" ]
[ targetFrame="frameName" ]
[ onFocus="event handler" ]
/>
Example
The example below displays a button with the label "Home" which will display the destination
Home.jsp when clicked and appear selected on screen.
<uix:button destination="Home.jsp" text="Home" selected="true" />
Description
The <uix:button> tag lets you insert a push button in your application which allows the user to
trigger some action in response to a click. The button fires an "onclick" event when it is
activated. A button will not render any child nodes. It must be an empty element; it may not
contain any child elements or text.
Attributes
● name—optional, the name used to identify the button.

● destination—optional, the URI this button should link to.
● text—the character string that will display as a label on the button.
● selected—optional, whether the link should be considered selected.
26-26
● accessKey—optional, the character used to select the button. This attribute is sometimes
referred to as the hotkey or mnemonic. The character specified by this attribute must
exist in the text attribute of this Button instance. If it does not, the user will receive no
visual indication of the existence of the accessKey. If the same access key appears in
multiple locations in the same page of output, the rendering user agent will cycle among
the elements accessed by the similar keys.
● disabled—optional, whether the button should be considered disabled.
● longDesc—optional, a long description associated with this button, used to clarify it
purpose.
● onBlur—optional, the event handler for the link losing the focus.
● targetFrame—optional, the target frame for the link.
● onFocus—optional, the event handler for the link gaining the focus.
26-27
<uix:cellFormat>
Adds formatting, such as vertical alignment, width, or colspan, to cells in a <uix:rowLayout> tag.
JSP Syntax
<uix:cellFormat
[ hAlign="Center | Left | Right | Start | End" ]
[ rowSpan="numberRows" ]
[ columnSpan="numberColumns" ]
[ vAlign="Middle | Top | Bottom" ]
[ wrappingDisabled="true | false" ]>
JSP content
</uix:cellFormat>
Example
The example below shows how the <uix:cellFormat> tag would be used to format cells.
<uix:cellFormat hAlign="center" rowSpan="2"

columnSpan="2" vAlign="middle"
wrappingDisabled="true" >
MiddleColumn
</uix:cellFormat>
Description
The <uix:cellFormat> tag is used to format cells in a <uix:rowLayout> tag. It is a container of

other layout tags which allows its contents to take additional formatting, such as vertical
alignment, width, or colspan.
Attributes
● hAlign—optional, the horizontal alignment of the grid row elements. Valid values are
center, left, right, start, and end.
● height—optional, the preferred height of the enclosed layout elements.
● rowSpan—optional, the number of cells high of the child layout element.
● columnSpan—optional, the number of cells wide of the child layout element.
26-28
● vAlign—optional, the vertical alignment of the grid row elements. The acceptable values
are middle, top, and bottom.
● width—optional, the preferred width of the enclosed layout elements.
● wrappingDisabled—optional, whether automatic text wrapping should be disabled for
this cell.
26-29
<uix:checkBox>
Creates a standard browser input check box.
JSP Syntax
<uix:checkBox
[ text="buttonName" ]
value ="string"
[ checked="true | false" ]
name="string"
[ readOnly="true | false" ]
[ selectedValue="string" ]
/>
Example
The example below displays a form with two check boxes. The second check box is selected.

<uix:document>
<uix:body>
<uix:form name="form1" >
<uix:checkBox text="this is non-checked checkbox" value="100" checked="false" />
<uix:checkBox text="this is checked checkbox" value="200" checked="true" />
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:checkBox> tag maps to a standard browser input check box, which toggles between
selected and unselected states. The text defined by the checkbox attribute will be displayed as
the checkbox label.
It must be an empty element. It may not contain any child elements or text.
26-30
Attributes
● text—optional, the character string that will display as a label on the check box.
● value—the string value to be sent when this check box is selected from its group.
● checked—optional, whether the check box should be considered selected.
● name—the name used to identify the check box.
● disabled—optional, whether the check box should be considered disabled.
● readOnly—optional, whether the check box should be editable.
● accessKey—optional, the character used to select the check box. This attribute is
sometimes referred to as the hotkey or mnemonic. The character specified by this
attribute must exist in the text attribute of this check box instance. If it does not, the user
will receive no visual indication of the existence of the accessKey. If the same access
key appears in multiple locations in the same page of output, the rendering user agent
will cycle among the elements accessed by the similar keys.
● selectedValue—optional, the the string value for the selected checkbox in the list.
26-31
<uix:choice>
Displays a menu-style list of items from which the user can select.
JSP Syntax
<uix:choice
name="string"
[ required ="Yes | No" ]
[ selectedIndex="selectedItemNumber" ]
[ selectedValue="string" ]>
JSP content
</uix:choice>
Example
The example below displays a menu with two choices, choice1 and choice2.

<uix:document>
<uix:body>
<uix:choice name="MyChoice" >
<uix:option text="choice1" value="100" />
</uix:choice>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:choice> tag creates a menu-style control, which allows the user to select a single
value from a list of items. The choice control contains any number of<option>elements, each of
which represents an available option that the user may select. The choice tag is similar to the
list tag, with the restriction that the choice control only allows a single item to be selected at a
26-32
time.
Attributes
● name—the name used to identify the choice control.

● required—whether the choice requires a non-empty value. Two values are allowed: Yes
and No. Yes causes user input in this choice to be required. The default is No, which
causes user input to be not required.
● disabled—optional, whether the list should be considered disabled.
● readOnly—optional, whether the list should be editable
● selectedIndex—optional, the value of the index of the selected item in the list. Use the
selectedIndex attribute to specify which list item appears selected. The selectedIndex
attribute is zero-based.
● selectedValue—optional, the the string value for the selected item in the list. Use either
the selectedValue attribute or the selectedIndex attribute to specify which item appears
selected.
26-33
<uix:column>
Supports encapsulating all of the rendering and formatting information for a <uix:table> tag
column into a single tag.
JSP Syntax
<uix:column
id="columnIdentifier">
JSP content
</uix:column>
Example
<uix:column id="call1" />
Description
The <uix:column> tag supports encapsulating all of the rendering and formatting information for
a <uix:table> tag column into a single node. The <uix:column> tag should only be used as the
indexed child, i.e. data column stamp, of a <uix:table> tag.
The <uix:column> tag is useful if you wish to encapsulate all the information describing a
column into a single entity, rather than spreading it out across the indexed child (column
stamp), header stamp, header format, header data, and column format objects set globally on
the table. The <uix:column> tag will not render anything itself; however, its own indexed
children will be stamped down each cell of that table column
The <uix:column> tag also allows you to set its own column format, column header format,
column header data, and column header stamp. If specified, these will override the values for
formats and stamps attributed to the <uix:table> tag itself. If they are not specified, the
<uix:table> tag's own formats and stamps will be used, as before.
You can use <uix:column> tags for any, all, or none of the columns in the <uix:table> tag. You
can also set the rendered flag on a <uix:column> tag to hide it from view for a given render.
Attributes
● id—The name used to identify the object instance in the specified scope's namespace,
and also the scripting variable name declared and initialized with that object reference.
The name specified is case sensitive and shall conform to the current scripting language
26-34
variable-naming conventions.
26-35
<uix:columnFooter>
Used to render the table footer inside of a <uix:table> tag.
JSP Syntax
<uix:columnFooter>
JSP content
</uix:columnFooter>
Example
The example below shows how the <uix:columnFooter> tag is used to render the table footer,
"footer text."

<uix:document>
<uix:body>
<uix:form name="form1">
<uix:table name="table 1" >
<uix:singleSelection text="Single selection" >
<uix:button name="button1" destination="SingleSelectionSample.jsp"
text="My Button1" />
<uix:columnFooter>
<uix:styledText text="footer text" ></uix:styledText>
</uix:columnFooter>
</uix:table>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:columnFooter> tag is used to render the table footer. This element is used as a
wrapper tag inside of a <uix:table> tag.
There are some cases where it is appropriate to summarize the data in a table in a special
section located at the bottom of the data area. This is known as the column footer, and it is a
named child of the table. However, unlike the column header stamp and row header stamp, the
26-36
column footer is not a stamp. It is rendered only once at the bottom of the table instead of being
stamped across every column. This is by design; most column footers summarize table-wide
statistics or actions rather than per-column actions. In fact, there are two special UINodes that
are intended to be used only as column footers: <addTableRow> and <totalRow>.
The <uix:columnFooter> tag has no attributes.
26-37
<uix:columnHeaderStamp>
Renders each column header inside a <uix:table> tag.
JSP Syntax
JSP content
</uix:columnHeaderStamp>
Example
The example below shows how the <uix:columnHeaderStamp> tag is used to render the
column header.
<uix:styledText textBinding="LABEL"/>
Description
The <uix:columnHeaderStamp> tag is used as a template to render each column header. This
tag is used as a wrapper inside of a <uix:table> tag.
26-38
<uix:contentFooter>
Creates a horizontal separator with a curved right corner.
JSP Syntax
<uix:contentFooter
[ width="numberCharactersWide" ]>
JSP content
</uix:contentFooter>
Example
The example below displays a horizontal line that is 25 characters wide, with a curved right
corner.
<uix:contentFooter width="25" />
Description
The <uix:contentFooter> tag creates a horizontal separator with a curved right corner. It is used
to distinguish action buttons from action/navigation buttons, or page level action/navigation
buttons from local content.
Attributes
● width—optional, the number of characters wide of the content footer.
26-39
<uix:dateField>
Creates a text field for entering dates and a button for selecting dates from a calendar.
JSP Syntax
<uix:dateField
name="string"
[ maximumLength=numberCharactersLong" ]
[ required ="Yes | No" ]
[ columns="numberColumns" ]
[ onChange="event handler" ]
[ onSelect="event handler" ]>
JSP content
</uix:dateField>
Example
The example below displays a field for entering a date and a button labeled "Select Date" that
opens a calendar from which the user can select a date.

<uix:document>
<uix:body>
<uix:dateField name="MyDate" text="Select Date" />
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:dateField> tag creates a text field for entering dates and a button for selecting dates
from a calendar. The name property is required and must be set for the validation to work
correctly. In addition, the HTML implementation takes advantage of several JavaScript libraries
26-40
and Java Server Pages which must be installed correctly for the dateField to function. The JSP
to use is specified by the destination property, and a JSP calendarDialog.jsp is provided to
provided to act as the implementation of the destination property.
Attributes
● name—the name used to identify the button.

● text—optional, the character string that will display as a label on the button.
● maximumLength—optional, the maximum number of characters of the date field.
● required—whether the date value will be a required field to submit the form. Two values
are allowed: Yes and No. The default is No.
● columns—optional, the number of columns to display in the date field. If no value is
specified, a default of 30 columns is used.
● readOnly—optional, whether the button should be editable.
● onChange—optional, the event handler for when the value in the date field is changed.
● onSelected—optional, the event handler for the selected link.
26-41
<uix:document>
Generates the root tags for a page.
JSP Syntax
<uix:document>
JSP content
</uix:document>
Example
The example below shows the <uix:document> tag as the root tag for a page.

<uix:document>
<uix:body>
</uix:choice>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:document> tag generates the root tags for a page. For example, in HTML, this tag
generates the<html> tag. It must be used as the outermost element of a Java-built tree.
Pages built with XML UIX files do not have to use it, as the UIX Controller will add this tag
automatically, but developers who want more control over the generated output, or want to use
the metaContainer, are free to use it explicitly.
The <uix:document> tag has no attributes.
26-42
<uix:end>
Specifies the end named child container in a page layout or the border to be rendered to the
right of the indexed children in a border layout.
JSP Syntax
<uix:end>
JSP content
</uix:end>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
<uix:start><uix:styledText text="start"/></uix:start>
<uix:end><uix:styledText text="end" /></uix:end>
<uix:innerStart><uix:styledText text="innerStart"/></uix:innerStart>
<uix:innerEnd><uix:styledText text="innerEnd"/></uix:innerEnd>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:end> tag specifies the border to be rendered to the right of the indexed children and
between any top and bottom children, if the reading direction is left-to-right; otherwise, on the
left of the indexed children. This tag is used inside of a <uix:borderLayout> tag.
The <uix:end> tag has no attributes.
26-43
<uix:fileUpload>
Adds a widget that can be used to upload a file.
JSP Syntax
<uix:fileUpload
name="string"
/>
Example
The example below shows a form that can upload a file named MyFile.

<uix:document>
<uix:body>
<uix:fileUpload name="MyFile" columns="40" />
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:fileUpload> tag adds a widget that can be used to upload a file. Any form that contains
this tag must have the usesUpload attribute set to true.
Attributes
● name—the name used to identify the element in client-to-client or client-to-server events.

● columns—optional, the number of columns to display in the text control. If no value is
specified, a default of 30 columns is used. Columns are measured in character width.
26-44
<uix:flowLayout>
Lays out each of its children horizontally, wrapping as needed.
JSP Syntax
<uix:flowLayout>
JSP content
</uix:flowLayout>
Example
The example below displays four inline messages laid out horizontally.

<uix:document>
<uix:body>
<uix:flowLayout name="flow1" >
<uix:inlineMessage message="message1" prompt="Prompt#1:" tip="This is message #1" />
</uix:flowLayout>
</uix:body>
</uix:document>
Description
The <uix:flowLayout> tag is a layout tag which will display each of its children horizontally,
wrapping as needed. Each pair of adjacent children will be separated by an optional separator
child.
The <uix:flowLayout> tag has no attributes.
26-45
<uix:footer>
Used at the bottom of pages to optionally display footer links.
JSP Syntax
<uix:footer>
JSP content
</uix:footer>
Example
The example below displays a footer with three links.
<uix:footer>
<uix:link text="Employees" destination="EmployeesView_Browse.jsp"/>
<uix:link text="Locations" destination="LocationsView_Browse.jsp"/>
<uix:link text="Managers" destination="ManagersView_Browse.jsp"/>
</uix:footer>
Description
The <uix:footer> tag should be used at the bottom of pages. It can optionally contain a series of
links, each defined by a link node.
The <uix:footer> tag has no attributes.
26-46
<uix:form>
Creates an HTML<form> element inside the page.
JSP Syntax
<uix:form
name="string"
[ usesUpload="true | false" ]
[ method="methodName" ]
[ onSubmit="event handler" ]
[ targetFrame="frameName" ]>
JSP content
</uix:form>
Example
The example below creates a form with two choice elements.

<uix:document>
<uix:body>
</uix:choice>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:form> tag creates an HTML<form> element inside the page.
Attributes
● name—the name used to identify the form.

● destination—optional, Sthe URI this form will deliver its data to. If not set, the form will
26-47
deliver its data back to the URI that delivered the page.
● usesUpload—optional, whether the form supports file upload.
● method—optional, the HTTP method used for submission; defaults to GET.
● onSubmit—optional, the JavaScript code to be called when the form is submitted.
● targetFrame—optional, the target frame for the form.
26-48
<uix:formValue>
Adds a value that will be submitted with a form, but not displayed.
JSP Syntax
<uix:formValue
name="string"
[ value ="string" ]
[ valueBinding="boundvalue" ]
/>
Example
The example below creates a form with a value that will be sent when the form is submitted.

<uix:document>
<uix:body>
<uix:formValue name="MyValue" value="this is my value" />
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:formValue> tag adds a value that will be submitted with a form, but not displayed to
the user.
Attributes
● name—the name used to identify the formValue in client-to-client or client-to-server

events.
● value—optional, the string value to be sent when the form is submitted. Use either the
value or valueBinding attribute, but not both.
● valueBinding—optional, a bound value.
26-49
26-50
<uix:globalButton>
Inserts a button to provide access to globally available functionality.
JSP Syntax
<uix:globalButton
text="buttonName"
destination="URI"
[ icon="graphicName" ]
[ source=URI ]
/>
Example
The example below creates a global button bar with two global buttons.
<uix:globalButtonBar>
<uix:globalButton text="Home" destination="Home.jsp" source="/images/home.gif" />
<uix:globalButton text="Help" destination="Help.jsp" source="/images/help.gif" />
</uix:globalButtonBar>
Description
The <uix:globalButton> tag lets you insert a button in your application to provide access to
functionality which should be globally available. A global button displays a link label as well as
an icon. It must be an empty element; it may not contain any child elements or text.
Attributes
● text—the character string that will display as a label on the button.

● destination—the URI this button should link to.
26-51
● icon—optional, a URI specifying the location of a fully processed target image. While the
source attribute must refer to a local resource, this URL is not processed further, and so
can refer to a remote server..
● source—the URI specifying the location of the image resource. This must currently be a
full path to a file on the local system.
exist in the text attribute of this GlobalButton instance. If it does not, the user will receive
no visual indication of the existence of the accessKey. If the same access key appears in
● disabled—optional, whether the link should be considered disabled.
● longDesc—optional, a long description associated with this link, used to clarify it
purpose.
● name—optional, the name used to identify the link as an anchor.
26-52
Displays a set of global buttons inserted with the <uix:globalButton> tag.
JSP Syntax
JSP content
Example
The example below creates a global button bar with two global buttons, Home and Help.
<uix:globalButton text="Home" destination="Home.jsp" source="home.gif" />
<uix:globalButton text="Help" destination="Help.jsp" source="help.gif" />
Description
The <uix:globalButtonBar> tag lays out a set of global buttons that are inserted with the
<uix:globalButton> tag.
The <uix:globalButtonBar> tag has no attributes.
26-53
<uix:globalButtons>
Wraps the global button region of the page.
JSP Syntax
<uix:globalButtons>
JSP content
</uix:globalButtons>
Example
The example below creates a global button bar with two global buttons.
<uix:globalButtons>
<uix:globalButton text="Home" destination="Home.jsp" source="/images/home.gif" />
<uix:globalButton text="Help" destination="Help.jsp" source="/images/help.gif" />
Description
The <uix:globalButtons> tag wraps the global button region of the page. This section typically
contains a <uix:globalButtonBar> tag. This tag is used as a wrapper tag inside of a
<pageLayout> tag.
The <uix:globalButtons> tag has no attributes.
26-54
<uix:globalHeader>
Adds a blue banner under the tabs that optionally can contain a series of links for site
navigation.
JSP Syntax
<uix:globalHeader
[ text="string" ]
[ selectedIndex="linkNumber" ]>
JSP content
</uix:globalHeader>
Example
The example below creates a banner with links for Home, Orders and Help. Orders is the
selected link.
<uix:pageHeader>
<uix:globalHeader text="Online Orders" / selectedIndex="1" >
<uix:link text="Home" destination="main.jsp" />
<uix:link text="Orders" destination="order.jsp" />
<uix:link text="Help" destination="Help.jsp" />
</uix:pageHeader>
Description
The <uix:globalHeader> tag, sometimes known as Level Two tabs, creates a blue banner
under the tab bar which can include a line of text. The banner can optionally include a series of
links, however both text and links cannot be included in the global header simultaneously.
Attributes
● text—optional, the character string that will display as text for this header.
● selectedIndex—optional, the value of the index of the selected link. Use the
selectedIndex attribute to specify which containee, in this case a tab, is active on the
page. The selectedIndex attribute is zero-based.
26-55
<uix:header>
Places a label and icon at the top of a section, and indents the contents.
JSP Syntax
<uix:header
[shortText="string"]
[text="string"]
[icon="URI"]
[size="numberTextSize"]>
JSP content
</uix:header>
Example
The example below creates a label and icon at the top of the Help section.
<uix:contents>
<uix:header text="Help" size="1" icon="/images/help.gif" />
</uix:contents>
Description
The <uix:header> tag places a label and icon at the top of a section, and then indents the
contents of the section.
The <uix:header> tag works closely with the <uix:quickLinks> tag if the quickLinksShown
attribute is specified in the <uix:pageLayout> tag. The <uix:quickLinks> tag places a link to all
top level headers under a given node, except the first header. When a <uix:quickLinks> tag is
present (or has been created with the quickLinksShown attribute of the<uix:pageLayout> tag)
the headers linked to also have a link to the top of the page as part of the header. To specify a
different link text from the default (which is the full text of the header), set the shortText attribute
on the <uix:header> tag to the desired text.
Attributes
● shortText—optional, the abbreviated text of the header, used in the QuickLinks control.
● text—optional, the character string that will display as text of this header.
26-56
● icon—optional, the URI for the image that appears as part of the header.
● size—optional, the size of this header. 0 is the largest, 2 is the smallest.
26-57
<uix:hideShow>
Toggles a group of UINodes between being disclosed or undisclosed.
JSP Syntax
<uix:hideShow
id="eventName"
[ disclosed="true | false" ]
[ disclosedText="true | false" ]
[ FormName="navigationBarName" ]
[ undisclosedText="true | false" ]
[ formSubmitted="true | false" ]>
JSP content
</uix:hideShow>
Example
The example below registers a UIX Component DataProvider and toggles a group of UINodes
between being disclosed or undisclosed:
<uix:dataScope id="ds2" >

<uix:contents>
<uix:hideShow id="hideShow" formSubmitted="true">
<uix:contents>
<uix:header text="Header">
<uix:contents>
<uix:header text="SubHeader"/>
</uix:contents>
</uix:header>
</uix:contents>
</uix:hideShow>
</uix:contents>
</uix:dataScope>
Description
The <uix:hideShow> tag provides a means of toggling a group of UINodes between being
disclosed or undisclosed. A <uix:hideShow> tag should be used to hide or show an entire
section, part of a section of information, or functionality within a page such as:
26-58
● show / hide more information
● show / hide details
● show / hide "section name"
● show / hide graph
● show / hide details of a table row
● simple / advance search
If the DISCLOSED attribute on the HideShow is set to false, the icon arrow will point sideways,
the text specified by the UNDISCLOSED_TEXT attribute will be rendered as a link, and the
children of the HideShow will not be rendered. If the DISCLOSED attribute on the HideShow is
set to true, the icon arrow will point down, the text specified by the DISCLOSED_TEXT attribute
will be rendered as a link, and the children of the HideShow will be rendered.
Clicking on either the icon or the text of the HideShow will send an event to the server. The
source of the event will be the HideShow's ID. The event will be either hide or show .
The ID attribute is used to specify the name which is used to identify the HideShow in client-
server events.
The DISCLOSED attribute toggles the HideShow's children between being disclosed or
undisclosed. This attribute may be set to Boolean.TRUE or Boolean.FALSE. By default, this
attribute will be FALSE.
The text of the HideShow comes from the DISCLOSED_TEXT and UNDISCLOSED_TEXT
attributes. In almost all cases, the DISCLOSED_TEXT should consist of the word "Hide" plus a
description of the HideShow's children, and the UNDISCLOSED_TEXT should consist of the
word "Show" plus a description of the children. The default values for these attributes are
"Hide" and "Show".
The FORM_SUBMITTED attribute causes the links generated by the HideShow to handle
events through form submission. In addition to event information, the state of each HideShow in
the form will be submitted through a parameter which is the concatenation of the HideShow's
ID, and the String "State". The default value for FORM_SUBMITTED is TRUE. The name of the
form to be submitted can be specified through the FORM_NAME attribute. If no name is
specified, the form to which the HideShow belongs will be used.
If the FORM_SUBMITTED attribute is set to FALSE, the links generated by the HideShow will
be URLs based on the DESTINATION attribute. If not destination is specified, the default URL
for the servlet will be used.
26-59
Attributes
● id—the name which is used to identify the <uix:hideShow> tag in client-server events.
● destination—optional, the base URL to which the hideShow link points.
● disclosed—optional, whether or not to disclose the children.
● disclosedText—optional, the text to display when the children are shown.
● formName—optional, the name of the form to which HideShow events should be
submitted .
● undisclosedText—optional, the text to display when the children are hidden.
● formSubmitted—optional, determines whether or not to use form submission in the
Hide/Show link.
26-60
<uix:image>
Inserts a specified image in the application page.
JSP Syntax
<uix:image
source="URI"
[ borderWidth="numberCharactersWide" ]
[ longDescURL="URL" ]
/>
Example
The example below displays an image named tools.gif which links to the tools.jsp page.
<uix:image source="/webapp/tools.gif" destination="/webapp/tools.jsp" />
Description
The <uix:image> tag lets you insert a specified image in a page; the image can also be a link.
The "alt" image tag can be set using the shortDesc attribute. The image tag must be an empty
element; it may not contain any child elements or text.
Attributes
● source—the URI specifying the location of the image resource. This must currently be a
full path to a file on the local system.
● destination—optional, the URI this image should link to. The same effect can be
achieved by wrapping the image inside of a link; this is only a shortcut.
● borderWidth—optional, the width of the border drawn around the image; defaults to zero.
● hAlign—optional, the horizontal alignment of the image. Valid values are center, left,
right, start, and end.
● height—optional, the number of characters high of the image.
26-61
● longDescURL—optional, a URL that specifies a link to a long description of the image.
This description should supplement the short description.
● width—optional, the number of characters wide of the image.
● accessKey—optional, the character used to select the image with the keyboard if the
image is a link. This attribute is sometimes referred to as the hotkey or mnemonic. The
character specified by this attribute must exist in the text attribute of this Button instance.
If it does not, the user will receive no visual indication of the existence of the accessKey.
If the same access key appears in multiple locations in the same page of output, the
rendering user agent will cycle among the elements accessed by the similar keys.
26-62
<uix:inlineMessage>
Inserts a component that wraps another, adding a label, and optionally an icon with a message.
JSP Syntax
<uix:inlineMessage
[ longDescURL="URI" ]
[ message="string" ]
[ messageType="error | warning | info | none" ]
[ prompt="string" ]
[ required="Yes | No | Default" ]
[ tip="string" ]
[ anchor="anchorTagName" ]
[ accessKey="character" ]>
JSP content
</uix:inlineMessage>
Example
The example below displays the message "an error occurred".
<uix:inlineMessage message="an error occurred" />
Description
The <uix:inlineMessage> tag inserts a component that wraps another, always adding a label,
and optionally adding an error, information, or warning icon with an explanatory message. It
can also receive a destination, which would be attached to the icon to link to further information.
The control can also be set to indicate the associated control requires user input.
Typically, the only indexed child will be a form element of some sort, but as many children as
necessary can be added and will be laid out as in a <uix:rowLayout> tag.
You can also add an "end" named child which will be rendered to the right of the form
elements.
The <uix:inlineMessage> tag is almost always placed directly inside <uix:tableLayout> tags.
When placed inside a <uix:tableLayout> tag, the labels and further content will line up; for
26-63
layout purposes, this tag can be considered equivalent to a specialization of a <uix:rowLayout>
tag. Like the <uix:rowLayout> tag, this tag can be used on its own.
Attributes
● longDescURL—optional, a URL to a page with more information about the message.

● message—optional, the error, warning, or informational text.
● messageType—optional, the type of the message; acceptable values are error, warning,
info, and none. Defaults to none.
● prompt—optional, the text string that displays as the prompt.
● required—optional, whether the associated control requires user input. Three values are
allowed: yes, no, and default. A visual indication will only be displayed if the value is set
to yes. This attribute does not affect client-side or server-side validation, which must be
done independently. This simply affects the displayed user interface .
● targetFrame—optional, the target frame for the URL, if any.
● tip—optional, the tip text associated with the control.
● vAlign—optional, the vertical alignment of the prompt and other contents. The
acceptable values are middle, top, and bottom.
● anchor—optional, specifies the name of an anchor tag. This tag will uniquely identify this
inline message across a single page. The destinations of links in a MessageBox would
reference this anchor.
● accessKey—optional, the character used to select the link. This attribute is sometimes
exist in the text attribute of this link instance. If it does not, the user will receive no visual
indication of the existence of the accessKey. If the same access key appears in multiple
locations in the same page of output, the rendering user agent will cycle among the
elements accessed by the similar keys.
26-64
<uix:innerBottom>
Specifies the border to be rendered below the indexed children and above any bottom child.
JSP Syntax
<uix:innerBottom>
JSP content
</uix:innerBottom>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:innerBottom> tag specifies the border to be rendered below the indexed children and
above any bottom child. This tag is used inside of a <uix:borderLayout> tag.
The <uix:innerBottom> tag has no attributes.
26-65
<uix:innerEnd>
Specifies the border to be rendered to the right of the indexed children.
JSP Syntax
<uix:innerEnd>
JSP content
</uix:innerEnd>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:innerEnd> tag specifies the border to be rendered to the right of the indexed children,
to the left of any right-appearing child and between any top and bottom children, if the reading
direction is left-to-right; otherwise on the left to the right of any left-appearing child. This tag is
used inside of a <uix:borderLayout> tag.
The <uix:innerEnd> tag has no attributes.
26-66
<uix:innerLeft>
Specifies the border to be rendered to the left of the indexed children and to the right of any left
child.
JSP Syntax
<uix:innerLeft>
JSP content
</uix:innerLeft>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:innerLeft> tag specifies the border to be rendered to the left of the indexed children, to
the right of any left child, and between any top and bottom children. This tag is used inside of a
<uix:borderLayout> tag.
The <uix:innerLeft> tag has no attributes.
26-67
26-68
<uix:innerRight>
Specifies the border to be rendered to the right of the indexed children and to the left of any
right child.
JSP Syntax
<uix:innerRight>
JSP content
</uix:innerRight>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:innerRight> tag specifies the border to be rendered to the right of the indexed
children, to the left of any right child and between any top and bottom children. This tag is used
inside of a <uix:borderLayout> tag.
The <uix:innerRight> tag has no attributes.
26-69
26-70
<uix:innerStart>
Specifies the border to be rendered to the left of the indexed children and to the right of any left-
appearing child.
JSP Syntax
<uix:innerStart>
JSP content
</uix:innerStart>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:innerStart> tag specifies the border to be rendered to the left of the indexed children,
to the right of any left-appearing child and between any top and bottom children, if the reading
direction is left-to-right; otherwise, on the right to the left of any right-appearing child . This tag
is used inside of a <uix:borderLayout> tag.
The <uix:innerStart> tag has no attributes.
26-71
<uix:innerTop>
Specifies the border to be rendered above the indexed children and below any top child.
JSP Syntax
<uix:innerTop>
JSP content
</uix:innerTop>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:innerTop> tag specifies the border to be rendered above the indexed children and
below any top child. This tag is used inside of a <uix:borderLayout> tag.
The <uix:innerTop> tag has no attributes.
26-72
<uix:labeledFieldLayout>
Lays out its indexed children in a series of columns, displaying one set for the labels and the
other set for the fields.
JSP Syntax
<uix:labeledFieldLayout
[ columns="numberColumnPairs" ]
[ fieldWidth="numberPixels | percentTotalWidth" ]
[ labelWidth="numberPixels | percentTotalWidth" ]
[ width="numberPixels" ]>
JSP content
Example
The example below displays the inline messages in two pairs of columns.

<uix:document>
<uix:body>
<uix:labeledFieldLayout columns="2" width="100%" >
</uix:body>
</uix:document>
Description
The <uix:labeledFieldLayout> tag lays out its indexed children in a series of columns,
displaying one set for the labels and the other set for the fields, with a space between. The
children are laid out across and down, with the first child in each row in the label position and
the second in the field position. The contents of each row are centered in the available space,
with the labels right aligned, and the fields left aligned. With multiple columns, the children
continue to be laid out across and down. For example, with two columns, the third child will be
used as the label for the first row and second column.
26-73
Although designed for labeled text fields, this layout can be used with any UINodes. It also has
special support for all of the inline messaging tag. Each inline messaging tag will automatically
occupy both a label and field position.
Attributes
● columns—optional, the number of pairs of columns to display in the layout. If no value is

specified, a default of 1 is used.
● fieldWidth—optional, the preferred width of each field column. May be specified as either
a percentage or an absolute number of pixels. If the label width is not specified, it will
default appropriately to fill up the rest of the layout.
● labelWidth—optional, the preferred width of each label column. May be specified as
either a percentage or an absolute number of pixels. If the field width is not specified, it
will default appropriately to fill up the rest of the layout.
● width—optional, the preferred total width of the layout.
26-74
<uix:leading>
Creates the leading list of the shuttle.
JSP Syntax
<uix:leading>
JSP content
</uix:leading>
Example
The example below shows how the <uix:shuttle> tag is used with the <uix:leading>,
<uix:leadingFooter>, <uix:trailing> and and <uix:trailingFooter> tags to create two lists that can
be reordered.

<uix:document>
<uix:body>
<uix:shuttle name="shuttle1" >
<uix:leadingFooter>
<uix:styledText text="leading footer" ></uix:styledText>
</uix:leadingFooter>
<uix:trailingFooter>
</uix:trailingFooter>
<uix:leading>
<uix:list name="list1">
<uix:contents>
<uix:option text="option 1" value="10" />
<uix:option text="option 2" value="11"/>
</uix:contents>
</uix:list>
</uix:leading>
<uix:trailing>
<uix:contents>
</uix:contents>
26-75
</uix:list>
</uix:trailing>
</uix:shuttle>
</uix:body>
</uix:document>
Description
The <uix:leading> tag creates the leading list of the shuttle. This tag is used as a wrapper tag
inside of a <uix:shuttle> tag.
The <uix:leading> tag has no attributes.
26-76
<uix:leadingFooter>
Creates the footer of buttons and images under the leading list in a shuttle.
JSP Syntax
<uix:leadingFooter>
JSP content
Example
be reordered.

<uix:document>
<uix:body>
<uix:leadingFooter>
<uix:leading>
<uix:contents>
</uix:contents>
</uix:list>
</uix:leading>
<uix:trailing>
<uix:contents>
</uix:contents>
26-77
</uix:list>
</uix:trailing>
</uix:shuttle>
</uix:body>
</uix:document>
Description
The <uix:leadingFooter> tag creates the footer of buttons and images under the leading list.
This tag is used as a wrapper tag inside of a <uix:shuttle> tag.
The <uix:leadingFooter> tag has no attributes.
26-78
<uix:left>
Specifies the border to be rendered below the indexed children and above any bottom child.
JSP Syntax
<uix:left>
JSP content
</uix:left>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:left> tag specifies the border to be rendered below the indexed children and above
any bottom child. This tag is used inside of a <uix:borderLayout> tag.
The <uix:left> tag has no attributes.
26-79
26-80
<uix:link>
Inserts a text link to a target.
JSP Syntax
<uix:link
[ text="string" ]
[ name="anchorName" ]
[ onClick="event handler" ]>
JSP content
</uix:link>
Example
The first example below displays a text link to the page Home1.jsp. The second example shows
a series of links included within a sideNav bar.
<uix:link text="Home" destination="Home1.jsp" />
<uix:sideNav>
<uix:link text="Managers" destination="EmpManagerLink_Browse.jsp"/>
</uix:sideNav>
Description
The <uix:link> tag wraps its children inside of an HTML link. It is used on its own for general
linking, but also as the content for several components that support linking, like the
<uix:tabBar> tag, <uix:globalHeader> tag, and <uix:sideNav> tag.
Attributes
26-81
● text—optional, the character string that will display as the text link.
● destination—optional, the URI this link should reference.
● accessKey—optional, the character used to select the link. This attribute is sometimes
exist in the text attribute of this link instance. If it does not, the user will receive no visual
indication of the existence of the accessKey. If the same access key appears in multiple
locations in the same page of output, the rendering user agent will cycle among the
elements accessed by the similar keys.
● disabled—optional, whether the link should be considered disabled.
● longDesc—optional, a long description associated with this link, used to clarify it
purpose.
● name—optional, the name used to identify the link as an anchor.
● onFocus—optional, the event handler for the link gaining the focus
● onClick—optional, the event handler for the link being selected.
26-82
<uix:list>
Displays a defined list of items from which the user can select.
JSP Syntax
<uix:list
name="string"
[ multiple="true | false" ]
[ size="numberItems" ]
[ selectedValue="string" ]>
JSP content
</uix:list>
Example
The example below displays a list of items with two choices.

<uix:document>
<uix:body>
<uix:list name="MyChoice" >
</uix:list>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:list> tag creates a control which allows the user to select one or more values from a
list of items. The list control contains any number of <uix:option> tags, each of which
represents an available option that the user may select.
26-83
Attributes
● name—the name used to identify the list.

● multiple—optional, whether multiple items may be selected. By default, only a single
item may be selected from the list.
● size—the number of items that should be displayed.
● disabled—optional, whether the list should be considered disabled.
● readOnly—optional, whether the list should be editable.
● selectedIndex—optional, the value of the index of the selected item in the list. Use the
selectedIndex attribute to specify which list item appears selected on the page. The
selectedIndex attribute is zero-based.
● selectedValue—optional, the the string value for the selected item in the list. Use either
the selectedValue attribute or the selectedIndex attribute to specify which list item
appears selected on the page.
26-84
<uix:lovField>
Creates a text field with an associated button for launching a List of Values (LOV) dialog.
JSP Syntax
<uix:lovField
name="string"
[ text="textInputName" ]
[ required ="Yes | No | validaterOnly" ]
[ wrap="Soft | Hard" ]
[ secret="true | false" ]
[ onSelect="event handler" ]
[ destination="URL" ]>
JSP content
</uix:lovField>
Example
The example below creates a text field with a button for launching a List of Values (LOV)
dialog.

<uix:document>
<uix:body>
<uix:lovField name="MyLovField" text="test text" />
</uix:form>
</uix:body>
</uix:document>
Description
26-85
The <uix:lovField> tag creates a text field with an associated button for launching a List of
Values (LOV) dialog. A button to launch a List of Values dialog is provided, but you are
responsible for actually launching the dialog and handling the returned result, either through a
JavaScript pseudo URL on the destination attribute or through a JavaScript onClick handler.
Any onClick handler or short description attached to the <uix:lovField> tag will only apply to the
LOV Button on the <uix:lovField> tag. The name property is required and must be set for the
validation to work correctly.
Attributes
● name—the name used to identify the LOV field.

● text—optional, the character string that will display as a label on the LOV field.
● maximumLength—optional, the maximum number of characters per line that can be
entered into the LOV field. Note that this value is independent of the "columns"
displayed.
● required—optional, whether user input is required in the LOV field. Three values are
allowed: Yes, No, and validaterOnly. The default is No. Yes means that User input in this
field is required and any attached validater must succeed. No means that either this field
is empty or any attached validater must succeed. validaterOnly means that any attached
validater must succeed. Thus validation success is only dependent on the validater and
not whether any text has been entered into this field. These values interact with any
ClientValidaters attached to the <uix:textInput> tag to determine whether field validation
succeeds or fails.
● rows—optional, the number of rows to display in the LOV field. The default is one, which
creates a text field. Setting to more than one row creates a text area and precludes the
use of some attributes, such as secret.
● columns—optional, the number of columns to display in the LOV field. If no value is
specified, a default of 30 columns is used. Columns are measured in character width.
● wrap—optional, the type of text wrapping to be used in a multi-row text control. This
attribute is ignored for single row controls. By default, multi-row text does not wrap at the
column edge, but instead scrolls horizontally. Two values are allowed: Soft and Hard.
Soft indicates that the text should wrap visually, but not include carriage returns in the
value. Hard specifies that the value of the text should include any carriage returns
needed to wrap the lines.
● secret—optional, whether the actual value of the text should be hidden from the user.
When set to true, it hides the text entered by the user, as for a password. The default in
false.
● disabled—optional, whether the LOV field should be considered disabled.
● readOnly—optional, whether the LOV field should be editable.
26-86
● onChange—optional, the event handler for when the value in the LOV field is changed.
● onSelected—optional, the event handler for when LOV field becomes selected.
● destination—optional, the destination URL invoked when the LOV button next to the field
is clicked.
26-87
<uix:messageBox>
Inserts important messaging information at the top of an application page.
JSP Syntax
<uix:messageBox
[ messageType="error | info | warning | confirmation" ]
[ text="string" ]
[ automatic="true | false" ]
[ dataName="boundvalue" ]
[ dataNameSpace="namespace" ]>
JSP content
</uix:messageBox>
Example
The example below displays the message "Access Denied" at the top of a page.
<uix:messageBox message="Access Denied" />
Description
The <uix:messageBox> tag is used at the top of an application page to give the user important
messaging information. The types of messages are:
● Error
● Information
● Warning
● Confirmation
There are two ways to use a MessageBox: using explicit attributes and using automatic
configuration.
Using explicit messageBox attributes gives you complete control, but requires more work to
configure. It involves directly setting attributes on the MessageBox to completely specify how it
should display. The type of message box to display is set using the messageType property. It
should be set to the corresponding UIConstant: error, info, warning, or confirmation. The title
26-88
text of the message is automatically generated, but can be overridden using the text property.
The message text to be displayed at the top of the box is set with the message property. The
individual messages are represented by the indexed children, which should be <uix:link> with
the longDesc attribute set to the value of the descriptive text following the link.
Using automatic messageBox configuration allows it to gather all of its information from a
MessageData instance. This is accomplished by setting the automatic attribute of the
<uix:messageBox> tag to true.
The automatic configuration cannot be used for <uix:messageBox> tags that display
confirmation messages. Those cases must be handled using explicit attributes.
Attributes
● message—optional, the error, warning, or informational text for the box.

● messageType—optional, the type of the message; acceptable values are: error, info,
warning, and confirmation. Defaults to none.
● text—optional, specified text that will override the title text.
● automatic—optional, whether or not the messageBox should gather its information from
MessageData instead of its own properties and children. Values allowed are: true and
false.
● dataName—optional, the name of the data object from which to gather message data,
which is only used in automatically configured MessageBoxes.
● dataNameSpace—optional, the namespace of the data object from which to gather
message data, which is only used in automatically configured MessageBoxes.
26-89
<uix:messageStyledText>
Combines the <uix:styledText> and <uix:inlineMessage> tags.
JSP Syntax
<uix:messageStyledText
[ prompt="string" ]
[ tip="string" ]
[ vAlign="Middle | Top | Bottom" ]>
JSP content
Example
The example below displays the text message formatted as styled text.

<uix:document>
<uix:body>
<uix:messageStyledText message="This is the message" prompt="Prompt" tip="This is a
tip">
</uix:body>
</uix:document>
Description
The <uix:messageStyledText> tag is a combination of the <uix:styledText> and

<uix:inlineMessage> tags. The <uix:styledText> applies a style class to text or a text link. The
<uix:inlineMessage> tag inserts a component that wraps another, adding a label, and optionally
an icon with a message.
Attributes
26-90
● anchor—optional, specifies the name of an anchor tag. This tag will uniquely identify this
inline message across a single page. The destinations of links in a MessageBox would
reference this anchor.
● longDescURL—optional, a URL to a page with more information about the message.
● message—optional, the error, warning, or informational text.
● messageType—optional, the type of the message; acceptable values are: error, warning,
● tip—optional, the tip text associated with the control.
26-91
<uix:multipleSelection>
Causes a table to render both a selection column for multiple selection of rows and a control
bar surrounding the table contents.
JSP Syntax
<uix:multipleSelection
[ text="string" ]
[ selected="true | false" ]>
JSP content
</uix:multipleSelection>
Example
The example below displays columns with check boxes that allow multiple selection.

<uix:document>
<uix:body>
<uix:tableSelection>
<uix:labeledFieldLayout columns="1" width="100%" >
<uix:styledText text="Choice 1" /></uix:styledText>
<uix:multipleSelection text="choice1" />
<uix:styledText text="Choice 1" />
<uix:multipleSelection text="choice2" />
</uix:table>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:multipleSelection> tag provides multi-selection for <uix:table> and <bc4juix:table>

tags. It is only useful in the context of a <uix:table> tag, and should be initialized and set on the
26-92
<uix:table> tag as the tableSelection attribute. For a single-selection table, use the
<uix:singleSelection> tag instead.
Selection Appearance
Adding a <uix:multipleSelection> tag to a Table causes the table to render both a selection
column in the table and a control bar surrounding the table contents. The selection is
represented by a checkbox column rendered into the table.
The control bar rendered above and below the table appears automatically when a
<uix:multipleSelection> tag is present in the table. The text displayed in the control bar is the
value of the <uix:multipleSelection> tag's text property. Additionally, any indexed children of the
<uix:multipleSelection> tag are rendered into the control bar on the right side. Together, these
properties allow you to easily create the control bars specified by the Oracle UI guidelines: a
brief text message accompanied by action buttons which act on the selected row(s) of the
table.
Initial Selection
The initial selection state of a <uix:multipleSelection> tag is retrieved by a DataObjectList

whose DataObjects map to the rows in the table. This DataObjectList is specified by setting the
selection attribute. If this DataObjectList is not specified, the same DataObjectList used to
generate data in the table itself is used.
For each row in the table, the selection DataObjectList must return a DataObject which can be
queried for the selected status of its corresponding row. The key used to query each
DataObject must be set using the selectedBinding attribute. If a row DataObject returns
Boolean.TRUE when queried with the value of the selectedBinding attribute, then that row will
be initially selected. Otherwise, that row will be initially deselected.
Disabling Selection
Rows in the selection can be disabled, so they cannot be selected. To accomplish this, simply
set the disabled property to return true. However, in most cases you will only want to mark
certain rows as unselectable. In those cases, simply bind the disabled property to return "true"
for those DataObject rows which should be disabled. Note that, as mentioned above, the
selection DataObjectList will first be checked for this attribute, and if the selection is not
specified, the table's own DataObjectList will be queried.
Selection Results
The results of a user's selection are stored in a page via well-known form elements based on
26-93
the row and the name of the<uix:table> tag containing them. This allows the utility
classServletRequestDataSet to be used to easily determine which row(s) the user selected at
the time of the form submission. You can construct a ServletRequestDataSet using a
ServletRequest and the name attribute of the <uix:table> tag, and retrieve the zero-based row
numbers that were selected by calling getSelectedIndices() with that DataSet.
Attributes
● text—optional, the character string to display in the control bar.

● disabled—optional, whether this multiple selection should be disabled.
● selected—optional, the initial selection of a table row; generally, this attribute will be
databound to the current DataObject, so it can pull selection state from the "selection"
DataObjectList.
26-94
<uix:navigationBar>
Displays the current position among a larger set of steps or records and provides links to
additional steps and records.
JSP Syntax
<uix:navigationBar
[ blockSize="numberRecords" ]
[ maxValue="lastRecordNumber" ]
[ minValue="firstRecordNumber" ]
[ name="navigationBarName" ]
[ value="recordNumber" ]
[ formName="string" ]
/>
Example
The first example shows the default single step navigation bar, which displays the progress
through a sequence of known steps, such as those in a wizard. Its text is generated in the form
"Step 3" with Back and Next buttons.
<uix:navigationBar value="3" />
The next example shows the multiple step navigation bar, which is used within tables with large
sets of records. It takes a different appearance including text of the form "10-19 of 100" with
links for previous and next sets of records.
<uix:navigationBar blockSize="10" maxValue="100" minValue="1" name="navigationBarName"

value="15" formSubmitted="Yes" />
Description
The <uix:navigationBar> tag is used to display the user's current position among a larger set of
steps or records. It provides navigation through these steps or records using generated Next
and Previous links of a specified number.
There are two distinct types of NavigationBars: single- and multiple step. The default single
step navigation bar shows the progress through a sequence of known steps, such as those in a
26-95
wizard. Its text is generated in the form "Step 3" as shown in the first example or "Step 3 of 6".
The multiple step NavigationBar is used within tables with large sets of records, and its
appearance includes text of the form "10-19 of 100" as shown in the second example. The
<uix:table> tag also creates multiple step NavigationBars as part of its own rendering.
The type of NavigationBar that displays is determined by the blockSize property. It defaults to
the constant -1, which causes a single step NavigationBar to be rendered. Setting it to any
other value causes the NavigationBar to render as a multiple step control with the specified
number of records as the currently viewed block size.
Setting the blockSize to the special value of zero will cause a NavigationBar which has no
range and disabled links to be rendered.
The minValue and maxValue properties determine the boundaries of records or steps through
which navigation can occur. For instance, if the navigation occurs through steps 1 through 10,
minValue should be set to 1 and maxValue to 10. Navigation occurring through employee
numbers which range from 1000 to 100000 should use 1000 as the minValue and 100000 as
the maxValue. The minValue property defaults to a value of 1, while the maxValue property
defaults to the special UIConstant value -1, which causes changes in the rendering to reflect
that the range of navigation is unknown.
The value property determines the current step in a single step navigation or the first record
currently displayed in a multiple step navigation.
The NavigationBar can render its links either as URLs with standard arguments or as well-
known values in a submitted form.
By default, the NavigationBar generates URL links based on two of its properties: destination
and name . The destination property determines the base URL to which all generated links
point. The name property is transformed into a source parameter to indicate the source of the
event. The parameters of the URL contain the goto event ID, the name property of the
NavigationBar as the source parameter, and the requested values or steps to view. Note that if
the NavigationBar is created and rendered by a Table tag, the NavigationBar inherits the name
of the table which is rendering it as its source.
For example, if a single step NavigationBar had a destination property with a value of
http://bali.com/navigate.jsp and a name property of testNav on step 3 of 6 of navigation, it
would generate a back link with the destination:
"http://bali.com/navigate.jsp?event=goto&source=testNav&value=2"
26-96
and a next link with destination:
"http://bali.com/navigate.jsp?event=goto&source=testNav&value=4"
If a <uix:table> tag named "testTable" created a multiple step NavigationBar displaying "10-19
of 100", it would generate a "Previous 10" link with destination:
"http://bali.com/navigate.jsp?event=goto&source=testTable&value=1&size=10"
and a "Next 10" link with destination:
"http://bali.com/navigate.jsp?event=goto&source=testTable&value=20&size=10"
The NavigationBar can also render links that trigger a form submission using JavaScript. This is
useful for NavigationBars which are rendered by <uix:table> tags containing editable form
controls, as it submits the form values along with special hidden values indicating the user's
requested navigation.
To have a NavigationBar render form-based URLs, set the formSubmitted property in the
<uix:navigationBar> tag, or in the <uix:table> tag which creates the NavigationBar, to true. As a
result, hidden fields with the following names will be rendered into the page:
● event
● source
● value
● size
If the form is submitted as a result of the user selecting a NavigationBar link, the event field will
be set to the special value goto, the source field will be set to the name of the NavigationBar or
Table generating the event, the value field will be set to the navigation target value, and the
size field will be set to the number of records to display. The size field will not be rendered for
single step NavigationBars.
On the server, the values of these hidden fields can be retrieved as parameters directly from a
ServletRequest. If the form was not submitted as part of a navigation event, these parameters
will have no values.
Attributes
● blockSize—optional, the number of records currently displayed in the navigation bar. It

26-97
defaults to -1.
● destination—optional, the base URL to which all generated links point.
● maxValue—optional, the last possible record in a navigation bar. If this value is not
known, it should be set to -1, which is also the default value.
● minValue—optional, the first possible record in a multiple step navigation bar. This value
is ignored in a single step navigation bar. It defaults to 1.
● name—optional, the name of the navigation bar, which is used to generate links. The
name property is transformed into a source parameter to indicate the source of the
event.
● value—optional, the current step in a single step navigation bar, or the first currently
viewed element in a multiple step navigation bar. It defaults to 1.
● formSubmitted—optional, determines whether the NavigationBar renders links that
trigger a form submission using JavaScript. Set to true to create a NavigationBar with
form-based URLs.
● formName—optional, the name of the form to submit. Setting this attribute causes
NavigationBar links to use JavaScript form submission.
26-98
<uix:option>
Creates a single option which the user may select from a set of items.
JSP Syntax
<uix:option
text="optionName"
value ="string"
/>
Example
The example below displays two options from which users can select.

<uix:document>
<uix:body>
</uix:choice>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:option> tag represents a single option which the user may select from a set of items in
a list or choice control. The text attribute specifies what is displayed to the user as the label of
the option.
Attributes
● text—the character string that will display as a label on the option.

● value—the value used to identify this item when the parent control is submitted to the
server. If no value is specified for a particular item, the item's contents will be used as its
value.
26-99
● selected—optional, whether the option should be considered selected. By default, no
options are selected.
26-100
<uix:pageButtonBar>
Displays a set of buttons inserted with the <uix:button> tag.
JSP Syntax
<uix:pageButtonBar>
JSP content
</uix:pageButtonBar>
Example
The example below displays a button bar with two buttons.
<uix:pageButtonBar>
<uix:button text="Home" destination="Home.jsp" source="home.gif" />
<uix:button text="Help" destination="Help.jsp" source="help.gif" />
</uix:pageButtonBar>
Description
The <uix:pageButtonBar> tag lays out a set of buttons inserted with the <uix:button> tag that
operate over the scope of the entire page.
The <uix:pageButtonBar> tag has no attributes.
26-101
<uix:pageLayout>
Applies a template to the entire page, wrapping all page elements.
JSP Syntax
<uix:pageLayout
[ title="string" ]
[ quickLinksShown="true | false" ]>
JSP content
</uix:pageLayout>
Example
The following example shows where <uix:pageLayout> and </uix:pageLayout> are placed
within the structure of the help page template.
<HTML>
<BODY>
<uix:pageLayout title ="Main Help Page">
<uix:globalButtons>
<uix:globalButton text="Feedback" destination="http://otn.oracle.com/products/jdev"
source="/webapp/feedback.gif" />
<uix:tabs>
<uix:tabBar>
<uix:link text="Help" destination="main_Help.jsp" selected="true" />
</uix:tabBar>
</uix:tabs>
<uix:copyright>
<uix:styledText text="Copyright 2001 Oracle Corporation" />"
</uix:copyright>
<%-- Main page contents go here --%>

<uix:contents>
<uix:header text="Help Text" />
</uix:contents>
</uix:pageLayout>
</BODY>
26-102
</HTML>
The following example shows the </uix:pageLayout> tag with title and quickLinksShown
attributes specified.
<uix:pageLayout title="Getting Started" quickLinksShown="true" />
Description
The <uix:pageLayout> tag is a high-level layout element that acts as a template for the entire
page, wrapping all page elements inside the <BODY> tag.
Attributes
● title—optional, the text to display as the title of the page.

● quickLinksShown—optional, whether links to the top-level headers should be shown on
this page.
26-103
<uix:radioButton>
Inserts a button within a form to trigger some action in response to a click.
JSP Syntax
<uix:radioButton
name="string"
[ value ="string" ]
[ accessKey="character" ]>
JSP content
</uix:radioButton>
Example
The example below displays a form with two radio buttons.

<uix:document>
<uix:body>
<uix:radioButton name="radio1" text="Radio Choice 1" />
<uix:radioButton name="radio2" text="Radio Choice 2" />
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:radioButton> tag maps to a standard browser input radio, which is grouped with all
other radio button controls on the same page which share the same name. The text defined by
the radio button attribute will be displayed as the radio button label. Radio buttons with the
same name will be placed in the same group with mutually exclusive selection, regardless of
their physical placement on the page.
26-104
Attributes
● name—the name used to identify the button.

● selected—optional, whether the button should be considered selected.
● value—optional, the string value to be sent when this radio button is selected from its
group
● readOnly—optional, whether the button should be editable
exist in the text attribute of this Button instance. If it does not, the user will receive no
visual indication of the existence of the accessKey. If the same access key appears in
26-105
<uix:radioGroup>
Creates a set of radio buttons, laid out vertically.
JSP Syntax
<uix:radioGroup
[ id="radioGroupIdentifier" ]
name="string"
[ selectedValue="string" ]
[ type="Radio | Choice" ]
[ onBlur="event handler" ]>
JSP content
</uix:radioGroup>
Example
The example below creates a form with a set of radio buttons.

<uix:document>
<uix:body>
<uix:radioGroup id="group1" >
</uix:radioGroup>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:radioGroup> tag creates a set of radio buttons, laid out vertically and controlled from a
26-106
single list of data.
Attributes
● name—the name used to identify the radio group.

● id—optional, the name used to identify the object instance in the specified scope's
namespace, and also the scripting variable name declared and initialized with that object
reference. The name specified is case sensitive and shall conform to the current scripting
language variable-naming conventions.
● onChange—optional, the event handler for when the value in the radio group selection is
changed.
● required—whether user input is required in the radio group. Two values are allowed: Yes
and No. The default is No, user input is not required.
● selectedIndex—optional, the value of the index of the selected item in the radio group.
Use the selectedIndex attribute to specify which radio group item appears selected on
the page. The selectedIndex attribute is zero-based.
● selectedValue—optional, the the string value for the selected item in the radio group.
Use either the selectedValue attribute or the selectedIndex attribute to specify which
radio group item appears selected on the page.
● type—optional, whether the group of options should be displayed as a series of radio
buttons or a choice. Allowable values are radio and choice. Choice creates a combo box
or choice field.
● disabled—optional, whether the radio group should be considered disabled.
● readOnly—optional, whether the radio group should be selectable.
26-107
<uix:rawText>
Supports outputting of unescaped text generated in HTML.
JSP Syntax
<uix:rawText
[ text="string" ]
[ preText="string" ]
[ postText="string" ]>
JSP content
</uix:rawText>
Example
The example below will display text formatted with the <B> and </B> tags in the HTML page.
<uix:rawText preText="<B>" postText="</B>">

<span style="border-style:solid; border-width:0pt 0pt 1pt 1pt; ">
<font face="Arial" color="#999966" size="5"><b>BC4J JSP Application</b></font>
</span>
</uix:rawText/>
Description
The <uix:rawText> tag supports outputting of unescaped text. Use of this tag requires the
developer to generate proper HTML and for that reason, you should strongly consider using
provided component tags instead. In particular, this class does not attempt to encode or escape
characters for NLS or HTML compliance.
Attributes
● text—optional, the character string that will display as raw text, formatted in HTML.
● preText—optional, the text to be rendered before any children of this rawText tag.
● postText—optional, the text to be rendered after any children of this rawText tag.
26-108
<uix:renderingContext>
Introduces the renderingContext so you can call methods.
JSP Syntax
<uix:renderingContext
id="renderingContext">
JSP content
</uix:renderingContext>
Example
The example shows how the <uix:renderingContext> tag is used within a UIX JSP page.

<uix:renderingContext id="MyCtx" >

<%
String sVersion = MyCtx.getAgent().getAgentVersion();
out.println(sVersion);
%>
</uix:renderingContext>
<uix:document>
<uix:body>
</uix:choice>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:renderingContext> tag introduces a script variable that you can program against. The
class name is oracle.cabo.ui.servletRenderingContext. Additional information on
servletRenderingContext can be found in the JavaDoc.
26-109
Attributes
● id—a variable name used to access the renderingContext. The name used to identify the
object instance in the specified scope's namespace, and also the scripting variable name
declared and initialized with that object reference. The name specified is case sensitive
and shall conform to the current scripting language variable-naming conventions.
26-110
<uix:resetButton>
Creates a push button that resets the content of a form.
JSP Syntax
<uix:resetButton
[ text="string" ]
/>
Example
The example below creates a button that will reset the form named form.jsp.
<uix:resetButton text="Reset" formName="form.jsp" />
Description
The <uix:resetButton> tag creates a push button that resets the content of a form. Reset
buttons will not render any child nodes.
Attributes
● formName—optional, the name of the form whose contents should be reset. If not set,
the button will search for a <uix:form> tag ancestor and use the name of the first one
found.
26-111
<uix:right>
Specifies the border to be rendered to the right of the indexed children.
JSP Syntax
<uix:right>
JSP content
</uix:right>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:right> tag specifies the border to be rendered to the right of the indexed children and
between any top and bottom children. This tag is used inside of a <uix:borderLayout> tag.
The <uix:right> tag has no attributes.
26-112
<uix:rowLayout>
Defines a row within a <uix:tableLayout> tag or on its own.
JSP Syntax
<uix:rowLayout
JSP content
</uix:rowLayout>
Example
The example below displays four inline messages laid out in a row of four cells.

<uix:document>
<uix:body>
<uix:rowLayout>
</uix:rowLayout>
</uix:body>
</uix:document>
Description
The <uix:rowLayout> tag can be used on its own, or to define a row within a <uix:tableLayout>
tag. It can contain any arbitrary content, one per cell, but if you need formatting beyond a
simple <td> tag, you must wrap the child nodes in cell format objects.
Attributes
● hAlign—optional, the default horizontal alignment of cells in this row. Valid values are
center, left, right, start, and end.
● vAlign—optional, the default vertical alignment of cells in this row. The acceptable values
26-113
are middle, top, and bottom.
● width—optional, the preferred total width of the layout. This attribute is ignored when the
row layout is inside of a table layout.
26-114
<uix:separator>
Inserts a line that acts as a horizontal separator anywhere within a page.
JSP Syntax
<uix:separator />
Example
The example below inserts a horizontal line on a page.
<uix:separator/>
Description
The <uix:separator> tag creates a line that acts as a horizontal separator anywhere within the
page.
The <uix:separator> tag has no attributes.
26-115
<uix:shuttle>
Provides a mechanism for moving items between two lists and reordering one of these lists.
JSP Syntax
<uix:shuttle
name="shuttleName"
[ reorderable="true | false" ]
[ size="numberItems" ]>
JSP content
</uix:shuttle>
Example
be reordered.

<uix:document>
<uix:body>
<uix:leadingFooter>
<uix:leading>
<uix:contents>
</uix:contents>
</uix:list>
</uix:leading>
<uix:trailing>
<uix:contents>
26-116
</uix:contents>
</uix:list>
</uix:trailing>
</uix:shuttle>
</uix:body>
</uix:document>
Description
The <uix:shuttle> tag provides a mechanism for moving items between two lists and reordering
one of these lists. Often the shuttle will be used to select items from one list by placing them in
the other. However, the shuttle can be used to operate on lists in other ways as well.
The shuttle is required to have a name, from which the names of elements within the shuttle
are derived. Set the name attribute to the name of the shuttle. Each list in the shuttle is required
to have a header, the text of which should be set as the leadingHeader attribute and the
trailingHeader attribute. By default the trailing list of the shuttle has reordered icons next to it.
To remove these icons so that the list cannot be reordered with them, set the reorderable
attribute to false. To set the height of both lists in number of items, set the size attribute. Note
that the size must be between 10 and 20 items. If the attribute is not set, a size is determined
based on the lengths of both lists and the minimum and maximum values.
Attributes
● name—the name of the shuttle.

● reorderable—optional, whether the trailing list of the shuttle has should have reordered
icons next to it. To display icons, set the value to true.
● size—optional, the number of items in both lists. The size must be between 10 and 20
items.
26-117
<uix:sideNav>
Creates a series of linked items down the left side of the page, each defined by a link node.
JSP Syntax
<uix:sideNav
JSP content
</uix:sideNav>
Example
The example below displays a series of links as a vertical list down the left side of each page,
as a side navigation bar.
<uix:sideNav selectedIndex="1">
<uix:link text="Managers" destination="EmpManager_Browse.jsp"/>
</uix:sideNav>
Description
Use the <uix:sideNav> tag to contain a series of links, inserted with the <uix:link> tag, that will
display as a vertical list down the left side of each page of the application. The <uix:sideNav>
tag can contain any kind of link node. The <uix:sideNav> tag must be included within
<uix:pageLayout> tags. The active link can be specified in either the <uix:sideNav> tag with the
selectedIndex attribute, or the <uix:link> tag with the selected attribute.
Attributes
selectedIndex attribute to specify which containee, in this case a link in the side
navigation bar, is active on the page. The selectedIndex attribute is zero-based.
26-118
<uix:singleSelection>
Causes a table to render both a selection column and a control bar surrounding the table
contents.
JSP Syntax
<uix:singleSelection
[ text="string" ]
[ selected="true | false" ]>
JSP content
Example
The example below displays a table with a column that lets a user select a single row.

<uix:document>
<uix:body>
<uix:button name="button1" destination="SingleSelectionSample.jsp" text="My Button1"
/>
</uix:table>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:singleSelection> tag provides single-selection for <uix:table> and <bc4juix:table>

tags. It is only useful in the context of a <uix:table> tag, and should be initialized and set on the
<uix:table> tag as the tableSelection property. For a multiple-selection table, use the
<uix:multipleSelection> tag instead.
26-119
Adding a <uix:singleSelection> tag to a Table causes the table to render both a selection
column in the Table and a control bar surrounding the table contents. The selection is
represented by a radio button column rendered into the table without any additional work done.
The control bar rendered above and below the Table appears automatically when a
<uix:singleSelection> tag is present in the Table. The text displayed in the control bar is the
value of the <uix:singleSelection> tag's text property. Additionally, any indexed children of the
<uix:singleSelection> tag are rendered into the control bar on the right side. Together, these
properties allow you to easily create the control bars specified by the Oracle UI guidelines: a
brief text message accompanied by action buttons which act on the selected row(s) of the
table.
The results of a user's selection are stored in a page via well-known form elements based on
the row and the name of the table containing them. This allows the static
methodgetSelectedIndex() to be used to easily determine which row the user selected at the
time of the form submission. You can construct a ServletRequestDataSet using a
ServletRequest and the name attribute of the <uix:table> tag, and retrieve the zero-based row
number which was selected by calling getSelectedIndex() with that DataSet.
Attributes
● text—optional, the character string to display in the control bar.

● disabled—optional, whether this selection should be disabled.
● selected—optional, the initial selection of a table row; generally, this attribute will be
databound to the current DataObject, so it can pull selection state from the "selection"
DataObjectList.
26-120
<uix:sortableHeader>
Used in a table as a "stamp" for column headers that allow sorting.
JSP Syntax
<uix:sortableHeader
[ value ="string" ]
[ vAlign="Middle | Top | Bottom" ]>
JSP content
</uix:sortableHeader>
Example
The example below creates a column header that allows sorting:
<uix:sortableHeader required="Default"/>
Description
The <uix:sortableHeader> tag is a convenience tag intended to be used as a "stamp" for

column headers in a Table that allow sorting. The <uix:sortableHeader> tag allows you to
create easily table column headers that implement sorting and display any desired status and
messaging icons.
The <uix:sortableHeader> tag uses many of the attributes of its parent tag, the
<uix:messageStyledText> tag. You can use that API to set the display text or its binding, or any
of the message or status icons and their bindings. However, the <uix:sortableHeader> tag uses
one additional attribute in its rendering: sortable. When a <uix:table> tag renders a
<uix:sortableHeader> tag, it uses the value of the sortable attribute to determine whether or not
to render that column header as sortable and, if necessary, whether to flag the column as being
sorted in ascending or descending order.
There are four different values which can be set against the sortable attribute. By default, or if
26-121
no value is set for this attribute, or if No is returned as the value, the column header is not
rendered as sortable. If Yes is returned as the value, the column header is rendered as
sortable. If ascending is returned, the column is rendered as sortable and currently sorted in
ascending order. Similarly, if descending is returned, the column is rendered as sortable and
sorted in descending order.
When specified as being sorted in ascending order, an up arrow will be rendered in the header
to indicate that values increase when read down. When specified as being sorted in
descending order, a down arrow will be rendered in the header to indicate that values increase
when read up the column. No arrow is shown for Yes.
If a destination attribute is set , that value will be used as the destination for the links rendered
in the sortable headers. If not, the destination links generated by a sortable header make use of
four properties and their established values:
● the event property, with the value sort.

● the source property, with the value taken as the name of the table containing the
<uix:sortableHeader> tag.
● the value property, which will be the data bound to this tag's value property, or if nothing
is bound, the zero-based index of the column to sort.
● the state property, with the value ascending if this column is currently sorted in
ascending order, or descending if this column is currently sorted in descending order.
If this <uix:sortableHeader> tag is used in a <uix:table> tag which uses form submission, those
properties and values will be submitted as form values. Otherwise, those four values will be
appended as URL arguments to the destination attribute on the <uix:table> tag.
Attributes
● anchor—optional, specifies the name of an anchor tag.

● value—optional, the value submitted when this column is sorted.
● longDescURL—optional, a URL to a page with more information about the table header.
done independently. This simply affects the displayed user interface.
26-122
26-123
<uix:spacer>
Inserts a fixed amount of space in an HTML layout.
JSP Syntax
<uix:spacer
[ height="numberCharactersHigh" ]>
JSP content
</uix:spacer>
Example
The example below inserts a space anywhere within an HTML layout.
<uix:spacer height="15" width="25" />
Description
The <uix:spacer> tag lets you insert a fixed amount of space in an HTML layout, by specifying
the width and height.
Attributes
● width—optional, the number of characters wide of the space to be inserted.

● height—optional, the number of characters high of the space to be inserted.
26-124
<uix:stackLayout>
Lays out each of its children vertically, wrapping as needed.
JSP Syntax
<uix:stackLayout>
JSP content
</uix:stackLayout>
Example
The example below displays four inline messages laid out vertically.

<uix:document>
<uix:body>
<uix:stackLayout >
</uix:stackLayout>
</uix:body>
</uix:document>
Description
The <uix:stackLayout> tag is a layout tag which will lay out each of its children vertically. Each
pair of adjacent children will be separated by an optional separator child.
The <uix:stackLayout> tag has no attributes.
26-125
<uix:start>
Specifies the start named child container in a page layout or the border to be rendered above
the indexed children in a border layout.
JSP Syntax
<uix:start>
JSP content
</uix:start>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:start> tag specifies the border to be rendered above the indexed children and any
innerTop child. This tag is used inside of a <uix:borderLayout> tag.
The <uix:start> tag has no attributes.
26-126
<uix:styledText>
Applies a style class to text or a text link.
JSP Syntax
<uix:styledText
[ text="string" ]
[ textBinding="boundvalue" ]
[ destination="URI" ]>
JSP content
</uix:styledText>
Example
The example below displays the text "Welcome" formatted with the styleClass "OraHeader".
<uix:styledText styleClass="OraHeader" text="Welcome" />

<span style="border-style:solid; border-width:0pt 0pt 1pt 1pt; ">
<font face="Arial" color="#999966" size="5"><b>to BC4J JSP Application</b></font>
</span>
Description
The <uix:styledText> tag supports both styled text and links. Use the <uix:rawText> tag if the
text does not require styling or simple link capability. Use the <uix:link> tag for more complex
linking.
Attributes
● text—optional, the character string that will display as styled text or the link.
● textBinding—optional, a bound value.
<uix:styledText> tag. This attribute is sometimes referred to as the hotkey or mnemonic.
The character specified by this attribute must exist in the text attribute of this
<uix:styledText> tag. If it does not, the user will receive no visual indication of the
existence of the accessKey. If the same access key appears in multiple locations in the
26-127
same page of output, the rendering user agent will cycle among the elements accessed
by the similar keys.
● destination—optional, the URI this text should reference. This attribute provides a
shortcut, however the same effect can be achieved by wrapping the text inside of a link.
26-128
<uix:styleSheet>
Creates the stylesheet link reference to a generated UIX Styles stylesheet.
JSP Syntax
<uix:styleSheet />
Example
The example below shows the <uix:styleSheet> tag in the head section of an HTML document.
<HEAD>
<TITLE>Browse Page</TITLE>
<uix:styleSheet />
</HEAD>
Description
The <uix:styleSheet> tag is a utility tag for inserting the stylesheet link reference to a generated
UIX Styles stylesheet. It is used in the head section of an HTML document and should not be
used in the body of an HTML document.
The <uix:styleSheet> tag takes no additional properties, but instead uses the UIX Configuration
information to render.
26-129
<uix:submitButton>
Creates a push button that allows submission of a form.
JSP Syntax
<uix:submitButton
[ text="string" ]
[ value="string" ]
[ unvalidated="true | false" ]
/>
Example
The example below creates a button labeled "Update" that will submit the form named form1.
<uix:form name="form1" method="GET">

<uix:submitButton name="jboEvent" text="Update" formName="form1" value="Update" />
</uix:form>
Description
The <uix:submitButton> tag creates a push button that allows submission of forms. Submit
buttons will not render any child nodes. The destination attribute of a submit button is ignored; it
instead uses the destination of the form. It must be an empty element. It may not contain any
child elements or text.
Attributes
● name—optional, the name used to identify the button.

● formName—optional, the name of the form whose contents should be reset. If not set,
the button will search for a <uix:form> tag ancestor and use the name of the first one
found.
● value—optional, the string value to be sent when this button is pressed. The value will be
sent as a key-value pair with the name of the button as the key. For this submission to
work properly, the <uix:submitButton> tag must be inside of the <uix:form> tag used for
submission
26-130
● unvalidated—optional, whether onSubmit validation is fired before submitting the form.
Acceptable values are true and false. false causes no validation to occur. true causes no
validation to occur. By default, validation is fired, and the submission only occurs if the
validation succeeds. In some cases, such as when the Back button in a wizard is clicked,
the programmer would like the form to be submitted, but doesn't want the values to be
validated. Not validating the input allows the values to be remembered without annoying
the user by forcing him to correct any mistakes he made before going back. For these
cases, the value of unvalidated should be set to true so that no validation occurs.
26-131
<uix:switcher>
Used to switch between one of a set of items.
JSP Syntax
<uix:switcher
childName="string">
JSP content
</uix:switcher>
Example
The example below shows how the <uix:switcher> tag is used to switch between two sets
included in a form.
%@ taglib uri="http://xmlns.oracle.com/uix/ui" prefix="uix" %>

<uix:document>
<uix:body>
<uix:switcher childName="secondset" >
<uix:case name="firstset">
<uix:textInput name="MyInputField" text="first control" />
</uix:case>
<uix:case name="secondset">
<uix:textInput name="MyInputField" text="second control" />
</uix:case>
</uix:switcher>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:switcher> tag can be used to switch between sets of items. It has one property,
childName; the tag will render the named child under this name. It is possible to achieve this
same functionality by using a FlowLayout and binding the "rendered" property of each indexed
child, but this approach is simpler. Indexed children of the Switcher tag are not rendered at all.
Attributes
26-132
● childName—at rendering time, the value of the childName attribute is compared to the
name attribute of each of the case elements. If the childName attribute matches the
name of the case, the content of that case will be rendered.
26-133
<uix:tabBar>
Creates a series of tabbed items, each defined by a link node.
JSP Syntax
<uix:tabBar
JSP content
</uix:tabBar>
Example
The examples below create a tab bar with two links. In both examples, the second link is
selected.
<uix:tabBar>
<uix:link text="Help" destination="help.jsp" selected="true" />
</uix:tabBar>
<uix:tabBar selectedIndex="1" >

<uix:link text="Help" destination="help.jsp" />
</uix:tabBar>
Description
Use the <uix:tabBar> tag to contain a series of links, inserted with the <uix:link> tag, that will
display as sequential horizontal tabs across each page of the application. The <uix:tabBar> tag
must be included within <uix:pageLayout> tags. The active link can be specified in either the
<uix:tabBar> tag with the selectedIndex attribute, or the <uix:link> tag with the selected
attribute.
Attributes
● selectedIndex—optional, the value of the index of the selected tab. Use the
selectedIndex attribute to specify which containee, in this case a tab, is active on the
page. The selectedIndex attribute is zero-based.
26-134
26-135
<uix:table>
Supports the editing, display, and formatting of tabular data.
JSP Syntax
<uix:table
id="tableIdentifier"
[ alternateText="string" ]
[ blockSize="numberRows" ]
[ maxValue="lastRowNumber" ]
[ minValue="firstRowNumber" ]
[ name="string" ]
[ nameTransformed="true | false" ]
[ proxied="true | false" ]
[ summary="string" ]
[ tableDataBinding="boundvalue" ]
[ text="string" ]
[ value="rowNumber" ]>
JSP content
</uix:table>
Example
The example below creates a simple table with a column for single selection of a row.

<uix:document>
<uix:body>
/>
</uix:table>
</uix:form>
26-136
</uix:body>
</uix:document>
Description
The <uix:table> tag supports the editing and display of tabular data, as well as special
formatting that accompanies that data.
The number of rows in the data area of the table is specified by the DataObjectList which is set
as the tableData property. The size of that DataObjectList maps to the number of data rows,
with each DataObject in the DataObjectList corresponding to the data for that row.
The rendering of the data in each cell is performed by the indexed children of the <uix:table>
tag. Each indexed child is the equivalent of a column in the table, because columns generally
display a common type of data, and you should add an indexed child to the table for every
column you wish the table to visibly display. When the table data cells are rendered, the
DataObject representing a table row is passed to each indexed child, in turn, for rendering. This
is accomplished by making the row DataObject the "current" DataObject on the
RenderingContext. Then, each indexed child acts as "stamp" which renders itself repeatedly in
every row for that column.
The indexed child selects data from the row DataObject using a select key whose result it
knows how to display. For example, a <uix:textInput> tag that is added as an indexed child of a
table will ask a row DataObject for whatever value it is bound to and render that as a text field.
A <uix:image> tag would query the row DataObject for the source of an image and render its
data as an image tag.
It is your responsibility to make sure that the table data DataObjectList returns DataObjects that
the indexed children can query and use.
In some rare cases, such as where radio buttons need to be rendered in a group across rows,
you may need to turn off the name transformation of rendered data form controls. Setting the
nameTransformed property to "false" will prevent the table from transforming the names of the
rendered data cells in any way throughout the table.
Storing Data on the Client
Sometimes you will want to store data on a table that is not visible to the user, but is still
returned as part of the form submission for that table. This can be useful in keeping state with
the client rather than forcing a server to maintain that state in memory.
To support this globally, UIX Components provides a <uix:formValue> tag which will insert a
26-137
hidden field in a rendered page. That hidden value is then returned to the server in a form
submission. The <uix:table> tag additionally supports adding one or more <uix:formValue> tags
as children of the table. The <uix:formValue> tag queries the table DataObjectList for the data
to insert into its column just as every other table column does. However, a <uix:formValue> tag
in a <uix:table> tag does not render any visible table cells. This allows per-row data to be
stored on a client and returned to a server without affecting the page display.
It is recommended that you make the <uix:formValue> tags the last indexed children in a
<uix:table> tag. This is due to the fact that column header DataObjectList must supply
DataObjects for any column headers up through the final visible data column.
Note that this technique should be used sparingly, as the cost of transmitting the data to the
client and back to the server is still incurred, even if that data isn't directly visible.
Retrieving Submitted Table Data
To support tables which contain editable data columns such as <uix:TextInput> tags, the
CaboShare project contains the utility classServletRequestDataSet. An instance of this class
can be constructed on the server with a ServletRequest and the name of the <uix:table> tag.
The utility class will then parse the ServletRequest and recreate a DataSet implementation so
that the resulting values from a form submission can be easily extracted from a <uix:table> tag.
The constructed DataSet will return a DataObject for each row in the <uix:table> tag, and the
row DataObjects can be queried using selectValue() with the name of a column rendering
UINode in order to return the submitted form value for that row and column. Note that only form
data from the client is stored in a ServletRequestDataSet, and that the indices into the
ServletRequestDataSet are always zero-based. See the ServletRequestDataSet
documentation for more details.
Note also that UIX Controller clients can bypass the ServletRequestDataSet altogether and
callselectValue() directly on a PageEvent to get the form data submitted by a <uix:table> tag.
Column and Row Headers
Column and row headers work similar to the rendering of table data, except that the renderers
are explicitly set on the table as named children rather than added as indexed children. Here,
as with the table data, UINodes function as "stamps".
The node specified as thecolumnHeaderStamp will be used to "stamp" the column header cells,
and the node specified as the rowHeaderStamp will be used to "stamp" the row header cells.
The data used by the column and row headers is set using the columnHeaderData and
rowHeaderData DataObjectList properties. The row header DataObjectList must supply a
26-138
DataObject for each row in the table, and the column header DataObjectList must supply a
DataObject for each column in the table.
Note that both the row header and column header are optional and independent of each other
and the table data.
Selectable Table Rows
A common function of tables is to allow users to select one or more rows and perform an action
on those rows. To facilitate this, UIX Components provides the <uix:singleSelection> tag and
<uix:multipleSelection> tag, either of which can be added to a table using its tableSelection
property. These tags perform three useful tasks:
● They render a column in the table for selecting rows.

● They render a "control bar" around the table with actions to take on the selected rows.
● They work with the ServletRequestDataSet to allow easy retrieval of the client's selection
upon form submission.
Hide/Show in a Table Row
Some table designs call for the ability to hide or show additional detail for individual rows in a
table. This can be achieved by adding a special named child to the table: the detail child. Any
table with such a named child will automatically render an additional column with the heading
details and a hide/show component in each cell.
The disclosed state, whether hidden or disclosed, of each cell in that column is determined by a
new DataObjectList attribute on the table, the detail Disclosure. This DataObjectList should
contain one DataObject for each row in the table, each of which will be queried with the
DISCLOSURE_KEY when that row is rendered. If this DataObject returns Boolean.TRUE from
the query, the row will be rendered as disclosed and the contents of the detail child will be
stamped in a special row under the normal data row. If Boolean.TRUE is not returned, nothing
additional will render under that table row.
When the detail child is rendered underneath any disclosed table row, the current data object
will be the data object for that table row. Thus, the contents of the detail child can get their
bound values from that table row data object by binding to the current object.
Table Footers
There are two tags available which serve as <uix:table> tag "footers", which are rendered
26-139
below the content area. The <uix:addTableRow> tag and <uix:totalRow> tag provide ways for
users to add rows and see total data, respectively, and can be set as the columnFooter named
child. See their documentation for more details.
JavaScript Proxies
In some cases, developers will need to use JavaScript to update or retrieve values in
<uix:table> tags while they are running on the client. When the proxied property is set to true, a
set of JavaScript utility methods will be rendered that allow you to get access to Form elements
based on their columns and rows locations. Additional methods allow access to other table
properties such as the number or rows and the currently selected indices.
The methods can be accessed by creating a TableProxy instance based on the table name.
For example:
// create the proxy object

var proxy = new TableProxy("testTable");
// get the number of rows currently displayed

var length = proxy.getLength();
// get the selected index of a single-selection table

var selectedIndex = proxy.getSelectedRow();
// display the value of the text field in row 2, column "lastName"

var row2Field = proxy.getFormElement("lastName", 2);
alert("The value of the lastName in row 2 is " + row2Field.value);
Formatting the Table
The appearance of the table can be adjusted using five formatting objects: the tableFormat, the
columnFormats, the rowFormats, and the columnHeaderFormats and rowHeaderFormats.
The table format DataObject is queried for format information applicable across the entire table
rendering. Currently, the table format DataObject is queried for the type of banding (i.e.
alternating colors) to render in the table data, using the UIConstant TABLE_BANDING_KEY.
If the format DataObject returns the UIConstant ROW_BANDING, the table data rows alternate
colors. If it returns COLUMN_BANDING, the table columns alternate colors. Otherwise, no
banding is rendered (the default). If the format does indicate that banding is desired, the table
format DataObject will also be queried with the BANDING_INTERVAL_KEY. If this key returns
an Integer greater than 1, that interval will be used as the number of rows or columns to group
in a band. For instance, if a row-banded table returns "2" as the banding interval, the table will
26-140
alternate two dark rows with two light rows over the course of the render.
The column format DataObjectList must return a DataObject for each column to specify the
formatting of that column. Currently, each column format DataObject is queried for the type of
data it displays using the COLUMN_DATA_FORMAT_KEY. This information is used to align
the contents of the cells by type.
If a format DataObject returns TEXT_FORMAT (the default), the text is aligned to the left. If a
format DataObject returns NUMBER_FORMAT, the text is aligned to the right, and if it returns
ICON_BUTTON_FORMAT it will be center aligned, as specified by Oracle UI standards.
Column format DataObjects are also queried to determine if a cell should be rendered with line
wrapping disabled. When queried with the CELL_NO_WRAP_FORMAT_KEY, if the format
object returns Boolean.TRUE, the cells in that column will be rendered without wrapping the
contents.
The column format DataObjects are also queried with the DISPLAY_GRID_KEY. For each
DataObject returning Boolean.TRUE to this query, a vertical grid line will be rendered before
that column's content (to the left in a left-to-right locale). DataObjects which return
Boolean.FALSE for that query will not have grid lines rendered. The default is to render a grid
line for every column.
Column formats can also control their widths by returning a string representing their preferred
width when queried with the WIDTH_KEY. This width can be in pixels or percentages, and it
will be used as a recommended width for the column content. However, if the content is wider
than the specified width, it will take more space than requested. If no column formats in the
table request a specific width, the space will be divided evenly among the data columns as
much as is possible.
One other way that the column format can control the column appearance is to return a value
when queried with the BANDING_SHADE_KEY. If any column format returns a value for this
key, the table will explicitly band all of the columns according to the values of these keys, giving
you complete control over column banding patterns. The allowable results for this query are
BANDING_SHADE_LIGHT for a light shaded column or BANDING_SHADE_DARK (the
default) or normal or dark shaded columns. Note that using any explicit column bands overrides
the use of banding specified by the table format DataObject.
The row format DataObjectList also must supply a DataObject, but for each row in the table.
Each of these DataObjects is queried with the DISPLAY_GRID_KEY, and each one that does
not return Boolean.FALSE from this query will have a grid line rendered above that row. Again,
the default is to render a grid line above every row.
26-141
The column and row header format DataObjectLists also supply DataObjects, but for each row
or column header. When queried with the CELL_NO_WRAP_FORMAT_KEY, if the format
object returns Boolean.TRUE, the cells in that column or row header will be rendered without
wrapping the contents.
The TableFormat class provides simple utility implementations of DataObjectLists and

DataObjects which assist in formatting tables.
Encapsulated Columns
In many cases, you may wish to encapsulate all the information describing a column into a
single entity, rather than spreading it out across the indexed child (column stamp), header
stamp, header format, header data, and column format objects set globally on the table. To
support this, there is a <uix:column> tag which can be added as the indexed child of a table.
The <uix:column> tag will not render anything itself; however, its own indexed children will be
stamped down each cell of that table column
The <uix:column> tag also allows you to set its own columnFormat, column header format,
column header data, and column header stamp. If specified, these will override the values for
formats and stamps attributed to the <uix:table> tag itself. If they are not specified, the
<uix:table> tag's own formats and stamps will be used.
You can use the <uix:column> tag for any, all, or none of the columns in the <uix:table> tag.
You can also set the rendered flag on a <uix:column> tag to hide it from view for a given
render.
Navigation Bars
Tables which show a subset of a larger set of data should render navigation bars at the top
(and sometimes at the bottom) of the table. The <uix:table> tag automatically creates and
renders these navigation bars if it is supplied with the appropriate properties.
To render navigation bars, set one or more of the following properties on the table:
● minValue: the first possible value in the range of data displayed by the table. It defaults
to 1.
● maxValue: the last possible value in the range of data displayed by the table. It defaults
to MAX_VALUE_UNKNOWN.
● value: The first index currently displayed in the table. It defaults to 1.
● blockSize: the number of rows displayed in a normal subset of the table data. Usually
this is the same as the number of rows displayed by the table, which is also the default
26-142
value. However, in edge cases they will differ. For example, a table with maxValue of
103 displaying 10 rows at a time will display 3 rows, but still have a block size of 10,
when it displays rows 101-103.
These properties, along with the table name, are passed to the navigation bars for rendering.
By default, the links generated by the navigation bar are URLs based on the destination
property of the <uix:table> tag and the current view on the navigation set. But the navigation
bar will instead generate form submission links if the formSubmitted property is set on the table.
For more information on the use of these properties and the links they render, refer to the
documentation for the <uix:navigationBar> tag.
For tables displaying a large number of data rows on a single page, the navigation bar should
be repeated at the bottom of the table display.
Other Formatting
The table can also render a title above the data and navigation area. This title can be specified
by setting the text property on the table.
An alternateText property can be used to specify text to be displayed inside the table when no
data has been supplied or there are no rows in the table data.
Attributes
● id—the name which is used to identify the <uix:table> tag in client-server events.
● alternateText—optional, the text to display inside an empty table.
● blockSize—optional, the standard number of rows in displayed in the table. This defaults
to the current number of rows of table data, but may be larger than the number of data
rows at the edge of a set of data.
● destination—optional, the base destination for all links generated by the table.
● formSubmitted—optional, whether or not to use form submission in the links generated
by the table's navigation bars.
● height—optional, the number of characters high of the table.
● width—optional, the number of characters wide of the table.
● maxValue—optional, the last possible row in the set of data displayed by the table. If this
value is not known, it should be set to MAX_VALUE_UNKNOWN, which is also the
default value.
● minValue—optional, the first possible row in the set of data displayed by the table. It
26-143
defaults to 1.
● name—optional, the name used to identify the table in client-to-client or client-to-server
events.
● nameTransformed—optional, whether or not <uix:table> tag should provide any name
transformation when rendering data controls. Valid values are true and false. By default,
the names are transformed.
● proxied—optional, whether or not the table should include JavaScript proxy code when
rendering on the client. Valid values are true and false
● summary—optional, the summary of the table's purpose and structure for user agents
rendering to non-visual media. If this attribute is not provided, the value of the text
attribute will be used.
● tableDataBinding—optional, a bound value.
● text—optional, the character string that will display as the title above the table.
● value—optional, the first currently visible row in the set of data which is displayed by the
table. It defaults to 1.
26-144
<uix:tableLayout>
Contains a series of row layout elements.
JSP Syntax
<uix:tableLayout
[ borderWidth="numberCharactersWide" ]
[ cellPadding="numberCharacters" ]
[ cellSpacing="numberCharacters" ]
JSP content
</uix:tableLayout>
Example
The example below creates a simple table which displays a series of inline messages.

<uix:document>
<uix:body>
<uix:tableLayout >
</uix:tableLayout>
</uix:body>
</uix:document>
Description
The <uix:tableLayout> tag is a thin wrapper around the HTML<table> tag. It contains a series of
<uix:rowLayout> tags.
Attributes
● borderWidth—optional, the width of the border drawn around each cell.

● cellPadding—optional, the spacing within cells.
26-145
● cellSpacing—optional, the spacing between cells.
● hAlign—optional, the horizontal alignment of the table. Valid values are center, left, right,
start, and end.
● width—optional, the preferred total width of the table layout.
26-146
Turns on selection in a table.
JSP Syntax
JSP content
Example
The example below displays a table with a column that lets a user select a single row.

<uix:document>
<uix:body>
/>
</uix:table>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:tableSelection> tag is used to turn on selection in a table. The tag is used inside a
<uix:table> tag as a container for the <uix:singleSelection> tag and <uix:multipleSelection> tag.
The <uix:tableSelection> tag has no attributes.
26-147
<uix:textInput>
Creates either a single-line text field or multi-line text area.
JSP Syntax
<uix:textInput
name="string"
[ text="textInputName" ]
[ wrap="Soft | Hard" ]
[ secret="true | false" ]
[ onSelect="event handler" ]>
JSP content
</uix:textInput>
Example
The example below creates a text field with specified event handlers.

<uix:document>
<uix:body>
<uix:textInput name="MyInputField" text="aaaa" onBlur="alert(\" onBlur\")"
onChange="alert(\" onChange\")" onSelect="alert(\" onSelect\")" />
</uix:form>
</uix:body>
</uix:document>
Description
26-148
The <uix:textInput> tag creates a browser input text widget. Depending on the number of rows,
this control either maps to a text field (for single row controls) or text area (for multiple row text
controls). Use the secret attribute if input should be hidden from the user while displayed, such
as for passwords.
Attributes
● name—the name used to identify the text field or area.

● text—optional, the character string that will display as a label on the text field or area.
● maximumLength—optional, the maximum number of characters per line that can be
entered into the text field or area. Note that this value is independent of the "columns"
displayed.
● required—whether user input is required in the text field or area. Three values are
allowed: Yes, No, and validaterOnly. The default is No. Yes means that User input in this
field is required and any attached validater must succeed. No means that either this field
is empty or any attached validater must succeed. validaterOnly means that any attached
validater must succeed. Thus validation success is only dependent on the validater and
not whether any text has been entered into this field. These values interact with any
ClientValidaters attached to the TextInput tag to determine whether field validation
succeeds or fails.
● rows—optional, the number of rows to display in the text field or area. The default is one,
which creates a text field. Setting to more than one row creates a text area and
precludes the use of some attributes, such as secret.
● columns—optional, the number of columns to display in the text field or area. If no value
is specified, a default of 30 columns is used. Columns are measured in character width.
● wrap—optional, the type of text wrapping to be used in a multi-row text control. This
attribute is ignored for single row controls. By default, multi-row text does not wrap at the
column edge, but instead scrolls horizontally. Two values are allowed: Soft and Hard.
Setting the value for this attribute to "Soft" indicates that the text should wrap visually, but
not include carriage returns in the value. Setting it to "Hard" specifies that the value of
the text should include any carriage returns needed to wrap the lines.
● secret—optional, whether the actual value of the text should be hidden from the user.
Can only be used with single row text fields. When set to true, it hides the text entered by
the user, as for a password. The default in false.
● disabled—optional, whether the text field or area should be considered disabled.
● readOnly—optional, whether the text field or area should be editable.
26-149
● onChange—optional, the event handler for when the value in the text field or area is
changed.
● onSelected—optional, the event handler for when text becomes selected.
26-150
<uix:tip>
Inserts a graphical and textual component that highlights text intended as a hint to the user.
JSP Syntax
<uix:tip
[ text="string" ]>
JSP content
</uix:tip>
Example
The example below creates a tip with the text "Try this method".
<uix:tip text="Try this method" />
Description
The <uix:tip> tag inserts a component that typically provides page or section level hints to the
user. Typically, the only indexed child of the <uix:tip> tag will be a <uix:Text> tag, but as many
children as necessary can be added and will be laid out as with a <uix:flowLayout> tag.
Attributes
● text—optional, the character string that will display as the content of the tip.
26-151
<uix:top>
Specifies the border to be rendered above the indexed children and any innerTop child.
JSP Syntax
<uix:top>
JSP content
</uix:top>
Example
children.

<uix:document>
<uix:body>
<uix:borderLayout>
</uix:borderLayout>
</uix:body>
</uix:document>
Description
The <uix:top> tag specifies the border to be rendered above the indexed children and any
innerTop child. This tag is used inside of a <uix:borderLayout> tag.
The <uix:top> tag has no attributes.
26-152
<uix:totalRow>
Causes a special table row and button that lets users see the updated totals of the data in one
or more columns.
JSP Syntax
<uix:totalRow
[ text="string" ]>
JSP content
</uix:totalRow>
Example
The example below creates a row and button within a table to update a column total.
<uix:totalRow destination="total.jsp" readOnly="false" text="Update Total" />
Description
The <uix:totalRow> tag when when used inside a <uix:table> tag, will cause a special table row
and button to be rendered which lets users see the updated totals of one or more columns. To
use the <uix:totalRow> tag, set it as the columnFooter child of the <uix:table> tag.
There are two customizations clients can make to the <uix:totalRow> tag. First, the text of the
update button can be customized. By default, the button will display a localized version of the
text "Update". If this is not satisfactory, you can change the button text by setting the text
property.
in the parent table. If form submission is used, the <uix:totalRow> tag will submit the table's
form with an "event" form value set to "total" and a "source" form value set to the name of the
table. If URL argument links are used, the same two key/value pairs will be sent as parameters.
destination property of the <uix:totalRow> tag.
Also, to display the actual total data cells in the <uix:totalRow> tag, clients should add indexed
26-153
children to this tag. If one indexed child is added to a <uix:totalRow> tag, it will be rendered
under the rightmost column of its parent table. If two indexed children are added to the
<uix:totalRow> tag, each one will be rendered in turn under the two rightmost columns of the
parent table. The presence of grid lines and the alignment of the <uix:totalRow> tag's children
is also determined by the data in the corresponding table columns.
you can use both a<uix:addTableRow> tag and a <uix:totalRow> tag together. To do this,
create and configure both tags, then add the <uix:totalRow> tag as an indexed child of the
<uix:addTableRow> tag. Then add the <uix:addTableRow> tag as the columnFooter child as
usual.
Attributes

● readOnly—optional, whether the button should be rendered. Valid values are true and
false. If set to true the button will not be rendered.
26-154
<uix:trailing>
Creates the trailing list of the shuttle.
JSP Syntax
<uix:trailing>
JSP content
</uix:trailing>
Example
be reordered.

<uix:document>
<uix:body>
<uix:leadingFooter>
<uix:leading>
<uix:contents>
</uix:contents>
</uix:list>
</uix:leading>
<uix:trailing>
<uix:contents>
</uix:contents>
26-155
</uix:list>
</uix:trailing>
</uix:shuttle>
</uix:body>
</uix:document>
Description
The <uix:trailing> tag creates the trailing list of the shuttle. This tag is used as a wrapper tag
inside of a <uix:shuttle> tag.
The <uix:trailing> tag has no attributes.
26-156
Creates the footer of buttons and images under the trailing list in a shuttle.
JSP Syntax
JSP content
Example
be reordered.

<uix:document>
<uix:body>
<uix:leadingFooter>
<uix:leading>
<uix:contents>
</uix:contents>
</uix:list>
</uix:leading>
<uix:trailing>
<uix:contents>
</uix:contents>
26-157
</uix:list>
</uix:trailing>
</uix:shuttle>
</uix:body>
</uix:document>
Description
The <uix:trailingFooter> tag creates the footer of buttons and images under the trailing list. This
tag is used as a wrapper tag inside of a <uix:shuttle> tag.
The <uix:trailingFooter> tag has no attributes.
26-158
<uix:train>
Inserts a visual indicator on the page that shows where a user is in a multi-step process.
JSP Syntax
<uix:train
[selectedIndex="linkNumber"]>
JSP content
</uix:train>
Example
The example below displays the steps in a process that consists of Steps 1, 2, and 3 on the
"Step 2" page.
<uix:train selectedIndex="1">
<uix:link text="Step 1" destination="BrowseEdit1.jsp" />
</uix:train>
Description
The <uix:train> tag is used to indicate the current page of a multi-page process that the user is
following. The <uix:train> tag must be included within <uix:pageLayout> tags. The active link
can be specified in either the <uix:train> tag with the selectedIndex attribute, or the <uix:link>
tag with the selected attribute.
Attributes
selectedIndex attribute to specify which containee, in this case a link in the train, is active
on the page. The selectedIndex attribute is zero-based.
26-159
<uix:buildTree>
Builds a UIX tree and saves it to the page context so it can be re-used.
JSP Syntax
<uix:buildTree
nodeID="string">
JSP content
</uix:buildTree>
Example
The example below creates the Global ToolBar to be re-used accross various pages:
<uix:buildTree nodeID="GlobalToolBar" >

<uix:globalButton text="Help"
destination="main_Help.jsp" icon="help.gif" />
<uix:globalButton text="Feedback"
destination="http://otn.oracle.com/products/jdev" icon="feedback.gif" />
<uix:globalButton text="Commit"
destination="<%= sCommitDestination %>" icon="commit.gif"/>
<uix:globalButton text="Rollback"
destination="<%=sRollbackDestination %>" icon="rollback.gif"/>
</uix:buildTree>
Description
The <uix:buildTree> tag builds a UIX tree and saves it to the page context so it can be re-used.
The <uix:buildTree> tag is used to display objects in a hierarchical format. It factors data into
child/leaf nodes and parent nodes which are either expanded or collapsed. The purpose of the
tree control is to allow users to quickly browse through complex sets of hierarchical objects and
access detailed information for a record by highlighting it in the tree. The visual representation
of the hierarchy using the tree is also intended to show the relationship between a set of
objects with respect to one another.
Attributes
26-160
● nodeID—used to for the purpose of identifying the tree during events through the server.
26-161
<uix:case>
Defines one of the possible rendered children for the <uix:switcher> tag.
JSP Syntax
<uix:case
name="string">
JSP content
</uix:case>
Example
The example below shows how the <uix:switcher> tag is used to switch between two possible
rendered children defined by the <uix:case> tag.
%@ taglib uri="http://xmlns.oracle.com/uix/ui" prefix="uix" %>

<uix:document>
<uix:body>
<uix:switcher childName="secondset" >
<uix:case name="firstset">
<uix:textInput name="MyInputField" text="first control" />
</uix:case>
<uix:case name="secondset">
<uix:textInput name="MyInputField" text="second control" />
</uix:case>
</uix:switcher>
</uix:form>
</uix:body>
</uix:document>
Description
The <uix:case> tag defines each one of the possible rendered children for the <uix:switcher>
tag. A case element has a name attribute, and one child (UINode) element as content. The
content will only be rendered if the childName attribute of the switcher matches the case name
attribute at rendering time. This element is used as a wrapper element inside of a
<uix:switcher> tag.
26-162
Attributes
● name—the name used to identify this case, to be compared to the value of the switcher
childName attribute at rendering time.
26-163
<uix:cobranding>
Creates the cobranding section of the page layout.
JSP Syntax
<uix:cobranding>
JSP content
</uix:cobranding>
Example
The example below displays a company logo in the cobranding section of a page:
<uix:cobranding>
<uix:image source="/webapp/cobrandinglogo.gif" />
</uix:cobranding>
Description
The <uix:cobranding> tag creates the cobranding section of the page layout that typically
contains a small image of a logo of a non-owning company. This tag is used as a wrapper
inside of a <uix:pageLayout> tag.
The <uix:cobranding> tag has no attributes.
26-164
<uix:columnHeader>
Used to render the column header inside of a table column
JSP Syntax
<uix:columnHeader>
JSP content
</uix:columnHeader>
Example
The example below shows how the <uix:columnHeader> tag is used to render the column
Header, "Header text."
<uix:columnHeader>
<uix:styledText text="header text" ></uix:styledText>
</uix:columnHeader>
Description
The <uix:columnHeader> tag is used to render the column header. This tag is used as a
wrapper tag inside of a <uix:column> tag.
The <uix:columnHeader> tag has no attributes.
26-165
<uix:contentContainer>
Places ancillary information on a page, offset by color.
JSP Syntax
<uix:contentContainer
[ width="numberPixelsWide | percentage" ]
[ text="string"]
[ icon="URI" ]
[ background ="light | medium | dark" ]>
JSP content
Example
The example below places the text "Page End!" in a contentContainer at the end of the page
layout, using the default background.
<uix:end>
<uix:contentContainer>
<uix:styledText text="Page End!" />"
</uix:end>
Description
The <uix:contentContainer> tag is used to place ancillary information on a page, offset by a

certain color.
There are four possible attributes to set for the content container. The width of the container
can be set to either an exact pixel size or a percentage of the element the content container is
within.
Content containers can have headers and icons. Set the text and icon attributes to gain these
items. If neither is set, the content container will only display its children. If there is a header but
no icon, the header will show and the content will be offset to line up with the start of the
header. If an icon is set, the icon will appear to the left of the header, but the content will still be
offset to the left of the header. If an icon is set but no header, the icon will still be displayed on
the left but no header text will be visible.
26-166
Content containers can have light, medium, or dark appearances. Set the background attribute
to "light", "medium", or "dark" to specify which appearance the container should have. The
default is "light" if no background is set. The appearance affects the color of the background,
border, header, and header line.
Content containers will generally have only one child with the actual contents as its children.
This child will describe how the content should be displayed. However, the content container
can have multiple children, in which case the children are displayed in a stack fashion, lined up
vertically.
Attributes
● width—optional, the width of the content container in pixels or as a percentage.

● text—optional, the character string that will display as the header of the content
container.
● icon—optional, a uriReference to an image to use for the icon of the content container.
● background—optional, the appearance type of the content container. It can be either
light, medium, or dark.
26-167
<uix:contents>
Inserts a container for indexed children inside a <uix:pageLayout> tag.
JSP Syntax
<uix:contents>
JSP contents
</uix:contents>
Example
The example below shows the <uix:contents> tag used as a container to wrap the main page
contents.
<uix:contents>
<uix:styledText styleClass="OraHeader" text="Welcome" />
<uix:rawText>
<B>to BC4J JSP Application</B>
</uix:rawText/>
</uix:contents>
Description
The <uix:contents> tag inserts a container for indexed children inside a <uix:pageLayout> tag.
The <uix:contents> tag has no attributes.
26-168
<uix:copyright>
Creates the copyright section of a page layout.
JSP Syntax
<uix:copyright>
JSP content
</uix:copyright>
Example
The example below shows the copyright section with the copyright notice in styledText.
<uix:copyright>
<uix:styledText text="Copyright 2001 Oracle Corporation" />"
</uix:copyright>
Description
The <uix:copyright> tag inserts a container inside of a <uix:pageLayout> tag that creates the
copyright region of the page. This area typically contains a TextNode with the copyright
information for the page.
The <uix:copyright> tag has no attributes.
26-169
<uix:corporateBranding>
Creates the corporateBranding section of a page layout.
JSP Syntax
JSP contents
</uix:corporateBranding>
Example
The example below displays the Oracle logo in the corporateBranding section of a page:
<uix:image source="/webapp/oraclelogo.gif" />
</uix:corporateBranding>
Description
The <uix:corporateBranding> tag creates inserts a container inside of a <uix:pageLayout> tag

that creates the corporateBranding section of the page. This section typically contains a
medium size image of the logo of the company owning the page.
The <uix:corporateBranding> tag has no attributes.
26-170
<uix:dataScope>
Registers UIX Component DataProviders for a UINode subtree.
JSP Syntax
<uix:dataScope
id="string">
JSP content
</uix:dataScope>
Example
The example below registers a UIX Component DataProvider and toggles a group of UINodes
between being disclosed or undisclosed:
<uix:dataScope id="ds2" >

<uix:contents>
<uix:hideShow id="hideShow" formSubmitted="true">
<uix:contents>
<uix:header text="Header">
<uix:contents>
<uix:header text="SubHeader"/>
</uix:contents>
</uix:header>
</uix:contents>
</uix:hideShow>
</uix:contents>
</uix:dataScope>
Description
The <uix:dataScope> tag can be used to register UIX Component DataProviders for a UINode
subtree. Any requests for data by any children of this tag are first handled by any
DataProviders registered on this tag before using other providers.
Attributes
● id—used for the purpose of identifying the DataProvider.
26-171
26-172
<uix:date>
Adds a date validator as a child of onSubmit or onBlur tags.
JSP Syntax
<uix:date
[ pattern="string" ]
[ dateStyle="Full | Long | Medium | Short | Shortish" ]
[ timeStyle="Full | Long | Medium | Short" ]
/>
Example
The example below performs client-side form validation of a date.
<uix:textInput name="date" text="Date:">

<uix:onSubmitValidater>
<uix:date pattern="yyyy/dd/mm"/>
</uix:onSubmitValidater>
</uix:textInput>
Description
The <uix:date> tag adds a date validator as a child of <uix:onSubmitValidater> or

<uix:onBlurValidater> tags. It defines a client validater for localized date formats.
Attributes
● pattern—optional, the pattern for the <uix:onSubmitValidater> or <uix:onBlurValidater>,

as defined by the Java SimpleDateFormat class.
● dateStyle—optional, the format style to use when validating the date. Valid options are
full, long, medium, short or shortish. "Shortish" is identical to "short" but forces the year
to include four digits.
● timeStyle—optional, the format style to use when validating the time. Valid options are
full, long, medium, or short.
26-173
<uix:decimal>
Adds a decimal validator as a child of an onSubmit or onBlur tag.
JSP Syntax
<uix:decimal />
Example
The example below performs client-side form validation of a decimal:
<uix:textInput name="decimal" text="Enter number:">

<uix:onBlurValidater>
<uix:decimal />
</uix:onBlurValidater>
</uix:textInput>
Description
The <uix:decimal> tag adds a decimal validator as a child of a <uix:onSubmitValidate> or

<uix:onBlurValidate> tag.
The <uix:decimal> tag has no attributes.
26-174
<uix:largeAdvertisement>
Creates the largeAdvertisement section of a page layout.
JSP Syntax
JSP content
</uix:largeAdvertisement>
Example
The example below displays an image and link in the largeAdvertisement section of a page:
<uix:image source="/webapp/advertisement.gif" />
<uix:link text="More Info" destination="AdInfo.jsp" />
</uix:largeAdvertisement>
Description
The <uix:largeAdvertisement> tag creates inserts a container inside of a <uix:pageLayout> tag

that creates the largeAdvertisement section of the page. This section typically contains an
image of the advertisement with a link for more information.
The <uix:largeAdvertisement> tag has no attributes.
26-175
<uix:location>
Creates the location section of the page layout that typically contains either a Train or
BreadCrumbs.
JSP Syntax
<uix:location>
JSP content
</uix:location>
Example
The example below displays the location section of a page layout that contains a Train.
<uix:location>
<uix:train>
<uix:link text="Step1" destination="UixBrowseHideShow1.jsp" />
<uix:link text="Step2" destination="UixHelp1.jsp" />
</uix:train>
</uix:location>
Description
The <uix:location> tag inserts a container inside of a <uix:pageLayout> tag that creates the the
locator region of the page. This section typically contains either a <uix:train> tag, indicating the
user's location in a multistep process, or a <uix:breadCrumbs> tag, containing links that will
bring the user back to each of the parent pages of a tree of pages he has navigated.
The <uix:location> tag has no attributes.
26-176
<uix:mediumAdvertisement>
Creates the mediumAdvertisement section of a page layout.
JSP Syntax
JSP content
</uix:mediumAdvertisement>
Example
The example below displays an image and link in the mediumAdvertisement section of a page:
<uix:image source="/webapp/advertisement.gif" />
<uix:link text="More Info" destination="AdInfo.jsp" />
</uix:mediumAdvertisement>
Description
The <uix:mediumAdvertisement> tag creates inserts a container inside of a <uix:pageLayout>

tag that creates the mediumAdvertisement section of the page. This section typically contains
an image of the advertisement with a link for more information.
The <uix:mediumAdvertisement> tag has no attributes.
26-177
<uix:messagePrompt>
Displays the prompt portion of an inline message.
JSP Syntax
<uix:messagePrompt
[ prompt="string" ]
/>
Example
The example below displays the prompt portion of an error message.
<uix:messagePrompt messageType="error" prompt="User not Known" required="Yes" />
Description
The <uix:messagePrompt> tag displays the prompt portion of an inline message, including a
text prompt, an (optional) required icon, and an (optional) icon indicating the type of message.
Use this tag if you need more control over layout than the composite <uix:inline message> tag
allows.
Attributes
26-178
Inserts a parent tag for client-side field validaters.
JSP Syntax
JSP content
Example
The example below performs client-side form validation of a decimal:
<uix:textInput name="decimal" text="Enter number:">

<uix:decimal/>
</uix:textInput>
Description
The <uix:onBlurValidater> tag inserts a parent tag for client-side field validaters. This tag
should be a child tag of <uix:textInput>, <uix:dataField> or <uix:lovField>. This is the
ClientValidater to fire whenever the textInput field, dataField, or lovField loses keyboard focus.
The <uix:onBlurValidater> tag has no attributes.
26-179
Inserts a parent tag for client-side form validaters.
JSP Syntax
JSP content
Example
The example below performs client-side form validation using Wireless Markup Language
(WML) patterns.
<uix:textInput name="ssn" text="SSN:">

<uix:wml pattern="NNN\-NN\-NNNN"/>
</uix:textInput>
Description
The <uix:onSubmitValidater> tag inserts a parent tag for client-side form validaters. This tag
should be a child tag of <uix:textInput>, <uix:dataField> or <uix:lovField>. This is the
ClientValidater to fire whenever the form containing the textInput field, dataField, or lovField is
submitted.
The <uix:onSubmitValidater> tag has no attributes.
26-180
<uix:pageHeader>
Inserts a container at the top of a page in a page layout that typically contains a GlobalHeader.
JSP Syntax
<uix:pageHeader>
JSP content
</uix:pageHeader>
Example
The example below creates a banner with links for Home, Orders and Help. Orders is the
selected link.
<uix:pageHeader>
<uix:globalHeader text="Online Orders" / selectedIndex="1" >
<uix:link text="Orders" destination="order.jsp" />
<uix:link text="Help" destination="Help.jsp" />
</uix:pageHeader>
Description
The <uix:pageHeader> tag creates inserts a container inside of a <uix:pageLayout> tag for the
pageHeader section of the page. This section typically contains a <uix:globalHeader> tag.
The <uix:pageHeader> tag has no attributes.
26-181
<uix:privacy>
Creates the privacy section of a page layout.
JSP Syntax
<uix:privacy>
JSP content
</uix:privacy>
Example
The example below displays the privacy notice in the privacy section of a page.
<uix:privacy>
<uix:link text="Privacy Statement"
destination="http://www.oracle.com/html/privacy.html" />
</uix:privacy>
Description
The <uix:privacy> tag creates inserts a container inside of a <uix:pageLayout> tag that creates
the privacy section of the page. This section typically contains a link to the privacy policy for the
site on which this page is present.
The <uix:privacy> tag has no attributes.
26-182
<uix:productBranding>
Creates the productBranding section of a page layout.
JSP Syntax
JSP content
</uix:productBranding>
Example
The example below displays a product logo in the productBranding section of a page:
<uix:image source="/webapp/product_logo.gif" />
</uix:productBranding>
Description
The <uix:productBranding> tag creates inserts a container inside of a <uix:pageLayout> tag

that creates the productBranding section of the page. This section typically contains an image
of the product logo.
The <uix:productBranding> tag has no attributes.
26-183
<uix:quickSearch>
Creates the quickSearch section of a page layout.
JSP Syntax
<uix:quickSearch>
JSP content
</uix:quickSearch>
Example
The example below creates a quickSearch region on a page:
<uix:quickSearch>
<uix:textInput text="Search" name="QSearch"/>
<uix:end>
<uix:submitButton name="submit"/>
</uix:end>
</uix:textInput>
</uix:quickSearch>
Description
The <uix:quickSearch> tag creates inserts a container inside of a <uix:pageLayout> tag that
creates the quickSearch region of the page. This section typically contains a search button and
text input field.
The <uix:quickSearch> tag has no attributes.
26-184
<uix:ref>
Re-uses a UIX tree saved by the <uix:buildTree> tag.
JSP Syntax
<uix:ref
refID="string">
JSP content
</uix:ref>
Example
The example below reuses a tree saved by the <uix:buildTree> tag.
<uix:globalButtons>
<uix:ref refID="GlobalToolBar" ></uix:ref>
Description
The <uix:ref> tag re-uses a UIX tree saved by the <uix:buildTree> tag.
Attributes
● refID—the name of the tree created with the <uix:buildTree> tag to be re-used.
26-185
<uix:regExp>
Adds a regular expression validator as a child of a <uix:onSubmitValidater> or
<uix:onBlurValidater> tag.
JSP Syntax
<uix:regExp
pattern="string"
/>
Example
The example below performs client-side form validation using a regular expression pattern.

<uix:regExp pattern="[0-9]{3}-[0-9]{2}-[0-9]{4}"/>
</uix:textInput>
Description
The <uix:regExp> tag adds a regular expression validator as a child of a

<uix:onSubmitValidater> or <uix:onBlurValidater> tag.
Attributes
● pattern—the text pattern for the <uix:onSubmitValidater> or <uix:onBlurValidater>.
26-186
<uix:tableDetail>
Used to stamp below every table row that is disclosed.
JSP Syntax
<uix:tableDetail>
JSP content
</uix:tableDetail>
Example
The example below is used to stamp a table row that is disclosed.
<uix:tableDetail>
The details of the table row
</uix:tableDetail>
Description
The <uix:tableDetail> tag is used to stamp below every table row that is disclosed. The tag is
used inside a <uix:table> tag. Adding a detail child will automatically cause the detail column to
be displayed
The <uix:tableDetail> tag has no attributes.
26-187
<uix:tabs>
Specifies the tabs region of the page that typically contains a <uix:tabBar> tag.
JSP Syntax
<uix:tabs>
JSP content
</uix:tabs>
Example
The example below shows the tabs region of the page with a tab bar.
<uix:tabs>
<uix:tabBar>
<uix:link text="Help" destination="help.jsp" selected="true" />
</uix:tabBar>
</uix:tabs>
Description
The <uix:tabs> tag specifies the tabs region of the page that typically contains a <uix:tabBar>
tag.
The <uix:tabs> tag has no attributes.
26-188
<uix:wml>
Defines a client validater using Wireless Markup Language (WML) patterns.
JSP Syntax
<uix:wml
pattern="string"
/>
Example
The example below performs client-side form validation using Wireless Markup Language
patterns.

<uix:wml pattern="NNN\-NN\-NNNN"/>
</uix:textInput>
Description
The <uix:wml> tag defines a client validater using a WML pattern, which is the only pattern
capable of validating on both HTML and WML.
Attributes
● pattern—the text pattern for the <uix:onSubmitValidater> or <uix:onBlurValidater>.
26-189
<xsql:delete-request>
Deletes the rows represented in the XML document that has been posted in the request.
XSQL Syntax
<xsql:delete-request
key-columns="string"
table="table"
[ transform="url" ]
/>
Example
The example below deletes the rows in DEPT table based on DEPTNO key:
<xsql:delete-request table="dept" transform="doc-to-dept.xsl" key-columns="deptno"/>
Description
Deletes the rows represented in the (optionally transformed) XML document that has been
posted in the request. If an HTML Form has been posted, then the posted XML document is
materialized from HTTP request parameters, cookies, and session variables.
Attributes
● table—(Required, String value) Name of the table, view, or synonym to be used for SQL
DELETE.
● transform—(Optional, URL value) Relative or absolute URL of the XSLT transformation
to use to transform the document to be inserted into canonical ROWSET/ROW format.
● key-columns—(Required, String value) Space-separated or comma-separated list of one
or more column names whose values in the posted document should be used to identify
the existing rows in the table for delete.
26-190
<xsql:dml>
Executes a SQL DML statement or PL/SQL anonymous block.
XSQL Syntax
<xsql:dml>
SQL DML or PL/SQL code
</xsql:dml>
Examples
The examples below execute a single DML statement, a single stored procedure, and
combined statements.
A single DML statement:
<xsql:dml> INSERT INTO dept( deptno, dname ) VALUES ({@dept},'{@dname}');</xsql:dml>
A single stored procedure:
<xsql:dml>my_package.my_procedure({@dname});</xsql:dml>
An anonymous block to combine statements:
<xsql:dml>
BEGIN
INSERT INTO dept( deptno, dname ) VALUES ({@dept},'{@dname}');
my_package.my_procedure({@dname});
END;
</xsql:dml>
Description
The <xsql:dml> tag executes a SQL DML statement or PL/SQL anonymous block. Use the
DML panel to enter the required SQL DML or PL/SQL code. This tag is typically used to include
statements that would be executed or rolled back together.
The <xsql:dml> tag has no attributes.
26-191
<xsql:include-owa>
Executes a PL/SQL stored procedure that uses the OWA packages to generate XML content,
and includes the resulting XML.
XSQL Syntax
<xsql:include-owa>
PLSQL
</xsql:include-owa>
Examples
The following example executes a stored procedure:
<xsql:include-owa>
</xsql:include-owa>
The following example executes PL/SQL statements in an anonymous block:
<xsql:include-owa>
BEGIN
my_other_package.another_procedure;
END;
</xsql:include-owa>
This example executes the stored procedure OwaExample.Validate and print validation errors
back to the XSQL file:
<xsql:include-owa>
OwaExample.Validate('{@param1}','{@param2}');
</xsql:include-owa>
Here is the stored procedure OwaExample.Validate that performs the validation:
CREATE OR REPLACE PACKAGE OwaExample IS

PROCEDURE validate( a varchar2, b varchar2);
END;
/
26-192
CREATE OR REPLACE PACKAGE BODY OwaExample IS
PROCEDURE validate( a varchar2, b varchar2) IS
BEGIN
HTP.P('<Status>');
IF SUBSTR(a,1,1) <> 'A' THEN
HTP.P('<Error>First argument has to start with "A"</Error>');
END IF;
IF SUBSTR(b,1,1) <> 'B' THEN
HTP.P('<Error>Second argument has to start with "B"</Error>');
END IF;
HTP.P('</Status>');
END;
END;
/
Description
The <xsql:include-owa> tag executes a PL/SQL stored procedure that uses the OWA packages
to generate XML content, and includes the resulting XML. Use the OWA panel to enter the
required PL/SQL code. This tag is typically used to print tagged data back to the XSQL file.
The <xsql:include-owa> tag has no attributes.
26-193
<xsql:include-param>
Includes XML representing the name and value of a specified parameter.
XSQL Syntax
<xsql:include-param
name="string"
/>
Example
The example below includes the parameter name and value as an XML element:
<xsql:include-param name="rows-skipped">
Description
Includes XML representing the name and value of a specified parameter. This tag is typically
used to let the stylesheet access the value of the specified parameter.
Attributes
● name—(Required, String value) Name of the parameter whose value you want to
include.
26-194
<xsql:include-request-params>
Includes an XML fragment representing the names and values of all HTTP parameters,
cookies, and session variables.
XSQL Syntax
<xsql:include-request-params/>
Example
<xsql:include-request-params/>
Description
Includes an XML fragment representing the names and values of all HTTP parameters,
cookies, and session variables. This tag is typically used to make all of these parameters
available to the stylesheet. The tag has no attributes.
For the HTTP case through the XSQL Servlet, the XML document fragment that is included
when you use the Include Request Params tag is:
<request>
<parameters>
<param1>value1</param1>
:
</parameters>
<session>
<name1>val1</name1>
<name2>val2</name2>
:
</session>
<cookies>
<cookiename1>value1</cookiename1>
:
</cookies>
</parameters>
For other types of requests, such as through the XSQL Command Line Utility or through the
programmatic XSQLRequest class, the XML document fragment that is included when you use
26-195
the Include Request Params tag is:
<request>
<parameters>
:
</parameters>
</parameters>
26-196
<xsql:include-xml>
Include external XML content by specifying an absolute, relative , or parameterized URL.
XSQL Syntax
<xsql:include-xml
href="url"
/>
Examples
The examples below show how to specify an absolute, relative , and parameterized URL.
Include XML from another site:
<xsql:include-xml href="http://stock.com/quotes?symbol={@symbols}"/>
Include XML from an XML file (relative URL):
<xsql:include-xml href="list-of-states.xml"/>
Include XML from parameterized URL:
<xsql:include-xml href="{@pagename}"/>
Description
Allows you to include external XML content by specifying an absolute URL, a relative URL, or a
parameterized URL. The URL can represent a static file or a dynamic source.
Attributes
● href—(Required, URL value) The absolute, relative, or parameterized URL of the XML
resource to be included. The resource can be either a static file or a dynamic source.
26-197
<xsql:include-xsql>
Includes the XML output of another XSQL page.
XSQL Syntax
<xsql:include-xsql
href="url"
[ reparse="boolean" ]
/>
Examples
The examples below show how to specify a relative URL, pass parameters, and use a
parameterized name.
Includes XSQL page result (specifying a relative URL):
<xsql:include-xsql href="order/orders.xsql"/>
Includes XSQL page result, passing parameters:
<xsql:include-xsql href="orders.xsql?cust={@id}"/>
Includes XSQL page result, using a parameterized name and passing parameters:
<xsql:include-xsql href="{@pagename}?cust={@id}"/>
Description
Includes the XML output of another XSQL page. Use this tag to create a hierarchical page from
XML produced by other pages.
Attributes
● href—(Required, URL value) The absolute, relative, or parameterized URL of the XSQL
resource to be included. The resource can be either a static file or a dynamic source.
● reparse—(Optional, boolean) Indicates whether the output of the included XSQL page
should be reparsed before it is included. Use this property if the included XSQL page is
selecting the text of an XML document fragment that the including page wants to treat as
26-198
elements. Valid values are yes and no. The default value is no.
26-199
<xsql:insert-param>
Inserts the value of a parameter into a database table or view.
XSQL Syntax
<xsql:insert-param
name="param"
table="table"
[ date-format="string" ]
[ transform="url" ]
/>
Example
The example below parses and transforms the contents of the parameter xmlfield for database
insert:
<xsql:insert-param
name="xmlfield"
table="image_metadata_table"
transform="field-to-rowset.xsl"/>
Description
Inserts the (optionally transformed) value of a parameter into a database table or view. Use this
tag when the client is posting a well-formed XML document as text in an HTTP parameter or
individual HTML form field.
Attributes
● name—(Required, String value) Name of the parameter whose value contains XML
markup for insert.
INSERT.
● transform—(Optional, URL value) Relative, absolute, or parameterized URL of the XSLT
transformation to use to transform the document to be inserted into canonical
ROWSET/ROW format.
● date-format—(Optional, String value) Date format mask to use for interpreting date field
values in XML being inserted. Valid values are those documented for
26-200
java.text.SimpleDateFormat.
26-201
<xsql:insert-request>
Inserts the (optionally transformed) XML document that has been posted in the request into a
database table or view.
XSQL Syntax
<xsql:insert-request
table="table"
[ columns="string" ]
[ transform="url" ]
/>
Example
The example below parses and transforms the contents of the posted XML document or HTML
Form for insert:
<xsql:insert-request table="purchase_order"
transform="purchseorder-to-rowset.xsl"/>
Description
Inserts the (optionally transformed) XML document that has been posted in the request into a
database table or view. If an HTML Form has been posted, then posted XML document is
This tag supports both HTTP-Posted XML documents and HTTP-Posted HTML Forms. If an
HTML Form is posted, the servlet creates an XML document of the form:
<request>
<parameters>
:
</paramN>valueN</paramN>
</parameters>
:
</request>
Attributes
26-202
INSERT.
● date-format—(Optional, String value) Date format mask to use for interpreting date field
values in the XML being inserted. Valid values are those documented for
● columns—(Optional, String value) Space-separated or comma-separated list of one or
more column names whose values will be inserted. If this list is supplied, then only these
columns will be inserted.
26-203
<xsql:query>
Executes an arbitrary SQL statement and includes its result set in canonical XML format.
XSQL Syntax
<xsql:query
[ fetch-size="integer" ]
[ id-attribute="string" ]
[ id-attribute-column="string" ]
[ max-rows="integer" ]
[ null-indicator="boolean" ]
[ row-element="string" ]
[ rowset-element="string" ]
[ skip-rows="integer" ]
[ tag-case="string" ]
>
SQL
</xsql:query>
Example
The example below executes the SQL query and includes XML for the results:
<xsql:query max-rows="5" tag-case="lower" null-indicator="yes">

SELECT carrier, flightno, TO_CHAR(arrival_time,'HH24:MI') as arrives
FROM todays_flights
WHERE arrival_airport = UPPER('{@airport}')
AND arrival_time > SYSDATE
ORDER BY arrival_time
</xsql:query>
Description
The <xsql:query> tag executes an arbitrary SQL statement and includes its result set in
canonical XML format. Use the Query panel to enter the required SQL statement. This tag is
typically used to specify the SQL query, specify the number of rows to fetch, or to override the
default attribute and element names.
Attributes
26-204
● fetch-size—(Optional, Integer value) Number of records to fetch in each round-trip to the
database. If this property is not set, the default value is taken from the
/XSQLConfig/processor/default-fetch-size configuration setting in XSQLConfig.xml.
● id-attribute—(Optional, String value) XML attribute name to use instead of the default
num attribute for uniquely identifying each row in the result set.
● id-attribute-column—(Optional, String value) Column name whose value should be used
in each row as the value of the id-attribute. Default is to use the row count.
● max-rows—(Optional, Integer value) Maximum number of rows to fetch, after optionally
skipping the number of rows indicated by the skip-rows attribute. The default value is -1
which fetches all rows.
● null-indicator—(Optional, Boolean) Indicates whether to signal that a column's value is
NULL by including the NULL="Y" attribute on the element for the column. By default,
columns with NULL values are omitted from the output. Valid values are yes and no.
Default value is no.
● row-element—(Optional, String value) XML element name to use instead of the default
ROW element name for the entire rowset of query results. Set to the empty-string (" ") to
suppress generating a containing ROW element for each row in the result set.
Note: If you set both row-element and rowset-element to a blank value (" ") and perform a a
query that returns more than one row, then the parser will return an ill-formed document error.
● rowset-element—(Optional, String value) XML element name to use instead of the

default ROWSET element name for the entire rowset of query results. Set to the empty-
string (" ") to suppress generating a containing ROWSET element.
● skip-rows—(Optional, Integer value) Number of rows to skip before fetching rows from
the result set. Can be combined with max-rows for stateless paging through query
results.
● tag-case—(Optional, String value) Valid values are lower and upper. If not specified, the
default is to use the case of column names as specified in the query as corresponding
XML element names. The default value is lower.
26-205
<xsql:ref-cursor-function>
Executes an arbitrary stored function returning a REF CURSOR and includes the result set in
canonical XML format.
XSQL Syntax
<xsql:ref-cursor-function
[ id-attribute="string" ]
[ id-attribute-column="string" ]
[ max-rows="integer" ]
[ null-indicator="boolean" ]
[ row-element="string" ]
[ rowset-element="string" ]
[ skip-rows="integer" ]
[ tag-case="string" ]
>
PLSQL
</xsql:ref-cursor-function>
Examples
The following example executes the stored function returning REF Cursor and include the
results in XML format:
<xsql:ref-cursor-function max-rows="5" tag-case="lower" null-indicator="yes">

flight_schedule.flights_left_today_for(UPPER('{@airport}'));
The following example executes the stored procedure DynamicQuery which returns a cursor to
the query.
<xsql:ref-cursor-function>
RefCursorExample.DynamicQuery('{@param1}');
Here is the stored procedure DynamicQuery which returns a cursor to the query:
CREATE OR REPLACE PACKAGE RefCursorExample IS

TYPE ref_cursor IS REF CURSOR;
FUNCTION DynamicQuery(userid VARCHAR2) RETURN ref_cursor;
26-206
END;
/
CREATE OR REPLACE PACKAGE BODY RefCursorExample IS

FUNCTION DynamicQuery(userid VARCHAR2) RETURN ref_cursor IS
the_cursor ref_cursor;
my_sal NUMBER := 1;
query VARCHAR2(2000);
BEGIN
IF UPPER(userid) = 'STEVE' THEN
query := 'SELECT ename, sal FROM EMP WHERE ROWNUM < 4';
ELSE
query := 'SELECT dname, deptno FROM DEPT WHERE ROWNUM < 2';
END IF;
OPEN the_cursor FOR query; /* USING var, var, var */
RETURN the_cursor;
END;
END;
/
Description
Executes an arbitrary stored function returning a REF CURSOR and includes the result set in
canonical XML format. Use the wizard's Query panel to enter the required PL/SQL code or the
name of a stored procedure.
Use this tag to invoke a stored procedure that determines what the query is and returns a
cursor to the query. Used in this way, this tag also provides a weak level of security in that it
can hide the query from direct inspection. See the Examples for more information.
Attributes
● max-rows—(Optional, Integer value) Maximum number of rows to fetch, after optionally

skipping the number of rows indicated by the skip-rows attribute. The default value is -1
which fetches all rows.
● skip-rows—(Optional, Integer value) Number of rows to skip before fetching rows from
the result set. Can be combined with max-rows for stateless paging through query
results.
● rowset-element—(Optional, String value) XML element name to use instead of the
default ROWSET element name for the entire rowset of query results. Set to the empty-
26-207
string (" ") to suppress generating a containing ROWSET element.
Note: If you set both row-element and rowset-elementto a blank value (" ") and perform a a
query that returns more than one row, then the parser will return an ill-formed document error.
● row-element—(Optional, String value) XML element name to use instead of the default
ROW element name for the entire rowset of query results. Set to the empty-string (" ") to
suppress generating a containing ROW element for each row in the result set.
● id-attribute—(Optional, String value) XML attribute name to use instead of the default
num attribute for uniquely identifying each row in the result set.
● id-attribute-column—(Optional, String value) Column name whose value should be used
in each row as the value of the id-attribute. Default is to use the row count.
● null-indicator—(Optional, Boolean value) Indicates whether to signal that a column's
value is NULL by including the NULL="Y" attribute on the element for the column. By
default, columns with NULL values are omitted from the output. Valid values are yes and
no. Default value is no.
● tag-case—(Optional, String value) Valid values are lower and upper. If not specified, the
default is to use the case of column names as specified in the query as corresponding
XML element names. Default value is lower.
26-208
<xsql:set-cookie>
Sets the value of an HTTP Cookie, and optionally specifies the maximum age and domain of
the cookie.
XSQL Syntax
<xsql:set-cookie
name="string"
[ domain="string" ]
[ ignore-empty-value="boolean" ]
[ max-age="integer" ]
[ only-if-unset="boolean" ]
[ path="string" ]
[ value="string" ]
>
SQL
</xsql:set-cookie>
Examples
The following example sets the HTTP cookie to the value of the parameter named choice:
<xsql:set-cookie name="last_selection" value="{@choice}"/>
The following example sets the HTTP cookie to a value selected from the database:
<xsql:set-cookie name="shopping_cart_id">
SELECT cartmgr.new_cart_id(UPPER('{@user}')) FROM dual
</xsql:set-cookie>
Description
Sets the value of an HTTP Cookie, and optionally specifies the maximum age and domain of
the cookie. The value of the cookie can be set on the wizard's Value Selector page by either of
the following:
● Clicking the String button and specifying the optional value attribute.
● Clicking the SQL button and including a SQL statement as the element content. If the
SQL statement is provided, the value of the first column of the first row retrieved is used
26-209
as the cookie value.
Only the value attribute or the SQL statement can appear in the Set Cookie tag; they cannot be
used together.
Attributes
● name—(Required, String value) Name of the HTTP Cookie whose value you want to set.
● domain—(Optional, String value) Domain in which the cookie value is valid and
readable. If the domain is not set explicitly, then it defaults to the full domain of the
document creating the cookie.
● ignore-empty-value—(Optional, Boolean value) Indicates whether the cookie assignment
should be ignored if the value to which it is being assigned is an empty string. Valid
values are yes and no. Default value is no.
● max-age—(Optional, Integer value) Sets the maximum age of the cookie in seconds.
Default is to set the cookie to expire when users current browser session terminates.
● only-if-unset—(Optional, Boolean value) Indicates whether the cookie assignment
should only occur when the cookie currently does not exists. Valid values are yes and
no. Default value is no.
● path—(Optional, String value) Relative URL path within the domain in which the cookie
value is valid and readable. If the path is not set explicitly, then it defaults to the URL
path of the document creating the cookie.
● value—(Optional, String value) Value to assign to the cookie. Enter this value by clicking
the String button in the wizard's Value Selector page and entering a value in the editable
field.
26-210
<xsql:set-page-param>
Sets the value of a page-level parameter.
XSQL Syntax
<xsql:set-page-param
name="string"
[ value="string" ]
>
SQL
</xsql:set-page-param>
Example
The following example sets the page-level parameter to a value selected from database. The
value is used in the second code snippet:
<xsql:set-page-param name="max-rows-pref">
SELECT max_rows
FROM user_profile
WHERE userid = {@userid}
</xsql:set-page-param>
...
<xsql:query max-rows="{@max-rows-pref}">
SELECT title, url
FROM newsstory
ORDER BY date_entered DESC
</xsql:query>
Description
Sets the value of a page-level parameter. Use this element to fetch the value of a parameter
from a SQL statement, then refer to the parameter in subsequent action elements in the page.
The value of the page parameter can be set on the wizard's Value Selector page by either of
the following:
26-211
as the parameter value.
Only the value attribute or the SQL statement can appear in the Set Page Param tag; they
cannot be used together.
Attributes
● name—(Required, String value) Name of the page-level parameter whose value you
want to set.
● ignore-empty-value—(Optional, Boolean value) Indicates whether the page-level
parameter assignment should be ignored if the value to which it is being assigned is an
empty string (" "). Valid values are yes and no. Default value is no.
● value—The value to assign to the page parameter. Enter this value by clicking the String
button in the wizard's Value Selector page and entering a value in the editable field.
26-212
<xsql:set-stylesheet-param>
Sets the value of a top-level XSLT stylesheet parameter.
XSQL Syntax
<xsql:set-stylesheet-param
name="string"
[ value="string" ]
>
SQL
</xsql:set-stylesheet-param>
Examples
The following example sets the stylesheet parameter to the value of the parameter named cat:
<xsql:set-stylesheet-param name="current_category" value="{@cat}"/>
This example sets the stylesheet parameter to a value selected from the database:
<xsql:set-stylesheet-param name="security_level">
SELECT role_name
FROM user_profile
WHERE userid = {@userid}
</xsql:set-stylesheet-param>
Description
Sets the value of a top-level XSLT stylesheet parameter.
The value of the stylesheet parameter can be set on the wizard's Value Selector page by either
of the following:
26-213
Only the value attribute or the SQL statement can appear in the Set Stylesheet Param tag; they
Attributes
● name—(Required, String value) Name of the session-level parameter whose value you
want to set.
● ignore-empty-value—(Optional, Boolean value) Indicates whether the stylesheet
parameter assignment should be ignored if the value to which it is being assigned is an
empty string. Valid values are yes and no. Default value is no.
● value—(Optional, string value) Value to assign to the session parameter. Enter this value
by clicking the String button in the wizard's Value Selector page and entering a value in
the editable field.
26-214
<xsql:update-request>
Updates the rows represented in the (optionally transformed) XML document that has been
posted in the request.
XSQL Syntax
<xsql:update-request
key-columns="string"
table="table"
[ columns="string" ]
[ transform="url" ]<br>
/>
Example
The following example updates the columns in the DEPT table based on DEPTNO key.
<xsql:update-request table="dept" transform="doc-to-dept.xsl"

key-columns="deptno"/>
Description
Updates the rows represented in the (optionally transformed) XML document that has been
posted in the request. If an HTML Form has been posted, then the posted XML document is
Attributes
UPDATE.
● key-columns—(Required, String value) Space-separated or comma-separated list of one
or more column names whose values in the posted document should be used to identify
the existing rows in the table for update.
● columns—(Optional, String value) Space-separated or comma-separated list of one or
more column names whose values will be updated. If this list is supplied, then only these
columns will be updated. Otherwise, all columns will be updated.
26-215
● date-format—(Optional, String) Date format mask to use for interpreting date field values
in the XML being updated. Valid values are those documented for
26-216
<xsql:set-session-param>
Sets the value of a session-level parameter.
XSQL Syntax
<xsql:set-session-param
name="string"
[ value="string" ]
>
SQL
</xsql:set-session-param>
Examples
The following example sets the HTTP Session parameter to the value of the parameter named
userid:
<xsql:set-session-param name="current_user" value="{@userid}"/>
This example sets the HTTP Session parameter to a value selected from the database.
<xsql:set-session-param name="current_user">
SELECT member_id
FROM member_session_info
WHERE session_id = {@sessionCookie}
</xsql:set-session-param>
Description
Sets the value of a session-level parameter.
The value of the session parameter can be set on the wizard's Value Selector page by either of
the following:
26-217
Only the value attribute or the SQL statement can appear in the Set Session Param tag; they
Attributes
● name—(Required, String value) Name of the session-level parameter whose value you
want to set.
● ignore-empty-value—(Optional, Boolean value) Indicates whether the session parameter
assignment should be ignored if the value to which it is being assigned is an empty string
(" "). Valid values are yes and no. Default value is no.
● value—(Optional, String value) Value to assign to the session parameter. Enter this
value by clicking the String button in the wizard's Value Selector page and entering a
value in the editable field.
26-218
View Object - Show data
Renders canonical XML data from a business components view object and optionally any
number of levels of related, view-linked view objects.
Action Handler Class
oracle.xml.xsql.ViewObject
Syntax
<xsql:action handler="oracle.xml.xsql.ViewObject"
name="SomeView"
appmodule="fully.qualified.AppModuleName"
connname="someconnection"
/>
Legal values for connname are any XSQL connection definitions that reside in the
XSQLConfig.xml file found in the server classpath. In JDeveloper, this will typically be in
J:\lib\XSQLConfig.xml (with J:\ being the JDeveloper installation home).
The name attribute must be the name of a view usage in the application module.
This approach (using connname) uses Business Components for Java in local mode
exclusively.
Alternatively, a user can use Business Components for Java application module configurations
to specify the connection information for the application module. In this case, the connname
attribute must not appear, and instead the configname attribute appears in its place:
name="SomeView"
configname="someconfigname"/>
The legal values for configname are the configurations defined in the bc4j.xcfg file which
resides in the ./common subdirectory of the package directory for the package in which the
application module resides. So, if the application module is "a.b.c.MyModule" then the valid
confignames will be in file ./a/b/c/common/bc4j.xcfg in the runtime classpath.
Description
26-219
Renders canonical XML data from a business components view object and optionally any
number of levels of related, view-linked view objects.
In addition to the optional attributes shown at the bottom of this page, an optional <where>
element can be nested inside the <xsql:action handler="oracle.xml.xsql.ViewObject"> tag to do
query-by-example functionality. The <where> element can contain any number of nested
<attribute> elements to provide query-by-example criteria against that attribute name.
name="ViewUsageName"
configname="someconfigname">
<where>
<attribute name="attrname1" value="someval2"/>
<attribute name="attrname2" value="someval2"/>
</where>
</xsql:action>
As with any XSQL Action Handler, XSQL attributes can be used anywhere attribute values are
provided, so the entire use (or any part of it) can be driven by attribute values like:
name="ViewUsageName"
configname="someconfigname">
<where>
<attribute name="{@attr}" value="{@val}"/>
</where>
</xsql:action>
There is also a new nested element that can appear inside any usage of the
"oracle.jbo.xsql.ViewObject" action handler named <view-attribute-list>. You can use this <view-
attribute-list> element to specify additional metadata per view object that lists which attributes to
include.
If you do not include a <view-attribute-list> element for a particular viewdef name, then the
default is to include all attributes for that view. The syntax of the <view-attribute-list> element
26-220
(which must appear as a nested child of the <xsql:action> element is:
<view-attribute-list
viewdefname="String"
include-only="Space-or-comma-separated-list-of-attr-names"/>
The order of the attribute names in the space-separated or comma-separated include-only="xx

yy zz" is relevant. For example:
viewdefname="foo.barView"
include-only="EmpName Salary"/>
will produce XML with attribute EmpName before Salary, and:
viewdefname="foo.barView"
include-only="Salary EmpName"/>
will produce XML with attributeSalary before EmpName.
The following example shows the use of the <view-attribute-list> element.
<xsql:action handler="oracle.jbo.xsql.ViewObject"
name="DepartmentsView"
appmodule="test.HRModule"
configname="HRModuleLocal"
dlist="DepartmentName EmployeesView"
name=""
elist="FirstName LastName">

<where>
<attribute name="DepartmentName" value="{@name}"/>
</where>

26-221
<view-attribute-list viewdefname="test.EmployeesView"
include-only="{@elist}"/>

<view-attribute-list viewdefname="test.DepartmentsView"
include-only="{@dlist}"/>
</xsql:action>
Attributes
● max-rows—(Optional, number value) If specified, limits the number of rows retrieved to

the non-negative number N. If not specified, the default value if this optional attribute is "-
1" which means "all rows" (in other words, no maximum).
● skip-rows—(Optional, number value) If specified, skips the initial N rows retrieved from
the view before beginning to generate XML for the remaining rows. Rows that are
skipped do not count towards the max-rows limit, if specified. For example, specifying the
combination of skip-rows="10" and max-rows="10" would retrieve the effective rows 11
through 20.
● max-levels—(Optional, number value) If specified, limits the number of levels of depth
that view link accessor attributes will be traversed. If not specified, the default is "-1" for
no limit. For example, if you have DeptView linked to EmpView linked to DependentView
and you use this action handler against the top DeptView, a value of max-levels="0"
would retrieve only the DeptView information. max-levels="1" would retrieve DeptView
and related EmpView information. max-levels="2" would retrieve both nested levels of
EmpView and DependentView information.
26-222
View Object - Update data
Processes inserts, updates, and deletes to rows in a view object and and any number of levels
of related, view-linked view objects, based on an optionally transformed XML document.
Action Handler Class
oracle.xml.xsql.UpdateViewObject
Syntax
<xsql:action handler="oracle.xml.xsql.UpdateViewObject"
name="SomeView"
connname="someconnection"/>
Legal values for connname are any XSQL connection definitions that reside in the
XSQLConfig.xml file found in the server classpath. In JDeveloper, this will typically be in
J:\lib\XSQLConfig.xml (with J:\ being the JDeveloper installation home).
The name attribute must be the name of a view usage in the application module.
This approach (using connname) uses Business Components for Java in local mode
exclusively.
Alternatively, a user can use Business Components for Java application module configurations
to specify the connection information for the application module. In this case, the connname
attribute must not appear, and instead the configname attribute appears in its place:
<xsql:action handler="oracle.xml.xsql.UpdateViewObject"
name="SomeView"
configname="someconfigname"/>
The legal values for configname are the configurations defined in the bc4j.xcfg file which
resides in the ./common subdirectory of the package directory for the package in which the
application module resides. So, if the application module is "a.b.c.MyModule" then the valid
confignames will be in file ./a/b/c/common/bc4j.xcfg in the runtime classpath.
Description
26-223
Processes inserts, updates, and deletes to rows in a view object and and any number of levels
of related, view-linked view objects, based on an optionally transformed XML document.
Use the Property Values page to set the attribute values of the View Object - Update data tag.
The oracle.xml.xsql.ViewUpdateObject action handler supports several optional features.
As with any XSQL Action Handler, XSQL attributes can be used anywhere attribute values are
provided, so the entire use (or any part of it) can be driven by parameter values.
Attributes
● max-levels—(Optional, number value) If specified, limits the number of levels of depth

that view link accessor attributes will be traversed. If not specified, the default is "-1" for
no limit. For example, if you have DeptView linked to EmpView linked to DependentView
and you use this action handler against the top DeptView, a value of max-levels="0"
would process only the DeptView information from the XML document. max-levels="1"
would process DeptView and related EmpView information, and so on.
● transform—(Optional, URL value) If specified, uses the XSLT stylesheet whose relative
URL is given to transform the incoming XML document into canonical XML format before
passing it to the indicated view object for processing.
26-224
Compiling and Debugging Reference
● Add Class Folder
● Adjust Range Dialog
● Attach to OJVM/JPDA Dialog
● Breakpoints Window
● Classes Window
● Data Window
● Default Run Target Dialog
● Edit Filters Dialog
● Heap Window
● Inspector Window
● Listen for JPDA
● Log Window - Compiler
● Log Window - Debugger Process
● Log Window - Running Process
● Modify Class Folder Name
● Modify Value Dialog
● Modify Watch or Modify Inspect Expression Dialog
● Monitors Window
● New/Edit Breakpoint - Actions Page
● New/Edit Breakpoint - Conditions Page
● New/Edit Breakpoint - Definition Page
● Project Settings - Compiler Panel
● Project Settings - Debugger Panel
● Project Settings - Debugger Tracing Panel
● Project Settings - Runner Options Panel
● Project Settings - Runner Panel
● Remote Debugging and Profiling Wizard - Finish
27-1
● Remote Debugging and Profiling Wizard - J2SE Version and Libraries
● Remote Debugging and Profiling Wizard - Project Directory and File Name
● Remote Debugging and Profiling Wizard - Protocol
● Remote Debugging and Profiling Wizard - Specifiying Java Source Directories
● Remote Debugging and Profiling Wizard - Welcome
● Smart Data Window
● Source Not Found Dialog
● Stack Window
● Threads Window
● Tools | Preferences - Debug Windows - Breakpoints - Default Action Panel
● Tools | Preferences - Debug Windows | Monitors Panel
● Tools | Preferences - Debug Windows - Breakpoints Panel
● Tools | Preferences - Debug Windows - Classes Panel
● Tools | Preferences - Debug Windows - Data Panel
● Tools | Preferences - Debug Windows - Heap Panel
● Tools | Preferences - Debug Windows - Inspector Panel
● Tools | Preferences - Debug Windows - Monitors - Threads Panel
● Tools | Preferences - Debug Windows - Smart Data Panel
● Tools | Preferences - Debug Windows - Stack Panel
● Tools | Preferences - Debug Windows - Threads Panel
● Tools | Preferences - Debug Windows - Watch Window Panel
● Tools | Preferences - Debug Windows Panel
● Tracing Dialog
● Tracing Exclude Edit Dialog
● Tracing Include Edit Dialog
● View Whole Value Dialog
● Watch Window
27-2
Add Class Folder to Heap
A class folder lets you see all the instances of a particular type that are in the heap of the
program you are debugging.
Enter Name of Class

Enter the fully-specified name of a class including the package name. To specify an
array type, add brackets [] after the class name. For example,
java.awt.geom.Dimension2D[].
In the Heap window, a new folder, labeled with the class name and the number of
instances that the folder contains, is added at the bottom of the Heap window. When the
new folder is expanded, child nodes are displayed, one for each instance. The memory
address of the instance is displayed in the Name column for each child node.
Notes:
Be sure to spell your class names correctly as the debugger does not verify if the class
name is valid.
You can also create a class folder in the heap by dragging a class node from the Classes
window and dropping it onto the Heap window.
Related Topics

Examining Program State with Debugger Windows
27-3
Adjust Range Dialog
In the Data window, when an array is expanded, child nodes are displayed for the elements of
the array. However, to avoid lengthy delays when a large array is expanded, JDeveloper only
displays the first 100 array elements. Use the Adjust Range dialog to change the number of
array elements that are displayed when the array is expanded.
You would adjust the range of an array in the following situations:
● If you want to see more array elements when you expand the selected array. Since, by
default, JDeveloper only displays the first 100 array elements in a large array, you would
have to specify a range to display more than 100 arrays.
● If you want to view fewer array elements when you expand the selected array.
Sometimes displaying all the elements of an array can be distracting. Displaying only
part of an array can allow you to focus on only those elements which are of immediate
interest to you during your debugging session.
Note: This dialog does not let you modify the array itself. This dialog only lets you control which
array elements are displayed when you expand the selected array node.
Start Index
Enter the index of the first array element you want displayed when you expand the
selected array node. If you want to start at index 2 (skipping elements 0 and 1), then
enter 2. The minimum start index is zero (0).
Count
Enter the maximum number of array elements that you want to display. For example, if
you want to display three elements when you expand the selected array node, enter 3.
Related Topics
27-4
Attach to OJVM/JPDA Dialog
Use this dialog box to establish a connection between the debugger (attacher) and a debuggee
(listener). The debugger can connect to the Java Virtual Machine (JVM) which was started with
the appropriate debugging command line options. The debugger supports both the Oracle Java
Virtual Machine (OJVM) debugging protocol and Sun Microsystem's Java Platform Debugger
Architecture (JPDA). You must specify which debugging protocol you are using in the Project |
Project Settings - Debugger panel.
Starting the Debuggee Process
You must start the debuggee process before you attempt to attach to it.
Examples
To run OJVM:
java -ojvm -XXdebug,port4000 ...
To run JPDA:
Java -classic -Xdebug -Xnoagent -Djava.compiler=NONE -

Xrunjdwp:transport=dt_socket,address=4000,server=y ...
For more information about JPDA Connection and Invocation, see

Host
Enter the host name or the IP address of the machine where the remote debuggee has
been started. If you are running the debuggee on the local machine (localhost), you can
leave this field blank.
Port
Enter the port number for the remote debuggee, which was specified in the command
line options when you started the debuggee process. In the example given above, 4000
is the port number.
Save Parameters
If you want to bypass this dialog box the next time you attach to OJVM or JPDA,
select this check box. As a result, the debugger automatically attempts to connect
to the remote debuggee when you click Debug .
27-5
Note: This setting can be cleared in the Configuring Your Project for Debugging by
clicking Unsave Parameters.
Related Topics
27-6
Breakpoints Window
Use this window to view a list of all the breakpoints that are active for the current project. This
would include all global breakpoints, breakpoints whose scope is the current workspace, and
breakpoints whose scope is the current project.
The columns displayed in this window depend on those column settings that were checked in
the Tools | Preferences - Debugger - Breakpoints Panel or by choosing Settings... from the
Breakpoints window context menu options which you can access by right-clicking in the
Breakpoints window.
The Context Menu options are described below.
The icon next to each breakpoint and the value in the Status column provide information about
the status of the breakpoint, including whether the breakpoint is enabled or disabled, and
whether the breakpoint has been verified by the debugger.
Verified
When the debugger is running, it verifies a breakpoint when the method or class
containing the breakpoint is loaded by the debuggee Java Virtual Machine.
Note: The Debugger verifies deadlock breakpoints when it connects to the debuggee
Java Virtual Machine. Not all Java Virtual Machines support deadlock detection; for
example, the HotSpot VM does not support deadlock detection.
Unverified
When the debugger is not running, all the breakpoints are listed as Unverified. When the
debugger is running, a breakpoint that has not been verified is listed as Unverified.
Enabled
When a breakpoint is enabled, it means that the conditions and actions are executed
when the breakpoint is encountered.
Disabled
A breakpoint that has been disabled, is ignored by the Debugger.
Context Menu
The following context menu options may be available from the Breakpoints window depending
on whether they apply to the currently selected node in the Breakpoints window. Right-click in
the Breakpoints window to display the context menu options including:
27-7
Go to Source for Breakpoint
(Only available for source breakpoints.) Displays the location of the source breakpoint
directly in the Code Editor.
Disable Breakpoint
If chosen for a given breakpoint, the breakpoint's status is changed from Unverified to
Disabled. If a breakpoint is disabled from the Breakpoint window, execution does not halt
at that breakpoint when the program is running in the Debugger. The context menu
options changes appropriately. The next time the context menu is accessed, the "Disable
Breakpoint" menu item will be replaced with "Enable Breakpoint."
Enable Breakpoint
The breakpoint becomes enabled, which means that the conditions and actions are
executed when the breakpoint is encountered. The context menu options change
appropriately. The next time the context menu is accessed, the "Enable Breakpoint"
menu item will be replaced with "Disable Breakpoint."
Remove Breakpoint
The breakpoint is removed from the Breakpoints window as well as from the Code Editor.
Edit Breakpoint...
Displays the Edit Breakpoint dialog box from which you can make changes to the
breakpoint's definition, conditions, and actions.
Change Scope
Displays a sub-menu with three menu items you can use to change the scope of the
breakpoint: Global, Workspace, and Project. Global breakpoints are active whenever you
are debugging, regardless of what project you are using.
Workspace breakpoints are active whenever you are debugging a project in the specified
workspace.
Project breakpoints are active only when you are debugging the specified project.
New Breakpoint...
Displays the New Breakpoint dialog box from which you can specify details about the
new breakpoint's definition, conditions, and actions.
Disable All
Disables all the breakpoints. When the Debugger is run, it ignores disabled breakpoints.
Enable All
Enables all the breakpoints. When a breakpoint is enabled, it means that the conditions
and actions are executed when the breakpoint is encountered.
Remove All
27-8
All breakpoints are removed from the Breakpoints window as well as from the Code
Editor.
Note: Persistent breakpoints cannot be removed.
Settings...
Displays the Tools | Preferences - Debugger - Breakpoints settings, from which you can
choose which columns you want to appear in the Breakpoints window.
Expand All
Expands all breakpoint group nodes.
Collapse All
Collapses all breakpoint group nodes.

Export...
Saves the contents of the Breakpoints window in its current state to a text file.
Enable Group
A breakpoint group folder must be selected for this option to be available. Enables all the
breakpoints contained in the selected group. When a breakpoint is enabled, it means that
the conditions and actions are executed when the breakpoint is encountered.
Disable Group
A breakpoint group folder must be selected for this option to be available. Disables all the
breakpoints contained in the selected group. When the Debugger is run, it ignores
disabled breakpoints.
Remove Group
A breakpoint group folder must be selected for this option to be available.
All breakpoints in the specified group are removed from the Source and Breakpoints
window.
Related Topics

About Deadlocks
27-9
Setting Preferences for the the Debugger Windows
27-10
Classes Window
Use this window to view a list of loaded classes and their status in reference to tracing, a count
of the number of instances in the heap for each class listed, and the amount of memory being
consumed by variables of listed class. In addition to classes, this window displays information
about interfaces, arrays, and packages.
By default, only the Class column displays. If you want to display the Memory and Count
columns, enable them by choosing the Tools | Preferences - Debugger - Classes panel or by
choosing Settings... from the Classes window context menu options which you can access by
right-clicking in the Classes window.
Also, note that only the Oracle Java Virtual Machine (OJVM) provides the memory and count
information. The memory and count information is not provided by Sun JPDA, the debugging
protocol used with the Classic and HotSpot Java Virtual Machines. If you are using either the
Classic or the HotSpot virtual machine (the VM is specified in the Project | Project Settings -
Runner Panel), the count and memory information will not be displayed.
Other functions you can perform from this window include:
● In a flat list display (which displays when the Show Package Structure check box is not
checked in the Tools | Preferences - Debugger - Classes Panel), clicking a column
header sorts the information. For example, clicking Memory sorts the information by how
much memory each class consumes.
● Clicking the garbage collection icon in the main toolbar forces garbage collection to
occur which may decrease the count and memory usage.
● You can drag a class or array node from the Classes window and drop it onto the Heap
window to create a Class Folder in the Heap window.
Note: In the class list, if an icon is dimmed or grayed, this indicates that tracing is disabled. If
an icon is not dimmed (appears normal), this indicates that tracing is enabled. If icon
appears, this indicates that tracing is enabled, but that the debugger does not have sufficient
information (for example, the class does not contain line number tables) to permit tracing in the
class. The class may have been obfuscated.
Context Menu
The following context menu options may be available from the Classes window. Right-click in
27-11
the Classes window to display the context menu options including:
Go to Source for <classname>

Only available if the selected node is a class or an interface; this option is not available
when the selected node is an array or a package. Displays the source code for the class
or interface in the Code Editor.
You can also double-click an item in this window list to go directly to the source code.
Tracing...
Displays the Tracing dialog from which you can adjust the Tracing Include and/or
Tracing Exclude lists to enable and disable tracing on specified packages and classes.
Expand All/Collapse All
Only available if the Show Package Structure check box is checked in the Tools |
Preferences - Debug Windows - Classes panel. As a result, all the package nodes
expand or collapse.
Settings...
Displays the Tools | Preferences - Debugger - Classes panel which lets you set the
window settings including the columns that appear in the Classes window as well as
other display options.
Export...
Saves the contents of the Classes window in its current state to a text file.
Related Topics

Show and Hide Fields in Filtered Classes List
27-12
Data Window
Use this window to see information about arguments, local variables, and static fields, for the
current method. The columns which display in this window depend on those column settings
that were enabled in the Tools | Preferences - Debugger - Data Panel or by choosing
Settings... from the Data window context menu options which you can access by right-clicking
in the Data window.
When you click an item in the Stack window, the Data, Watches, and Inspector windows all
update. These windows work in conjunction with one another and show you data in a given
context. Expand the branches to display more details about your data.
Note: If you are stepping through code and want to see the data that relates to the source
code, consider using the Smart Data window which displays all the variables and fields that are
used in the lines of code that you are stepping through.
Other functions you can perform from the Data window include:
● Drag a data item from the Data window and drop it onto the Watches window to add a
new expression to the watch window.
● Drag an object or array from the Data window and drop it onto the Heap window to
create a class folder in the Heap window.
Context Menu
The following context menu options may be available from the Data window depending on if
they apply to the currently selected item in the Data Window. Right-click in the Data window to
display the context menu options including:
View Whole Value...

Displays the value in its entirety in a multiline text field in a modal dialog box. Available
for String, byte array, char array, short array, int array, and long array.
Adjust Range...
Lets you control how many elements of the selected array are displayed when you
expand the node. Available only for arrays.
Toggle Value
27-13
(Applies to booleans only.) Modifies the value of a boolean data item. If the value is true
then selecting this option will make it false. If the value is false then selecting this
option will make it true.
Modify Value...
Displays the Modify Value dialog box which lets you modify the value for the selected
data item.
Watch
The selected data item is added to the Watch window.
Inspect
Creates a floating Inspector window for the selected data item.
Go to Source for <type of object>
Only available if the type of the selected data item is a class; not available for an array or
a primitive type. Displays the source code for the class in the Code Editor.
Note: If the Declared Type column is visible and the declared type is different than the
actual type, then there will be two Go to Source options on the context menu: one for the
actual type, and one for the declared type.
Use Filters
Lets you enable and disable the class filters you set in the Edit Filters dialog box without
having to remove them from the Filtered Classes list.
Edit Filter for <type of object>
Lets you go directly to the Edit Filters dialog box for this specific class from which you
can specify filters to control which fields are displayed and which fields are not displayed
when you expand an object.
Edit Filters...
Lets you go directly to the Edit Filters dialog box from which you can specify filters to
control which fields are displayed and which fields are not displayed when you expand
an object.
Settings
Displays the Tools | Preferences - Debugger - Data panel from which you can choose
the columns and other display options to appear in the Data window.
Collapse All
Causes all the branches to collapse, so that the data is not visible below the branches.
Note: In the Data window, there is no Expand All option on the context menu. This is
because the complete tree would contain far too many branches and because data items
may contain circular references which would cause the debugger to go into an infinite
27-14
loop while trying to expand the branches.
Export...
Saves the contents of the Data window in its current state to a text file.
Related Topics

27-15
Default Run Target Dialog
This dialog is displayed when you run a project for which no Default Run Target was specified
in the Project | Project Settings - Runner Panel. Use this dialog to specify the Default Run
Target.
Default RunTarget
The dropdown list contains all the files in your project which may be possible run targets.
A run target can be a Java application, a Java servlet, a Java Server Page (JSP), an
HTML file, an XSQL file, a UIX file, or a JDeveloper Addin. Choose the Default Run
Target for this project from the dropdown list, or click Browse to locate a run target
outside of your project.
Note: The Default Run Target does not have to be a file contained in the project. For
example, you may be working in a workspace with multiple projects, where each project
is just part of a large program. You may set the Default Run Target for each of the
projects to be a specific Java class which is contained in only one of the projects.
If this option is selected, the runner will attempt to run the current node in the active view.
is active. If that file is not runnable, then the Runner attempts to run the project's
specified Default Run Target.
If this option is no selected, the Runner runs the project's specified Default Run Target.
Related Topics

27-16
Edit Filters Dialog
Use this dialog to reduce the number of fields that display when you expand an object in any of
JDeveloper's data-related windows including the Smart Data window, the Data window, the
Inspector window, the Watch window, the Heap window, and the left-hand side of the Monitors
window. Displaying fewer fields narrows your focus when debugging and may make it easier to
locate and isolate potential problems in your program. In the Edit Filters dialog, you can easily
traverse the superclass hierarchy for any class, defining or updating the filters for each
superclass.
Filtered Classes
Lists all the classes for which there are filters defined. The list is initially empty if you
have not defined any filters yet.
Superclass
Click to define/update the filter for the superclass of the currently selected class in
the Filtered Classes list.
Click this button as many times as you want to traverse the superclass hierarchy.
The next class in the superclass chain is displayed each time you click this button.
You can repeat this action until it reaches the base class (java.lang.Object)
at which time this button becomes dimmed (gray).
Subclass
Click to return to the previous subclass after pressing the Superclass button.
Add
Click to add a class to the Filtered Classes list. The Class Browser dialog is
displayed, from which you can choose any class which is accessible in you
project.
Remove
Click to remove the selected class from the Filtered Classes list.
Fields to Show
Lists the fields declared in the class selected in the Filtered Classes list, that you want to
be displayed when you expand an object of that type in the Data window.
Note: When you add a new class to the Filtered Classes list, initially all of the fields
declared in that class will be listed in the Fields to Show box. Use the shuttle buttons to
move some (or all) of the fields to the Fields to Hide box.
Fields to Hide
27-17
Lists the fields declared in the class selected in the Filtered Classes list, that you do not
want to be displayed when you expand an object of that type in the Data window.
Note: When you add a new class to the Filtered Classes list, the Fields to Hide box will
be empty until you use the shuttle buttons to move fields from the Fields to Show box.
Related Topics

27-18
Heap Window
Use this window to display information about objects and arrays located in the heap of the
program you are debugging. The columns which display in this window depend on those
column settings that were enabled in the Tools | Preferences - Debugger - Heap Panel or by
choosing Settings... from the Heap window context menu options which you can access by
right-clicking in the Heap window.
Note: Only the Oracle Java Virtual Machine (OJVM) provides heap information. Heap
information is not provided by Sun Microsystem's Java Platform Debugger Architecture (JPDA),
the debugging protocol used with the Classic and HotSpot Java Virtual Machines. If you are
using either the Classic or the HotSpot virtual machine (the VM is specified in the Project |
Project Settings - Runner Panel), the Heap window will not be able to provide any information
about the heap in the program you are debugging.
Remember that Java uses an automatic storage memory management system, commonly
called the garbage collector. This means that when an object is no longer used, it is
automatically reclaimed by the garbage collector.
Note: It is important to make sure that the garbage collection system has been forced to
reclaim any unreferenced objects before you begin your investigation. Before you begin using
the Heap window, you should click the Garbage Collection icon on the toolbar. This will
ensure that unused objects have been removed from the heap.
The Heap window contains two different types of folders: class folders and reference path
folders.
What is a class folder?
A class folder lets you see all the instances of a particular class or array type that are in the
heap of the program you are debugging. For example, you may want to see all the instances of
java.awt.Rectangle that are in the heap.
You can create a class folder in any of the following ways:
● Right-click in the Heap window and choose Add Class Folder...

● Drag-and-drop a class from the Classes window.
● Drag-and-drop an object or array from the Data window.
27-19
In the Heap window, a new folder, labeled with the class name and the number of instances
that the folder contains, is added at the bottom of the Heap window. When the new folder is
expanded, child nodes are displayed, one for each instance. The memory address of the
instance is displayed in the name column for each child node.
What is a reference folder?
A reference path folder lets you understand why a particular object is still in the heap and has
not been reclaimed by the garbage collector. A reference path folder in the Heap window
contains all the reference paths that lead to a particular object in the heap. When there are no
reference paths that lead to an object, the object can be reclaimed by the garbage collector.
A reference path starts with what is called a root reference. A root reference is usually a stack
variable, a static field, or an object that has been pinned by Java Native Interface (JNI). Due to
implementation details in a garbage collection system, a root reference can also be a thread
register or a stack area. A reference path displayed in the Heap window will show you the root
reference and the chain of references between the root reference and the particular object you
are investigating.
To create a reference path folder, a class folder must exist (see above for instructions on
creating a class folder). Expand the class folder and look at the instances (the child nodes of
the class folder). Choose one instance that you would like to investigate; let's call that object
the target object. Right-click on the target object and choose Show Reference Paths from the
context menu. A new folder, labeled Reference Paths to <instance address> will be added to
the bottom of the Heap window. When the new folder is expanded, child nodes are displayed,
one for each root reference that leads to the target object. The depth of the chain from the root
reference to the target object is displayed in the Value column. To expand the reference path
fully, from the root reference to the target object, right-click on the root reference and choose
Expand Reference Path.
Context Menu
The following context menu options may be available from the Heap window depending on if
they apply to the current selected node in the Heap window.
Show Reference Paths

Available when an instance node within a class folder is selected. Adds a reference path
folder for the selected instance to the bottom of the Heap window.
Expand Reference Path
27-20
Available when a reference root or an object within a reference path is selected. Expands
the shortest path from the selected object to the target object.
Modify Class Name...
Displays the Modify Class Folder Name dialog from which you can edit an existing class
folder in the Heap window. For example, you may want to edit this name because it was
misspelled or the incorrect class was specified.
Remove Folder
Available when a class folder or a reference path folder is selected. Removes the folder
from the Heap window.
View Whole Value...
Adjust Range...
Toggle Value
Modify Value...
data item.
Watch
Inspect
Use Filters
27-21
Edit Filters...
an object.
Add Class Folder...
Displays the Add Class Folder dialog from which you can add a new class folder to the
Heap window.
Remove All Folders
Removes all folders (class folders and reference path folders) from the Heap window.
Settings...
Displays the Tools | Preferences - Debugger - Heap Panel from which you can choose
the columns and other display options to appear in the Heap window.
Collapse All
Note: In the Heap window, there is no Expand All option on the context menu. This is
Export...
Saves the contents in the Heap window in its current state to a text file.
Related Topics

27-22
27-23
Inspector Window
Use this window to evaluate and display a single expression. The columns which display in this
window depend on those column settings that were enabled in the Tools | Preferences -
Debugger - Inspector Panel or by choosing Settings... from the Inspector window context
menu options which you can access by right-clicking in the Inspector window.
An Inspector window is similar to the Watches window except for the following differences:
● An Inspector window evaluates only one expression, while the Watches window
evaluates a list of expressions.
● You can have many Inspector windows, while there is only one Watches window.
● Inspector windows are initially floating windows. You can dock them if you wish, but they
start out as floating windows.
You can create a new Inspector window in either of these ways:
● Right-clicking an item in the Data window or Smart Data window and choosing Inspect
● Right-clicking in the Code Editor, choosing Inspect... from the context menu, and
entering an expression.
Context Menu
The following context menu options may be available from the Inspector window depending on
if they apply to the currently selected item in the Inspector Window. Right-click in the Inspector
window to display the context menu options including:
Edit Expression ...

Available when the Inspector window's expression is selected. Displays the Modify
Inspect Expression dialog, from which you can edit the expression for this Inspector
27-24
window.
Pin Object
Available only when the Java Virtual Machine of the debuggee (specified in the Project |
Project Settings - Runner Panel) is OJVM, the Inspector window's expression is
selected, and the evaluation of that expression produces an object or array. Changes the
way the Inspector window evaluates the expression so that instead of evaluating the
expression in the context of the selected stack frame (the normal behavior), the Inspector
window will show the value at a specific memory address. The memory address is
determined by the address of the object or array at the time of the Pin Object operation.
Unpin Object
Available only when the selected expression has been pinned. Restores the normal
behavior of the Inspector window so that the expression is evaluated in the context of the
selected stack frame.
View Whole Value...
Adjust Range...
Toggle Value
Modify Value...
data item.
Watch
Inspect
27-25
Use Filters
Edit Filters...
an object.
Settings
Displays the Debugger - Inspector panel from which you can choose the columns and
other display options to appear the Inspector window.
Collapse All
Note: In the Inspector window, there is no Expand All option on the context menu. This is
Export
Saves the contents of the Inspector window in its current state to a text file.
Related Topics

Show and Hide Fields in Filtered Classes
27-26
Listen for JPDA
Use this dialog box to start the debugger listening for JPDA at a specified port so that a
debuggee can attach to the debugger via Sun Microsystem's JPDA debugging protocol. For
more information about JPDA Connection and Invocation, see
Note: You must start the debugger listening before you attempt to start the debuggee process.
When starting the debuggee process, run a command similar to the following:

Xrunjdwp:transport=dt_socket,address=4000,server=n ...
Port
Enter the port number at which you want to the debugger to listen. The port number
specified here must match the port number specified in the command line argument you
will use when you start the debuggee process. For example, in the above command, the
port number is 4000.
Save Parameters
If you want to bypass this dialog box the next time you want to start the debugger
listening for JPDA, select this check box. This will cause the debugger to
automatically start listening for JPDA when you click Debug in the toolbar.
Note: This setting can be cleared by clicking Unsave Parameters from the Project
| Project Settings - Debugger - Remote panel.
Related Topics

27-27
Log Window - Compiler
A Log Window Compiler tab panel displays a list of all warnings and errors encountered after
Make or Build is executed. If no errors or warnings are found, the Compiler tab would not
appear in the Log window.
All error and warning messages are displayed in a tree structured format. You can double-click
any message to go directly to the source file location corresponding to the selected message.
Messages and errors appear from the Compiler tab for only one Make or Build command at
any given time. Any information from a previous make or build is deleted upon a new invocation
of the Make or Build command.
Related Topics

27-28
Log Window - Debugger Process
A Log Window Debugger Process panel displays the same information as a Log Window
Running Process panel including the following additional information:
● Status messages about the connection between the debugger and the debuggee
process.
● Message logged when a breakpoint occurs and the breakpoint has Log selected as one
of its actions.
● Status message about the termination of the connection between the debugger and the
debuggee process.
Related Topics
About the Debugger

27-29
Log Window - Running Process
A Log Window Running Process panel may display the following information, depending on the
settings specified in the Project Settings - Runner Options Panel:
● The command line used to launch the process.

● The redirected output from the System.out PrintStream.
● The redirected output from the System.err PrintStream.
● The exit code for the process.
In addition, you can also use the Log Window to enter console-style input into your program.
Console-style input can be read by a Java program using the System.in InputStream.
You can perform a number of tasks including Clear, Copy, Save As, and Close by right-clicking
either on the tab or within the window itself and choosing the desired option from the context
menu.
Related Topics
About the Debugger

27-30
Modify Class Folder Name
Use this dialog to edit an existing class folder in the Heap window. For example, you may want
to edit this name because it was misspelled or the incorrect class was specified.
A class folder lets you see all the instances of a particular type that are in the heap of the
program you are debugging. Use this dialog to edit the class name for an existing class folder
in the Heap window:
Modify Name of Class

Enter the fully-specified name of a class including the package name. To specify an
array type, simply add [] after the class name. For example,
java.awt.geom.Dimension2D[].
In the Heap window, the existing class folder is replaced with a new folder, labeled with
the new class name and the number of instances that the folder contains. When the new
folder is expanded, child nodes are displayed, one for each instance. The memory
address of the instance is displayed in the name column for each child node.
Note: Be sure to spell your class names correctly as the debugger does not verify if a
class of that name actually exists.
Related Topics

27-31
Modify Value Dialog
Use this dialog box to modify the value for the selected data item. You can modify primitive
values, strings, and reference pointers.
Note: You cannot undo action on this dialog so be careful when making any changes.
Current Value
Displays the value of the data item. You can select this item to copy but you cannot edit
this value.
New Value
Enter the new value or select a previously entered value from the dropdown list.
If you are modifying a primitive value, you can enter a new value.
If you are modifying a reference pointer, you can enter the memory address of an
existing object or array.
If you are modifying a string, you can enter either a new string value or the memory
address of an existing string.
Interpret New Value As An Object Address

If this box is checked, the entry in the New Value field will be interpreted as a memory
address pointer to an object or array in the heap of the program you are debugging.
If you are modifying a primitive value, this box is disabled (cleared); you cannot check it.
If you are modifying a reference pointer (other than a string), this box is enabled
(cleared).
If you are modifying a string, this box is enabled and you must check it if the value you
enter in the New Value field is the memory address of an existing string.
Related Topics

27-32
Modify Watch or Modify Inspect Expression Dialog
Use this dialog to enter or modify a Java expression that you want to watch or inspect from
within the Watches window, Inspect window, or Code Editor. Any of these fields may display
depending on how you accessed this dialog:
Enter Expression to Watch / Enter Expression to Inspect

Enter the Java expression that you want the debugger to watch or inspect. The
expression must be a legal Java expression that the debugger can evaluate. Because
the debugger cannot execute Java methods while evaluating an expression, you cannot
enter any methods in the expression, including the equals method.
Modify Expression to Watch / Modify Expression to Inspect

Modify the Java expression that you want the debugger to watch or inspect. The
expression must be a legal Java expression that the debugger can evaluate. Because
the debugger cannot execute Java methods while evaluating an expression, you cannot
enter any methods in the expression, including the equals method.
Sample Expressions
Simple variable name:

rect
Field access:
rect.width
Array element:
myArray[3]
Array length:
myArray.length
Comparison operation:
rect.height == 100
myArray.length > 7
Arithmetic operation:
rect.width * rect.height
x + y + z
27-33
Logical operation:
frame1.enabled && frame1.visible
textField1.hasFocus || textField2.hasFocus
Instance of operator:
o instanceof java.lang.String
Shift operator:
x << 2
y >> 1
Binary operator:
keyEvent.modifiers & java.awt.event.InputEvent.CTRL_MASK
Question-colon operation:
y>5 ? y*7 : y*4
Static field name:
java.awt.Color.pink
Fully-qualified class name:
java.awt.Color
Related Topics

27-34
Monitors Window
Use the Monitors window to view information about the active monitors in the program that you
are debugging. Monitors are used for synchronization in multi-threaded Java programs and
each monitor is associated with an object in the heap of the program that you are debugging. A
monitor is active when:
● A thread owns the monitor. A thread becomes the owner of a monitor by entering a
synchronized statement or method. Only one thread can own a particular monitor at a
time.
● A thread is waiting on the monitor. A thread waits on a monitor by calling the wait method
for an object.
● A thread is blocked on a monitor. A thread becomes blocked by attempting to gain
ownership of a monitor when another thread is already the owner.
Note: Not all Java Virtual Machines provide monitor information; for example, the HotSpot VM
does not provide monitor information. If you are using the HotSpot VM, the Monitors Window
will not be able to provide any information about the monitors in the program you are
debugging.
Monitors Sub-Windows
When you choose to display the Monitors window, you are presented with several sub-windows
including:
Monitors
Owning Threads
Waiting Threads
Blocked Threads
Monitors
The Monitors sub-window lists all objects whose monitors are active in the program that you
are debugging.
27-35
The columns which display in this window depend on those column settings that were enabled
in the Tools | Preferences - Debugger - Monitors panel or by choosing Settings... from the
context menu options which you can access by right-clicking in the Monitors window.
The Monitors Context Menu options are described below.
Owning Thread
The Owning Thread sub-window contains the thread which owns the monitor selected in the
Monitors sub-window.
Name
Displays the name of the thread.
Status
Displays the current status for the owning thread.
Blocked
The thread is blocked on another object's monitor.
Blocked (Deadlocked)
The thread is blocked on another object's monitor and is deadlocked due to a
monitor block cycle involving this thread.
Waiting
This thread is waiting on another object's monitor.
Sleeping
This thread is sleeping, because it has called the Thread.sleep method.
Runnable
This thread is not blocked, waiting, or sleeping.
Unknown
The status of this thread is unknown.
Waiting Threads
The Waiting Threads sub-window contains the threads which are waiting on the monitor
selected in the Monitors sub-window.
27-36
Name
Status
Waiting
This thread is waiting.
Blocked Threads
The Blocked Threads sub-window contains the threads which are blocked on the monitor
selected in the Monitors sub-window.
Name
Status
Blocked
The thread is blocked.
Blocked (Deadlocked)
The thread is blocked and deadlocked due to a monitor block cycle involving this
thread.
Context Menu
The following context menu options may be available from the Monitors window depending on if
they apply to the currently selected item in the Monitors window. Right-click in the Monitors
window to display the context menu options including
View Whole Value...

Adjust Range...
27-37
Toggle Value
Modify Value...
data item.
Watch
Inspect
Use Filters
Edit Filters...
an object.
Collapse All
Note: In the Monitors window, there is no Expand All option on the context menu. This is
Settings...
27-38
Displays the Monitors Window Settings Panel from which you can choose the columns
and other display options to appear in the Monitors window.
Export...
Saves the contents of Monitors sub-window in its current state to a text file.
Context Menu Options - Owning Thread, Waiting Thread, Blocked

Threads
The following context menu options apply to the Owning Thread, Waiting Thread, Blocked
Threads:
Go to Source for Thread

Displays the location of the selected thread's execution point in the Code Editor.
Settings...
Displays the Tools | Preferences - Debug Window - Monitors Threads Panel from which
you can choose the columns and other display options.
Export...
Saves the selected sub-window contents in its current state to a text file.
Related Topics

27-39
New/Edit Breakpoint - Actions Page
Use this page to specify the actions that you want the debugger to take when the breakpoint
occurs. You can use a combination of these breakpoint actions. The usual action for a
breakpoint is to halt the program you are debugging, but you may want the debugger to beep
and log information to the Log window without halting the program. Setting breakpoint actions
so that information is logged without halting the debugger can be useful for debugging user
interface programming such as mouse event handlers, focus event handlers, and so on.
Halt Execution
Select if you want the debugger to pause the debuggee program when it encounters the
breakpoint.
Beep
Select if you want the debugger to beep when it encounters the breakpoint.
Log Breakpoint Occurrence
Select if you want the debugger to send a message to the log window when it encounters
the breakpoint.
Tag
(optional) Enter a tag which will be displayed in the log window. There are no
formatting rules for the tag, the debugger simply passes it to the log window.
Expression
(optional) Enter an expression which the debugger will evaluate and display in the
log window. The expression is evaluated each time the breakpoint is encountered.
Enable a Group of Breakpoints

Select this check box and choose a group name from the available list. When the
breakpoint is encountered, the breakpoints in the specified group will be enabled.
Disable a Group of Breakpoints
Select this check box and choose a group name from the available list. When the
breakpoint is encountered, the breakpoints in the specified group will be disabled.
Related Topics

27-40
About Deadlocks
27-41
New/Edit Breakpoint - Conditions Page
Use this page to specify the conditions which apply to the breakpoint. The conditions must be
valid for the breakpoint to occur.
Condition
Enter the condition to apply to the breakpoint. A conditional breakpoint occurs only when
the given condition is satisfied (when the condition evaluates to true). For example, if
you enter a > 2 && b > 2, then the breakpoint will only occur when a is greater than
2 and b is greater than 2.
Use standard Java syntax to express the condition. Do not use method calls in the
expression, including the equals method; the debugger cannot evaluate an expression
containing a method call. To use the throw exception object in the condition for an
exception breakpoint, use _throw.
Examples
rect.width > 100
myArray.length != 0
buffer[7] == 'c'
(keyEvent.modifiers &
java.awt.event.InputEvent.CTRL_MASK) != 0
s != null && s.count > 0
o instanceof java.lang.String
_throw.detailMessage.value[0] == 'P'
Thread Options
Choose one of the following:
Break for All Threads

Break if the breakpoint is hit by any thread.
Break Only for Threads Named
Break if the breakpoint is hit by a thread whose name matches the name specified
in this text field.
Break Only for Threads Not Named
Break if the breakpoint is hit by a thread whose name does not match the name
specified in this text field.
27-42
This option is useful for debugging multi-threaded programming where some code
should only be executed on a particular thread. For example, many methods in
Swing (Java Foundation Classes) should only be called on the AWT event
dispatching thread. If you believe that your program may be calling one of these
methods on an incorrect thread, you may want to set a breakpoint and check
Break Only for Threads Not Named and enter AWT-EventQueue-0 in the text
field.
Pass Count
Enter the number of times the debugger should allow execution to pass over the
breakpoint before the breakpoint occurs.
Related Topics

27-43
New/Edit Breakpoint - Definition Page
Use this page to specify the definition of the breakpoint.
Breakpoint Type
Choose the type of breakpoint you want to create. If you are editing an existing
breakpoint, the type of the existing breakpoint will be displayed, but you cannot change
it.
Source
Breakpoint for a specific line of source code. Source breakpoint icons appear in
the margin of the Code Editor. A source breakpoint can be created by clicking the
line number in the Code Editor or by choosing New Breakpoint... from the context
menu in the Breakpoints Window.
Exception
Breakpoint for a specific exception class. The breakpoint will occur when an
exception is thrown.
Note: The JDeveloper debugger automatically creates a persistent exception
breakpoint for uncaught throws for java.lang.Throwable; this breakpoint will
occur whenever an uncaught exception is thrown. You cannot delete a persistent
breakpoint.
Deadlock
Breakpoint for a monitor block cycle deadlock. Not all Java Virtual Machines
support deadlock detection; for example, the HotSpot VM does not support
deadlock detection.
Note: The JDeveloper debugger automatically creates a persistent deadlock
breakpoint; this breakpoint will occur whenever a monitor block cycle is detected.
You cannot delete a persistent breakpoint. You cannot create a new deadlock
breakpoint, but you can edit the existing persistent deadlock breakpoint.
Method
Breakpoint for a method. The breakpoint will occur when the specified method is
executed.
Class
Breakpoint for a class. The breakpoint will occur when any method in the specified
class is executed, just as if a source breakpoint has been placed at the first line of
each method in the class.
Source Breakpoint Details

27-44
Package
Specify the package for the source breakpoint. For example, java.util.
Source File
Specify the source file for the source breakpoint. The source file specified here
should not contain any directory information, but should contain the filename
extension. For example, Vector.java.
Line Number
Enter the line number for the source breakpoint.
Breakpoint Group Name

Enter the name of the breakpoint group to which you would like this breakpoint to belong.
Putting a breakpoint into a breakpoint group is useful for the following reasons:
● You can set a breakpoint's actions so that when the breakpoint occurs, it enables or
disables all the breakpoints in a specific breakpoint group.
● You can edit a breakpoint group so that each breakpoint in the group has the exact same
conditions and actions.
● In the Breakpoints window, you can quickly enable, disable, or remove, all the
breakpoints belonging to a specific breakpoint group.
● In the Breakpoints window, you can expand or collapse breakpoint groups so that you
can focus your attention on specific breakpoints while ignoring others.
Breakpoints belonging to a breakpoint group are displayed in the Breakpoints window as child
nodes of the breakpoint group's parent node.
Related Topics

About Deadlocks
27-45
Project Settings - Compiler Page
Use this page to configure the project's compiler settings in a development environment. Select the
check box to enable the appropriate feature. The following general compiler options are available
and are also available from the command line by entering ojc from the following directory:
<JDEV_HOME>/jdev/bin
Include Debug Information

Allows additional information to be inserted in your code and used to display the values of
local variables and other useful information while debugging your program. As a final step
prior to deploying your program, you may choose to compile your program without selecting
this option to reduce the size of your compiled class files.
Show Warnings
Outputs warning messages as the code is compiled. The messages are displayed in the Log
window's Compiler tab.
Unused Import Warnings

Allows the output of a warning for every single unused narrow import statement found
in the source code being compiled.
Partially Used Import Warnings

Allows the output of a warning for every incomplete use of a wide import statement
found in the source code being compiled, and provides a complete list of narrow import
statements to replace it with.
Deprecation Warnings
Allows the output of a warning for every reference to a deprecated method or class
encountered in the source code being compiled.
Obfuscate
Alters your compiled code, rendering it less vulnerable to reverse engineering. When your
obfuscated code is decompiled, the generated source code contains altered symbol names
for private symbols. As a result, the code is obscure in meaning (cryptic) and difficult to read
for anyone trying to reverse engineer the code.
27-46
Update Imports
Recompiles any imported class files that are not part of the project being compiled and that
are out of date (assuming respective source file is found on the sourcepath and more recent
than the class file).
Include JAR and ZIP Imports

Performs 'Update Imports' from classes found in zip and/or jar archive files.
Note: Typically, included archive files are considered stable and should not be updated
at compile time.
Show Compile Progress

Provides visual feedback in the Log Window's Message View about the compile progress.
Enable J2SE 1.4 Assertions

When selected, the J2SE 1.4 assert statement feature is enabled. Make sure that the
project's J2SE library is 1.4 (or higher) compliant. This option is equivalent to entering the
following OJC command line argument:
-source 1.4
Target
By default, all classes generated by JDeveloper are J2SE 1.3 compliant, but may be
overriden in this project by selecting another target version. This option is equivalent to
entering the following OJC command line argument:
-target x.x
For more information, see
http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javac.html#options
Exclude Class
Eliminates all calls to static void methods of the specified class(es). Use a semicolon
separated list to specify more than one class (for example,
package1.class1;package2.class2).
You can use this option to exclude diagnostic classes used during development from the final
compilation of your program.
Character Encoding
Specifies a native-encoding name to control how the compiler interprets characters beyond
27-47
the ASCII character set. The default setting uses the native-encoding converter for the
platform.
Example
System.out.println(System.getProperty("file.encoding"));
For more information, see Specifying a Native Encoding for Compiling.
Resource File Types to Copy to Output Directory

Enter a semicolon separated list of file types to copy from the source path to the output
directory when invoking the Make or Build command. File types may be extensions and/or file
endings. For example, if you enter .gif, all image files that end with .gif are copied to the
output directory. Similiarly, entering -apf.xml would copy all files ending with -apf.xml filename
to the output directory. The Make/Build command copies only files that are specified in the
project being made or built.
Related Topics

27-48
Project Settings - Remote Debugger Page
Use this page to configure the remote debugging settings:
Remote Debugging
Select if you want to debug a Java process which is or will be running on another
machine, or if you want to start the debuggee process yourself. Choose the debugging
protocol you will be using.
Attach to OJVM
Select if you will be using the Oracle Java Virtual Machine (OJVM) debugging
protocol.
The OJVM has additional features to help you debug your project.
Note: OJVM runs only on Windows NT.
Attach to JPDA
Select if you will be using Sun Microsystem's Java Platform Debugger Architecture
(JPDA) and you would like the debugger to attach to the debuggee process.
Note: Choose this option if you will be using a Java virtual machine other than the
Oracle Java Virtual Machine. For example, choose this option if you will be using
the Classic or HotSpot virtual machine.
Listen for JPDA
Select if you will be using the Sun Microsystem's Java Platform Debugger
Architecture (JPDA) and you would like the debugger to listen so that a debuggee
(attacher) can attach to the debugger.
Note: Choosing this option is unlikely. Usually, the debugger attaches to the
debuggee. In this case, the debugger listens and the debuggee attaches to the
debugger.
Unsave Parameters
Available only after you have chosen to Save Parameters from the Attach to
OJVM dialog box, Attach to JPDA dialog box, or the Listen for JPDA dialog box.
Click to unsave the saved parameters.
Related Topics
27-49
27-50
Project Settings - Debugger Page
Before you start debugging, use this dialog box to specify the packages and classes in which
you want to enable or disable tracing. Enabling tracing means that the Step Into command will
trace into a method. Disabling tracing means that the Step Into command will not trace into a
method. It is customary to disable tracing in the packages for which you do not have the source
code.
Tracing Class/Package Include List

Enter or click Edit to specify the packages and classes for which tracing is enabled.
Separate items with a semi-colon (;).
Note: If the Tracing Class/Package Include List field is left blank, tracing is enabled on
all packages except for those specified in the Tracing Class/Package Exclude List.
Tracing Class/Package Exclude List
Enter or click Edit to specify the packages and classes for which tracing is disabled.
Separate items with a semicolon (;).
Example 1
Include
<blank>
Exclude
java;javax;sun;sunw;com.sun
Effect
This example will enable tracing in all classes except those in the Java, javax, sun, sunw,
and com.sun packages.
Example 2
Include
com.acme;com.petstore
Exclude
<blank>
Effect
This example will enable tracing in all classes in the com.acme and com.petstore
27-51
packages.
Example 3
Include
com.acme
Exclude
com.acme.internal
Effect
This example will enable tracing in all classes in the com.acme package, except for the
classes in the com.acme.internal package.
Scope for New Breakpoints
Global
Specifies that new breakpoints (breakpoints you create from now on) will be global
breakpoints. Global breakpoints are active whenever you are debugging,
regardless of what project you are using.
Workspace
Specifies that new breakpoints (breakpoints you create from now on) will be
workspace breakpoints. Workspace breakpoints are active whenever you are
debugging a project in the specified workspace.
Project
Specifies that new breakpoints (breakpoints you create from now on) will be
project breakpoints. Project breakpoints are active only when you are debugging
Related Topics

27-52
Project Settings - Runner Options Page
Use this page to select additional options for running a project. These options are also used by
the debugger, profiler, and code coach.
Make Project Before Running

Automatically performs the make command or compiles the entire workspace including
all projects within it before the application is run in JDeveloper.
Clear Log Before Running

Clears the previously logged information from the Log window before running the project.
Log Start Command

Displays the command line used to launch the process in the Log window when running
the project.
Log Program Output

Redirects the System.out PrintStream to the log window when running the project.
Log Program Error

Redirects the System.err PrintStream to the log window when running the project.
Allow Program Input

Allows you to enter console-style input into your program from the Log window when
running the project. Console-style input can be read by a Java program using the
System.in InputStream.
Log Process Exit

Displays the exit code for the process, when the process finishes.
Use Proxy
If your Java code uses external resources on the Internet and you need to use a proxy
server to access the internet, enter the proxy server information in the Tools |
27-53
Preferences - Proxy Server panel and select this check box to pass the proxy
information to the running process when running the project.
Related Topics
About the Debugger

27-54
Project Settings - Runner Page
Use this page to specify the settings for running a project. These options are also used by the
debugger, profiler, and CodeCoach.
Default Run Target

The dropdown list contains all the files in your project which you can choose as run
targets. A run target can be a Java application, a Java servlet, a JavaServer Page (JSP),
an HTML file, an XSQL file, a UIX file, or a JDeveloper Addin. Choose the Default Run
Target for this project from the dropdown list, or click Browse to locate a run target
outside of your project.
Note: The Default Run Target does not have to be a file contained in the project. For
example, you may be working in a workspace with multiple projects, where each project
is just part of a large program. You may set the Default Run Target for each of the
projects to be a specific Java class which is contained in only one of the projects.
If the specified item is not runnable at all, then an error is displayed in the Log window.

If this option is selected, the runner will attempt to run the current node in the active view.
is active. If that file is not runnable, then the Runner attempts to run the project's
specified Default Run Target.
If this option is no selected, the Runner runs the project's specified Default Run Target.
Virtual Machine
Choose which Java Virtual Machine (JVM) to use when running the project. The VMs
listed here are the VMs which are available in the J2SE that you selected from the
Project Settings - Libraries panel.
Note: Some features of JDeveloper may or may not be available, depending on which
JVM you choose here. For example, the Profiler and CodeCoach only work with Oracle
Java Virtual Machine (OJVM), and the debugger has many features which only work with
OJVM.
Java Options
Enter any additional Java options you want included in the command line when the Java
process is launched. Based on your project settings, JDeveloper already includes the
27-55
appropriate Java Virtual Machine (JVM) option, classpath, and any additional
debugger/profiler/CodeCoach options when the Java process is launched. Thus, you are
not required to enter these options.
The Java options that are available depend on the requested JVM used when running
your project. To display the available Java options on the specified JVM, you can enter
the following at a command prompt from the installation location of your J2SE (for
example: <JDEV_HOME>\jdk1.3\bin):
java -?
A usage example of the -D option is as follows:
-Dmy.favorite.color=yellow
Program Arguments
Enter arguments that you want passed to your application's main method.
Run Directory
Specify the directory from which to launch the process when running the project. If your
program opens files using relative paths, it is important that you specify the Run
Directory. The Run Directory can be determined in a Java program by calling
System.getProperty("user.dir"). Click Browse to locate a directory.
Related Topics

About the Debugger
27-56
Remote Debugging and Profiling Wizard - Finish
Use this page to review and change your selections. If you want to change any of the
selections, click Back until you reach the appropriate page.
Click Finish to complete the wizard. JDeveloper auto-generates the required project files for
you to use.
Once the project is created, you can edit the settings from any of the Project | Project Settings
panel. For example, you may want to add another source path or change the libraries in your
project.
Related topics
Using a Project Configured for Remote Debugging
27-57
Remote Debugging and Profiling Project Wizard -
J2SE Version and Libraries
Use the Libraries page of the Remote Debugging and Profiling Wizard to define libraries for
your new project.
J2SE Version
The Java2 Standard Edition (J2SE) used by your project. Select an existing J2SE from
the dropdown list or click Define to create a new one.
Available Libraries
Selected Libraries listing.
Selected Libraries
left) to move libraries from the Available Libraries listing into this listing. Use the reorder
New
Click to create a new library and add it to the Selected Libraries listing.
Edit
Delete
Classpath
Displays the classpath for the library currently selected in either the Available Libraries
or Selected Libraries listings.
Related topics
27-58
About Libraries
About J2SE
27-59
Remote Debugging and Profiling Wizard - Project
Directory and File Name
The Remote Debugging and Profiling Wizard uses default values for a remote debugging or
profiling a project and its contents. These default values are based on the current workspace.
You can change these values in this page to specify another directory or project file name, or to
create a new directory . When you change the location, the wizard also updates the locations of
all project-related subdirectories.
Enter the Project Directory Name
Enter a new directory name for the project or browse to select an existing one. By
default, the directory is placed within JDeveloper. If you intend to reinstall JDeveloper,
you may want to place this directory outside the product.
Enter the Project File Name
Enter a filename for your remote debugging or profiling project, maintaining the .jpr file
extension. By default, the generic name Project is incremented. The name you supply
here will identify the project for you in the Navigator.
Click Next to specify the Java sources directories for your project.
Related Topics
About Projects
27-60
Select a Remote Debugging Protocol
Choose the remote debugging protocol for your remote debug project.
Note: You are not required to complete this page if all you want to do is perform remote
profiling since profiling is supported on OJVM only. This page is required for remote debugging
only.
Attach to OJVM
Select if you will be using the Oracle Java Virtual Machine (OJVM) debugging protocol.
The OJVM has additional features to help you debug your project.
Note: OJVM runs only on Windows NT.
Attach to JPDA
Select if you will be using Sun Microsystem's Java Platform Debugger Architecture
(JPDA) and you would like the debugger to attach to the debuggee process.
Note: Choose this option if you will be using a Java virtual machine other than the Oracle
Java Virtual Machine. For example, choose this option if you will be using the Classic or
HotSpot virtual machine.
Listen for JPDA

Select if you will be using the Sun Microsystem's Java Platform Debugger Architecture
(JPDA) and you would like the debugger to listen so that a debuggee (attacher) can
attach to the debugger.
Note: Selecting this option is unlikely. Usually, the debugger attaches to the debuggee.
In this case, the debugger listens and the debuggee attaches to the debugger.
Click Next to review your selections and finish creating the project.
Related Topics
27-61
27-62
Specifiying Java Source Directories
The Remote Debugging and Profiling Project wizard uses the default path of the Java source
directory for this project. This default value is based on the current project information you
specified in the previous page. You can change this value if you know the full path, or click
Browse to select a folder and have the wizard fill in this value.
Don't list directories that contain paths to source files for libraries; you can do that in the next
page.
Java Source Path

Enter the path or paths to the Java source code (.java files) contained in your project. By
default, this is the src directory under the project file's directory. To change the default,
enter a new value or click Browse to display the Edit Project Source Path dialog, which
you can use to modify paths in, or add paths to, your list of root directories.
Click Next to specify the J2SE version and paths to library source files.
Related Topics
About Projects
About Project Paths
27-63
Welcome
This wizard guides you in the creation of a project for remote debugging and profiling. You do
not need to add any source files to the project, but you will need access to the source files for
the code you will be debugging.
You do not need to add any source files to the project, but you will need access to the source
files for the code you will be debugging and profiling. You may need to copy your source files to
the machine where you are running JDeveloper.
Click Next to select the project directory and project name for the remote debugging and
profiling session.
Related Topics

About the Profiler
27-64
Smart Data Window
Use the Smart Data window if you are stepping through code and want to see the data that
relates to the source code. The Smart Data window analyzes the source code near the
execution point and finds the variables, fields, and expressions, that are used in the lines of
code that you are stepping through. Instead of displaying all the arguments and local variables
for the current stack frame (like the Data window), the Smart Data window displays only the
data that appears to be relevant to the source code that you are stepping through.
in the Tools | Preferences - Debugger - Smart Data panel or by choosing Settings... from the
Smart Data window context menu options which you can access by right-clicking in the Smart
Data window.
Analysis of your code begins from the Execution Point arrow in the Code Editor. By default,
the debugger analyzes only one line of code for each location and analyzes up to two locations.
You can adjust these settings in the Tools | Preferences - Debugger - Smart Data panel which
you can also access by right-clicking in the Smart Data window and choosing Settings... from
the context menu.
As you step over code , the results of the analysis for both the current location and the
previous location (or locations) are displayed in the Smart Data window.
The variables, fields, and expressions, listed in the Smart Data window are displayed in
alphabetical order.
Unlike the Data, Watch, and Inspector windows, changing the selection in the Stack window
has absolutely no effect on what is displayed in the Smart Data window.
Note: JDeveloper's other data-related windows include the Data window, the Inspector window,
the Watches window, the Heap window, and the left-hand side of the Monitors window.
Context Menu
The following context menu options may be available from the Smart Data window depending
on if they apply to the currently selected item in the Smart Data window. Right-click in the
Smart Data window to display the context menu options including:
27-65
View Whole Value...
Adjust Range...
Toggle Value
Modify Value...
data item.
Watch
Inspect
Use Filters
Edit Filters...
an object.
27-66
Settings...
Displays the Smart Data Window Settings Panel from which you can choose the columns
and other display options to appear in the Smart Data window.
Collapse All
Note: In the Smart Data window, there is no Expand All option on the context menu. This
is because the complete tree would contain far too many branches and because data
items may contain circular references which would cause the debugger to go into an
infinite loop while trying to expand the branches.
Export...
Saves the contents of the Smart Data window in its current state to a text file.
Related Topics

27-67
Source Not Found Dialog
This dialog is displayed when JDeveloper cannot locate a source file while debugging. You
must instruct JDeveloper on how to proceed in this case.
Unable to find source file for package [name], filename [name]

Choose one of the following options:
Generate a source file stub for the class.
A skeletal stub file is displayed in place of the missing source file. Although many
users like to see the skeletal stub file, the line numbers in the skeletal stub file do
not match the line numbers that the debugger uses.
Don't generate a source file stub for the class.
Continue debugging without the missing source file.
Let me find the file myself.
You locate the source file and continue debugging. Select this option if you have
the missing source file.
The following options will prevent this dialog from being displayed repeatedly.
Always use this choice for this specific file.

The option you selected above is applied every time this specific source file is not found.
Always use this choice for files in this package.
The option you selected above is applied to all files in this package when a source file is
not found.
Always use this choice for any file.
The option you selected above is applied anytime a source file is not found.
Related Topics

27-68
27-69
Stack Window
The Stack window displays the call stack for the selected thread. The Stack window lists every
method that has been executed on the selected thread but not yet completed. Once executed,
methods do not display in the Stack window.
By default, the stack window lists the name of the class and the name of the methods. You can
optionally choose to display the name of the file and the line number. The columns that are
visible are determined by the Stack Window Settings which you set by choosing Tools |
Preferences - Debugger - Stack or by by choosing Settings... from the Stack window context
menu options which you can access by right-clicking in the Stack window.
context.
Tooltips are automatically displayed when you hover the mouse over a cell in the Stack
window. The fully-qualified class name appears when you hover over a cell in the Class
column. The full method (with return type, package, classname, and argument types) appears
when you hover over a cell in the Method column.
The displayed columns in the Stack window may include the following: Class, Method, File,
Line. For more information, see the Tools | Preferences | Debugger - Stack panel.
Context Menu
The following context menu options may be available from the Stack window depending on if
they apply to the currently selected item in the Stack window. Right-click in the Stack window to
display the context menu options including:
Go to Source for Method <method>

Displays the method in the Code Editor and highlights the line of code.
You can also double-click a method name in the Stack window list to go directly to the
source code.
Settings...
Displays the Debugger - Stack Panel from which you can choose the columns and other
display options to appear in the Stack window.
Export...
27-70
Saves the contents of Stack window in its current state to a text file.
Related Topics

27-71
Threads Window
The columns which display in this window depend on those column settings that are enabled in
the Tools | Preferences - Debugger - Threads panel or by choosing Settings... from the
Threads window context menu options which you can access by right-clicking in the Threads
window.
By default, the threads window is not displayed automatically when the debugger is started.
You can display this window by choosing the View | Debug Windows | Threads menu option.
The Debugger supports display of Thread Groups in the Thread window. A Thread Group can
contain another group and a group can contain threads.
The Threads window and the Stack window work in conjuction with one another. Whatever
thread you highlight in the Threads window determines what is displayed in the Stack window.
The Stack window is automatically updated to display the call stack for the highlighted thread.
The current thread's name is displayed in bold text in the Threads window. All the stepping
commands (Step Over, Step Into, Step Out, and Step to End of Method) as well as the Set
Next Statement command, apply to the current thread only. To change which thread is the
current thread, right-click on the thread you want to become the current thread and choose
Select Thread from the context menu.
The execution point arrow icon is displayed in the left-hand margin of the Code Editor, at the
location of the execution point of the current thread.
The Context Menu options are displayed below.
Context Menu
The following context menu options may be available from the Threads window depending on
your settings in the Tools | Preferences - Debugger - Thread panel, and if they apply to the
currently selected item in the Threads window. Right-click in the Threads window to display the
context menu options including:
Select Thread
Use this option to make another thread become the current thread. The current thread's
name is displayed in bold text in the Threads window. All the stepping commands (Step
Over, Step Into, Step Out, and Step to End of Method) as well as the Set Next Statement
command, apply to the current thread only.
Expand All/Collapse All
27-72
Only available if the Show Thread Group Structure check box is checked in the Tools |
Preferences - Debug Windows - Threads panel. Causes all the thread group nodes to
expand or collapse.
Settings...
Displays the Tools | Preferences - Debugger - Threads panel from which you can choose
the columns and other display options for the Threads window.
Export...
Saves the contents of the Threads window in its current state to a text file.
Export Full Thread Dump...
Saves to a text file the stack traces for all the threads in the program you are debugging.
Related Topics

About the Debugger Icons
Running to the Cursor Location
27-73
Tools | Preferences - Debugger - Breakpoints -
Default Action Page
Use this page to set the default actions for breakpoints you create in the future. Once a
breakpoint has been created, you can modify the actions for the specific breakpoint by using
the New/Edit Breakpoint dialog - Actions page.
Note: You can use any combination of these breakpoint actions.
Halt Execution
Select if you want the debugger to pause the debuggee program when it encounters a
breakpoint.
Beep
Select if you want the debugger to beep when it encounters a breakpoint.
Log Breakpoint Occurrence
Select if you want the debugger to send a message to the log window when it encounters
a breakpoint.
Tag
(optional) Enter a tag which will be displayed in the log window. There are no
formatting rules for the tag, the debugger simply passes it to the log window.
Expression
(optional) Enter an expression which the debugger will evaluate and display in the
log window. The expression is evaluated each time the breakpoint is encountered.
Enable a Group of Breakpoints

Select this check box and enter a group name. When the breakpoint is encountered, the
breakpoints in the specified group will be enabled.
Disable a Group of Breakpoints
Select this check box and enter a group name. When the breakpoint is encountered, the
breakpoints in the specified group will be disabled.
Related Topics
27-74
About Deadlocks
27-75
Tools | Preferences - Debugger - Monitors Page
Use this page to choose the columns and other options you want to display in the Monitors
window:
Choose Columns
Name
Displays the name of the data item. The name may be the memory address of the
object associated with the monitor, or the name of a field or array element. This
column always shows, you cannot hide it.
Value
(Selected by default.) Displays the value of the data item.
Note: In general, values are not displayed for objects and arrays. However,
JDeveloper will show the values of char arrays and some common objects, such
as String, StringBuffer, Boolean, Character, Byte, Short, Integer, Long, Double,
Float, java.io.File, java.net.URL, and java.util.Date
Type
(Selected by default.) Displays the type of the data item. The type may be the
name of a primitive type (for example, boolean, int, short), the name of a class (for
example String, StringBuffer, JTextField), or an array type (for example String[],
char[], Object[]).
Declared Type
Displays the type the variable, field, or array element was declared as. This may
be different than the type displayed in the Type column.
Hex Value
Displays the hexadecimal value of the data item, if any.
Address
Displays the memory address of an object or array.
Note: Only the Oracle Java Virtual Machine (OJVM) provides memory addresses
of objects and arrays. Memory addresses are not provided by JPDA, the
debugging protocol used with the Classic and HotSpot Java Virtual Machines. If
you are using either the Classic or the HotSpot virtual machine (the VM is
specified in the Project | Project Settings - Runner Panel), the memory addresses
will not be displayed.
Sort Fields By Name
27-76
Normally, fields display in the Data window in the order they appear in the object, with
fields declared in a subclass appearing before fields declared in a superclass. Selecting
this option results in all fields of an object being displayed in alphabetical order,
regardless of whether a field is declared in a subclass or superclass. This option does
not affect the sorting of variables.
Show Package Names
(Not selected by default.) Select to enable the display of the fully-qualified package name
with the class name. If not selected, only the class name is displayed.
Hide Static Fields
(Selected by default.) Controls whether static fields are displayed when an object node is
expanded.
Hide Final Fields
Controls whether final fields are displayed when an object node is expanded.
Hide Null Array Elements
Controls whether null array elements are displayed when an array node is expanded.
Note: This option is useful when you expand an object array such as the elementData
field in a Vector or ArrayList, or the table field in a Hashtable or HashMap. These object
arrays often contain many null elements and hiding the null elements can help you focus
on those array elements which are of interest to you during your debugging session.
Related Topics

27-77
Tools | Preferences - Debugger - Breakpoints Page
Use this page to choose which columns you want to appear in the Breakpoints window:
Choose Columns
Only the columns you select in this panel will appear in the Breakpoints window.
Description
JDeveloper automatically generates a description for each breakpoint displayed based
on the breakpoint type and details. For a Source breakpoint, the description includes the
package, source file, and line number. For an Exception breakpoint, the description
includes the exception class name. For example: java.lang.Throwable is the name
of an exception breakpoint.
Type
Displays the type of the breakpoint including:
Source
The most common type of breakpoint set is a source breakpoint which is set for a
specific line of source code. Source breakpoint icons appear in the margin of
the Code Editor. Source breakpoints are created by clicking the line number in the
Code Editor or by choosing the Add Breakpoint context menu option in the
Breakpoints window.
Exception
Breakpoint for a specific exception class. The breakpoint will occur when an
exception is thrown.
Note: The JDeveloper debugger automatically creates a persistent exception
breakpoint for uncaught throws for java.lang.Throwable; this breakpoint will
occur whenever an uncaught exception is thrown. You cannot delete a persistent
breakpoint.
Deadlock
Breakpoint for a monitor block cycle deadlock. Not all Java Virtual Machines
support deadlock detection; for example, the HotSpot VM does not support
deadlock detection.
Note: The JDeveloper debugger automatically creates a persistent deadlock
breakpoint; this breakpoint will occur whenever a monitor block cycle is detected.
You cannot delete a persistent breakpoint.
Method
Breakpoint for a method. The breakpoint will occur when the specified method is
executed.
27-78
Class
Breakpoint for a class. The breakpoint will occur when any method in the specified
class is executed, just as if a source breakpoint has been placed at the first line of
each method in the class.
Status
Displays the status of the breakpoint, including whether the breakpoint is enabled or
disabled, and whether the breakpoint has been verified by the debugger. For more
information, see Breakpoints window.
Scope
Displays the scope to which the breakpoint belongs including:
Global
These breakpoints are active whenever you are debugging, regardless of what
project you are using.
Workspace
These breakpoints are active whenever you are debugging a project in the
specified workspace.
Project
These breakpoints are active only when you are debugging the specified project.
Group
Displays the breakpoint group name if applicable. You can create a breakpoint group by
setting a group name in the New/Edit Breakpoint - Definition page. Once a breakpoint
group has been created, a breakpoint group node is displayed and you can drag
breakpoints and drop them onto the breakpoint group node.
Condition
Displays the conditional expression for the breakpoint. A condition is specified in the
New/Edit Breakpoint - Conditions page, and allows execution to pass over a breakpoint
until a condition is satisfied.
Thread
If the breakpoint has a thread condition, the thread name is displayed.
Passcount
Displays the passcount value for the breakpoint. A passcount is specified in the New/Edit
Breakpoint - Conditions page, and allows execution to pass over a breakpoint a specific
number of times before the breakpoint occurs.
Action
27-79
Displays what actions will be taken when the breakpoint occurs. These actions can
include any of the following Halt, Beep, Log, Enable a group of breakpoints, and Disable
a group of breakpoints.
Related Topics

About Deadlocks
27-80
Tools | Preferences - Debugger - Classes Page
Use this page to choose the columns and other options you want to display in the Classes
window:
Choose Columns
Class
(Appears by default) Displays the name of the class, interface, array, or package.
This column always appears, you cannot hide it.
Count
Displays the count of instances, of the specific type, that are in the heap of the
program you are debugging.
Memory
Displays the memory consumption of each type.
File
Displays the source file name attribute for the class.
Show Package Structure

Determines if classes are displayed hierachically based on package structure or in a flat
list.
If this check box is selected, the Class column displays a tree where each package is a
branch, and classes, interfaces, and arrays, are displayed as leaf nodes.
If this check box is cleared, classes, interfaces, and arrays, are displayed in a flat list and
all names displayed in the Class column are package qualified.
Sort By
Allows sorting in ascending or descending order based on the selected column.
Class
Sorts alphabetically by fully-qualified class name.
Count
Sorts numerically by count of instances.
Memory
Sorts numerically by memory consumption.
27-81
Sort Ascending
If this check box is selected, the information is sorted from lowest to highest.
If this check box is cleared, the information is sorted from highest to lowest.
Related Topics

27-82
Tools | Preferences - Debugger - Data Page
Use this page to choose the columns and other options you want to display in the Data window:
Choose Columns
Name
(Selected by default; cannot be hidden.) Displays the name of the data item. The
name may be the name of an argument, variable, field, or array element. This
column always displays; you cannot hide it.
Value
Type
char[], Object[]).
Declared Type
Displays the type of the variable, field, or array element as it was declared. This
may be different from the type displayed in the Type column.
Hex Value
Address
specified in the Project | Project Settings - Runner Panel), the memory addresses
will not be displayed.
Sort Fields By Name
27-83
Show Package Names

Hide Static Fields

expanded.

Sort Variables By Name

Normally, variables are displayed in the Data window in the order that they appear in the
source code of the method, with arguments appearing before local variables. Selecting
this option results in all arguments and local variables being displayed in alphabetical
order. This option does not affect the sorting of fields.
Show Static Folder

(Selected by default.) Controls whether the folder containing static fields for the class
with the current method is displayed in the Data window.
Hide Final Fields

Hide Out of Scope Variables
27-84
(Selected by default.) When this option is selected, only variables which are in scope at
the current execution point are displayed in the Data window. When this option is
cleared, all variables in the current method are displayed in the Data window.
Related Topics

27-85
Tools | Preferences - Debugger - Heap Page
Use this page to choose the columns and other options you want to display in the Heap
window:
Choose Columns
Name
name may be the memory address of an object in the heap, or the name of a field
or array element. This column always shows, you cannot hide it.
Value
Type
char[], Object[]).
Declared Type
Hex Value
Address
specified in the Project Settings - Runner Panel), the memory addresses will not
be displayed.
Sort Fields By Name
27-86
Show Package Names
Hide Static Fields
expanded.
Hide Final Fields
Hide Unrelated Items in Reference Paths
(Selected by default.) A reference path is the chain of objects which leads from a
reference root to the target object. Each object in the reference path will have at least
one field (or array element) whose value is also on the reference path, but also has other
fields (or array elements) whose values are not on the reference path. These other fields
(or array elements) are unrelated items. This option controls whether the unrelated fields
(or array elements) are displayed when an object in a reference path is expanded.
Ignore Soft and Weak References in Reference Paths
(Selected by default.) Controls whether the debugger ignores soft and weak references
when it is determining the reference paths to a target object. Since soft and weak
references are cleared in response to memory demand and do not prevent an object
from being reclaimed by the garbage collector, it is usually advisable to ignore them
when investigating reference paths in the Heap window.
Related Topics
27-87
Debugger Viewlet on the Oracle Technology Network at:
http://otn.oracle.com/products/jdev/viewlets/viewlet.html
27-88
Tools | Preferences - Debugger - Inspector Page
Use this page to choose the columns and other options you want to display in the Inspector
window:
Choose Columns
Name
(Selected by default; cannot be cleared.) Displays the name of the data item. The
name may be an expression, or the name of an argument, local variable, field or
array element. This column always shows, you cannot hide it.
Value
Type
char[], Object[]).
Declared Type
Hex Value
Address
be displayed.
Sort Fields By Name
27-89
Show Package Names

Hide Static Fields

expanded.
Hide Final Fields


Related Topics

27-90
Tools | Preferences - Debugger - Monitors - Threads
Page
Use this page to choose the columns and other options you want to display in the Monitors
window Threads sub-windows:
Choose Columns
Name
(Selected by default; cannot be hidden.) Displays the name of the thread. This
column always displays; you cannot hide it.
Status
(Selected by default.) Displays the current status for the thread: Runnable,
Blocked, Blocked (Deadlocked), Waiting, Sleeping.
Group
Displays the name of the thread group to which this thread belongs.
Priority
Displays the thread's priority.
Daemon
Displays graphically as a check box if the thread is a daemon thread.
Related Topics

27-91
Tools | Preferences - Debugger - Smart Data Page
Use this page to choose the columns and other options you want to display in the Smart Data
window:
Choose Columns
Only the columns you select in this panel will appear in the Smart Data window with
appropriate information.
Name
name may be an expression, or the name of an argument, local variable, field or
array element. This column always displays, you cannot hide it.
Value
Type
char[], Object[]).
Declared Type
Hex Value
Address
be displayed.
27-92
Sort Fields By Name
Normally, fields display in the Smart Data window in the order they appear in the object,
with fields declared in a subclass appearing before fields declared in a superclass.
Selecting this option results in all fields of an object being displayed in alphabetical order,
Show Package Names
Hide Static Fields
expanded.
Hide Final Fields
Maximum Locations to Remember
Enter how many locations (including the current location) for which you want the Smart
Data window to display data. The default is 2 and the maximum is 10. For example, if
you set this value to 5, then as you step over code, the results of the analysis for the
current location and the 4 previous locations are displayed in the Smart Data window.
Number of Lines to Analyze
Enter the number of lines that you want the debugger to analyze at each location. The
default is 1 and the maximum is 10. The higher the number, the greater the amount of
information that will be displayed in the Smart Data window. The Smart Data window is
designed to reduce the amount of irrelevant data displayed, allowing you to focus on only
the data that appears to be relevant to the source code that you are stepping through.
Thus, you would typically enter a low value in this field to get the most out of this feature.
Related Topics
27-93
27-94
Tools | Preferences - Debugger - Stack Page
Use this page to choose the columns and other options you want to display in the Stack
window:
Choose Columns
Class
(Selected by default.) Displays the class name for the stack frame. If Show
Package Names is selected (see below), the class name displayed will be
package qualified.
Method
(Selected by default.) Displays the method name for the stack frame.
File
Displays the source file name for the stack frame.
Line
Displays the line number for the stack frame.
Show Package Names

Related Topics

27-95
Tools | Preferences - Debugger - Threads Page
Use this page to choose the columns and other options you want to display in the Threads
window:
Choose Columns
Name
Displays the name of the thread or thread group. This column always shows, you
cannot hide it.
Status
(Selected by default.) Displays the current status for the thread: Runnable,
Blocked, Blocked (Deadlocked), Waiting, Sleeping, Completed.
If this columns displays Blocked (Deadlocked), it means that a monitor block cycle
deadlock has been detected and the programmer should view the Monitors
Window to determine the cause of the deadlock.
Group
Displays the name of the thread group to which this thread belongs.
Priority
Displays the thread's priority or the thread group's maximum priority.
Daemon
Displays graphically as a check box if the thread is a daemon thread or if the
thread group is a daemon thread group.
Show Thread Group Structure

Determines if threads are displayed hierarchically based on thread group structure or in a
flat list.
If Show Thread Group Structure is checked, the Name column displays a tree where
each Thread Group is a branch, and Threads are displayed as leaf nodes.
If Show Thread Group Structure is not checked, Threads are displayed in a flat list.
Related Topics

27-96
27-97
Tools | Preferences - Debugger - Watches Window
Page
Use this page to choose the columns and other options you want to display in the Watches
window:
Choose Columns
Name
Displays the name of the data item. The name may be an expression, or the name
of an argument, local variable, field or array element. This column always shows,
you cannot hide it.
Value
Type
char[], Object[]).
Declared Type
Hex Value
Address
be displayed.
27-98
Sort Fields By Name
Show Package Names
Hide Static Fields
expanded.
Hide Final Fields
Related Topics

27-99
Tools | Preferences - Debugger Page
Table Resize Mode
Use this page to configure the behavior when a column is resized in any of the debugger
windows.
When a Column is Resized

Choose one of the following choices for how you want the table column(s) to behave
when a column is resized:
Do Not Adjust Other Columns
Only the resized column is adjusted. The column size does not change for all
other columns. A scroll bar is used if the width of the columns exceeds the width of
the window.
Adjust the Next Column Only
The column size for the column beside the resized column is adjusted.
Adjust All Subsequent Columns
(Selected by default.) All columns following the resized column are adjusted.
Adjust the Last Column Only
Only the last column is adjusted.
Adjust All Columns Proportionally
All columns are adjusted proportionally.
Show Debug Actions On Main Debug Menu

Select this check box to display the various debugger context menu options on the main
JDeveloper menu under Debug | Debug Actions | <Name of Debug window> option.
Show Tool Tip in Code Editor While Debugging

(Selected by default.) While debugging, if you stop at a breakpoint (or after stepping or
pressing pause), you will be able to see a tooltip in the Code Editor when you hover the
mouse over a variable name. The tooltip displays the current value of the variable.
Connection Retry Setting

Select the number of times that the debugger retries a connection to the debuggee
process if the connection fails. The number of retries depends on the operating system.
For example, on Windows NT, setting one (1) retry is usually satisfactory; while on some
27-100
Linux machines, 5 retries seems necessary. The default setting is 10 retries which
seems to be sufficient for most operating systems. However, if you see the message
"Debugger unable to connect to local process." in the Log page when you try to debug,
try increasing this setting.
Related Topics
About the Debugger

27-101
Tracing Dialog
While you are debugging, use this dialog box to adjust the packages and classes in which you
want to enable or disable tracing. Enabling tracing means that the Step Into command will trace
into a method. Disabling tracing means that the Step Into command will not trace into a
method. It is customary to disable tracing in the packages for which you do not have the source
code.
Tracing Class/Package Include List

Enter or click Edit to specify the packages and classes for which tracing is enabled.
Note: If the Tracing Class/Package Include List field is left blank, tracing is enabled on all
packages except for those specified in the Tracing Class/Package Exclude List.
Tracing Class/Package Exclude List

Enter or click Edit to specify the packages and classes for which tracing is disabled.
Example 1
Include
<blank>
Exclude
Effect
This example will disable tracing in all classes in the com.acme and com.petstore
packages. All others are enabled.
Example 2
Include
Exclude
<blank>
Effect
27-102
This example will enable tracing in all classes in the com.acme and com.petstore
packages.
Example 3
Include
com.acme
Exclude
com.acme.internal
Effect
This example will enable tracing in all classes in the com.acme package, except for the
classes in the com.acme.internal package.
Related Topics

27-103
Tracing Exclude Edit Dialog
Use this dialog box to specify the packages and classes for which tracing is disabled.
Add ...
Click to display the Package/Class Browser dialog box from which you can choose any
package or class which is accessible in you project.
Remove
Select a package or class from the list and click Remove to remove it from this Tracing
Exclude list.
Note: This does not remove the class or package from your hard drive; it only removes it
from this Tracing Exclude list.
Related Topics

27-104
Tracing Include Edit Dialog
Use this dialog box to specify the packages and classes for which tracing is enabled.
Add ...
Click to display the Package/Class Browser dialog box from which you can choose any
package or class which is accessible in you project.
Remove
Select a package or class from the list and click Remove to remove it from this Tracing
Include list.
Note: This does not remove the class or package from your hard drive; it only removes it
from this Tracing Include list.
Related Topics

27-105
View Whole Value Dialog
Use this dialog to display the value in its entirety in a multiline text field in a modal dialog box.
Available for string, byte array, char array, short array, int array, and long array.
View As a String
(Available only for byte array.) Select this check box to view the byte array as a String.
Clear this check box to view the byte array as hexadecimal values.
Character Encoding
(Available only for byte array and when View As a String is selected.) In the list, choose
the type of character encoding used when displaying the value.
For more information on using character encodings, see

http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc.
Related Topics
About the Smart Data window

About the Debugger
27-106
Watches Window
Use this window to evaluate and display expressions. The Watches window is similar to an
Inspector window except for the following differences:
● The Watches window evaluates a list of expressions, while an Inspector window

evaluates only one expression .
● There is only one Watches window, while you can have many Inspector windows.
You can create a watch in any of the following ways:
● Dragging an item from the Data or Smart Data window and dropping it onto the Watches
window.
● Right-clicking an item in the Data or Smart Data window and choosing Watch from the
context menu.
● Right-clicking in the Watches window, choosing Add Watch from the context menu, and
entering an expression.
● Right-clicking in the Code Editor, choosing Watch... from the context menu, and entering
an expression.
in the Tools | Preferences - Debugger - Watch panel or by choosing Settings... from the
Watches window context menu options which you can access by right-clicking in the Watches
window.
Note: JDeveloper's other data-related windows include the Data window, the Inspector window,
the Smart Data window, the Heap window, and the left-hand side of the Monitors window.
Context Menu
The following context menu options may be available from the Watches window depending on
27-107
your Project Settings and if they apply to the currently selected item in the Watches window.
Right-click in the Watches window to display the context menu options including:
Edit Watch...
Available when a watch expression is selected. Displays the Edit Watch Expression
dialog, from which you can edit the expression.
Remove Watch
Available when a watch expression is selected. Removes the selected watch expression
from the Watches window.
Pin Object
Available only when the Java Virtual Machine of the debuggee (specified in the Project
Settings - Runner Panel) is OJVM, a watch expression is selected, and the evaluation of
that expression produces an object or array. Changes the way the Watches window
evaluates the expression so that instead of evaluating the expression in the context of
the selected stack frame (the normal behavior), the Watches window will show the value
at a specific memory address. The memory address is determined by the address of the
object or array at the time of the Pin Object operation.
Unpin Object
Available only when the selected expression has been pinned. Restores the normal
behavior of the Watches window for the selected expression so that the expression is
evaluated in the context of the selected stack frame.
View Whole Value...
Adjust Range...
Toggle Value
Modify Value...
data item.
Watch
27-108
Inspect
Use Filters
Edit Filters...
an object.
Add Watch...
Displays the Add Watch Expression dialog box, from which you can enter a new watch
expression.
Remove All Watches
Removes all watch expressions from the Watches window.
Collapse All
Note: In the Watches window, there is no Expand All option on the context menu. This is
Settings...
Displays the Watches Window Settings Panel from which you can choose the columns
and other display options to appear in the Watches window.
Export...
Saves the contents of the Watches window in its current state to a text file.
27-109
Related Topics

27-110
CodeCoach and Profiler Reference
● Class Access Modifier Is Advised
● Class Must Be Compiled with Debug Info
● CodeCoach Results
● Connect to Profilee Dialog
● Creating New Immutable Objects with Constant Parameters
● Dead Code Is Detected
● Field Access Modifier Is Advised
● Field Is Unused
● Inefficient instanceof
● Local Variable Is Unused
● Memory Advice - Allocation Size
● Method Access Modifier Is Advised
● Project Settings Dialog - CodeCoach Page
● Project Settings Dialog - Events Page
● Project Settings Dialog - Execution Page
● Project Settings Dialog - Memory Page
● Project Settings Dialog - Profiler Page
● Setting a Field to Local Is Advised
● Setting a Local Variable to Final Is Advised
● The Event Profiler
● The Execution Profiler
● The Memory Profiler
28-1
Class Access Modifier Is Advised
CodeCoach will advise you when you can change a class modifier. CodeCoach may advise
one or both of these changes, depending upon the field.
Class classname should be static.

If all the symbols of the outer class accessed by an inner class are static, the inner class
should be static as well.
If the inner class accesses even one nonstatic field, method, or object of the outer class,
then it cannot be static.
Class classname should be final.

A class which is never extended can be declared final.
In a final class, all the methods can be considered final. Final methods can be inlined
and, more importantly, final methods can be called directly without using the method
table.
In addition, declaring the class final helps the JVM to execute instanceof /checkcast
operations, which are, in general, very expensive.
If CodeCoach detects a class which could be declared final, no final methods advices are
given for the methods of this class.
If you expect to extend the class in the future, you should not follow this suggestion.
Related topics

28-2
Class Must Be Compiled with Debug Info
When a class is run through CodeCoach, but debug information has not been included in the
class, CodeCoach will give you this warning.
information enabled in the Project Properties dialog (from the Compile tab, select Include
debug information) or using the -g switch of OJC on the command line. You should exclude all
third-party classes.
Related topics

28-3
CodeCoach Results
The CodeCoach results window displays the results of your most recent CodeCoaching
session.
To receive help on an individual advice line, select the line and press F1.
Right-click anywhere within the window to bring up a context menu of commands.
Working with CodeCoach Results
To locate the line in the Code Editor that a given advice line refers to, scroll through the
messages using the menu selection Search | Go to Next Message or Search | Go to Previous
message or using (in the default keymap) the corresponding accelerators Alt-F8 and Alt-F7.
Alternately, you can double-click on an individual advice line, or right-click on it and choose
Find Source.
To apply simple, mechanical fixes automatically, select any number of advice lines, right-click
and choose Apply Fix to Source. Not all advice lines refer to a mechanical fix. If an advice line
involves a more complicated fix, this menu item is disabled. If any one of a multiple selection of
advice lines is unfixable, the menu item will be disabled for the entire group. When you apply a
mechanical fix, the original advice line disappears.
Once you have applied these mechanical fixes, you can undo any number of them by clicking
the Undo Navigation icon on the toolbar. If you undo such a fix, the original advice line that
indicated it as a potential problem does not reappear.
Automatic fixes are available only for those advice types which modify access level (static, final,
private), that is, for advice types associated with the keywords CFIN, CSTA, MFIN, MPRI, MSTA,
FFIN, FPRI, and FSTA.
To hide messages of a given type, right-click on an individual advice line of that type, right-click
and choose Hide Messages of This Type. You can always return these messages to the listing
by later right-clicking anywhere in the window and choosing Show Hidden Messages.
To ignore the advice given in a particular line, select the line, right-click and choose Ignore
Message. A disable nextline pragma is now inserted directly into the source code. To get
the advice back, you will need to remove that line from your code. The disable nextline
pragma is very strict: if a blank line follows it, the advice will not be disabled.
28-4
Related topics

28-5
Connect to Profilee Dialog
Use the Connect to Profilee dialog to set connection parameters for remote profiling.
Host
Enter the name of the machine on which the program to be profiled is running.
Port
Enter the port on the machine where the program to be profiled is waiting for the UI to
connect to it.
Save parameters
Select to save the host and port name in subsequent remote profiling sessions.
Related topics
28-6
Creating New Immutable Objects with Constant
Parameters
Some Java classes, including java.lang.String and java.awt.Color, are immutables.
Once an instance of an immutable class has been allocated, its value can never be modified.
If such an immutable object is used repeatedly, CodeCoach will recommend creating a static
final instance of this object in the class static initializer. This will spare memory and gain
performance for the program.
For an example of what CodeCoach can detect, see CodeCoach Miscellaneous Advice.
Be careful using this advice if the object is used for any synchronization process. Creating a
static final field in that case would make synchronization global to the process instead of local
to the object instance.
Related topics

Customizing CodeCoach Advice

Oracle9i Jdeveloper User&#39;s Guide

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Oracle9i Jdeveloper User&#39;s Guide

Transféré par

Droits d'auteur :

Formats disponibles

Oracle9i Developer Suite

Oracle9i JDeveloper User’s Guide

Release 9.0.2 Production

Part No. A97276-01

Copyright © 1996, 2002, Oracle Corporation. All rights reserved.

Portions of this software and documentation copyright © 2001Three D Graphics.

JDeveloper Conceptual and Task Help

1. Welcome to Oracle9i JDeveloper

2. Getting Started with JDeveloper

4. Developing Web Applications (J2EE Web Modules)

5. Working with XML Files

6. Working with UIX XML and UIX JSP Pages

8. Developing Java GUI Clients

9. Testing and Optimizing Your Code

10. Developing JavaBeans

11. Developing Business Components

12. UML Modeling

13. Developing Enterprise JavaBeans

14. Packaging and Deploying

15. Using SQL in Java Programs

16. Browsing the Database

18. Web Services

19. Using WebDAV Support

20. Extending JDeveloper Using the Addin API

1. Getting Started F1 Help

3. Web Application F1 Help

4. JSP Tag F1 Help

5. JSP and JSP UIX General F1 Help

6. UIX XML and UIX JSP Pages F1 Help

7. Compiling and Debugging F1 Help

8. CodeCoach and Profiling F1 Help

9. Developing JavaBeans F1 Help

10. UML Modeling F1 Help

12. Packaging and Deploying F1 Help

13. SQL in Java Programs F1 Help

14. Source Control F1 Help

15. Web Services F1 Help

16. WebDAV F1 Help

■ Help System Menus

❍ JDeveloper Accessibility Information

■ Importing JDeveloper 3.2.x Connections and Files into Oracle9i

■ Migrating Oracle9i JDeveloper Beta Projects to Oracle9i JDeveloper

■ Migrating Oracle9i JDeveloper Release Candidate Projects to Oracle9i

■ Migrating Projects Between Different Installations of Oracle9i JDeveloper

To take J2EE application development to a higher level of productivity, JDeveloper offers

For more information, please see any of the following:

● New Features in Oracle9i JDeveloper

Additional information is available at the Oracle Technology Network (OTN)

"Copyright © 1997, 2002, Oracle Corporation. All rights reserved."

"Portions of this software and documentation copyright © 2001Three D Graphics."

License Restrictions & Warranty Disclaimer

Restricted Rights Notice

"RESTRICTED RIGHTS NOTICE

Accessibility of Code Examples in Documentation

Accessibility of Links to External Web Sites in Documentation

UIX Tag Libraries

We would like to know:

● Did you find any errors?

You can send your comments by email at jdev_us@oracle.com

In your email, please indicate the following information:

● Topic title (for example, "Starting JDeveloper")

Using hosted documentation

1. In JDeveloper, in the Tools menu, select Preferences .

Oracle9i Jdeveloper User's Guide

Oracle9i Jdeveloper User's Guide