15 Developing Applications Using XML

This chapter describes how to create and update applications using the XML tools and editors provided by JDeveloper.

This chapter includes the following sections:

15.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 also use JDeveloper to create and edit your XSQL files. It provides a robust XML editing environment that allows you to create and edit many different types of XML files in your application.

XML Schema development is easy with JDeveloper. You can create a schema document from scratch, generate schemas from XML documents or vice-versa. Once your schema is created, manage your elements using the XSD Visual Editor and the Component Palette. For more information, see Section 15.5, "Working with XML Schemas".

You can also create XSQL files from scratch or edit existing files. JDeveloper provides a complete development environment to simplify the task of developing databound XML pages with XSQL servlet. For more information, see Section 15.6, "Developing Databound XML Pages with XSQL Servlet".

15.2 Using the XML Editors

JDeveloper provides three different editors for working with your an XML files.

15.2.1 Understanding XML Editing Features

Table 15-1 summarizes the editing features that are available when you're working with XML files.

Table 15-1 XML Editing Features

Feature Purpose

Code Insight

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 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 Application Navigator, 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

These features can be customized in 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 <foo and you type the >,</foo> is added automatically.

Component Palette

You can choose View > Component Palette to open the palette 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 palette.

Property Inspector

The Property Inspector displays attributes of elements in the file. You can edit the values of attributes in the Property Inspector 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 Application Navigator, 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 complexType element. This is convenient because the list of attributes that display under the element can be large.

15.2.2 Understanding the XML Editor Toolbar

Table 15-2 contains the icons that display on the XML Editor toolbar.

Table 15-2 XML Editor Toolbar Icons

Icon Name Description

Search (Ctrl +F)

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)

Find Next (F3)

Click to locate the first occurrence of the text that meets the specified parameters in the file.

Find Previous (Shift + F3)

Find Previous (Shift + F3)

Click to locate the previous occurrence of the text that meets the specified parameters in the file.

15.3 Creating XML Files in Oracle JDeveloper

The New Gallery offers several different XML file type options, as shown in Table 15-3. To create a new XML file choose File menu > New > General > XML.

Table 15-3 XML File Types

File Type Description

XML Document

Create a new XML file that includes only the <?xml version="1.0"?> line at the top.

XML Document from XML Schema

Generates an XML document from an existing XML schema.

XML Localization File (XLIFF)

Creates an XML-based localization file with an .xlf extension. For more information, see Section 15.3.1, "Localizing with XML".

XML Document from XML Schema

Generates as XML Document from an XML Schema.

XQuery File

Creates an XQuery File with an .xq extension. For more information, see Section 15.4.2, "Using XQuery with XML".

XSL Map

Creates an XSL Map File with an .xsl extension.

XSL Map from XSL Stylesheet

Creates an XSL Map File with an .xsl extension from an XSL Stylesheet.

XSL Stylesheet

Creates an XSL Stylesheet with an .xsl extension. For more information, see Section 15.6.12, "How to Create an XSL Style Sheet for XSQL Files".

XSQL File

Creates an XSQL file with an .xsql extension. For more information, see Section 15.6.2, "How to Create an XSQL File".

15.3.1 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.

15.3.1.1 How to Create a New XLIFF file

You create a new XMLFF file in the JDeveloper New Gallery under the XML node.

To create a new XLIFF file:

Choose File menu >New > General > XML > XML Localization File.

For more information on XLIFF, see the OASIS open standard website at, http://www.oasis-open.org/home/index.php

15.3.1.2 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.

15.3.2 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.

To import and register an XML schema:

  1. From the main menu, choose Tools > Preferences.

  2. Select the XML Schemas node.

  3. Click Add to open the Add Schema dialog where you can specify a new schema to add to the list of user schemas.

  4. 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.

  5. Enter the file extension to register the schema for a specific file type in the Extension field. JDeveloper uses the extension to efficiently load the schema into memory and to display automatically created Component Palette pages based on the items in the schema.

  6. Click OK.

    JDeveloper automatically validates the schema when you add it.

  7. Confirm that the new schema has been added in the User Schemas for XML Editing list and click OK.

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.

