17 Developing Applications Using XML

This chapter describes how to create well-formed XML documents using the IDE.

This chapter contains the following sections:

• Section 17.1, "About Developing Applications Using XML"

• Section 17.2, "Creating and Editing XML Documents"

• Section 17.3, "Generating a DTD from an Existing XML File"

• Section 17.4, "Creating an Empty DTD"

• Section 17.5, "Generating Documentation for a DTD"

• Section 17.6, "Registering a Local DTD or XML Schema"

• Section 17.7, "Removing a DTD or XML Schema Entry from the User Catalog"

17.1 About Developing Applications Using XML

You can use the IDE to create XML documents.

To create an XML document using the IDE:

1. Create a new XML, CSS, DTD, or XSL stylesheet document.

2. Use the Source Editor to open and edit the XML document.

3. Check the XML document.

   • Check that the document is well formed.

   • Validate documents constrained by an XML Schema or DTD.

17.2 Creating and Editing XML Documents

The Extensible Markup Language (XML) is a subset of SGML designed to enable generic SGML to be served, received, and processed on the Web easily and efficiently. Because its format is not fixed, XML enables you to design your own customized markup languages with which to create various types of documents.In the IDE, XML documents are represented by XML nodes (). The IDE provides tools to assist you in creating, editing, checking, and validating the various XML document types it supports.

The IDE supports several types of XML documents, including:

• Cascading Style Sheet. A CSS ( ) provides a simple mechanism for formatting and adding style to HTML and XML documents.

• Document Type Definition. A DTD ( ) describes the grammar that can be used in an XML file and indicates the valid arrangement of the file's tags. It can exist as a prologue to an XML file (internal DTD) or as a separate file (external DTD).

• Parsed Entity Objects. Parsed entity nodes represent parsed entity (.ent) files. If several of your XML documents refer to a single piece of information, you can store that information in a parsed entity. Any changes you make to the parsed entity are then automatically reflected in all of the documents that reference it.

  For more information about using parsed entities in XML documents, see:

  http://www.w3.org/TR/REC-xml/#TextEntities

• XML Catalogs. XML catalogs ( ) provide mapping information that maps an external entity in an XML document to the actual location of the document being referenced. You can use a catalog to redirect mappings for an external entity, such as a DTD or XML file, to a different location.

• XSL Stylesheet. XSL stylesheets ( ) define transformation rules for your XML documents. You can perform an XML transformation to transform the data in an XML document into the output of your choice, such as formatted HTML or a text file.

You can use the New File wizard to create regular well-formed documents with no DTD or schema constraints, DTD-constrained documents, and XML schema-constrained documents.

17.2.1 How to Create a Well-formed XML Document

You can use the IDE to create an XML document whose syntax conforms to the XML specification.

To create a well-formed XML document:

1. From the main window, choose File > New File.

2. In the New File wizard, select the XML node in the Categories pane and the XML Document node in the right pane. Then click Next.

3. Specify a name and location for the document and click Next.

4. Select Well-formed Document and click Finish.

   The IDE creates the new XML document in the specified location

17.2.2 How to Create a DTD-constrained XML Document

You can use the IDE to create a well-formed XML document whose structure is determined by a document type definition (DTD).

To create a DTD-constrained XML document:

1. From the main window, choose File > New File.

2. In the New File wizard, select the XML node in the left pane and the XML Document node in the right pane. Then click Next.

3. Specify a name and location for the document and click Next.

4. Select DTD-Constrained Document and click Next.

5. Type the DTD Public ID or select it from the combo box list of all public IDs for your mounted XML catalogs. Once you have specified the DTD public ID, press Enter to automatically load the DTD information in the wizard.

6. Specify the DTD system ID for your document.

7. Specify the document root for your document. The Document Root combo box contains all of the declared entities in your DTD.

8. Click Finish.

   The IDE creates the new XML document in the specified location.

17.2.3 How to Create an XML Schema-constrained Document

You can use the IDE to create a well-formed XML document whose structure is determined by an XML schema.

To create an XML schema-constrained document:

1. From the main window, choose File > New File.

2. In the New File wizard, select the XML node in the left pane and the XML Document node in the right pane. Then click Next.

3. Specify a name and location for the document and click Next.

4. Select XML Schema-Constrained Document and click Next.

5. In the Schema URI field, type or browse to the schema location. Once you have selected a schema, the wizard suggests values for the remaining fields in the pane.

6. Specify the namespace for your document in the Document Namespace combo box. The wizard automatically enters the schema's target Namespace in this field.

7. Type or select the document root for your document in the Root Element combo box. The combo box contains all of the schema's exposed elements.

8. Click Finish.

   The IDE creates the new XML document in the specified location.

17.2.4 How to Edit an XML Document

The IDE's Source Editor provides the following features for editing XML documents:

• Syntax coloring. Colored highlighting of code elements.

• Indentation and reformatting. The IDE indents lines as you type. You can format selected lines or the entire file by pressing Alt+Shift+F.

• Code completion. Basic code completion, such as auto-completion of element end tags, is available for all XML documents. If your document is defined by a DTD and the IDE can access the DTD, the Source Editor also offers code completion for all supported elements, attributes, and entities. As you type, a combo box displays all matching elements in the DTD. Press Enter to enter only the element name, or press Shift+Enter to enter a start tag and end tag for the element.

