20 Developing Applications Using XML
This chapter includes the following sections:
20.1 About Developing Applications Using XML
JDeveloper provides you with the tools you need to work with the XML files in your application. There is an XML source editor, an XML validator, and tools for working with XML schemas. You can create your JSPX, XSD, XSQL, and configuration files using the wizards, and edit your files in the XML editor.
20.2 Using the XML File Editors
There are three different editors for your XML files. Each editor has a specific function.
Table 20-1 XML File Editors
| Editor | Description |
|---|---|
|
XML Editor |
A specialized schema-driven editor for editing XML languages, including |
|
Overview Editor |
View and edit XML ( |
|
XSD Visual Editor |
Create or edit XML schemas. Visually displays the structure, content, and semantics of an XML document. For more information, see Working with XSD Documents and Components. |
20.2.1 Understanding XML Editing Features
Table 20-2 summarizes the editing features that are available when you're working with XML files.
Table 20-2 XML Editing Features
| Feature | Purpose |
|---|---|
|
Code Insight |
While you are typing, you can invoke Code Insight by pausing after typing < (opening bracket) or by pressing Ctrl+Space if you are using the default keymapping. Code Insight opens a list with valid elements based on the grammar. After selecting an element, enter a space and then either pause or press Ctrl+Space to open a list of valid attributes from which you can select. After you enter the opening quote for the attribute value, either the required type of value or a list of available values is provided. |
|
XML Validation |
In an open XML Source Editor window, or in the Applications window, right-click an XML file and choose Validate XML. The Validate XML command will validate the XML against a schema registered with JDeveloper defined in the XML file. To register a schema with JDeveloper choose Tools > Preferences > XML Schemas. This command on the context menu is disabled whenever an XML file does not have an XML namespace defined. |
|
Quick Form Check |
Right-click on an XML file and choose Make to check for well-formedness of the file. |
|
XML Schemas Preferences |
Use the options on the XML Schemas page in the Preferences dialog to view all the currently registered XML schemas, to add new schemas, to support additional namespaces and elements, to remove user-defined schemas, and to unload schemas from memory. To get to the Preferences dialog choose Tools > Preferences > XML Schemas. |
|
XML Preferences |
You can customize these features on the XML Preferences page. Choose Tools > Preferences > Code Editor > XML and JSP/HTML to display XML Preferences. If Required Attribute Insertion is selected, the required attributes of an element will also be inserted for you. If End Tag Completion is selected, the end tag will be automatically inserted when you close the start tag, for example if you have |
|
Components Window |
Choose Window > Components to open the Components window and select one of the available pages from the dropdown list. For example, while editing XSD files, you can select elements from the XML Schema pages on the window. |
|
Properties Window |
The Properties window displays attributes of elements in the file. You can edit the values of attributes in the Properties window to update your file. |
|
Structure Window |
A file's elements 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 or error to edit it in the XML editor. |
|
Validate XML |
In an open XML editor window, or in the Applications window, right-click an XML file and choose Validate XML. The Validate XML command will validate the XML against the schema defined in the XML file. It validates the XML constraints and definitions but not XSDs. This context-menu command is disabled whenever an XML file does not have an XML namespace defined. |
|
F2 Key |
After creating an XML schema, select an element in the Structure window and press F2. The element now has focus in the XML design editor. You are automatically able to input new text for the element into the XML design editor. |
|
Expand/Collapse Attributes |
You can expand or collapse attributes that display under the |
20.2.2 Understanding the XML Editor Toolbar
Table 20-3 contains the icons that display on the XML Editor toolbar.
Table 20-3 XML Editor Toolbar Icons
| Icon | Name | Description |
|---|---|---|
|
|
Search (Crtl + F) |
Enter search text in the XML Editor. Click the down arrow to view and set additional parameters for the search, including Match Case to perform a case-sensitive search, Whole Word to locate complete word matches only, and Highlight Occurrences to use shading to show the location of the match. |
|
|
Find Next (F3) |
Click to locate the first occurrence of the text that meets the specified parameters in the file. |
|
|
Find Previous (Shift + F3) |
Click to locate the previous occurrence of the text that meets the specified parameters in the file. |
20.2.3 How to Set Editing Options for the XML Editor
The XML Editor has the following editing features:
-
Required Attribute Insertion - Required attributes that are associated with a tag are added automatically to your code, when you add the tag.
-
End Tag Completion - Automatically adds end tags when you close a start tag. For example, in an XML file, if you type
<foo>,</foo>is added automatically.
To customize editing options for the XML Editor:
- Choose Tools > Preferences.
- Expand the Code Editor node.
- Select the JSP/XML/HTML node.
- On the Code Editor - JSP/XML/HTML page, select an option.
- Click OK.
20.3 Working with XML Schemas
XML schemas define the elements of your XML files. JDeveloper provides an XSD Visual Editor that gives a visual representation of the structure, content, and semantics of an XML document. Use the XSD Visual Editor to author a new XML schema (.xsd file) or to edit an existing XML schema.
You can insert components into the XSD document using the Components window or by right-clicking on a location in the XSD document.
The XML Schema component displays at the top of an XSD file, as shown in Figure 20-1. Right-click the element and select Properties to display a dialog for configuring the schema namespaces.
Figure 20-1 XML Schema Component
JDeveloper supports various refactoring operations on XML Schemas, such as changing the schema's target namespace and changing the base type on a simpletype element that has facets. For more information, see Refactoring XML Schemas .
20.3.1 Working with Attributes in the XSD Visual Editor
You can create an XML schema's attributes and set properties and facets from using the XSD Visual Editor. Figure 20-2 contains an example XML schema in the Design tab of the XSD Visual Editor.
Figure 20-2 Schema in XSD Visual Editor
You can edit attributes in attribute2 in the attribute editor, which is displayed in Figure 20-2 as the union element. In this editor, you can:
-
Display all available attributes under an element. To hide or display details, click the plus and minus signs next to the attribute.
-
Display all facets and type details of an attribute display in the attribute node.
-
Display the default "Insert Into" menu with the valid schema components (for example,
union) when you right-click on an attribute node. -
Expand an attribute node within to display a subtler containing child nodes like list or union.
20.3.2 What Happens When You Create an XML Schema in the XSD Visual Editor
As you create an XML Schema in the XSD visual editor, JDeveloper automatically updates the XML source in the design tab, as well as updating the contents of the Structure window. The following is the source for the example.xsd file shown in Figure 20-2.
<?xml version="1.0" encoding="windows-1252" ?>
xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.example.org"
targetNamespace="http://www.example.org" <elementFormDefault="qualified">
<xsd:complexType name="UnionTest">
<xsd:sequence>
<xsd:element name="element1">
<xsd:complexType>
<xsd:attribute name="attribute1">
</xsd:attribute>
</xsd:complexType>
</xsd:element>
<xsd:element name="element2">
<xsd:complexType>
<xsd:attribute name="attribute2">
<xsd:simpleType>
<xsd:restriction>
<xsd:simpleType>
<xsd:union/>
</xsd:simpleType>
<xsd:pattern value="abcd"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
20.3.3 Selecting XSD Components
The selection of any component or attribute in the editor is indicated by highlighting the selected item in blue. In Figure 20-3, the selected simpleType component defines a simple type and specifies the constraints and information about the values of attributes or text-only components, in this case restricting the string type.
Figure 20-3 simpleType Component
20.3.4 Choice Component
The choice component allows only one of the components contained in the <choice> declaration to be present within the containing component, as shown in Figure 20-4. Set attribute maxOccurs to >1 to have more than one item from the choice in the parent.
Figure 20-4 Choice Component
?xml version="1.0" encoding="windows-1252" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.example.org"
targetNamespace="http://www.example.org" elementFormDefault="qualified">
<xsd:element name="choice">
<xsd:complexType>
<xsd:choice>
<xsd:element name="one"/>
<xsd:element name="two"/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
</xsd:schema>
20.3.5 All Component
The all component shown in Figure 20-5 specifies that the child components can appear in any order and that each child component can occur zero or one times.
Figure 20-5 All Component
<?xml version="1.0" encoding="windows-1252" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.example.org"
targetNamespace="http://www.example.org" elementFormDefault="qualified">
<xsd:element name="all">
<xsd:complexType>
<xsd:all>
<xsd:element name="one"/>
<xsd:element name="two"/>
</xsd:all>
</xsd:complexType>
</xsd:element>
</xsd:schema>
20.3.6 Sequence Component
The sequence component shown in Figure 20-6 specifies that the child components must appear in a sequence. Each child component can occur from 0 to any number of times.
Figure 20-6 Sequence Component
<?xml version="1.0" encoding="windows-1252" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.example.org"
targetNamespace="http://www.example.org" elementFormDefault="qualified">
<xsd:element name="all">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="one"/>
<xsd:element name="two"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
20.3.7 Cardinality and Ordinality
In the example of cardinality shown in Figure 20-7, components are displayed with the attributes shown in Table 20-4.
Figure 20-7 Cardinality Component
Table 20-4 Cardinality Display
| Component | Display |
|---|---|
|
Required components (minOccurs=">0") |
Display with a solid line. |
|
Optional components (minOccurs="0") |
Display with a dotted line. |
|
Unbounded components (maxOccurs="unbounded") |
Display an infinity symbol in the component stack number. Any component that can appear more than once is displayed as a "stack" of components. In the numbers to the left of the component, the number before the colon indicates the minimum number of times the component can occur (minOccurs). The number after the colon indicates the maximum number of times the component can occur (maxOccurs). In Figure 20-7, the maximum is unbounded so an infinity symbol is displayed. |
|
Range of components |
Display in the component stack number. In Figure 20-7, the component must appear at least 2 times in the instance document, but no more than 7. |
20.3.8 ComplexType Component
In Figure 20-8, the complexType component extends a base type, and inherits an attribute and children from that base type. The yellow background represents a reference to the baseType defined elsewhere in the schema and illustrated below the complexType component. The component attributes are displayed as:
-
Inherited, marked with a square.
-
Optional, marked with a square.
-
Required, marked with an orange asterisk.
-
Prohibited, marked with an orange X.
Figure 20-8 complexType Component
20.3.9 Attribute Group Component
The attribute group component groups a set of attribute declarations so that they can be incorporated as a group into complex type definition.
Figure 20-9 displays three attribute groups.
Figure 20-9 Attribute Group Component
If you add an element to a schema that has multiple attributeGroups, you can add choose one or more attributeGroups for the element by clicking on the element's attribute and choosing from a drop-down list.
20.3.10 Union Component
The union component defines a simple type as a collection (union) of values from specified simple data types. In Figure 20-10, the union represents all strings that begin with the letter "i".
Figure 20-10 Union Component
20.3.11 List Component
The list component defines a simple type component as a space separated list of values of a specified data type. In Figure 20-11, the component represents a series of short value objects.
Figure 20-11 List Component
20.3.12 Working with XML Schema Substitution Groups
One element can substitute for another element in an XML Schema group. If you have a set of XML Schemas that use the substitution group feature, ensure that the XML Schema that defines the head of the substitution group is loaded before loading additional schemas that place elements into that substitution group.
For example, you might have an XML Schema named A.xsd that contains
<element name="A"/>
and another XML Schema named B.xsd that contains
<element name="B" substitutionGroup="namespaceForA:A" />
Ensure that one of the following is true:
-
You call
SchemaGrammarProvider.add(A.xsd)before callingSchemaGrammarProvider.add(B.xsd). Or, -
B.xsdcontains an import or include statement with aschemaLocationattribute that contains a valid path toA.xsd.
20.4 How to Import and Register XML Schemas
Use the options on 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 user-defined schemas, and unload schemas from memory.
JDeveloper automatically validates the schema when you add or modify it.
To import and register an XML schema:
Tips
You can only remove user-defined schemas with the Remove button.
If a schema changes, you must use the Clear Cache button to unload all currently loaded schemas from memory. JDeveloper will then reload any needed schemas including the modified schema.
20.5 How to Generate Java Classes from XML Schemas with JAXB
In JDeveloper you can use JAXB (Java Architecture for XML Binding) to generate Java classes from XML schemas. JAXB is an easy way to incorporate XML data and processing functions in Java applications without having to know XML. You can generate a JAXB 1.0 or 2.0 content model, including the necessary annotations, from an XML schema.
When the JAXB binding compiler is run against an XML schema, JAXB packages, classes, and interfaces are generated. You can then use the generated JAXB packages and the JAXB utility packages in a binding framework to unmarshal, marshal, and validate XML content.
To generate Java classes from XML schemas with JAXB:
20.6 Working with XSD Documents and Components
Use the XSD Visual Editor or Design structure window to work with XML Schema files (.xsd files) and components. By default, new schema files are opened with the XSD Visual Editor in focus.
Double-clicking a file in the Applications window opens or brings the default editor on the Design tab to the foreground. Clicking the Source tab opens the file in the XML Source Editor. Changes made in one editor are automatically updated in the other editor
20.6.1 How to Display a Schema in Both Editors
Edit a schema file (.xsd) simultaneously in the visual and source editors by opening the page in one of the editors and using the splitter to open a second page view in the alternate editor.
To display a schema file in both editors:
-
To split the file horizontally, grab the splitter just above the vertical scroll bar (on the upper right-hand side of the window) and drag it downward.
-
To split the file vertically, grab the splitter just to the right of the horizontal scroll bar (on the lower right-hand side of the window) and drag it left.
20.6.2 How to Create an Image of the XSD Visual Editor Design Tab
You can create the design tab of the XSD Visual Editor as an image. You can then share the image as a file or print out or image with others.
Supported image formats are .svg, .svgz, .jpg, and .png.
To save the XSD editor design tab as an image:
- Click the Design tab in the XSD Visual Editor.
A design view of the
.xsdfile displays, similar to Developing Databound XML Pages with XSQL Servlet.Figure 20-12 Design Tab in XSD Visual Editor
20.6.3 How to Navigate with Grab Scroll in the XSD Visual Editor
In the XSD Visual Editor, you can quickly navigate an XML Schema that displays with scroll bars using a grab scroll operation. Use the grab scroll to invoke a small hand cursor to grab an XML Schema page and drag it inside the editor window.
To navigate using grab scroll in an XML Schema:
20.6.4 How to Expand and Collapse the XSD Component Display
While working in the XSD Visual Editor or Design structure window, you can expand or collapse XSD components to display children components or collapse container components to create a higher level view of the schema.
-
Click the + (plus) sign of the parent component to expand one level beyond the parent component.
-
Click the - (minus) sign of the parent component to collapse all levels below the parent component.
-
Press Ctrl + *, using the * on the numeric keypad of the keyboard to expand all parent components in the schema. Keep in mind that this view can be very large.
20.6.5 How to Zoom In and Out in the XSD Visual Editor
Zooming enables you to magnify (zoom in) or shrink (zoom out) on the display of an XML Schema in the XSD Visual Editor. After placing your cursor in the area of the XML Schema you want to magnify
-
Press Ctrl+Plus to zoom in. You can also use the Plus key on the numeric keypad of the keyboard
-
Press Ctrl+Minus to zoom out. You can also use the Minus key on the numeric keypad of the keyboard.
20.6.6 How to Select XSD Components
One of the most common actions you perform in the editor is to select components. you will select components to:
-
Edit properties
-
Move components
-
Delete components
-
Choose a target position to insert another component
20.6.6.1 Escalating a Single Component
You can select a single component without children.
To select a single component, click the component.
If the selected component contains children, selecting the component also selects all its children. If you copy, move, or delete the parent, all its children are also copied, moved, or deleted.
Tip:
Double-clicking an XSD component in the XSD Visual Editor displays the Properties window for the component.
20.6.6.2 Selecting Multiple Components
You can select a component along with its children, or multiple components.
To select multiple components:
Note:
Selecting multiple, non-adjacent components for any reason other than deleting them can lead to unexpected results. For example, if the components exist at different levels in the schema hierarchy, they can lose their relative hierarchical positions if you move or copy them to another position in the schema page.
In the XSD Visual Editor it is possible to select a container component (and thereby select its children) and also explicitly select one or more of the children. That means that any explicitly selected child is selected twice. If you do this and then copy and past the selection, the double-selected child will be pasted twice, once as a child to the copied parent and once as a peer to the copied parent.
20.6.7 What Happens When You Select a Component in the XSD Visual Editor
When you select a component in the XSD Visual Editor, the component displays in blue. When a container component is selected and any of its children, all are blue.
When selected in the Structure window, the component is highlighted. However, when you select any components with children, the children are also selected. If you delete or move the parent, all the children are deleted or moved.
Whenever you select an component, you are also selecting a position in which another component can be inserted. For more information, see How to Select Target Positions for XSD Components.
Tips
When you pass the mouse pointer over a component, a tooltip with the component's name is displayed.
When you select a component in the XSD Visual Editor, it is also selected in the Design and Source view of Structure window, and vice versa. You can look at the selection in both tools to clarify what is selected and where the insertion position is.
The status bar explicitly states the insertion point for a selected component.
20.6.8 How to Select Target Positions for XSD Components
While inserting, copying, or moving XSD components in the XSD Visual Editor or Structure window (Design or Source view), you need to select a target position in relation to the node on which you are performing the activity. The possible target positions on a node are before, after, and inside.
To select a target position, do one of the following:
-
Select the target position by clicking the node.
-
When dropping a component at a target position, do one of the following:
-
To insert a component before a target node, drag it towards the top of the node until you see a solid horizontal line (in the Visual Editor) or horizontal line with an embedded up arrow (in the Structure window), then release the mouse button.
-
To insert a component after a target node, drag it towards the bottom of the node until you see a solid horizontal line (in the Visual Editor) or a horizontal line with an embedded down arrow (structure), then release the mouse button.
-
To insert a component inside a target node, drag it over the node until it is surrounded by a box outline, then release the mouse button. This target position is available only on nodes that can contain child nodes.
-
-
When using the context menu to select a target position, right-click the target node, choose an option, and then select a component. Table 20-5 summarizes the options.
Table 20-5 Target Position Options
Option Description Insert before <component>
Inserts a component before the selected node.
Insert inside <component>
Inserts a component inside (under) the selected node
Insert after <component>
Inserts a component after the selected node
Not all options are always available. Choosing an option displays a submenu from which you can choose a component list and then select the component you desire. Depending on the node you select, the submenu may also contain one or more components that are eligible for insertion inside the selected node.
Note:
When you select a target position in the Design or Source views in the Structure window, the selection is also reflected in the XSD Visual Editor, and vice versa. This enables you to verify the insertion position visually as well as hierarchically. The selection is also explicitly stated in the status bar at the bottom of the JDeveloper window.
20.6.9 How to Insert XSD Components
In the XSD Visual Editor and Structure window you can also insert XSD components by copying or by cutting and pasting. If you are cutting and pasting, you can insert multiple components at a time.
Note:
Pasting multiple components that were copied from different places in the XML schema hierarchy can lead to unexpected results.
20.6.9.1 Inserting XSD Components Using the Components Window
You can insert XSD components by dragging from the Components window or by using a context menu. You can also select the target position in the visual editor or Structure window and then click the component in the Components window.
To insert XSD components using the Components Window:
- In the XSD Visual Editor or Structure window, locate the position where you wish to insert a component. You may have to expand nodes in the Structure window to uncover the node you want.
- In the Components window, select an XSD component list from the dropdown list box, and then drag the component from the list and drop into the desired target position in the XSD Visual Editor or Structure window.
20.6.9.2 Inserting XSD Components Using the Context Menu
You can also right-click to display a context menu with options for inserting XSD components.
To insert XSD components using the context menu:
- In the XSD Visual Editor or Structure window, right-click the node to display a context menu. You may have to expand nodes to uncover the node you want.
- Choose an option in the context menu, and then select a component.
20.6.10 How to Cut XSD Components
When you cut a component, it is removed from the editor and placed into a local clipboard accessible only by JDeveloper, not to the system clipboard. If you quit without pasting the component, the cut version of the component is lost.
You can cut, copy, and paste between files of the same project or different projects.
Deleting a component removes it without changing the contents. 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. For more information, see How to Delete XSD Components .
To cut one or more components:
20.6.11 How to Copy XSD Components
You can copy XSD components in the visual editor or the Structure window. You can cut, copy, and paste between files of the same project or different projects.
To copy one or more components:
20.6.12 How to Delete XSD Components
You can remove components from your XML Schema in the XSD Visual Editor or Structure (Design or Source view) window. When you delete a component, JDeveloper deletes the associated lines from the source code.
To delete one or more XSD components:
20.6.13 How to Paste XSD Elements
The elements you cut or copy from the XSD Visual Editor or Structure window can be pasted into any other XSD file in the application. For more information, see How to Select Target Positions for XSD Components.
You can cut, copy, and paste between files of the same project or different projects.
To paste an element:
20.6.14 How to Move XSD Components
You can work in the visual editor or the Structure window to move components or work in both at once, moving components between the editors.
You can move one or multiple components at a time. However, selecting and moving multiple, non-adjacent components or multiple components from different levels in the schema hierarchy can lead to unexpected results.
20.6.14.1 Moving Components by Dragging
You can move an XSD component to a new insertion point in the XSD Visual Editor or Structure (Design or Source view) window by dragging.
To move components by dragging:
Do either of the following:
-
Drag the component(s) from the original position to a target position in the visual editor or Structure window. For more information, see How to Select Target Positions for XSD Components.
-
Right-click and drag the component(s) from its original position to an insertion point. Choose Move Nodes Here from the context menu.
20.6.14.2 Moving Components by Cutting and Pasting
You can move an XSD component to a valid insertion point in another file in the same project or a different project by cutting and pasting. For more information, see How to Select XSD Components .
To move components by cutting and pasting:
Do either of the following:
-
Cut the component(s). Then, paste it into some other position in the visual editor or Schema structure window.
-
Cut the component(s). Then, paste it into another file in the same project or a different project.
Note:
The selected components and all of its child components are moved to the new target position.
20.6.15 How to Set and Modify XSD Component Properties
The Properties window displays the properties of XSD components selected. Use the Properties window to set or modify the property values for any component in your XML Schema. Set property values are marked with a green square.
Choose Edit > Undo Change Attribute from the main menu.
To change a property back to its default setting, click on the down arrow next to the property, and choose Reset to Default.
To set a component's properties:
20.6.16 How to Set Properties for Multiple XSD Components
If you have multiple components selected, by default the Properties window displays all the properties of the selected components. Click the Union button in the Properties window toolbar to toggle between displaying all the properties of the selected components (union) and displaying only the properties that the selected components have in common (intersection). Values represented in italic font indicate common properties that have differing values.
To set properties for multiple components:
20.7 Localizing with XML
JDeveloper has tools to support full localization for your application based on XML-based XLIFF technology. XLIFF supports a full localization process by providing tags and attributes that hold the data your translators and vendors will use when you internationalize your application.
For more information on XLIFF, see the OASIS open standard website at, http://www.oasis-open.org/home/index.php
To create a new XLIFF file:
-
Choose File menu >New > From Gallery > General > XML > XML Localization File.
20.7.1 What You May Need to Know About XLIFF Files
The main elements in an XLIFF file are the trans-unit elements. These elements store localizable text and its translations. These elements represent segments (usually sentences in the source file that can be translated reasonably independently). The trans-unit elements contain source, target, alt-trans, and a handful of other elements.
There are also elements for review comments, the translation status of individual strings, and metrics such as word counts of the source sentences. The XLIFF file consists of one or more file elements. Each of these contains a header and a body section. The header contains project data, such as contact information, project phases, pointers to reference material, and information on the skeleton file.
JDeveloper uses Resource Bundles to hold all of the localization information, including the XLIFF files. When you create content in a JSF page, a resource bundle is automatically created for you in that project.
20.8 Developing Databound XML Pages with XSQL Servlet
You will find a complete development environment to simplify the task of developing databound XML pages with XSQL servlet. XSQL servlet 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.
Table 20-7 shows the logical layers in an XSQL Servlet application.
Table 20-7 XSQL Servlet Logical Layers
| Layer | Description |
|---|---|
|
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 style sheets to convert XML to any of these languages. |
|
XSQL Servlet in a Web Servlet |
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. |
20.8.1 Supporting XSQL Servlet Clients
Support for XSQL Servlet includes the following:
-
XSQL tags on the Components window
-
Create XSQL pages automatically
-
Includes XSQL libraries
-
Provides
XSQLConfig.xmlon 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
20.8.2 How Can You Use XSQL Servlet?
XSQL servlets offer a simple and productive way to get XML in and out of the database. Using simple scripts you can:
-
Generate simple or complex XML documents
-
Apply XSL style sheets 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, the emp.xsql file below:
<?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 XML in below:
<EMPLOYEES>
<EMP>
<ENAME>Scott</ENAME>
<SAL>1000</SAL>
<DEPARTMENT>Boston</DEPARTMENT>
</EMP>
<EMP>
...
</EMP>
</EMPLOYEES>
For more information on XSQL Servlet, see your Oracle10i documentation.
20.8.3 How to Create an XSQL File
Using the wizard to create an XSQL file adds a skeleton file named untitled#.xsql to your project, which opens in the XML Editor. You can type code in this editor, add tags by selecting them from the Components window, and modify the file with your own style sheet information.
To create an XSQL file:
-
In the Applications window, select the project in which you want to create the new XSQL page.
-
Choose File > New > From Gallery.
-
In the Categories tree, expand General and select XML.
-
In the Items list, double-click XSQL File.
20.8.4 How to Edit XML Files with XSQL Tags
The XML Editor supports syntax highlighting in the Structure window view, and the Properties window. You can also select tags from the Components window to insert in your pages while you are editing.
To use the XML Editor to edit an XSQL file:
- In the Applications window, double-click right-click an XSQL file.
- Select the Source tab of the editor.
- Choose View > Components window to open the Components window and select the XSQL tag page from the dropdown list in the window. You can then select XSQL tags from the window.
- While you are typing, you can invoke Code Insight by pausing after typing the < (opening bracket) or by pressing Ctrl+Space (if you are using the default keymapping). Code Insight opens a list with valid tags.
- After selecting a tag, enter a space and then either pause or press Ctrl+Space to open a list of valid attributes from which you can select. After you enter the opening quote for the attribute value, Tip Insight displays the type of value that is required.
- While you are editing, or after you finish, you can right-click in the file and choose Auto Indent XML to correctly indent the file.
- You can also right-click in any tag and choose Locate in Structure to highlight that tag in the Structure window.
20.8.5 How to Check the Syntax in XSQL Files
You can check your XSQL file to determine if it is a well-formed XML document and if not, to find any errors. Errors display in the XML Validation Errors tab of the Log.
To check the syntax in an XSQL file:
-
In the Applications window, or in an open XML Editor window, right-click an XSQL file and choose Validate XML.
Note:
The Validate XML command on this context menu is disabled whenever an XML file does not have an XML namespace defined.
20.8.6 How to Create 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. This procedure shows how to use the XSQL Query tag to display data.
To create an XSQL servlet client that directly accesses the database:
You can format the XML data with a style sheet. The XML data also can be passed on to another application through a messaging service.
20.8.7 Creating XSQL Servlet Clients for Business Components
You can create XML-based clients for business components using XSQL servlet. 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.
To create an XSQL servlet client for business components:
You can format the XML data with a style sheet. The XML data also can be passed on to another application through a messaging service.
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.
20.8.8 What You May Need to Know About XSQL Error JBO-27122
You may get the XSQL error JBO-27122 while querying view objects with circular ViewLink accessors.
Consider a scenario in which there are foreign key relationships between multiple tables. For example, in the HR schema in the Oracle 10i Release 2 database samples, there is such a relationship between countries, departments, employees and locations tables. If you created a simple Business Components project on top of these tables and further created an XSQL client in which you access the view object called CountriesView1, you will get an error such as the one displayed in [the example below.
<?xml version="1.0" encoding="windows-1252" ?> - <!-- | Uncomment the following processing instruction and replace | the stylesheet name to transform output of your XSQL Page using XSLT <?xml-stylesheet type="text/xsl" href="YourStylesheet.xsl" ?> --> - <page> - <xsql-error action="xsql:action"> <message>JBO-27122: SQL error during statement preparation. Statement: SELECT Employees.EMPLOYEE_ID, Employees.FIRST_NAME, Employees.LAST_NAME, Employees.EMAIL, Employees.PHONE_NUMBER, Employees.HIRE_DATE, Employees.JOB_ID, Employees.SALARY, Employees.COMMISSION_PCT, Employees.MANAGER_ID, Employees.DEPARTMENT_ID, Employees.DN FROM EMPLOYEES Employees WHERE (Employees.DEPARTMENT_ID = :1)</message> </xsql-error> </page>
The reason you are getting this error is because of the way the underlying writeXML() method works in combination with the fact that you are using the default values for the max-levels parameter. This causes an infinite loop because of the circular references created by the foreign keys as mentioned above - internally causing an ORA-1000 MaxOpenCursors exceeded error.
The way to work around this is to modify your code as shown below:
<xsql:action handler="oracle.jbo.xsql.ViewObject"
name="YourViewUsageName"
appmodule="a.b.c.YourModuleName"
configname="YourModuleNameLocal">
<view-attribute-list viewdefname="a.b.c.YourViewName"
include-only"Attr1 Attr2 Attr3"
:
</xsql:action>
You can have multiple <view-attribute-list> elements for each view definition that you want to control the attribute list for. As soon as you have one <view-attribute-list> element, then use the new API for writeXML() that will only include the attributes that are listed in the <view-attribute-list> elements.
In order to show the details for a VO, you need to include the name of the view link accessory attribute in the list of attribute names in the "include-only" list for that view definition. The following example contains a working example based on the CountriesView.
<?xml version="1.0" encoding='windows-1252'?>
<!--
| Uncomment the following processing instruction and replace
| the stylesheet name to transform output of your XSQL Page using XSLT
<?xml-stylesheet type="text/xsl" href="YourStylesheet.xsl" ?>
-->
<page xmlns:xsql="urn:oracle-xsql">
<xsql:action
handler="oracle.jbo.xsql.ViewObject"
name="CountriesView1"
configname="HrModuleLocal"
appmodule="hr.HrModule">
<view-attribute-list viewdefname="hr.HrModule.CountriesView"
include-only="CountryId CountryName CurrencyName" />
</xsql:action>
</page>
20.8.9 How to Create 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 prebuilt action handlers for various tasks such as setting cookies, applying style sheets, performing queries against databases, and so on. 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.
To create an action handler:
- Add the XSQL configuration file to your project.
- In the XSQL configuration file, register the new action handler by specifying the element name and handler class.
- 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
XSQLActionHandlerImplclass.
The XSQL action handlers for BC4J are packaged as part of the JBO HTML library in JDeveloper, which includes the relevant: <JdevHome>/BC4J/jlib/bc4jhtml.jar archive in the build.
// Copyright (c) 2000, 2009, Oracle and/or its affiliates. All
rights reserved. import oracle.xml.xsql.*;
import org.w3c.dom.Node;
import java.util.Date;
/**
* A Class class.
* <P>
* @author Pas Apicella
public class JavaDate extends XSQLActionHandlerImpl
{
public void handleAction (Node root)
{
addResultElement(root, "CURRENTDATE", (new Date()).toString());
}
}
20.8.10 How to Deploy XSQL Servlets
XSQL servlet generates executable packages that contain the information and logic required to deploy the database to the servlet client environments. The database deployment package can be incorporated into a setup and deployment solution or can be shipped to clients as a separate application. When you deploy an XSQL servlet, you must specify a master database, the deployment scenario, and then generate a self-contained executable that is ready for deployment.
The following is a custom application. As you create it, you will add appropriate features for developing an XSQL application (that it, when you choose Java and XSQL as part of creating the application).
To deploy an XSQL servlet:
20.8.11 How to View 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 style sheet.
To view an XSQL file as raw XML data:
-
Select the XSQL file in the Applications window, right-click and choose Run to open the source file in your web browser.
JDeveloper starts the Integrated WebLogic Server, launches your default web browser, and displays the raw XML data that is produced after the XSQL servlet processes the XSQL page.
20.8.12 How to Create an XSL Style Sheet for XSQL Files
In JDeveloper, you can create an XSL style sheet that you can apply to your XSQL files in order to format the data for HTML, WML or another output. When you create an XSL style sheet, it is added to the selected XSQL project.
To create an XSL style sheet:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <!-- Root template --> <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"> <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>
20.8.13 How to Format XML Data with a Style Sheet
After creating an XSQL file and adding tags, you can format the XML data with an XSL style sheet or view the raw XML data. You can use a style sheet you previously created or create a new one in JDeveloper and apply it. By applying a style sheet, 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 style sheet:
20.8.14 How to Modify 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 file when you create a new connection in JDeveloper. 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.
Note:
When you migrate an XSQL project in JDeveloper, the XSQLConfig.xml file is not updated for you. You can update your connections after migrating the project by recreating the connection or editing an existing connection in JDeveloper.
To modify the XSQL configuration file for your project:
- With the project selected in the Applications window, choose Project > Add to Project <project name>.
- Navigate to the system directory in your JDeveloper installation directory, select
XSQLConfig.xmland click Open. - Make any changes or additions in the XML Editor.
- Choose File > Save to save your revised file.
20.8.15 Using XML Metadata Properties in XSQL Files
The custom properties shown in Table 20-8 affect XML generation when using the writeXML method of a view object or row.
Table 20-8 Metadata Properties
| Property Name | Value | Valid For |
|---|---|---|
|
XML_ELEMENT |
a legal element name |
view objects and view attributes |
|
XML_ROW_ELEMENT |
a legal element name |
view objects |
|
XML_CDATA |
any value (not empty) |
view attributes |
|
XML_EXPLICIT_NULL |
any value (not empty) |
view objects and view attributes |
20.8.15.1 Using 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
produces XML like:
<Departments>
<DeptViewRow>
<Empno>1010</Empno>
<Ename>Steve</Ename>
<Salary>1234</Salary>
</DeptViewRow>
</Departments>
instead of the default:
<DeptView>
<DeptViewRow>
<Empno>1010</Empno>
<Ename>Steve</Ename>
<Sal>1234</Sal>
</DeptViewRow>
</DeptView>
20.8.15.2 Using 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.
For example, for a view object named DeptView with an attribute named Sal, setting:
-
XML_ELEMENT="Departments" in the view object properties
-
XML_ROW_ELEMENT="Department" in the view object properties
-
XML_ELEMENT="Salary" in the view attribute properties for
Sal
produces XML like:
<Departments>
<Department>
<Empno>1010</Empno>
<Ename>Steve</Ename>
<Salary>1234</Salary>
</Department>
</Departments>
instead of the default:
<DeptView>
<DeptViewRow>
<Empno>1010</Empno>
<Ename>Steve</Ename>
<Sal>1234</Sal>
</DeptViewRow>
</DeptView>
20.8.15.3 Using 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.
20.8.15.4 Using 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:
<AttributeName null="true"/>
instead of omitting the <AttributeName> element from the XML result, which is the default.