15.3.3 How to Add an XML Element to the Palette

You can add pages to the Component Palette in JDeveloper to include the elements from a registered schema or you can add elements to an existing page. Once you add the elements to the Palette, you can insert the elements into the XML file while you are editing, by selecting them from the Palette.

To add XML elements to the Component Palette:

  1. From the main menu, choose Tools > Configure Palette to open the Configure Component Palette dialog.

    Skip to step 4 if you do not want to add a new page.

  2. Click Add under the Pages list to open the New Palette Page dialog.

  3. In the New Palette Page dialog, enter the name of the new page and select the appropriate type from the dropdown list, then click OK.

    Your new page name is added to the bottom of the Pages list in the Configure Component Palette dialog.

  4. Select the new page name in the Pages list and click Add under the Components list to open the XML Elements dialog.

    The XML Elements dialog displays the Registered Schemas.

  5. Expand the appropriate schema node to display the elements you can add to the Palette.

  6. To add an individual element, select it in the tree. To add multiple elements, use Ctrl-click or Shift-click to select them. Then click OK.

    You can also click Use Default Icon or Select Icon to select the icon that will display for an individual element on the Palette, before you click OK.

  7. After adding XML elements, click OK to close the Configure Component Palette dialog.

The name of the page you added displays in the dropdown list in the Palette. All the elements you added are displayed with angle brackets (< >) as the icon, if you accepted the default icon. If you do not see any element names on the Palette, right-click in the Palette and choose List View.

15.3.4 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:

  1. From the main menu choose File > New > Business Tier > TopLink/JPA and select either JAXB 1.0 or 2.0 Content Model from XML Schema to open the compilation dialog.

  2. Select the schema file and optionally the JAXB customization file to use and the package to which the generated classes will be added.

    The JAXB package and generated classes are added to the Application Resources folder.

15.4 Editing XML Files in Oracle JDeveloper

The XML Source Editor in JDeveloper is a specialized schema-driven editor for editing XML languages including XSD, WSDL, XSQL, XHTML, and XSL files.

To edit an XML file in the XML Source Editor:

  1. In the Navigator, right-click a file and choose Open.

  2. Click the Source tab if not selected by default for that file.

  3. 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 elements, based on the schema.

  4. 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, Tip Insight displays the type of value that is required.

Tip:

To edit an XML document with the Component Palette, choose View > Component Palette to open the Palette and select one of the available pages from the dropdown list. Then choose elements from the page.

15.4.1 How to Set Editing Options for the XML Editor

When editing XML files in the XML Editor you can set two editing options.

To customize editing options for the XML Editor:

  1. Choose Tools > Preferences.

  2. Expand the Code Editor node.

  3. Select the XML node.

  4. Select the XML node. On the XML Preferences page, select Required Attribute Insertion or End Tag Completion to enable the desired options.

  5. Click OK.

15.4.2 Using XQuery with XML

You can create and edit your XML-based XQuery files in JDeveloper. XQuery provides the means to extract and manipulate data from XML documents or any data source that can be viewed as XML, such as relational databases or office documents.

15.4.2.1 How to Create a New XQuery File

You create a new XQuery file in the JDeveloper New Gallery under the XML node.

To create a new XQuery file:

Choose File menu, > New, > General > XML > XQuery File.

For more information on XQuery, see the W3C website at, http://www.w3.org/TR/xquery/

15.4.2.2 What You May Need to Know About XPath Expression Syntax

XQuery uses XPath expression syntax to address specific parts of an XML document. It supplements this with a SQL-like "FLWOR expression" for performing joins. A FLWOR expression is constructed from the five clauses after which it is named: FOR, LET, WHERE, ORDER BY, RETURN.

The language is based on a tree-structured model of the information content of an XML document, containing seven kinds of node: document nodes, elements, attributes, text nodes, comments, processing instructions, and namespaces.

15.5 Working with XML Schemas

JDeveloper provides an XSD Visual Editor that gives a visual representation of the structure, content, and semantics of an XML document.