• Navigator window. The Navigator window (Ctrl+7) displays the structure of your XML documents. The Navigator window displays the name, attributes, and text content of each element. You can double-click any element node to jump to its location in the Source Editor.

• Code folding. You can expand and collapse any element in the Source Editor.

To open an XML file in the Source Editor:

• Double-click the XML file's node.

17.2.5 How to Validate an XML Document

If you have an XML document that is constrained by an XML schema or DTD, you can validate the XML document to check its contents for syntax errors.

If your XML document's DTD is located on a remote machine, ensure that the IDE's proxy is correctly configured and you have access to the DTD. For more information see Section 18.5.2, "How to Set a Proxy for Web Services and Clients."

Note:

If the IDE cannot access the DTD, it returns a single error message listing the DOCTYPE declaration. If the IDE cannot access the XML schema, it displays Failed to read schema document.

To validate an XML document:

1. Do one of the following:

   • Right-click the document's node in the Files or Projects window.

   • If the file is open in the Editor, right-click anywhere in the file.

2. Choose Validate XML (or if the file is open in the Editor, press Validate XML)).

   The Output window lists any errors along with the line number where the error was detected.

   Note:

   This location is not necessarily the line where the error occurred. You can double-click any error message to go to the line in the XML file where the error was detected.

Common Error Messages

Some common error messages generated during DTD validation include:

• End of entity not allowed; an end tag is missing. There is no final end tag for the document.

• Expected "</tagname>" to terminate element started on line line#. There is no end tag for the specific element.

• Element type "element name" must be declared. The XML document contains an element type that was not declared in the DTD.

17.2.6 How to Check that an XML Document is Well-formed

XML documents, including DTD, CSS, and XSL files, are considered well-formed if they adhere to a basic set of grammatical rules. The IDE enables you to check an XML document to ensure it conforms to the necessary rules, including the following requirements:

• Every start tag must have a matching end tag. Tags are case-sensitive.

• Start, end and empty-element tags must have proper nesting, without missing or overlapping tags.

• There must be exactly one root element, also known as the document element, that does not appear in the content of any other element.

• Attribute values must be quoted. Attributes are listed in the start tag.

• An element cannot have two or more attributes with the same name.

• Comments and processing instructions cannot appear inside tags.

• No unescaped < or & signs can occur in the element's character data or attribute's character data, except when used as markup.

To check an XML document:

1. Right-click the document's node in the Files window.

2. Choose Check XML, Check DTD, or Check CSS, depending on the document you are checking.

3. The Output window lists any errors along with the line number where the error was detected.

Note:

This location is not necessarily the line where the error occurred. You can double-click any error message to go to the line in the XML file where the error was detected.

17.3 Generating a DTD from an Existing XML File

You can generate a DTD from an existing XML file.

1. In the Files window, right-click an XML file's node and choose Generate DTD.

   Make sure that you have previously checked the XML file to ensure that it is well-formed.

2. Type a name for the new DTD and click OK.

   The new DTD node appears in the Files window and is displayed in the Source Editor.

17.4 Creating an Empty DTD

A document type definition (DTD) describes the grammar that can be used in an XML file and indicates the valid arrangement of the file's tags. It can exist as a prologue to an XML file (internal DTD) or as a separate file (external DTD). This section describes how to create your own empty DTD. You can also generate a DTD from an existing file. See "Generating a DTD from an Existing XML File."

To create an empty DTD:

1. From the main window, choose File > New File.

2. Expand the XML node and select DTD Entity. Click Next to proceed.

3. Type a name and package for the DTD.

4. Click Finish to create the new file.

   In the Files window, the new DTD node appears under the package you specified. The DTD is also displayed in the Source Editor.

17.5 Generating Documentation for a DTD

A document type definition (DTD) describes the grammar that can be used in an XML file and indicates the valid arrangement of the file's tags. It can exist as a prologue to an XML file (internal DTD) or as a separate file (external DTD). You can create a new DTD yourself, or you can automatically generate a DTD from an existing XML document.

17.6 Registering a Local DTD or XML Schema

The DTDs and XML Schemas Manager displays all of the currently registered DTD and XML schemas. To open the DTDs and XML Schemas Manager, choose Tools > DTDs and XML Schemas from the main menu.

To register a local DTD or XML schema:

1. Choose Tools > DTDs and XML Schemas from the main menu.

2. Select the User Catalog node and click Add Local DTD or Schema.

3. Select which ID to map to the local file:

   • Public ID. Generally you use this option to redirect references to a DTD.

   • System ID. Generally you use this option to redirect references to an XML schema.

4. Browse to the location of the local DTD or XML schema in the URI field.

The appropriate User Catalog entry node () appears under the User Catalog node. This entry represents the public ID or system ID mapping to the local DTD or XML schema resource.

17.7 Removing a DTD or XML Schema Entry from the User Catalog

Follow these steps to unregister a DTD or XML Schema.

1. Choose Tools > DTDs and XML Schemas from the main menu.

2. Expand the User Catalog node.

3. Select the XML catalog node you want to remove and click Remove.