15.5.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 15-1 contains an example XML schema in the Design tab of the XSD Visual Editor.

Figure 15-1 Schema in XSD Visual Editor

Schema in XSD Visual Editor

You can edit attributes in attribute2 in the attribute editor, which is displayed in Figure 15-1 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 subtree containing child nodes like list or union.

15.5.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. Example 15-1 contains the source for the example.xsd file shown in Figure 15-1.

Example 15-1 XML Source

<?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>

15.5.3 Understanding the XSD Component Display in the XSD Visual Editor

The JDeveloper XSD Visual Editor provides a visual representation of the structure, content, and semantics of an XML document. Use the XSD Visual Editor to author a new, or to edit an existing, XML Schema.

15.5.3.1 XSD Component Selection

The selection of any component or attribute in the editor is indicated by highlighting the selected item in blue. In Figure 15-2, 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 15-2 simpleType Component

simpleType component

15.5.3.2 XML Schema Component

The XML Schema component is displayed at the top of an XSD file, as shown in Figure 15-3. Right-click the element and select Properties to display a dialog for configuring the schema namespaces.

Figure 15-3 XML Schema Component

XML Schema Component

15.5.3.3 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 15-4. Set attribute maxOccurs to >1 to have more than one item from the choice in the parent.

Figure 15-4 Choice Component

Choice Component

15.5.3.4 All Component

The all component shown in Figure 15-5 specifies that the child components can appear in any order and that each child component can occur zero or one time.

Figure 15-5 All Component

All Component

15.5.3.5 Sequence Component

The sequence component shown in Figure 15-6 specifies that the child components must appear in a sequence. Each child component can occur from 0 to any number of times.

Figure 15-6 Sequence Component

Sequence Component

15.5.3.6 Cardinality and Ordinality

In the example of cardinality shown in Figure 15-7, components are displayed with the following attributes:

  • Required components (minOccurs=">0") are displayed with a solid line.

  • Optional components (minOccurs="0") are displayed 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) and the number after the colon indicates the maximum number of times the component can occur (maxOccurs). In the illustration the maximum is unbounded so an infinity symbol is displayed.

  • Range of components is displayed in the component stack number. In the illustration the component must appear at least 2 times in the instance document, but no more than 7.

Figure 15-7 Cardinality Component

Cardinality Component

15.5.3.7 ComplexType Component

In Figure 15-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 15-8 complexType Component

complexType Component

15.5.3.8 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 15-9 displays three attribute groups.

Figure 15-9 Attribute Group Component

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.

15.5.3.9 Union Component

The union component defines a simple type as a collection (union) of values from specified simple data types. In Figure 15-10, the union represents all strings that begin with the letter "i".

Figure 15-10 Union Component

Union Component

15.5.3.10 List Component

The list component defines a simple type component as a space separated list of values of a specified data type. In Figure 15-11, the component represents a series of short value objects.

Figure 15-11 List Component

List Component

15.5.4 How to Generate an XML Schema from XML Documents

Use the XML wizard in the New Gallery to help you quickly generate industry standard W3C XML schema (.xsd) from your XML (.xml) documents. Conversely, you can also generate XML documents from your XML schema.

To generate an XML schema from an XML document:

  1. Choose File menu > New > General > XML > XML Schema from XML Document.

  2. Enter the information as directed.

To generate an XML document from an XML schema

  1. Choose File menu > New > General > XML > XML Documents from XML Schema.

  2. Enter the information as directed.

15.5.5 How to Generate an XSD File from a DTD File

You can generate an XML schema document (XSD) file from a document type definition (DTDs) file.

To generate an XSD file from a DTD:

  1. On the main menu, click Tools.

  2. In the Tools menu, click Convert DTD to XSD.

15.5.6 How to Display an XSD File for Editing

Open a schema (.xsd) file for editing in the XSD Visual Editor or XML Source Editor. By default new schema files are opened with the XSD Visual Editor in focus. Double-clicking a file in the Application Navigator 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.

A schema file (.xsd) can be edited simultaneously with 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.

15.5.7 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.

  1. In the Application Navigator, double click the .xsd file you want to display in the XSD Visual Editor.

  2. Click the Design tab in the XSD Visual Editor.

    A design view of the .xsd file displays, similar to Figure 15-12.

    Figure 15-12 Design Tab in XSD Visual Editor

    Design Tab in XSD Visual Editor

  3. Right-click anywhere on the Design tab and choose Publish Diagram.

  4. Enter a name, the path where you want to save the diagram, and the image type you want to use.

    Notes:

    If the diagram you are attempting to save is too large, a message displays indicating that the image should be saved in .svg format.

    If you right-click on a node in the XSD Visual Editor, only the current node and its child nodes are saved as an image.

15.5.8 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:

  1. In the XSD Visual Editor press and hold down the spacebar.

    The pointer turns into an open hand cursor.

  2. Press and hold down the left mouse button.

    The hand closes and grabs the XML Schema page.

  3. Use your mouse to move the XML Schema page inside the editor window.

  4. Release the XML Schema page by releasing the left mouse button.

  5. Close grab scroll by releasing the spacebar.

15.5.9 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.

To expand one level beyond the parent component:

Click the + (plus) sign of the parent component.

To collapse all levels below the parent component:

Click the - (minus) sign of the parent component.

To expand all parent components in the schema:

Press Ctrl + *, using the * on the numeric keypad of the keyboard.

Note:

This view can be big.

15.5.10 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.

To zoom in:

  1. Place your cursor in the area of the XML Schema you wish to magnify.

  2. Press Ctrl+Plus.

    Note:

    Use the Plus on the numeric keypad of the keyboard.

To zoom out:

  1. Place your cursor on the area of the XML Schema you wish to shrink.

  2. Press Ctrl+Minus.

    Note:

    Use the Minus on the numeric keypad of the keyboard.

15.5.11 How to Select XSD Components

One of the most common actions you perform in the XSD Visual Editor or Structure window (Design or Source view) is to select components in order to do something with them. There are several reasons for selecting components:

  • Edit the properties of the component(s)

  • Move the component(s)

  • Delete the component(s)

  • Select a target position in which to insert another component

You can select a single component without children, a component along with its children, and multiple components.

To select a 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 a property editor for the component.

To select multiple components:

  1. Click the first component.

  2. Press and hold down the Ctrl key.

  3. Click any additional components. If you want to deselect one without losing the other selections, continue to hold down the Ctrl key and click the component again.

    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.

15.5.11.1 What Happens When You Select a Component in the XSD Visual Editor

When a component is selected in the XSD Visual Editor, the component displays in blue. When a container component is selected and any of its children are also explicitly selected, all are displayed in blue.

When selected in the Structure window (Design or Source view), the component is highlighted. However, when you select any components with children, the children are also selected with it, even if their names are not selected. If you delete or move the parent, all the children are deleted or moved with it.

Whenever you select an component, you are also selecting a position in which another component can be inserted. For more information, see Section 15.5.12, "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. That makes it easier to know where to click to select a component.

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. That means that you can look at the selection in both tools to clarify what is selected and where the insertion position is.

The JDeveloper status bar explicitly states the insertion point for a selected component.

15.5.12 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:

Choose from one of the following options:

  • Select the target position by clicking the node on which you are performing the action.

  • 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 (visual editor) or horizontal line with an embedded up arrow (structure), then release the mouse button.

      Schema Insert Up

    • To insert a component after a target node, drag it towards the bottom of the node until you see a solid horizontal line (visual editor) or a horizontal line with an embedded down arrow (structure), then release the mouse button.

      Schema Insert Down

    • 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. The options are:

    • 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.

15.5.13 How to Insert XSD Components

In the XSD Visual Editor and Structure window (Design and Source view), you can insert XSD components by dragging from the Component Palette or by using a context menu. 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. For more information, see Section 15.5.16, "How to Cut, Copy, and Paste XSD Components".

Note:

Pasting multiple components that were copied from different places in the XML schema hierarchy can lead to unexpected results.

To insert XSD components using the Component Palette:

  1. In the XSD Visual Editor or Structure window, locate the desired position where you wish to insert a component. You may have to expand nodes in the Structure window to uncover the node you want.

  2. In the Component Palette, select an XSD component list from the dropdown list box, and then drag the desired component from the list and drop into the desired target position in the XSD Visual Editor or Structure window.

You can also select the target position in the visual editor or Structure window and then click the desired component in the Component Palette.

Tip:

A brief description of a component appears when the cursor is placed over a component name in a list. For detailed help, right-click a components in the list and choose Help.

To insert XSD components using the context menu:

  1. In the XSD Visual Editor or Structure window, right-click the desired node to display a context menu. You may have to expand nodes to uncover the node you want.

  2. Choose an option in the context menu, and then select a component. The options are:

    • 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 in the context menu 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.

15.5.14 How to Set and Modify XSD Component Properties

The Property Inspector displays the properties of XSD components selected in the XSD Visual Editor or the Structure (Design or Source view) window. Use the Property Inspector to set or modify the property values for any component in your XML Schema. Set property values are marked with a green square.

To undo changes, from the main menu select Edit, > Undo action. Use the Set to Default button to reset a property that has been set to its default value (if any).

To set a component's properties:

  1. With an XML Schema open, select a component in the visual editor or Structure window.

    The Property Inspector displays the property values for the selected component. If the Property Inspector is not in view choose View > Property Inspector or use the shortcut Ctrl+Shift+I.

  2. Scroll until the property you want is visible, then select it with the mouse or the arrow keys.

    A brief description of the property is displayed at the bottom of the Property Inspector.

    Tip:

    To quickly locate a property in a long list, click the search button in the Property Inspector toolbar. In the Find text field, type the name of the property, then press Enter.

  3. Enter the property value in the right column in one of the following ways:

    • In a text field, type the string value for that property, for example a text value or a number value, then press Enter.

    • In a value field with a down arrow, click the down arrow and choose a value from the list, then press Enter.

    • In a value field with an ellipsis (...), click the ellipsis to display an editor for that property. Set the values in the property editor, then press OK.

    Tips:

    Double-click an XSD component or right-click the component and choose Properties to display a property editor for the component.

    In the property editor select an attribute and view a brief description in the status area below the editor.

    Click Help in the property editor for a link to a component reference topic.

15.5.15 How to Set Properties for Multiple Components

If you have multiple components selected, by default the Property Inspector displays all the properties of the selected components. Click the Union button in the Property Inspector 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:

  1. Hold down the Ctrl key and select each of the components.

  2. To change the list of properties displayed by the Property Inspector, click the Union button in the Property Inspector toolbar.

    • Selected state displays all the properties of the selected components.

    • Unselected state displays only the properties the selected components have in common.

  3. Select and edit the desired property in the Property Inspector.

    If the value is shown in italic font, the selected components have differing values. Editing the value of a shared property will cause all selected components to have the same value.

15.5.16 How to Cut, Copy, and Paste XSD Components

You can cut, copy, and paste XSD components in the XSD Visual Editor or Structure (Design or Source) window. You can perform these operations between files of the same project or different projects.

15.5.16.1 Cutting Components

When you cut a component, it is removed from the editor and placed into a local clipboard only accessible by JDeveloper, not to the system clipboard. If you quit JDeveloper without pasting the component, the cut version of the component will be lost.

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 Section 15.5.18, "How to Delete XSD Components".

To cut one or more components:

  1. Select the XSD component you wish to cut in the visual editor or the Structure window.

  2. Do one of the following:

    • Press Ctrl+X.

    • Right-click and select Cut.

    • Choose Edit > Cut from the main menu.

15.5.16.2 Copying Components

You can copy XSD components in the visual editor or the Structure window.

To copy one or more components:

  1. Select the XSD component you wish to copy in the visual editor or the Structure window.

  2. Do one of the following:

    • Press Ctrl+C.

    • Right-click and select Copy.

    • Choose Edit > Copy from the main menu.

    • Hold down Ctrl and drag a copy of the selected component to a target position.

15.5.16.3 Pasting Elements

The elements you cut or copy from the XSD Visual Editor or Structure window can be pasted into any other XSD file in JDeveloper. For more information, see Section 15.5.12, "How to Select Target Positions for XSD Components".

To paste an element:

  1. Open the file in which you want to paste a XSD element in the visual editor or Structure window.

  2. Select the insertion point where you want to paste the element.

  3. Do one of the following:

    • Press Ctrl+V.

    • Right-click and select Paste.

    • Choose Edit > Paste.

15.5.17 How to Move XSD Components

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 or by cutting and pasting. 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. 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 Section 15.5.11, "How to Select XSD Components".

You can move one or multiple components at a time. However, you should be aware that selecting and moving multiple, non-adjacent components or multiple components from different levels in the schema hierarchy can lead to unexpected results.

To move components by dragging

In the visual editor or Structure window 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 Section 15.5.12, "How to Select Target Positions for XSD Components".

  • Right-click drag the component(s) from the original position to an insertion point in the visual editor or Structure window, and then choose Move Nodes Here from the context menu.

To move components by cutting and pasting:

In the visual editor or Structure window do either of the following:

  • Cut the component(s). Then, paste into some other position in the visual editor or Schema structure window.

  • Cut the component(s). Then, paste 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.

15.5.18 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:

  1. Select one or more XSD components you wish to delete in the visual editor or Structure window. For more information, see Section 15.5.11, "How to Select XSD Components".

  2. Do one of the following:

    • Press the Delete key.

    • Press Ctrl+X.

    • Right-click and select Delete.

    • Choose Edit > Delete from the main menu.

15.6 Developing Databound XML Pages with XSQL Servlet

JDeveloper provides a complete development environment to simplify the task of developing databound XML pages with XSQL servlet.

15.6.1 Supporting 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

15.6.1.1 What is 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.

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 (BC4J), 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 style sheets 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.

15.6.1.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 developers 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, a file such as emp.xsql in Example 15-2:

Example 15-2 emp.sql File

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="emp.xsl"?> 
<FAQ xmlns:xsql="urn:oracle-xsql" connection = "scottDS">
  <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 Example 15-3:

Example 15-3 XML File

<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 Oracle database documentation.

15.6.2 How to Create an XSQL File

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. In the Navigator, select the project in which you want to create the new XSQL page.

  2. Choose File > New to open the New Gallery.

  3. In the Categories tree, expand General and select XML.

  4. In the Items list, double-click XSQL Page.

This will add a skeleton XSQL 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 Component Palette, and modify the file with your own style sheet information.

15.6.3 How to Edit XML Files with XSQL Tags

JDeveloper's XML Editor supports syntax highlighting, Structure window view, and the Property Inspector. You can also select tags from the Component Palette to insert in your pages while you are editing.

To use the XML Editor to edit an XSQL file:

  1. In the Navigator, right-click an XSQL file and choose XML Editor.

  2. Choose View > Componenet Palette to open the Component Palette and select the XSQL tag page from the dropdown list in the Palette. You can then select XSQL tags from the Palette.

  3. 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.

  4. 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.

  5. While you are editing, or after you finish, you can right-click in the file and choose Auto Indent XML to properly indent the file.

  6. You can also right-click in any tag and choose Locate in Structure to highlight that tag in the Structure window.

15.6.4 How to Add 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 Palette if it is not displayed.

  4. Select XSQL Tags from the dropdown list in the Palette if it is not displayed.

  5. Select the appropriate tag from the 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 or click Help in the dialog to get help for an XSQL tag and its attributes.

  7. After entering attributes, click Next to display the next dialog or click Finish if it is enabled.

    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 style sheet.

15.6.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.

To check the syntax in an XSQL file:

In the Navigator, or in an open XML Editor window, right-click an XSQL file and choose Check XML Syntax.

The results display in the Log window.

Note:

The Validate XML command on this context menu is disabled whenever an XML file does not have an XML namespace defined.

15.6.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. 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 to open the New Gallery.

  2. In the Categories tree, expand General and select Projects.

  3. In the Items list, double-click Empty Project to open the New Project dialog.

  4. Complete the New Project dialog and click OK to add the empty project to your workspace.

  5. Select the new project in the Navigator and choose File > New.

  6. In the Categories list, select General and select XML.

  7. In the Items list, double-click XSQL Page.

    This adds a skeleton XSQL file named untitled#.xsql to your project.

  8. In the Navigator, right-click the new XSQL file, and choose XML Editor to open the source file.

  9. Place your cursor in the blank line after the <page xmlns:xsql="urn:oracle-xsql"> tag.

  10. Choose View > Component Palette to open the Palette if it is not displayed.

  11. Select XSQL Tags from the dropdown list in the Palette if it is not displayed.

  12. Drag the Query (XSQL) tag from the Palette onto the XSQL file.

    The Query tag executes a SQL statement and includes its result set in XML format.

  13. 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.

  14. After entering attributes, click Next.

  15. In the Connection Selection dialog, select your connection or create a new database connection, then click Next.

  16. In the Query dialog, type the SQL statement that you want to execute, then click Next.

    For example, you might type select * from customer to display all the records in the customer database, based on the attributes you entered.

  17. Click Finish.

    Notice that the Query tag and attributes you entered appear in the XSQL page.

  18. Choose File > Save All to save your work.

  19. Right-click the XSQL file in the Navigator, and choose Run filename.xsql to view the raw XML data in your web browser.

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.

15.6.7 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.

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 to open the New Gallery.

  2. In the Categories tree, expand General and select Projects.

  3. In the Items list, double-click Empty Project to open the New Project dialog.

  4. Complete the New Project dialog and click OK to add the empty project to your workspace.

  5. Select the new project in the Navigator and choose File > New.

  6. In the Categories list, select General and select XML.

  7. In the Items list, double-click XSQL Page.

    This adds a skeleton XSQL file named untitled#.xsql to your project.

  8. In the Navigator, right-click the new XSQL file, and choose XML Editor to open the source file if it is not open.

  9. Place your cursor in the blank line after the <page xmlns:xsql="urn:oracle-xsql"> tag.

  10. Choose View > Component Palette to open the Palette if it is not displayed.

  11. Select XSQL tags from the dropdown list in the Palette if it is not displayed.

  12. Select the ViewObject Show tag from the 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 transformed XML document.

  13. In the View Object Selection dialog, select the appropriate view object > click Next.

  14. Change or accept the default values for the attributes. Press F1 or click Help in the dialog to get help on the tag and its attributes. After entering attributes, click Next.

  15. Click Finish.

    Notice that the tag and attributes you entered appear in the XSQL page.

  16. Choose File > Save All to save all your work thus far.

  17. Right-click the XSQL file in the Navigator, and choose Run filename.xsql to view the raw XML data in your web browser.

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:

Please refer to the section titled "Caveats while Querying View Objects with Circular ViewLink Accessors" in the ViewObject Show F1 help topic if you get the XSQL error JBO-27122.

15.6.7.1 What You May Need to Know About Business Components XSQL Action Handlers

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.

15.6.8 How to 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 prebuilt action handlers for various tasks such as setting cookies, applying style sheets, 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.

To create an action handler:

  1. Add the XSQL configuration file to your project.

  2. In the XSQL configuration file, register the new action handler by specifying the element name and handler class.

  3. In the XSQL file, add the new element and its attributes.

  4. In the XSQL file, add connection information to the <page> tag.

  5. Add a Java file to the project.

  6. 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 JDeveloper, which includes the relevant: <JdevHome>/BC4J/jlib/bc4jhtml.jar archive in the build.

Example 15-4 Action Handler For XSQL

// 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()); 
    }
}

15.6.9 How to Run and Deploy XSQL Servlet Clients

After you have completed your XSQL file, you can test the XSQL query by running it in Integrated WebLogic Server, which provides everything you need to develop, test and debug web applications from within the IDE. For more information, see Section 9.2, "Running Java EE Applications in the Integrated Application Server."

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 Log window.

  2. If there are no XML syntax errors, right-click the XSQL file and select Run filename.xsql.

    JDeveloper compiles the servlet. It then starts the Integrated WebLogic Server. The first time you start Integrated WebLogic Server, a dialog is displayed where you have to enter a password for the default user weblogic on the default domain. You only need to do this once.

JDeveloper launches your default web browser, and displays the output of the servlet in the browser.

After the XSQL file has run successfully in Integrated WebLogic Server, you can deploy the application containing it to an external application server, such as Oracle WebLogic Server.

To deploy an XSQL application:

  1. The syntax used by JDeveloper and Oracle WebLogic Server to run XSQL is different, so in your XSQL source file you have to change the connection information as follows. Replace:

    connection="java:comp/env/jdbc/database-connection-nameDS"

    with

    connection="jdbc/database-connection-nameDS"

    Note:

    If you want to run the application in the Integrated WebLogic Server, you need to change the connection information back again.

  2. In order to deploy the application, you first have to create a deployment profile and deploy the application to it. In the navigator, right-click the project containing your XSQL servlet, then choose New. In the New Gallery, expand General and select Deployment Profiles.

  3. Choose a profile, for example, a WAR deployment profile and click OK and continue to create the deployment profile. For more information, see Section 9.3.2, "How to Create and Edit Deployment Profiles."

  4. To deploy the application to the deployment profile, right-click on the project containing your XSQL servlet files and choose Deploy > profile where profile is the name of the deployment profile you just created.

    In the Deployment dialog, choose Deploy to WAR (or the appropriate option if you have chosen a different type of deployment profile) and click Finish.

  5. The application is now ready to deploy to an application server, for example, Oracle WebLogic Server. The steps you need to perform are:

    Once the application is deployed, you can view the results of the query in a browser window by navigating to http://targethost:port/web-context-root/filename.xsql.

15.6.10 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 Navigator, right-click and choose Run filename.xsql 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.

15.6.11 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:

  1. In the Navigator, select the XSQL file to which you want to add a style sheet, right-click and choose XML Editor to open the source file.

  2. Locate the xml-stylesheet line and comment, which looks like this:

    <!--
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" ?>
-->

  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 style sheet; for example, your style sheet could be named stylesheet1.xsl.

    Next, add the file that you just specified to your project, if you used one 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 style sheet file you specified.

  6. Click Open.

  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 filename.xsql to open the file in your web browser.

    You can see the formatted XML data in the browser.

15.6.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:

  1. In the Navigator, select the project in which you want to create the new XSL file.

  2. Choose File > New to open the New Gallery.

  3. In the Categories tree, expand General and select XML.

  4. In the Items list, double-click XSL Style Sheet to open the New XSL File dialog.

  5. Leave the Directory Name field unchanged to save your work in the directory where JDeveloper expects to find web application files. In the File Name field, enter the name of the file you want to generate.

    A skeleton XSL file is generated and appears in your active project.

You can edit it in the XML Editor to create your own custom style sheet. An example of an XSL style sheet that transforms XML data into wireless markup language (WML) is provided below. When you are finished, you can specify the style sheet name in your XSQL file to format the raw XML data.

XSL Style Sheet Example

The style sheet in Example 15-5 demonstrates the conversion of XML to WML. It uses the default DeptView in a BC4J application.

Example 15-5 Conversion of XML to WML

<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"/>&nbsp;</strong>
   xsl:value-of select="Dname"/>&nbsp;
   <xsl:value-of select="Loc"/>
   </p>
   </xsl:for-each>
   </card>
</wml>

</xsl:template>
</xsl:stylesheet>

15.6.13 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:

  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 Open.

  3. Make any changes or additions in the XML Editor.

  4. Choose File > Save to save your revised file.

15.6.14 Using XML Metadata Properties in XSQL Files

The custom properties shown in Table 15-4 affect XML generation when using the writeXML method of a view object or row.

Table 15-4 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

15.6.14.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

would produce 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>

15.6.14.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

would produce 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>

15.6.14.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.

15.6.14.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.